Objek Kunci dan Parameter

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().