Package org.opensaml.xmlsec.derivation.impl

# Class ConcatKDF

java.lang.Object
net.shibboleth.shared.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.

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`static class`
`ConcatKDF.Parser`
Implementation of `KeyAgreementParameterParser`.

## Field Summary

Fields
Modifier and Type
Field
Description
`private String`
`algorithmID`
AlgorithmID.
`static final String`
`DEFAULT_DIGEST_METHOD`
Default digest method.
`private String`
`digestMethod`
Digest method.
`private String`
`partyUInfo`
PartyUInfo.
`private String`
`partyVInfo`
PartyVInfo.
`private String`
`suppPrivInfo`
SuppPrivInfo.
`private String`
`suppPubInfo`
SuppPubInfo.

## Constructor Summary

Constructors
Constructor
Description
`ConcatKDF()`

## Method Summary

Modifier and Type
Method
Description
`XMLObject`
`buildXMLObject()`
Build an `XMLObject` instance representing this parameter.
`ConcatKDF`
`clone()`
Clone the parameter instance.
`protected byte[]`
`decodeParam(String value, String name)`
Decode the specified concatenation parameter value for input to the derivation operation.
`protected byte[]`
`derive(byte[] secret, byte[] otherInfo, Integer keyLength)`
Derive the key bytes.
`SecretKey`
`derive(byte[] secret, String keyAlgorithm, Integer keyLength)`
Derive a `SecretKey` from the specified secret.
`protected void`
`doInitialize()`
`static ConcatKDF`
`fromXMLObject(KeyDerivationMethod xmlObject)`
Create and initialize a new instance from the specified `XMLObject`.
`String`
`getAlgorithm()`
The key derivation algorithm URI.
`String`
`getAlgorithmID()`
Get the AlgorithmID in its unpadded hex-encoded form.
`protected org.bouncycastle.crypto.Digest`
`getDigestInstance(String digestURI)`
Get a new instance of the Bouncy Castle `Digest` for the specified digest algorithm URI.
`String`
`getDigestMethod()`
Get the digest method algorithm URI.
`String`
`getPartyUInfo()`
Get the PartyUInfo in its unpadded hex-encoded form.
`String`
`getPartyVInfo()`
Get the PartyVInfo in its unpadded hex-encoded form.
`String`
`getSuppPrivInfo()`
Get the SuppPrivInfo in its unpadded hex-encoded form.
`String`
`getSuppPubInfo()`
Get the SuppPubInfo in its unpadded hex-encoded form.
`protected static String`
`padParam(String value)`
Pad the specified concatenation parameter value for output in the formed required by XML Encryption 1.1.
`void`
`setAlgorithmID(String newAlgorithmID)`
Set the AlgorithmID in its unpadded hex-encoded form.
`void`
`setDigestMethod(String newDigestMethod)`
Set the digest method algorithm URI.
`void`
`setPartyUInfo(String newPartyUInfo)`
Set the PartyUInfo in its unpadded hex-encoded form.
`void`
`setPartyVInfo(String newPartyVInfo)`
Set the PartyVInfo in its unpadded hex-encoded form.
`void`
`setSuppPrivInfo(String newSuppPrivInfo)`
Set the SuppPrivInfo in its unpadded hex-encoded form.
`void`
`setSuppPubInfo(String newSuppPubInfo)`
Set the SuppPubInfo in its unpadded hex-encoded form.
`protected static String`
`unpadParam(String value, String name)`
Unpad the specified concatenation parameter value from the padded from required by XML Encryption 1.1 for input to the derivation operation.

### Methods inherited from class net.shibboleth.shared.component.AbstractInitializableComponent

`checkComponentActive, checkSetterPreconditions, destroy, doDestroy, ifDestroyedThrowDestroyedComponentException, ifInitializedThrowUnmodifiabledComponentException, ifNotInitializedThrowUninitializedComponentException, initialize, isDestroyed, isInitialized`

### Methods inherited from class java.lang.Object

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

## Field Details

### DEFAULT_DIGEST_METHOD

@Nonnull @NotEmpty public static final String DEFAULT_DIGEST_METHOD
Default digest method.

See Also:
  - Constant Field Values

### 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

@Nonnull 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

@Nonnull 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 supported, this method merely prepends "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 are supported, this method requires 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

@Nonnull 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