Package org.opensaml.xmlsec.derivation.impl

Class ConcatKDF

java.lang.Object
net.shibboleth.utilities.java.support.component.AbstractInitializableComponent
org.opensaml.xmlsec.derivation.impl.ConcatKDF
All Implemented Interfaces:
Cloneable, Component, DestructableComponent, InitializableComponent, CloneableKeyAgreementParameter, KeyAgreementParameter, XMLExpressableKeyAgreementParameter, KeyDerivation
public class ConcatKDF extends AbstractInitializableComponent implements KeyDerivation, XMLExpressableKeyAgreementParameter, CloneableKeyAgreementParameter
Implementation of ConcatKDF key derivation as defined in XML Encryption 1.1.

The following rules apply to the concatenation parameters:

  • AlgorithmID
  • PartyUInfo
  • PartyVInfo
  • SuppPubInfo
  • SuppPrivInfo

Configured parameter string values must conform to the XML hexBinary representation defined in XML Encryption 1.1, section 5.4.1, except in unpadded form, with number of padding bits not indicated. Per the recommendation in the XML Encryption specification, this implementation only supports whole byte (bye-aligned) values, not arbitrary length bit-strings as theoretically allowed in the NIST specification, so the # of padding bits for each parameter value in the XML representation must and will always be 0. This means the methods unpadParam(String, String) and fromXMLObject(KeyDerivationMethod) which consume external values from the XML representation will throw if the number of indicated padding bits is non-zero. Similarly buildXMLObject() will always emit values which indicate 0 padding bits.

  • Field Details

    • DEFAULT_DIGEST_METHOD

      public static final String DEFAULT_DIGEST_METHOD
      Default digest method.
      See Also:

    • digestMethod

      @NonnullAfterInit private String digestMethod
      Digest method.

    • algorithmID

      @Nullable private String algorithmID
      AlgorithmID.

    • partyUInfo

      @Nullable private String partyUInfo
      PartyUInfo.

    • partyVInfo

      @Nullable private String partyVInfo
      PartyVInfo.

    • suppPubInfo

      @Nullable private String suppPubInfo
      SuppPubInfo.

    • suppPrivInfo

      @Nullable private String suppPrivInfo
      SuppPrivInfo.

  • Constructor Details

    • ConcatKDF

      public ConcatKDF()

  • Method Details

    • getAlgorithm

      public String getAlgorithm()
      The key derivation algorithm URI.
      Specified by:
      getAlgorithm in interface KeyDerivation
      Returns:
      the algorithm

    • getDigestMethod

      @NonnullAfterInit public String getDigestMethod()
      Get the digest method algorithm URI.
      Returns:
      the algorithm URI

    • setDigestMethod

      public void setDigestMethod(@Nullable String newDigestMethod)
      Set the digest method algorithm URI.
      Parameters:
      newDigestMethod - the algorithm URI

    • getAlgorithmID

      @Nullable public String getAlgorithmID()
      Get the AlgorithmID in its unpadded hex-encoded form.
      Returns:
      the AlgorithmID

    • setAlgorithmID

      public void setAlgorithmID(@Nullable String newAlgorithmID)
      Set the AlgorithmID in its unpadded hex-encoded form.
      Parameters:
      newAlgorithmID - the AlgorithmID

    • getPartyUInfo

      @Nullable public String getPartyUInfo()
      Get the PartyUInfo in its unpadded hex-encoded form.
      Returns:
      the PartyUInfo

    • setPartyUInfo

      public void setPartyUInfo(@Nullable String newPartyUInfo)
      Set the PartyUInfo in its unpadded hex-encoded form.
      Parameters:
      newPartyUInfo - the PartyUInfo

    • getPartyVInfo

      @Nullable public String getPartyVInfo()
      Get the PartyVInfo in its unpadded hex-encoded form.
      Returns:
      the PartyUInfo

    • setPartyVInfo

      public void setPartyVInfo(@Nullable String newPartyVInfo)
      Set the PartyVInfo in its unpadded hex-encoded form.
      Parameters:
      newPartyVInfo - the PartyVInfo

    • getSuppPubInfo

      @Nullable public String getSuppPubInfo()
      Get the SuppPubInfo in its unpadded hex-encoded form.
      Returns:
      the SuppPubInfo

    • setSuppPubInfo

      public void setSuppPubInfo(@Nullable String newSuppPubInfo)
      Set the SuppPubInfo in its unpadded hex-encoded form.
      Parameters:
      newSuppPubInfo - the SuppPubInfo

    • getSuppPrivInfo

      @Nullable public String getSuppPrivInfo()
      Get the SuppPrivInfo in its unpadded hex-encoded form.
      Returns:
      the SuppPrivInfo

    • setSuppPrivInfo

      public void setSuppPrivInfo(@Nullable String newSuppPrivInfo)
      Set the SuppPrivInfo in its unpadded hex-encoded form.
      Parameters:
      newSuppPrivInfo - the SuppPrivInfo

    • doInitialize

      protected void doInitialize() throws ComponentInitializationException
      Overrides:
      doInitialize in class AbstractInitializableComponent
      Throws:
      ComponentInitializationException

    • derive

      public SecretKey derive(@Nonnull byte[] secret, @Nonnull String keyAlgorithm, @Nullable Integer keyLength) throws KeyDerivationException
      Derive a SecretKey from the specified secret.
      Specified by:
      derive in interface KeyDerivation
      Parameters:
      secret - the input secret from which to derive the key.
      keyAlgorithm - the algorithm URI for which the derived key will be used
      keyLength - the length of the derived key. This may be null if the keyAlgorithm URI implies a key length, for example if the URI represents a KeyLengthSpecifiedAlgorithm. However if the URI implies a key length and this parameter value does not match that length, that is an error and and exception will be thrown
      Returns:
      the derived key
      Throws:
      KeyDerivationException - if the key derivation operation is not completed successfully

    • derive

      protected byte[] derive(@Nonnull byte[] secret, @Nonnull byte[] otherInfo, @Nonnull Integer keyLength) throws KeyDerivationException
      Derive the key bytes.

      This re-factored method mostly exists to facilitate unit testing using external test vectors which only specify the OtherInfo as an input, rather than its 5 constituent parts as defined in NIST SP 800-56A and XML Encryption 1.1.

      Parameters:
      secret - the input secret from which to derive the key
      otherInfo - the OtherInfo bit string as defined in NIST SP 800-56A
      keyLength - the length of the derived key, in bits
      Returns:
      the derived key bytes
      Throws:
      KeyDerivationException - if key derivation does not complete successfully

    • getDigestInstance

      @Nonnull protected org.bouncycastle.crypto.Digest getDigestInstance(@Nonnull String digestURI) throws KeyDerivationException
      Get a new instance of the Bouncy Castle Digest for the specified digest algorithm URI.
      Parameters:
      digestURI - the digest algorithm URI
      Returns:
      a new corresponding instance of BC Digest
      Throws:
      KeyDerivationException - if the specified digest algorithm is unsupported

    • clone

      public ConcatKDF clone()
      Clone the parameter instance.
      Specified by:
      clone in interface CloneableKeyAgreementParameter
      Overrides:
      clone in class Object
      Returns:
      the cloned parameter

    • decodeParam

      @Nonnull protected byte[] decodeParam(@Nullable String value, @Nonnull String name) throws KeyDerivationException
      Decode the specified concatenation parameter value for input to the derivation operation.
      Parameters:
      value - the value to process
      name - the name of the value being processed, for diagnostic purposes
      Returns:
      the decoded value, which may be an empty array
      Throws:
      KeyDerivationException - if parameter value could not be decoded successfully

    • padParam

      @Nullable protected static String padParam(@Nullable String value)
      Pad the specified concatenation parameter value for output in the formed required by XML Encryption 1.1.

      No syntactic validation is done on the input value. Since only whole byte-aligned values are not supported, this method merely pre-pends "00" to indicate 0 padding bits.

      Parameters:
      value - the value to process
      Returns:
      the padded value, which may be null

    • unpadParam

      @Nullable protected static String unpadParam(@Nullable String value, @Nullable String name) throws KeyDerivationException
      Unpad the specified concatenation parameter value from the padded from required by XML Encryption 1.1 for input to the derivation operation.

      Since only whole byte-aligned values supported, this method required input values to begin with "00", indicating 0 padding bits.

      Parameters:
      value - the value to process
      name - the name of the value being processed, for diagnostic purposes
      Returns:
      the unpadded value, which may be null
      Throws:
      KeyDerivationException - if the input value is invalid

    • buildXMLObject

      public XMLObject buildXMLObject()
      Build an XMLObject instance representing this parameter.
      Specified by:
      buildXMLObject in interface XMLExpressableKeyAgreementParameter
      Returns:
      the XML object instance

    • fromXMLObject

      @Nonnull public static ConcatKDF fromXMLObject(@Nonnull KeyDerivationMethod xmlObject) throws ComponentInitializationException
      Create and initialize a new instance from the specified XMLObject.
      Parameters:
      xmlObject - the XML object
      Returns:
      new parameter instance
      Throws:
      ComponentInitializationException - if component initialization fails