Dalam praktiknya, Tink menyediakan objek Key
untuk mewakili
kunci dan objek Parameters
untuk mewakili Parameters
.
Misalnya, pada Java, kita memiliki objek AesGcmKey
untuk
merepresentasikan kunci AES GCM.
Di bagian ini, kami akan menjelaskan cara objek ini didesain di Java dan cara interaksinya.
Objek Parameters
Pertimbangkan AES GCM, skema enkripsi AEAD yang banyak digunakan.
Tink menyediakan objek AesGcmParameters
dengan informasi yang diperlukan untuk
membuat AesGcmKey
, yang akan kami jelaskan nanti.
Hierarki parameter di Java terlihat seperti berikut:
public abstract class Parameters {
public abstract boolean hasIdRequirement();
}
public abstract class AeadParameters extends Parameters {}
public final class AesGcmParameters extends AeadParameters {
/**
* The Variant specified how ciphertexts are [tagged](/tink/design/keysets#tagging_ciphertexts).
*/
public static final class Variant {...}
/** A helper object to create new AesGcmParameters. */
public static final class Builder {...}
public int getKeySizeBytes() {...}
public int getIvSizeBytes() {...}
public int getTagSizeBytes() {...}
public Variant getVariant() {...}
public OutputPrefixType getOutputPrefixType() {...}
public boolean equals(Object object) {...}
public int hashCode() {...}
}
Seperti yang dijelaskan di bagian
Keyset, Pemberian Tag Ciphertext,
beberapa kunci memiliki persyaratan di ID-nya, saat berada dalam keyset. Setiap objek Parameters
memiliki metode hasIdRequirement
yang menentukan apakah kunci yang dibuat oleh objek Parameters
ini akan memiliki ID yang diperlukan tersebut, atau tidak.
Objek AesGcmParameters
berikutnya menyediakan metode getKeySizeBytes()
,
getIvSizeBytes()
, dan getTagSizeBytes()
. Fungsi ini menampilkan panjang
kunci yang digunakan, panjang IV yang digunakan, dan panjang tag yang dihasilkan,
dalam byte. Meskipun menyediakan beberapa fungsi ini untuk kelengkapan, Tink tidak selalu memungkinkan pembuatan Aead
untuk setiap pilihan. Misalnya, saat ini
hanya IV 12 byte yang didukung untuk AES GCM.
Objek AesGcmParameters
juga menyediakan penggantian untuk metode yang ditentukan sebelumnya (dan metode standar Java equals
dan hashCode
yang dianggap praktik yang baik).
Terakhir, bagian ini menyediakan metode statis untuk membuat objek AeadParameters
baru.
Kode ini memvalidasi input, yaitu, memeriksa bahwa ukurannya adalah salah satu dari 16, 24,
atau 32.
Objek utama
Tink juga memiliki hierarki kunci. Tetap menggunakan contoh AES GCM, tampilannya seperti ini:
public abstract class Key {
public abstract Parameters getParameters();
public abstract @Nullable Integer getIdRequirementOrNull();
public abstract boolean equalsKey(Key other);
}
public abstract class AeadKey extends Key {
public abstract AeadParameters getParameters();
public abstract Bytes getOutputPrefix();
}
public final class AesGcmKey implements AeadKey {
public SecretBytes getKeyBytes();
public abstract Bytes getOutputPrefix();
public AesGcmParameters getParameters();
public @Nullable Integer getIdRequirementOrNull();
public boolean equalsKey(Key object);
}
Metode getIdRequirementOrNull
menampilkan ID yang harus dimiliki oleh kunci ini, atau null
jika tidak ada persyaratan.
(Persyaratan pada kunci tersebut berasal dari fakta bahwa Tink dalam beberapa kasus memberikan awalan ciphertext atau tanda tangan dengan string 0x01<id>
. Lihat bagian tentang pemberian tag ciphertext).
Hal ini akan selalu konsisten dengan hasil
getParameters().hasIdRequirement()
dan pengimplementasi class kunci
baru harus memastikannya.
Implementasi Key
juga perlu menyediakan metode equalsKey
untuk
membandingkan kunci yang berbeda. Metode
tersebut sering kali berguna: misalnya saat menguji derivasi kunci, seseorang
tertarik untuk memastikan bahwa penerapan berulang dari derivasi tersebut menghasilkan
objek kunci yang sama. Selain itu, KMS juga perlu memeriksa apakah salah satu kunci yang diberikan kepada pengguna yang berbeda sama (yang kadang terjadi jika pengguna berbagi kunci dan menguploadnya ke KMS yang sama beberapa kali). Perlu diperhatikan bahwa kita
tidak mengganti metode Java equals
, karena hal ini akan mengharuskan kita
mengganti hashCode
, dan tidak ada cara untuk mengimplementasikan hashCode
dalam cara yang aman
yang kompatibel dengan equals
tanpa membuat asumsi yang belum terbukti.
Selanjutnya, kita memerlukan metode getParameters()
. Dengan begitu, pengguna dapat memperoleh informasi asli tentang Parameter yang digunakan untuk membuat kunci.
Terakhir, AesGcmKey
memiliki metode getKeyBytes
yang menampilkan material kunci mentah.
Metode tersebut sangat umum untuk class kunci: metode ini khusus untuk jenisnya,
dan menyediakan akses ke materi kunci yang mendasarinya. Dengan menggunakan hal tersebut, pengguna
pada prinsipnya dapat mengimplementasikan primitif yang diwakili oleh kunci,
atau membuat serialisasi kunci untuk menyimpannya di disk atau mengirimkannya melalui
jaringan. Kunci itu sendiri bertanggung jawab melindungi materi kunci dari
akses yang tidak sah. Misalnya, SecretBytes
memerlukan token akses untuk benar-benar menyediakan materi (lihat Kontrol Akses).
Kunci Asimetris
Untuk primitif asimetris, Tink menggunakan dua class Kunci, satu untuk kunci pribadi dan satu untuk kunci publik. Untuk Parameter, akan lebih mudah untuk menggunakan class yang sama (karena hanya ada satu class yang dapat digunakan untuk membuat kunci).
Tink juga memiliki antarmuka PrivateKey
dengan fungsi
tambahan getPublicKey()
.