Object Storage Service：(Direkomendasikan) Tanda Tangan V4 dalam URL yang Ditandatangani

Gunakan SDK OSS untuk secara otomatis mengimplementasikan tanda tangan V4

SDK OSS mendukung implementasi otomatis tanda tangan V4. Kami merekomendasikan agar Anda menggunakan SDK OSS untuk memulai permintaan, sehingga tidak perlu menghitung tanda tangan secara manual. Untuk informasi lebih lanjut tentang implementasi tanda tangan untuk bahasa pemrograman tertentu, lihat kode contoh dari SDK OSS untuk bahasa pemrograman tersebut. Tabel berikut memberikan referensi ke kode contoh yang digunakan untuk menandatangani permintaan dengan menggunakan algoritma tanda tangan V4 saat menggunakan SDK OSS untuk berbagai bahasa pemrograman.

Penandatanganan URL

• Contoh

  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

  Untuk kemudahan pembacaan, bidang-bidang dalam parameter x-oss-credential di URL sebelumnya dipisahkan oleh garis miring (/). Saat memulai permintaan, URI-encode garis miring (/) di URL untuk mengonversinya menjadi %2F. Contoh:

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

• Parameter string kueri

  Parameter	Tipe	Diperlukan	Contoh	Deskripsi
  x-oss-signature-version	String	Ya	OSS4-HMAC-SHA256	Versi dan algoritma dari tanda tangan. Atur nilainya menjadi OSS4-HMAC-SHA256.
  x-oss-credential	String	Ya	LTAI********************/20241203/cn-hangzhou/oss/aliyun_v4_request	Kredensial yang dapat Anda gunakan untuk menghitung tanda tangan. Format: LTAI********************/<date>/<region>/oss/aliyun_v4_request AccessKeyId: ID AccessKey dalam pasangan AccessKey. date: tanggal ketika permintaan dimulai. region: wilayah tempat sumber daya yang diminta berada. oss: nama layanan yang diminta. Atur nilainya menjadi oss. aliyun_v4_request: deskripsi versi tanda tangan dalam permintaan. Atur nilainya menjadi aliyun_v4_request.
  x-oss-date	String	Ya	20241203T034420Z	Waktu ketika URL ditandatangani. Waktu mengikuti standar ISO 8601 dan ditampilkan dalam UTC. Catatan Waktu ini digunakan sebagai timestamp untuk string yang akan ditandatangani. Nilainya harus sama dengan nilai bidang date dalam kunci penandatanganan yang diperoleh.
  x-oss-expires	Integer	Ya	3600	Masa berlaku URL yang ditandatangani. Periode validitas dihitung dari nilai parameter x-oss-date. Unit: detik. Jika Anda menggunakan pasangan AccessKey, nilainya harus antara 1 dan 604.800 (7 hari). Jika Anda menggunakan kredensial akses sementara yang diperoleh dari Security Token Service (STS), nilainya harus antara 1 dan 43.200 (12 jam). Catatan Titik waktu ketika OSS menerima permintaan (T) harus memenuhi persyaratan berikut: (x-oss-date - 15 menit) ≤ T ≤ (x-oss-date + x-oss-expires). Jika T lebih awal dari nilai (x-oss-date - 15 menit), permintaan tidak valid. Jika waktu saat ini lebih lambat dari nilai (x-oss-date + x-oss-expires), permintaan tidak valid.
  x-oss-additional-headers	String	Tidak	host	Header yang ingin Anda tambahkan untuk menghitung tanda tangan. Misalnya, Anda dapat menambahkan header host untuk mencegah domain tempat permintaan dimulai dari diubah. Item berikut menggambarkan persyaratan untuk membangun header: Semua header dalam parameter x-oss-additional-headers harus dalam huruf kecil. Semua header dalam parameter x-oss-additional-headers harus diurutkan secara alfabetis. Semua header dalam array dipisahkan oleh titik koma (;) untuk mendapatkan string.
  x-oss-signature	String	Ya	77Dv****************	Deskripsi verifikasi tanda tangan. Parameter x-oss-signature tidak disertakan dalam perhitungan tanda tangan.
  x-oss-security-token	String	Tidak	CAIS********************************	Token keamanan yang dikeluarkan oleh STS. Parameter ini hanya diperlukan jika Anda menggunakan token keamanan untuk menghitung tanda tangan untuk URL.

Proses perhitungan tanda tangan

Metode yang digunakan untuk menghitung tanda tangan untuk URL serupa dengan metode yang digunakan untuk menghitung tanda tangan untuk header Otorisasi. Berikut adalah perbedaan utama antara kedua metode:

• Header x-oss-content-sha256 yang menggambarkan hash payload tidak digunakan untuk menghitung tanda tangan untuk URL. Saat membuat URL yang ditandatangani, Anda tidak dapat mengevaluasi konten payload. Sebagai gantinya, UNSIGNED-PAYLOAD digunakan.

• Jika kunci dalam parameter string kueri URL yang ditandatangani sama dengan header yang akan ditandatangani tetapi nilainya berbeda, kesalahan dilaporkan. Jika sebuah kunci memiliki beberapa nilai, semua nilai dari kunci dibandingkan pada saat yang sama. Jika nilainya berbeda, kesalahan dilaporkan.

• Jika Anda menggunakan kredensial akses sementara yang diperoleh dari STS untuk mengakses sumber daya OSS dalam URL yang ditandatangani, Anda harus menambahkan parameter x-oss-security-token ke string kueri URL.

• Parameter x-oss-signature dalam string kueri tidak disertakan dalam perhitungan tanda tangan.

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

Kode contoh lengkap untuk mendapatkan URL yang ditandatangani V4

Kode berikut memberikan contoh cara menghitung tanda tangan V4 untuk menghasilkan URL yang telah ditandatangani untuk permintaan GET. URL yang telah ditandatangani ini hanya dapat digunakan untuk operasi unduhan dan akses.

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 {

    /**
     * Alat perhitungan tanda tangan
     *
     * @return url
     */
    public static void main(String[] args) throws Exception {
        // Sebelum menjalankan kode contoh, pastikan bahwa variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET dikonfigurasi.
        String accesskeyid =  System.getenv().get("OSS_ACCESS_KEY_ID");
        String accesskeysecret =  System.getenv().get("OSS_ACCESS_KEY_SECRET");
        // Kueri dan tampilkan waktu saat ini. Waktu mengikuti standar ISO 8601 dan ditampilkan dalam 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'"));
        // Langkah 1: Buat permintaan kanonik.
        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);
        // Langkah 2: Buat string untuk ditandatangani.
        String stringToSign = "OSS4-HMAC-SHA256\n" +
                dateTimeStr + "\n" +
                dateStr + "/cn-hangzhou/oss/aliyun_v4_request\n" +
                DigestUtils.sha256Hex(canonicalRequest);

        // Langkah 3: Hitung tanda tangan.
        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);

        // Langkah 4: Tambahkan tanda tangan ke 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 {
            // Inisialisasi spesifikasi kunci HMAC, atur algoritma ke HMAC-SHA256, dan gunakan kunci yang disediakan.
            SecretKeySpec secretKeySpec = new SecretKeySpec(key, "HmacSHA256");

            // Dapatkan instance Mac dan gunakan metode getInstance untuk mengatur algoritma ke HMAC-SHA256.
            Mac mac = Mac.getInstance("HmacSHA256");
            // Gunakan kunci untuk menginisialisasi instance Mac.
            mac.init(secretKeySpec);

            // Hitung HMAC. Gunakan metode doFinal untuk memproses data dan kembalikan hasilnya sebagai array byte.
            byte[] hmacBytes = mac.doFinal(data.getBytes());

            return hmacBytes;
        } catch (Exception e) {
            throw new RuntimeException("Gagal menghitung HMAC-SHA256", e);
        }
    }
}

Contoh keluaran:

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

Referensi

• Jika Anda menggunakan URL yang ditandatangani untuk melihat pratinjau file .txt, karakter acak mungkin muncul di browser. Untuk informasi lebih lanjut, lihat Apa yang harus saya lakukan jika karakter acak muncul saat saya melihat pratinjau objek dalam format TXT secara online?

• Untuk informasi lebih lanjut tentang cara secara otomatis menghasilkan URL yang ditandatangani untuk mengunggah dan mengunduh objek dengan menggunakan SDK OSS untuk bahasa pemrograman umum, lihat Unggah objek menggunakan URL yang telah ditandatangani dan Unduh objek menggunakan URL yang telah ditandatangani.