Todos os produtos
Search

Este produto

    Object Storage Service:Guide to upgrading from Signature V1 to Signature V4

    Central de documentação

    Object Storage Service:Guide to upgrading from Signature V1 to Signature V4

    Última atualização: Oct 10, 2026

    Para aumentar a segurança, o Object Storage Service (OSS) está descontinuando a Signature V1. Atualize para a Signature V4 o mais rápido possível para garantir que suas aplicações continuem funcionando corretamente.

    Como atualizar da Assinatura V1 para a Assinatura V4

    Siga o guia correspondente para concluir o upgrade de acordo com o seu uso atual.

    Ferramenta

    Tipo

    Versões com suporte à V4

    Guia de upgrade

    OSS SDK

    Java

    Versão 3.17.4 e posteriores

    OSS SDK

    Python V2

    Todas as versões

    Python V1

    Versão 2.18.4 e posteriores

    Go V2

    Todas as versões

    Go V1

    Versão 3.0.2 e posteriores

    PHP V2

    Todas as versões

    PHP V1

    Versão 2.7.0 e posteriores

    C# V2

    Todas as versões

    C# V1

    Versão 2.14.0 e posteriores

    JavaScript

    Versão 6.20.0 e posteriores

    C++

    Versão 1.10.0 e posteriores

    C

    Versão 3.11.0 e posteriores

    Swift

    Todas as versões

    Objective-C

    Versão 2.11.1 e posteriores

    Android

    Versão 2.3 e posteriores

    ossutil

    ossutil 2.0

    Todas as versões

    ossutil

    ossutil 1.0

    Versão 1.7.12 e posteriores

    ossfs

    ossfs 2.0

    Todas as versões

    ossfs

    ossfs 1.0

    Versão 1.91.4 e posteriores

    API (construção manual de assinatura)

    Para saber como atualizar um algoritmo de assinatura V1 construído manualmente para a V4, consulte API (construção manual de assinatura).

    console do OSS

    As atualizações do OSS ocorrem automaticamente. O processo é transparente para os usuários.

    OSS SDK

    Java

    1. Atualize o OSS SDK for Java para a versão 3.17.4 ou posterior.

    2. Ao inicializar um OSS Client com a Signature V4, execute as seguintes etapas:

      • Especifique o ID da região do bucket como identificador para a região da requisição. Por exemplo, o ID da região para China (Hangzhou) é cn-hangzhou.

      • Declare explicitamente o uso do algoritmo de assinatura V4. Por exemplo: SignVersion.V4.

    Exemplo de código

    Authorization: OSS4-HMAC-SHA256 Credential=<AccessKeyId>/<Date>/<Region>/oss/aliyun_v4_request, AdditionalHeaders=<Headers>, Signature=<Signature>

    Python

    Python V2

    1. Todas as versões do OSS SDK for Python V2 suportam a Signature V4 por padrão.

    2. Ao inicializar um OSS Client com a Signature V4, execute a seguinte etapa:

      Especifique o ID da região do bucket como identificador para a região da requisição. Por exemplo, o ID da região para China (Hangzhou) é cn-hangzhou.

    Exemplo de código

    Authorization: OSS4-HMAC-SHA256 Credential=<AccessKeyId>/<Date>/<Region>/oss/aliyun_v4_request, AdditionalHeaders=<Headers>, Signature=<Signature>

    Python V1

    1. Atualize o OSS SDK for Python V1 para a versão 2.18.4 ou posterior.

    2. Ao inicializar um OSS Client com a Signature V4, execute as seguintes etapas:

      • Especifique o ID da região do bucket como identificador para a região da requisição. Por exemplo, o ID da região para China (Hangzhou) é cn-hangzhou.

      • Declare explicitamente o uso do algoritmo de assinatura V4. Por exemplo: oss2.ProviderAuthV4.

    Exemplo de código

    Authorization: OSS4-HMAC-SHA256 Credential=<AccessKeyId>/<Date>/<Region>/oss/aliyun_v4_request, AdditionalHeaders=<Headers>, Signature=<Signature>

    Go

    Go V2

    1. Todas as versões do OSS SDK for Go V2 suportam a Signature V4 por padrão.

    2. Ao inicializar um OSS Client com a Signature V4, execute a seguinte etapa:

      Especifique o ID da região do bucket como identificador para a região da requisição. Por exemplo, o ID da região para China (Hangzhou) é cn-hangzhou.

    Exemplo de código

    Authorization: OSS4-HMAC-SHA256 Credential=<AccessKeyId>/<Date>/<Region>/oss/aliyun_v4_request, AdditionalHeaders=<Headers>, Signature=<Signature>

    Go V1

    Nota

    Todas as versões do OSS SDK for Go V2 suportam a Signature V4 por padrão. Migre do Go V1 para o Go V2.

    1. Atualize o OSS SDK for Go V1 para a versão 3.0.2 ou posterior.

    2. Ao inicializar um OSS Client com a Signature V4, execute as seguintes etapas:

      • Especifique o ID da região do bucket como identificador para a região da requisição. Por exemplo, o ID da região para China (Hangzhou) é cn-hangzhou.

      • Declare explicitamente o uso do algoritmo de assinatura V4. Por exemplo: oss.AuthV4.

    Exemplo de código

    Authorization: OSS4-HMAC-SHA256 Credential=<AccessKeyId>/<Date>/<Region>/oss/aliyun_v4_request, AdditionalHeaders=<Headers>, Signature=<Signature>

    PHP

    PHP V2

    1. Todas as versões do OSS SDK for PHP V2 suportam a Signature V4 por padrão.

    2. Ao inicializar um OSS Client com a Signature V4, execute a seguinte etapa:

      Especifique o ID da região do bucket como identificador para a região da requisição. Por exemplo, o ID da região para China (Hangzhou) é cn-hangzhou.

    Authorization: OSS4-HMAC-SHA256 Credential=<AccessKeyId>/<Date>/<Region>/oss/aliyun_v4_request, AdditionalHeaders=<Headers>, Signature=<Signature>

    PHP V1

    1. Atualize o OSS SDK for PHP V1 para a versão 2.7.0 ou posterior.

    2. Ao inicializar um OSS Client com a Signature V4, execute as seguintes etapas:

      • Especifique o ID da região do bucket como identificador para a região da requisição. Por exemplo, o ID da região para China (Hangzhou) é cn-hangzhou.

      • Declare explicitamente o uso do algoritmo de assinatura V4. Por exemplo: OSS_SIGNATURE_VERSION_V4.

    Exemplo de código

    Authorization: OSS4-HMAC-SHA256 Credential=<AccessKeyId>/<Date>/<Region>/oss/aliyun_v4_request, AdditionalHeaders=<Headers>, Signature=<Signature>

    C#

    C# V2

    1. Todas as versões do OSS SDK for C# V2 suportam a Signature V4 por padrão.

    2. Ao inicializar um OSS Client com a Signature V4, execute a seguinte etapa:

      Especifique o ID da região do bucket como identificador para a região da requisição. Por exemplo, o ID da região para China (Hangzhou) é cn-hangzhou.

    using OSS = AlibabaCloud.OSS.V2; // Crie um alias para o Alibaba Cloud OSS SDK para simplificar o uso posterior. var region = "cn-hangzhou"; // Obrigatório. Especifique a região onde o bucket está localizado. Por exemplo, se o seu bucket estiver localizado na região China (Hangzhou), defina a região como cn-hangzhou. var endpoint = null as string; // Opcional. Especifique o endpoint para acessar o OSS. Por exemplo, se o bucket estiver localizado na região China (Hangzhou), defina o endpoint como https://oss-cn-hangzhou.aliyuncs.com. // Carregue a configuração padrão do SDK, que lê automaticamente as credenciais (como o AccessKey) das variáveis de ambiente. var cfg = OSS.Configuration.LoadDefault(); // Use explicitamente as variáveis de ambiente para obter credenciais para autenticação. (Formato: OSS_ACCESS_KEY_ID, OSS_ACCESS_KEY_SECRET) cfg.CredentialsProvider = new OSS.Credentials.EnvironmentVariableCredentialsProvider(); // Defina a região na configuração. cfg.Region = region; // Se um endpoint for especificado, substitua o endpoint padrão. if(endpoint != null) { cfg.Endpoint = endpoint; } // Use a configuração para criar uma instância do Client. using var client = new OSS.Client(cfg); // Use a instância do Client para realizar operações subsequentes.

    C# V1

    1. Atualize o OSS SDK for C# V1 para a versão 2.14.0 ou posterior.

    2. Ao inicializar um OSS Client com a Signature V4, execute as seguintes etapas:

      • Especifique o ID da região do bucket como identificador para a região da requisição. Por exemplo, o ID da região para China (Hangzhou) é cn-hangzhou.

      • Declare explicitamente o uso do algoritmo de assinatura V4. Por exemplo: SignVersion.V4.

    Exemplo de código

    Authorization: OSS4-HMAC-SHA256 Credential=<AccessKeyId>/<Date>/<Region>/oss/aliyun_v4_request, AdditionalHeaders=<Headers>, Signature=<Signature>

    Node.js

    1. Atualize o OSS SDK for Node.js para a versão 6.20.0 ou posterior.

    2. Ao inicializar um OSS Client com a Signature V4, execute as seguintes etapas:

      • Especifique o ID da região dedicada do OSS do bucket como identificador para a região da requisição. Por exemplo, o ID da região para China (Hangzhou) é oss-cn-hangzhou.

      • Declare explicitamente o uso do algoritmo de assinatura V4. Por exemplo: authorizationV4.

    Authorization: OSS4-HMAC-SHA256 Credential=<AccessKeyId>/<Date>/<Region>/oss/aliyun_v4_request, AdditionalHeaders=<Headers>, Signature=<Signature>

    Browser.js

    1. Atualize o OSS SDK for Browser.js para a versão 6.20.0 ou posterior.

    2. Ao inicializar um OSS Client com a Signature V4, execute as seguintes etapas:

      • Especifique o ID da região dedicada do OSS do bucket como identificador para a região da requisição. Por exemplo, o ID da região para China (Hangzhou) é oss-cn-hangzhou.

      • Declare explicitamente o uso do algoritmo de assinatura V4. Por exemplo: authorizationV4.

    Exemplo de código

    Authorization: OSS4-HMAC-SHA256 Credential=<AccessKeyId>/<Date>/<Region>/oss/aliyun_v4_request, AdditionalHeaders=<Headers>, Signature=<Signature>

    C++

    1. Atualize o OSS SDK for C++ para a versão 1.10.0 ou posterior.

    2. Ao inicializar um OSS Client com a Signature V4, execute as seguintes etapas:

      • Especifique o ID da região do bucket como identificador para a região da requisição. Por exemplo, o ID da região para China (Hangzhou) é cn-hangzhou.

      • Declare explicitamente o uso do algoritmo de assinatura V4. Por exemplo: SignatureVersionType::V4.

    Exemplo de código

    Authorization: OSS4-HMAC-SHA256 Credential=<AccessKeyId>/<Date>/<Region>/oss/aliyun_v4_request, AdditionalHeaders=<Headers>, Signature=<Signature>

    C

    1. Atualize o OSS SDK for C para a versão 3.11.0 ou posterior.

    2. Ao inicializar um OSS Client com a Signature V4, execute as seguintes etapas:

      • Especifique o ID da região do bucket como identificador para a região da requisição. Por exemplo, o ID da região para China (Hangzhou) é cn-hangzhou.

      • Declare explicitamente o uso do algoritmo de assinatura V4. Por exemplo: signature_version = 4.

    Exemplo de código

    Authorization: OSS4-HMAC-SHA256 Credential=<AccessKeyId>/<Date>/<Region>/oss/aliyun_v4_request, AdditionalHeaders=<Headers>, Signature=<Signature>

    Swift

    1. Todas as versões do OSS SDK for Swift suportam a Signature V4 por padrão.

    2. Ao inicializar um OSS Client com a Signature V4, execute a seguinte etapa:

      Especifique o ID da região do bucket como identificador para a região da requisição. Por exemplo, o ID da região para China (Hangzhou) é cn-hangzhou.

    Authorization: OSS4-HMAC-SHA256 Credential=<AccessKeyId>/<Date>/<Region>/oss/aliyun_v4_request, AdditionalHeaders=<Headers>, Signature=<Signature>

    iOS

    1. Atualize o OSS SDK for iOS para a versão 2.11.1 ou posterior.

    2. Ao inicializar um OSS Client com a Signature V4, execute as seguintes etapas:

      • Especifique o ID da região do bucket como identificador para a região da requisição. Por exemplo, o ID da região para China (Hangzhou) é cn-hangzhou.

      • Declare explicitamente o uso do algoritmo de assinatura V4. Por exemplo: OSSSignVersionV4.

    Exemplo de código

    Authorization: OSS4-HMAC-SHA256 Credential=<AccessKeyId>/<Date>/<Region>/oss/aliyun_v4_request, AdditionalHeaders=<Headers>, Signature=<Signature>

    Android

    1. Atualize o OSS SDK for Android para a versão 2.3 ou posterior.

    2. Ao inicializar um OSS Client com a Signature V4, execute as seguintes etapas:

      • Especifique o ID da região do bucket como identificador para a região da requisição. Por exemplo, o ID da região para China (Hangzhou) é cn-hangzhou.

      • Declare explicitamente o uso do algoritmo de assinatura V4. Por exemplo: SignVersion.V4.

    Exemplo de código

    Authorization: OSS4-HMAC-SHA256 Credential=<AccessKeyId>/<Date>/<Region>/oss/aliyun_v4_request, AdditionalHeaders=<Headers>, Signature=<Signature>

    ossutil

    ossutil 2.0

    Todas as versões da interface de linha de comando ossutil 2.0 suportam a Signature V4 por padrão.

    Em comparação com a Signature V1, ao usar a Signature V4, defina o parâmetro Region como o ID da região do bucket ao configurar o ossutil.

    Exemplo de comando

    Authorization: OSS4-HMAC-SHA256 Credential=<AccessKeyId>/<Date>/<Region>/oss/aliyun_v4_request, AdditionalHeaders=<Headers>, Signature=<Signature>

    ossutil 1.0

    Nota

    Todas as versões do ossutil 2.0 suportam a Signature V4 por padrão. Migre do ossutil 1.0 para o ossutil 2.0.

    A versão 1.7.12 e posteriores da interface de linha de comando ossutil 1.0 suportam a Signature V4.

    Em comparação com a Signature V1, ao usar a Signature V4, execute o seguinte no comando:

    • Defina a opção --sign-version como v4.

    • Defina a opção --region como o ID da região do bucket.

    Exemplo de comando

    Authorization: OSS4-HMAC-SHA256 Credential=<AccessKeyId>/<Date>/<Region>/oss/aliyun_v4_request, AdditionalHeaders=<Headers>, Signature=<Signature>
    Authorization: OSS4-HMAC-SHA256 Credential=<AccessKeyId>/<Date>/<Region>/oss/aliyun_v4_request, AdditionalHeaders=<Headers>, Signature=<Signature>

    ossfs

    ossfs 2.0

    Todas as versões do ossfs 2.0 (Preview) oferecem suporte à Signature V4, mas utilizam a Signature V1 por padrão.

    1. Antes de fazer o upgrade, execute o comando ossfs --version para verificar a versão atual e conclua os seguintes pré-requisitos de acordo com a sua versão.

      Importante

      A desinstalação interromperá os seus serviços. Execute esta operação fora dos horários de pico.

      Desmonte o sistema de arquivos do OSS. Substitua &lt;mountpoint&gt; pelo seu diretório real.

      Authorization: OSS4-HMAC-SHA256 Credential=<AccessKeyId>/<Date>/<Region>/oss/aliyun_v4_request, AdditionalHeaders=<Headers>, Signature=<Signature>

      Após desmontar, siga o comando de exemplo para fazer o upgrade.

    2. Em comparação com a Signature V1, ao usar a Signature V4, é necessário incluir os seguintes parâmetros no comando de montagem:

    Comando de exemplo

    Authorization: OSS4-HMAC-SHA256 Credential=<AccessKeyId>/<Date>/<Region>/oss/aliyun_v4_request, AdditionalHeaders=<Headers>, Signature=<Signature>

    ossfs 1.0

    A versão 1.91.4 e as versões posteriores do ossfs 1.0 oferecem suporte à Signature V4.

    1. Antes de fazer o upgrade, execute o comando ossfs --version para verificar a versão atual e conclua os seguintes pré-requisitos de acordo com a sua versão.

      Importante

      A desinstalação interromperá os seus serviços. Execute esta operação fora dos horários de pico.

      Fazer upgrade para V4 se o requisito de versão for atendido

      Desmonte o sistema de arquivos do OSS. Substitua &lt;mountpoint&gt; pelo seu diretório real.

      Authorization: OSS4-HMAC-SHA256 Credential=<AccessKeyId>/<Date>/<Region>/oss/aliyun_v4_request, AdditionalHeaders=<Headers>, Signature=<Signature>

      Após desmontar, siga o Comando de exemplo para fazer o upgrade.

      Fazer upgrade para V4 se o requisito de versão não for atendido

      1. Desmonte o sistema de arquivos do OSS. Substitua &lt;mountpoint&gt; pelo seu diretório real.

        Authorization: OSS4-HMAC-SHA256 Credential=<AccessKeyId>/<Date>/<Region>/oss/aliyun_v4_request, AdditionalHeaders=<Headers>, Signature=<Signature>

      2. Desinstale a versão antiga.

        Se você instalou o ossfs usando um gerenciador de pacotes, como apt ou yum, execute o seguinte comando:

        Authorization: OSS4-HMAC-SHA256 Credential=<AccessKeyId>/<Date>/<Region>/oss/aliyun_v4_request, AdditionalHeaders=<Headers>, Signature=<Signature>

        Se você compilou e instalou o ossfs a partir do código-fonte, acesse o diretório de instalação e execute o seguinte comando:

        Authorization: OSS4-HMAC-SHA256 Credential=<AccessKeyId>/<Date>/<Region>/oss/aliyun_v4_request, AdditionalHeaders=<Headers>, Signature=<Signature>

      3. Baixe e instale a nova versão.

      Após instalar a nova versão, siga o Comando de exemplo para fazer o upgrade.

    2. Em comparação com a Signature V1, ao usar a Signature V4, é necessário incluir os seguintes parâmetros no comando de montagem:

    • Defina a opção sigv4.

    • Defina a opção region com o ID da região do bucket.

    Comando de exemplo

    Authorization: OSS4-HMAC-SHA256 Credential=<AccessKeyId>/<Date>/<Region>/oss/aliyun_v4_request, AdditionalHeaders=<Headers>, Signature=<Signature>

    API (construção manual de assinatura)

    Use um SDK do OSS para enviar solicitações, pois o SDK calcula a assinatura automaticamente. Se não for possível usar um SDK do OSS, construa manualmente uma assinatura V4 e garanta que a solicitação esteja correta.

    Método de assinatura

    Descrição

    Referências

    Incluir a assinatura no cabeçalho

    No OSS, o método mais comum para verificação de identidade é incluir a assinatura no cabeçalho Authorization de uma solicitação HTTP. Todas as operações do OSS, exceto aquelas que usam assinaturas POST ou assinaturas de URL, exigem autenticação por meio do cabeçalho Authorization.

    Incluir uma assinatura V4 no cabeçalho

    Incluir a assinatura na URL

    Você pode conceder acesso de terceiros aos seus recursos do OSS por um período de validade específico sem revelar suas credenciais de acesso. Para isso, gere uma URL assinada que inclua a assinatura e outras informações necessárias para a solicitação.

    Incluir uma assinatura V4 na URL

    Assinatura de solicitação POST

    A assinatura PostObject é um mecanismo que permite enviar arquivos diretamente para o OSS por meio de um formulário HTML. Esse mecanismo possibilita a construção de um formulário HTML em um cliente, como um navegador web. O formulário inclui campos para o arquivo a ser enviado e outros parâmetros necessários, como a assinatura, o par de AccessKey, o nome do bucket e a chave do objeto. Ao enviar o formulário, o sistema transmite essas informações ao OSS por meio de uma solicitação HTTP POST, e o OSS verifica a validade da solicitação.

    Assinatura V4 para solicitações POST

    Cronograma de descontinuação e impacto da Assinatura V1

    De acordo com o Anúncio de descontinuação da Assinatura Versão 1 do Alibaba Cloud Object Storage Service, a Assinatura V1 do Alibaba Cloud Object Storage Service será gradualmente descontinuada para novos clientes (novos UIDs) a partir de 1º de março de 2025. A partir de 1º de setembro de 2025, a Assinatura V1 não receberá mais atualizações nem manutenção e não estará disponível para novos buckets.

    Comparação entre a Assinatura V1 e a Assinatura V4

    Item

    Assinatura V1

    Assinatura V4

    Algoritmo de assinatura

    HMAC-SHA1

    HMAC-SHA256

    Período de validade da URL assinada

    O horário de assinatura pode ser superior a 7 dias no passado. O período de validade pode exceder 7 dias.

    O horário de assinatura é limitado aos últimos 7 dias. O período de validade é limitado a 7 dias.

    Construção da string de assinatura

    A string de assinatura inclui o método HTTP, Content-MD5, Content-Type, data, cabeçalhos canonizados e o caminho do recurso.

    A string de assinatura possui uma estrutura mais complexa, que inclui o método de requisição, URI canonizada, parâmetros de consulta canonizados, cabeçalhos canonizados, cabeçalhos assinados adicionais e o hash do payload.

    Cabeçalhos e parâmetros de consulta canonizados

    Apenas os cabeçalhos com o prefixo x-oss- são canonizados. Apenas alguns parâmetros de consulta são incluídos na assinatura.

    Todos os cabeçalhos com o prefixo x-oss- e os cabeçalhos assinados por padrão (como content-type e content-md5) são canonizados. Cabeçalhos assinados adicionais também são suportados.

    Codificação do caminho do recurso

    A barra (/) no caminho do recurso é codificada.

    A / nos caminhos de recurso não é escapada, enquanto a / nos parâmetros de consulta deve ser escapada como %2F.

    Formato de carimbo de data/hora e data

    Utiliza o formato de data HTTP padrão, por exemplo, Wed, 21 Oct 2015 07:28:00 GMT.

    Utiliza o formato ISO 8601 para horário UTC, por exemplo, 20151021T072800Z.

    Informações da região

    A assinatura não inclui informações de região.

    As regras de assinatura introduzem o conceito de região. Tanto a string de assinatura quanto a chave de assinatura devem incluir o ID da região.

    Perguntas frequentes

    Como verificar rapidamente se estou usando a Assinatura V1 ou a Assinatura V4?

    Use a Consulta de log em tempo real ou uma ferramenta de captura de pacotes, como Wireshark ou Fiddler, e visualize o campo Authorization no cabeçalho da requisição HTTP enviada ao OSS.

    • Assinatura V1: O campo Authorization começa com OSS e tem o seguinte formato:

      Authorization: OSS4-HMAC-SHA256 Credential=<AccessKeyId>/<Date>/<Region>/oss/aliyun_v4_request, AdditionalHeaders=<Headers>, Signature=<Signature>

    • Assinatura V4: O campo Authorization começa com OSS4-HMAC-SHA256 e tem o seguinte formato:

      Authorization: OSS4-HMAC-SHA256 Credential=<AccessKeyId>/<Date>/<Region>/oss/aliyun_v4_request, AdditionalHeaders=<Headers>, Signature=<Signature>

    Como solucionar um erro SignatureDoesNotMatch

    Se o cálculo da assinatura estiver incorreto, o sistema retornará o código de erro SignatureDoesNotMatch. Para localizar rapidamente o problema, compare as informações relacionadas à assinatura geradas pelo servidor e pelo cliente. A resposta retornada pelo servidor contém as seguintes informações principais:

    • CanonicalRequest: A string de consulta canonizada gerada pelo servidor.

    • StringToSign: A string a ser assinada gerada pelo servidor com base na requisição canonizada.

    • Signature: O valor final da assinatura calculado pelo servidor.

    A comparação desses campos com os correspondentes gerados pelo cliente permite identificar rapidamente as diferenças e localizar a origem do erro. Por exemplo:

    • Se o CanonicalRequest estiver inconsistente, a ordem de concatenação ou o formato dos parâmetros de requisição pode estar incorreto.

    • Se a StringToSign estiver inconsistente, a data, a região ou as informações do produto cloud podem estar definidas incorretamente.

    • Se a Signature estiver inconsistente, pode haver um problema no cálculo da chave derivada ou na implementação do algoritmo de assinatura.