Solicitudes 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. Si envías URL firmadas de V2, consulta el proceso de firma de V2

Descripción general

Una solicitud canónica es una string que representa una solicitud HTTP específica a Cloud Storage. Una solicitud canónicas 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 cadena de consulta y los encabezados que se espera usar en la solicitud real, así como el objeto, el depósito o algún otro recurso que se solicite.

Una solicitud canónica garantiza que cuando Cloud Storage reciba la solicitud, puede 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

1Las URL firmadas no admiten POST solicitudes, excepto cuando se trabaja con cargas reanudables.

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 del recurso, debes incluir en un código por ciento los siguientes caracteres reservados: ?=!#$&'()*+,:;@[]." Cualquier otro código por ciento usado en la URL también debe incluirse en la ruta 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 y usa 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 cadena de consulta canónica:

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

  • Cada parámetro en 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 simplemente una línea nueva (/n).

Parámetros de string de consulta obligatorios

La mayoría de los parámetros de cadena 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]%2F[CREDENTIAL_SCOPE]. El autorizador puede ser un nombre de cuenta de servicio o una clave de acceso HMAC.
  • X-Goog-Date: la fecha y hora actuales, en el formato básico [ISO 8601][8] 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 cadena de consulta se deben usar luego 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 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 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úsculas.
  • 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).
  • A fin de eliminar los nombres de encabezado duplicados, crea un nombre de encabezado con una lista de valores separada 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 Google.

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 los encabezados de extensión y content-type, se agregan según sea necesario, pero el siguiente encabezado es obligatorio en todas las solicitudes firmadas:

  • host: el URI que se usa para acceder a Cloud Storage.

Además, los siguientes encabezados no se pueden usar en solicitudes que usan la firma a menos que se definan de manera explícita como encabezados canónicos.

  • x-goog-project-id
  • x-goog-copy-source
  • x-goog-metadata-directive
  • x-amz-copy-source
  • x-amz-metadata-directive

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á:

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

Carga útil

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

  • Si tu solicitud canónica se usará como parte de una solicitud que usa un encabezado Authorization, este valor debe ser una carga útil de solicitud con hash SHA-256 codificada en hexadecimal. Si la carga útil está vacía, usa una string vacía como entrada para la función hash. Un ejemplo de una carga útil con hash (en este caso, una carga útil vacía) es:

    3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

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

Próximos pasos

¿Te sirvió esta página? Envíanos tu opinión:

Enviar comentarios sobre…

¿Necesitas ayuda? Visita nuestra página de asistencia.