Solicitações canônicas

As solicitações canônicas definem os elementos de uma solicitação que devem ser incluídos pelo usuário ao enviar solicitações autenticadas por assinatura V4, como URLs assinados, para o Cloud Storage.

Visão geral

Uma solicitação canônica é uma string que representa uma solicitação HTTP específica para o Cloud Storage. Essa solicitação é usada junto com uma chave criptográfica, como a chave RSA, para criar uma assinatura que será incluída como forma de autenticação na solicitação principal.

Uma solicitação canônica inclui informações como: verbo HTTP, parâmetros de string de consulta e cabeçalhos. Esses elementos devem ser usados na solicitação principal, assim como o objeto, o bucket ou outro recurso a ser solicitado.

A solicitação em questão garante que o Cloud Storage consiga calcular a mesma assinatura calculada por você ao receber a solicitação. Se não houver correspondência entre sua versão e a versão calculada pelo Cloud Storage, haverá falha na solicitação.

Estrutura

A estrutura das solicitações canônicas tem os seguintes componentes (incluindo o uso de novas linhas entre cada elemento):

HTTP_VERB
PATH_TO_RESOURCE
CANONICAL_QUERY_STRING
CANONICAL_HEADERS

SIGNED_HEADERS
PAYLOAD

Verbos HTTP

As solicitações assinadas podem usar os seguintes verbos HTTP, que devem ser especificados como parte da solicitação canônica:

  • DELETE
  • GET
  • HEAD
  • POST1
  • PUT

1 Os URLs assinados só podem ser usados para solicitações POST que iniciam um upload recuperável. Para mais informações, consulte Como usar URLs assinados com uploads retomáveis.

Caminho do recurso

Nas solicitações canônicas, encontramos o caminho para o recurso ao qual a solicitação se aplica. Esse caminho é tudo o que segue o nome do host, mas precede qualquer string de consulta.

Se o URL do Cloud Storage é https://storage.googleapis.com/example-bucket/cat-pics/tabby.jpeg, por exemplo, então o caminho para o recurso é /example-bucket/cat-pics/tabby.jpeg.

Caso utilize um URL alternativo do Cloud Storage, como https://example-bucket.storage.googleapis.com/cat-pics/tabby.jpeg, então o caminho para o recurso será /cat-pics/tabby.jpeg.

Para conhecer outros endpoints de URL que podem ser usados com URLs assinados, consulte Endpoints de solicitação da API XML.

Ao definir o caminho do recurso, codifique por cento os seguintes caracteres reservados: ?=!#$&'()*+,:;@[]". Qualquer outra codificação de cento usada no URL também precisa ser incluída no caminho do recurso.

String de consulta canônica

As solicitações canônicas especificam cada parâmetro de string de consulta que será incluído em qualquer solicitação assinada que usar a assinatura relevante, com exceção do parâmetro de string de consulta X-Goog-Signature ou X-Amz-Signature. A string de consulta especificada na solicitação canônica é chamada de string de consulta canônica.

A string de consulta é tudo o que vem após o ponto de interrogação (?) no final do caminho do recurso.

Exemplo: se o URL do Cloud Storage é https://storage.googleapis.com/example-bucket/cat-pics/tabby.jpeg?generation=1360887697105000&userProject=my-project, então a string de consulta é generation=1360887697105000&userProject=my-project.

Ao construir a string de consulta canônica:

  • Classifique os parâmetros na string de consulta por nome usando uma classificação lexicográfica por pontuação de código.

  • Separe cada parâmetro na string de consulta com o símbolo &.

  • Se a string de consulta canônica está vazia, essa parte da solicitação canônica é simplesmente uma nova linha (\n).

Parâmetros obrigatórios da string de consulta

A maioria dos parâmetros de string de consulta é adicionada conforme necessário. Entretanto, os parâmetros a seguir devem ser incluídos em sua solicitação canônica se você pretende usá-la para criar um URL assinado:

  • X-Goog-Algorithm: esse é o algoritmo que você usará para assinar o URL. Os valores válidos são: GOOG4-RSA-SHA256 e GOOG4-HMAC-SHA256.
  • X-Goog-Credential: essa é a credencial que você usará para assinar o URL. Ela consiste em um autorizador e um escopo de credencial fornecidos no formato AUTHORIZER%2FCREDENTIAL_SCOPE. O autorizador pode ser um nome de conta de serviço ou um ID de acesso de chave HMAC.
  • X-Goog-Date: a data e a hora em que o URL assinado se torna utilizável, no formato básico ISO 8601 YYYYMMDD'T'HHMMSS'Z'.
  • X-Goog-Expires: o ciclo de vida do URL assinado, medido em segundos a partir de X-Goog-Date. O maior tempo de expiração é de 604800 segundos (sete dias).
  • X-Goog-SignedHeaders: uma lista, separada por ponto e vírgula, de nomes de cabeçalhos definidos na solicitação canônica. Também são conhecidos como cabeçalhos assinados. Um dos nomes de cabeçalho deve ser: host.

Posteriormente, esses parâmetros de string de consulta devem ser usados no próprio URL assinado, junto com o parâmetro de string de consulta X-Goog-Signature, que contém a assinatura de autenticação da solicitação.

Cabeçalhos canônicos

As solicitações canônicas incluem todos os cabeçalhos que devem ser incluídos posteriormente nas solicitações assinadas que usam a assinatura relevante. Entretanto, talvez essas solicitações assinadas incluam outros cabeçalhos que não foram especificados na solicitação canônica, exceto conforme indicado em cabeçalhos obrigatórios. Chamamos os cabeçalhos especificados na solicitação canônica de cabeçalhos canônicos.

Os cabeçalhos canônicos podem incluir cabeçalhos personalizados e cabeçalhos de extensão iniciados com x-goog-.

Ao especificar cabeçalhos canônicos, tenha isto em mente:

  • Escreva todos os nomes de cabeçalho em minúsculas.
  • Classifique todos os cabeçalhos por nome usando uma classificação lexicográfica por pontuação de código.
  • Separe cada cabeçalho com uma nova linha (\n).
  • Elimine nomes de cabeçalho duplicados criando um nome de cabeçalho com uma lista de valores separados por vírgula. Verifique se não há espaços em branco entre os valores e se a ordem da lista separada por vírgulas corresponde à ordem em que os cabeçalhos aparecem na sua solicitação. Para mais informações, consulte a seção 3.2 do RFC 7230 (em inglês).
  • Substitua qualquer espaço em branco ou novas linhas (CRLF ou LF) por um único espaço. Para mais informações sobre espaços em branco, consulte a seção 3.2.4 da RFC 7230 (em inglês).

  • Remova qualquer espaço em branco em volta do sinal de dois pontos que aparece após o nome do cabeçalho.

    Ao usar o cabeçalho personalizado x-goog-acl: private sem remover o espaço após os dois-pontos, por exemplo, retorna o erro 403 Forbidden porque a assinatura da solicitação que você calcula não corresponde à assinatura calculada pelo Cloud Storage.

Exemplo

Se você tivesse o seguinte conjunto de cabeçalhos:

host: storage.googleapis.com
content-type: text/plain
x-goog-meta-reviewer: jane
x-goog-meta-reviewer: john

A construção dos cabeçalhos canônicos na solicitação canônica seria esta:

content-type:text/plain
host:storage.googleapis.com
x-goog-meta-reviewer:jane,john

Cabeçalhos canônicos obrigatórios

A maioria dos cabeçalhos, como content-type, é adicionada conforme necessário, mas os cabeçalhos a seguir precisam ser sempre definidos nos cabeçalhos canônicos se você pretende usá-los na solicitação assinada:

  • host: é o URI usado para acessar o Cloud Storage.
  • Cabeçalhos prefixados com x-goog-. O único desses cabeçalhos que é opcional para incluir como canônico é x-goog-content-sha256.
  • Cabeçalhos prefixados com x-amz-. O único desses cabeçalhos que é opcional para incluir como um canônico é x-amz-content-sha256.

Cabeçalhos assinados

A parte do nome de um cabeçalho canônico é o cabeçalho assinado.

Para criar a lista de cabeçalhos assinados, deixe todos os nomes de cabeçalho em letras minúsculas, classifique-os por código de caractere e separe cada um usando ponto e vírgula (;).

Exemplo

Se você tivesse o seguinte conjunto de cabeçalhos:

host: storage.googleapis.com
content-type: text/plain
x-goog-meta-reviewer: jane
x-goog-meta-reviewer: john

A construção dos cabeçalhos assinados na solicitação canônica seria esta:

content-type;host;x-goog-meta-reviewer

Payload

  • Caso sua solicitação canônica seja usada para criar um URL assinado, o valor deverá ser simplesmente a string UNSIGNED-PAYLOAD.

  • Se a solicitação canônica for usada como parte de uma solicitação que use um cabeçalho Authorization:

    • Use UNSIGNED-PAYLOAD se quiser permitir payloads arbitrários como parte da solicitação. Ao iniciar uma solicitação de upload retomável, também recomendamos usar UNSIGNED-PAYLOAD. Qualquer valor sha256 incluído é ignorado para uploads retomáveis.

    • Se você quiser permitir apenas um payload específico, esse valor deverá ser um hash SHA-256 codificado em minúsculas do payload desejado. Para exigir um payload vazio, use uma string vazia como entrada para a função de hash. Veja um exemplo de payload em hash (nesse caso, um payload vazio):

      e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Exemplo

Veja o exemplo de uma solicitação canônica formada corretamente, com novas linhas sendo mostradas, de fato, como novas linhas, não como \n:

GET
/example-bucket/tabby.jpeg

host:storage.googleapis.com
x-amz-content-sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-amz-date:20190301T190859Z

host;x-amz-content-sha256;x-amz-date
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

A seguir