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 intended 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 simultaneously by multiple threads.

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

• the dataToSeal.
• One or more encryption credentials. Each credential can be of following type
  • A Certificate (Asymmetric) known to belong to the recipient intended by the author.
  • A PublicKey (Asymmetric) and its (registration)KeyId (Base64 encoded), known to belong to the recipient intended by the author.
  • A SecretKey (Symmetric) and its (registration)KeyId (Base64 encoded), known or accessible by the recipient(s)

You need to pass at least one asymmetric or symmetric key.

The KEK ID will be readable 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 use in order to decrypt the sealed message. In some circumstances, you don't want to have the real identifier of the 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 or multiple keys for the same addressee. In that case a Set of EncryptionCredentials must be passed to the seal operation.

See Also:

DataSealerBuilder

Method Summary

Modifier and Type	Method and Description
byte[]	seal(byte[] dataToSeal, EncryptionCredential... encryptionKeys) Seals the given message so that it can be exchanged safely with the owner(s) of the given encryption credential(s).
byte[]	seal(byte[] dataToSeal, javax.crypto.SecretKey symKek, java.lang.String base64encodedSymKekId) Deprecated. Use seal(byte[], EncryptionCredential...)
byte[]	seal(EncryptionToken etk, byte[] dataToSeal) Deprecated. Use seal(byte[], EncryptionCredential...)
byte[]	seal(EncryptionToken asymKek, byte[] dataToSeal, javax.crypto.SecretKey symKek, java.lang.String base64encodedSymKekId) Deprecated. Use seal(byte[], EncryptionCredential...)
void	seal(EncryptionToken asymKek, java.io.InputStream dataToSeal, java.io.OutputStream sealedData) Deprecated. Use seal(InputStream, OutputStream, EncryptionCredential...)
void	seal(EncryptionToken asymKek, java.io.InputStream dataToSeal, java.io.OutputStream sealedData, javax.crypto.SecretKey symKek, java.lang.String base64encodedSymKekId) Deprecated. Use seal(InputStream, OutputStream, EncryptionCredential...)
void	seal(java.io.InputStream dataToSeal, java.io.OutputStream sealedData, EncryptionCredential... encryptionKeys) Seals the given message so that it can be exchanged safely with the owner(s) of the given encryption credential(s).
void	seal(java.io.InputStream dataToSeal, java.io.OutputStream sealedData, javax.crypto.SecretKey symKek, java.lang.String base64encodedSymKekId) Deprecated. Use seal(InputStream, OutputStream, EncryptionCredential...)
byte[]	seal(java.util.Set<EncryptionToken> asymKeks, byte[] dataToSeal) Deprecated. Use seal(byte[], EncryptionCredential...)
byte[]	seal(java.util.Set<EncryptionToken> asymKeks, byte[] dataToSeal, javax.crypto.SecretKey symKek, java.lang.String base64encodedSymKekId) Deprecated. Use seal(byte[], EncryptionCredential...)
void	seal(java.util.Set<EncryptionToken> asymKeks, java.io.InputStream dataToSeal, java.io.OutputStream sealedData) Deprecated. Use seal(InputStream, OutputStream, EncryptionCredential...)
void	seal(java.util.Set<EncryptionToken> asymKeks, java.io.InputStream dataToSeal, java.io.OutputStream sealedData, javax.crypto.SecretKey symKek, java.lang.String base64encodedSymKekId) Deprecated. Use seal(InputStream, OutputStream, EncryptionCredential...)

Method Detail

seal

byte[] seal(byte[] dataToSeal,
            EncryptionCredential... encryptionKeys)
     throws DataSealerException

Seals the given message so that it can be exchanged safely with the owner(s) of the given encryption credential(s).

Parameters:

dataToSeal - - the data to seal

encryptionKeys - - keys owned or known by the receiver(s) of the message, used to encrypt the data

Returns:

the sealed data

Throws:

DataSealerException - When the CMS message could not be generated.

seal

void seal(java.io.InputStream dataToSeal,
          java.io.OutputStream sealedData,
          EncryptionCredential... encryptionKeys)
   throws DataSealerException

Seals the given message so that it can be exchanged safely with the owner(s) of the given encryption credential(s). Seals the data ready in the given InputStream and writes the sealed result into the given OutputStream.

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.

encryptionKeys - - keys owned or known by the receiver(s) of the message, used to encrypt the data

Throws:

DataSealerException - When the CMS message could not be generated.

seal

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

Deprecated. Use seal(byte[], EncryptionCredential...)

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 addressee

Returns:

the sealed data

Throws:

DataSealerException - When the CMS message could not be generated.

seal

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

Deprecated. Use seal(byte[], EncryptionCredential...)

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

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

Deprecated. Use seal(byte[], EncryptionCredential...)

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

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

Deprecated. Use seal(byte[], EncryptionCredential...)

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

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

Deprecated. Use seal(byte[], EncryptionCredential...)

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

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

Deprecated. Use seal(InputStream, OutputStream, EncryptionCredential...)

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

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

Deprecated. Use seal(InputStream, OutputStream, EncryptionCredential...)

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

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

Deprecated. Use seal(InputStream, OutputStream, EncryptionCredential...)

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

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

Deprecated. Use seal(InputStream, OutputStream, EncryptionCredential...)

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

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

Deprecated. Use seal(InputStream, OutputStream, EncryptionCredential...)

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.