Package org.conscrypt

Interface HpkeSpi

All Known Implementing Classes:
DuckTypedHpkeSpi, HpkeImpl, HpkeImpl.HpkeMlKemImpl, HpkeImpl.HpkeX25519Impl, HpkeImpl.HpkeXwingImpl, HpkeImpl.MlKem1024HkdfSha256Aes128Gcm, HpkeImpl.MlKem1024HkdfSha256Aes256Gcm, HpkeImpl.MlKem1024HkdfSha256ChaCha20Poly1305, HpkeImpl.MlKem768HkdfSha256Aes128Gcm, HpkeImpl.MlKem768HkdfSha256Aes256Gcm, HpkeImpl.MlKem768HkdfSha256ChaCha20Poly1305, HpkeImpl.X25519_AES_128, HpkeImpl.X25519_AES_256, HpkeImpl.X25519_CHACHA20, HpkeImpl.XwingHkdfSha256Aes128Gcm, HpkeImpl.XwingHkdfSha256Aes256Gcm, HpkeImpl.XwingHkdfSha256ChaCha20Poly1305
public interface HpkeSpi
SPI for HPKE clients to communicate with implementations. The client API can use any implementation which implements this interface, by duck-typing if necessary.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final byte[]
    DEFAULT_PSK
     
    static final byte[]
    DEFAULT_PSK_ID
     

  • Method Summary

    Modifier and Type
    Method
    Description
    byte[]
    engineExport(int length, byte[] context)
    Exports secret key material from this SPI as described in RFC 9180.
    void
    engineInitRecipient(byte[] encapsulated, PrivateKey recipientKey, byte[] info, PublicKey senderKey, byte[] psk, byte[] psk_id)
    Initialises an HPKE recipient SPI.
    void
    engineInitSender(PublicKey recipientKey, byte[] info, PrivateKey senderKey, byte[] psk, byte[] psk_id)
    Initialises an HPKE sender SPI.
    void
    engineInitSenderForTesting(PublicKey recipientKey, byte[] info, PrivateKey senderKey, byte[] psk, byte[] psk_id, byte[] sKe)
    Initialises an HPKE sender SPI.
    byte[]
    engineOpen(byte[] ciphertext, byte[] aad)
    Opens a message, using the internal key schedule maintained by an HPKE recipient.
    byte[]
    engineSeal(byte[] plaintext, byte[] aad)
    Seals a message, using the internal key schedule maintained by an HPKE sender.
    byte[]
    getEncapsulated()
    Returns the encapsulated key material for an HPKE sender.

  • Field Details

    • DEFAULT_PSK

      static final byte[] DEFAULT_PSK

    • DEFAULT_PSK_ID

      static final byte[] DEFAULT_PSK_ID

  • Method Details

    • engineInitSender

      void engineInitSender(PublicKey recipientKey, byte[] info, PrivateKey senderKey, byte[] psk, byte[] psk_id) throws InvalidKeyException
      Initialises an HPKE sender SPI.
      Parameters:
      recipientKey - public key of the recipient
      info - application-supplied information, may be null or empty
      senderKey - private key of the sender, for symmetric auth modes only, else null
      psk - pre-shared key, for PSK auth modes only, else null
      psk_id - pre-shared key ID, for PSK auth modes only, else null
      Throws:
      InvalidKeyException - if recipientKey is null or an unsupported key format
      UnsupportedOperationException - if mode is not a supported HPKE mode
      IllegalStateException - if this SPI has already been initialised

    • engineInitSenderForTesting

      void engineInitSenderForTesting(PublicKey recipientKey, byte[] info, PrivateKey senderKey, byte[] psk, byte[] psk_id, byte[] sKe) throws InvalidKeyException
      Initialises an HPKE sender SPI.
      Parameters:
      recipientKey - public key of the recipient
      info - application-supplied information, may be null or empty
      senderKey - private key of the sender, for symmetric auth modes only, else null
      psk - pre-shared key, for PSK auth modes only, else null
      psk_id - pre-shared key ID, for PSK auth modes only, else null
      sKe - optional random seed, should be null for all uses except for validation against known test vectors
      Throws:
      InvalidKeyException - if recipientKey is null or an unsupported key format or senderKey is an unsupported key format
      UnsupportedOperationException - if mode is not a supported HPKE mode
      IllegalStateException - if this SPI has already been initialised

    • engineInitRecipient

      void engineInitRecipient(byte[] encapsulated, PrivateKey recipientKey, byte[] info, PublicKey senderKey, byte[] psk, byte[] psk_id) throws InvalidKeyException
      Initialises an HPKE recipient SPI.
      Parameters:
      encapsulated - encapsulated ephemeral key from a sender
      recipientKey - private key of the recipient
      info - application-supplied information, may be null or empty
      senderKey - public key of sender, for asymmetric auth modes only, else null
      psk - pre-shared key, for PSK auth modes only, else null
      psk_id - pre-shared key ID, for PSK auth modes only, else null
      Throws:
      InvalidKeyException - if recipientKey is null or an unsupported key format or senderKey is an unsupported key format
      UnsupportedOperationException - if mode is not a supported HPKE mode
      IllegalStateException - if this SPI has already been initialised

    • engineSeal

      byte[] engineSeal(byte[] plaintext, byte[] aad)
      Seals a message, using the internal key schedule maintained by an HPKE sender.
      Parameters:
      plaintext - the plaintext
      aad - optional associated data, may be null or empty
      Returns:
      the ciphertext
      Throws:
      NullPointerException - if the plaintext is null
      IllegalStateException - if this SPI has not been initialised or if it was initialised as a recipient

    • engineOpen

      byte[] engineOpen(byte[] ciphertext, byte[] aad) throws GeneralSecurityException
      Opens a message, using the internal key schedule maintained by an HPKE recipient.
      Parameters:
      ciphertext - the ciphertext
      aad - optional associated data, may be null or empty
      Returns:
      the plaintext
      Throws:
      IllegalStateException - if this SPI has not been initialised or if it was initialised as a sender
      GeneralSecurityException - on decryption failures

    • engineExport

      byte[] engineExport(int length, byte[] context)
      Exports secret key material from this SPI as described in RFC 9180.
      Parameters:
      length - expected output length
      context - optional context string, may be null or empty
      Returns:
      exported value
      Throws:
      IllegalArgumentException - if the length is not valid for the KDF in use
      IllegalStateException - if this SPI has not been initialised

    • getEncapsulated

      byte[] getEncapsulated()
      Returns the encapsulated key material for an HPKE sender.
      Returns:
      the key material
      Throws:
      IllegalStateException - if this SPI has not been initialised or if it was initialised as a recipient