Bifroest	Mr. Tines	CTC Home	CTClib	MacCTC	CTCjava	Manual

Application Interface

Data Types

ctc_codes

Status codes: These indicate conditions that can be detected by the CTC engine.  These are codes of all severities varying from merely informational to very serious errors.  The associated severity code will indicate how serious the condition is.

CTC_SEARCHING

Looking for an armoured block

CTC_DEARMOURING

Unarmouring a block

CTC_ARMOURING

Armouring a block

CTC_COMPRESSING

Compressing data

CTC_DECOMPRESSING

Decompressing data

CTC_DIGESTING

Calculating digest

CTC_BULK_ENCRYPTING

Encrypting with symmetric cypher

CTC_BULK_DECRYPTING

Decrypting with symmetric cypher

CTC_PKE_ENCRYPTING

Encrypting with public key

CTC_PKE_DECRYPTING

Decrypting with secret key

CTC_PKE_SIGNING

Signing with secret key

CTC_PKE_VERIFY

Verifying signature with public key

CTC_NOTHING_FOUND

File contained no armoured blocked

CTC_UNIMP_MSG_DIGEST

Unimplemented Message Digest algorithm

CTC_UNIMP_COMPRESS

Unimplemented Compression algorithm

CTC_UNIMP_DECOMPRESS

Unimplemented Decompression algorithm

CTC_UNIMP_BULK_CYPH

Unimplemented Bulk Cypher

CTC_UNIMP_PKE_CYPHER

Unimplemented PKE algorithm

CTC_NO_TEMP_FILE

Unable to create temporary file

CTC_UNIMP_MULTI_PASS

Multiple data passes for symmetric encryption not implemented

CTC_UNIMP_REV_PASS

Reverse data passes for sym. cypher

CTC_WRONG_BULK_KEY

Attempt to decrypt with wrong symmetric key

CTC_READ_FILE_ERR

Error reading from disc file

CTC_WRITE_FILE_ERR

Error writing to disc dile

CTC_SECKEY_UNAVAIL

Incoming is message is encrypted with this (unavailable) key.

CTC_PUBKEY_UNAVAIL

Incoming message is signed with this (unavailable) key.

CTC_UNKNWN_CTB

unknown cypher (block) type byte

CTC_UNIMPL_CTB

Unknown block type in a PGP file structure.

CTC_BAD_PLAIN_SIG

Plain-signed block with an invalid signature encountered

CTC_GOOD_PLAIN_SIG

Plain-signed block with a valid signature encountered

CTC_OUT_OF_MEMORY

Failed to allocate necessary memory

CTC_COMMENT_FOUND

Comment packet found. (This refers to a PGP 2.6 file format CTB_COMMENT packet, not to an ASCII-armour "Comment:" line.

CTC_NO_KEY_AVAIL

No key available to decrypt message.

CTC_BAD_VERSION

Unrecognised packet version

CTC_NOT_SIGNATURE

Non-signature packet found trying to verify signature

enum decode_operation

DECODE = 0

Normal decode operation.  Operations are drived by cyphertext structure to produce plaintext and import keys.

REVEALKEY

The main purpose is to generate session key blocks to allow the decryption of messages without the secret key.  The main purpose of this is to allow decryption of some messages, (e.g. in response to a court order) with revealing the secret key.

USEKEY

To decode the message using the conventional key provided (in the decode_context structure) rather than any PKE blocks found in the cyphertext.

struct decode_context

hashtable * keyRings

The key-ring to be used for this decryption operation.

recordSummary current

This is used internally of the summary of the cyphertext block currently being processed.

cb_context cbContext

Defines the type of operation

byte  splitkey

This takes a decode_operation value, and determines the operating mode.

size_t cv_len

Defines the length of the key data cv_data. (Only used if splitkey == USEKEY)

cv_details cv_algor[MAXCVALGS]

Defines the conventional algorithms to be used.  (Only used if splitkey == USEKEY)

byte * cv_data;

Defines the conventional key data.  (Only used if splitkey == USEKEY)

struct encryptInsts

This structure includes all the parameters to describe how a plaintext file should be processed into cyphertext.

char * filename

This is the filename to be recorded in the ciphertext. Note that no other processing is done on this field. CTC will not open the named file.  The actual file must be provided separately by application.

byte version

PGP version values are 2 for up to 2.5, 3 for 2.6, 4 for PGP5.0

char fileType

't' for text or 'b' for binary

byte md_algor

Message digest algorithm

byte cp_algor

Compression algorithm

byte armour

Armour format; see armour_style defined in armour.h

byte padding

dummy spacer to re-establish 4-byte alignment (ignored)

cv_details cv_algor[MAXCVALGS]

conventional key algorithm details

pubkey * * to

NULL terminated list of recipients

seckey * signatory

Pointer to secret key to sign message (or NULL if the message is not to be signed).

Functions

continue_action examine(DataFileP input, decode_context * context);

Examine and decypher a binary input file. The operation of this function is driven by the structure of the input  file. The context should must be provided by the application.  For normal operation it can be all zeros except for having a valid key-ring hashtable in .keyrings.  If a special operation is required then .splitkey must be set appropriately.  If .splitkey == USEKEY the conventional encryption fields must also be completed.

This routine will call itself recursively to unpack to any depth. Appropriate callbacks inform the application of progress and allow it to decide how to process what is found.

continue_action examine_text(DataFileP input, decode_context * context);

Examine and decypher an armoured text input  file. The context should must be provided by the application and should set as for examine(). This scans the input file for ASCII armour blocks and passes the unarmoured results of any of these examine() for further processing.

boolean encrypt(DataFileP source, DataFileP output, encryptInsts * instructions);

Encrypt file according to instructions (closes source file).

boolean signOnly(DataFileP source, DataFileP output, encryptInsts * instructions)

Generate either clear-signed text, or a detached signature, according to the instructions (closes source file).

boolean key_extract(DataFileP file, pubkey * pub_key);

Writes the specified public key block to the specified file in PGP style ASCII-armour. This may be used repeatedly to write several key-blocks to the file.  Returns TRUE if successful.

boolean key_revoke(DataFileP file, seckey * sec_key, boolean permanently);

Write a key revocation certificate and optionally keep the revocation record (typically the revocation record is not kept as the revocation certificate is normally written on key generation). Returns TRUE if successful.

void hashpass(char *keystring, byte *key, int keylen, byte hashalg)

This function is maintained for compatibility only. New code should use hashpassEx().

Hash the keystring with the given algorithm then truncate or repeat as required to fill keylen bytes of key.

void hashpassEx(char *keystring, byte *key, int keylen, byte * s2k, boolean convertToUTF8)

Hash the keystring to fill the key with keylen bytes of hashed data. S2k must point to an OpenPGP String to key sub-packet as per section 3.6 of the OpenPGP specification. The length of the data is implied in the value of s2k[0].(For simple implementations s2k should be two bytes. The first being zero and the second being a hash algorithm byte.) convertToUTF is a boolean indicating if the passphrase still needs to be converted to the default character set encoding for OpenPGP.