Object Storage Service:Include a V1 signature in the header

Implementação de assinatura via SDK

Os SDKs do OSS gerenciam automaticamente as assinaturas V1. Não é necessário calcular a assinatura manualmente ao usar um SDK. Para entender a implementação em uma linguagem específica, consulte o código source do SDK. A tabela a seguir lista os arquivos de implementação de assinatura para cada SDK.

Como calcular o campo Authorization

Método de cálculo

Authorization = "OSS " + AccessKeyId + ":" + Signature
Signature = base64(hmac-sha1(AccessKeySecret,
            VERB + "\n"
            + Content-MD5 + "\n" 
            + Content-Type + "\n" 
            + Date + "\n" 
            + CanonicalizedOSSHeaders
            + CanonicalizedResource))

Parâmetros

Exemplos de assinatura

• Exemplo 1 (inclui todos os parâmetros)

  Requisição	Fórmula da string a ser assinada	String a ser assinada
  PUT /nelson HTTP/1.0 Content-MD5: eB5e Content-Type: text/html Date: Wed, 28 Dec 2022 10:27:41 GMT Host: examplebucket.oss-cn-hangzhou.aliyuncs.com x-oss-meta-author: alice x-oss-meta-magic: abracadabra	Signature = base64(hmac-sha1(AccessKeySecret, VERB + "\n" + Content-MD5 + "\n" + Content-Type + "\n" + Date + "\n" + CanonicalizedOSSHeaders + CanonicalizedResource))	PUT\n eB5e\n text/html\n Wed, 28 Dec 2022 10:27:41 GMT\n x-oss-meta-magic:abracadabra\nx-oss-meta-author:alice\n/examplebucket/nelson

  Se o AccessKey ID for LTAI e o AccessKey secret for yourAccessKeySecret, use o código Python abaixo para calcular a assinatura.

  import hmac
  import hashlib
  import base64
  
  h = hmac.new("yourAccessKeySecret".encode('utf-8'),
               "PUT\nODBGOERFMDMzQTczRUY3NUE3NzA5QzdFNUYzMDQxNEM\ntext/html\nWed, 28 Dec 2022 10:27:41 GMT\nx-oss-meta-magic:abracadabra\nx-oss-meta-author:alice\n/oss-example/nelson".encode('utf-8'), hashlib.sha1)
  signature =  base64.encodebytes(h.digest())
  print(signature)

  A assinatura calculada é J9Nl************************. A requisição final apresenta a seguinte estrutura.

  PUT /nelson HTTP/1.0
  Authorization:OSS LTAI****************:J9Nl************************
  Content-Md5: eB5e********************
  Content-Type: text/html
  Date: Wed, 28 Dec 2022 10:27:41 GMT
  Host: oss-example.oss-cn-hangzhou.aliyuncs.com
  x-oss-meta-author: alice
  x-oss-meta-magic: abracadabra

• Exemplo 2 (exclui os parâmetros opcionais Content-MD5 e Content-Type)

  Requisição	Fórmula da string a ser assinada	String a ser assinada
  PUT /nelson HTTP/1.0 Date: Wed, 28 Dec 2022 09:56:32 GMT Host: examplebucket.oss-cn-hangzhou.aliyuncs.com x-oss-meta-author: alice x-oss-meta-magic: abracadabra	Signature = base64(hmac-sha1(AccessKeySecret, VERB + "\n" + "\n" + "\n" + Date + "\n" + CanonicalizedOSSHeaders + CanonicalizedResource))	PUT\n\n\nWed, 28 Dec 2022 09:56:32 GMT\n x-oss-meta-magic:abracadabra\nx-oss-meta-author:alice\n/examplebucket/nelson

  Neste exemplo, o AccessKey ID é LTAI e o AccessKey secret é yourAccessKeySecret. O código Python a seguir demonstra como calcular a assinatura.

  import hmac
  import hashlib
  import base64
  
  h = hmac.new("yourAccessKeySecret".encode('utf-8'),
               "PUT\n\n\nWed, 28 Dec 2022 09:56:32 GMT\nx-oss-meta-magic:abracadabra\nx-oss-meta-author:alice\n/oss-example/nelson".encode('utf-8'), hashlib.sha1)
  signature =  base64.encodebytes(h.digest())
  print(signature)

  A assinatura calculada é Mhb1************************. A requisição final apresenta a seguinte estrutura.

  PUT /nelson HTTP/1.0
  Authorization:OSS LTAI****************:Mhb1************************
  Date: Wed, 28 Dec 2022 09:56:32 GMT
  Host: oss-example.oss-cn-hangzhou.aliyuncs.com
  x-oss-meta-author: alice
  x-oss-meta-magic: abracadabra

Informações adicionais

• Caso o AccessKey ID fornecido não exista ou esteja inativo, o OSS retorna um erro 403 Forbidden com o código InvalidAccessKeyId. Se o AccessKey ID estiver ativo, mas o OSS detectar um erro de assinatura na requisição, o serviço retornará um erro 403 Forbidden. A resposta inclui a string correta a ser assinada, permitindo que você verifique seu processo de assinatura.

  O código abaixo exibe um exemplo de resposta:

  <?xml version="1.0" ?>
  <Error>
   <Code>
       SignatureDoesNotMatch
   </Code>
   <Message>
       The request signature we calculated does not match the signature you provided. Check your key and signing method.
   </Message>
   <StringToSignBytes>
       47 45 54 0a 0a 0a 57 65 64 2c 20 31 31 20 4d 61 79 20 32 30 31 31 20 30 37 3a 35 39 3a 32 35 20 47 4d 54 0a 2f 75 73 72 65 61 6c 74 65 73 74 3f 61 63 6c
   </StringToSignBytes>
   <RequestId>
       1E446260FF9B****
   </RequestId>
   <HostId>
       oss-cn-hangzhou.aliyuncs.***
   </HostId>
   <SignatureProvided>
       y5H7************************
   </SignatureProvided>
   <StringToSign>
       GET
  Wed, 11 May 2011 07:59:25 GMT
  /examplebucket?acl
   </StringToSign>
   <OSSAccessKeyId>
       AKIA****************
   </OSSAccessKeyId>
  </Error>

• Quando o formato do valor Authorization no cabeçalho da requisição estiver incorreto, o OSS retorna um erro 400 Bad Request com o código InvalidArgument.

• Todas as requisições enviadas ao OSS devem usar o formato de data GMT especificado no HTTP 1.1. O formato da data é o seguinte:

  date1 = 2DIGIT SP month SP 4DIGIT; day month year (e.g., 02 Jun 1982)

  Nota

  No formato de data acima, day representa um número de dois dígitos. Portanto, Jun 2, 2 Jun 1982 e 2-Jun-1982 são formatos de data inválidos.

  • Se o cabeçalho Date estiver ausente em uma requisição assinada ou apresentar formato inválido, o OSS retorna um erro 403 Forbidden com o código AccessDenied.

  • O horário na requisição deve estar dentro de 15 minutos do horário atual do servidor OSS. Caso contrário, o OSS retorna um erro 403 Forbidden com o código RequestTimeTooSkewed.

Como construir CanonicalizedOSSHeaders

Todos os cabeçalhos HTTP com prefixo x-oss- são considerados cabeçalhos OSS canônicos. Para construir a string CanonicalizedOSSHeaders, siga estas etapas:

1. Converta para minúsculas os nomes de todos os cabeçalhos de requisição HTTP com prefixo x-oss-. Por exemplo, converta X-OSS-Meta-Name: TaoBao para x-oss-meta-name: TaoBao.

2. Ao enviar uma requisição com credenciais de acesso temporárias do Security Token Service (STS), adicione o token de segurança à string a ser assinada no formato x-oss-security-token:security-token.

   Nota

   Para mais informações sobre como configurar o STS, consulte Use temporary credentials provided by STS to access OSS. Chame a operação AssumeRole ou use STS SDKs for various programming languages para obter credenciais de acesso temporárias. Essas credenciais contêm um token de segurança e um par de AccessKey temporário. Um par de AccessKey consiste em um AccessKey ID e um AccessKey secret.

3. Ordene todos os cabeçalhos de requisição HTTP recuperados em ordem lexicográfica pelo nome do cabeçalho.

4. Remova quaisquer espaços em branco antes e depois dos dois pontos que separam o nome e o valor do cabeçalho. Por exemplo, converta x-oss-meta-name: TaoBao para x-oss-meta-name:TaoBao.

5. Concatene os cabeçalhos processados. Separe cada cabeçalho com um caractere de nova linha (\n) para criar a string CanonicalizedOSSHeaders.

Como construir CanonicalizedResource

O recurso alvo do OSS que você deseja acessar em uma requisição é conhecido como recurso canônico. Para construir a string CanonicalizedResource, siga estas regras:

• Se o recurso incluir um bucket e um objeto, defina CanonicalizedResource como /BucketName/ObjectName.

• Caso o recurso inclua apenas um bucket, defina CanonicalizedResource como /BucketName/.

• Quando o recurso não incluir bucket nem objeto, defina CanonicalizedResource como uma barra (/).

• Se a requisição incluir sub-recursos, ordene todos eles lexicograficamente e una-os com um e comercial (&) para criar uma string de sub-recurso. Anexe um ponto de interrogação (?) e a string de sub-recurso ao final da string CanonicalizedResource. A string CanonicalizedResource resultante terá o formato /BucketName/ObjectName?acl&uploadId=UploadId.

  O OSS oferece suporte aos quatro tipos de sub-recursos a seguir:

  • Identificadores de recursos, como acl, uploads, location, cors, logging, website, referer, lifecycle, delete, append, tagging, objectMeta, uploadId, partNumber, security-token, position, img, style, styleName, replication, replicationProgress, replicationLocation, cname, bucketInfo, comp, qos, live, status, vod, startTime, endTime, symlink, x-oss-process, callback e callback-var. Para mais informações, consulte Bucket operations e Object operations.

    Importante

    Os identificadores de recursos diferenciam maiúsculas de minúsculas.

  • Campos de cabeçalho de resposta, como response-content-language, response-expires, response-cache-control, response-content-disposition e response-content-encoding. Para mais informações, consulte GetObject.

  • Métodos de processamento de imagens, como x-oss-process. Para mais informações, consulte Image processing.

  • Campos de controle de acesso que começam com x-oss-ac-*, como x-oss-ac-source-ip, x-oss-ac-subnet-mask, x-oss-ac-vpc-id e x-oss-ac-forward-allow. Para mais informações, consulte Signature version 1.

    Nota

    Após gerar uma assinatura usando uma string CanonicalizedResource que contenha o parâmetro x-oss-ac-source-ip, remova x-oss-ac-source-ip dos parâmetros de consulta da requisição para proteger o endereço IP.

Regras de cálculo de assinatura

• A string a ser assinada deve estar no formato UTF-8. Uma string contendo caracteres chineses precisa ser codificada em UTF-8 antes de ser usada com o AccessKeySecret para calcular a assinatura.

• O cálculo da assinatura usa o método HMAC-SHA1 conforme definido em RFC 2104. A chave para o cálculo é o seu AccessKey secret.

• Content-Type e Content-MD5 não são obrigatórios em uma requisição. Se esses cabeçalhos estiverem ausentes em uma requisição que exige verificação de assinatura, ainda assim inclua um caractere de nova linha (\n) para cada um deles na string a ser assinada.

• Apenas cabeçalhos HTTP não padrão iniciados com x-oss- devem ser incluídos na string a ser assinada. Por exemplo, o cabeçalho x-oss-meta-magic nos exemplos de assinatura deve ser incluído. O OSS ignora outros cabeçalhos HTTP não padrão.

  Nota

  Cabeçalhos iniciados com x-oss- devem ser processados de acordo com as seguintes regras antes da verificação da assinatura:

  • Os nomes dos cabeçalhos devem estar em minúsculas.

  • Os cabeçalhos devem ser ordenados lexicograficamente por nome.

  • Não deve haver espaço antes ou depois dos dois pontos que separam o nome e o valor do cabeçalho.

  • Cada cabeçalho deve ser separado por um caractere de nova linha (\n). Se nenhum desses cabeçalhos for especificado, a string CanonicalizedOSSHeaders estará vazia.

Como calcular Content-MD5

Esta seção usa o conteúdo de mensagem "0123456789" como exemplo para demonstrar as formas correta e incorreta de calcular o valor Content-MD5.

• Cálculo correto

  1. Primeiro, calcule o hash MD5, que é um array binário de 128 bits.

  2. Codifique o array binário em Base64, e não a string hexadecimal de 32 caracteres.

  O exemplo a seguir usa Python:

  >>> import base64,hashlib
  >>> hash = hashlib.md5()
  >>> hash.update("0123456789")   # In Python 3, change this to hash.update(b"0123456789").
  >>> base64.b64encode(hash.digest())
  'eB5e********************'

  O método hash.digest() retorna o array binário de 128 bits.

  >>> hash.digest()
  'x\x1e^$]i\xb5f\x97\x9b\x86\xe2\x8d#\xf2\xc7'

• Exemplo de cálculo incorreto

  Nota

  Um erro comum é codificar diretamente em Base64 a string hexadecimal de 32 caracteres.

  # The hash.hexdigest() method calculates the visible 32-character hexadecimal string.
  >>> hash.hexdigest()
  '781e****************************'
  # The result of Base64-encoding the incorrect MD5 hash.
  >>> base64.b64encode(hash.hexdigest())
  'Nzgx****************************************'