Peticiones canónicas

Las solicitudes canónicas definen los elementos de una solicitud que un usuario debe incluir cuando envíe solicitudes V4 autenticadas con firma, como URL firmadas, a Cloud Storage.

Descripción general

Una solicitud canónica es una string que representa una solicitud HTTP específica a Cloud Storage. Una solicitud canónica se usa junto con una clave criptográfica, como una clave RSA, para crear una firma que se incluya en la solicitud real como autenticación.

Una solicitud canónica incluye información como el verbo HTTP, los parámetros de string de consulta y los encabezados que se espera usar en la solicitud real, así como el objeto, el bucket o algún otro recurso que se solicitará.

Una solicitud canónica garantiza que, cuando Cloud Storage reciba la solicitud, pueda determinar la misma firma que tú. Si tu versión y la que determina Cloud Storage no coinciden, la solicitud falla.

Estructura

Las solicitudes canónicas tienen la siguiente estructura, incluido el uso de líneas nuevas entre cada elemento:

HTTP_VERB
PATH_TO_RESOURCE
CANONICAL_QUERY_STRING
CANONICAL_HEADERS

SIGNED_HEADERS
PAYLOAD

Verbos HTTP

Las solicitudes firmadas pueden usar los siguientes verbos HTTP, que se deben especificar como parte de la solicitud canónica:

  • DELETE
  • GET
  • HEAD
  • POST1
  • PUT

1 Las URL firmadas solo se pueden usar para solicitudes POST que inician una carga reanudable. Consulta Usa URL firmadas con cargas reanudables para obtener más información.

Ruta de acceso al recurso

Las solicitudes canónicas incluyen la ruta del recurso al que la solicitud aplica. La ruta al recurso se encuentra entre el nombre del host y una cadena de consulta.

Por ejemplo, si la URL de Cloud Storage es https://storage.googleapis.com/example-bucket/cat-pics/tabby.jpeg, entonces la ruta al recurso es /example-bucket/cat-pics/tabby.jpeg.

Si usas una URL de Cloud Storage alternativa, como https://example-bucket.storage.googleapis.com/cat-pics/tabby.jpeg, la ruta al recurso es /cat-pics/tabby.jpeg.

Para conocer los extremos de URL adicionales que se pueden usar con URL firmadas, consulta extremos de solicitud a la API de XML.

Cuando defines la ruta de acceso del recurso, debes incluir en un código por ciento los siguientes caracteres reservados: ?=!#$&'()*+,:;@[]" Cualquier otro código por ciento que se use en la URL también debe incluirse en la ruta de acceso del recurso.

Cadena de consulta canónica

Las solicitudes canónicas incluyen cualquier parámetro de cadena de consulta que se debe incluir luego en las solicitudes firmadas que usan la firma correspondiente. Sin embargo, esas solicitudes firmadas pueden incluir parámetros de cadena de consulta adicionales que no se especificaron en la solicitud canónica. La cadena de consulta especificada en la solicitud canónica se denomina cadena de consulta canónica.

La cadena de consulta es todo lo que le sigue al signo de interrogación (?) al final de la ruta del recurso.

Por ejemplo, si la URL de Cloud Storage es https://storage.googleapis.com/example-bucket/cat-pics/tabby.jpeg?generation=1360887697105000&userProject=my-project, la cadena de consulta es generation=1360887697105000&userProject=my-project.

Cuando se construye la string de consulta canónica, se deben cumplir las siguientes condiciones:

  • Los parámetros en la string de consulta deben ordenarse por nombre mediante un orden lexicográfico por valor de punto de código.

  • Cada parámetro en la cadena de consulta debe separarse con &.

  • Si la string de consulta canónica está vacía, esta parte de la solicitud canónica general es una línea nueva (\n).

Parámetros de string de consulta obligatorios

La mayoría de los parámetros de string de consulta se agregan según sea necesario, pero los siguientes deben incluirse en la solicitud canónica si deseas usarla para crear una URL firmada:

  • X-Goog-Algorithm: El algoritmo que usarás para firmar la URL. Los valores válidos son GOOG4-RSA-SHA256 y GOOG4-HMAC-SHA256.
  • X-Goog-Credential: Las credenciales que usarás para firmar la URL. Las credenciales consisten en un autorizador y un alcance de credencial que se brindan en el formato: AUTHORIZER%2FCREDENTIAL_SCOPE. El autorizador puede ser un nombre de cuenta de servicio o un ID de acceso de clave HMAC.
  • X-Goog-Date: La fecha y la hora a partir de las que se puede usar la URL firmada, en el formato básico ISO 8601 YYYYMMDD'T'HHMMSS'Z'.
  • X-Goog-Expires: La vida útil de la URL firmada, medida en segundos desde X-Goog-Date. El valor de vencimiento más largo es 604800 segundos (7 días).
  • X-Goog-SignedHeaders: una lista separada por punto y coma de los nombres de los encabezados definidos en la solicitud canónica. También se los conoce como encabezados firmados. host debe ser uno de los nombres de los encabezados.

Estos parámetros de string de consulta se deben usar luego en la URL firmada, junto con el parámetro de string de consulta X-Goog-Signature, que contiene la firma que autentica la solicitud.

Encabezados canónicos

Las solicitudes canónicas incluyen cualquier encabezado que debe incluirse luego en las solicitudes firmadas que usan la firma correspondiente. Sin embargo, esas solicitudes firmadas pueden incluir encabezados adicionales que no se especificaron en la solicitud canónica, excepto como se indica en la sección sobre encabezados obligatorios. Los encabezados especificados en la solicitud canónica se denominan encabezados canónicos.

Los encabezados canónicos pueden incluir encabezados personalizados, así como encabezados de extensión que comienzan con x-goog-.

Cuando especifiques encabezados canónicos, ten en cuenta lo siguiente:

  • Escribe todos los nombres de encabezados en minúscula.
  • Ordena todos los encabezados por nombre mediante un orden lexicográfico por valor de punto de código.
  • Separa cada encabezado con una línea nueva (\n).
  • Borra los nombres de encabezados duplicados y crea un nombre de encabezado con una lista de valores separados por comas. Asegúrate de que no haya espacios en blanco entre los valores y de que el orden de la lista separada por comas coincida con el de los encabezados de tu solicitud. Para obtener más información, consulta la sección 3.2 de RFC 7230.
  • Reemplaza cualquier espacio en blanco plegable o salto de línea (CRLF o LF) con un solo espacio. Para obtener más información sobre el plegado de espacios en blanco, consulta RFC 7230, sección 3.2.4.

  • Quita los espacios en blanco alrededor de los dos puntos que aparecen después del nombre del encabezado.

    Por ejemplo, si usas el encabezado predeterminado x-goog-acl: private sin quitar el espacio luego de los dos puntos, se mostrará el error 403 Forbidden, debido a que la firma de solicitud que tú determinas no coincide con la que determina Cloud Storage.

Ejemplo

Si tienes el siguiente conjunto de encabezados:

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

La construcción de los encabezados canónicos en la solicitud canónica sería:

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

Encabezados canónicos obligatorios

La mayoría de los encabezados, como content-type, se agregan según sea necesario, pero los siguientes siempre deben definirse en los encabezados canónicos si pretendes usarlos en la solicitud firmada:

  • host: El URI que se usa para acceder a Cloud Storage.
  • Encabezados con el prefijo x-goog-. El único encabezado de este tipo que es opcional para incluir como un encabezado canónico es x-goog-content-sha256.
  • Encabezados con el prefijo x-amz-. El único encabezado de este tipo que es opcional para incluir como un encabezado canónico es x-amz-content-sha256.

Encabezados firmados

Un encabezado firmado es la parte del nombre de un encabezado canónico.

Para crear la lista de encabezados firmados, pasa todos los nombres de encabezados a minúsculas, ordénalos por código de carácter y usa punto y coma (;) para separarlos.

Ejemplo

Si tienes el siguiente conjunto de encabezados:

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

La construcción de los encabezados firmados en la solicitud canónica será la siguiente:

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

Carga útil

  • Si la solicitud canónica se usará para crear una URL firmada, este valor debe ser solo la string UNSIGNED-PAYLOAD.

  • Si la solicitud canónica se usará como parte de una solicitud que use un encabezado Authorization, haz lo siguiente:

    • Usa UNSIGNED-PAYLOAD si quieres permitir cargas útiles arbitrarias en la solicitud.

    • Si deseas permitir solo una carga útil específica, este valor debe ser un hash SHA-256, en minúscula y con codificación hexadecimal de la carga útil deseada. Para requerir una carga útil vacía, usa una string vacía como entrada de la función de hash. Un ejemplo de una carga útil con hash (en este caso, una carga útil vacía) es el siguiente:

      e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Ejemplo

El siguiente es un ejemplo de una solicitud canónica formada correctamente, con líneas nuevas que se muestran como líneas nuevas reales y no \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

¿Qué sigue?