javax.crypto.spec.HPKEParameterSpec

すべての実装されたインタフェース:: AlgorithmParameterSpec

public finalクラスHPKEParameterSpec拡張オブジェクトは、AlgorithmParameterSpecを実装します

この不変クラスは、ハイブリッド公開キー暗号化(HPKE)アルゴリズムのCipherで使用されるパラメータのセットを指定します。 HPKEは、受信者の公開キーを使用して任意のサイズのプレーン・コンテキストを暗号化するための公開キー暗号化スキームです。これは、キー・カプセル化メカニズム(KEM)、キー導出関数(KDF)、および認証済暗号化と追加データ(AEAD)暗号を組み合せます。

暗号の標準アルゴリズム名は「HPKE」です。他のほとんどの暗号とは異なり、HPKEは"algorithm/mode/padding"形式の変換文字列として表現されません。したがって、Cipher.getInstanceの引数は、単一のアルゴリズム名「HPKE」である必要があります。

HPKEでは、送信者のCipherは常に暗号化モードで受信者の公開キーで初期化されますが、受信者のCipherオブジェクトは復号化モードで独自の秘密キーで初期化されます。

HPKEParameterSpecオブジェクトは、HPKEの暗号初期化で指定する必要があります。

of(int, int, int)静的メソッドは、指定されたKEM、KDFおよびAEADアルゴリズム識別子を持つHPKEParameterSpecオブジェクトを返します。「KEMアルゴリズム識別子」、「KDFアルゴリズム識別子」および「AEADアルゴリズム識別子」という用語は、RFC 9180の第7項で定義され、IANA HPKEページで保守される、それぞれの数値(特にkem_id、kdf_idおよびaead_id)を指します。

HPKEParameterSpecオブジェクトが作成されると、追加のメソッドを使用して、様々な機能を持つ新しいHPKEParameterSpecオブジェクトを生成できます。

アプリケーションが提供する情報は、withInfo(byte[])メソッドを使用して両側から指定できます。
事前共有キー(mode_psk)を使用して認証するには、両側でwithPsk(SecretKey, byte[])メソッドを使用して事前共有キーとその識別子を指定する必要があります。
非対称キー(mode_auth)を使用して認証するには、非対称キーをwithAuthKey(AsymmetricKey)メソッドを使用して指定する必要があります。正確には、送信者は独自の秘密キーを使用してこのメソッドをコールする必要があり、受信者は送信者の公開キーを使用してこのメソッドをコールする必要があります。
PSKと非対称キー(mode_auth_psk)の両方を使用して認証するには、前述のようにwithAuthKey(AsymmetricKey)メソッドとwithPsk(SecretKey, byte[])メソッドの両方をコールする必要があります。
HPKEでは、KEMステップ中に共有シークレットがネゴシエートされ、受信者が共有シークレットを回復できるように、キーカプセル化メッセージを送信者から受信者に送信する必要があります。送信側では、暗号が初期化されると、Cipher.getIV()メソッドを使用してキー・カプセル化メッセージを取得できます。受信者側では、このメッセージをwithEncapsulation(byte[])メソッドから取得したHPKEParameterSpecオブジェクトの一部として指定する必要があります。

相互運用性を実現するには、両側が同じアルゴリズム識別子を持ち、同一のinfo、pskおよびpsk_idを指定するか、一致する認証キーを指定する必要があります(指定されている場合)。 HPKEモードの詳細は、RFC 9180の第5項を参照してください。

HPKE暗号がパラメータなしで初期化されると、InvalidKeyExceptionがスローされます。

HPKE暗号初期化時に、指定されたキー・タイプをサポートするHPKE実装がない場合は、InvalidKeyExceptionがスローされます。提供されたHPKEParameterSpecがHPKE実装で受け入れられない場合は、InvalidAlgorithmParameterExceptionがスローされます。たとえば、

アルゴリズム識別子がサポートされていないか、指定されたキー・タイプと一致しません。
鍵のカプセル化メッセージが送信側に表示されます。
キーのカプセル化メッセージは、受信者側には提供されません。
withAuthKey(key)を使用しようとすると、互換性のないキーが使用されます。
withAuthKey(key)を使用しようとしましたが、mode_authまたはmode_auth_pskは、使用されるKEMアルゴリズムではサポートされていません。

初期化後、送信者と受信者の両方が、doFinal呼出しを繰り返し、オプションで1つ以上のupdateAADおよびupdateを前に付けて、複数のメッセージを順番に処理できます。各doFinalは、RFC 9180の第5.2項で指定されているように、内部シーケンス・カウンタから導出された個別のIVを使用して、完全なHPKE暗号化または復号化操作を実行します。受信者側では、各doFinalコールは1つの完全な暗号テキストに対応している必要があり、コールの数と順序は送信者側のものと一致する必要があります。これは、コール元が新しいIVを提供し、各メッセージの暗号を再初期化する必要があるAEAD暗号の直接使用とは異なります。 IVを内部的に管理することで、HPKEでは、単一の初期化で複数のメッセージをサポートしながら、IVの一意性を確保し、AEADのセキュリティを保証できます。

この例は、HPKEを使用してメッセージをX25519鍵ペアと安全に交換する送信者および受信者を示しています。

// Recipient key pair generation
KeyPairGenerator g = KeyPairGenerator.getInstance("X25519");
KeyPair kp = g.generateKeyPair();

// The HPKE sender cipher is initialized with the recipient's public
// key and an HPKEParameterSpec using specified algorithm identifiers
// and application-supplied info.
Cipher senderCipher = Cipher.getInstance("HPKE");
HPKEParameterSpec ps = HPKEParameterSpec.of(
                HPKEParameterSpec.KEM_DHKEM_X25519_HKDF_SHA256,
                HPKEParameterSpec.KDF_HKDF_SHA256,
                HPKEParameterSpec.AEAD_AES_128_GCM)
        .withInfo(HexFormat.of().parseHex("010203040506"));
senderCipher.init(Cipher.ENCRYPT_MODE, kp.getPublic(), ps);

// Retrieve the key encapsulation message (from the KEM step) from
// the sender.
byte[] kemEncap = senderCipher.getIV();

// The HPKE recipient cipher is initialized with its own private key,
// an HPKEParameterSpec using the same algorithm identifiers as used by
// the sender, and the key encapsulation message from the sender.
Cipher recipientCipher = Cipher.getInstance("HPKE");
HPKEParameterSpec pr = HPKEParameterSpec.of(
                HPKEParameterSpec.KEM_DHKEM_X25519_HKDF_SHA256,
                HPKEParameterSpec.KDF_HKDF_SHA256,
                HPKEParameterSpec.AEAD_AES_128_GCM)
        .withInfo(HexFormat.of().parseHex("010203040506"))
        .withEncapsulation(kemEncap);
recipientCipher.init(Cipher.DECRYPT_MODE, kp.getPrivate(), pr);

// Encryption and decryption
byte[] msg = "Hello World".getBytes(StandardCharsets.UTF_8);
byte[] ct = senderCipher.doFinal(msg);
byte[] pt = recipientCipher.doFinal(ct);

assert Arrays.equals(msg, pt);

実装上のノート:

このクラスは、KEM_DHKEM_P_256_HKDF_SHA256、KDF_HKDF_SHA256、AEAD_AES_128_GCMなどの標準アルゴリズム識別子の一部の定数を定義します。 HPKE Cipher実装は、ここで定義したアルゴリズム識別子のすべて、一部またはいずれもサポートしない場合があります。実装では、プライベート値や実験値など、ここに記載されていない追加の識別子をサポートすることもできます。

導入されたバージョン:

26

外部仕様

フィールドのサマリー

フィールド

修飾子と型

フィールド

説明

static final int

AEAD_AES_128_GCM

RFC 9180で定義されているAES-128-GCMのAEADアルゴリズム識別子。

static final int

AEAD_AES_256_GCM

RFC 9180で定義されているAES-256-GCMのAEADアルゴリズム識別子。

static final int

AEAD_CHACHA20_POLY1305

RFC 9180で定義されているChaCha20Poly1305のAEADアルゴリズム識別子。

static final int

EXPORT_ONLY

RFC 9180で定義されているエクスポート専用のAEADアルゴリズム識別子。

static final int

KDF_HKDF_SHA256

RFC 9180で定義されているHKDF-SHA256のKDFアルゴリズム識別子。

static final int

KDF_HKDF_SHA384

RFC 9180で定義されているHKDF-SHA384のKDFアルゴリズム識別子。

static final int

KDF_HKDF_SHA512

RFC 9180で定義されているHKDF-SHA512のKDFアルゴリズム識別子。

static final int

KEM_DHKEM_P_256_HKDF_SHA256

RFC 9180で定義されているDHKEM(P-256、HKDF-SHA256)のKEMアルゴリズム識別子。

static final int

KEM_DHKEM_P_384_HKDF_SHA384

RFC 9180で定義されているDHKEM(P-384、 HKDF-SHA384)のKEMアルゴリズム識別子。

static final int

KEM_DHKEM_P_521_HKDF_SHA512

RFC 9180で定義されているDHKEM(P-521、 HKDF-SHA512)のKEMアルゴリズム識別子。

static final int

KEM_DHKEM_X25519_HKDF_SHA256

RFC 9180で定義されているDHKEM(X25519、 HKDF-SHA256)のKEMアルゴリズム識別子。

static final int

KEM_DHKEM_X448_HKDF_SHA512

RFC 9180で定義されているDHKEM(X448、HKDF-SHA512)のKEMアルゴリズム識別子。
メソッドのサマリー

修飾子と型

メソッド

説明

int

aead_id()

AEADのアルゴリズム識別子を返します。

AsymmetricKey

authKey()

認証用のキーを返します。キーがない場合はnullを返します。

byte[]

encapsulation()

キーのカプセル化メッセージのコピーを返します。存在しない場合はnullを返します。

byte[]

info()

アプリケーションが提供する情報のコピーを返します。ない場合は空にします。

int

kdf_id()

KDFのアルゴリズム識別子を返します。

int

kem_id()

KEMのアルゴリズム識別子を返します。

static HPKEParameterSpec

of(int kem_id, int kdf_id, int aead_id)

指定されたKEM、KDFおよびAEADアルゴリズム識別子を持つ新しいHPKEParameterSpecオブジェクトを空のinfoでmode_baseモードで作成するファクトリ・メソッド。

SecretKey

psk()

事前共有キーを返します。存在しない場合はnullを返します。

byte[]

psk_id()

PSKの識別子のコピーを返します。存在しない場合は空です。

HPKEParameterSpec

withAuthKey(AsymmetricKey kS)

指定された認証キー値を使用して、新しいHPKEParameterSpecオブジェクトを作成します。

HPKEParameterSpec

withEncapsulation(byte[] encapsulation)

受信者が使用する指定されたキー・カプセル化メッセージ値を使用して、新しいHPKEParameterSpecオブジェクトを作成します。

HPKEParameterSpec

withInfo(byte[] info)

指定されたinfo値を使用して、新しいHPKEParameterSpecオブジェクトを作成します。

HPKEParameterSpec

withPsk(SecretKey psk, byte[] psk_id)

指定されたpskおよびpsk_id値を使用して、新しいHPKEParameterSpecオブジェクトを作成します。

クラスオブジェクトで宣言されたメソッド
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

修飾子と型

メソッド

説明

protected Object

clone()

このオブジェクトのコピーを作成して、返します。

boolean

equals(Object obj)

このオブジェクトと他のオブジェクトが等しいかどうかを示します。

protected void

finalize()

削除予定のため非推奨: このAPI要素は、将来のバージョンで削除される可能性があります。
最終決定は非推奨であり、将来のリリースで削除される可能性があります。

final Class<?>

getClass()

このObjectの実行時クラスを返します。

int

hashCode()

このオブジェクトに対するハッシュ・コード値を返します。

final void

notify()

このオブジェクトのモニターで待機中のスレッドを1つ再開します。

final void

notifyAll()

このオブジェクトのモニターで待機中のすべてのスレッドを再開します。

String

toString()

オブジェクトの文字列表現を返します。

final void

wait()

現在のスレッドが目覚めるまで待機します。通常、notifiedまたはinterruptedです。

final void

wait(long timeoutMillis)

現在のスレッドは、通常、notifiedまたはinterruptedであるか、一定のリアルタイムが経過するまで、目覚めるまで待機します。

final void

wait(long timeoutMillis, int nanos)

現在のスレッドは、通常、notifiedまたはinterruptedであるか、一定のリアルタイムが経過するまで、目覚めるまで待機します。

フィールド詳細
- KEM_DHKEM_P_256_HKDF_SHA256
  public static final int KEM_DHKEM_P_256_HKDF_SHA256
  
  RFC 9180で定義されているDHKEM(P-256、HKDF-SHA256)のKEMアルゴリズム識別子。
  
  関連項目:
  
  定数フィールド値
- KEM_DHKEM_P_384_HKDF_SHA384
  public static final int KEM_DHKEM_P_384_HKDF_SHA384
  
  RFC 9180で定義されているDHKEM(P-384、 HKDF-SHA384)のKEMアルゴリズム識別子。
  
  関連項目:
  
  定数フィールド値
- KEM_DHKEM_P_521_HKDF_SHA512
  public static final int KEM_DHKEM_P_521_HKDF_SHA512
  
  RFC 9180で定義されているDHKEM(P-521、 HKDF-SHA512)のKEMアルゴリズム識別子。
  
  関連項目:
  
  定数フィールド値
- KEM_DHKEM_X25519_HKDF_SHA256
  public static final int KEM_DHKEM_X25519_HKDF_SHA256
  
  RFC 9180で定義されているDHKEM(X25519、 HKDF-SHA256)のKEMアルゴリズム識別子。
  
  関連項目:
  
  定数フィールド値
- KEM_DHKEM_X448_HKDF_SHA512
  public static final int KEM_DHKEM_X448_HKDF_SHA512
  
  RFC 9180で定義されているDHKEM(X448、HKDF-SHA512)のKEMアルゴリズム識別子。
  
  関連項目:
  
  定数フィールド値
- KDF_HKDF_SHA256
  public static final int KDF_HKDF_SHA256
  
  RFC 9180で定義されているHKDF-SHA256のKDFアルゴリズム識別子。
  
  関連項目:
  
  定数フィールド値
- KDF_HKDF_SHA384
  public static final int KDF_HKDF_SHA384
  
  RFC 9180で定義されているHKDF-SHA384のKDFアルゴリズム識別子。
  
  関連項目:
  
  定数フィールド値
- KDF_HKDF_SHA512
  public static final int KDF_HKDF_SHA512
  
  RFC 9180で定義されているHKDF-SHA512のKDFアルゴリズム識別子。
  
  関連項目:
  
  定数フィールド値
- AEAD_AES_128_GCM
  public static final int AEAD_AES_128_GCM
  
  RFC 9180で定義されているAES-128-GCMのAEADアルゴリズム識別子。
  
  関連項目:
  
  定数フィールド値
- AEAD_AES_256_GCM
  public static final int AEAD_AES_256_GCM
  
  RFC 9180で定義されているAES-256-GCMのAEADアルゴリズム識別子。
  
  関連項目:
  
  定数フィールド値
- AEAD_CHACHA20_POLY1305
  public static final int AEAD_CHACHA20_POLY1305
  
  RFC 9180で定義されているChaCha20Poly1305のAEADアルゴリズム識別子。
  
  関連項目:
  
  定数フィールド値
- EXPORT_ONLY
  public static final int EXPORT_ONLY
  
  RFC 9180で定義されているエクスポート専用のAEADアルゴリズム識別子。
  
  関連項目:
  
  定数フィールド値
メソッドの詳細
- of
  
  public static HPKEParameterSpec of(int kem_id, int kdf_id, int aead_id)
  
  指定されたKEM、KDFおよびAEADアルゴリズム識別子を持つ新しいHPKEParameterSpecオブジェクトを空のinfoでmode_baseモードで作成するファクトリ・メソッド。
  
  パラメータ:
  
  kem_id - KEMのアルゴリズム識別子。0から65535の間である必要があります(この値を含む)
  
  kdf_id - KDFのアルゴリズム識別子。0から65535の間である必要があります(この値を含む)
  
  aead_id - AEADのアルゴリズム識別子。0から65535の間である必要があります(この値を含む)
  
  戻り値:
  
  新しいHPKEParameterSpecオブジェクト
  
  スロー:
  
  IllegalArgumentException - 入力値が範囲外の場合(0から65535の範囲内である必要があります)。
- withInfo
  
  public HPKEParameterSpec withInfo(byte[] info)
  
  指定されたinfo値を使用して、新しいHPKEParameterSpecオブジェクトを作成します。
  相互運用性のために、RFC 9180セクション7.2.1では、この値を最大64バイトに制限することをお薦めします。
  
  パラメータ:
  
  info - アプリケーションが提供する情報。この配列の内容は、後続の変更に影響されないようにコピーされる。
  
  戻り値:
  
  新しいHPKEParameterSpecオブジェクト
  
  スロー:
  
  NullPointerException - infoがnullの場合
  
  IllegalArgumentException - infoが空の場合。
- withPsk
  
  public HPKEParameterSpec withPsk(SecretKey psk, byte[] psk_id)
  
  指定されたpskおよびpsk_id値を使用して、新しいHPKEParameterSpecオブジェクトを作成します。
  RFC 9180セクション5.1.2では、PSKに少なくとも32バイトのエントロピーが必要です。相互運用性のために、RFC 9180セクション7.2.1では、キー・サイズおよび識別子の長さを最大64バイトに制限することをお薦めします。
  
  パラメータ:
  
  psk - 事前共有キー
  
  psk_id - PSKの識別子。この配列の内容は、後続の変更に影響されないようにコピーされる。
  
  戻り値:
  
  新しいHPKEParameterSpecオブジェクト
  
  スロー:
  
  NullPointerException - pskまたはpsk_idがnullの場合
  
  IllegalArgumentException - pskが32バイトより短い場合、またはpsk_idが空の場合
- withEncapsulation
  
  public HPKEParameterSpec withEncapsulation(byte[] encapsulation)
  
  受信者が使用する指定されたキー・カプセル化メッセージ値を使用して、新しいHPKEParameterSpecオブジェクトを作成します。
  
  パラメータ:
  
  encapsulation - キーのカプセル化メッセージ。この配列の内容は、後続の変更に影響されないようにコピーされる。
  
  戻り値:
  
  新しいHPKEParameterSpecオブジェクト
  
  スロー:
  
  NullPointerException - encapsulationがnullの場合
- withAuthKey
  
  public HPKEParameterSpec withAuthKey(AsymmetricKey kS)
  
  指定された認証キー値を使用して、新しいHPKEParameterSpecオブジェクトを作成します。
  ノート: このメソッドは、KEMアルゴリズムがmode_authまたはmode_auth_pskをサポートしているかどうかをチェックしません。結果のオブジェクトを使用してHPKE暗号をサポートされていないモードで初期化すると、その時点でInvalidAlgorithmParameterExceptionがスローされます。
  
  パラメータ:
  
  kS - 認証キー
  
  戻り値:
  
  新しいHPKEParameterSpecオブジェクト
  
  スロー:
  
  NullPointerException - kSがnullの場合
- kem_id
  
  public int kem_id()
  
  KEMのアルゴリズム識別子を返します。
  
  戻り値:
  
  KEMのアルゴリズム識別子
- kdf_id
  
  public int kdf_id()
  
  KDFのアルゴリズム識別子を返します。
  
  戻り値:
  
  KDFのアルゴリズム識別子
- aead_id
  
  public int aead_id()
  
  AEADのアルゴリズム識別子を返します。
  
  戻り値:
  
  AEADのアルゴリズム識別子
- info
  
  public byte[] info()
  
  アプリケーションが提供する情報のコピーを返します。ない場合は空にします。
  
  戻り値:
  
  アプリケーションが提供する情報のコピー。何もない場合は空
- psk
  
  public SecretKey psk()
  
  事前共有キーを返します。存在しない場合はnullを返します。
  
  戻り値:
  
  事前共有キー(存在しない場合はnull)
- psk_id
  
  public byte[] psk_id()
  
  PSKの識別子のコピーを返します。存在しない場合は空です。
  
  戻り値:
  
  PSKの識別子のコピー(存在しない場合は空)
- authKey
  
  public AsymmetricKey authKey()
  
  認証用のキーを返します。キーがない場合はnullを返します。
  
  戻り値:
  
  認証用のキー。ない場合はnull
- encapsulation
  
  public byte[] encapsulation()
  
  キーのカプセル化メッセージのコピーを返します。存在しない場合はnullを返します。
  
  戻り値:
  
  キーのカプセル化メッセージのコピー。ない場合はnull

クラスHPKEParameterSpec

フィールドのサマリー

メソッドのサマリー

クラスオブジェクトで宣言されたメソッド

フィールド詳細

KEM_DHKEM_P_256_HKDF_SHA256

KEM_DHKEM_P_384_HKDF_SHA384

KEM_DHKEM_P_521_HKDF_SHA512

KEM_DHKEM_X25519_HKDF_SHA256

KEM_DHKEM_X448_HKDF_SHA512

KDF_HKDF_SHA256

KDF_HKDF_SHA384

KDF_HKDF_SHA512

AEAD_AES_128_GCM

AEAD_AES_256_GCM

AEAD_CHACHA20_POLY1305

EXPORT_ONLY

メソッドの詳細

of

withInfo

withPsk

withEncapsulation

withAuthKey

kem_id

kdf_id

aead_id

info

psk

psk_id

authKey

encapsulation