ewe.security
Class SecureDocument

java.lang.Object
  ewe.security.SecureDocument

public class SecureDocument

extends Object

A SecureDocument is a document that has been made secure by any one or more of a number of ways. These include:

The document has been encrypted - and optionally compressed by deflation before encryption. The data is usually salted before encryption.

The key for the document compression (if any) may be included, itself being encrypted using the receivers public key.

The document may be digitally signed by the sender using the sender's private key. This signature will contain the SHA1 digest of the message (or salted message if it is encrypted), the length of the message (or salted message) and a signature timestamp (which may be zeroed).

Field Summary

int	changeFrequency This is only used if there is a remote Public Key available, since this indicates that an encryption password could be created at random for each message, and then encrypted in the receivers public key.
boolean	dontTimestampSignature
boolean	dontUseCompression
byte[]	encryptedKey
Signature	signature
static int	STATUS_DATA_IS_ENCRYPTED
static int	STATUS_HAS_ENCRYPTION_KEY
static int	STATUS_HAS_SIGNATURE

Constructor Summary

SecureDocument()
Create a new SecureDocument.

Method Summary

byte[]	authenticate(byte[] authenticator, EncryptionKey myPrivateKey) This is called by a server when it has received a sequence of bytes as created by makeServerAuthenticator().
SecureDocument	changeEncryption() This forces the SecureDocument to change its encryption for encoding by choosing a new random key.
SecureDocument	clearEncryption() This removes all encryption parameters, leaving it in a state unable to encrypt or decrypt any data.
ByteArray	decode(ByteArray dest) Decode the encrypted text as set by setData() into the plain text of the original document.
ByteArray	encode(ByteArray destination) Encode the plain text as set by setData() into a secure document sequence of bytes.
protected DataProcessor	getDecryptor(byte[] key)
protected DataProcessor	getEncryptor(byte[] key)
int	getStatus() Get the encryption status of the encoded document.
boolean	hasEncryptionParameters() Return whether or not this SecureDocument can encode() any data with any kind of security.
byte[]	makeAuthenticator(EncryptionKey serverPublicKey) Call this on a new SecureDocument to create a byte sequence to be sent to the server who you believe is holding the private key of the supplied public key.
SecureDocument	setData(byte[] source) Set the source data.
SecureDocument	setData(byte[] source, int offset, int length) Set the source data.
SecureDocument	setDecryptor(DataProcessor decryptor)
SecureDocument	setEncryptor(DataProcessor encryptor)
SecureDocument	setKeys(EncryptionKey receiverKey, EncryptionKey creatorKey) Set the private/public keys.
SecureDocument	setPassword(byte[] key) You can call this before encoding to explicitly set the key used for the symmetric encryption.
SecureDocument	setPassword(String password) You can call this before encoding to explicitly set the key used for the symmetric encryption.
protected byte[]	stringToKey(String password)
boolean	validateAuthenticator(byte[] reply) Validate the reply from the server as created by authenticate().

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, toString

Field Detail

dontUseCompression

public boolean dontUseCompression

dontTimestampSignature

public boolean dontTimestampSignature

signature

public Signature signature

encryptedKey

public byte[] encryptedKey

changeFrequency

public int changeFrequency

This is only used if there is a remote Public Key available, since this indicates that an encryption password could be created at random for each message, and then encrypted in the receivers public key.

STATUS_HAS_ENCRYPTION_KEY

public static final int STATUS_HAS_ENCRYPTION_KEY

See Also:

Constant Field Values

STATUS_DATA_IS_ENCRYPTED

public static final int STATUS_DATA_IS_ENCRYPTED

See Also:

Constant Field Values

STATUS_HAS_SIGNATURE

public static final int STATUS_HAS_SIGNATURE

See Also:

Constant Field Values

Constructor Detail

SecureDocument

public SecureDocument()

Create a new SecureDocument. After calling this you would call the set() methods to set the security parameters, and then call either encode() to generate the document or decode() to decode the document.

Method Detail

setData

public SecureDocument setData(byte[] source,
                              int offset,
                              int length)

Set the source data. This is either the document in its secure form (in which case you later wish to decode it using decode()) or the document in its plaintext form (in which case you wish later to call encode() on it to encode it).

Parameters:

source - The source bytes.

offset - The offset.

length - The length.

Returns:

this SecureDocument

setData

public SecureDocument setData(byte[] source)

Set the source data. This is either the document in its secure form (in which case you later wish to decode it using decode()) or the document in its plaintext form (in which case you wish later to call encode() on it to encode it).

Parameters:

source - The source bytes.

Returns:

this SecureDocument

getEncryptor

protected DataProcessor getEncryptor(byte[] key)

getDecryptor

protected DataProcessor getDecryptor(byte[] key)

stringToKey

protected byte[] stringToKey(String password)

setPassword

public SecureDocument setPassword(String password)
                           throws IOException

You can call this before encoding to explicitly set the key used for the symmetric encryption.

Returns:

This SecureDocument.

Throws:

IOException

setPassword

public SecureDocument setPassword(byte[] key)
                           throws IOException

You can call this before encoding to explicitly set the key used for the symmetric encryption.

Parameters:

key - the key for the encryption.

Returns:

This SecureDocument.

Throws:

IOException

setEncryptor

public SecureDocument setEncryptor(DataProcessor encryptor)
                            throws IOException

Throws:

IOException

setDecryptor

public SecureDocument setDecryptor(DataProcessor decryptor)
                            throws IOException

Throws:

IOException

setKeys

public SecureDocument setKeys(EncryptionKey receiverKey,
                              EncryptionKey creatorKey)

Set the private/public keys. If you are going to be creating (encoding) the document then you should set creatorKey to be your private key and receiverKey to be the receiver's key. If you do not set the creatorKey then the document will not be digitaly signed. If you do not set the receiverKey then the document will not be encrypted unless you explicitly set the encryption key using setEncryptor(byte[] key).

Parameters:

receiverKey - The key of the receiver of the document - if this is not null, then random symmetric keys will be used to encode the data and the key will be encrypted using the receiver's public key.

creatorKey - The key of the creator of the document - this is used for signing the document. If it is null, the document will not be signed.

Returns:

This SecureDocument

clearEncryption

public SecureDocument clearEncryption()

This removes all encryption parameters, leaving it in a state unable to encrypt or decrypt any data.

Returns:

This SecureDocument.

changeEncryption

public SecureDocument changeEncryption()
                                throws IOException

This forces the SecureDocument to change its encryption for encoding by choosing a new random key. This is only used when a remote Public Key is available. The new encryption key is encrypted using the receiver's Public Key and then saved along with the data encrypted using that new key.

Throws:

IOException

hasEncryptionParameters

public boolean hasEncryptionParameters()

Return whether or not this SecureDocument can encode() any data with any kind of security. This will return true if:

• creatorKey != null - in which case a signature can be generated for the data and saved with the document.
• receiverKey != null - in which case a random symmetric key can be chosen and used to encrypt the data. The symmetric key will be encrypted using the receiver's public key and stored along with the encrypted data.
• encryptor != null - in which case the encryptor will be used to encrypt the data to be stored, and it is assumed that the receiver will have the matching decryptor to decrypt the data.

encode

public ByteArray encode(ByteArray destination)
                 throws IOException,
                        IllegalStateException

Encode the plain text as set by setData() into a secure document sequence of bytes. This byte sequence can be stored or transmitted and then another SecureDocument object can be used to decode the data - once it has been set up with the correct decryption parameters.

Parameters:

destination - an optional destination ByteArray.

Returns:

the destination or a new ByteArray if destination is null.

Throws:

IOException - on an encryption error.

IllegalStateException - if no security options have been setup.

getStatus

public int getStatus()
              throws StreamCorruptedException

Get the encryption status of the encoded document.

Returns:

a value that has one or more of the flags set: STATUS_HAS_ENCRYPTION_KEY, STATUS_DATA_IS_ENCRYPTED, STATUS_HAS_SIGNATURE

Throws:

StreamCorruptedException - if the data is corrupted.

decode

public ByteArray decode(ByteArray dest)
                 throws IOException

Decode the encrypted text as set by setData() into the plain text of the original document.

Parameters:

dest - an optional destination ByteArray.

Returns:

the destination or a new ByteArray if dest is null.

Throws:

IOException - on a decryption error.

makeAuthenticator

public byte[] makeAuthenticator(EncryptionKey serverPublicKey)
                         throws IOException

Call this on a new SecureDocument to create a byte sequence to be sent to the server who you believe is holding the private key of the supplied public key. The server should call authenticate() on the received data and then send back the authenticated bytes. The sender should then call validateAuthenticator() on this same SecureDocument providing the received authenticated bytes. If it returns true this proves that the receiver is in possession of the private key.

Parameters:

serverPublicKey - the public key of ther server.

Returns:

a byte sequence to be sent to the server for authentication.

Throws:

IOException - if this authentication cannot be carried out using the server's public key.

authenticate

public byte[] authenticate(byte[] authenticator,
                           EncryptionKey myPrivateKey)
                    throws IOException

This is called by a server when it has received a sequence of bytes as created by makeServerAuthenticator(). It will attempt to authenticate that it holds the private key of the public key that the requestor believes belongs to this server. It produces a sequence of bytes to send back to the requestor for validation using validateAuthenticator().

Parameters:

authenticator - the byte sequence as created by makeServerAuthenticator() on the client.

myPrivateKey - my private key.

Returns:

a byte sequence to be sent back to the client to prove that this server does have the private key.

Throws:

IOException - if an error occurs decrypting or encrypting the data - which usually indicates that the keys do not match.

validateAuthenticator

public boolean validateAuthenticator(byte[] reply)

Validate the reply from the server as created by authenticate(). This can only be called on the same SecureDocument that makeServerAuthenticator() was called on.

Parameters:

reply - the reply from the server as generated by authenticate().

Returns:

true if it passed the test, false if not.