Object Storage Service:(推奨) URL に V4 署名を含める

OSS SDK を使用して V4 署名を自動的に実装する

OSS SDK は、V4 署名の自動実装をサポートしています。 リクエストを開始するには、OSS SDK を使用することをお勧めします。 これにより、署名を手動で計算する必要がなくなります。 特定のプログラミング言語の署名実装の詳細については、以下の表にある OSS SDK のサンプルコードファイルを参照してください。

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=20241203T034420Z&x-oss-expires=86400&x-oss-signature=70c542eaf652ac291c0c343d63ac24ede41c0526661d9d4c63c0906a2686160c&x-oss-signature-version=OSS4-HMAC-SHA256

  読みやすくするために、上記の URL の x-oss-credential パラメーターの値はスラッシュ (/) で区切られています。 リクエストを開始するときは、URL 内のスラッシュ (/) を URI エンコードして %2F に変換します。 例：

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

• クエリ文字列パラメーター

  パラメーター	タイプ	必須	例	説明
  x-oss-signature-version	文字列	はい	OSS4-HMAC-SHA256	署名のバージョンとアルゴリズム。 値を OSS4-HMAC-SHA256 に設定します。
  x-oss-credential	文字列	はい	LTAI********************/20241203/cn-hangzhou/oss/aliyun_v4_request	署名の計算に使用できるクレデンシャル。 形式： LTAI********************/<date>/<region>/oss/aliyun_v4_request AccessKeyId：AccessKey ペアの AccessKey ID。 date：リクエストが開始された日付。 region：リクエストされたリソースが存在するリージョン。 oss：リクエストされたサービスの名前。 値を oss に設定します。 aliyun_v4_request：リクエストの署名バージョンの説明。 値を aliyun_v4_request に設定します。
  x-oss-date	文字列	はい	20241203T034420Z	URL が署名された日時。ISO 8601 標準に準拠し、UTC で表示されます。 説明 日時は、署名対象文字列のタイムスタンプとして使用されます。 値は、派生署名キーの date フィールドの値と同じである必要があります。
  x-oss-expires	整数	はい	3600	署名付き URL の有効期間。x-oss-date パラメーターの値から計算されます。 単位：秒。 AccessKey ペアを使用して生成された署名付き URL の有効期間は、次の要件を満たす必要があります。最小値：1 秒。 最大値：604,800 秒 (7 日間)。 Security Token Service (STS) から取得した一時的なアクセスクレデンシャルを使用して生成された署名付き URL の有効期間は、次の要件を満たす必要があります。最小値：1 秒。 最大値：43,200 秒 (12 時間)。 説明 OSS がリクエストを受信する日時 (T) は、次の要件を満たす必要があります。(x-oss-date - 15 分) ≤ T ≤ (x-oss-date + x-oss-expires)。 T が値 (x-oss-date - 15 分) より前の場合、リクエストは無効です。 現在の日時が (x-oss-date + x-oss-expires) より後の場合、リクエストは無効です。
  x-oss-additional-headers	文字列	いいえ	host	署名の計算に追加するヘッダー。 たとえば、host ヘッダーを追加して、リクエストが開始されるドメイン名が変更されないようにすることができます。 ヘッダーを作成するための要件は以下のとおりです。 x-oss-additional-headers パラメーターのすべてのヘッダーは小文字にする必要があります。 x-oss-additional-headers パラメーターのすべてのヘッダーはアルファベット順にソートする必要があります。 配列内のすべてのヘッダーはセミコロン (;) で区切って文字列にします。
  x-oss-signature	文字列	はい	77Dv****************	署名検証の説明。 x-oss-signature パラメーターは署名の計算には含まれません。
  x-oss-security-token	文字列	いいえ	CAIS********************************	STS によって発行されたセキュリティトークン。 このパラメーターは、セキュリティトークンを使用して URL の署名を計算する場合にのみ必要です。

署名計算プロセス

URL の署名を計算する方法は、Authorization ヘッダーの署名を計算する方法と似ています。 以下では、2 つの方法の違いについて説明します。

• 署名付き URL を作成する場合、ペイロードコンテンツを評価できないため、ペイロードハッシュを記述する x-oss-content-sha256 ヘッダーは、URL の署名の計算には使用されません。その代わりに、UNSIGNED-PAYLOAD が使用されます。

• 署名付き URL のクエリ文字列パラメーターのキーが署名対象のヘッダーと同じであるが、値が異なる場合、エラーが報告されます。 キーに複数の値がある場合、キーのすべての値は同時に比較されます。 値が異なる場合、エラーが報告されます。

• STS から取得した一時的なアクセスクレデンシャルを使用して署名付き URL で OSS リソースにアクセスする場合は、URL のクエリ文字列に x-oss-security-token パラメーターを追加する必要があります。

• クエリ文字列の x-oss-signature パラメーターは署名の計算には含まれません。

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);

V4 署名付き URL を取得するために使用される完全なサンプルコード

以下のサンプルコードは、Java の OSS SDK を使用して V4 署名付き URL を計算する方法の例を示しています。 この URL は、オブジェクトのダウンロードとアクセスにのみ使用できます。

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 value. Use the doFinal method to receive the data to be calculated and return the calculation results in arrays. 
            byte[] hmacBytes = mac.doFinal(data.getBytes());

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

サンプル出力：

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

関連情報

• 生成された署名付き URL が格納されているファイルが TXT 形式の場合、ファイルをオンラインでプレビューすると文字化けが発生することがあります。 詳細については、「TXT 形式のオブジェクトをオンラインでプレビューすると文字化けが発生する場合はどうすればよいですか。」をご参照ください。

• 一般的なプログラミング言語の OSS SDK を使用して、オブジェクトをアップロードおよびダウンロードするための署名付き URL を自動的に生成する方法の詳細については、「事前署名済み URL を使用してオブジェクトをアップロードする」および「事前署名済み URL を使用してオブジェクトをダウンロードする」をご参照ください。