Object Storage Service:(Recommended) V4 signatures in presigned URLs

Use os OSS SDKs para implementar automaticamente as assinaturas V4

Os OSS SDKs suportam a implementação automática de assinaturas V4. Recomendamos o uso dos OSS SDKs para iniciar solicitações, eliminando a necessidade de calcular assinaturas manualmente. Para mais informações sobre a implementação de assinaturas em uma linguagem de programação específica, consulte o código de exemplo do OSS SDK para essa linguagem. A tabela a seguir apresenta referências ao código de exemplo usado para assinar solicitações com o algoritmo de assinatura V4 nos OSS SDKs para diferentes linguagens de programação.

Assinatura de URL

• Exemplo

  https://examplebucket.oss-cn-hangzhou.aliyuncs.com/exampleobject?x-oss-additional-headers=host&x-oss-credential=LTAI********************%2F20241203%2Fcn-hangzhou%2Foss%2Faliyun_v4_request&x-oss-date=20241203T034420Z&x-oss-expires=86400&x-oss-signature=70c542eaf652ac291c0c343d63ac24ede41c0526661d9d4c63c0906a2686160c&x-oss-signature-version=OSS4-HMAC-SHA256

  Para facilitar a leitura, os campos do parâmetro x-oss-credential na URL acima são separados por barras (/). Ao iniciar uma requisição, aplique a codificação URI nas barras (/) da URL para convertê-las em %2F. Exemplo:

  &x-oss-credential=LTAI********************%2F20241203%2Fcn-hangzhou%2Foss%2Faliyun_v4_request

• Parâmetros de query string

  Parâmetro	Tipo	Obrigatório	Exemplo	Descrição
  x-oss-signature-version	String	Sim	OSS4-HMAC-SHA256	A versão e o algoritmo da assinatura. Defina o valor como OSS4-HMAC-SHA256.
  x-oss-credential	String	Sim	LTAI/20241203/cn-hangzhou/oss/aliyun_v4_request	As credenciais usadas para calcular a assinatura. Formato: LTAI********************/<date>/<region>/oss/aliyun_v4_request AccessKeyId: o AccessKey ID no par de AccessKey. date: a data em que a requisição foi iniciada. region: a região onde o recurso solicitado reside. oss: o nome do service solicitado. Defina o valor como oss. aliyun_v4_request: a descrição da versão de assinatura na requisição. Defina o valor como aliyun_v4_request.
  x-oss-date	String	Sim	20241203T034420Z	O horário em que a URL foi assinada. O horário segue o padrão ISO 8601 e é exibido em UTC. Nota Esse horário é usado como timestamp para a string a assinar. O valor deve ser idêntico ao do campo date na chave de assinatura derivada.
  x-oss-expires	Integer	Sim	3600	O período de validade da URL assinada, calculado a partir do valor do parâmetro x-oss-date. Unidade: segundos. Ao usar um par de AccessKey, o valor deve estar entre 1 e 604.800 (7 dias). Ao usar credenciais de acesso temporário obtidas pelo Security Token Service (STS), o valor deve estar entre 1 e 43.200 (12 horas). Nota O momento em que o OSS recebe a requisição (T) deve satisfazer a seguinte condição: (x-oss-date - 15 minutos) ≤ T ≤ (x-oss-date + x-oss-expires). Se T for anterior ao valor (x-oss-date - 15 minutos), a requisição é inválida. Se o horário atual for posterior ao valor (x-oss-date + x-oss-expires), a requisição é inválida.
  x-oss-additional-headers	String	Não	host	Os headers que você deseja incluir no cálculo da assinatura. Por exemplo, adicione o header host para impedir que o nome de domínio de origem da requisição seja alterado. Os requisitos para construção de um header são os seguintes: Todos os headers no parâmetro x-oss-additional-headers devem estar em letras minúsculas. Todos os headers no parâmetro x-oss-additional-headers devem estar em ordem alfabética. Todos os headers do array são separados por ponto e vírgula (;) para formar uma string.
  x-oss-signature	String	Sim	77Dv	A descrição da verificação de assinatura. O parâmetro x-oss-signature não é incluído no cálculo da assinatura.
  x-oss-security-token	String	Não	CAIS**	O token de segurança emitido pelo STS. Este parâmetro é obrigatório apenas quando você usa um token de segurança para calcular a assinatura da URL.

Processo de cálculo de assinatura

O método usado para calcular uma assinatura para uma URL é semelhante ao utilizado para calcular uma assinatura para o cabeçalho Authorization. Os itens a seguir descrevem as diferenças entre os dois métodos:

• O cabeçalho x-oss-content-sha256, que descreve o hash do payload, não é usado para calcular a assinatura de uma URL. Ao criar uma URL assinada, não é possível avaliar o conteúdo do payload. Em vez disso, utiliza-se UNSIGNED-PAYLOAD.

• Se uma chave nos parâmetros de query string de uma URL assinada for igual a um cabeçalho a ser assinado, mas os valores forem diferentes, um erro será retornado. Se uma chave tiver múltiplos valores, todos os valores da chave serão comparados simultaneamente. Caso os valores sejam diferentes, um erro será retornado.

• Se você usar as credenciais de acesso temporário obtidas do STS para acessar recursos do OSS em uma URL assinada, adicione o parâmetro x-oss-security-token à query string da URL.

• O parâmetro x-oss-signature na query string não é incluído no cálculo da assinatura.

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

"GET" | "GET" | ... + "\n" +
UriEncode(<Resource>) + "\n" +
UriEncode(<QueryParam1>) + "=" + UriEncode(<Value>) + "&" + UriEncode(<QueryParam2>) + "\n" +
Lowercase(<HeaderName1>) + ":" + Trim(<value>) + "\n" + Lowercase(<HeaderName2>) + ":" + Trim(<value>) + "\n" + "\n"
Lowercase(<AdditionalHeaderName1>) + ";" + Lowercase(<AdditionalHeaderName2>) + "\n" +
UNSIGNED-PAYLOAD

"OSS4-HMAC-SHA256" + "\n" +
dateTimeStr + "\n" +
dateStr + "\n" +
DigestUtils.sha256Hex(canonicalRequest);

String stringToSign = "OSS4-HMAC-SHA256\n" +
                dateTimeStr + "\n" +
                dateStr + "/cn-hangzhou/oss/aliyun_v4_request\n" +
                DigestUtils.sha256Hex(canonicalRequest);

Código de exemplo completo para obtenção de uma URL assinada V4

O código a seguir demonstra como calcular uma assinatura V4 para gerar uma URL pré-assinada para requisições GET. Essa URL pré-assinada é válida apenas para operações de download e acesso.

import com.aliyun.oss.common.utils.BinaryUtil;
import org.apache.commons.codec.digest.DigestUtils;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.net.URL;
import java.time.ZonedDateTime;
import java.time.format.DateTimeFormatter;
import java.util.TimeZone;

public class Demo {

    /**
     * Signature calculation tool
     *
     * @return url
     */
    public static void main(String[] args) throws Exception {
        // Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
        String accesskeyid =  System.getenv().get("OSS_ACCESS_KEY_ID");
        String accesskeysecret =  System.getenv().get("OSS_ACCESS_KEY_SECRET");
        // Query and display the current time. The time follows the ISO 8601 standard and is displayed in UTC.
        ZonedDateTime now = ZonedDateTime.now(TimeZone.getTimeZone("UTC").toZoneId());
        String dateStr = now.format(DateTimeFormatter.ofPattern("yyyyMMdd"));
        String dateTimeStr = now.format(DateTimeFormatter.ofPattern("yyyyMMdd'T'HHmmss'Z'"));
        // Step 1: Create a canonical request. 
        String canonicalRequest =
                "GET\n" +
                        "/examplebucket/exampleobject\n" +
                        "x-oss-additional-headers=host&x-oss-credential=" + accesskeyid + "%2F" + dateStr + "%2Fcn-hangzhou%2Foss%2Faliyun_v4_request&x-oss-date=" + dateTimeStr + "&x-oss-expires=86400&x-oss-signature-version=OSS4-HMAC-SHA256\n" +
                        "host:examplebucket.oss-cn-hangzhou.aliyuncs.com\n" +
                        "\n" +
                        "host\n" +
                        "UNSIGNED-PAYLOAD";
        System.out.println("canonicalRequest:" + canonicalRequest);
        // Step 2: Create a string to sign. 
        String stringToSign = "OSS4-HMAC-SHA256\n" +
                dateTimeStr + "\n" +
                dateStr + "/cn-hangzhou/oss/aliyun_v4_request\n" +
                DigestUtils.sha256Hex(canonicalRequest);

        // Step 3: Calculate the signature. 
        byte[] dateKey = hmacsha256(("aliyun_v4" + accesskeysecret).getBytes(), dateStr);
        byte[] dateRegionKey = hmacsha256(dateKey, "cn-hangzhou");
        byte[] dateRegionServiceKey = hmacsha256(dateRegionKey, "oss");
        byte[] signingKey = hmacsha256(dateRegionServiceKey, "aliyun_v4_request");

        byte[] result = hmacsha256(signingKey, stringToSign);
        String signature = BinaryUtil.toHex(result);
        System.out.println("signature:" + signature);

        // Step 4: Add the signature to the URL. 
        String resourcePath = "exampleobject";
        String endpoint = "https://examplebucket.oss-cn-hangzhou.aliyuncs.com";
        String queryString = "x-oss-additional-headers=host&" +
                "x-oss-credential=" + accesskeyid + "%2F" + dateStr + "%2Fcn-hangzhou%2Foss%2Faliyun_v4_request&" +
                "x-oss-date=" + dateTimeStr + "&" +
                "x-oss-expires=86400&" +
                "x-oss-signature=" + signature + "&" +
                "x-oss-signature-version=OSS4-HMAC-SHA256";

        String urlStr = endpoint + "/" + resourcePath + "?" + queryString;
        URL url = new URL(urlStr);
        System.out.println("url:" + url);
    }

    public static byte[] hmacsha256(byte[] key, String data) {
        try {
            // Initialize the HMAC key specifications, set the algorithm to HMAC-SHA256, and use the provided key. 
            SecretKeySpec secretKeySpec = new SecretKeySpec(key, "HmacSHA256");

            // Obtain a Mac instance and use the getInstance method to set the algorithm to HMAC-SHA256. 
            Mac mac = Mac.getInstance("HmacSHA256");
            // Use the key to initialize the Mac instance. 
            mac.init(secretKeySpec);

            // Calculate the HMAC. Use the doFinal method to process the data and return the result as a byte array. 
            byte[] hmacBytes = mac.doFinal(data.getBytes());

            return hmacBytes;
        } catch (Exception e) {
            throw new RuntimeException("Failed to calculate HMAC-SHA256", e);
        }
    }
}

Exemplo de saída:

signature:eee300fa39f52127a02af5f9bb86c0fd8b6776fc19101d9a6a7982c9d0edcc04
url:https://examplebucket.oss-cn-hangzhou.aliyuncs.com/exampleobject?x-oss-additional-headers=host&x-oss-credential=LTAI********************%2F20241203%2Fcn-hangzhou%2Foss%2Faliyun_v4_request&x-oss-date=20241203T032307Z&x-oss-expires=86400&x-oss-signature=eee300fa39f52127a02af5f9bb86c0fd8b6776fc19101d9a6a7982c9d0edcc04&x-oss-signature-version=OSS4-HMAC-SHA256

Referências

• Ao utilizar uma URL pré-assinada para visualizar um arquivo .txt, podem aparecer caracteres ilegíveis no navegador. Para mais informações, consulte 在线预览.txt文件出现乱码问题怎么办？

• Para mais informações sobre como gerar automaticamente uma URL assinada para upload e download de objetos usando o OSS SDK para as principais linguagens de programação, consulte Object uploads by using presigned URLs e Using presigned URLs to download or preview files.