```
O HMAC-SHA1 é um algoritmo definido pelo hash de chave [ RFC 2104 para autenticação de mensagem](http://www.ietf.org/rfc/rfc2104.txt). O algoritmo recebe como input duas strings de byte, uma chave e uma mensagem. Para a autenticação de solicitação do Amazon S3, use sua chave de acesso secreta da AWS (`YourSecretAccessKey`) como a chave e a codificação UTF-8 do elemento `StringToSign` como a mensagem. A saída de HMAC-SHA1 também é uma string de byte, chamada de resumo. O parâmetro de solicitação `Signature` é criado pela codificação Base64 desse resumo.
## Canonização de solicitação para assinatura
Lembre-se de que quando o sistema recebe uma solicitação autenticada, ele compara a assinatura de solicitação computada com a assinatura fornecida na solicitação em `StringToSign`. Por esse motivo, é necessário computar a assinatura usando o mesmo método usado pelo Amazon S3. O processo de colocar uma solicitação em um formato acordado para assinatura é chamado de *canonização*.
## Criar o elemento CanonicalizedResource
`CanonicalizedResource` representa o recurso do Amazon S3 visado pela solicitação. Crie-o para uma solicitação REST como se segue:
1. Inicie com uma string vazia (`""`).
1. Se a solicitação especificar um bucket usando o cabeçalho de host HTTP (estilo hosted virtual), adicione o nome do bucket precedido por uma `"/"` (por exemplo, “/bucketname”). Para solicitações de estilo de caminho e solicitações que não seja endereçada a um bucket, não faça nada. Para obter mais informações sobre solicitações de estilo hospedadas virtualmente, consulte [Hospedagem virtual de buckets](https://docs.aws.amazon.com/AmazonS3/latest/userguide/VirtualHosting.html).
Para uma solicitação no estilo de hospedagem virtual "https://awsexamplebucket1.s3.us-west-1.amazonaws.com/photos/puppy.jpg", o `CanonicalizedResource` é "/awsexamplebucket1".
Para uma solicitação em estilo de caminho, "https://s3.us-west-1.amazonaws.com/awsexamplebucket1/photos/puppy.jpg", o `CanonicalizedResource` é "".
1. Adicione a parte do caminho de um URI de solicitação HTTP descodificado, até a query string, mas sem incluí-la.
Para uma solicitação no estilo de hospedagem virtual "https://awsexamplebucket1.s3.us-west-1.amazonaws.com/photos/puppy.jpg", o `CanonicalizedResource` e "/awsexamplebucket1/photos/puppy.jpg".
Para uma solicitação no estilo de hospedagem virtual "https://s3.us-west-1.amazonaws.com/awsexamplebucket1/photos/puppy.jpg", o `CanonicalizedResource` é "/awsexamplebucket1/photos/puppy.jpg". Neste ponto, o `CanonicalizedResource` é o mesmo para a solicitação em estilo hosted virtual e em estilo de caminho.
Para uma solicitação que não seja endereçada a um bucket, como [GET Service](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTServiceGET.html), adicione “/”.
1. Se a solicitação endereça um sub-recurso, como `?versioning`, `?location`, `?acl`, `?lifecycle` ou `?versionid`, adicione o sub-recurso, seu valor, se houver um, e o ponto de interrogação. Observe que, em caso de vários sub-recursos, os sub-recursos devem ser classificados em ordem lexicográfica por nome de sub-recurso e ser separados por '&', por exemplo, ?acl&versionId={{value}}.
Os sub-recursos que devem ser incluídos ao criar o elemento CanonicalizedResource são acl, lifecycle, location, logging, notification, partNumber, policy, requestPayment, uploadId, uploads, versionId, versioning, versions e website.
Se a solicitação especificar os parâmetros de query string que cancelam os valores de cabeçalho da resposta (consulte [Objeto GET](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectGET.html)), adicione os parâmetros de query string e seus valores. Ao assinar, você não codifica esses valores; contudo, ao fazer a solicitação, você deve codificar esses valores de parâmetros. Os parâmetros de query string em uma solicitação GET incluem `response-content-type`, `response-content-language`, `response-expires`, `response-cache-control`, `response-content-disposition` e `response-content-encoding`.
O parâmetro de query string `delete` deve ser incluído ao criar o CanonicalizedResource para uma solicitação de exclusão de vários objetos.
Os elementos do CanonicalizedResource que vêm da URI da solicitação HTTP devem ser assinados literalmente como aparecem na solicitação HTTP, incluindo metacaracteres de codificação de URL.
O `CanonicalizedResource` pode ser diferente da URI da solicitação HTTP. Em particular, se sua solicitação usa o cabeçalho HTTP `Host` para especificar um bucket, o bucket não aparece na URI da solicitação HTTP. Contudo, o `CanonicalizedResource` continua a incluir o bucket. Os parâmetros de query string podem também aparecer na URI da solicitação, mas não estão incluídos em `CanonicalizedResource`. Para obter mais informações, consulte [Hospedagem virtual de buckets](https://docs.aws.amazon.com/AmazonS3/latest/userguide/VirtualHosting.html).
## Criar o elemento CanonicalizedAmzHeaders
Para criar a parte de CanonicalizedAmzHeaders de `StringToSign`, selecione todos os cabeçalhos de solicitações HTTP que comecem com 'x-amz-' (usando uma comparação que não diferencie maiúsculas e minúsculas) e use o processo a seguir.
1. Converta cada nome de cabeçalho HTTP para minúsculas. Por exemplo, '`X-Amz-Date`' torna-se '`x-amz-date`'.
1. Classifique a coleção de cabeçalhos por ordem lexicográfica por nome de cabeçalho.
1. Combine campos do cabeçalho com o mesmo nome em um par “header-name:comma-separated-value-list” conforme descrito em RFC 2616, seção 4.2, sem qualquer espaço entre os valores. Por exemplo, os dois cabeçalhos de metadados '`x-amz-meta-username: fred`' e '`x-amz-meta-username: barney`' seriam combinados em único cabeçalho '`x-amz-meta-username: fred,barney`'.
1. “Desdobre” os cabeçalhos longos que abrangem várias linhas (como permitido em RFC 2616, seção 4.2) substituindo o espaço de dobramento (incluindo a nova linha) por um único espaço.
1. Remova todos os espaços ao redor dos dois pontos no cabeçalho. Por exemplo, o cabeçalho '`x-amz-meta-username: fred,barney`' se tornaria '`x-amz-meta-username:fred,barney`'.
1. Finalmente, adicione um caractere de nova linha (`U+000A`) para cada cabeçalho canonizado na lista resultante. Crie o elemento CanonicalizedResource concatenando todos os cabeçalhos dessa lista em uma única string.
## Elementos StringToSign de cabeçalho HTTP posicionais versus nomeados
Os primeiros elementos de cabeçalho do `StringToSign` (Content-Type, Date e Content-MD5) são de natureza posicional. `StringToSign` não inclui os nomes desses cabeçalhos, somente seus valores da solicitação. Em contraste, os elementos '`x-amz-`' são nomeados. Os nomes de cabeçalho e os valores de cabeçalho aparecem em `StringToSign`.
Se um cabeçalho posicional chamado para a definição de `StringToSign` não estiver presente na sua solicitação (por exemplo, `Content-Type` ou `Content-MD5` são opcionais para solicitações PUT e sem sentido para solicitações GET), substitua a string vazia ("") para essa posição.
## Requisito de time stamp
Um time stamp válido (usando o cabeçalho HTTP `Date` ou uma alternativa `x-amz-date`) é obrigatório para solicitações autenticadas. Além disso, o time stamp do cliente, incluído com uma solicitação autenticada, não deve exceder 15 minutos do tempo do sistema do Amazon S3 quando a solicitação é recebida. Caso contrário, haverá falha na solicitação com o código de erro `RequestTimeTooSkewed`. A intenção dessas restrições é limitar a possibilidade de que solicitações interceptadas possam ser reenviadas por um adversário. Para uma proteção mais forte contra espionagem, use o transporte HTTPS para solicitações autenticadas.
**nota**
A restrição de validação na data da solicitação se aplica somente a solicitações autenticadas que não usem a autenticação por query string. Para obter mais informações, consulte [Alternativa de autenticação de solicitação por string de consulta](#RESTAuthenticationQueryStringAuth).
Algumas bibliotecas de clientes HTTP não expõem a capacidade para configurar o cabeçalho `Date` para uma solicitação. Se tiver problemas para incluir o valor do cabeçalho "Data" nos cabeçalhos canonizados, você pode configurar o time stamp para a solicitação usando um cabeçalho '`x-amz-date`'. O valor do cabeçalho `x-amz-date` deve estar em um dos formatos RFC 2616 ([http://www.ietf.org/rfc/rfc2616.txt](http://www.ietf.org/rfc/rfc2616.txt)). Quando um cabeçalho `x-amz-date` está presente em uma solicitação, o sistema ignorará qualquer cabeçalho `Date` ao calcular a assinatura da solicitação. Portanto, se você incluir o cabeçalho `x-amz-date`, use a string vazia para o `Date` quando criar o `StringToSign`. Consulte a próxima seção para ver um exemplo.
## Exemplos de autenticação
Os exemplos nesta seção usam as credenciais (não trabalho) na tabela a seguir.
| Parâmetro | Valor |
| --- | --- |
| AWSAccessKeyId | AKIAIOSFODNN7EXAMPLE |
| AWSSecretAccessKey | wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY |
No exemplo `StringToSign`s, o formato não é significativo e `\n` significa o ponto de código Unicode `U+000A`, chamado geralmente de nova linha. Além disso, os exemplos usam "\+0000" para designar o fuso horário. Você pode usar "GMT" para designar o fuso horário, mas as assinaturas mostradas nos exemplos serão diferentes.
### Objeto GET
Este exemplo obtém um objeto do bucket awsexamplebucket1.
| Solicitação | StringToSign |
| --- | --- |
| GET /photos/puppy.jpg HTTP/1.1
Host: awsexamplebucket1.us-west-1.s3.amazonaws.com
Date: Tue, 27 Mar 2007 19:36:42 +0000
{{Authorization: AWS AKIAIOSFODNN7EXAMPLE:
qgk2+6Sv9/oM7G3qLEjTH1a1l1g=}}
| GET\n
\n
\n
Tue, 27 Mar 2007 19:36:42 +0000\n
/awsexamplebucket1/photos/puppy.jpg
|
Observe que o CanonicalizedResource inclui o nome do bucket, mas a URI da solicitação HTTP não o inclui. (O bucket é especificado pelo cabeçalho de host.)
**nota**
O script Python a seguir calcula a assinatura precedente, usando os parâmetros fornecidos. É possível usar esse script para criar suas próprias assinaturas, substituindo as chaves e StringToSign conforme apropriado.
```
1. import base64
2. import hmac
3. from hashlib import sha1
4.
5. access_key = '{{AKIAIOSFODNN7EXAMPLE}}'.encode("UTF-8")
6. secret_key = '{{wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY}}'.encode("UTF-8")
7.
8. string_to_sign = '{{GET\n\n\nTue, 27 Mar 2007 19:36:42 +0000\n/awsexamplebucket1/photos/puppy.jpg}}'.encode("UTF-8")
9. signature = base64.b64encode(
10. hmac.new(
11. secret_key, string_to_sign, sha1
12. ).digest()
13. ).strip()
14.
15.
16. print(f"AWS {access_key.decode()}:{signature.decode()}")
```
### PUT objeto
Este exemplo coloca um objeto no bucket awsexamplebucket1 bucket.
| Solicitação | StringToSign |
| --- | --- |
| PUT /photos/puppy.jpg HTTP/1.1
Content-Type: image/jpeg
Content-Length: 94328
Host: awsexamplebucket1.s3.us-west-1.amazonaws.com
Date: Tue, 27 Mar 2007 21:15:45 +0000
{{Authorization: AWS AKIAIOSFODNN7EXAMPLE:
iqRzw+ileNPu1fhspnRs8nOjjIA=
}}
| PUT\n
\n
image/jpeg\n
Tue, 27 Mar 2007 21:15:45 +0000\n
/awsexamplebucket1/photos/puppy.jpg
|
Observe o cabeçalho Content-Type na solicitação e em StringToSign. Também observe que o Content-MD5 está em branco em StringToSign porque não está presente na solicitação.
### Lista
Este exemplo lista o conteúdo do bucket awsexamplebucket1.
| Solicitação | StringToSign |
| --- | --- |
| GET /?prefix=photos&max-keys=50&marker=puppy HTTP/1.1
User-Agent: Mozilla/5.0
Host: awsexamplebucket1.s3.us-west-1.amazonaws.com
Date: Tue, 27 Mar 2007 19:42:41 +0000
{{Authorization: AWS AKIAIOSFODNN7EXAMPLE:
m0WP8eCtspQl5Ahe6L1SozdX9YA=}}
| GET\n
\n
\n
Tue, 27 Mar 2007 19:42:41 +0000\n
/awsexamplebucket1/
|
Observe a barra final no CanonicalizedResource e a ausência de parâmetros de query string.
### Fetch
Este exemplo busca o sub-recurso de política de controle de acesso para o bucket “awsexamplebucket1” bucket.
| Solicitação | StringToSign |
| --- | --- |
| GET /?acl HTTP/1.1
Host: awsexamplebucket1.s3.us-west-1.amazonaws.com
Date: Tue, 27 Mar 2007 19:44:46 +0000
{{Authorization: AWS AKIAIOSFODNN7EXAMPLE:
82ZHiFIjc+WbcwFKGUVEQspPn+0=}}
| GET\n
\n
\n
Tue, 27 Mar 2007 19:44:46 +0000\n
/awsexamplebucket1/?acl
|
Observe como o parâmetro de query string do sub-recurso está incluído no CanonicalizedResource.
### Excluir
Este exemplo exclui um objeto do bucket “awsexamplebucket1” usando o estilo de caminho e a alternativa de data.
| Solicitação | StringToSign |
| --- | --- |
| DELETE /awsexamplebucket1/photos/puppy.jpg HTTP/1.1
User-Agent: dotnet
Host: s3.us-west-1.amazonaws.com
Date: Tue, 27 Mar 2007 21:20:27 +0000
x-amz-date: Tue, 27 Mar 2007 21:20:26 +0000
{{Authorization: AWS AKIAIOSFODNN7EXAMPLE:XbyTlbQdu9Xw5o8P4iMwPktxQd8=}}
| DELETE\n
\n
\n
Tue, 27 Mar 2007 21:20:26 +0000\n
/awsexamplebucket1/photos/puppy.jpg
|
Observe o método alternativo “x-amz-date” de especificação da data (pois nossa biblioteca de cliente, por exemplo, pode ter impedido a definição da data). Nesse caso, o `x-amz-date` tem precedência sobre o cabeçalho `Date`. Portanto, entrada de data na assinatura deve conter o valor de cabeçalho `x-amz-date`.
### Carregar
Este exemplo faz upload de um objeto para um bucket de estilo hosted virtual CNAME com metadados.
| Solicitação | StringToSign |
| --- | --- |
| PUT /db-backup.dat.gz HTTP/1.1
User-Agent: curl/7.15.5
Host: static.example.com:8080
Date: Tue, 27 Mar 2007 21:06:08 +0000
x-amz-acl: public-read
content-type: application/x-download
Content-MD5: 4gJE4saaMU4BqNR0kLY+lw==
X-Amz-Meta-ReviewedBy: joe@example.com
X-Amz-Meta-ReviewedBy: jane@example.com
X-Amz-Meta-FileChecksum: 0x02661779
X-Amz-Meta-ChecksumAlgorithm: crc32
Content-Disposition: attachment; filename=database.dat
Content-Encoding: gzip
Content-Length: 5913339
{{Authorization: AWS AKIAIOSFODNN7EXAMPLE:
jtBQa0Aq+DkULFI8qrpwIjGEx0E=}}
| PUT\n
4gJE4saaMU4BqNR0kLY+lw==\n
application/x-download\n
Tue, 27 Mar 2007 21:06:08 +0000\n
x-amz-acl:public-read\n
x-amz-meta-checksumalgorithm:crc32\n
x-amz-meta-filechecksum:0x02661779\n
x-amz-meta-reviewedby:
joe@example.com,jane@example.com\n
/static.example.com/db-backup.dat.gz
|
Observe como os cabeçalhos 'x-amz-' são classificados, os espaços são removidos e os cabeçalhos são convertidos em minúsculas. Observe também que vários cabeçalhos com o mesmo nome foram unidos usando vírgulas para separar valores.
Observe como somente os cabeçalhos de entidade HTTP `Content-Type` e `Content-MD5` aparecem em `StringToSign`. Os outros cabeçalhos de entidade `Content-*` não aparecem.
Mais uma vez, observe que o `CanonicalizedResource` inclui o nome do bucket, mas a URI da solicitação HTTP não o inclui. (O bucket é especificado pelo cabeçalho de host.)
### Listar todos os meus buckets
| Solicitação | StringToSign |
| --- | --- |
| GET / HTTP/1.1
Host: s3.us-west-1.amazonaws.com
Date: Wed, 28 Mar 2007 01:29:59 +0000
{{Authorization: AWS AKIAIOSFODNN7EXAMPLE:qGdzdERIC03wnaRNKh6OqZehG9s=}}
| GET\n
\n
\n
Wed, 28 Mar 2007 01:29:59 +0000\n
/
|
### Chaves Unicode
| Solicitação | StringToSign |
| --- | --- |
| GET /dictionary/fran%C3%A7ais/pr%c3%a9f%c3%a8re HTTP/1.1
Host: s3.us-west-1.amazonaws.com
Date: Wed, 28 Mar 2007 01:49:49 +0000
{{Authorization: AWS AKIAIOSFODNN7EXAMPLE:DNEZGsoieTZ92F3bUfSPQcbGmlM=}}
| GET\n
\n
\n
Wed, 28 Mar 2007 01:49:49 +0000\n
/dictionary/fran%C3%A7ais/pr%c3%a9f%c3%a8re
|
**nota**
Os elementos em `StringToSign` que foram derivados da URI de solicitação são obtidos literalmente, incluindo a codificação do URL e a capitalização.
## Problemas de assinatura de solicitação REST
Quando a autenticação de solicitação REST falha, o sistema responde à solicitação com um documento de erro em XML. As informações contidas neste documento de erro têm o objetivo de ajudar os desenvolvedores a diagnosticar o problema. Especificamente, o elemento `StringToSign` do documento de erro `SignatureDoesNotMatch` diz exatamente que canonização de solicitação o sistema está usando.
Alguns toolkits inserem silenciosamente os cabeçalhos que você não conhece antecipadamente, como a adição do cabeçalho `Content-Type` durante um PUT. Na maioria desses casos, o valor do cabeçalho inserido permanece constante, permitindo que você descubra os cabeçalhos que faltam, usando ferramentas como Ethereal ou o tcpmon.
## Alternativa de autenticação de solicitação por string de consulta
Você pode autenticar determinados tipos de solicitações passando as informações necessárias como parâmetros de query string em vez de usar o cabeçalho HTTP `Authorization`. Isso é útil para habilitar o acesso de navegadores de terceiros a seus dados privados do Amazon S3 sem um proxy na solicitação. A ideia é criar uma solicitação "pré-assinada" e codificá-la como um URL que o navegador de um usuário final pode recuperar. Além disso, você pode limitar uma solicitação pré-assinada, especificando um tempo de expiração.
Consulte mais informações sobre como usar parâmetros de consulta para autenticação de solicitações em [Autenticação de solicitações: uso de parâmetros de consulta (AWS Signature Version 4)](https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-query-string-auth.html) na *Referência de API do Amazon Simple Storage Service*. Para obter exemplos de uso de SDKs da AWS para gerar URLs pré-assinados, consulte [Compartilhamento de objetos com URLs pré-assinados](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ShareObjectPreSignedURL.html).
### Criar uma assinatura
Veja a seguir um exemplo de solicitação REST do Amazon S3 autenticada por query string.
```
1. GET /photos/puppy.jpg
2. ?AWSAccessKeyId=AKIAIOSFODNN7EXAMPLE&Expires=1141889120&Signature=vjbyPxybdZaNmGa%2ByT272YEAiv4%3D HTTP/1.1
3. Host: awsexamplebucket1.s3.us-west-1.amazonaws.com
4. Date: Mon, 26 Mar 2007 19:37:58 +0000
```
O método de autenticação por query string não requer nenhum cabeçalho especial HTTP. Em vez disso, os elementos de autenticação exigidos são especificados como parâmetros de query string:
| Nome de parâmetro de string de consulta | Valor de exemplo | Descrição |
| --- | --- | --- |
| AWSAccessKeyId | AKIAIOSFODNN7EXAMPLE | Seu ID de chave de acesso da AWS. Especifica a chave de acesso secreta da AWS usada para assinar a solicitação e, indiretamente, a identidade do desenvolvedor que fez a solicitação. |
| Expires | 1141889120 | O tempo quando a assinatura vai expirar, especificado como o número de segundos desde o epoch (00:00:00 UTC em 1º de janeiro de 1970). Uma requisição recebida depois desse tempo (de acordo com o servidor) será rejeitada. |
| Signature | vjbyPxybdZaNmGa%2ByT272YEAiv4%3D | A codificação do URL da codificação Base64 do HMAC-SHA1 de StringToSign. |
O método de autenticação de solicitação por query string difere ligeiramente do método comum, mas somente no formato do parâmetro da solicitação `Signature` e no elemento `StringToSign`. A seguir está a pseudogramática que ilustra o método de autenticação de solicitação por query string.
```
1. Signature = URL-Encode( Base64( HMAC-SHA1( YourSecretAccessKey, UTF-8-Encoding-Of( StringToSign ) ) ) );
2.
3. StringToSign = HTTP-VERB + "\n" +
4. Content-MD5 + "\n" +
5. Content-Type + "\n" +
6. Expires + "\n" +
7. CanonicalizedAmzHeaders +
8. CanonicalizedResource;
```
`YourSecretAccessKey` é o ID da chave de acesso secreta da AWS que a Amazon atribui a você ao se cadastrar para ser um desenvolvedor da Amazon Web Services. Observe como o `Signature` é codificado por URL para ser apropriado para a colocação na query string. Observe também que no `StringToSign`, o elemento posicional HTTP `Date` foi substituído por `Expires`. O `CanonicalizedAmzHeaders` e o `CanonicalizedResource` são os mesmos.
**nota**
No método de autenticação por query string, você não utiliza o cabeçalho `Date` nem o `x-amz-date request` para calcular o string para assinar.
#### Autenticação de solicitação por string de consulta
| Solicitação | StringToSign |
| --- | --- |
| GET /photos/puppy.jpg?AWSAccessKeyId=AKIAIOSFODNN7EXAMPLE&
Signature=NpgCjnDzrM%2BWFzoENXmpNDUsSn8%3D&
Expires=1175139620 HTTP/1.1
Host: awsexamplebucket1.s3.us-west-1.amazonaws.com
| GET\n
\n
\n
1175139620\n
/awsexamplebucket1/photos/puppy.jpg
|
Este exemplo pressupõe que, quando um navegador fizer a solicitação GET, ele não fornecerá um cabeçalho Content-MD5 nem um cabeçalho Content-Type, nem definirá nenhum cabeçalho x-amz-, portanto, essas partes de `StringToSign` ficam em branco.
#### Usar codificação Base64
As assinaturas de solicitação HMAC devem ser codificadas em Base64. A codificação Base64 converte a assinatura em uma string simples ASCII que pode ser anexada à solicitação. Os caracteres que poderiam aparecer na string da assinatura como mais (\+), barra (/) e igual (=) devem ser codificados se forem usados em uma URI. Por exemplo, se o código de autenticação inclui um sinal de mais (\+), codifique-o como %2B na solicitação. Codifique uma barra como %2F e o sinal de igual como %3D.
Para obter exemplos de codificação Base64, consulte do Amazon 3 [Exemplos de autenticação](#RESTAuthenticationExamples).