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

Java

1. Upgrade OSS SDK for Java to version 3.17.4 or later.

2. When initializing the OSS client, set two additional values:

   • The region ID of the bucket (for example, cn-hangzhou for China (Hangzhou))

   • The signature version: SignVersion.V4

import com.aliyun.oss.*;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.common.comm.SignVersion;

public class OSSClientV4 {

    public static void main(String[] args) throws Exception {
        // Endpoint for the region where the bucket is located.
        // Example: China (Hangzhou)
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        String region = "cn-hangzhou";

        // Load credentials from environment variables.
        // Set OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET before running.
        EnvironmentVariableCredentialsProvider credentialsProvider =
            CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();

        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        // Declare Signature V4 explicitly.
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);

        OSS ossClient = OSSClientBuilder.create()
                .endpoint(endpoint)
                .credentialsProvider(credentialsProvider)
                .clientConfiguration(clientBuilderConfiguration)
                .region(region)
                .build();

        // Use ossClient for upload, download, and management operations.

        ossClient.shutdown();
    }
}

Python V2

All versions of OSS SDK for Python V2 use Signature V4 by default.

When initializing the client, specify the region ID of the bucket.

import alibabacloud_oss_v2 as oss

def main():
    # Load credentials from environment variables.
    # Set OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET before running.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # Option 1: Specify only the region.
    cfg.region = 'cn-hangzhou'

    # Option 2: Specify both the region and endpoint.
    # cfg.region = 'cn-hangzhou'
    # cfg.endpoint = 'https://oss-cn-hangzhou.aliyuncs.com'

    client = oss.Client(cfg)

if __name__ == "__main__":
    main()

Python V1

1. Upgrade OSS SDK for Python V1 to version 2.18.4 or later.

2. When initializing the client, set two additional values:

   • The region ID of the bucket

   • The auth class: oss2.ProviderAuthV4

# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

# Load credentials from environment variables.
# Set OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET before running.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

endpoint = 'https://oss-cn-hangzhou.aliyuncs.com'
region = 'cn-hangzhou'

bucket = oss2.Bucket(auth, endpoint, 'examplebucket', region=region)

Go V2

All versions of OSS SDK for Go V2 use Signature V4 by default.

When initializing the client, specify the region ID of the bucket.

package main

import (
    "github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
    "github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

func main() {
    // Option 1: Specify only the region.
    cfg := oss.LoadDefaultConfig().
        WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
        WithRegion("cn-hangzhou")

    // Option 2: Specify both the region and endpoint.
    // cfg := oss.LoadDefaultConfig().
    //     WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
    //     WithRegion("cn-hangzhou").
    //     WithEndpoint("https://oss-cn-hangzhou.aliyuncs.com")

    client := oss.NewClient(cfg)
    _ = client
}

Go V1

All versions of OSS SDK for Go V2 use Signature V4 by default. Consider migrating from Go V1 to Go V2 for a simpler upgrade path.

1. Upgrade OSS SDK for Go V1 to version 3.0.2 or later.

2. When initializing the client, set two additional values:

   • The region ID of the bucket

   • The auth version: oss.AuthV4

package main

import (
    "log"
    "github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func handleError(err error) {
    log.Fatalf("Error: %v", err)
}

func setupClient(endpoint, region string) (*oss.Client, error) {
    provider, err := oss.NewEnvironmentVariableCredentialsProvider()
    if err != nil {
        return nil, err
    }
    // Use AuthV4 to enable Signature V4.
    client, err := oss.New(
        endpoint, "", "",
        oss.SetCredentialsProvider(&provider),
        oss.AuthVersion(oss.AuthV4),
        oss.Region(region),
    )
    return client, err
}

func main() {
    endpoint := "https://oss-cn-hangzhou.aliyuncs.com"
    region := "cn-hangzhou"

    client, err := setupClient(endpoint, region)
    if err != nil {
        handleError(err)
    }
    log.Printf("Client: %#v\n", client)
}

PHP V2

All versions of OSS SDK for PHP V2 use Signature V4 by default.

When initializing the client, specify the region ID of the bucket.

<?php

require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// Load credentials from environment variables.
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider(credentialsProvider: $credentialsProvider);

// Option 1: Specify only the region.
$cfg->setRegion(region: "cn-hangzhou");

// Option 2: Specify both the region and endpoint.
// $cfg->setRegion(region: 'cn-hangzhou')
//     ->setEndpoint(endpoint: 'https://oss-cn-hangzhou.aliyuncs.com');

$client = new Oss\Client($cfg);

PHP V1

1. Upgrade OSS SDK for PHP V1 to version 2.7.0 or later.

2. When initializing the client, set two additional values:

   • The region ID of the bucket

   • The signature version: OssClient::OSS_SIGNATURE_VERSION_V4

<?php
if (is_file(__DIR__ . '/../autoload.php')) {
    require_once __DIR__ . '/../autoload.php';
}
if (is_file(__DIR__ . '/../vendor/autoload.php')) {
    require_once __DIR__ . '/../vendor/autoload.php';
}

use OSS\Credentials\EnvironmentVariableCredentialsProvider;
use OSS\OssClient;
use OSS\Core\OssException;

try {
    // Load credentials from environment variables.
    // Set OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET before running.
    $provider = new EnvironmentVariableCredentialsProvider();
    $endpoint = "https://oss-cn-hangzhou.aliyuncs.com";

    $config = array(
        "provider"          => $provider,
        "endpoint"          => $endpoint,
        "signatureVersion"  => OssClient::OSS_SIGNATURE_VERSION_V4,
        "region"            => "cn-hangzhou",
    );
    $ossClient = new OssClient($config);
} catch (OssException $e) {
    printf($e->getMessage() . "\n");
    return;
}

C# V2

All versions of OSS SDK for C# V2 use Signature V4 by default.

When initializing the client, specify the region ID of the bucket.

using OSS = AlibabaCloud.OSS.V2;

var region = "cn-hangzhou";  // Region where the bucket is located.
var endpoint = null as string;  // Optional. Example: https://oss-cn-hangzhou.aliyuncs.com

// Load credentials from environment variables (OSS_ACCESS_KEY_ID, OSS_ACCESS_KEY_SECRET).
var cfg = OSS.Configuration.LoadDefault();
cfg.CredentialsProvider = new OSS.Credentials.EnvironmentVariableCredentialsProvider();
cfg.Region = region;

if (endpoint != null)
{
    cfg.Endpoint = endpoint;
}

using var client = new OSS.Client(cfg);

C# V1

1. Upgrade OSS SDK for C# V1 to version 2.14.0 or later.

2. When initializing the client, set two additional values:

   • The region ID of the bucket

   • The signature version: SignatureVersion.V4

using Aliyun.OSS;
using Aliyun.OSS.Common;

// Load credentials from environment variables.
// Set OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET before running.
var accessKeyId = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_ID");
var accessKeySecret = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET");

const string endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
const string region = "cn-hangzhou";

var conf = new ClientConfiguration();
conf.SignatureVersion = SignatureVersion.V4;

var client = new OssClient(endpoint, accessKeyId, accessKeySecret, conf);
client.SetRegion(region);

Node.js

1. Upgrade OSS SDK for Node.js to version 6.20.0 or later.

2. When initializing the client, set two additional values:

   • The dedicated OSS region ID of the bucket (for example, oss-cn-hangzhou — note the oss- prefix, which differs from other SDKs)

   • The flag: authorizationV4: true

const OSS = require('ali-oss');

const client = new OSS({
  // Load credentials from environment variables.
  // Set OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET before running.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // Note: Node.js uses the oss- prefixed region ID (e.g., oss-cn-hangzhou).
  region: 'oss-cn-hangzhou',
  authorizationV4: true,
  bucket: 'examplebucket',
  endpoint: 'https://oss-cn-hangzhou.aliyuncs.com',
});

Browser.js

1. Upgrade OSS SDK for Browser.js to version 6.20.0 or later.

2. When initializing the client, set two additional values:

   • The dedicated OSS region ID of the bucket (for example, oss-cn-hangzhou)

   • The flag: authorizationV4: true

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Document</title>
  </head>
  <body>
    <script
      type="text/javascript"
      src="https://gosspublic.alicdn.com/aliyun-oss-sdk-6.20.0.min.js"
    ></script>
    <script type="text/javascript">
      const client = new OSS({
        region: 'oss-cn-hangzhou',
        authorizationV4: true,
        // Use temporary credentials from Security Token Service (STS).
        accessKeyId: 'yourAccessKeyId',
        accessKeySecret: 'yourAccessKeySecret',
        stsToken: 'yourSecurityToken',
        bucket: 'examplebucket',
      });
    </script>
  </body>
</html>

C++

1. Upgrade OSS SDK for C++ to version 1.10.0 or later.

2. When initializing the client, set two additional values:

   • The region ID of the bucket

   • The signature version: SignatureVersionType::V4

#include <alibabacloud/oss/OssClient.h>
using namespace AlibabaCloud::OSS;

int main(void)
{
    std::string Endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
    std::string Region = "cn-hangzhou";

    InitializeSdk();

    ClientConfiguration conf;
    conf.signatureVersion = SignatureVersionType::V4;

    // Load credentials from environment variables.
    // Set OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET before running.
    auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>();
    OssClient client(Endpoint, credentialsProvider, conf);
    client.SetRegion(Region);

    ShutdownSdk();
    return 0;
}

C

1. Upgrade OSS SDK for C to version 3.11.0 or later.

2. When initializing the client, set two additional values:

   • The region ID of the bucket

   • The signature version: signature_version = 4

#include "oss_api.h"
#include "aos_http_io.h"

const char *endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
const char *region = "cn-hangzhou";

void init_options(oss_request_options_t *options)
{
    options->config = oss_config_create(options->pool);
    aos_str_set(&options->config->endpoint, endpoint);
    // Load credentials from environment variables.
    // Set OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET before running.
    aos_str_set(&options->config->access_key_id, getenv("OSS_ACCESS_KEY_ID"));
    aos_str_set(&options->config->access_key_secret, getenv("OSS_ACCESS_KEY_SECRET"));
    aos_str_set(&options->config->region, region);
    options->config->signature_version = 4;
    options->config->is_cname = 0;
    options->ctl = aos_http_controller_create(options->pool, 0);
}

int main() {
    aos_pool_t *p;
    oss_request_options_t *options;

    if (aos_http_io_initialize(NULL, 0) != AOSE_OK) {
        return -1;
    }

    aos_pool_create(&p, NULL);
    options = oss_request_options_create(p);
    init_options(options);

    /* Add your logic here. */

    aos_pool_destroy(p);
    aos_http_io_deinitialize();
    return 0;
}

Swift

All versions of OSS SDK for Swift use Signature V4 by default.

When initializing the client, specify the region ID of the bucket.

import AlibabaCloudOSS
import Foundation

@main
struct Main {
    static func main() async {
        let region = "cn-hangzhou"
        let endpoint: String? = nil  // Optional. Example: https://oss-cn-hangzhou.aliyuncs.com

        // Load credentials from environment variables.
        // Set OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET before running.
        let credentialsProvider = EnvironmentCredentialsProvider()

        let config = Configuration.default()
            .withRegion(region)
            .withCredentialsProvider(credentialsProvider)

        if let endpoint = endpoint {
            config.withEndpoint(endpoint)
        }

        let client = Client(config)
        _ = client
    }
}

iOS (Objective-C)

1. Upgrade OSS SDK for iOS to version 2.11.1 or later.

2. When initializing the client, set two additional values:

   • The region ID of the bucket

   • The signature version: OSSSignVersionV4

// Endpoint for the region where the bucket is located.
NSString *endpoint = @"https://oss-cn-hangzhou.aliyuncs.com";

// Use temporary credentials from Security Token Service (STS).
NSString *accessKeyId = @"yourAccessKeyId";
NSString *accessKeySecret = @"yourAccessKeySecret";
NSString *securityToken = @"yourSecurityToken";
NSString *region = @"cn-hangzhou";

id<OSSCredentialProvider> credentialProvider = [[OSSStsTokenCredentialProvider alloc]
    initWithAccessKeyId:accessKeyId
    secretKeyId:accessKeySecret
    securityToken:securityToken];

OSSClientConfiguration *configuration = [OSSClientConfiguration new];
configuration.signVersion = OSSSignVersionV4;

OSSClient *client = [[OSSClient alloc]
    initWithEndpoint:endpoint
    credentialProvider:credentialProvider
    clientConfiguration:configuration];
client.region = region;

Android

1. Upgrade OSS SDK for Android to version 2.3 or later.

2. When initializing the client, set two additional values:

   • The region ID of the bucket

   • The signature version: SignVersion.V4

// Endpoint for the region where the bucket is located.
String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";

// Use temporary credentials from Security Token Service (STS).
String accessKeyId = "yourAccessKeyId";
String accessKeySecret = "yourAccessKeySecret";
String securityToken = "yourSecurityToken";
String region = "cn-hangzhou";

OSSCredentialProvider credentialProvider =
    new OSSStsTokenCredentialProvider(accessKeyId, accessKeySecret, securityToken);

ClientConfiguration config = new ClientConfiguration();
config.setSignVersion(SignVersion.V4);

OSSClient oss = new OSSClient(getApplicationContext(), endpoint, credentialProvider);
oss.setRegion(region);

ossutil 2.0

All versions of ossutil 2.0 use Signature V4 by default.

The only change from Signature V1: set the Region parameter to the region ID of the bucket when configuring ossutil.

Please enter Region [cn-hangzhou]:cn-hangzhou

ossutil 1.0

All versions of ossutil 2.0 use Signature V4 by default. Consider migrating from ossutil 1.0 to ossutil 2.0 for a simpler upgrade path.

Version 1.7.12 and later of ossutil 1.0 support Signature V4.

Add two options to your commands:

• --sign-version v4

• --region <region-id>

./ossutil64 --sign-version v4 --region cn-hangzhou mb oss://examplebucket

ossfs 2.0

All versions of ossfs 2.0 (Preview) support Signature V4, but use Signature V1 by default.

Before upgrading:

1. Check your current version: ossfs --version

2. Unmount the file system. Replace <mountpoint> with your actual directory.

   Important

   Unmounting interrupts active services. Perform this step during off-peak hours.

      sudo umount <mountpoint>

3. Install the new version, then mount with the oss_region option set to the region ID of the bucket.

ossfs2 mount /tmp/ossfs2-bucket/ -c /etc/ossfs2.conf --oss_region=cn-hongkong

ossfs 1.0

Version 1.91.4 and later of ossfs 1.0 support Signature V4.

Before upgrading:

1. Check your current version: ossfs --version

2. Unmount the file system. Replace <mountpoint> with your actual directory.

   Important

   Unmounting interrupts active services. Perform this step during off-peak hours.

      sudo umount <mountpoint>

3. If your version meets the requirement (1.91.4 or later): Mount with the V4 options directly (see sample command below). If your version is earlier than 1.91.4: Uninstall the old version first. Then download and install the new version.

   • Installed via package manager: ``bash sudo apt remove ossfs # Ubuntu/Debian sudo yum remove ossfs # CentOS/Anolis/Alibaba Cloud Linux ``

   • Installed from source: ``bash sudo make uninstall ``

4. Mount with two additional options: -o sigv4 and -o region=<region-id>.

ossfs examplebucket -o sigv4 -o region=cn-hangzhou /tmp/ossfs \
  -o url=http://oss-cn-hangzhou.aliyuncs.com