キーとパラメータ オブジェクト

実際には、Tink にはキーを表す Key オブジェクトと、Parameters を表す Parameters オブジェクトが用意されています。たとえば、Java には、AES GCM 鍵を表す AesGcmKey オブジェクトがあります。

このセクションでは、これらのオブジェクトが Java でどのように設計され、相互作用するかについて説明します。

Parameters 個のオブジェクト

広く使用されている AEAD 暗号化スキームである AES GCM を検討してください。Tink は、AesGcmKey の作成に必要な情報を含む AesGcmParameters オブジェクトを提供します。これについては後で説明します。Java のパラメータ階層は次のようになります。

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

鍵セット、暗号テキストのタグ付けのセクションで説明したように、一部の鍵は鍵セット内にある場合、ID に要件があります。すべての Parameters オブジェクトにはメソッド hasIdRequirement があり、この Parameters オブジェクトによって作成された鍵にそのような必須の ID があるかどうかを指定します。

次に、AesGcmParameters オブジェクトはメソッド getKeySizeBytes()、getIvSizeBytes()、getTagSizeBytes() を提供します。使用されている鍵の長さ、使用された IV の長さ、生成されたタグの長さがバイト単位で返されます。Tink には、完全性を期すためにこれらの関数の一部が用意されていますが、すべての選択肢に Aead を作成できない場合もあります。たとえば、AES GCM では現在 12 バイトの IV のみがサポートされています。

AesGcmParameters オブジェクトは、以前に定義したメソッド（および Java 標準メソッドの equals および hashCode）のオーバーライドも提供します。これらはおすすめの方法です。

最後に、新しい AeadParameters オブジェクトを作成するための静的メソッドを提供します。これらは入力を検証します。つまり、サイズが 16、24、32 のいずれかであることを確認します。

キーオブジェクト

Tink にも鍵の階層があります。AES GCM の例が続く場合は、次のようになります。

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

getIdRequirementOrNull メソッドは、このキーに必要な ID を返します。要件がない場合は null を返します。（この鍵に関する要件は、Tink が暗号テキストまたは署名の前に文字列 0x01<id> を付加する場合があるためです。暗号テキストのタグ付けのセクションをご覧ください）。

これは常に getParameters().hasIdRequirement() の結果と一致しており、新しい鍵クラスの実装者はこれを確保する必要があります。

Key の実装では、異なるキーを比較するメソッド equalsKey も用意する必要があります。多くの場合、このようなメソッドは有用です。たとえば、鍵導出をテストする場合、導出を繰り返し適用した場合に同じ鍵オブジェクトが生成されるようにする必要があります。また、KMS が異なるユーザーに提供する鍵が同一であるかどうかを確認する場合があります（これは、ユーザーが鍵を共有し、同じ KMS に複数回アップロードした場合に発生することがあります）。注目すべきは、Java メソッド equals をオーバーライドしないということです。これは、hashCode をオーバーライドする必要があるためです。また、実証されていない仮定なしに、equals と互換性のある安全な方法で hashCode を実装することはできません。

次に、getParameters() メソッドが必要です。これにより、ユーザーは鍵の作成に使用されたパラメータに関する元の情報を取得できます。

最後に、AesGcmKey には未加工の鍵マテリアルを返すメソッド getKeyBytes があります。このようなメソッドは鍵クラスでは非常に一般的で、型に固有で、基となる鍵マテリアルへのアクセスを提供します。これらを使用すると、原則として、鍵で表されるプリミティブを実装する、鍵をシリアル化してディスクへの保存やネットワーク経由での送信などを行うことができます。鍵自体は、不正アクセスから鍵マテリアルを保護する役割を担います。たとえば、SecretBytes は実際にコンテンツを提供するため、アクセス トークンを必要とします（アクセス制御をご覧ください）。

非対称鍵

非対称プリミティブの場合、Tink は 2 つの鍵クラス（秘密鍵用と公開鍵用）を使用します。パラメータの場合は、同じクラスを使用する（キーの生成に使用できるクラスが 1 つしかないため）便利です。

Tink には、追加の関数 getPublicKey() を持つインターフェース PrivateKey もあります。