Package org.opensaml.xmlsec.derivation.impl

# Class PBKDF2

java.lang.Object
net.shibboleth.shared.component.AbstractInitializableComponent
org.opensaml.xmlsec.derivation.impl.PBKDF2

All Implemented Interfaces:
  `Cloneable`, `Component`, `DestructableComponent`, `InitializableComponent`, `CloneableKeyAgreementParameter`, `KeyAgreementParameter`, `XMLExpressableKeyAgreementParameter`, `KeyDerivation`

public class PBKDF2 extends AbstractInitializableComponent implements KeyDerivation, XMLExpressableKeyAgreementParameter, CloneableKeyAgreementParameter
Implementation of PBKDF2 key derivation as defined in XML Encryption 1.1.

## Nested Class Summary

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

## Field Summary

Fields
Modifier and Type
Field
Description
`static final Integer`
`DEFAULT_GENERATED_SALT_LENGTH`
Default length for generated salt, in bytes.
`static final Integer`
`DEFAULT_ITERATION_COUNT`
Default iteration count.
`static final String`
`DEFAULT_PRF`
Default PRF.
`private Integer`
`generatedSaltLength`
Generated salt length, in bytes.
`private Integer`
`iterationCount`
Iteration count.
`private Integer`
`keyLength`
Key length, in bits.
`private static final String`
`PBKDF2_JCA_ALGORITHM_BASE`
Base algorithm ID for PBKDF2 SecretKeyFactory.
`private String`
`prf`
Pseudo-random function algorithm.
`private String`
`salt`
Base64-encoded salt value.
`private SecureRandom`
`secureRandom`
SecureRandom generator for salt.

## Constructor Summary

Constructors
Constructor
Description
`PBKDF2()`

## Method Summary

Modifier and Type
Method
Description
`XMLObject`
`buildXMLObject()`
Build an `XMLObject` instance representing this parameter.
`PBKDF2`
`clone()`
Clone the parameter instance.
`SecretKey`
`derive(byte[] secret, String keyAlgorithm, Integer specifiedKeyLength)`
Derive a `SecretKey` from the specified secret.
`protected void`
`doInitialize()`
`static PBKDF2`
`fromXMLObject(KeyDerivationMethod xmlObject)`
Create and initialize a new instance from the specified `XMLObject`.
`String`
`getAlgorithm()`
The key derivation algorithm URI.
`protected Integer`
`getEffectiveKeyLength(String keyAlgorithm, Integer specifiedKeyLength)`
Get the effective key length, in bits.
`protected byte[]`
`getEffectiveSalt()`
Get the effective salt bytes to use.
`Integer`
`getGeneratedSaltLength()`
Get the generated salt length, in bytes.
`Integer`
`getIterationCount()`
Get the iteration count.
`Integer`
`getKeyLength()`
Get the key length, in number of bits.
`String`
`getPRF()`
Get the pseudo-random function algorithm URI.
`SecureRandom`
`getRandom()`
Get the secure random generator.
`String`
`getSalt()`
Get the Base64-encoded salt value.
`void`
`setGeneratedSaltLength(Integer length)`
Set the generated salt length, in bytes.
`void`
`setIterationCount(Integer count)`
Set the iteration count.
`void`
`setKeyLength(Integer length)`
Set the key length, in number of bits.
`void`
`setPRF(String uri)`
Set the pseudo-random function algorithm URI.
`void`
`setRandom(SecureRandom sr)`
Set the secure random generator.
`void`
`setSalt(String value)`
Set the Base64-encoded salt value.
`private static PBKDF2`
`validateAndSetXMLObjectParameters(PBKDF2Params xmlParams)`
Validate the `PBKDF2Params` instance.

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

@Nonnull @NotEmpty public static final String DEFAULT_PRF
Default PRF.

See Also:
  - Constant Field Values

### DEFAULT_ITERATION_COUNT

@Nonnull public static final Integer DEFAULT_ITERATION_COUNT
Default iteration count.

### DEFAULT_GENERATED_SALT_LENGTH

@Nonnull public static final Integer DEFAULT_GENERATED_SALT_LENGTH
Default length for generated salt, in bytes.

### PBKDF2_JCA_ALGORITHM_BASE

@Nonnull private static final String PBKDF2_JCA_ALGORITHM_BASE
Base algorithm ID for PBKDF2 SecretKeyFactory.

See Also:
  - Constant Field Values

### salt

@Nullable private String salt
Base64-encoded salt value.

### generatedSaltLength

@NonnullAfterInit private Integer generatedSaltLength
Generated salt length, in bytes.

### secureRandom

@NonnullAfterInit private SecureRandom secureRandom
SecureRandom generator for salt.

### iterationCount

@NonnullAfterInit private Integer iterationCount
Iteration count.

### keyLength

@Nullable private Integer keyLength
Key length, in bits.

### prf

@NonnullAfterInit private String prf
Pseudo-random function algorithm.

## Constructor Details

### PBKDF2

public PBKDF2()

## Method Details

### getAlgorithm

@Nonnull public String getAlgorithm()
The key derivation algorithm URI.

Specified by:
  `getAlgorithm` in interface `KeyDerivation`
Returns:
  the algorithm

### getSalt

@Nullable public String getSalt()
Get the Base64-encoded salt value.

Returns:
  the salt value

### setSalt

public void setSalt(@Nullable String value)
Set the Base64-encoded salt value.

Parameters:
  `value` - the salt

### getGeneratedSaltLength

@NonnullAfterInit public Integer getGeneratedSaltLength()
Get the generated salt length, in bytes.

Returns:
  the generated salt length, in bytes

### setGeneratedSaltLength

public void setGeneratedSaltLength(@Nullable Integer length)
Set the generated salt length, in bytes.

Parameters:
  `length` - the generated salt length

### getRandom

@NonnullAfterInit public SecureRandom getRandom()
Get the secure random generator.

Defaults to the platform default via `new SecureRandom()`

Returns:
  the secure random instance

### setRandom

public void setRandom(@Nullable SecureRandom sr)
Set the secure random generator.

Defaults to the platform default via `new SecureRandom()`

Parameters:
  `sr` - the secure random generator to set

### getIterationCount

@NonnullAfterInit public Integer getIterationCount()
Get the iteration count.

Returns:
  the iteration count

### setIterationCount

public void setIterationCount(@Nullable Integer count)
Set the iteration count.

Parameters:
  `count` - the iteration count

### getKeyLength

@Nullable public Integer getKeyLength()
Get the key length, in number of bits.

Note: KeyLength in expressed XML will be in bytes

Returns:
  the key length

### setKeyLength

public void setKeyLength(@Nullable Integer length)
Set the key length, in number of bits.

Note: KeyLength in expressed XML will be in bytes

Parameters:
  `length` - the key length

### getPRF

@NonnullAfterInit public String getPRF()
Get the pseudo-random function algorithm URI.

Returns:
  the algorithm URI

### setPRF

public void setPRF(@Nullable String uri)
Set the pseudo-random function algorithm URI.

Parameters:
  `uri` - the PRF URI

### 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 specifiedKeyLength) 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
  `specifiedKeyLength` - 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

### getEffectiveSalt

protected byte[] getEffectiveSalt() throws KeyDerivationException
Get the effective salt bytes to use.

Returns:
  the salt bytes
Throws:
  `KeyDerivationException` - if the salt value can not be successfully resolved

### getEffectiveKeyLength

protected Integer getEffectiveKeyLength(@Nonnull String keyAlgorithm, @Nullable Integer specifiedKeyLength) throws KeyDerivationException
Get the effective key length, in bits.

Parameters:
  `keyAlgorithm` - the algorithm for which the derived key will be used
  `specifiedKeyLength` - the explicitly specified key length
Returns:
  the effective key length, in bits
Throws:
  `KeyDerivationException` - if the key length can not be successfully resolved

### clone

public PBKDF2 clone()
Clone the parameter instance.

Specified by:
  `clone` in interface `CloneableKeyAgreementParameter`
Overrides:
  `clone` in class `Object`
Returns:
  the cloned parameter

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

### validateAndSetXMLObjectParameters

@Nonnull private static PBKDF2 validateAndSetXMLObjectParameters(@Nonnull PBKDF2Params xmlParams) throws ComponentInitializationException
Validate the `PBKDF2Params` instance.

Parameters:
  `xmlParams` - the instance to validate
Returns:
  the initialized `PBKDF2` object
Throws:
  `ComponentInitializationException` - if the specified params fails validation of required values