ccs.crypt
Class Cipher

java.lang.Object
  ccs.crypt.Cipher

Direct Known Subclasses:

AbstractBlockCipher

public abstract class Cipher
extends java.lang.Object

A superclass for symmetric (single key) cryptography. The Cipher object provides a CipherOutputStream and a corresponding CipherInputStream. Plaintext written to the CipherOutputStream appears on the underlying stream as ciphertext; conversely, a CipherInputStream will produce plaintext when attached to an underlying stream of ciphertext (provided, obviously, that the passwords match and the same cipher is used for encrypt and decrypt).

The standard cryptographic term for the secret piece of information required to transform ciphertext into plaintext and vice-versa is a "key". Unfortunately, this word is also used in database terminology for the piece of information by which a record is located. Since the primary purpose of this framework is to provide encrypted databases, there is a clash. Therefore, the term "password" will be used for a symmetric key in the cryptographic sense. (If the framework should expand to include asymmetric cryptography, this ambiguity is lifted, since "public key" and "private key" are not database terms). "Password" is an unfortunate term since it need not (and should not) be a word - it can be any arbitrary sequence of octets (bytes) within the range of lengths permitted by the Cipher. However, the term is likely to be familiar to users, and the alternatives sound rather contrived.

When this framework was first written, the standard Java crypto API was unavailable outside the USA / Canada due to US export restrictions, which is part of the reason we wrote our own. Since then, the crypto API has been made available, but the current framework works fine, is light weight, and has no tendency to weaken keys without telling you / require user-unfriendly tweaking to enable full strength keys / etc. etc. In short, it ain't broke and we don't intend to fix it.

Field Summary

protected byte[]

passwd

Constructor Summary

Cipher()

Method Summary

abstract long	getCiphertextLength(long plainlen, boolean isSelfDelimit) returns the encrypted length of a given length of plaintext.
abstract CipherInputStream	getInputStream(java.io.InputStream is, boolean isSelfDelimit) Returns a CipherInputStream that reads ciphertext from the underlying stream and provides plaintext.
abstract CipherOutputStream	getOutputStream(java.io.OutputStream os, long plainlen) Returns a CipherOutputStream that accepts plaintext and writes ciphertext to the underlying stream.
byte[]	getPasswd() Returns a copy of the current password.
abstract long	getPlaintextLength(long cipherlen, boolean isSelfDelimit) returns the length of plaintext resulting from a given length of ciphertext - the inverse of getCiphertextLength.
protected void	out(java.lang.String q)
void	setPasswd(byte[] pw) Sets the password, and should be called at the start of the encryption procedure.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

passwd

protected byte[] passwd

Constructor Detail

Cipher

public Cipher()

Method Detail

setPasswd

public void setPasswd(byte[] pw)
               throws CipherException

Sets the password, and should be called at the start of the encryption procedure.

Parameters:

pw - the new password.

Throws:

CipherException - if doesn't like the pass-string (maybe it's too short / too long / too boring / too vulnerable to dictionary attack, depending on how sophisticated the implementation is.)

getPasswd

public byte[] getPasswd()

Returns a copy of the current password.

Returns:

The password bytes.

getCiphertextLength

public abstract long getCiphertextLength(long plainlen,
                                         boolean isSelfDelimit)

returns the encrypted length of a given length of plaintext. This can usually be computed without knowing the plaintext itself since Ciphers are not supposed to attempt compression.

Parameters:

plainlen - the length of plaintext.

isSelfDelimit - Whether the stream includes its own length.

Returns:

the length of the corresponding ciphertext, or -1 if this cannot be computed for this particular Cipher.

getPlaintextLength

public abstract long getPlaintextLength(long cipherlen,
                                        boolean isSelfDelimit)

returns the length of plaintext resulting from a given length of ciphertext - the inverse of getCiphertextLength. However, this is generally difficult or impossible to calculate for a block cipher since an unknown amount of padding is present.

Parameters:

cipherlen - the length of ciphertext.

isSelfDelimit - Whether the stream includes its own length.

Returns:

the length of the corresponding plaintext, or -1 if this cannot be computed for this particular Cipher

getOutputStream

public abstract CipherOutputStream getOutputStream(java.io.OutputStream os,
                                                   long plainlen)
                                            throws CipherException,
                                                   java.io.IOException

Returns a CipherOutputStream that accepts plaintext and writes ciphertext to the underlying stream.

Parameters:

os - The stream to write ciphertext to.

plainlen - The length of plaintext to be written. If known, this allows the length to be encrypted as part of the stream itself, and makes the ciphertext self-delimiting; where many ciphertexts are concatenated onto a stream, no boundary sequences are required in this mode, which is preferable. (Such sequences leak information.) Supply -1 if you really don't know; in this case, you must delimit the ciphertext yourself. Note that the limit is applied to the ciphertext, not the plaintext; the cipher may allow you to append a few bytes of garbage without complaining (For a block cipher with an incomplete last block, this does not change the ciphertext length).

Throws:

CipherException - if a cryptographic problem occurs.

java.io.IOException - if the CipherOutputStream could not be created for some reason.

getInputStream

public abstract CipherInputStream getInputStream(java.io.InputStream is,
                                                 boolean isSelfDelimit)
                                          throws CipherException,
                                                 java.io.IOException

Returns a CipherInputStream that reads ciphertext from the underlying stream and provides plaintext.

Parameters:

is - The stream to read ciphertext from.

isSelfDelimit - Whether the ciphertext is self-delimiting, ie. it has its own length stored inside itself. If not, the ciphertext is assumed to extend to EOF.

Throws:

CipherException - if a cryptographic problem occurs.

java.io.IOException - if the CipherInputStream could not be created for some reason.

out

protected void out(java.lang.String q)