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 and 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) Deprecated. Use HSSPrivateKeyParameters.generate(HSSKeyGenerationParameters).
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) Deprecated. use LMSPublicKeyParameters.generateLMSContext(byte[]) instead.
static LMSContext	generateVerifyContext(LMSPublicKeyParameters publicKey, LMSSignature signature) The context a message is absorbed into before verifying a decoded LMS signature against a public key: the LM-OTS verification context of the leaf the signature names.
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 LMSPublicKeyParameters.generateLMSContext(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

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

Deprecated. use LMSPublicKeyParameters.generateLMSContext(byte[]) instead.

generateVerifyContext

public static LMSContext generateVerifyContext(LMSPublicKeyParameters publicKey,
                                               LMSSignature signature)

The context a message is absorbed into before verifying a decoded LMS signature against a public key: the LM-OTS verification context of the leaf the signature names. Public only because LMSPublicKeyParameters.generateLMSContext(byte[]) lives in another package; callers holding an encoded signature use that.

The typecode and leaf-number checks RFC 8554 sec. 5.4.2 requires before a signature is processed happen here: step 2g refuses a signature whose LMS typecode is not the one from the public key, and step 2i refuses a leaf number q outside the tree. Without the first, the path computation took its height and tree digest from the parameter set the signature named rather than the key's, so a signature claiming h25 drove a 25-level computation against an h5 key; without the second, an out-of-range q flowed into the node arithmetic and was left to be caught by the candidate-root comparison. Neither was a forgery under a secure hash - the domain separation and the final comparison saw to that - but both are work the specification says to refuse up front.

verifySignature

public static boolean verifySignature(LMSPublicKeyParameters publicKey,
                                      LMSContext context)

Verify the LMS signature a context from LMSPublicKeyParameters.generateLMSContext(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

@Deprecated
public static HSSPrivateKeyParameters generateHSSKeyPair(HSSKeyGenerationParameters parameters)

Deprecated. Use HSSPrivateKeyParameters.generate(HSSKeyGenerationParameters).

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) }.