Bifroest	Mr. Tines	CTC Home	CTClib	MacCTC	CTCjava	Manual

Callback Module

This module (in the CTC library) consists only of the header file callback.h. The application writer must provide the implementation. The file callback.c contains some stub code and partial implementation that may prove useful in writing this.

Data Types

enum cb_severity

This represents a condition severity. The valid values are:-

CB_CRASH

Very serious and unrecoverable error; program should exit (e.g. assert failure)

CB_FATAL

Serious and only partially recoverable error; Operation should be aborted (e.g. out of memory)

CB_ERROR

Serious but continuable error (e.g. bad signature)

CB_WARNING

Warning (e.g. No public key to check signature)

CB_INFO

Nothing wrong; merely for information (e.g. good signature)

CB_STATUS

Status; purely transitory information, typically the type of operation being started. (e.g. currently checking signature)

enum cb_context

This datatype is used to indicate the context in which a condition arose. The valid values are:-

CB_DECRYPTION

decrypting or interpreting a PGP format (CTB) file.

CB_ENCRYPTION

encrypting a message.

CB_SIGNING

generating a signature

CB_VERIFYING

verifying a signature

CB_KEYGEN

Generating a PKE key pair.

CB_KEYMAN

Engaged in PKE key management

CB_READING_RING

Reading a key-ring.

CB_UNKNOWN

Context unknown

enum cb_module

This enumeration type defines the module that generated the condition. This is most important in the interpretation of conditions codes as each module has its own set of condition codes. Valid values are:-

CB_CTC_ENGINE

the CTC top-level control engine

CB_ARMOUR

ASCII-Armour module; see data-type armour_return for condition codes.

CB_COMPAND

Compression/Decompression

CB_MSG_DIGEST

Message Digest

CB_BULK_CYPHER

Bulk (symmetric) cypher

CB_PKE

Public key cypher

CB_PK_MANAGE

PKE key management

CB_CTB_IO

CTB file i/o

CB_RANDOM

Random number generator

CB_FILING

Filing system

struct cb_enumeration

This is an enumeration type that identifies enumeration types. The following enumerations are lists:-

CB_ENUMERATION

Self referencial entry for completeness.

CB_MODULE

Enumeration of CTC modules

CB_CONTEXT

Status/error condition contexts (types of operation in hand at the time of the status/error)

CB_SEVERITY

Severity of a condition

CTBVERSION

PGP packet version number (i.e. the per packet version number contained in the CTB packet) (not strictly an enumeration, but a list of macros)

SKSTAT

Status of a secret key (with respect to the encryption of its secret components)

CTBTYPE

Cypher type byte CTB: a field of the first byte of a PGP format packet. Indicates the type of the packet

SIGCLASS

Class of signature, i.e. the semantics of the signature

SIGSUBPKTS

Type of sub-packet (in version 4 and later signature packets)

PKEALGOR

Public-Key Encryption algorithm

MDALGOR

Message Digest algorithm

CEALGOR

Conventional (symmetric) encryption algorithm

COMPANDALGOR

Compress/expansion algorithm

SIGSTAT

Status (with respect to verification) of a signature.

struct cb_condition

short severity;

The severity (cb_severity) code for the condition.

short module;

The module (cb_module) reporting the condition.

short code;

The (module dependent) error code for the condition. (See the appropriate modules error list.)

short context;

The type of operation that encountered this condition (cb_context).

char * text;

Text associated with (qualifying) the error. Note this is not a description of the error. Usage varies for condition to condition.

pubkey * pub_key;

The key (if any) that this condition is associated with.

struct cb_details

pubkey *signatory;

The public key (if any) with which the message was signed, NULL is none.

boolean valid_sig;

If the signature (if any) was valid.

seckey * addressee;

secret key used to decrypt

ulong timestamp;

PGP format time (seconds since 00:00 GMT, 1 Jan 1970)

char typeByte;

't' for text, or 'b' for binary

char fileName[256];

The name of the file.

enum cb_purpose

cb_purpose is used in cb_filedesc and is used to specify for what purpose the CTC engine is requiring an open file.

SIGNEDFILE

the file corresponding to a signature

SPLITKEY

A file to hold a conventional key when revealing the content of a single message

CYPHERTEXTFILE

The file of cyphertext corresponding to an already loaded conventional key

struct cb_filedesc

fileType file_type;

Type of file that is required.

accessMode mode;

Type of access to the files that is required.

cb_purpose purpose;

The reason for accessing the file

Functions

int cb_need_key(seckey * keys[], int Nkeys);

The engine requires an internalised secret key. It provides a list of possible keys, in keys . Nkeys  indicates the number keys. Typically there is only one key in the list. (The only exception is if decrypting a message which is encryption to more than one of the user's secret keys, in which the user has a choice as to which key to use.) The routine should return the offset to the key internalised if successful, or a negative number if unsuccessful.  Returning zero indicates the first key is internalised.

continue_action cb_exception(cb_condition * condition);

The engine reports an exception. The calling program has the option of continuing (ignoring the error), skipping (the operation in question) but continuing with further processing, or aborting.

void cb_information(cb_condition * condition);

Similar to cb_exception, except that the user is merely informed and the routine should ideally return immediately. This is used where there is no choice. However in the case of very serious errors (especially CB_CRASH) and where the program exiting will end the display of the message, implementors should consider awaiting user acknowledgement before returning.

void cb_result_file(DataFileP results, cb_details * details);

The engine has a final output file. It is being returned to the calling program for display or storage. Note that a NULL results pointer is valid and means that no output file is produced (e.g. case of detached signature)

void cb_convKey(cv_details *details, void **key, size_t *keylen);

The message being examined has no public key encrypted parts; it is presumed conventionally encrypted, and a request is made for the (single) algorithm and key from hashed passphrase

DataFileP cb_getFile(cb_filedesc * filedesc);

Requests the application to provide an open file. The details of the file required are in filedesc. The application may refuse to provide such a file by returning a NULL. However this will be interpreted as the operation being abandoned. It is CTC's responsibility to close the file.

char * enumName(cb_enumeration enumeration, int value, boolean full);

Returns (as a static C string) the short name (if full is FALSE) or longer description (if full is TRUE) of the 'value' in the 'enumeration' enumeration type. It returns NULL if 'enumeration' is not valid. It returns an appropriate "unknown" text if 'value' is not recognised. There is a default (English) implementation of this function in keywords.c which will be adequate for English-only applications. Non-English single-language or multi-language will need a different implementation.