com.silverpeas.util.security
Interface ContentEncryptionService

All Known Implementing Classes:

DefaultContentEncryptionService

public interface ContentEncryptionService

It is a security service for protecting content from an access in plain data. The service provides the encryption and the decryption of content by using a symmetric-key cryptographic algorithm for which it manages the key.

The implementation of this service must be accessible within an IoC container under the name "contentEncryptionService".

This service doesn't maintain the knowledge of the contents that were encrypted; it is not of its responsibility. Therefore, when the encryption key is updated, it is the responsibility of the content management services to provide this service the encrypted contents they manage. For doing, it provides them an interface to register a content provider in the form of an EncryptionContentIterator object. These iterators will be then used directly by the content encryption service to renew their cipher when the key is updated.

When the encryption key is updated, all of the encryption and decryption capabilities are then locked. If a call is performed to one of this service's methods, an IllegalStateException is thrown.

Author:

mmoquillon

Method Summary

Map<String,String>	decryptContent(Map<String,String> encryptedContent) Decrypts the specified encrypted content by using the encryption key that was set with the updateCipherKey(String) method.
String[]	decryptContent(String... encryptedContentParts) Decrypts the specified encrypted content by using the encryption key that was set with the updateCipherKey(String) method.
void	decryptContents(EncryptionContentIterator... iterators) Decrypts the encrypted contents provided by the specified iterators.
Map<String,String>	encryptContent(Map<String,String> content) Encrypts the specified content by using the encryption key that was set with the updateCipherKey(String) method.
String[]	encryptContent(String... contentParts) Encrypts the specified content by using the encryption key that was set with the updateCipherKey(String) method.
void	encryptContents(EncryptionContentIterator... iterators) Encrypts the contents provided by the specified iterators.
boolean	isCipherKeyDefined() Checks if a key is defined and so if content can be encrypted
void	registerForRenewingContentCipher(EncryptionContentIterator iterator) Registers the specified iterator on some encrypted contents for which the cipher has to be renewed when the encryption key is updated.
void	renewCipherOfContents(EncryptionContentIterator... iterators) Renews explicitly the cipher of the contents provided by the specified iterators.
void	updateCipherKey(String key) Updates the key to use to encrypt and to decrypt the enciphered content.

Method Detail

decryptContent

String[] decryptContent(String... encryptedContentParts)
                        throws CryptoException

Decrypts the specified encrypted content by using the encryption key that was set with the updateCipherKey(String) method.

Parameters:

encryptedContentParts - either the different part of an encrypted content to decrypt or several single encrypted textual contents to decrypt.

If the encryption key is is being updated, an IllegalStateException is thrown.

Returns:

an array with the different parts of the decrypted content in the same order they were passed as argument of this method.

Throws:

CryptoException - the decryption of one of the encrypted content (or content part) failed.

decryptContent

Map<String,String> decryptContent(Map<String,String> encryptedContent)
                                  throws CryptoException

Decrypts the specified encrypted content by using the encryption key that was set with the updateCipherKey(String) method.

The encrypted content is here in the form of a Map instance in which each entry represents a field or a property of the encrypted content. The method returns also a Map with, for each entry, the field or the property decrypted.

If the encryption key is is being updated, an IllegalStateException is thrown.

Parameters:

encryptedContent - the content to decrypt in the form of a Map instance. Each entry in the Map represents a field/property of the content to decrypt.

Returns:

a Map with the different field/property of the content decrypted.

Throws:

CryptoException - the decryption of the content failed.

decryptContents

void decryptContents(EncryptionContentIterator... iterators)
                     throws CryptoException

Decrypts the encrypted contents provided by the specified iterators.

This method is for decrypting in batch several and possibly different encrypted contents. If there is more than one iterator on contents, each of them will be taken in charge concurrently by a pool of several threads.

If the encryption key is is being updated, an IllegalStateException is thrown.

Parameters:

iterators - the iterators on the contents to decrypt.

Throws:

CryptoException

encryptContent

String[] encryptContent(String... contentParts)
                        throws CryptoException

Encrypts the specified content by using the encryption key that was set with the updateCipherKey(String) method.

Parameters:

contentParts - either the different part of a content to encrypt or several single textual contents to encrypt.

If the encryption key is is being updated, an IllegalStateException is thrown.

Returns:

an array with the different parts of the content, encrypted and in base64, in the same order they were passed as argument of this method.

Throws:

CryptoException - the encryption of one of the content (or content part) failed.

encryptContent

Map<String,String> encryptContent(Map<String,String> content)
                                  throws CryptoException

Encrypts the specified content by using the encryption key that was set with the updateCipherKey(String) method.

The content is here in the form of a Map instance in which each entry represents a field or a property of the content. The method returns also a Map with, for each entry, the field or the property encrypted and in base64.

If the encryption key is is being updated, an IllegalStateException is thrown.

Parameters:

content - the content to encrypt in the form of a Map instance. Each entry in the Map represents a field/property of the content to encrypt.

Returns:

a Map with the different field/property of the content encrypted.

Throws:

CryptoException - the encryption of the content failed.

encryptContents

void encryptContents(EncryptionContentIterator... iterators)
                     throws CryptoException

Encrypts the contents provided by the specified iterators.

This method is for encrypting in batch several and possibly different contents. If there is more than one iterator on contents, each of them will be taken in charge concurrently by a pool of several threads.

If the encryption key is is being updated, an IllegalStateException is thrown.

Parameters:

iterators - the iterators on the contents to encrypt.

Throws:

CryptoException

registerForRenewingContentCipher

void registerForRenewingContentCipher(EncryptionContentIterator iterator)

Registers the specified iterator on some encrypted contents for which the cipher has to be renewed when the encryption key is updated.

This method is dedicated to the content management service for providing to the content encryption services a way to access the encrypted contents they manage in order to renew their cipher when the encryption key is updated.

Parameters:

iterator - a provider of encrypted content in the form of a EncryptionContentIterator iterator.

renewCipherOfContents

void renewCipherOfContents(EncryptionContentIterator... iterators)
                           throws CipherKeyUpdateException,
                                  CryptoException

Renews explicitly the cipher of the contents provided by the specified iterators.

This method is mainly for encrypted contents for which the renew of their cipher has failed when the encryption key has been updated.

The execution of this method will block any other call of the DefaultContentEncryptionService methods for all of its instances in order to prevent incoherent state of encrypted contents. Any attempts to execute one of the DefaultContentEncryptionService method, whereas this method is running, will raise an IllegalStateException exception.

If it doesn't exist a previous encryption key required to decrypt the contents before encrypting them with the actual encryption key, then nothing is performed by this method and it will return silently.

Parameters:

iterators - the iterators on the encrypted contents for which their cipher has to be renewed.

Throws:

CipherKeyUpdateException - if the replace of the cipher key has failed.

CryptoException - if an error while renewing the cipher of the encrypted contents with the new cipher key.

updateCipherKey

void updateCipherKey(String key)
                     throws CipherKeyUpdateException,
                            CryptoException

Updates the key to use to encrypt and to decrypt the enciphered content. The key must be in hexadecimal otherwise an AssertionError will be thrown. If no previous key existed, then the cipher key will be created with this specified one and it will be used to encrypt and to decrypt at the demand the content in Silverpeas.

The update of the key triggers automatically the renew of the cipher of the encrypted contents in Silverpeas with the new cipher key. If one of the cipher renew of one of the encrypted content failed, the key update is rolled-back (the key isn't updated) and a CryptoException is thrown.

The execution of this method will block any other call of the DefaultContentEncryptionService methods for all of its instances in order to prevent incoherent state of encrypted contents. Any attempts to execute one of the DefaultContentEncryptionService method, whereas this method is running, will raise an IllegalStateException exception.

Parameters:

key - the new symmetric key in hexadecimal.

Throws:

CipherKeyUpdateException - if the update of the cipher key has failed.

CryptoException - if an error while renewing the cipher of the encrypted contents with the new cipher key.

isCipherKeyDefined

boolean isCipherKeyDefined()

Checks if a key is defined and so if content can be encrypted

Returns:

true if the key exist and it is valid