Package com.yahoo.security.hpke

Interface Kem

public interface Kem
Key encapsulation mechanism (KEM)
Author:
vekterli

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static final record 
    Kem.EncapResult
     
    static final record 
    Kem.UnsafeDeterminsticKeyPairOnlyUsedByTesting
     

  • Method Summary

    Modifier and Type
    Method
    Description
    byte[]
    authDecap(byte[] enc, XECPrivateKey skR, XECPublicKey pkS)
    Section 4 Cryptographic Dependencies: "Same as Decap(), and the recipient is assured that the KEM shared secret was generated by the holder of the private key skS."
    Kem.EncapResult
    authEncap(XECPublicKey pkR, XECPrivateKey skS)
    Section 4: Cryptographic Dependencies: "Same as Encap(), and the outputs encode an assurance that the KEM shared secret was generated by the holder of the private key skS."
    byte[]
    decap(byte[] enc, XECPrivateKey skR)
    Section 4 Cryptographic Dependencies: "Deterministic algorithm using the private key skR to recover the ephemeral symmetric key (the KEM shared secret) from its encapsulated representation enc."
    static Kem
    dHKemX25519HkdfSha256()
     
    static Kem
    dHKemX25519HkdfSha256(Kem.UnsafeDeterminsticKeyPairOnlyUsedByTesting testingKP)
    Returns an unsafe test KEM that returns a single fixed, deterministic key pair.
    Kem.EncapResult
    encap(XECPublicKey pkR)
    Section 4 Cryptographic Dependencies: "Randomized algorithm to generate an ephemeral, fixed-length symmetric key (the KEM shared secret) and a fixed-length encapsulation of that key that can be decapsulated by the holder of the private key corresponding to pkR"
    short
    kemId()
    Predefined KEM ID, as given in RFC 9180 section 7.1
    short
    nEnc()
    The length in bytes of an encapsulated key produced by this KEM.
    short
    nPk()
    The length in bytes of an encoded public key for this KEM.
    short
    nSecret()
    The length in bytes of a KEM shared secret produced by this KEM.
    short
    nSk()
    The length in bytes of an encoded private key for this KEM.

  • Method Details

    • encap

      Kem.EncapResult encap(XECPublicKey pkR)
      Section 4 Cryptographic Dependencies:
      "Randomized algorithm to generate an ephemeral, fixed-length symmetric key (the KEM shared secret) and a fixed-length encapsulation of that key that can be decapsulated by the holder of the private key corresponding to pkR"

    • authEncap

      Kem.EncapResult authEncap(XECPublicKey pkR, XECPrivateKey skS)
      Section 4: Cryptographic Dependencies:
      "Same as Encap(), and the outputs encode an assurance that the KEM shared secret was generated by the holder of the private key skS."

    • decap

      byte[] decap(byte[] enc, XECPrivateKey skR)
      Section 4 Cryptographic Dependencies:
      "Deterministic algorithm using the private key skR to recover the ephemeral symmetric key (the KEM shared secret) from its encapsulated representation enc."

    • authDecap

      byte[] authDecap(byte[] enc, XECPrivateKey skR, XECPublicKey pkS)
      Section 4 Cryptographic Dependencies:
      "Same as Decap(), and the recipient is assured that the KEM shared secret was generated by the holder of the private key skS."

    • nSecret

      short nSecret()
      The length in bytes of a KEM shared secret produced by this KEM.

    • nEnc

      short nEnc()
      The length in bytes of an encapsulated key produced by this KEM.

    • nPk

      short nPk()
      The length in bytes of an encoded public key for this KEM.

    • nSk

      short nSk()
      The length in bytes of an encoded private key for this KEM.

    • kemId

      short kemId()
      Predefined KEM ID, as given in RFC 9180 section 7.1

    • dHKemX25519HkdfSha256

      static Kem dHKemX25519HkdfSha256()
      Returns:
      a HKEM(X25519, HKDF-SHA256) instance that generates new ephemeral X25519 key pairs from a secure random source per encap(XECPublicKey) invocation.

    • dHKemX25519HkdfSha256

      static Kem dHKemX25519HkdfSha256(Kem.UnsafeDeterminsticKeyPairOnlyUsedByTesting testingKP)
      Returns an unsafe test KEM that returns a single fixed, deterministic key pair. As the name implies, this must only ever be used in the context of testing. If anyone tries to be clever and use this anywhere else, I will find them and bite them in the ankles!