DESKey

DESKey objects provide DES encryption related operations. The encryption routines are accessed by calling methods on the key you wish to use. A DESKey object contains a key to be used for encryption, a key schedule (which must be computed from the actual key, but is what is usually used for computation by the encryption routines rather than the key itself), and for convenience, input and output initialization vectors.

Initialization vectors are used by routines which use chaining encryption (CBC and PCBC encrypt and decrypt). They can be used keep chaining state across multiple encryption calls. Initialization vectors may be passed directly into these routines, or nil may be passed. If nil is passed, the DESKey's internal initialization vector will be used. (There is one vector used for the encryption routines, and another used for decryption.)

If internal vectors are to be used, they should be initialized by SetEncryptVector or SetDecryptVector.

The prototype DESKey object may be referred to via the constant protoDESKey (which is just the unit reference UR('|DES:MIT-Athena|, 'DESKey)).

Methods

New

key := DESKey:New()

Creates a DESKey object. This should only be called on the prototype DES key.

key: Key is a DESKey object with no key set.

Working.

GetKey

key := DESKey:GetKey()

GetKey returns the DES key.

key: Key is the eight byte binary object containing the key. It is not a copy.

Working

SetKey

DESKey:SetKey(key)

SetKey sets the DES key.

key: Key is an eight byte binary object which is stored as the key in the DESKey object. A copy of the object is not made.

Working

SetEncryptVector

DESKey:SetEncryptVector(vector)

SetEncryptVector sets the DES encryption initialization vector.

vector: Vector is an eight byte binary object.

Untested

SetDecryptVector

DESKey:SetDecryptVector(vector)

SetDecryptVector sets the DES decryption initialization vector.

vector: Vector is an eight byte binary object.

Untested

SetKeyToString

DESKey:SetKeyToString(string)

SetKeyToString converts an arbitrary length string to an 8 byte DES key (which is placed in the DESKey object), with odd byte parity, per FIPS specification. A one-way function is used to convert the string to a key, making it very difficult to reconstruct the string from the key.

string: String is a NewtonScript string used to generate a DES key. The string is converted into a C string before processing, so characters outside of the normal ASCII range should not be included.

Working

CheckBounds

DESKey:CheckBounds()

CheckBounds is called internally by many of the encryption routines to verify the sanity of arguments passed to those routines. Bounds are checked this way because afterwards the arguments are passed on to C functions which will happily stomp all over memory rather than throw an exception should bad arguments be passed. This routine is not actually to be called by the user, but is mentioned to provide a central location describing the exceptions it throws (and therefore most of the encryption routines throw).

|evt.ex.des|, des_NegativeOffset: A negative offset was passed on the input or output object.
|evt.ex.des|, des_BadInputBounds: The length plus offset on the input object point beyond the end of the input object.
|evt.ex.des|, des_BadOutputBounds: The length plus offset on the output object point beyond the end of the output object.
|evt.ex.des|, des_NoPadSpace: Insufficient pad space was provided in the output object to contain the entire data. All DES operations occur on 8 byte blocks, so objects must be padded to at least the nearest multiple of 8 bytes.
|evt.ex.des|, des_NoSchedule: No key schedule has been generated.

MakeKeySchedule

DESKey:MakeKeySchedule()

MakeKeySchedule calculates a key schedule.

|evt.ex.des|, des_NoKey: No key has been set.
|evt.ex.des|, des_BadParity: The key has bad parity.
|evt.ex.des|, des_WeakKey: The key is weak.
|evt.ex.des|, des_SomethingBad: Something bad (unexpected) happened.

ECBEncrypt

DESKey:ECBEncrypt(input, inputOffset, output, outputOffset)

ECBEncrypt is the basic DES encryption routine that encrypts a single 8-byte block in electronic code book mode.

input: Input is a binary object containing the data to be encrypted.
inputOffset: InputOffset is the offset into input where the eight bytes of data should be encrypted.
output: Output is a binary object where the encrypted data should be placed. If output is nil, outputOffset is ignored and the data is encrypted in place.
outputOffset: OutputOffset is the offset into output where the encrypted data should be placed.

|evt.ex.krb4|: See CheckBounds for a list of exceptions thrown by this routine.

Working

ECBDecrypt

DESKey:ECBDecrypt(input, inputOffset, output, outputOffset)

ECBDecrypt is the basic DES decryption routine that decrypts a single 8-byte block in electronic code book mode.

input: Input is a binary object containing the data to be decrypted.
inputOffset: InputOffset is the offset into input where the eight bytes of data should be decrypted.
output: Output is a binary object where the decrypted data should be placed. If output is nil, outputOffset is ignored and the data is decrypted in place.
outputOffset: OutputOffset is the offset into output where the decrypted data should be placed.

|evt.ex.krb4|: See CheckBounds for a list of exceptions thrown by this routine.

Working

CBCEncrypt

DESKey:CBCEncrypt(input, inputOffset, output, outputOffset, length, vector)

CBCEncrypt encrypts using the cipher-block-chaining mode of DES. A characteristic of CBC mode is that changing a single bit of the cleartext, then encrypting using CBC mode, affects all of the subsequent ciphertext. This makes cryptanalysis much more difficult. However, modifying a single bit of the ciphertext, then decrypting, only affects the resulting cleartext from the modified block and the succeeding block. Therefore PCBCEncrypt is strongly recommended for applications where indefinite propagation of errors is required in order to detect modifications.

input: Input is a binary object containing the data to be encrypted.
inputOffset: InputOffset is an integer specifying the offset into input where encryption should begin.
output: Output is a binary object where the encrypted data should be placed. If output is nil, outputOffset is ignored and the data is encrypted in place.
outputOffset: OutputOffset is an integer specifying the offset into output where the encrypted data should be placed.
length: Length is an integer specifying the number of bytes to be encrypted.
vector: Vector is an eight byte binary object containing the initialization vector for the encryption. If nil, the key's embedded output vector will be used. See DESKey for a discussion of initialization vectors.

|evt.ex.krb4|: See CheckBounds for a list of exceptions thrown by this routine.

Working

CBCDecrypt

DESKey:CBCDecrypt(input, inputOffset, output, outputOffset, length, vector)

CBCDecrypt decrypts using the cipher-block-chaining mode of DES.

input: Input is a binary object containing the data to be decrypted.
inputOffset: InputOffset is an integer specifying the offset into input where decryption should begin.
output: Output is a binary object where the decrypted data should be placed. If output is nil, outputOffset is ignored and the data is decrypted in place.
outputOffset: OutputOffset is an integer specifying the offset into output where the decrypted data should be placed.
length: Length is an integer specifying the number of bytes to be decrypted.
vector: Vector is an eight byte binary object containing the initialization vector for the decryption. If nil, the key's embedded input vector will be used. See DESKey for a discussion of initialization vectors.

|evt.ex.krb4|: See CheckBounds for a list of exceptions thrown by this routine.

Working

PCBCEncrypt

DESKey:PCBCEncrypt(input, inputOffset, output, outputOffset, length, vector)

PCBCEncrypt encrypts using a modified block chaining mode. It is highly recommended for most encryption purposes, in that modification of a single bit of the ciphertext will affect all of the subsequent (decrypted) cleartext. Similarly, modifying a single bit of the cleartext will affect all of the subsequent (encrypted) ciphertext. "PCBC" mode, on encryption, XORs both the cleartext of block N and the ciphertext resulting from block N with the cleartext for block N+1 prior to encrypting block N+1.

input: Input is a binary object containing the data to be encrypted.
inputOffset: InputOffset is an integer specifying the offset into input where encryption should begin.
output: Output is a binary object where the encrypted data should be placed. If output is nil, outputOffset is ignored and the data is encrypted in place.
outputOffset: OutputOffset is an integer specifying the offset into output where the encrypted data should be placed.
length: Length is an integer specifying the number of bytes to be encrypted.
vector: Vector is an eight byte binary object containing the initialization vector for the encryption. If nil, the key's embedded output vector will be used. See DESKey for a discussion of initialization vectors.

|evt.ex.krb4|: See CheckBounds for a list of exceptions thrown by this routine.

Working

PCBCDecrypt

DESKey:PCBCDecrypt(input, inputOffset, output, outputOffset, length, vector)

PCBCDecrypt decrypts using a modified block chaining mode.

input: Input is a binary object containing the data to be decrypted.
inputOffset: InputOffset is an integer specifying the offset into input where decryption should begin.
output: Output is a binary object where the decrypted data should be placed. If output is nil, outputOffset is ignored and the data is decrypted in place.
outputOffset: OutputOffset is an integer specifying the offset into output where the decrypted data should be placed.
length: Length is an integer specifying the number of bytes to be decrypted.
vector: Vector is an eight byte binary object containing the initialization vector for the decryption. If nil, the key's embedded input vector will be used. See DESKey for a discussion of initialization vectors.

|evt.ex.krb4|: See CheckBounds for a list of exceptions thrown by this routine.

Working

CBCChecksum

checksum := DESKey:CBCChecksum(input, inputOffset, output, outputOffset, length, vector)

CBCChecksum produces an 8 byte cryptographic checksum by cipher-block-chain encrypting the passed cleartext data. All of the ciphertext output is discarded, except the last 8-byte ciphertext block.

input: Input is a binary object containing the data to be checksummed.
inputOffset: InputOffset is an integer specifying the offset into input where checksumming should begin.
output: Output is a binary object where the checksum should be placed. Eight bytes should be available from the offset. If output is nil, a binary object will be automatically allocated.
outputOffset: OutputOffset is an integer specifying the offset into output where the checksum should be placed.
length: Length is an integer specifying the number of bytes to be checksummed. If it is not an integral multiple of eight bytes, the last cleartext block is copied to a temp and zero filled (highest addresses). The output is always eight bytes.
vector: Vector is an eight byte binary object containing the initialization vector for the checksum. See DESKey for a discussion of initialization vectors.

checksum: If a non-nil output argument was passed, that is the return value of this function. If nil was passed, the return value is an eight-byte binary object containing the computed checksum.

|evt.ex.des|, des_NoSchedule: No key schedule has been generated.

Working: Bounds checking is not currently done on the arguments.

QuadChecksum

DESKey:QuadChecksum(input, inputOffset, output, outputOffset, length, count, seed)

QuadChecksum produces a checksum by chaining quadratic operations on cleartext data.

input: Input is a binary object containing the data to be checksummed.
inputOffset: InputOffset is an integer specifying the offset into input where checksumming should begin.
output: Output is a binary object where the checksum should be placed. The amount of space required in output depends on the count argument.
outputOffset: OutputOffset is an integer specifying the offset into output where the checksum should be placed.
length: Length is an integer specifying the number of bytes to be checksummed. Exactly this many bytes will be checksummed; no padding is needed.
count: Count is an integer specifying the number of iterations (between one and four) the algorithm should run over the data. Multiple iterations run slower, but provide a longer checksum if desired.
seed: Seed is an eight byte binary object which is used to seed the first iteration of the algorithm. If multiple iterations are requested, the results of one iteration are automatically used as the seed for the next iteration.

Dubious: I don't think the NS version of this call could possibly be working right now. Don't even try to use it. This call also technically has nothing to do with DES.