org.owasp.esapi
Interface Encryptor

All Known Implementing Classes:

JavaEncryptor

public interface Encryptor

The Encryptor interface provides a set of methods for performing common encryption, random number, and hashing operations. Implementations should rely on a strong cryptographic implementation, such as JCE or BouncyCastle. Implementors should take care to ensure that they initialize their implementation with a strong "master key", and that they protect this secret as much as possible.

Possible future enhancements (depending on feedback) might include:

• encryptFile

Since:

June 1, 2007

Author:

Jeff Williams (jeff.williams .at. aspectsecurity.com) Aspect Security

Method Summary

java.lang.String	decrypt(java.lang.String ciphertext) Decrypts the provided ciphertext string (encrypted with the encrypt method) and returns a plaintext string.
java.lang.String	encrypt(java.lang.String plaintext) Encrypts the provided plaintext and returns a ciphertext string.
long	getRelativeTimeStamp(long offset) Gets an absolute timestamp representing an offset from the current time to be used by other functions in the library.
long	getTimeStamp() Gets a timestamp representing the current date and time to be used by other functions in the library.
java.lang.String	hash(java.lang.String plaintext, java.lang.String salt) Returns a string representation of the hash of the provided plaintext and salt.
java.lang.String	seal(java.lang.String data, long timestamp) Creates a seal that binds a set of data and includes an expiration timestamp.
java.lang.String	sign(java.lang.String data) Create a digital signature for the provided data and return it in a string.
java.lang.String	unseal(java.lang.String seal) Unseals data (created with the seal method) and throws an exception describing any of the various problems that could exist with a seal, such as an invalid seal format, expired timestamp, or decryption error.
boolean	verifySeal(java.lang.String seal) Verifies a seal (created with the seal method) and throws an exception describing any of the various problems that could exist with a seal, such as an invalid seal format, expired timestamp, or data mismatch.
boolean	verifySignature(java.lang.String signature, java.lang.String data) Verifies a digital signature (created with the sign method) and returns the boolean result.

Method Detail

hash

public java.lang.String hash(java.lang.String plaintext,
                             java.lang.String salt)
                      throws EncryptionException

Returns a string representation of the hash of the provided plaintext and salt. The salt helps to protect against a rainbow table attack by mixing in some extra data with the plaintext. Some good choices for a salt might be an account name or some other string that is known to the application but not to an attacker. See this article for more information about hashing as it pertains to password schemes.

Parameters:

plaintext - the plaintext String to encrypt

salt - the salt to add to the plaintext String before hashing

Returns:

the encrypted hash of 'plaintext' stored as a String

Throws:

EncryptionException - if the specified hash algorithm could not be found or another problem exists with the hashing of 'plaintext'

encrypt

public java.lang.String encrypt(java.lang.String plaintext)
                         throws EncryptionException

Encrypts the provided plaintext and returns a ciphertext string.

Parameters:

plaintext - the plaintext String to encrypt

Returns:

the encrypted String representation of 'plaintext'

Throws:

EncryptionException - if the specified encryption algorithm could not be found or another problem exists with the encryption of 'plaintext'

decrypt

public java.lang.String decrypt(java.lang.String ciphertext)
                         throws EncryptionException

Decrypts the provided ciphertext string (encrypted with the encrypt method) and returns a plaintext string.

Parameters:

ciphertext - the ciphertext (encrypted plaintext)

Returns:

the decrypted ciphertext

Throws:

EncryptionException - if the specified encryption algorithm could not be found or another problem exists with the encryption of 'plaintext'

sign

public java.lang.String sign(java.lang.String data)
                      throws EncryptionException

Create a digital signature for the provided data and return it in a string.

Parameters:

data - the data to sign

Returns:

the digital signature stored as a String

Throws:

EncryptionException - if the specified signature algorithm cannot be found

verifySignature

public boolean verifySignature(java.lang.String signature,
                               java.lang.String data)

Verifies a digital signature (created with the sign method) and returns the boolean result.

Parameters:

signature - the signature to verify against 'data'

data - the data to verify against 'signature'

Returns:

true, if the signature is verified, false otherwise

seal

public java.lang.String seal(java.lang.String data,
                             long timestamp)
                      throws IntegrityException

Creates a seal that binds a set of data and includes an expiration timestamp.

Parameters:

data - the data to seal

timestamp - the absolute expiration date of the data, expressed as seconds since the epoch

Returns:

the seal

Throws:

IntegrityException

unseal

public java.lang.String unseal(java.lang.String seal)
                        throws EncryptionException

Unseals data (created with the seal method) and throws an exception describing any of the various problems that could exist with a seal, such as an invalid seal format, expired timestamp, or decryption error.

Parameters:

seal - the sealed data

Returns:

the original (unsealed) data

Throws:

EncryptionException - if the unsealed data cannot be retrieved for any reason

verifySeal

public boolean verifySeal(java.lang.String seal)

Verifies a seal (created with the seal method) and throws an exception describing any of the various problems that could exist with a seal, such as an invalid seal format, expired timestamp, or data mismatch.

Parameters:

seal - the seal to verify

Returns:

true, if the seal is valid. False otherwise

getRelativeTimeStamp

public long getRelativeTimeStamp(long offset)

Gets an absolute timestamp representing an offset from the current time to be used by other functions in the library.

Parameters:

offset - the offset to add to the current time

Returns:

the absolute timestamp

getTimeStamp

public long getTimeStamp()

Gets a timestamp representing the current date and time to be used by other functions in the library.

Returns:

a timestamp representing the current time