Objek Kunci dan Parameter

Dalam praktiknya, Tink menyediakan objek Key untuk diwakili keys dan objek Parameters untuk mewakili Parameters. Misalnya, di Java, kita memiliki objek AesGcmKey untuk mewakili kunci AES GCM.

Dalam bagian ini, kami akan menjelaskan bagaimana objek ini didesain di Java dan bagaimana objek tersebut berinteraksi.

Parameters objek

Pertimbangkan AES GCM, skema enkripsi AEAD yang banyak digunakan. Tink memberikan 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 pada ID-nya, ketika mereka berada dalam {i>keyset<i}. Setiap Objek Parameters memiliki metode hasIdRequirement yang menentukan apakah kunci yang dibuat oleh objek Parameters ini akan memiliki ID yang diperlukan atau tidak.

Selanjutnya objek AesGcmParameters menyediakan metode getKeySizeBytes(), getIvSizeBytes(), dan getTagSizeBytes(). Ini mengembalikan panjang kunci yang digunakan, panjang IV yang digunakan, dan panjang {i>tag<i} yang dihasilkan, dalam byte. Meskipun Tink menyediakan beberapa fungsi ini untuk kelengkapan, tidak selalu mengizinkan pembuatan Aead untuk setiap pilihan. Misalnya, saat ini hanya IV 12 byte yang didukung untuk AES GCM.

Objek AesGcmParameters juga menyediakan penggantian untuk elemen metode yang ditentukan (dan metode standar Java equals dan hashCode yang dianggap sebagai praktik yang baik).

Terakhir, menyediakan metode statis untuk membuat objek AeadParameters baru. Ini memvalidasi input, yaitu, mereka memeriksa bahwa ukurannya adalah salah satu dari 16, 24, atau 32.

Objek utama

Tink juga memiliki hierarki kunci. Tetap menggunakan contoh AES GCM, terlihat 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 kunci ini, atau null jika tidak ada persyaratan. (Persyaratan seperti ini berasal dari fakta bahwa Tink dalam beberapa kasus teks tersandi awalan atau tanda tangan dengan string 0x01<id>, lihat bagian tentang pemberian tag teks tersandi).

Ini akan selalu konsisten dengan hasil dari getParameters().hasIdRequirement() dan pengimplementasi kelas utama perlu memastikan hal ini.

Implementasi Key juga harus menyediakan metode equalsKey untuk membandingkan kunci yang berbeda. Seperti suatu metode sering kali berguna: misalnya saat menguji turunan kunci, salah satunya adalah tertarik untuk memastikan bahwa penerapan dari hasil turunan secara berulang objek kunci yang sama. KMS juga perlu memeriksa apakah ada kunci yang berikan kepada pengguna yang berbeda sama (yang kadang-kadang terjadi jika pengguna berbagi kunci dan menguploadnya ke KMS yang sama beberapa kali). Perlu dicatat bahwa kita jangan mengganti metode Java equals, karena ini mengharuskan kita untuk mengganti hashCode, dan tidak ada cara untuk menerapkan hashCode dalam yang kompatibel dengan equals tanpa membuat asumsi yang tidak terbukti.

Selanjutnya, kita memerlukan metode getParameters(). Hal ini memungkinkan pengguna mendapatkan informasi asli tentang Parameter yang digunakan untuk membuat kunci.

Terakhir, AesGcmKey memiliki metode getKeyBytes yang menampilkan materi kunci mentah. Metode ini sangat umum untuk class kunci: metode ini spesifik untuk jenisnya, dan menyediakan akses ke materi kunci yang mendasarinya. Dengan menggunakan hal tersebut, pengguna akan pada prinsipnya, misalnya menerapkan primitif yang direpresentasikan oleh kunci tersebut, atau melakukan serialisasi kunci untuk menyimpannya di {i>disk<i} atau mengirimkannya melalui jaringan. Kunci itu sendiri bertanggung jawab untuk 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 Key, satu untuk pribadi dan satu lagi untuk kunci publik. Untuk Parameter, akan lebih mudah untuk menggunakan parameter (karena hanya ada satu class yang dapat digunakan untuk membuat kunci).

Tink juga memiliki antarmuka PrivateKey dengan tambahan fungsi getPublicKey().