Token Web JSON (JWT)

Tink mendukung pembuatan dan verifikasi JWT, yang merupakan standar yang banyak digunakan di web. Implementasi JWT Tink menyediakan subset standar JWT yang ditentukan dalam RFC 7519 yang dianggap aman untuk digunakan oleh tim Tink, dan yang cocok dengan library Tink.

Tink tidak mendukung bagian standar yang jarang digunakan atau sulit digunakan dengan benar. Berikut batasannya:

• Tink hanya mendukung format JWS Compact Serialization. Serialisasi JSON JWS dan JWE tidak didukung.
• Tink tidak mendukung nilai None di header alg.
• Tink hanya mendukung header typ, alg, dan kid. Header lainnya tidak didukung.
• Tink tidak mengizinkan token diuraikan sebelum tanda tangan atau MAC diverifikasi.

Tanda Tangan JWT

Jika token dibuat dan diverifikasi oleh entitas yang berbeda, Anda harus menggunakan kunci asimetris dengan primitif JwtPublicKeySign dan JwtPublicKeyVerify. Kunci pribadi digunakan untuk membuat token, dan kunci publik digunakan untuk memverifikasi token. Algoritma yang didukung oleh primitif ini adalah: ES256, ES384, ES512, RS256, RS384, RS512, PS256, PS384, dan PS512.

Pilih jenis kunci

Tanda tangan JWT menggunakan jenis kunci yang berbeda dengan tanda tangan digital normal di Tink. Hal ini diperlukan karena beberapa metadata (seperti alg dan kid) perlu disimpan dengan kunci.

Sebaiknya gunakan JWT_ES256 untuk sebagian besar kasus penggunaan. Token yang dibuat dengan jenis kunci ini selalu memiliki header kid. Jika Anda lebih memilih token yang sedikit lebih pendek tanpa header kid, pilih jenis kunci JWT_ES256_RAW. Untuk semua jenis kunci yang didukung, lihat Jenis Kunci yang Didukung.

Distribusi set kunci publik

Tink memungkinkan set kunci publik dikonversi ke dan dari format Set JWK yang ditentukan dalam RFC 7517, yang dipahami oleh sebagian besar library JWT.

Catatan: Format serialisasi set kunci JSON Tink bukan Set JWK dan library lain kemungkinan tidak dapat membacanya.

Tink tidak mendukung ekspor kunci JWT publik dalam format lain. Alasannya adalah karena format lain tidak berisi metadata alg dan kid yang akan digunakan dalam verifikasi, sehingga penggunaannya lebih rentan terhadap error dan dapat membuat rotasi kunci menjadi lebih sulit.

Sebaiknya jangan hanya membagikan set kunci publik satu kali, tetapi sediakan cara untuk memperbarui set kunci publik secara otomatis. (Jika tidak, mengganti kunci enkripsi dengan kunci baru akan sangat sulit.) Hal ini sering dilakukan dengan memublikasikan set kunci publik di URL yang tepercaya dan aman. Server yang memverifikasi token kemudian harus mengambil ulang set kunci publik secara berkala dari URL tersebut, misalnya sekali per hari. Untuk merotasi kunci, kunci publik baru harus ditambahkan ke set kunci publik setidaknya satu hari sebelum digunakan untuk menandatangani token. Jika tidak, token baru yang ditandatangani dengan kunci pribadi baru akan ditolak oleh server yang masih menggunakan keyset kunci publik lama.

Catatan: Beberapa penerapan mengambil ulang kunci publik segera setelah token dengan header kid yang tidak diketahui diterima. Logika ini tidak dapat diterapkan di Tink, karena token tidak diuraikan sebelum diverifikasi. Sebaiknya Anda tidak melakukannya karena dapat menyebabkan banyak permintaan tambahan ke URL set kunci jika token berbahaya dengan header kid acak dikirim.

MAC JWT

Tink juga mendukung JWT dengan kunci simetris dengan primitif JwtMac. Gunakan primitif ini hanya jika token dibuat dan diverifikasi oleh entitas yang sama. Algoritma yang didukung oleh primitif ini adalah HS256, HS384, dan HS512.

Pilih jenis kunci

Jenis kunci MAC JWT berbeda dari jenis kunci MAC normal. Sebaiknya gunakan JWT_HS256 untuk sebagian besar kasus penggunaan.

Contoh kasus penggunaan

Lihat Saya ingin membuat dan memverifikasi JWT.