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.

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 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()
ConcatKDF	clone()
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)
protected void	doInitialize()
static ConcatKDF	fromXMLObject(KeyDerivationMethod xmlObject)	Create and initialize a new instance from the specified XMLObject.
String	getAlgorithm()
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.utilities.java.support.component.AbstractInitializableComponent

destroy, doDestroy, initialize, isDestroyed, isInitialized

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_DIGEST_METHOD

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 Detail

ConcatKDF

public ConcatKDF()

Method Detail

getAlgorithm

public String getAlgorithm()

Specified by:

getAlgorithm in interface KeyDerivation

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

Specified by:

derive in interface KeyDerivation

Throws:

KeyDerivationException

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()

Specified by:

clone in interface CloneableKeyAgreementParameter

Overrides:

clone in class Object

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

public XMLObject buildXMLObject()

Specified by:

buildXMLObject in interface XMLExpressableKeyAgreementParameter

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