Object Storage Service:(Recomendado) Assinaturas V4 em URLs pré-assinadas

Usar SDKs do OSS para implementar automaticamente assinaturas V4

Os SDKs do OSS suportam a implementação automática de assinaturas V4. Recomendamos o uso dos SDKs do OSS para iniciar requisições, pois isso elimina a necessidade de calcular assinaturas manualmente. Para obter mais informações sobre a implementação de assinatura para uma linguagem de programação específica, consulte o código de exemplo do SDK do OSS correspondente. A tabela a seguir fornece referências aos códigos de exemplo usados para assinar requisições com o algoritmo de assinatura V4 ao utilizar SDKs do OSS em 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 no parâmetro x-oss-credential da URL anterior estão separados por barras (/). Ao iniciar uma requisição, codifique as barras (/) na URL para convertê-las em %2F. Exemplo:

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

• Parâmetros da string de consulta

  Parâmetro	Tipo	Obrigatório	Exemplo	Descrição
  x-oss-signature-version	String	Sim	OSS4-HMAC-SHA256	Versão e algoritmo da assinatura. Defina o valor como OSS4-HMAC-SHA256.
  x-oss-credential	String	Sim	LTAI/20241203/cn-hangzhou/oss/aliyun_v4_request	Credenciais utilizadas para calcular a assinatura. Formato: LTAI********************/<date>/<region>/oss/aliyun_v4_request AccessKeyId: o AccessKey ID do 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 serviço solicitado. Defina o valor como oss. aliyun_v4_request: a descrição da versão da assinatura na requisição. Defina o valor como aliyun_v4_request.
  x-oss-date	String	Sim	20241203T034420Z	O momento em que a URL foi assinada. O horário segue o padrão ISO 8601 e é exibido em UTC. Nota Este horário serve como timestamp para a string a ser assinada. O valor deve ser idêntico ao campo de data na chave de assinatura derivada.
  x-oss-expires	Integer	Sim	3600	Período de validade da URL assinada, calculado a partir do valor do parâmetro x-oss-date. Unidade: segundos. Ao utilizar um par de AccessKey, o valor deve estar entre 1 e 604.800 (7 dias). Ao utilizar credenciais de acesso temporárias 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 atender ao seguinte requisito: (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 será inválida. Se o horário atual for posterior ao valor (x-oss-date + x-oss-expires), a requisição será inválida.
  x-oss-additional-headers	String	Não	host	Cabeçalhos adicionais para incluir no cálculo da assinatura. Por exemplo, adicione o cabeçalho host para impedir alterações no nome de domínio de origem da requisição. Os itens a seguir descrevem os requisitos para construir um cabeçalho: Todos os cabeçalhos no parâmetro x-oss-additional-headers devem estar em letras minúsculas. Todos os cabeçalhos no parâmetro x-oss-additional-headers devem ser ordenados alfabeticamente. Todos os cabeçalhos em um array são separados por ponto e vírgula (;) para formar uma string.
  x-oss-signature	String	Sim	77Dv	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**	Token de segurança emitido pelo STS. Este parâmetro é necessário apenas quando você usa um token de segurança para calcular uma assinatura para a URL.

Processo de cálculo da assinatura

O método usado para calcular uma assinatura para uma URL é semelhante ao método usado 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 um hash de payload, não é usado para calcular uma assinatura para 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 da string de consulta de uma URL assinada for igual a um cabeçalho a ser assinado, mas seus valores forem diferentes, um erro será relatado. Caso uma chave possua múltiplos valores, todos serão comparados simultaneamente. Se houver divergência, um erro será relatado.

• Ao usar credenciais de acesso temporárias obtidas via STS para acessar recursos do OSS em uma URL assinada, adicione o parâmetro x-oss-security-token à string de consulta da URL.

• O parâmetro x-oss-signature na string de consulta 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 obter uma URL assinada com V4

O código a seguir fornece um exemplo de como calcular uma assinatura V4 para gerar uma URL pré-assinada para uma requisição GET. Esta URL pré-assinada pode ser usada 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);
        }
    }
}

Saída de exemplo:

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

• Se você usar uma URL pré-assinada para visualizar um arquivo .txt, caracteres ilegíveis podem aparecer no navegador. Para mais informações, consulte O que fazer quando aparecem caracteres ilegíveis na visualização online de arquivos .txt?

• Para obter mais informações sobre como gerar automaticamente uma URL assinada para upload e download de objetos usando o SDK do OSS para linguagens de programação comuns, consulte Upload de objetos usando URLs pré-assinadas e Usar URLs pré-assinadas para baixar ou visualizar arquivos.