Crypto API

The toplevel object "Crypto" can be imported (with chrome provileges) by using Components.utils.import():

Components.utils.import("resource://secret/secret.js");
// Crypto is now defined

Data Classes

Lightweight wrapper classes around keys and other values. Although the actual data contained by these is of the same type, their use differs. These classes prevent data being incorrectly passed into the wrong place, etc.

Crypto.SymKey128

Crypto.SymKey256

Symmetric keys, currently SymKey128 and SymKey256 (128 and 256 bits) are planned. They can be initialized with a byte string (obtained over the wire, for example), a random source, or a key derivation function (for password-based encryption, for example).

k1 = new Crypto.SymKey256(Crypto.Random.urandom);
k2 = new Crypto.SymKey256(Crypto.KDF.PBKDF2(pwd, Salt));
k3 = new Crypto.SymKey256(ByteString);

The first two examples (k1, k2) are constructed with a function argument, which will be called with the specified number of bytes required (16 for SymKey128, 32 for SymKey256). k3 simply uses the specified byte string as-is, though it checks the length and throws if it is not the same as the expected size.

Crypto.IV128

Crypto.IV256

Crypto.Salt128

Crypto.Salt256

These are similar to keys, except it makes little sense to initialize them using a KDF. They may be initialized using a random source to make new ones, or a byte string otherwise.

Crypto.SymCipher

Symmetric cipher implementations and associated data classes. Currently, only AES support is planned.

Crypto.SymCipher.AES

AES top-level object, can be used as a constructor to obtain a base encryptor/decryptor that can be used to implement all of the AES modes. It is essentially equivalent to ECB mode. Most users of this API, however, will want to use the mode-specific constructors (see below).

e = new Crypto.SymCipher.AES(SymKey);
ciphertxt = e.encrypt(data);
cleartxt = e.decrypt(ciphertxt);

The AES top-level encryptor operates with data in multiples of the blocksize only. Data of diferent lengths will cause the encrypt/decrypt operations to throw.

The key size used is determined by the SymKey argument given to the construction. Keys contain metadata specifying their length. Only keys of 128 and 256 bits are supported, however, using a key of a different size will cause the constructor to throw.

Crypto.SymCipher.AES.CBC

Crypto.SymCipher.AES.CTR

Mode constructors for different AES modes. These are similar to the base AES constructor, but can operate with arbitrary sizes of data, and require different arguments (depending on the mode) like IVs.

e = new Crypto.Symipher.AES.CBC.Encryptor(SymKey, IV);
ciphertxt = e.encrypt(data, true);
ciphertxt += e.encrypt(data, false);

CBC mode has different constructors for encryption and decryption, to prevent the same encryptor accidentally being used to both encrypt and decrypt. Also note the second "more" argument to encrypt(), it specifies whether more data will be provided later (causing the encryptor to hold off on returning the last block). If the second argument is omitted or false, the encryptor finalizes the operation and pads the last block as appropriate. So for a one-shot encryption operation where all the input is known ahead of time:

e = new Crypto.Symipher.AES.CBC.Encryptor(SymKey, IV);
ciphertxt = e.encrypt(data);

Other modes are similar. Counter mode (CTR) keeps an internal counter, and does not require an IV. (fixme: specify other modes).

[ Mike: How do you propose we implement CTR mode without an IV? If you call new AES.CTR.Encryptor(key) twice, what would happen? None of the options I can think of are any good. Also, we need an AEAD mode here. EAX? ]

Crypto.Random

Random number generators. See SymCiphers / Data Classes for usage.

Crypto.KDF

Key derivation functions. See SymCiphers / Data Classes for usage.

Crypto.Hash

Hashing functions such as SHA1, etc.

Crypto.MAC

HMACs. They may use SymKeys as secrets.

Crypto.PubKeySystem

Base implementations of public key cryptosystems.

Crypto.Signature

Applied public key crypto objects for using signatures. More convenient (and safer) than using Crypto.PubKeySystem directly.

Crypto.Encoder

Encoding of byte strings, etc. for exporting to other systems.

Crypto.Encoder.Base64

Base-64 encoder/decoder.

ascii = Crypto.Encoder.Base64.encode(data);
data =  Crypto.Encoder.Base64.encode(ascii);