Package org.bouncycastle.crypto.signers.lms

Class LMSEngine

java.lang.Object

org.bouncycastle.crypto.signers.lms.LMSEngine

public final class LMSEngine
extends java.lang.Object

The LMS and HSS operations of RFC 8554 that the key parameter classes in org.bouncycastle.crypto.params and the key pair generators in org.bouncycastle.crypto.generators call into. This is the whole public surface of the engine: the value classes for one-time keys and signatures, the seed derivation and the encoding helpers are package-private and no compatibility is promised for them. Applications sign and verify through LMSSigner / HSSSigner, or the LMSContextBasedSigner / LMSContextBasedVerifier the key classes implement.

Method Summary

Modifier and Type	Method	Description
static byte[]	computeLeaf(Digest H, LMOtsParameters otsParameters, byte[] I, int r, int q, byte[] masterSecret)	Leaf node r of the tree: H(I || u32str(r) || u16str(D_LEAF) || OTS_PUB_HASH[q]), where the one-time public key for leaf q is derived from the master secret.
static byte[]	computeNode(Digest H, byte[] I, int r, byte[] left, byte[] right)	Interior node r of the tree: H(I || u32str(r) || u16str(D_INTR) || T[2r] || T[2r+1]).
static Digest	createDigest(LMSigParameters sigParameters)	The digest an LMS tree over the given parameters is built with.
static byte[][]	deriveChildKey(LMOtsParameters otsParameters, byte[] I, byte[] masterSecret, int q)	Derive the identifier and master seed of the tree below one-time key q of an LMS tree (the child of leaf q in an HSS hierarchy).
static HSSPrivateKeyParameters	generateHSSKeyPair(HSSKeyGenerationParameters parameters)	Generate an HSS private key: a root LMS key drawn from the parameters' random source, with the lower trees derived from it when the key is first positioned at index 0.
static byte[]	generateHSSSignature(int L, LMSContext context)	Complete and encode an HSS signature over the message absorbed into a context from generateSignContext(org.bouncycastle.crypto.params.LMSigParameters, org.bouncycastle.crypto.params.LMOtsParameters, byte[], int, byte[], byte[][]) that has had its chain attached with withSignedPublicKeys(org.bouncycastle.crypto.signers.lms.LMSContext, org.bouncycastle.crypto.signers.lms.LMSSignature[], org.bouncycastle.crypto.params.LMSPublicKeyParameters[]).
static LMSContext	generateHSSVerifyContext(HSSPublicKeyParameters publicKey, byte[] signature)	The context a message is absorbed into before verifying an encoded HSS signature against a public key: the signature's signed public key chain is decoded and attached, and the context is for its leaf tree.
static LMSSignature	generateSign(LMSContext context)	Complete an LMS signature over the message absorbed into a context from generateSignContext(org.bouncycastle.crypto.params.LMSigParameters, org.bouncycastle.crypto.params.LMOtsParameters, byte[], int, byte[], byte[][]).
static LMSContext	generateSignContext(LMSigParameters sigParameters, LMOtsParameters otsParameters, byte[] I, int q, byte[] masterSecret, byte[][] path)	The context a message is absorbed into before signing with one-time key q of an LMS tree (RFC 8554 sec. 5.4.1): the randomiser C is derived and the I || q || D_MESG || C prefix is already absorbed.
static LMSContext	generateVerifyContext(LMSPublicKeyParameters publicKey, byte[] signature)	The context a message is absorbed into before verifying an encoded LMS signature against a public key.
static boolean	verifyHSSSignature(HSSPublicKeyParameters publicKey, LMSContext context)	Verify the HSS signature a context from generateHSSVerifyContext(org.bouncycastle.crypto.params.HSSPublicKeyParameters, byte[]) carries over the message absorbed into it (RFC 8554 sec. 6.3): each chaining signature over the next tree's public key, then the leaf tree's signature over the message.
static boolean	verifySignature(LMSPublicKeyParameters publicKey, LMSContext context)	Verify the LMS signature a context from generateVerifyContext(org.bouncycastle.crypto.params.LMSPublicKeyParameters, byte[]) carries over the message absorbed into it (RFC 8554 sec. 5.4.2, Algorithm 6).
static LMSContext	withSignedPublicKeys(LMSContext context, LMSSignature[] signatures, LMSPublicKeyParameters[] publicKeys)	Attach the signed public key chain of an HSS signature (RFC 8554 sec. 6.1) to the context for its leaf tree, so that generateHSSSignature(int, LMSContext) can emit it.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

createDigest

public static Digest createDigest(LMSigParameters sigParameters)

The digest an LMS tree over the given parameters is built with.

computeLeaf

public static byte[] computeLeaf(Digest H,
                                 LMOtsParameters otsParameters,
                                 byte[] I,
                                 int r,
                                 int q,
                                 byte[] masterSecret)

Leaf node r of the tree: H(I || u32str(r) || u16str(D_LEAF) || OTS_PUB_HASH[q]), where the one-time public key for leaf q is derived from the master secret.

Parameters:

H - the tree digest, from createDigest(LMSigParameters); reset on return.

computeNode

public static byte[] computeNode(Digest H,
                                 byte[] I,
                                 int r,
                                 byte[] left,
                                 byte[] right)

Interior node r of the tree: H(I || u32str(r) || u16str(D_INTR) || T[2r] || T[2r+1]).

Parameters:

H - the tree digest, from createDigest(LMSigParameters); reset on return.

generateSignContext

public static LMSContext generateSignContext(LMSigParameters sigParameters,
                                             LMOtsParameters otsParameters,
                                             byte[] I,
                                             int q,
                                             byte[] masterSecret,
                                             byte[][] path)

The context a message is absorbed into before signing with one-time key q of an LMS tree (RFC 8554 sec. 5.4.1): the randomiser C is derived and the I || q || D_MESG || C prefix is already absorbed. Consumed by generateSign(LMSContext).

withSignedPublicKeys

public static LMSContext withSignedPublicKeys(LMSContext context,
                                              LMSSignature[] signatures,
                                              LMSPublicKeyParameters[] publicKeys)

Attach the signed public key chain of an HSS signature (RFC 8554 sec. 6.1) to the context for its leaf tree, so that generateHSSSignature(int, LMSContext) can emit it.

Parameters:

signatures - the L - 1 chaining signatures, signatures[i] made by tree i over the public key of tree i + 1.

publicKeys - the public keys of trees 1 .. L - 1.

generateSign

public static LMSSignature generateSign(LMSContext context)

Complete an LMS signature over the message absorbed into a context from generateSignContext(org.bouncycastle.crypto.params.LMSigParameters, org.bouncycastle.crypto.params.LMOtsParameters, byte[], int, byte[], byte[][]).

generateHSSSignature

public static byte[] generateHSSSignature(int L,
                                          LMSContext context)

Complete and encode an HSS signature over the message absorbed into a context from generateSignContext(org.bouncycastle.crypto.params.LMSigParameters, org.bouncycastle.crypto.params.LMOtsParameters, byte[], int, byte[], byte[][]) that has had its chain attached with withSignedPublicKeys(org.bouncycastle.crypto.signers.lms.LMSContext, org.bouncycastle.crypto.signers.lms.LMSSignature[], org.bouncycastle.crypto.params.LMSPublicKeyParameters[]).

Parameters:

L - the number of levels in the HSS key.

generateVerifyContext

public static LMSContext generateVerifyContext(LMSPublicKeyParameters publicKey,
                                               byte[] signature)

The context a message is absorbed into before verifying an encoded LMS signature against a public key. Consumed by verifySignature(LMSPublicKeyParameters, LMSContext).

Throws:

java.lang.IllegalStateException - if the signature does not decode.

verifySignature

public static boolean verifySignature(LMSPublicKeyParameters publicKey,
                                      LMSContext context)

Verify the LMS signature a context from generateVerifyContext(org.bouncycastle.crypto.params.LMSPublicKeyParameters, byte[]) carries over the message absorbed into it (RFC 8554 sec. 5.4.2, Algorithm 6).

generateHSSVerifyContext

public static LMSContext generateHSSVerifyContext(HSSPublicKeyParameters publicKey,
                                                  byte[] signature)

The context a message is absorbed into before verifying an encoded HSS signature against a public key: the signature's signed public key chain is decoded and attached, and the context is for its leaf tree. Consumed by verifyHSSSignature(HSSPublicKeyParameters, LMSContext).

Throws:

java.lang.IllegalStateException - if the signature does not decode or its level count does not match the key's.

verifyHSSSignature

public static boolean verifyHSSSignature(HSSPublicKeyParameters publicKey,
                                         LMSContext context)

Verify the HSS signature a context from generateHSSVerifyContext(org.bouncycastle.crypto.params.HSSPublicKeyParameters, byte[]) carries over the message absorbed into it (RFC 8554 sec. 6.3): each chaining signature over the next tree's public key, then the leaf tree's signature over the message.

generateHSSKeyPair

public static HSSPrivateKeyParameters generateHSSKeyPair(HSSKeyGenerationParameters parameters)

Generate an HSS private key: a root LMS key drawn from the parameters' random source, with the lower trees derived from it when the key is first positioned at index 0.

deriveChildKey

public static byte[][] deriveChildKey(LMOtsParameters otsParameters,
                                      byte[] I,
                                      byte[] masterSecret,
                                      int q)

Derive the identifier and master seed of the tree below one-time key q of an LMS tree (the child of leaf q in an HSS hierarchy).

Returns:

{ I of the child tree (16 bytes), master seed of the child tree (n bytes) }.