Solicitudes canónicas

Las solicitudes canónicas definen los elementos que debe incluir un usuario al enviar solicitudes autenticadas con la firma V4, como las URLs firmadas, a Cloud Storage.

Información general

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

Una solicitud canónica incluye información como el verbo HTTP, los parámetros de la cadena de consulta y los encabezados que se espera que se usen en la solicitud real, así como el objeto, el contenedor u otro recurso que se va a solicitar.

Una solicitud canónica asegura que, cuando Cloud Storage recibe la solicitud, puede calcular la misma firma que has calculado tú. Si la versión y la versión calculada por Cloud Storage no coinciden, la solicitud falla.

Estructura

Las solicitudes canónicas tienen la siguiente estructura, que incluye el uso de saltos de línea 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 deben especificarse como parte de la solicitud canónica:

  • DELETE
  • GET
  • HEAD
  • POST1
  • PUT

1 Las URLs firmadas solo se pueden usar en solicitudes POST que inicien una subida reanudable. Para obtener más información, consulta Usar URLs firmadas con subidas reanudables.

Ruta de recurso

Las solicitudes canónicas incluyen la ruta al recurso al que se aplica la solicitud. La ruta al recurso es todo lo que va después del nombre de host, pero antes de cualquier cadena de consulta.

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

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

Para ver otros endpoints de URL que se pueden usar con URLs firmadas, consulta Endpoints de solicitudes de la API XML.

Al definir la ruta del recurso, debe codificar con porcentajes los siguientes caracteres reservados: ?=!#$&'()*+,:;@[]". También debe incluir en la ruta del recurso cualquier otra codificación con porcentajes que se use en la URL.

Cadena de consulta canónica

Las solicitudes canónicas especifican cada parámetro de cadena de consulta que se incluirá posteriormente en cualquier solicitud firmada que utilice la firma correspondiente, a excepción del parámetro de cadena de consulta X-Goog-Signature o X-Amz-Signature. 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 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.

Al crear la cadena de consulta canónica:

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

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

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

Parámetros de cadena de consulta obligatorios

La mayoría de los parámetros de cadena de consulta se añaden según sea necesario, pero los siguientes deben incluirse en la solicitud canónica si quieres 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 constan de un autorizador y un ámbito de credencial, que se indica con el siguiente 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: fecha y hora en las que se puede usar la URL firmada, en el formato básico ISO 8601 YYYYMMDD'T'HHMMSS'Z'.
  • X-Goog-Expires: tiempo de validez de la URL firmada, medido en segundos a partir de X-Goog-Date. El valor de caducidad más largo es de 604.800 segundos (7 días).
  • X-Goog-SignedHeaders: lista separada por punto y coma de los nombres de los encabezados definidos en la solicitud canónica. También se conocen como encabezados firmados. host debe ser uno de los nombres de encabezado.

Estos parámetros de cadena de consulta deben usarse posteriormente en la URL firmada, junto con el parámetro de cadena de consulta X-Goog-Signature, que contiene la firma que autentica la solicitud.

Encabezados canónicos

Las solicitudes canónicas incluyen los encabezados que deben incluirse posteriormente en las solicitudes firmadas que usen la firma correspondiente. Sin embargo, estas solicitudes firmadas pueden incluir encabezados adicionales que no se hayan especificado en la solicitud canónica, excepto los que se indican en 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 empiezan por x-goog-.

Cuando especifique encabezados canónicos, tenga en cuenta lo siguiente:

  • Escribe todos los nombres de los encabezados en minúsculas.
  • Ordena todos los encabezados por nombre de encabezado mediante una ordenación lexicográfica por valor de punto de código.
  • Separe cada encabezado con un salto de línea (\n).
  • Elimina los nombres de encabezado duplicados creando un nombre de encabezado con una lista de valores separados por comas. Asegúrese de que no haya espacios en blanco entre los valores y de que el orden de la lista separada por comas coincida con el orden en el que aparecen los encabezados en su solicitud. Para obtener más información, consulta la sección 3.2 de RFC 7230.
  • Cambia cualquier espacio en blanco o línea nueva plegable (CRLF o LF) por un espacio sencillo. Para obtener más información sobre el espacio en blanco de plegado, consulta la sección 3.2.4 de RFC 7230.

  • Elimina todos los espacios en blanco que rodeen los dos puntos que aparecen después del nombre del encabezado.

    Por ejemplo, si usa el encabezado personalizado x-goog-acl: private sin quitar el espacio después de los dos puntos, se devuelve un error 403 Forbidden, porque la firma de la solicitud que calcula no coincide con la que calcula 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 creación de los encabezados canónicos en la solicitud canónica sería la siguiente:

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 añaden según sea necesario, pero los siguientes encabezados siempre deben definirse en los encabezados canónicos si tienes intención de 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 se puede incluir como encabezado canónico es x-goog-content-sha256.
  • Encabezados con el prefijo x-amz-. El único encabezado de este tipo que se puede incluir como 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, convierte todos los nombres de encabezado a minúsculas, ordénalos por código de carácter y usa un punto y coma (;) para separar cada uno.

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 creación de los encabezados firmados en la solicitud canónica sería la siguiente:

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

Carga útil

  • Si tu solicitud canónica se va a usar para crear una URL firmada, este valor debe ser la cadena UNSIGNED-PAYLOAD.

  • Si tu solicitud canónica se va a usar para crear una firma que se utilizará en un encabezado Authorization:

    • Usa UNSIGNED-PAYLOAD si quieres permitir cargas útiles arbitrarias como parte de la solicitud.

    • Usa UNSIGNED-PAYLOAD si la solicitud va a iniciar una subida reanudable, ya que el encabezado x-goog-content-sha256 se ignora en las subidas reanudables.

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

      e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Ejemplo

A continuación, se muestra un ejemplo de solicitud canónica con el formato correcto, donde los saltos de línea se muestran como saltos de línea reales y no 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

Siguientes pasos