Package org.bouncycastle.pqc.jcajce.provider.xmss

Class BCXMSSPrivateKey

  • All Implemented Interfaces:
    java.io.Serializable, java.security.Key, java.security.PrivateKey, javax.security.auth.Destroyable, XMSSKey, XMSSPrivateKey
    public class BCXMSSPrivateKey
extends java.lang.Object
implements java.security.PrivateKey, XMSSPrivateKey, javax.security.auth.Destroyable
    See Also:
    Serialized Form

    • Method Detail

      • getIndex

        public long getIndex()
        Description copied from interface: XMSSPrivateKey
        Return the index of the next signature.
        Specified by:
        getIndex in interface XMSSPrivateKey
        Returns:
        the index number for the next signature.

      • getUsagesRemaining

        public long getUsagesRemaining()
        Description copied from interface: XMSSPrivateKey
        Return the number of usages left for the private key.
        Specified by:
        getUsagesRemaining in interface XMSSPrivateKey
        Returns:
        the number of times the key can be used before it is exhausted.

      • extractKeyShard

        public XMSSPrivateKey extractKeyShard​(int usageCount)
        Description copied from interface: XMSSPrivateKey
        Return a key representing a shard of the key space that can be used usageCount times.

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

        Specified by:
        extractKeyShard in interface XMSSPrivateKey
        Parameters:
        usageCount - the number of usages the key should have.
        Returns:
        a key based on the current key that can be used usageCount times.

      • getAlgorithm

        public java.lang.String getAlgorithm()
        Specified by:
        getAlgorithm in interface java.security.Key

      • getFormat

        public java.lang.String getFormat()
        Specified by:
        getFormat in interface java.security.Key

      • getEncoded

        public byte[] getEncoded()
        Specified by:
        getEncoded in interface java.security.Key

      • equals

        public boolean equals​(java.lang.Object o)
        Whether these are the same key at the same position, which for a stateful key means the same traversal state too - the whole of which XMSSPrivateKeyParameters.equals(Object) decides, this being the line that asks it.

        It was written out here, over the accessors, and none of it belonged here: the fields it reads are the key parameters' own, the monitor a signature is taken under is the key parameters' own, and each accessor hands out a clone rather than a value that could be held still beside another key's. BCLMSPrivateKey is this same line over HSSPrivateKeyParameters, which is where the other stateful family in this provider keeps the same reasoning.

        The tree digest this class carries alongside the key parameters is not compared, because comparing it decides nothing: it is keyParams.getParameters().getTreeDigestOID() at every route a key here is constructed by, and that is the OID the key parameters compare.

        The PKCS#8 attributes are not compared either, and that one does change what equals says about two keys getEncoded() writes differently: attributes travel into the encoding, so one key loaded from a PKCS#8 carrying a friendlyName and one built from the same secret without it are equal here and encode to different bytes. That is the answer this class wants. What a stateful key is asked here is whether this is the same key at the same position - the question a one-time key signing twice is the failure of, RFC 8391 sec. 1.1 - and a label a caller attached on the way through a keystore moves neither the secret nor the index. BCLMSPrivateKey, which carries attributes the same way and is where this comparison came from, leaves them out for the same reason, as does BCMLDSAPrivateKey over its own parameters' encoding. A caller that does need the encodings to agree should compare the encodings.

        Overrides:
        equals in class java.lang.Object

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object

      • getHeight

        public int getHeight()
        Specified by:
        getHeight in interface XMSSKey

      • getTreeDigest

        public java.lang.String getTreeDigest()
        Specified by:
        getTreeDigest in interface XMSSKey

      • destroy

        public void destroy()
        Destroy this key, zeroizing the secret key material it holds.

        The secret key seed, the PRF key and the WOTS+ secret retained by the BDS traversal state are zeroized; the public seed, root, index and tree nodes are retained, so getIndex(), getUsagesRemaining(), getHeight() and getTreeDigest() keep working and hashCode() is stable. After destruction isDestroyed() returns true, getEncoded() and extractKeyShard(int) throw IllegalStateException, the key can no longer be serialized, and a Signature refuses it at initSign. Shards extracted before destruction hold their own copies of the seeds and are unaffected. As the underlying XMSSPrivateKeyParameters object is destroyed, keys sharing it are invalidated too.

        Specified by:
        destroy in interface javax.security.auth.Destroyable

      • isDestroyed

        public boolean isDestroyed()
        Specified by:
        isDestroyed in interface javax.security.auth.Destroyable