com.yahoo.security.hpke.Kem Maven / Gradle / Ivy

Go to download
// Copyright Vespa.ai. Licensed under the terms of the Apache 2.0 license. See LICENSE in the project root.
package com.yahoo.security.hpke;

import com.yahoo.security.KeyUtils;

import java.security.KeyPair;
import java.security.interfaces.XECPrivateKey;
import java.security.interfaces.XECPublicKey;

/**
 * Key encapsulation mechanism (KEM)
 *
 * @author vekterli
 */
public interface Kem {

    record EncapResult(byte[] sharedSecret, byte[] enc) { }

    /**
     * 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"
     * 
     */
    EncapResult encap(XECPublicKey pkR);

    /**
     * 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."
     * 
     */
    EncapResult authEncap(XECPublicKey pkR, XECPrivateKey skS);

    /**
     * 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."
     * 
     */
    byte[] decap(byte[] enc, XECPrivateKey skR);

    /**
     * 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."
     * 
     */
    byte[] authDecap(byte[] enc, XECPrivateKey skR, XECPublicKey pkS);

    /** The length in bytes of a KEM shared secret produced by this KEM. */
    short nSecret();
    /** The length in bytes of an encapsulated key produced by this KEM. */
    short nEnc();
    /** The length in bytes of an encoded public key for this KEM. */
    short nPk();
    /** The length in bytes of an encoded private key for this KEM. */
    short nSk();
    /** Predefined KEM ID, as given in RFC 9180 section 7.1 */
    short kemId();

    /**
     * @return a HKEM(X25519, HKDF-SHA256) instance that generates new ephemeral X25519
     *         key pairs from a secure random source per {@link #encap(XECPublicKey)} invocation.
     */
    static Kem dHKemX25519HkdfSha256() {
        return new DHKemX25519HkdfSha256(KeyUtils::generateX25519KeyPair);
    }

    record UnsafeDeterminsticKeyPairOnlyUsedByTesting(KeyPair keyPair) {}

    /**
     * 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!
     */
    static Kem dHKemX25519HkdfSha256(UnsafeDeterminsticKeyPairOnlyUsedByTesting testingKP) {
        return new DHKemX25519HkdfSha256(() -> testingKP.keyPair);
    }

}