JSON Web Token (JWT)

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

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

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

Tanda Tangan JWT

Jika token dibuat dan diverifikasi oleh entity 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.

Memilih 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 singkat tanpa header kid, pilih jenis kunci JWT_ES256_RAW. Untuk semua jenis kunci yang didukung, lihat Jenis Kunci yang Didukung.

Distribusi keyset publik

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

Catatan: Format serialisasi keyset JSON Tink bukan Set JWK dan library lain mungkin tidak akan dapat membacanya.

Tink tidak mendukung ekspor kunci JWT publik dalam format lainnya. Alasan ini adalah karena format lain tidak berisi metadata alg dan kid untuk digunakan dalam verifikasi, yang membuatnya lebih rentan terhadap error dan dapat mempersulit rotasi kunci.

Sebaiknya tidak hanya membagikan keyset publik satu kali, tetapi juga cara untuk mengupdate keyset publik secara otomatis. (Jika tidak, memutar ke kunci baru akan sangat sulit.) Hal ini sering dilakukan dengan memublikasikan keyset publik pada URL yang tepercaya dan aman. Server yang memverifikasi token kemudian harus mengambil ulang keyset publik dari URL tersebut secara berkala, misalnya sekali per hari. Untuk merotasi kunci, kunci publik baru harus ditambahkan ke keyset 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 publik lama.

Catatan: Beberapa implementasi akan mengambil ulang kunci publik segera setelah menerima token dengan header kid yang tidak dikenal. Logika ini tidak dapat diterapkan di Tink karena token tidak diurai sebelum diverifikasi. Kami tetap tidak merekomendasikan tindakan ini karena dapat menyebabkan banyak permintaan tambahan ke URL keyset jika token berbahaya dengan header kid acak dikirim.

MAC JWT

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

Memilih jenis kunci

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