org.bouncycastle.crypto.params

Class LMSPrivateKeyParameters

java.lang.Object

org.bouncycastle.crypto.params.AsymmetricKeyParameter

org.bouncycastle.crypto.params.LMSKeyParameters

org.bouncycastle.crypto.params.LMSPrivateKeyParameters

All Implemented Interfaces:

javax.security.auth.Destroyable, CipherParameters, LMSContextBasedSigner, Encodable

public class LMSPrivateKeyParameters
extends LMSKeyParameters
implements LMSContextBasedSigner, javax.security.auth.Destroyable

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	LMSPrivateKeyParameters(LMSigParameters sigParameters, LMOtsParameters otsParameters, int maxQ) Deprecated. This class is not intended to be subclassed; the constructor will be removed.
	LMSPrivateKeyParameters(LMSigParameters sigParameters, LMOtsParameters otsParameters, int q, byte[] I, int maxQ, byte[] masterSecret) An LMS private key positioned at one-time key q of the tree named by I (RFC 8554 sec. 5.2, Algorithm 5).

Method Summary

Modifier and Type	Method and Description
void	destroy() Destroy this key, zeroizing the master secret it holds.
boolean	equals(java.lang.Object o)
LMSPrivateKeyParameters	extractKeyShard(int usageCount) Return a key that can be used usageCount times.
static LMSPrivateKeyParameters	generate(LMSParameters lmsParameters, java.security.SecureRandom random) A fresh LMS private key (RFC 8554 sec. 5.2, Algorithm 5): the SEED (m bytes) and then the identifier I (16 bytes) are drawn from the random, in that order, and the key starts at q = 0 with all 2^h one-time keys available.
LMSContext	generateLMSContext()
byte[]	generateSignature(LMSContext context)
byte[]	getEncoded() Return a byte array representing the implementing object.
byte[]	getI()
int	getIndex() Return the key index (the q value).
int	getIndexLimit()
static LMSPrivateKeyParameters	getInstance(byte[] privEnc, byte[] pubEnc)
static LMSPrivateKeyParameters	getInstance(java.lang.Object src)
LMSParameters	getLMSParameters()
byte[]	getMasterSecret() Deprecated. use getEncoded() instead. A seed handed out alone is a second copy of the key with no index attached - the state duplication SP 800-208 rules out - whereas the encoding carries the index, usage limit and tree cache with it.
LMOtsParameters	getOtsParameters()
LMSPublicKeyParameters	getPublicKey() The public key of this tree, derived on first use and kept thereafter.
LMSigParameters	getSigParameters()
long	getUsagesRemaining()
int	hashCode()
boolean	isDestroyed()

Methods inherited from class org.bouncycastle.crypto.params.AsymmetricKeyParameter

isPrivate

Methods inherited from class java.lang.Object

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

Constructor Detail

LMSPrivateKeyParameters

public LMSPrivateKeyParameters(LMSigParameters sigParameters,
                               LMOtsParameters otsParameters,
                               int q,
                               byte[] I,
                               int maxQ,
                               byte[] masterSecret)

An LMS private key positioned at one-time key q of the tree named by I (RFC 8554 sec. 5.2, Algorithm 5). The identifier and master secret are copied, so the caller keeps its arrays.

LMSPrivateKeyParameters

@Deprecated
protected LMSPrivateKeyParameters(LMSigParameters sigParameters,
                                              LMOtsParameters otsParameters,
                                              int maxQ)

Deprecated. This class is not intended to be subclassed; the constructor will be removed.

A key with no position, identifier or seed of its own - the placeholder an HSS hierarchy is built with for the levels below the root, each of which resetKeyToIndex replaces from the level above before the key is used. The sentinel values are deliberately ones the public constructor refuses, so a placeholder can never be mistaken for a key that was merely built carelessly, and the key itself refuses to sign, publish, encode or derive from itself.

Method Detail

generate

public static LMSPrivateKeyParameters generate(LMSParameters lmsParameters,
                                               java.security.SecureRandom random)

A fresh LMS private key (RFC 8554 sec. 5.2, Algorithm 5): the SEED (m bytes) and then the identifier I (16 bytes) are drawn from the random, in that order, and the key starts at q = 0 with all 2^h one-time keys available.

getInstance

public static LMSPrivateKeyParameters getInstance(byte[] privEnc,
                                                  byte[] pubEnc)
                                           throws java.io.IOException

Throws:

java.io.IOException

getInstance

public static LMSPrivateKeyParameters getInstance(java.lang.Object src)
                                           throws java.io.IOException

Throws:

java.io.IOException

getIndex

public int getIndex()

Return the key index (the q value).

Returns:

private key index number.

generateLMSContext

public LMSContext generateLMSContext()

Specified by:

generateLMSContext in interface LMSContextBasedSigner

generateSignature

public byte[] generateSignature(LMSContext context)

Specified by:

generateSignature in interface LMSContextBasedSigner

extractKeyShard

public LMSPrivateKeyParameters extractKeyShard(int usageCount)

Return a key that can be used usageCount times.

Note: this will use the range [index...index + usageCount) for the current key.

Parameters:

usageCount - the number of usages the key should have.

Returns:

a key based on the current key that can be used usageCount times.

getLMSParameters

public LMSParameters getLMSParameters()

getSigParameters

public LMSigParameters getSigParameters()

getOtsParameters

public LMOtsParameters getOtsParameters()

getI

public byte[] getI()

getMasterSecret

@Deprecated
public byte[] getMasterSecret()

Deprecated. use getEncoded() instead. A seed handed out alone is a second copy of the key with no index attached - the state duplication SP 800-208 rules out - whereas the encoding carries the index, usage limit and tree cache with it.

Return a copy of the master seed of this tree.

destroy

public void destroy()

Destroy this key, zeroizing the master secret it holds.

The key identifier I, the parameter sets, the index and the cached Merkle tree nodes are retained - none of them is secret, and the public key stays derivable where the tree's root is already cached. After destruction isDestroyed() returns true and getMasterSecret(), getEncoded(), generateLMSContext() and the derivation of child trees throw IllegalStateException; a signature attempt fails before its one-time index is claimed. Note: keys repositioned within this tree or split off it with extractKeyShard(int) share its master secret array, so destroying this key invalidates them too.

Specified by:

destroy in interface javax.security.auth.Destroyable

isDestroyed

public boolean isDestroyed()

Specified by:

isDestroyed in interface javax.security.auth.Destroyable

getIndexLimit

public int getIndexLimit()

getUsagesRemaining

public long getUsagesRemaining()

Specified by:

getUsagesRemaining in interface LMSContextBasedSigner

getPublicKey

public LMSPublicKeyParameters getPublicKey()

The public key of this tree, derived on first use and kept thereafter.

Deliberately not taken under the key's monitor: the root node is a function of the identifier, the master secret and the parameter sets and not of q, so nothing the monitor guards takes part in deriving it, and holding the monitor for a tree build (up to 2^h leaf derivations) would stall every one-time key claim on the key for its duration. Concurrent callers race harmlessly - findT(int) already dedupes the expensive per-node work, so a second caller finds the tree built - and they publish equal keys.

equals

public boolean equals(java.lang.Object o)

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

getEncoded

public byte[] getEncoded()
                  throws java.io.IOException

Description copied from interface: Encodable

Return a byte array representing the implementing object.

Specified by:

getEncoded in interface Encodable

Specified by:

getEncoded in class LMSKeyParameters

Returns:

a byte array representing the encoding.

Throws:

java.io.IOException - if an issue arises generation the encoding.