Object Storage Service:（推奨）事前署名済み URL での V4 署名

OSS SDK を使用した V4 署名の自動実装

OSS SDK は、V4 署名の自動実装をサポートしています。 リクエストを開始するには、OSS SDK を使用することをお勧めします。 これにより、署名を手動で計算する必要がなくなります。 特定のプログラミング言語の署名実装の詳細については、そのプログラミング言語の OSS SDK のサンプルコードを参照してください。 次の表は、さまざまなプログラミング言語の OSS SDK を使用する場合に、V4 署名アルゴリズムを使用してリクエストに署名するために使用されるサンプルコードへの参照を示しています。

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********************/<日付>/<リージョン>/oss/aliyun_v4_request AccessKeyId：AccessKey ペアの AccessKey ID。 日付：リクエストが開始された日付。 リージョン：リクエストされたリソースが存在するリージョン。 oss：リクエストされたサービスの名前。 値を oss に設定します。 aliyun_v4_request：リクエストの署名バージョンの説明。 値を aliyun_v4_request に設定します。
  x-oss-date	文字列	はい	20241203T034420Z	URL が署名された時刻。 時刻は ISO 8601 標準に準拠し、UTC で表示されます。 説明 時刻は、署名対象文字列のタイムスタンプとして使用されます。 値は、派生署名キーの日付フィールドの値と同じである必要があります。
  x-oss-expires	整数	はい	3600	署名付き URL の有効期間。 有効期間は、x-oss-date パラメータの値から計算されます。 単位：秒。 AccessKey ペアを使用する場合、値は 1 ～ 604,800（7 日間）である必要があります。 Security Token Service (STS) から取得した一時的なアクセス認証情報を使用する場合、値は 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 つの方法の違いは次のとおりです。

• ペイロードハッシュを記述する x-oss-content-sha256 ヘッダーは、URL の署名の計算には使用されません。 署名付き 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(<リソース>) + "\n" +
UriEncode(<QueryParam1>) + "=" + UriEncode(<値>) + "&" + UriEncode(<QueryParam2>) + "\n" +
Lowercase(<HeaderName1>) + ":" + Trim(<値>) + "\n" + Lowercase(<HeaderName2>) + ":" + Trim(<値>) + "\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 を取得するために使用される完全なサンプルコード

次のコードは、GET リクエストの事前署名済み URL を生成するために V4 署名を計算する方法の例を示しています。 この事前署名済み 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 {

    /**
     * 署名計算ツール
     *
     * @return url
     */
    public static void main(String[] args) throws Exception {
        // サンプルコードを実行する前に、OSS_ACCESS_KEY_ID 環境変数と OSS_ACCESS_KEY_SECRET 環境変数が設定されていることを確認してください。
        String accesskeyid =  System.getenv().get("OSS_ACCESS_KEY_ID");
        String accesskeysecret =  System.getenv().get("OSS_ACCESS_KEY_SECRET");
        // 現在の時刻をクエリして表示します。 時刻は ISO 8601 標準に準拠し、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'"));
        // ステップ 1：正規リクエストを作成します。
        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);
        // ステップ 2：署名対象文字列を作成します。
        String stringToSign = "OSS4-HMAC-SHA256\n" +
                dateTimeStr + "\n" +
                dateStr + "/cn-hangzhou/oss/aliyun_v4_request\n" +
                DigestUtils.sha256Hex(canonicalRequest);

        // ステップ 3：署名を計算します。
        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);

        // ステップ 4：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 {
            // HMAC キー仕様を初期化し、アルゴリズムを HMAC-SHA256 に設定し、指定されたキーを使用します。
            SecretKeySpec secretKeySpec = new SecretKeySpec(key, "HmacSHA256");

            // Mac インスタンスを取得し、getInstance メソッドを使用してアルゴリズムを HMAC-SHA256 に設定します。
            Mac mac = Mac.getInstance("HmacSHA256");
            // キーを使用して Mac インスタンスを初期化します。
            mac.init(secretKeySpec);

            // HMAC を計算します。 doFinal メソッドを使用してデータを処理し、結果をバイト配列として返します。
            byte[] hmacBytes = mac.doFinal(data.getBytes());

            return hmacBytes;
        } catch (Exception e) {
            throw new RuntimeException("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 を使用したファイルのダウンロードまたはプレビュー」をご参照ください。