be.fgov.ehealth.etee.crypto.encrypt
Interface DataSealer

public interface DataSealer

A DataSealer is a thread safe object that can protect data that must be exchanged between two parties. It provides protection regarding the following aspects of the data:

• Confidentiality : only the addressee intended by the author (also called 'the recipient') can read the sealed data after decryption in the 'data unseal' process.
• Integrity : the data can not be changed unnoticed , i.e. verifications during the data unseal process will reveal any changes made to the data of the author.
• Authenticity : the sealed data contains the information regarding the author of the sealed data.

The protection it provides is intended for a short period, i.e. the time necessary to exchange the data between author and addressee. It is not intented to protect data stored for long periods.

A DataSealer has a strong association with an author, because it signs data with the private authentication key of the author Consequently a DataSealer must be created for each author. Use the DataSealerBuilder to create DataSealers. Once the DataSealer is created, it can be used for several messages, to different addressees. It can be used simultaniously by multiple threads.

To seal the data, i.e. protect the data, you need to pass to the seal operation :

• the dataToSeal.
• [option 1] asymKek(s) : the EncryptionToken(s) of the recipient(s) intented by the author.
• [option 2] symKek: a symmetric Key Encryption Key
• [only required if symKek is given] base64encodedSymKekId : the identifier of the symmetric Key Encryption Key, base64 encoded.

You need to pass at least one ETK or one symmetric KEK.

The KEK ID will be readible included in the sealed message. In other words, the KEK ID is not encrypted. As such it can be used by the recipient to know which KEK to fetch from the KGSS (Kek Generation and Storage Service) in order to decrypt the sealed message. In some circumstances, you don't want to have the real identifier of the symmetric KEK of the message in the message. In that case you can pass a dummy value as KEK ID to the seal operation, and use another way of letting your recipient know which KEK to use to decrypt the message.

The dataToSeal can be a byte[] or an InputStream. Use the byte[] for small messages that can be loaded in memory in one take. Use the InputStream for bigger messages.
The result of a seal operation of the DataSealer is a CMS message according to the security policy of the eHealth Platform Belgium regarding End-To-End protection of data to exchange.
Note that one CMS message can have the data sealed for multiple addressees. In that case a Set of EncryptionTokens must be passed to the seal operation.

See Also:

DataSealerBuilder, EncryptionToken

Method Summary

byte[]	seal(byte[] dataToSeal, javax.crypto.SecretKey symKek, java.lang.String base64encodedSymKekId) Seals the given data so that it can be exchanged safely to the unknown addressee(s) who has access to the SecretKey.
byte[]	seal(EncryptionToken etk, byte[] dataToSeal) Seals the given data so that it can be exchanged safely to the owner of the given EncryptionToken.
byte[]	seal(EncryptionToken asymKek, byte[] dataToSeal, javax.crypto.SecretKey symKek, java.lang.String base64encodedSymKekId) Seals the given data so that it can be exchanged safely to the owner of the given EncryptionToken and to the unknown addressee who has access to the SecretKey.
void	seal(EncryptionToken asymKek, java.io.InputStream dataToSeal, java.io.OutputStream sealedData) Seals a given message for a known addressee.
void	seal(EncryptionToken asymKek, java.io.InputStream dataToSeal, java.io.OutputStream sealedData, javax.crypto.SecretKey symKek, java.lang.String base64encodedSymKekId) Seals a given message for a known addressee and for unknown addressee(s) who have access to the secret key.
void	seal(java.io.InputStream dataToSeal, java.io.OutputStream sealedData, javax.crypto.SecretKey symKek, java.lang.String base64encodedSymKekId) Seals a given message for unknown addressee(s) who have access to the secret key.
byte[]	seal(java.util.Set<EncryptionToken> asymKeks, byte[] dataToSeal) Seals the given data so that it can be exchanged safely to the owners of the given EncryptionTokens.
byte[]	seal(java.util.Set<EncryptionToken> asymKeks, byte[] dataToSeal, javax.crypto.SecretKey symKek, java.lang.String base64encodedSymKekId) Seals the given data so that it can be exchanged safely to the owners of the given EncryptionTokens and to the unknown addressee(s) who has access to the SecretKey.
void	seal(java.util.Set<EncryptionToken> asymKeks, java.io.InputStream dataToSeal, java.io.OutputStream sealedData) Seals a given message for a set of known addressees.
void	seal(java.util.Set<EncryptionToken> asymKeks, java.io.InputStream dataToSeal, java.io.OutputStream sealedData, javax.crypto.SecretKey symKek, java.lang.String base64encodedSymKekId) Seals a given message for a set of known addressees and for unknown addressee(s) who have access to the secret key.

Method Detail

seal

byte[] seal(EncryptionToken etk,
            byte[] dataToSeal)
            throws DataSealerException

Seals the given data so that it can be exchanged safely to the owner of the given EncryptionToken.

Parameters:

dataToSeal - - the data to seal

etk - - the EncryptionToken of the addresee

Returns:

the sealed data

Throws:

DataSealerException - When the CMS message could not be generated.

seal

byte[] seal(EncryptionToken asymKek,
            byte[] dataToSeal,
            javax.crypto.SecretKey symKek,
            java.lang.String base64encodedSymKekId)
            throws DataSealerException

Seals the given data so that it can be exchanged safely to the owner of the given EncryptionToken and to the unknown addressee who has access to the SecretKey.

Parameters:

asymKek - - the EncryptionToken of a recipient.

dataToSeal - - the data to seal

symKek - - the symmetric Key Encryption Key

base64encodedSymKekId - - the ID (base64 encoded) of the given SecretKey symKek

Returns:

the sealed data.

Throws:

DataSealerException - When the CMS message could not be generated.

seal

byte[] seal(java.util.Set<EncryptionToken> asymKeks,
            byte[] dataToSeal)
            throws DataSealerException

Seals the given data so that it can be exchanged safely to the owners of the given EncryptionTokens.

Parameters:

dataToSeal - - the data to seal

asymKeks - - the EncryptionTokens of the addressees

Returns:

the sealed data

Throws:

DataSealerException - When the CMS message could not be generated.

seal

byte[] seal(java.util.Set<EncryptionToken> asymKeks,
            byte[] dataToSeal,
            javax.crypto.SecretKey symKek,
            java.lang.String base64encodedSymKekId)
            throws DataSealerException

Seals the given data so that it can be exchanged safely to the owners of the given EncryptionTokens and to the unknown addressee(s) who has access to the SecretKey.

Parameters:

asymKeks - - the EncryptionTokens of the addressees

dataToSeal - - the data to seal

symKek - - the symmetric Key Encryption Key

base64encodedSymKekId - - the ID (base64 encoded) of the given SecretKey symKek

Returns:

the sealed data

Throws:

DataSealerException - When the CMS message could not be generated.

seal

byte[] seal(byte[] dataToSeal,
            javax.crypto.SecretKey symKek,
            java.lang.String base64encodedSymKekId)
            throws DataSealerException

Seals the given data so that it can be exchanged safely to the unknown addressee(s) who has access to the SecretKey.

Parameters:

dataToSeal - - the data to seal

symKek - - the symmetric Key Encryption Key

base64encodedSymKekId - - the ID (base64 encoded) of the given SecretKey symKek

Returns:

the sealed data

Throws:

DataSealerException - When the CMS message could not be generated.

seal

void seal(EncryptionToken asymKek,
          java.io.InputStream dataToSeal,
          java.io.OutputStream sealedData)
          throws DataSealerException

Seals a given message for a known addressee. Seals the data ready in the given InputStream and writes the sealed result into the given OutputStream.

Parameters:

asymKek - - the EncryptionToken of a recipient.

dataToSeal - the InputStream where the dataToSeal content is read from by the DataSealer. The given InputStream must implement the available() method.

sealedData - the OutputStream to which the sealed result is written by the DataSealer. When the sealing is finished, the OutputStream is not closed in here.

Throws:

DataSealerException - When the CMS message could not be generated.

seal

void seal(java.util.Set<EncryptionToken> asymKeks,
          java.io.InputStream dataToSeal,
          java.io.OutputStream sealedData)
          throws DataSealerException

Seals a given message for a set of known addressees.

Parameters:

asymKeks - - the EncryptionTokens of the known addressees

dataToSeal - the InputStream where the dataToSeal content is read from by the DataSealer. The given InputStream must implement the available() method.

sealedData - the OutputStream to which the sealed result is written by the DataSealer. When the sealing is finished, the OutputStream is not closed in here.

Throws:

DataSealerException - When the CMS message could not be generated.

seal

void seal(EncryptionToken asymKek,
          java.io.InputStream dataToSeal,
          java.io.OutputStream sealedData,
          javax.crypto.SecretKey symKek,
          java.lang.String base64encodedSymKekId)
          throws DataSealerException

Seals a given message for a known addressee and for unknown addressee(s) who have access to the secret key.

Parameters:

asymKek - - the EncryptionToken of a recipient.

dataToSeal - the InputStream where the dataToSeal content is read from by the DataSealer. The given InputStream must implement the available() method.

sealedData - the OutputStream to which the sealed result is written by the DataSealer. When the sealing is finished, the OutputStream is not closed in here.

symKek - - the symmetric Key Encryption Key

base64encodedSymKekId - - the ID (base64 encoded) of the given SecretKey symKek

Throws:

DataSealerException - When the CMS message could not be generated.

seal

void seal(java.util.Set<EncryptionToken> asymKeks,
          java.io.InputStream dataToSeal,
          java.io.OutputStream sealedData,
          javax.crypto.SecretKey symKek,
          java.lang.String base64encodedSymKekId)
          throws DataSealerException

Seals a given message for a set of known addressees and for unknown addressee(s) who have access to the secret key.

Parameters:

asymKeks - - the EncryptionTokens of the known addressees

dataToSeal - the InputStream where the dataToSeal content is read from by the DataSealer. The given InputStream must implement the available() method.

sealedData - the OutputStream to which the sealed result is written by the DataSealer. When the sealing is finished, the OutputStream is not closed in here.

symKek - - the symmetric Key Encryption Key

base64encodedSymKekId - - the ID (base64 encoded) of the given SecretKey symKek

Throws:

DataSealerException - When the CMS message could not be generated.

seal

void seal(java.io.InputStream dataToSeal,
          java.io.OutputStream sealedData,
          javax.crypto.SecretKey symKek,
          java.lang.String base64encodedSymKekId)
          throws DataSealerException

Seals a given message for unknown addressee(s) who have access to the secret key.

Parameters:

dataToSeal - the InputStream where the dataToSeal content is read from by the DataSealer. The given InputStream must implement the available() method.

sealedData - the OutputStream to which the sealed result is written by the DataSealer. When the sealing is finished, the OutputStream is not closed in here.

symKek - - the symmetric Key Encryption Key

base64encodedSymKekId - - the ID (base64 encoded) of the given SecretKey symKek

Throws:

DataSealerException - When the CMS message could not be generated.