net.shibboleth.utilities.java.support.security

Class DataSealer

java.lang.Object

net.shibboleth.utilities.java.support.component.AbstractInitializableComponent

net.shibboleth.utilities.java.support.security.DataSealer

All Implemented Interfaces:

Component, DestructableComponent, InitializableComponent

public class DataSealer
extends AbstractInitializableComponent

Applies a MAC to time-limited information and encrypts with a symmetric key.

Field Summary

Fields

Modifier and Type	Field and Description
private static int	CHUNK_SIZE Size of UTF-8 data chunks to read/write.
private org.apache.commons.codec.BinaryDecoder	decoder Decodes encrypted string to bytes.
private org.apache.commons.codec.BinaryEncoder	encoder Encodes encrypted bytes to string.
private DataSealerKeyStrategy	keyStrategy Source of keys.
private boolean	lockedAtStartup Whether the key source is expected to be locked initially.
private org.slf4j.Logger	log Class logger.
private SecureRandom	random Source of secure random data.

Constructor Summary

Constructors

Constructor and Description
DataSealer()

Method Summary

Modifier and Type	Method and Description
void	doInitialize() Performs the initialization of the component.
private String	extractAndCheckDecryptedData(byte[] decryptedBytes) Extract the GZIP'd data and test for expiration before returning it.
void	setDecoder(org.apache.commons.codec.BinaryDecoder d) Sets the decoder to use to convert a ciphertext string to bytes.
void	setEncoder(org.apache.commons.codec.BinaryEncoder e) Sets the encoder to use to produce a ciphertext string from bytes.
void	setKeyStrategy(DataSealerKeyStrategy strategy) Set the key strategy.
void	setLockedAtStartup(boolean flag) Set whether the key source is expected to be locked at startup, and unlocked later at runtime.
void	setRandom(SecureRandom r) Set the pseudorandom generator.
private void	testEncryption(SecretKey key) Run a test over the configured bean properties.
String	unwrap(String wrapped) Decrypts and verifies an encrypted bundle created with wrap(String, long).
String	unwrap(String wrapped, StringBuffer keyUsed) Decrypts and verifies an encrypted bundle created with wrap(String, long), optionally returning the label of the key used to encrypt the data.
String	wrap(String data, long exp) Encodes data into an AEAD-encrypted blob, gzip(exp|data) exp = expiration time of the data; 8 bytes; Big-endian data = the data; a UTF-8-encoded string

Methods inherited from class net.shibboleth.utilities.java.support.component.AbstractInitializableComponent

destroy, doDestroy, initialize, isDestroyed, isInitialized

Methods inherited from class java.lang.Object

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

Field Detail

CHUNK_SIZE

private static final int CHUNK_SIZE

Size of UTF-8 data chunks to read/write.

See Also:

Constant Field Values

log

@Nonnull
private org.slf4j.Logger log

Class logger.

lockedAtStartup

private boolean lockedAtStartup

Whether the key source is expected to be locked initially.

keyStrategy

@NonnullAfterInit
private DataSealerKeyStrategy keyStrategy

Source of keys.

random

@NonnullAfterInit
private SecureRandom random

Source of secure random data.

encoder

@Nonnull
private org.apache.commons.codec.BinaryEncoder encoder

Encodes encrypted bytes to string.

decoder

@Nonnull
private org.apache.commons.codec.BinaryDecoder decoder

Decodes encrypted string to bytes.

Constructor Detail

DataSealer

public DataSealer()

Method Detail

setLockedAtStartup

public void setLockedAtStartup(boolean flag)

Set whether the key source is expected to be locked at startup, and unlocked later at runtime.

Defaults to false.

Parameters:

flag - flag to set

Since:

7.4.0

setKeyStrategy

public void setKeyStrategy(@Nonnull
                           DataSealerKeyStrategy strategy)

Set the key strategy.

Parameters:

strategy - key strategy

setRandom

public void setRandom(@Nonnull
                      SecureRandom r)

Set the pseudorandom generator.

Parameters:

r - the pseudorandom generator to set

setEncoder

public void setEncoder(@Nonnull
                       org.apache.commons.codec.BinaryEncoder e)

Sets the encoder to use to produce a ciphertext string from bytes. Default is standard base-64 encoding without line breaks.

Parameters:

e - Byte-to-string encoder.

setDecoder

public void setDecoder(@Nonnull
                       org.apache.commons.codec.BinaryDecoder d)

Sets the decoder to use to convert a ciphertext string to bytes. Default is standard base-64 decoding.

Parameters:

d - String-to-byte decoder.

doInitialize

public void doInitialize()
                  throws ComponentInitializationException

Performs the initialization of the component. This method is executed within the lock on the object being initialized. The default implementation of this method is a no-op.

Overrides:

doInitialize in class AbstractInitializableComponent

Throws:

ComponentInitializationException - thrown if there is a problem initializing the component

unwrap

@Nonnull
public String unwrap(@Nonnull @NotEmpty
                              String wrapped)
                       throws DataSealerException

Decrypts and verifies an encrypted bundle created with wrap(String, long).

Parameters:

wrapped - the encoded blob

Returns:

the decrypted data, if it's unexpired

Throws:

DataSealerException - if the data cannot be unwrapped and verified

unwrap

@Nonnull
public String unwrap(@Nonnull @NotEmpty
                              String wrapped,
                              @Nullable
                              StringBuffer keyUsed)
                       throws DataSealerException

Decrypts and verifies an encrypted bundle created with wrap(String, long), optionally returning the label of the key used to encrypt the data.

Parameters:

wrapped - the encoded blob

keyUsed - a buffer to receive the alias of the key used to encrypt the data

Returns:

the decrypted data, if it's unexpired

Throws:

DataSealerException - if the data cannot be unwrapped and verified

extractAndCheckDecryptedData

@Nonnull
private String extractAndCheckDecryptedData(@Nonnull @NotEmpty
                                                     byte[] decryptedBytes)
                                              throws DataSealerException

Extract the GZIP'd data and test for expiration before returning it.

Parameters:

decryptedBytes - the data we are looking at

Returns:

the decoded data if it is valid and unexpired

Throws:

DataSealerException - if the data cannot be unwrapped and verified

wrap

@Nonnull
public String wrap(@Nonnull @NotEmpty
                            String data,
                            long exp)
                     throws DataSealerException

Encodes data into an AEAD-encrypted blob, gzip(exp|data)

• exp = expiration time of the data; 8 bytes; Big-endian
• data = the data; a UTF-8-encoded string

As part of encryption, the key alias is supplied as additional authenticated data to the cipher. Afterwards, the encrypted data is prepended by the IV and then again by the alias (in length-prefixed UTF-8 format), which identifies the key used. Finally the result is base64-encoded.

Parameters:

data - the data to wrap

exp - expiration time

Returns:

the encoded blob

Throws:

DataSealerException - if the wrapping operation fails

testEncryption

private void testEncryption(@Nonnull
                            SecretKey key)
                     throws DataSealerException

Run a test over the configured bean properties.

Parameters:

key - key to test

Throws:

DataSealerException - if the test fails