Include a V4 signature in the Authorization header (recommended) - Object Storage Service

Cuando envíe solicitudes a OSS, debe incluir un encabezado de solicitud Authorization que contenga una firma V4 para garantizar que la autenticación sea exitosa. Se recomienda utilizar primero el SDK proporcionado por OSS para enviar las solicitudes, ya que este integra el algoritmo de firma V4. Consulte esta documentación para implementar manualmente el algoritmo de firma V4 únicamente cuando no sea posible usar el SDK.

Usar los SDK de OSS para implementar firmas V4 automáticamente

Si necesita implementar el algoritmo de firma V4, consulte la implementación de dicha firma en los SDK de OSS.

SDK	Implementación
Java	OSSV4Signer.java
Python	v4.py
Go	v4.go
JavaScript	client.js
PHP	SignerV4.php
C#	SignerV4.cs
Android	OSSV4Signer.java
Swift	SignerV4.swift
Objective-C	OSSV4Signer.m
C++	SignerV4.cc
C	oss_auth.c

Encabezados de solicitud de autorización

Cuando envíe una solicitud a OSS, debe implementar la firma en el encabezado Authorization para verificar la solicitud.

A continuación se muestra la sintaxis del encabezado Authorization:

Authorization: OSS4-HMAC-SHA256 Credential=<AccessKeyId>/<SignDate>/<SignRegion>/oss/aliyun_v4_request, AdditionalHeaders=<AdditionalHeadersVal>, Signature=<SignatureVal>

A continuación se describe el encabezado Authorization:

Componente	Descripción
OSS4-HMAC-SHA256	Especifica el algoritmo utilizado para calcular la firma. Esta cadena indica la versión de la firma y el algoritmo de firmado (HMAC-SHA256). El valor OSS4-HMAC-SHA256 es obligatorio cuando se usan firmas V4 para la autenticación.
Credential	Indica el ID de AccessKey y el alcance, que incluye la fecha, la región y el servicio en la nube utilizados para calcular la firma. Este campo es obligatorio cuando se usan firmas V4 para la autenticación. La sintaxis es la siguiente: `<AccessKeyId>/<SignDate>/<SignRegion>/oss/aliyun_v4_request` Donde: `AccessKeyId`: su ID de AccessKey, un identificador único que sirve para comprobar la identidad del solicitante. `SignDate`: la fecha de la firma con el formato YYYYMMDD. `SignRegion`: la region ID utilizada para la solicitud. Por ejemplo, cn-hangzhou. `oss`: una cadena fija que identifica al servicio solicitado como Object Storage Service (OSS) de Alibaba Cloud. `aliyun_v4_request`: una cadena fija que establece la versión de la firma como V4.
AdditionalHeaders	Especifique los encabezados de solicitud opcionales que se incluyen en el cálculo de la firma (no es necesario especificar los encabezados obligatorios que deben incluirse en dicho cálculo). Este campo contiene únicamente nombres de encabezados en minúsculas, ordenados lexicográficamente y separados por punto y coma (;). El ejemplo es el siguiente: `content-disposition;content-length`
Signature	La firma calculada. Este campo es obligatorio cuando se usan firmas V4 para la autenticación. El siguiente código de ejemplo muestra un valor de firma de 256 bits representado con 64 dígitos hexadecimales en minúsculas: `3938**********************************dcdc`

Cálculo de la firma

Tras recibir una solicitud, OSS calcula la firma y la compara con la del encabezado de solicitud Authorization. Si coinciden, la solicitud se procesa correctamente. De lo contrario, la solicitud falla.

Proceso de cálculo de la firma

La siguiente figura muestra el proceso de cálculo de la firma:

El proceso de cálculo de la firma consta de los tres pasos siguientes:

Construir una solicitud canónica: formatee la solicitud según las especificaciones de firma de OSS para generar una solicitud canónica.
Construir una cadena para firmar: concatene la solicitud canónica para obtener la cadena para firmar.
Calcular la firma: aplique varias operaciones de hash al AccessKey Secret para generar una clave derivada. Después, use esta clave derivada para calcular la cadena para firmar y obtener la firma final. Al aplicar múltiples operaciones HMAC-SHA256 al AccessKey Secret, se genera una clave derivada que permite calcular el hash HMAC-SHA256 de la cadena para firmar, lo cual da como resultado la firma final.

1. Construir una solicitud canónica

La sintaxis de una solicitud canónica es la siguiente:

HTTP Verb + "\n" +
Canonical URI + "\n" +
Canonical Query String + "\n" +
Canonical Headers + "\n" +
Additional Headers + "\n" +
Hashed PayLoad

En la siguiente tabla se describen los parámetros de una solicitud canónica:

Parámetro	Descripción
HTTP Verb	El método de solicitud HTTP, como PUT, GET, POST, HEAD, DELETE y OPTIONS.
Canonical URI	La ruta del recurso codificada en URI. La ruta del recurso no incluye la cadena de consulta y no es necesario codificar las barras diagonales (`/`). Si el destino de la solicitud es OSS, la ruta del recurso es `/` y la ruta del recurso codificada en URI es `UriEncode("/")`. Si el destino de la solicitud es un bucket, la ruta del recurso es `/examplebucket/` y la ruta del recurso codificada en URI es `UriEncode("/examplebucket/")`. Si el destino de la solicitud es un objeto dentro de un bucket, la ruta del recurso es `/examplebucket/exampleobject` y la ruta del recurso codificada en URI es `UriEncode("/examplebucket/exampleobject")`.
Canonical Query String	Los parámetros de consulta codificados en URI y ordenados lexicográficamente. Si los parámetros de consulta incluyen nombres y valores, codifique en URI el nombre y el valor de cada parámetro por separado. Luego, ordene los parámetros lexicográficamente según sus nombres codificados. Tenga en cuenta que la clasificación se realiza después de la codificación. Use `=` para unir el nombre y el valor codificados, y `&` para concatenar los distintos parámetros. Parámetros de consulta: `prefix=somePrefix&marker=someMarker&max-keys=20` Parámetros de consulta canónicos: `UriEncode("marker")+"="+UriEncode("someMarker")+"&"+UriEncode("max-keys")+"="+UriEncode("20")+"&"+UriEncode("prefix")+"="+UriEncode("somePrefix")` Si el parámetro de consulta contiene únicamente el nombre, aplique la codificación URI solo al nombre del parámetro. Parámetro de consulta: `?acl` Parámetro de consulta canónico: `UriEncode("acl")` Si no hay parámetros de consulta, es decir, si el URI de la solicitud no contiene un signo `?`, establezca la cadena de consulta canónica como una cadena vacía (`""`).
Canonical Headers	La lista de encabezados de solicitud. Los encabezados de solicitud se dividen en las tres categorías siguientes: Encabezados que deben existir en la solicitud e incluirse en el cálculo de la firma: `x-oss-content-sha256`: solo es compatible con UNSIGNED-PAYLOAD. Encabezados que deben incluirse en el cálculo de la firma si están presentes en la solicitud: `Content-Type` `Content-MD5` `x-oss-*`: otros encabezados de solicitud que comienzan con `x-oss-`. Por ejemplo, al acceder mediante el STS AK, el SecurityToken se define a través de `x-oss-security-token:security-token`. Asimismo, la hora de la solicitud se define mediante `x-oss-date`, cuya sintaxis debe seguir el formato de hora estándar ISO8601, como `20231203T121212Z`. Encabezados de solicitud opcionales especificados en `AdditionalHeaders`. La sintaxis es la siguiente: `Lowercase(<HeaderName1>) + ":" + Trim(<value>) + "\n" Lowercase(<HeaderName2>) + ":" + Trim(<value>) + "\n" ... Lowercase(<HeaderNameN>) + ":" + Trim(<value>) + "\n"` El siguiente código muestra un ejemplo: `content-disposition:attachment content-length:3 content-md5:ICy5YqxZB1uWSwcVLSNLcA== content-type:text/plain x-oss-content-sha256:UNSIGNED-PAYLOAD x-oss-date:20250328T101048Z`
Additional Headers	Especifica los encabezados de solicitud opcionales que se incluyen en el cálculo de la firma (no es necesario especificar los encabezados obligatorios que deben incluirse en dicho cálculo). Este campo contiene únicamente nombres de encabezados en minúsculas, ordenados lexicográficamente y separados por punto y coma (;), de manera coherente con `AdditionalHeaders`. Especifique los encabezados opcionales que se incluyen en el cálculo de la firma (excluyendo los obligatorios). Solo se admiten nombres de encabezados en minúsculas, ordenados lexicográficamente. Estos se separan con punto y coma (`;`) y deben coincidir con `AdditionalHeaders`. El siguiente código muestra un ejemplo: `content-disposition;content-length`
Hashed PayLoad	La representación hexadecimal del valor de hash SHA256 de la carga útil de la solicitud. Solo es compatible con el valor `UNSIGNED-PAYLOAD`.

2. Construir una cadena para firmar

La sintaxis de la cadena para firmar es la siguiente:

"OSS4-HMAC-SHA256" + "\n" +
TimeStamp + "\n" +
Scope + "\n" +
Hex(SHA256Hash(<CanonicalRequest>))

En la siguiente tabla se describen los parámetros de la cadena para firmar:

Parámetro	Descripción
OSS4-HMAC-SHA256	El algoritmo de hash de la firma. El valor debe ser `OSS4-HMAC-SHA256`.
TimeStamp	La hora UTC actual, cuya sintaxis debe cumplir con el estándar ISO8601, por ejemplo, `20250320T083322Z`.
Scope	El conjunto de parámetros para obtener la clave derivada. Este conjunto especifica la fecha, la región y el servicio. Por lo tanto, la firma calculada con la clave derivada solo es válida para la fecha, la región y el servicio indicados. La sintaxis es la siguiente: `<SignDate>/<SignRegion>/oss/aliyun_v4_request` La descripción es la siguiente: `SignDate`: la fecha incluida en la firma con el formato `YYYYMMDD`. `SignRegion`: la region ID utilizada para la firma, como `cn-hangzhou`. `oss`: el nombre del servicio incluido en la firma, cuyo valor fijo es `oss`. `aliyun_v4_request`: la versión incluida en la firma, cuyo valor fijo es `aliyun_v4_request`.
CanonicalRequest	La solicitud canónica construida.

3. Calcular una firma

El cálculo de una firma implica los dos pasos siguientes:

Calcule el valor de SigningKey.
```
DateKey = HMAC-SHA256("aliyun_v4" + SK, Date);
DateRegionKey = HMAC-SHA256(DateKey, Region);
DateRegionServiceKey = HMAC-SHA256(DateRegionKey, "oss");
SigningKey = HMAC-SHA256(DateRegionServiceKey, "aliyun_v4_request");
```
- SK: el AccessKey Secret incluido en la firma.
- Date: la fecha incluida en la firma con el formato YYYYMMDD, la cual debe coincidir con el valor de SignDate de la cadena para firmar.
- Region: la region ID utilizada para la firma, como cn-hangzhou, que debe coincidir con el valor de SignRegion de la cadena para firmar.
Calcule el valor de Signature mediante SigningKey y la cadena para firmar.
```
Signature = HEX(HMAC-SHA256(SigningKey, StringToSign))
```

Ejemplo de cálculo de firma

El siguiente ejemplo muestra cómo calcular una firma al llamar a la operación PutObject.

Parámetros para el cálculo de la firma

Parámetro	Valor
AccessKeyId	LTAI
AccessKeySecret	yourAccessKeySecret
Timestamp	20250411T064124Z
Bucket	examplebucket
Object	exampleobject
Region	cn-hangzhou

Ejemplo de cálculo de firma

Construya una solicitud canónica.

PUT
/examplebucket/exampleobject

content-disposition:attachment
content-length:3
content-md5:ICy5YqxZB1uWSwcVLSNLcA==
content-type:text/plain
x-oss-content-sha256:UNSIGNED-PAYLOAD
x-oss-date:20250411T064124Z

content-disposition;content-length
UNSIGNED-PAYLOAD

Construya una cadena para firmar.

OSS4-HMAC-SHA256
20250411T064124Z
20250411/cn-hangzhou/oss/aliyun_v4_request
c46d96390bdbc2d739ac9363293ae9d710b14e48081fcb22cd8ad54b63136eca

Calcule la firma.
1. Calcule el SigningKey.
  
  Nota
  Para facilitar la lectura, el siguiente valor de SigningKey se muestra en formato hexadecimal.
```
3543b7686e65eda71e5e5ca19d548d78423c37e8ddba4dc9d83f90228b457c76
```
2. Calcule el Signature.
```
053edbf550ebd239b32a9cdfd93b0b2b3f2d223083aa61f75e9ac16856d61f23
```