# AWS Signature Version 4 para solicitações de API **Importante** Caso use um SDK da AWS (consulte [Sample Code and Libraries](https://aws.amazon.com/developer/)) ou a ferramenta da AWS Command Line Interface (AWS CLI) para enviar solicitações de API para a AWS, você pode pular o processo de assinatura, pois os clientes de SDK e CLI autenticarão suas solicitações usando as chaves de acesso fornecidas por você. A menos que haja um bom motivo para não usar, é recomendável usar sempre um SDK ou a CLI. Em regiões que oferecem suporte a várias versões de assinatura, assinar manualmente as solicitações significa que é necessário especificar qual versão de assinatura está sendo usada. Quando você fornece solicitações para pontos de acesso multirregionais, os SDKs e a CLI automaticamente alternam para o uso do Signature Version 4A, sem configuração adicional. As informações de autenticação enviadas em uma solicitação devem incluir uma assinatura. O AWS Signature Version 4 (SigV4) é o protocolo de assinatura da AWS para adicionar informações de autenticação às solicitações de API da AWS. Você não usa sua chave de acesso secreta para assinar solicitações da API. Em vez disso, você usa o processo de assinatura da SigV4. A assinatura de solicitações envolve: 1. A criação de uma solicitação canônica com base nos detalhes da solicitação. 1. O cálculo uma assinatura usando suas credenciais da AWS. 1. Adicionar essa assinatura à solicitação como um cabeçalho de autorização. A AWS, em seguida, replica esse processo e verifica a assinatura, concedendo ou negando o acesso adequadamente. A Symmetric SigV4 exige que você derive uma chave que tenha como escopo um único serviço da AWS, em uma única região da AWS, em um determinado dia. Isso torna a chave e a assinatura calculada diferentes para cada região, o que significa que você precisa saber a região à qual a assinatura se destina. A Assymmetric Signature Versão 4 (SigV4a) é uma extensão compatível com assinatura por um novo algoritmo e geração de assinaturas individuais que podem ser verificadas em mais de uma região da AWS. Com a SIGv4a, você pode assinar uma solicitação para várias regiões com roteamento e failover sem problemas entre regiões. Quando você usa o AWS SDK ou a AWS CLI para invocar uma funcionalidade que exige assinatura multirregional, o tipo de assinatura é alterado automaticamente para usar a Sigv4a. Para obter detalhes, consulte [Como a AWS SigV4 funciona](#how-sigv4a-works). ## Como o SigV4 da AWS funciona As seguintes etapas descrevem o processo geral de computação de uma assinatura com a SigV4: 1. A **string para assinar** depende do tipo de solicitação. Por exemplo, ao usar o cabeçalho HTTP Authorization ou os parâmetros de consulta para autenticação, utilize uma combinação de elementos de solicitação para criar a string a ser assinada. Para uma solicitação HTTP POST, a política `POST` na solicitação é a string que você assina. 1. A **chave de assinatura** é uma série de cálculos, com o resultado de cada etapa inserido na próxima. A etapa final é a chave de assinatura. 1. Ao receber uma solicitação autenticada, o serviço da AWS recria a **assinatura** usando as informações de autenticação contidas na solicitação. Se as assinaturas corresponderem, o serviço processará a solicitação. Caso contrário, rejeitará a solicitação. Para ter mais informações, consulte [Elementos de uma assinatura de solicitação de API da AWS](reference_sigv-signing-elements.md). ## Como a AWS SigV4 funciona A Sigv4a usa assinaturas assimétricas baseadas em criptografia com chave pública-privada. A SigV4a passa por um processo de derivação de credenciais cujo escopo é semelhante ao da SigV4, exceto que a SigV4a usa a mesma chave para assinar todas as solicitações sem precisar derivar uma chave de assinatura distinta de acordo com a data, o serviço e a região. Um par de chaves de [Algoritmo de Assinatura Digital de Curva Elíptica](https://csrc.nist.gov/glossary/term/ecdsa) (ECDSA) pode ser derivado da chave de acesso secreta da AWS já existente. O sistema usa criptografia assimétrica para verificar assinaturas multirregionais, de modo que a AWS só precise armazenar suas chaves públicas. As chaves públicas não são secretas e não podem ser usadas para assinar solicitações. Assinaturas assimétricas são necessárias para solicitações de API multirregionais, por exemplo, com os pontos de acesso multirregionais do Amazon S3. As seguintes etapas descrevem o processo geral de computação de uma assinatura com a SigV4a: 1. A **string para assinar** depende do tipo de solicitação. Por exemplo, ao usar o cabeçalho HTTP Authorization ou os parâmetros de consulta para autenticação, utilize uma combinação de elementos de solicitação para criar a string a ser assinada. Para uma solicitação HTTP POST, a política `POST` na solicitação é a string que você assina. 1. A **chave de assinatura** é derivada de uma chave de acesso secreta da AWS por uma série de cálculos, sendo que o resultado de cada etapa é inserido na próxima etapa. A etapa final produz o par de chaves. 1. Quando um serviço da AWS recebe uma solicitação assinada com a SigV4a, a AWS verifica a assinatura usando somente a metade pública do par de chaves. Se a assinatura for válida, a solicitação será autenticada e o serviço processará a solicitação. Solicitações com assinaturas inválidas são rejeitadas. Para obter mais informações sobre a SigV4a para solicitações de API multirregionais, consulte o projeto [sigv4a-signing-examples](https://github.com/aws-samples/sigv4a-signing-examples) no GitHub. ## Quando assinar solicitações Ao escrever um código personalizado que envia solicitações de API para a AWS, é necessário incluir um código que assine as solicitações. Você poderá escrever um código personalizado porque: + Você está trabalhando com uma linguagem de programação para a qual não há nenhum SDK da AWS. + Você precisa ter controle total sobre como as solicitações são enviadas à AWS. Enquanto as solicitações de API autenticam o acesso com o SigV4 da AWS, os SDKs da AWS e a AWS CLI autenticam suas solicitações usando as chaves de acesso que você fornece. Para obter mais informações sobre a autenticação com SDKs da AWS e a AWS CLI, consulte [Recursos adicionais](#reference_aws-signing-resources). ## Por que as solicitações são assinadas O processo de assinatura ajuda a proteger as solicitações das seguintes formas: + **Verificar a identidade do solicitante** As solicitações autenticadas exigem uma assinatura que você cria usando as chaves de acesso (ID da chave de acesso, chave de acesso secreta). Se você usar credenciais de segurança temporárias, os cálculos da assinatura também exigirão um token de segurança. Para obter mais informações, consulte [Credenciais de segurança da AWS, Acesso programático](security-creds-programmatic-access.md). + **Proteger dados em trânsito** Para evitar violação de uma solicitação enquanto ela estiver em trânsito, alguns dos elementos de solicitação são usados para calcular um hash (resumo) da solicitação, e o valor de hash resultante é incluído como parte da solicitação. Ao receber a solicitação, um AWS service (Serviço da AWS) usa as mesmas informações para calcular um hash e o compara com o valor de hash na solicitação. Se os valores não coincidirem, a AWS nega a solicitação. + **Proteger contra ataques potenciais de replay** Na maioria dos casos, uma solicitação deve chegar à AWS no lapso de cinco minutos a partir da marca de tempo na solicitação. Caso contrário, a AWS negará a solicitação. O SigV4 da AWS pode ser expresso no cabeçalho HTTP Authorization ou como uma string de consulta no URL. Para ter mais informações, consulte [Métodos de autenticação](reference_sigv-authentication-methods.md). ## Recursos adicionais + Para obter mais informações sobre o processo de assinatura do SigV4 para diferentes serviços, consulte [Exemplos de assinatura de solicitação](reference_sigv-examples.md). + Para configurar credenciais para acesso programático à AWS CLI, consulte [Authentication and access credentials](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-authentication.html) no *AWS Command Line Interface User Guide*. + Os AWS SDKs incluem código-fonte no GitHub para assinar solicitações de API da AWS. Para obter exemplos de código, consulte [Projetos de exemplo em repositório de amostras da AWS](reference_sigv-examples.md#signature-v4-examples-sdk). + AWS SDK para .NET: [AWS4Signer.cs](https://github.com/aws/aws-sdk-net/blob/master/sdk/src/Core/Amazon.Runtime/Internal/Auth/AWS4Signer.cs) + AWS SDK para C\$1\$1: [AWSAuthV4Signer.cpp](https://github.com/aws/aws-sdk-cpp/blob/main/src/aws-cpp-sdk-core/source/auth/signer/AWSAuthV4Signer.cpp) + AWS SDK para Go: [sigv4.go](https://github.com/aws/smithy-go/blob/a4c9efcda6aa54c75d1a130d1320a2709eebf51d/aws-http-auth/sigv4/sigv4.go) + AWS SDK para Java: [BaseAws4Signer.java](https://github.com/aws/aws-sdk-java-v2/blob/master/core/auth/src/main/java/software/amazon/awssdk/auth/signer/internal/BaseAws4Signer.java) + AWS SDK para JavaScript: [signature-v4](https://github.com/smithy-lang/smithy-typescript/tree/main/packages/signature-v4) + AWS SDK para PHP: [SignatureV4.php](https://github.com/aws/aws-sdk-php/blob/master/src/Signature/SignatureV4.php) + AWS SDK para Python (Boto): [signers.py](https://github.com/boto/botocore/blob/develop/botocore/signers.py) + AWS SDK para Ruby: [signer.rb](https://github.com/aws/aws-sdk-ruby/blob/version-3/gems/aws-sigv4/lib/aws-sigv4/signer.rb) # Elementos de uma assinatura de solicitação de API da AWS **Importante** A menos que você esteja usando AWS SDKs ou a CLI, é necessário escrever código para calcular assinaturas que forneçam informações de autenticação em suas solicitações. O cálculo da assinatura no AWS Signature Versão 4 pode ser uma tarefa complexa, então é recomendável usar os AWS SDKs ou a CLI sempre que possível. Cada solicitação HTTP/HTTPS que usa a assinatura do Signature Version 4 deve conter esses elementos. **Topics** + [ ## Especificação de endpoint ](#endpoint-specification) + [ ## Ação ](#action) + [ ## Parâmetros de ação ](#parameters) + [ ## Data ](#date) + [ ## Informações de autenticação ](#authentication) ## Especificação de endpoint Especifica o nome DNS do endpoint ao qual você envia a solicitação. Esse nome geralmente contém o código do serviço e a região. Por exemplo, o nome do endpoint para o Amazon DynamoDB na região `us-east-1` é `dynamodb.us-east-1.amazonaws.com`. Para solicitações de HTTP/1.1, é necessário incluir o cabeçalho `Host`. Para solicitações HTTP/2, você pode incluir o cabeçalho `:authority` ou o cabeçalho `Host`. Use apenas o cabeçalho `:authority` em conformidade com a especificação HTTP/2. Nem todos os serviços oferecem suporte a solicitações HTTP/2. Para obter os endpoints compatíveis com cada serviço, consulte [Endpoints e cotas de serviço](https://docs.aws.amazon.com/general/latest/gr/aws-service-information.html) na *Referência geral da AWS*. ## Ação Especifica uma ação de API para o serviço. Por exemplo, a ação `CreateTable` do DynamoDB ou a ação `DescribeInstances` do Amazon EC2. Para ver as ações compatíveis com cada serviço, consulte a [Referência de autorização do serviço](https://docs.aws.amazon.com//service-authorization/latest/reference/reference.html). ## Parâmetros de ação Especifica os parâmetros da ação especificada na solicitação. Cada ação de API da AWS tem um conjunto de parâmetros obrigatórios e opcionais. A versão da API geralmente é um parâmetro obrigatório. Para ver os parâmetros compatíveis com uma ação de API, consulte a Referência de API do serviço. ## Data Especifica a data e a hora da solicitação. Incluir a data e a hora na solicitação ajuda a evitar que terceiros interceptem sua solicitação e a enviem novamente mais tarde. A data especificada no escopo de credenciais deve corresponder à data da solicitação. O carimbo de data e hora deve estar em UTC e usar o seguinte formato: ISO 8601 *AAAAMMDD*T*HHMMSS*Z. Por exemplo, `20220830T123600Z`. Não inclua milissegundos na marca de tempo. Você pode usar um cabeçalho `date` ou `x-amz-date` ou incluir `x-amz-date` como um parâmetro de consulta. Se não conseguirmos encontrar um cabeçalho `x-amz-date`, procuraremos um cabeçalho `date`. ## Informações de autenticação Cada solicitação enviada deve incluir as informações a seguir. A AWS usa essas informações para garantir a validade e a autenticidade da solicitação. + Algoritmo: o algoritmo que você está usando como parte do processo de assinatura. + SigV4: use `AWS4-HMAC-SHA256` para especificar o Signature Version 4 com o algoritmo de hash `HMAC-SHA256`. + SigV4a: use `AWS4-ECDSA-P256-SHA256` para especificar o algoritmo de hash `ECDSA-P256-SHA-256`. + Credencial: uma string que é formada concatenando o ID da chave de acesso e os componentes do escopo de credencial. + SigV4: o escopo da credencial inclui o ID da chave de acesso, a data no formato *AAAAMMDD*, o código da região, o código do serviço e a string `aws4_request` de término separados por barras (/). O código da região, o código do serviço e a string de término devem usar caracteres minúsculos. ``` AKIAIOSFODNN7EXAMPLE/YYYYMMDD/region/service/aws4_request ``` + SigV4a: o escopo da credencial inclui a data no formato AAAAMMDD, o nome do serviço e a string `aws4_request` de término separados por barras (/). Observe que o escopo da credencial não inclui a região, pois ela é englobada em um cabeçalho `X-Amz-Region-Set` separado. ``` AKIAIOSFODNN7EXAMPLE/YYYYMMDD/service/aws4_request ``` + Cabeçalhos assinados: os cabeçalhos HTTP a serem incluídos na assinatura, separados por ponto e vírgula (;). Por exemplo, `host;x-amz-date`. Para SigV4a, você deve incluir um cabeçalho de conjunto de regiões que especifique o conjunto de regiões em que a solicitação será válida. O cabeçalho `X-Amz-Region-Set` é especificado como uma lista de valores separados por vírgula. O exemplo a seguir mostra um cabeçalho de região que permite fazer uma solicitação nas regiões us-east-1 e us-west-1. ``` X-Amz-Region-Set=us-east-1,us-west-1 ``` Você pode usar curingas (\$1) em regiões para especificar várias regiões. No exemplo a seguir, o cabeçalho permite que uma solicitação seja feita tanto na região us-west-1 quanto na us-west-2. ``` X-Amz-Region-Set=us-west-* ``` + Assinatura: uma string codificada em hexadecimal que representa a assinatura calculada. Você deve calcular a assinatura com o algoritmo especificado no parâmetro `Algorithm`. Para obter mais informações, consulte [Métodos de autenticação](reference_sigv-authentication-methods.md) # Métodos de autenticação **Importante** A menos que você esteja usando AWS SDKs ou a CLI, é necessário escrever código para calcular assinaturas que forneçam informações de autenticação em suas solicitações. O cálculo da assinatura no AWS Signature Versão 4 pode ser uma tarefa complexa, então é recomendável usar os AWS SDKs ou a CLI sempre que possível. É possível expressar informações de autenticação usando um dos métodos a seguir. ## Cabeçalho HTTP de autorização O cabeçalho HTTP `Authorization` é o método mais usado para autenticar uma solicitação. Todas as operações da API REST (exceto para carregamentos baseados em navegador que usam solicitações `POST`) requerem esse cabeçalho. Os exemplos a seguir mostram o valor do cabeçalho `Authorization` para SigV4 e SigV4a. As quebras de linha foram adicionadas a este exemplo somente para facilitar a leitura. Em seu código, o cabeçalho deve ser uma string contínua. Não use vírgula entre o algoritmo e a credencial, mas os outros elementos devem ser separados por vírgulas. **Example SigV4** ``` Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20130524/us-east-1/s3/aws4_request, SignedHeaders=host;range;x-amz-date, Signature=fe5f80f77d5fa3beca038a248ff027d0445342fe2855ddc963176630326f1024 ``` **Example Sigv4a** ``` Authorization: AWS4-ECDSA-P256-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20130524/s3/aws4_request, SignedHeaders=host;range;x-amz-date;x-amz-region-set, Signature=fe5f80f77d5fa3beca038a248ff027d0445342fe2855ddc963176630326f1024 ``` A tabela a seguir descreve os vários componentes do valor do cabeçalho de autorização do exemplo anterior: | Componente | Descrição | | --- | --- | | Autorização | O algoritmo que foi usado para calcular a assinatura. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/IAM/latest/UserGuide/reference_sigv-authentication-methods.html) | | Credential | Seu ID de chave de acesso e as informações do escopo. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/IAM/latest/UserGuide/reference_sigv-authentication-methods.html) O valor de é especificado usando o formato AAAAMMDD. O valor de é S3 ao enviar uma solicitação ao Amazon S3. | | SignedHeaders | Uma lista separada por ponto e vírgula dos cabeçalhos de solicitação usados para calcular a assinatura. A lista contém somente nomes de cabeçalho, e os nomes dos cabeçalhos devem estar em letras minúsculas. Por exemplo, .: `host;range;x-amz-date` Para SigV4a, você deve incluir um cabeçalho de conjunto de regiões que especifique o conjunto de regiões em que a solicitação será válida. O cabeçalho X-Amz-Region-Set é especificado como uma lista de valores separados por vírgula. | | Signature | A assinatura de 256 bits expressa como 64 caracteres hexadecimais minúsculos. Por exemplo, .:`fe5f80f77d5fa3beca038a248ff027d0445342fe2855ddc963176630326f1024` Os cálculos da assinatura variam de acordo com a opção escolhida para transferência de carga útil. | ## Parâmetros de string de consulta É possível usar uma string de consulta para expressar uma solicitação completa em um só URL. Nesse caso, utilize parâmetros de consulta para fornecer informações de solicitação, inclusive as informações de autenticação. Como a solicitação de assinatura faz parte do URL, esse tipo de URL muitas vezes é chamado de URL pré-assinado. É possível usar URLs pré-assinados para incorporar links clicáveis em HTML, que podem ser válidos por até sete dias. Para obter mais informações, consulte [Authenticating Requests: Using Query Parameters (AWS Signature Version 4)](https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-query-string-auth.html) na *Referência de APIs do Amazon S3*. Os exemplos a seguir mostram URLs pré-assinados para SigV4 e SigV4a. As quebras de linha foram adicionadas a este exemplo somente para facilitar a leitura: **Example SigV4** ``` https://s3.amazonaws.com/amzn-s3-demo-bucket/test.txt ? X-Amz-Algorithm=AWS4-HMAC-SHA256 & X-Amz-Credential=/20130721//s3/aws4_request & X-Amz-Date=20130721T201207Z & X-Amz-Expires=86400 & X-Amz-SignedHeaders=host &X-Amz-Signature= ``` **Example Sigv4a** ``` http://s3.amazonaws.com/amzn-s3-demo-bucket/test.txt ? X-Amz-Algorithm=AWS4-ECDSA-P256-SHA256 & X-Amz-Credential=/20240721/s3/aws4_request & X-amz-Region-Set= & X-Amz-Date=20240721T201207Z & X-Amz-Expires=86400 & X-Amz-SignedHeaders=host;x-amz-region-set & X-Amz-Signature= ``` **nota** O valor de `X-Amz-Credential` no URL exibe o caractere “/” somente para facilitar a leitura. Na prática, deve ser codificado como %2F. Por exemplo: `&X-Amz-Credential=%2F20130721%2Fus-east-1%2Fs3%2Faws4_request` A tabela a seguir descreve os parâmetros de consulta no URL que fornecem informações de autenticação. | Nome de parâmetro de string de consulta | Descrição | | --- | --- | | X-Amz-Algorithm | A versão da assinatura da AWS e o algoritmo que você usou para calcular a assinatura. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/IAM/latest/UserGuide/reference_sigv-authentication-methods.html) | | X-Amz-Credential | Além do ID da chave de acesso, esse parâmetro também fornece o escopo para o qual a assinatura é válida. O valor deve corresponder ao escopo usado nos cálculos de assinatura, abordados na seção a seguir. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/IAM/latest/UserGuide/reference_sigv-authentication-methods.html) Para obter uma lista de strings regionais da AWS, consulte [Regional Endpoints](https://docs.aws.amazon.com//general/latest/gr/rande.html#regional-endpoints) na *Referência geral da AWS*. | | X-Amz-Region-Set | O conjunto de regiões em que a solicitação será válida. O cabeçalho x-amz-region-set é especificado como uma lista de valores separados por vírgula. | | X-Amz-Date | O formato de data e hora deve seguir o padrão ISO 8601 e deve ter a formatação `yyyyMMddTHHmmssZ`. Por exemplo, se a data e a hora forem “08/01/2016 15:32:41.982-700”, elas primeiro deverão ser convertidas em UTC (Tempo Universal Coordenado) e depois enviadas como “20160801T223241Z”. | | X-Amz-Expires | Fornece o período, em segundos, de validade do URL pré-assinado gerado. Por exemplo, 86400 (24 horas). Esse valor é um inteiro. O valor mínimo que você pode definir é 1 e o máximo é 604800 (sete dias). O URL pré-assinado pode ser válido por no máximo sete dias, pois a chave de assinatura usada no cálculo da assinatura é válida por até sete dias. | | X-Amz-SignedHeaders | Lista os cabeçalhos usados para calcular a assinatura. Os seguintes cabeçalhos são obrigatórios para os cálculos da assinatura: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/IAM/latest/UserGuide/reference_sigv-authentication-methods.html) Para maior segurança, é necessário assinar todos os cabeçalhos de solicitação que pretende incluir na solicitação. | | X-Amz-Signature | Fornece a assinatura para autenticar a solicitação. Essa assinatura deve corresponder à assinatura calculada pelo serviço; caso contrário, o serviço negará a solicitação. Por exemplo, ., `733255ef022bec3f2a8701cd61d4b371f3f28c9f193a1f02279211d48d5193d7` Os cálculos de assinatura serão descritos na seção a seguir. | | X-Amz-Security-Token | Parâmetro de credencial opcional ao usar credenciais provenientes do serviço STS. | # Crie uma solicitação assinada de API da AWS **Importante** Caso use um SDK da AWS (consulte [Código de exemplo e bibliotecas](https://aws.amazon.com/developer/)) ou a ferramenta AWS Command Line Interface (AWS CLI) para enviar solicitações de API à AWS, você pode pular esta seção, pois os clientes do SDK e CLI autenticam as solicitações usando as chaves de acesso fornecidas por você. A menos que haja um bom motivo para não usar, é recomendável usar sempre um SDK ou a CLI. Em regiões compatíveis com várias versões de assinatura, assinar as solicitações manualmente significa que é necessário especificar qual versão de assinatura está sendo usada. Quando você fornece solicitações para pontos de acesso multirregionais, os SDKs e a CLI automaticamente alternam para o uso do Signature Version 4A, sem configuração adicional. Você pode usar o protocolo de assinatura SigV4 da AWS para criar uma solicitação assinada para solicitações de API da AWS. 1. A criação de uma solicitação canônica com base nos detalhes da solicitação. 1. O cálculo uma assinatura usando suas credenciais da AWS. 1. Adicionar essa assinatura à solicitação como um cabeçalho de autorização. A AWS, em seguida, replica esse processo e verifica a assinatura, concedendo ou negando o acesso adequadamente. Para ver como você pode usar o AWS SigV4 para assinar solicitações de API, consulte [Exemplos de assinatura de solicitação](reference_sigv-examples.md). A tabela a seguir descreve as funções usadas no processo de criação de uma solicitação assinada. É necessário implementar o código para essas funções. Para obter mais informações, consulte os [exemplos de código nos AWS SDKs](reference_sigv.md#reference_aws-signing-resources). | Função | Descrição | | --- | --- | | `Lowercase()` | Converta a string em letras minúsculas. | | `Hex()` | Codificação de base 16 em letras minúsculas. | | `SHA256Hash()` | Função de hash criptográfico do Secure Hash Algorithm (SHA). | | `HMAC-SHA256()` | Calcula o HMAC usando o algoritmo SHA256 com a chave de assinatura fornecida. Esta é a assinatura final quando você assina com o SigV4. | | `ECDSA-Sign` | Assinatura do Algoritmo de assinatura digital de curva elíptica (ECDSA) calculada usando assinaturas assimétricas baseadas em criptografia de chave pública-privada. | | `KDF(K, Label, Context, L)` | Um KDF NIST SP800-108 no Modo Contador usando a função PRF HMAC-SHA256, conforme definido no [NIST SP 800-108r1](https://doi.org/10.6028/NIST.SP.800-108r1-upd1). | | `Oct2Int(byte[ ])` | Uma função de octeto para inteiro, conforme descrito no ANSI X9.62. | | `Trim()` | Remova qualquer espaço em branco inicial e final. | | `UriEncode()` | O URI codifica cada byte. O UriEncode() deve aplicar as seguintes regras: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/IAM/latest/UserGuide/reference_sigv-create-signed-request.html) As funções UriEncode padrão fornecidas por sua plataforma de desenvolvimento podem não funcionar devido às diferenças na implementação e à ambiguidade relacionada nos RFCs subjacentes. É recomendável escrever sua própria função UriEncode personalizada para garantir que a codificação funcione. Para ver um exemplo de uma função UriEncode em Java, consulte [Java Utilities](https://github.com/aws/aws-sdk-java/blob/master/aws-java-sdk-core/src/main/java/com/amazonaws/util/SdkHttpUtils.java#L66) no site do GitHub. | **nota** Ao assinar as solicitações, você pode usar o AWS SigV4 ou o AWS SigV4a. A principal diferença entre os dois está na forma como a assinatura é calculada. Com o SigV4a, o conjunto de regiões é incluído na string a ser assinada, mas não faz parte da etapa de derivação da credencial. ## Solicitação de assinatura com credenciais de segurança temporárias Em vez de usar credenciais de longo prazo para assinar uma solicitação, é possível usar credenciais de segurança temporárias fornecidas pelo AWS Security Token Service (AWS STS). Ao usar credenciais de segurança temporárias, é necessário adicionar o código `X-Amz-Security-Token` ao cabeçalho de autorização ou incluí-lo na string de consulta para manter o token da sessão. Alguns serviços exigem que você adicione `X-Amz-Security-Token` à solicitação canônica. Outros serviços exigem apenas que você adicione `X-Amz-Security-Token` no final, depois de calcular a assinatura. Verifique a documentação de cada AWS service (Serviço da AWS) para obter requisitos específicos. ## Resumo das etapas de assinatura **Criar uma solicitação canônica** Organize o conteúdo da solicitação (host, ação, cabeçalhos etc.) em um formato padrão canônico. A solicitação canônica é um recurso usado para criar a string para assinar. Para obter detalhes sobre a criação da solicitação canônica, consulte [Elementos de uma assinatura de solicitação de API da AWS](reference_sigv-signing-elements.md). **Criar um hash para a solicitação canônica** Faça o hash da solicitação canônica usando o mesmo algoritmo que você usou para criar o hash da carga útil. O hash da solicitação canônica é uma string de caracteres hexadecimais em minúsculas. **Criar uma string para assinar** Crie uma string para assinar com a solicitação canônica e informações adicionais, como o algoritmo, data de solicitação, escopo de credencial e o hash da solicitação canônica. **Derivar uma chave de assinatura** Use a chave de acesso secreta para derivar a chave usada para assinar a solicitação. **Calcular a assinatura** Realize uma operação de hash com chave na string para assinar usando a chave de assinatura derivada como a chave de hash. **Adicionar a assinatura à solicitação** Adicione a assinatura calculada a um cabeçalho de HTTP ou à string de consulta da solicitação. ## Criar uma solicitação canônica Para criar uma solicitação canônica, concatene as strings a seguir separadas por caracteres de linha nova. Isso ajuda a garantir que a assinatura que você calcula possa corresponder à assinatura que a AWS calcula. ``` \n \n \n \n \n ``` + *HTTPMethod*: o método HTTP, como `GET`, `PUT`, `HEAD` e `DELETE`. + *CanonicalUri*: a versão codificada em URI do componente de caminho absoluto do URI, começando com o código `/` que segue o nome do domínio e indo até o final da string ou até o caractere de ponto de interrogação (`?`) se você tiver parâmetros de string de consulta. Se o caminho absoluto estiver vazio, use um caractere de barra inclinada (`/`). O URI no exemplo a seguir, `/amzn-s3-demo-bucket/myphoto.jpg`, é o caminho absoluto, e você não codifica o `/` no caminho absoluto: ``` http://s3.amazonaws.com/amzn-s3-demo-bucket/myphoto.jpg ``` + *CanonicalQueryString*: os parâmetros da string de consulta codificados por URI. Codifique por URI cada nome e valor individualmente. Também é necessário classificar os parâmetros na string de consulta canônica em ordem alfabética pelo nome da chave. A classificação ocorre após a codificação. A string de consulta no seguinte exemplo de URI é: ``` http://s3.amazonaws.com/amzn-s3-demo-bucket?prefix=somePrefix&marker=someMarker&max-keys=2 ``` A string de consulta canônica é como este exemplo (quebras de linha foram adicionadas ao exemplo para facilitar a leitura): ``` UriEncode("marker")+"="+UriEncode("someMarker")+"&"+ UriEncode("max-keys")+"="+UriEncode("20") + "&" + UriEncode("prefix")+"="+UriEncode("somePrefix") ``` Quando uma solicitação se destina a um sub-recurso, o valor do parâmetro de consulta correspondente é uma string vazia (`""`). Por exemplo, o URI a seguir identifica o sub-recurso `ACL` no bucket `amzn-s3-demo-bucket`: ``` http://s3.amazonaws.com/amzn-s3-demo-bucket?acl ``` Nesse caso, a CanonicalQueryString seria: ``` UriEncode("acl") + "=" + "" ``` Caso o URI não contenha um `?`, não há strings de consulta na solicitação, e você define a string de consulta canônica como uma string vazia (`""`). Você ainda precisará incluir o caractere de linha nova (`"\n"`). + *CanonicalHeaders*: uma lista de cabeçalhos de solicitação com os respectivos valores. Os pares individuais de nome e valor do cabeçalho são separados pelo caractere de linha nova (`"\n"`). Veja a seguir um exemplo de um CanonicalHeader: ``` Lowercase()+":"+Trim()+"\n" Lowercase()+":"+Trim()+"\n" ... Lowercase()+":"+Trim()+"\n" ``` A lista CanonicalHeaders deve conter: + Cabeçalho HTTP `host` + Se o cabeçalho `Content-Type` estiver presente na solicitação, você deverá adicioná-lo à lista *CanonicalHeaders*. + Também deverão ser adicionados todos os cabeçalhos `x-amz-*` que você pretende incluir na solicitação. Por exemplo, se você estiver usando credenciais de segurança temporárias, precisará incluir o `x-amz-security-token` na solicitação. É necessário adicionar esse cabeçalho à lista de *CanonicalHeaders*. + Para SigV4a, você deve incluir um cabeçalho de conjunto de regiões que especifique o conjunto de regiões em que a solicitação será válida. O cabeçalho `X-Amz-Region-Set` é especificado como uma lista de valores separados por vírgula. O exemplo a seguir mostra um cabeçalho de região que permite fazer uma solicitação nas regiões us-east-1 e us-west-1. `X-Amz-Region-Set=us-east-1,us-west-1 ` Você pode usar curingas (\$1) em regiões para especificar várias regiões. No exemplo a seguir, o cabeçalho permite que uma solicitação seja feita tanto na região us-west-1 quanto na us-west-2. `X-Amz-Region-Set=us-west-*` **nota** O cabeçalho `x-amz-content-sha256` é obrigatório para solicitações da AWS do Amazon S3. Ele fornece um hash da carga da solicitação. Se não houver carga útil, será necessário fornecer o hash de uma string vazia. Todo nome de cabeçalho deve: + usar caracteres minúsculos. + ser exibido em ordem alfabética. + ser seguido por dois pontos (`:`). Para valores, é necessário: + remover todos os espaços à esquerda ou à direita. + converter espaços sequenciais em um espaço único. + separar os valores de um cabeçalho de múltiplos valores usando vírgulas. + É necessário incluir na assinatura o cabeçalho host (HTTP/1.1) ou o cabeçalho :authority (HTTP/2) e quaisquer cabeçalhos `x-amz-*`. Opcionalmente, você pode incluir outros cabeçalhos padrão na assinatura, como content-type. As funções `Lowercase()` e `Trim()` usadas neste exemplo estão descritas na seção anterior. Veja a seguir um exemplo de string `CanonicalHeaders`. O nomes dos cabeçalhos estão em letras minúsculas e são classificados. ``` host:s3.amazonaws.com x-amz-content-sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 x-amz-date:20130708T220855Z ``` **nota** Para fins de cálculo de uma assinatura de autorização, somente o host e cabeçalhos `x-amz-*` são obrigatórios; no entanto, para evitar a adulteração de dados, considere incluir os cabeçalhos adicionais no cálculo da assinatura. Não inclua cabeçalhos hop-by-hop que são alterados com frequência durante o trânsito em um sistema complexo. Isso inclui todos os cabeçalhos de transporte voláteis que são alterados por proxies, balanceadores de carga e nós em um sistema distribuído, incluindo `connection`, `x-amzn-trace-id`, `user-agent`, `keep-alive`, `transfer-encoding`, `TE`, `trailer`, `upgrade`, `proxy-authorization` e `proxy-authenticate`. + *SignedHeaders*: uma lista ordenada alfabeticamente, separada por ponto e vírgula, de nomes de cabeçalhos de solicitação em letras minúsculas. Os cabeçalhos de solicitação da lista são os mesmos cabeçalhos que você incluiu na string `CanonicalHeaders`. Para o exemplo anterior, o valor de *SignedHeaders* seria: ``` host;x-amz-content-sha256;x-amz-date ``` + *HashedPayload*: uma string criada usando a carga útil no corpo da solicitação HTTP como entrada para uma função de hash. Esta string usa caracteres hexadecimais minúsculos. ``` Hex(SHA256Hash(>)) ``` Se não houver carga útil na solicitação, calcule um hash da string vazia. Por exemplo, ao recuperar um objeto usando uma solicitação `GET`, não haverá nada na carga útil. ``` Hex(SHA256Hash("")) ``` **nota** Para o Amazon S3, inclua a string literal `UNSIGNED-PAYLOAD` ao construir uma solicitação canônica e defina o mesmo valor como o cabeçalho `x-amz-content-sha256` ao enviar a solicitação. `Hex(SHA256Hash("UNSIGNED-PAYLOAD"))` ## Criar um hash para a solicitação canônica Crie um hash (resumo) da solicitação canônica usando o mesmo algoritmo que você usou para criar o hash da carga útil. O hash da solicitação canônica é uma string de caracteres hexadecimais em minúsculas. ## Criar uma string para assinar Para criar uma string para assinar, concatene as strings a seguir separadas por caracteres de linha nova. Não termine esta string com um caractere de linha nova. ``` Algorithm \n RequestDateTime \n CredentialScope \n HashedCanonicalRequest ``` + *Algorithm*: o algoritmo usado para criar o hash da solicitação canônica. + SigV4: use `AWS4-HMAC-SHA256` para especificar o algoritmo de hash `HMAC-SHA256`. + SigV4a: use `AWS4-ECDSA-P256-SHA256` para especificar o algoritmo de hash `ECDSA-P256-SHA-256`. + *RequestDateTime*: a data e a hora usadas no escopo da credencial. Esse valor é a hora UTC atual no formato ISO 8601 (por exemplo, `20130524T000000Z`). + *CredentialScope*: o escopo de credencial, que restringe a assinatura resultante à região e ao serviço especificados. + SigV4: as credenciais incluem o ID da chave de acesso, a data no formato `YYYYMMDD`, o código da região, o código do serviço e a string `aws4_request` de término separados por barras (/). O código da região, o código do serviço e a string de término devem usar caracteres minúsculos. A string tem o seguinte formato: `YYYYMMDD/region/service/aws4_request`. + SigV4a: as credenciais incluem a data no formato `YYYYMMDD`, o nome do serviço e a string `aws4_request` de término separados por barras (/). Observe que o escopo da credencial não inclui a região, pois ela é englobada em um cabeçalho `X-Amz-Region-Set` separado. A string tem o seguinte formato: `YYYYMMDD/service/aws4_request`. + *HashedCanonicalRequest*: o hash da solicitação canônica, calculada na etapa anterior. Veja a seguir um exemplo de string para assinar. ``` "" + "\n" + timeStampISO8601Format + "\n" + + "\n" + Hex(()) ``` ## Derivar uma chave de assinatura Para derivar uma chave de assinatura, escolha um dos processos a seguir para calcular uma chave de assinatura para SigV4 ou SigV4a. ### Derivar uma chave de assinatura para SigV4 Para derivar uma chave de assinatura para SigV4, realize uma sequência de operações de hash com chave (HMAC) no serviço, região e data da solicitação usando sua chave de acesso secreta da AWS como a chave para a operação inicial de hashing. Para cada etapa, chame a função de hash com a chave e os dados necessários. O resultado de cada chamada para a função de hash torna-se a entrada para a próxima chamada para a função de hash. O exemplo a seguir mostra como você deriva a `SigningKey` usada na próxima seção desse procedimento, mostrando a ordem na qual sua entrada é concatenada e transformada em hash. O código `HMAC-SHA256` é a função de hash usada para fazer o hash dos dados, conforme mostrado. ``` DateKey = HMAC-SHA256("AWS4"+"", "") DateRegionKey = HMAC-SHA256(, "") DateRegionServiceKey = HMAC-SHA256(, "") SigningKey = HMAC-SHA256(, "aws4_request") ``` **Entrada obrigatória** + `Key`: uma string que contém sua chave de acesso secreta. + `Date`: uma string que contém a data usada no escopo da credencial, no formato *AAAAMMDD*. + `Region`: uma string que contém o código da região (por exemplo, `us-east-1`). Para obter uma lista de regiões de strings, consulte [Regional endpoints](https://docs.aws.amazon.com//general/latest/gr/rande.html#regional-endpoints), na *Referência geral da AWS*. + `Service`: uma string que contém o código do serviço (por exemplo, `ec2`). + A string para assinar que você criou na etapa anterior. **Derivar uma chave de assinatura para SigV4** 1. Concatene `"AWS4"` e a chave de acesso secreta. Chame a função de hash com a string concatenada como chave e a string de data como os dados. ``` DateKey = hash("AWS4" + Key, Date) ``` 1. Chame a função de hash com o resultado da chamada anterior como chave e a string de região como os dados. ``` DateRegionKey = hash(kDate, Region) ``` 1. Chame a função de hash com o resultado da chamada anterior como a chave e a string de serviço como os dados. O código do serviço é definido pelo serviço. Você pode usar [get-products](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/pricing/get-products.html) na *AWS Pricing CLI* para retornar o código de serviço de um serviço. ``` DateRegionServiceKey = hash(kRegion, Service) ``` 1. Chame a função de hash com o resultado da chamada anterior como a chave e “aws4\$1request” como os dados. ``` SigningKey = hash(kService, "aws4_request") ``` ### Derivar uma chave de assinatura para SigV4a Para criar uma chave de assinatura para SigV4a, use o processo a seguir para derivar um par de chaves da chave de acesso secreta. Para obter um exemplo de implementação dessa derivação, consulte a [implementação da biblioteca C99 da autenticação do lado do cliente da AWS](https://github.com/awslabs/aws-c-auth/blob/e8360a65e0f3337d4ac827945e00c3b55a641a5f/source/key_derivation.c#L291.) ``` n = [NIST P-256 elliptic curve group order] G = [NIST P-256 elliptic curve base point] label = "AWS4-ECDSA-P256-SHA256" akid = [AWS access key ID as a UTF8 string] sk = [AWS secret access Key as a UTF8 Base64 string] input_key = "AWS4A" || sk count = 1 while (counter != 255) { context = akid || counter // note: counter is one byte key = KDF(input_key, label, context, 256) c = Oct2Int(key) if (c > n - 2) { counter++ } else { k = c + 1 // private key Q = k * G // public key } } if (c < 255) { return [k, Q] } else { return FAILURE } ``` ## Calcular a assinatura Depois de derivar a chave de assinatura, calcule a assinatura para adicionar à sua solicitação. Esse procedimento varia de acordo com a versão de assinatura que você usa. **Para calcular uma assinatura para SigV4** 1. Chame a função de hash com o resultado da chamada anterior como a chave e a **string para assinar** como os dados. Use a chave de assinatura derivada como a chave de hash para esta operação. O resultado é a assinatura como valor binário. ``` signature = hash(SigningKey, string-to-sign) ``` 1. Converta a assinatura da representação binária em hexadecimal, em caracteres minúsculos. **Para calcular uma assinatura para SigV4a** 1. Usando o algoritmo de assinatura digital (ECDSA P-256), assine a **string para assinar** que você criou na etapa anterior. A chave usada para essa assinatura é a chave assimétrica privada derivada da chave de acesso secreta, conforme descrito acima. ``` signature = base16(ECDSA-Sign(k, string-to-sign)) ``` 1. Converta a assinatura da representação binária em hexadecimal, em caracteres minúsculos. ## Adicionar a assinatura à solicitação Adicione a assinatura calculada à sua solicitação. **Example Exemplo: cabeçalho de autorização** **SigV4** O exemplo a seguir mostra um cabeçalho `Authorization` para a ação `DescribeInstances` usando o AWS SigV4. Para facilitar a leitura, este exemplo está formatado com quebras de linha. Em seu código, deve ser uma string contínua. Não há vírgula entre o algoritmo e `Credential`. Porém, os outros elementos devem ser separados por vírgulas. ``` Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20220830/us-east-1/ec2/aws4_request, SignedHeaders=host;x-amz-date, Signature=calculated-signature ``` **Sigv4a** O exemplo a seguir mostra um cabeçalho Authorization para a ação `CreateBucket` usando o AWS SigV4a. Para facilitar a leitura, este exemplo está formatado com quebras de linha. Em seu código, deve ser uma string contínua. Não há vírgula entre o algoritmo e a credencial. Porém, os outros elementos devem ser separados por vírgulas. ``` Authorization: AWS4-ECDSA-P256-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20220830/s3/aws4_request, SignedHeaders=host;x-amz-date;x-amz-region-set, Signature=calculated-signature ``` **Example Exemplo: solicitação com parâmetros de autenticação na string de consulta** **SigV4** O exemplo a seguir mostra uma consulta para a ação `DescribeInstances` usando o AWS SigV4 que contém as informações de autenticação. Para facilitar a leitura, esse exemplo está formatado com quebras de linha e não codificado de URL. Em seu código, a string de consulta deve ser uma string contínua codificada de URL. ``` https://ec2.amazonaws.com/? Action=DescribeInstances& Version=2016-11-15& X-Amz-Algorithm=AWS4-HMAC-SHA256& X-Amz-Credential=AKIAIOSFODNN7EXAMPLE/20220830/us-east-1/ec2/aws4_request& X-Amz-Date=20220830T123600Z& X-Amz-SignedHeaders=host;x-amz-date& X-Amz-Signature=calculated-signature ``` **Sigv4a** O exemplo a seguir mostra uma consulta para a ação `CreateBucket` usando o AWS SigV4a que contém as informações de autenticação. Para facilitar a leitura, esse exemplo está formatado com quebras de linha e não codificado de URL. Em seu código, a string de consulta deve ser uma string contínua codificada de URL. ``` https://ec2.amazonaws.com/? Action=CreateBucket& Version=2016-11-15& X-Amz-Algorithm=AWS4-ECDSA-P256-SHA256& X-Amz-Credential=AKIAIOSFODNN7EXAMPLE/20220830/s3/aws4_request& X-Amz-Region-Set=us-west-1& X-Amz-Date=20220830T123600Z& X-Amz-SignedHeaders=host;x-amz-date;x-amz-region-set& X-Amz-Signature=calculated-signature ``` # Exemplos de assinatura de solicitação Os exemplos a seguir de solicitações de  assinatura da AWS mostram como você pode usar o SigV4 para assinar solicitações enviadas sem o AWS SDK ou a ferramenta de linha de comando da AWS. ## Upload do Amazon S3 baseado em navegador usando HTTP POST [Solicitações de autenticação: os uploads baseados em navegador](https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-authentication-HTTPPOST.html) descrevem a assinatura e as informações relevantes que o Amazon S3 usa para calcular a assinatura ao receber a solicitação. [Exemplo: o upload baseado em navegador usando HTTP POST (usando o AWS Signature Version 4)](https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-post-example.html) fornece mais informações com um exemplo de política POST e um formulário que você pode usar para fazer upload de um arquivo. A política de exemplo e as credenciais fictícias mostram o fluxo de trabalho e a assinatura e o hash da política resultantes. ## Solicitações autenticadas do VPC Lattice Os [exemplos de solicitações autenticadas do Signature Version 4 (SigV4)](https://docs.aws.amazon.com/vpc-lattice/latest/ug/sigv4-authenticated-requests.html) fornecem exemplos em Python e Java que mostram como você pode realizar a assinatura de solicitações com e sem interceptores personalizados. ## Usar o Signature Version 4 com o Amazon Translate [Live Translations in the Metaverse](https://aws.amazon.com/blogs/spatial/live-translations-in-the-metaverse/) mostra como criar uma aplicação que produz uma solução de tradução quase em tempo real. Essa solução de tradução de fala para fala usa o SigV4 da AWS na codificação de fluxo de eventos para produzir transcrições em tempo real. ## Usar o Signature Version 4 com o Neptune [Exemplo: conectar-se ao Neptune usando Python com a assinatura do Signature Version 4](https://docs.aws.amazon.com/neptune/latest/userguide/iam-auth-connecting-python.html) mostra como fazer solicitações assinadas para o Neptune usando Python. Esse exemplo inclui variações para usar uma chave de acesso ou credenciais temporárias. ## Assinatura de solicitações HTTP no Amazon Glacier [Exemplo de cálculo de assinatura para API de streaming](https://docs.aws.amazon.com/amazonglacier/latest/dev/amazon-glacier-signing-requests.html) explica os detalhes da criação de uma assinatura para o Upload Archive (arquivo POST), uma das duas APIs de streaming no Amazon Glacier. ## Solicitações HTTP no Amazon SWF [Fazer solicitações HTTP no Amazon SWF](https://docs.aws.amazon.com/amazonswf/latest/developerguide/UsingJSON-swf.html#HTTPHeader) mostra o conteúdo do cabeçalho de uma solicitação JSON no Amazon SWF. ## Cálculo de assinatura para APIs de streaming no Amazon OpenSearch Service [Assinatura de uma solicitação de pesquisa do Amazon OpenSearch Service com AWS SDK para PHP versão 3](https://docs.aws.amazon.com/sdk-for-php/v3/developer-guide/service_es-data-plane.html) inclui um exemplo de como enviar solicitações HTTP assinadas para o Amazon OpenSearch Service. ## Projetos de exemplo em repositório de amostras da AWS Os projetos de exemplo a seguir mostram como assinar solicitações para fazer solicitações da API Rest para serviços da AWS com linguagens comuns, como Python, Node.js, Java, C\$1, Go e Rust. ### Projetos do Signature Version 4a O projeto [sigv4-signing-examples](https://github.com/aws-samples/sigv4-signing-examples) fornece exemplos de como assinar solicitações com SigV4 para fazer solicitações da API Rest para Serviços da AWS com linguagens comuns, como Python, Node.js, Java, C\$1, Go e Rust. O projeto [sigv4a-signing-examples](https://github.com/aws-samples/sigv4a-signing-examples) fornece exemplos para assinar solicitações de API multirregionais, por exemplo, [Pontos de acesso multirregionais no Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/MultiRegionAccessPoints.html). ### Publicar no AWS IoT Core O [código Python para publicar no AWS IoT Core usando o protocolo HTTPs](https://github.com/aws-samples/aws-iot-core-python-node-sigv4-https) fornece orientação sobre como publicar mensagens no AWS IoT Core usando o protocolo Https e autenticação SigV4 da AWS. Tem duas implementações de referência, uma em Python e outra em NodeJS. A [aplicação .Net Framework para publicar no AWS IoT Core usando o protocolo HTTPs](https://github.com/aws-samples/aws-iot-core-http-sigv4-dotnet-app) fornece orientação sobre como publicar mensagens no AWS IoT Core usando o protocolo HTTPS e autenticação SigV4 da AWS. Esse projeto também inclui uma implementação equivalente do .NET Core. # Solucionar problemas de assinatura do Signature Version 4 para solicitações de API da AWS **Importante** A menos que você esteja usando AWS SDKs ou a CLI, é necessário escrever código para calcular assinaturas que forneçam informações de autenticação em suas solicitações. O cálculo da assinatura no SigV4 pode ser uma tarefa complexa. Por isso, recomenda-se usar os AWS SDKs ou a CLI sempre que possível. Ao desenvolver um código que cria uma solicitação assinada, uma mensagem HTTP 403 `SignatureDoesNotMatch` poderá ser recebida dos Serviços da AWS. Esses erros significam que o valor da assinatura em sua solicitação HTTP para a AWS não correspondeu à assinatura calculada pelo AWS service (Serviço da AWS). Os erros HTTP 401 `Unauthorized` são retornados quando as permissões não permitem que o chamador faça a solicitação. As solicitações de API podem retornar um erro se: + A solicitação da API não é assinada e usa a autenticação do IAM. + As credenciais do IAM usadas para assinar a solicitação estão incorretas ou não têm permissão para invocar a API. + A assinatura da solicitação de API assinada não corresponde à assinatura calculada pelo serviço da AWS. + O cabeçalho da solicitação da API está incorreto. **nota** Atualize seu protocolo de assinatura do AWS Signature Version 2 (SigV2) para o AWS Signature Version 4 (SigV4) antes de explorar outras soluções de erro. Serviços, como o Amazon S3, e regiões não oferecem mais suporte a assinaturas SigV2. **Topics** + [ ## Erros de credencial ](#signature-v4-troubleshooting-credential) + [ ## Erros de solicitação canônica e string de assinatura ](#signature-v4-troubleshooting-canonical-errors) + [ ## Erros de escopo de credenciais ](#signature-v4-troubleshooting-credential-scope) + [ ## Erros de assinatura de chave ](#signature-v4-troubleshooting-key-signing) ## Erros de credencial Certifique-se de que a solicitação de API seja assinada com o SigV4. Se a solicitação da API não estiver assinada, o seguinte erro poderá ser recebido: `Missing Authentication Token`. [Adicione a assinatura que falta](https://docs.aws.amazon.com/IAM/latest/UserGuide/create-signed-request.html#add-signature-to-request) e reenvie a solicitação. Verifique se as credenciais de autenticação para a chave de acesso e a chave secreta estão corretas. Se a chave de acesso estiver incorreta, o seguinte erro poderá ser recebido: `Unauthorized`. Certifique-se de que a entidade usada para assinar a solicitação esteja autorizada a fazer a solicitação. Para obter detalhes, consulte [Solucionar problemas de mensagens de erro de acesso negado](troubleshoot_access-denied.md). ## Erros de solicitação canônica e string de assinatura Se você calculou incorretamente a solicitação canônica em [Criar um hash para a solicitação canônica](reference_sigv-create-signed-request.md#create-canonical-request-hash) ou [Criar uma string para assinar](reference_sigv-create-signed-request.md#create-string-to-sign), a etapa de verificação de assinatura executada pelo serviço falhará com a mensagem de erro: ``` The request signature we calculated does not match the signature you provided ``` Quando o serviço da AWS recebe uma solicitação assinada, ele recalcula a assinatura. Se houver diferenças nos valores, as assinaturas não coincidirão. Compare a solicitação canônica e a string à sua solicitação assinada com o valor na mensagem de erro. Modifique o processo de assinatura se houver alguma diferença. **nota** Você também pode verificar se não enviou a solicitação por meio de um proxy que modifica os cabeçalhos ou a solicitação. **Example Exemplo de solicitação canônica** ``` GET -------- HTTP method / -------- Path. For API stage endpoint, it should be /{stage-name}/{resource-path} -------- Query string key-value pair. Leave it blank if the request doesn't have a query string. content-type:application/json -------- Header key-value pair. One header per line. host:0123456789.execute-api.us-east-1.amazonaws.com -------- Host and x-amz-date are required headers for all signed requests. x-amz-date:20220806T024003Z content-type;host;x-amz-date -------- A list of signed headers d167e99c53f15b0c105101d468ae35a3dc9187839ca081095e340f3649a04501 -------- Hash of the payload ``` Para verificar se a chave secreta corresponde ao ID da chave de acesso, é possível testá-la com uma implementação em funcionamento conhecida. Por exemplo, use um AWS SDK ou a AWS CLI para fazer uma solicitação para a AWS. ### Cabeçalho da solicitação de API Quando o cabeçalho de autorização está vazio, a chave ou assinatura da credencial está ausente ou está incorreta, o cabeçalho não começa com um nome de algoritmo ou os pares de valores-chave não incluem um sinal de igual, você recebe um dos seguintes erros: + O cabeçalho de autorização não pode estar vazio. + O cabeçalho de autorização requer o parâmetro “Credential”. + O cabeçalho de autorização requer o parâmetro “Signature”. + A assinatura contém um par de chave=valor inválido (sem sinal de igualdade) no cabeçalho de autorização. Certifique-se de que o cabeçalho de autorização SigV4 que você adicionou em [Calcular a assinatura](reference_sigv-create-signed-request.md#calculate-signature) inclua a chave de credencial correta e também a data da solicitação usando HTTP Date ou o cabeçalho. Se você recebeu um erro IncompleteSignatureException e a construção da assinatura está correta, você pode verificar se o cabeçalho de autorização não foi modificado em trânsito para o computando um hash SHA-256 e a codificação B64 do cabeçalho de autorização em sua solicitação AWS service (Serviço da AWS) do lado do cliente. 1. Obtenha o [cabeçalho de autorização](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv-authentication-methods.html) que você enviou na solicitação. Seu cabeçalho de autorização é semelhante ao seguinte exemplo: ``` Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20130524/us-east-1/s3/aws4_request, SignedHeaders=host;range;x-amz-date, Signature=example-generated-signature ``` 1. Calcule um hash SHA-256 do cabeçalho de autorização. ``` hashSHA256(rawAuthorizationHeader) = hashedAuthorizationHeader ``` 1. Codifique o cabeçalho de autorização com hash no formato Base64. ``` base64(hashedAuthorizationHeader) = encodedHashedAuthorizationHeader ``` 1. Compare a string codificada e com hash que você acabou de calcular com a string que você recebeu na sua mensagem de erro. Sua mensagem de erro deve ser semelhante ao exemplo a seguir: ``` com.amazon.coral.service#IncompleteSignatureException: The signature contains an in-valid key=value pair (missing equal-sign) in Authorization header (hashed with SHA-256 and encoded with Base64): '9c574f83b4b950926da4a99c2b43418b3db8d97d571b5e18dd0e4f3c3ed1ed2c'. ``` + Se os dois hashes forem diferentes, então alguma parte do cabeçalho de autorização foi alterada em trânsito. Essa alteração pode ocorrer devido ao fato de seus manipuladores de rede ou cliente anexarem cabeçalhos assinados ou alterarem o cabeçalho de autorização de alguma forma. + Se os dois hashes corresponderem, o cabeçalho de autorização que você enviou na solicitação corresponderá ao AWS recebido. Analise a mensagem de erro que você recebeu para determinar se o problema é resultado de credenciais ou assinaturas incorretas. Esses erros são abordados nas outras seções desta página. ## Erros de escopo de credenciais O escopo da credencial criado em [Criar uma string para assinar](reference_sigv-create-signed-request.md#create-string-to-sign) restringe a assinatura a uma data, uma região e um serviço específicos. Essa string tem o seguinte formato: ``` YYYYMMDD/region/service/aws4_request ``` **nota** Se você estiver usando o SIGv4a, a região não estará incluída no escopo da credencial. **Data** Se o escopo da credencial não especificar a mesma data que o cabeçalho x-amz-date, a etapa de verificação da assinatura falhará com a seguinte mensagem de erro: ``` Date in Credential scope does not match YYYYMMDD from ISO-8601 version of date from HTTP ``` Se a solicitação especificar um horário no futuro, a etapa de verificação da assinatura falhará com a seguinte mensagem de erro: ``` Signature not yet current: date is still later than date ``` Se a solicitação tiver expirado, a etapa de verificação da assinatura falhará com a seguinte mensagem de erro: ``` Signature expired: date is now earlier than date ``` **Região** Se o escopo da credencial não especificar a mesma região que a solicitação, a etapa de verificação da assinatura falhará com a seguinte mensagem de erro: ``` Credential should be scoped to a valid Region, not region-code ``` **Serviço** Se o escopo da credencial não especificar o mesmo serviço que o cabeçalho host, a etapa de verificação da assinatura falhará com a seguinte mensagem de erro: ``` Credential should be scoped to correct service: 'service' ``` **String de término** Se o escopo da credencial não terminar com aws4\$1request, a etapa de verificação da assinatura falhará com a seguinte mensagem de erro: ``` Credential should be scoped with a valid terminator: 'aws4_request' ``` ## Erros de assinatura de chave Erros causados por derivação incorreta da chave de assinatura ou uso incorreto de criptografia são mais difíceis de solucionar. Após verificar se a string canônica e a string a ser assinada estão corretas, você também pode verificar se há um dos seguintes problemas: + A chave de acesso secreta não corresponde à ID de chave de acesso especificada. + Existe um problema com seu código de derivação de chaves. Para verificar se a chave secreta corresponde ao ID da chave de acesso, é possível testá-la com uma implementação em funcionamento conhecida. Por exemplo, use um AWS SDK ou a AWS CLI para fazer uma solicitação para a AWS. Para obter exemplos, consulte [Exemplos de assinatura de solicitação](reference_sigv-examples.md)