Obiekty klucza i parametrów

W praktyce Tink udostępnia Key obiekty do reprezentowania klucze i obiekty Parameters reprezentujące Parameters. Na przykład w Javie mamy obiekty AesGcmKey do reprezentują klucze GCM AES.

W tej sekcji wyjaśniamy, jak zaprojektowano te obiekty w Javie i jak są one interakcje.

Obiekty Parameters

Weźmy pod uwagę AES GCM, powszechnie stosowany schemat szyfrowania AEAD. Tink udostępnia obiekt AesGcmParameters z informacjami niezbędnymi do: utwórz AesGcmKey, co omówimy później. Hierarchia parametrów w Javie wygląda tak:

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

Zgodnie z opisem w sekcji Zestawy kluczy, mechanizmy szyfrowania tagów, niektóre klucze muszą zawierać wymagany identyfikator, jeśli znajdują się w zestawie kluczy. Co Obiekt Parameters ma metodę hasIdRequirement, która określa, czy klucz utworzony przez ten obiekt Parameters będzie miał lub nie będzie miał wymagany identyfikator.

Następny obiekt AesGcmParameters udostępnia metody getKeySizeBytes(), getIvSizeBytes() i getTagSizeBytes(). Zwracają one długości użytego klucza, długości IV i długości wygenerowanego tagu, w bajtach. Chociaż Tink zapewnia niektóre z tych funkcji, nie zawsze pozwala na tworzenie elementów Aead dla każdej opcji. Na przykład obecnie AES GCM obsługuje tylko 12-bajtowe identyfikatory IV.

Obiekt AesGcmParameters zawiera też zastąpienia wartości z poprzedniej (oraz standardowe metody Java equals i hashCode) co jest uważane za sprawdzoną metodę).

Udostępnia też metody statyczne do tworzenia nowych obiektów AeadParameters. Weryfikują one dane wejściowe, tj. sprawdzają, czy rozmiar to 16, 24, czyli 32.

Kluczowe obiekty

Tink ma też hierarchię kluczy. Jeśli chodzi o przykład AES GCM, wygląda na to, podobny do tego:

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);
}

Metoda getIdRequirementOrNull zwraca identyfikator, który musi mieć ten klucz: lub null, jeśli nie ma wymagania. (Takie wymaganie dotyczące klucza wynika z faktu, że w niektórych przypadkach Tink poprzedza tekst szyfrowany lub podpisy ciągiem 0x01<id>, patrz sekcja na temat tagowania tekstu zaszyfrowanego).

Zawsze będzie to spójne z wynikami funkcji getParameters().hasIdRequirement() i osoby wdrażające nowe klas kluczy muszą to zapewnić.

Implementacje funkcji Key muszą też udostępniać metodę equalsKey do porównaj różne klucze. Taka metoda jest często przydatna, np. przy testowaniu derywacji klucza zainteresowane zapewnieniem wielokrotnego stosowania pochodnych, ten sam obiekt klucza. Ponadto KMS może sprawdzić, czy któryś z kluczy różnych użytkowników są jednakowe (co czasem zdarza się, gdy użytkownicy udostępniają i wielokrotnie prześlij je do tego samego KMS). Warto zauważyć, że nie zastępuj metody Java equals, ponieważ wymagałoby to zastąp hashCode, a nie będzie możliwości implementacji dyrektywy hashCode w bezpiecznym w sposób zgodny z zasadą equals bez przyjmowania niepotwierdzonych założeń.

Następnie wymagana jest metoda getParameters(). Dzięki temu użytkownicy mają dostęp do oryginalne informacje o parametrach użytych do utworzenia klucza.

AesGcmKey ma metodę getKeyBytes, która zwraca nieprzetworzony materiał klucza. Takie metody są bardzo typowe dla klas kluczy: są specyficzne dla danego typu, i zapewnić dostęp do bazowego materiału klucza. Dzięki nim użytkownicy mogą z zasady, np. zaimplementuj element podstawowy reprezentowany przez klucz, lub zserializować klucz, aby zapisać go na dysku lub wysłać za pośrednictwem Sam klucz odpowiada za ochronę materiału klucza przed nieupoważnionego dostępu. Na przykład SecretBytes wymaga tokena dostępu, aby: dostarczać materiały, (zobacz Kontrola dostępu).

Klucze asymetryczne

W przypadku asymetrycznych elementów podstawowych Tink używa 2 klas kluczy – jednej dla prywatnych i jednej dla kluczy publicznych. Dla parametru Parametry wygodniej jest użyć tego samego parametru class (ponieważ istnieje tylko jedna klasa, której można użyć do wygenerowania kluczy).

Tink ma również interfejs PrivateKey z dodatkowymi funkcja getPublicKey().