OpenCDK API Overview

Open Crypto Development Kit (OpenCDK)

Introduction
OpenCDK is a library which implements basic parts of the OpenPGP (RFC2440) message format.

Function

int cdk_armor_filter_use (cdk_stream_t inp )

Arguments

cdk_stream_t inp: the stream to check

Description

Check if the stream contains armored data.

Function

cdk_error_t cdk_file_armor (cdk_ctx_t hd , const char * file , const char * output )

Arguments

cdk_ctx_t hd: Handle
const char * file: Name of the file to protect.
const char * output: Output filename.

Description

Protect a file with ASCII armor.

Function

cdk_error_t cdk_file_dearmor (const char * file , const char * output )

Arguments

const char * file: Name of the file to unprotect.
const char * output: Output filename.

Description

Remove ASCII armor from a file.

Function

cdk_error_t cdk_armor_encode_buffer (const byte * inbuf , size_t inlen , char * outbuf , size_t outlen , size_t * nwritten , int type )

Arguments

const byte * inbuf: the raw input buffer
size_t inlen: raw buffer len
char * outbuf: the destination buffer for the base64 output
size_t outlen: destination buffer len
size_t * nwritten: actual length of the base64 data
int type: the base64 file type.

Description

Encode the given buffer into base64 format.

Function

cdk_error_t cdk_stream_encrypt (cdk_ctx_t hd , cdk_strlist_t remusr , cdk_stream_t inp , cdk_stream_t out )

Arguments

cdk_ctx_t hd: Context handle for options
cdk_strlist_t remusr: List of recipients
cdk_stream_t inp: Input stream handle
cdk_stream_t out: Output stream handle

Description

If remusr is NULL, then symmetric encryption is used. Via the handle the caller can set or unset multiple options.

Function

cdk_error_t cdk_file_encrypt (cdk_ctx_t hd , cdk_strlist_t remusr , const char * file , const char * output )

Arguments

cdk_ctx_t hd: Context handle
cdk_strlist_t remusr: List of recipient
const char * file: Input file
const char * output: Output file

Description

Encrypt the given file and encrypt the session key with the given recipient keys.

Function

cdk_error_t cdk_file_decrypt (cdk_ctx_t hd , const char * file , const char * output )

Arguments

cdk_ctx_t hd: Handle.
const char * file: Name of the file to decrypt.
const char * output: Output filename.

Description

Decrypt a file. When the operation was successful, hd can contain information about the signature (when present) and more.

Function

cdk_error_t cdk_data_transform (cdk_ctx_t hd , enum cdk_crypto_mode_t mode , cdk_strlist_t locusr , cdk_strlist_t remusr , const void * inbuf , size_t insize , byte ** outbuf , size_t * outsize , int modval )

Arguments

cdk_ctx_t hd: session handle
enum cdk_crypto_mode_t mode: crypto mode
cdk_strlist_t locusr: local user list (sign mode only)
cdk_strlist_t remusr: remote users 'recipients'
const void * inbuf: input buffer with data
size_t insize: length of data in bytes
byte ** outbuf: pointer to the output data (will be allocated)
size_t * outsize: size of the new data in bytes
int modval: value for the modus (for example sign mode)

Description

This function transforms data into the given openpgp mode. It works exactly like the cdk_file_xxx functions with the exception that it can be used with memory and not with streams or files.

Function

cdk_kbnode_t cdk_kbnode_new (cdk_packet_t pkt )

Arguments

cdk_packet_t pkt: the packet to add

Description

Allocate a new key node and add the packet.

Function

void cdk_kbnode_release (cdk_kbnode_t node )

Arguments

cdk_kbnode_t node

Description

Release the memory of the node.

Function

void cdk_kbnode_delete (cdk_kbnode_t node )

Arguments

cdk_kbnode_t node: the key node

Description

Mark the given node as deleted.

Function

void cdk_kbnode_insert (cdk_kbnode_t root , cdk_kbnode_t node , int pkttype )

Arguments

cdk_kbnode_t root: the root key node
cdk_kbnode_t node: the node to add
int pkttype: packet type

Description

Insert @node into the list after @root but before a packet which is not of type @pkttype (only if @pkttype != 0).

Function

cdk_kbnode_t cdk_kbnode_find_prev (cdk_kbnode_t root , cdk_kbnode_t node , int pkttype )

Arguments

cdk_kbnode_t root: the root key node
cdk_kbnode_t node: the key node
int pkttype: packet type

Description

Find the previous node (if @pkttype = 0) or the previous node with pkttype @pkttype in the list starting with @root of @node.

Function

cdk_kbnode_t cdk_kbnode_find_next (cdk_kbnode_t node , int pkttype )

Arguments

cdk_kbnode_t node: the key node
int pkttype: packet type

Description

Ditto, but find the next packet. The behaviour is trivial if @pkttype is 0 but if it is specified, the next node with a packet of this type is returned. The function has some knowledge about

the valid ordering of packets

e.g. if the next signature packet is requested, the function will not return one if it encounters a user-id.

Function

cdk_kbnode_t cdk_kbnode_find (cdk_kbnode_t node , int pkttype )

Arguments

cdk_kbnode_t node: the key node
int pkttype: packet type

Description

Try to find the next node with the packettype @pkttype.

Function

cdk_packet_t cdk_kbnode_find_packet (cdk_kbnode_t node , int pkttype )

Arguments

cdk_kbnode_t node: the key node
int pkttype: packet type

Description

Same as cdk_kbnode_find but it returns the packet instead of the node.

Function

int cdk_kbnode_commit (cdk_kbnode_t * root )

Arguments

cdk_kbnode_t * root: the nodes

Description

Commit changes made to the kblist at ROOT. Note that ROOT my change, and it is therefore passed by reference. The function has the effect of removing all nodes marked as deleted. returns true if any node has been changed

Function

void cdk_kbnode_remove (cdk_kbnode_t * root , cdk_kbnode_t node )

Arguments

cdk_kbnode_t * root: the root node
cdk_kbnode_t node: the node to delete

Description

Remove a node from the root node.

Function

void cdk_kbnode_move (cdk_kbnode_t * root , cdk_kbnode_t node , cdk_kbnode_t where )

Arguments

cdk_kbnode_t * root: root node
cdk_kbnode_t node: the node to move
cdk_kbnode_t where: destination place where to move the node.

Description

Move NODE behind right after WHERE or to the beginning if WHERE is NULL.

Function

cdk_packet_t cdk_kbnode_get_packet (cdk_kbnode_t node )

Arguments

cdk_kbnode_t node: the key node

Description

Return the packet which is stored inside the node in @node.

Function

cdk_error_t cdk_kbnode_read_from_mem (cdk_kbnode_t * ret_node , const byte * buf , size_t buflen )

Arguments

cdk_kbnode_t * ret_node: the new key node
const byte * buf: the buffer which stores the key sequence
size_t buflen: the length of the buffer

Description

Try to read a key node from the memory buffer @buf.

Function

cdk_error_t cdk_kbnode_write_to_mem_alloc (cdk_kbnode_t node , byte ** r_buf , size_t * r_buflen )

Arguments

cdk_kbnode_t node: the key node
byte ** r_buf: buffer to hold the raw data
size_t * r_buflen: buffer length of the allocated raw data.

Description

The function acts similar to cdk_kbnode_write_to_mem but it allocates the buffer to avoid the lengthy second run.

Function

cdk_error_t cdk_kbnode_write_to_mem (cdk_kbnode_t node , byte * buf , size_t * r_nbytes )

Arguments

cdk_kbnode_t node: the key node
byte * buf: the buffer to store the node data
size_t * r_nbytes: the new length of the buffer.

Description

Try to write the contents of the key node to the buffer @buf and return the length of it in @r_nbytes. If buf is zero, only the length of the node is calculated and returned in @r_nbytes. Whenever it is possible, the cdk_kbnode_write_to_mem_alloc should be used.

Function

cdk_error_t cdk_kbnode_hash (cdk_kbnode_t node , gcry_md_hd_t md , int is_v4 , int pkttype , int flags )

Arguments

cdk_kbnode_t node: the key node
gcry_md_hd_t md
int is_v4: OpenPGP signature (yes=1, no=0)
int pkttype: packet type to hash (if zero use the packet type from the node)
int flags: flags which depend on the operation

Description

Hash the key node contents. Two modes are supported. If the packet type is used (!= 0) then the function searches the first node with this type. Otherwise the node is seen as a single node and the type is extracted from it.

Function

cdk_error_t cdk_keydb_idx_rebuild (cdk_keydb_hd_t db )

Arguments

cdk_keydb_hd_t db

Description

Rebuild the key index files for the given key database.

Function

cdk_error_t cdk_keydb_new_from_mem (cdk_keydb_hd_t * r_db , int secret , const void * data , size_t datlen )

Arguments

cdk_keydb_hd_t * r_db
int secret
const void * data: The raw key data.
size_t datlen: The length of the raw data.

Description

Create a new keyring db handle from the contents of a buffer.

Function

cdk_error_t cdk_keydb_new_from_stream (cdk_keydb_hd_t * r_hd , int secret , cdk_stream_t in )

Arguments

cdk_keydb_hd_t * r_hd: the output keydb handle
int secret: does the stream contain secret key data
cdk_stream_t in: the input stream to use

Description

This function creates a new keydb handle based on the given stream. The stream is not closed in cdk_keydb_free() and it is up to the caller to close it. No decoding is done.

Function

cdk_error_t cdk_keydb_new (cdk_keydb_hd_t * r_hd , int type , void * data , size_t count )

Arguments

cdk_keydb_hd_t * r_hd: handle to store the new keydb object
int type: type of the keyring
void * data: data which depends on the keyring type
size_t count: length of the data

Description

Create a new keydb object

Function

void cdk_keydb_free (cdk_keydb_hd_t hd )

Arguments

cdk_keydb_hd_t hd: the keydb object

Description

Free the keydb object.

Function

cdk_error_t cdk_keydb_search_start (cdk_keydb_hd_t db , int type , void * desc )

Arguments

cdk_keydb_hd_t db: key database handle
int type: specifies the search type
void * desc: description which depends on the type

Description

Create a new keydb search object.

Function

cdk_error_t cdk_keydb_search (cdk_keydb_hd_t hd , cdk_kbnode_t * ret_key )

Arguments

cdk_keydb_hd_t hd: the keydb object
cdk_kbnode_t * ret_key: kbnode object to store the key

Description

Search for a key in the given keyring. The search mode is handled via @ks. If the key was found, @ret_key contains the key data.

Function

cdk_error_t cdk_listkey_start (cdk_listkey_t * r_ctx , cdk_keydb_hd_t db , const char * patt , cdk_strlist_t fpatt )

Arguments

cdk_listkey_t * r_ctx: pointer to store the new context
cdk_keydb_hd_t db: the key database handle
const char * patt: string pattern
cdk_strlist_t fpatt: recipients from a stringlist to show

Description

Prepare a key listing with the given parameters. Two modes are supported. The first mode uses string pattern to determine if the key should be returned or not. The other mode uses a string list to request the key which should be listed.

Function

void cdk_listkey_close (cdk_listkey_t ctx )

Arguments

cdk_listkey_t ctx: the list key context

Description

Free the list key context.

Function

cdk_error_t cdk_listkey_next (cdk_listkey_t ctx , cdk_kbnode_t * ret_key )

Arguments

cdk_listkey_t ctx: list key context
cdk_kbnode_t * ret_key

Description

Retrieve the next key from the pattern of the key list context.

Function

cdk_error_t cdk_keygen_set_prefs (cdk_keygen_ctx_t hd , enum cdk_pref_type_t type , const byte * array , size_t n )

Arguments

cdk_keygen_ctx_t hd: the preference type
enum cdk_pref_type_t type
const byte * array: one-octet array with algorithm numers
size_t n

Function

void cdk_keygen_set_name (cdk_keygen_ctx_t hd , const char * name )

Arguments

cdk_keygen_ctx_t hd: the keygen object
const char * name: the name to use

Description

' To avoid charset conflicts, the name will be encoded in utf8.

Function

cdk_error_t cdk_keygen_set_algo_info (cdk_keygen_ctx_t hd , int type , int usage , enum cdk_pubkey_algo_t algo , unsigned int bits )

Arguments

cdk_keygen_ctx_t hd: the keygen object.
int type: key type (primary=0, subkey=1)
int usage: key usage
enum cdk_pubkey_algo_t algo: algorithm compliant with rfc2440
unsigned int bits: lengt of the key in bits

Description

set the length and type of the key

Function

int cdk_keygen_set_keyserver_flags (cdk_keygen_ctx_t hd , int no_modify , const char * pref_url )

Arguments

cdk_keygen_ctx_t hd: the handle
int no_modify: set the keyserver no modify flag for the key
const char * pref_url: set the preferred keyser URL.

Description

Set some keyserver specific options for the new key.

Function

int cdk_keygen_set_expire_date (cdk_keygen_ctx_t hd , int type , long timestamp )

Arguments

cdk_keygen_ctx_t hd: keygen object
int type: key type( 0=primary, 1=seconardy)
long timestamp: the date the key should expire

Description

set the expire date of the requested key

Function

cdk_error_t cdk_keygen_start (cdk_keygen_ctx_t hd )

Arguments

cdk_keygen_ctx_t hd: the keygen object

Function

cdk_error_t cdk_keygen_save (cdk_keygen_ctx_t hd , const char * pubf , const char * secf )

Arguments

cdk_keygen_ctx_t hd: the keygen object
const char * pubf
const char * secf

Function

void cdk_keygen_free (cdk_keygen_ctx_t hd )

Arguments

cdk_keygen_ctx_t hd: the keygen object

Function

cdk_error_t cdk_keygen_new (cdk_keygen_ctx_t * r_hd )

Arguments

cdk_keygen_ctx_t * r_hd: the new object

Description

allocate a new key generation context.

Function

int cdk_pklist_select_algo (cdk_keylist_t pkl , int preftype )

Arguments

cdk_keylist_t pkl: the keylist
int preftype: preference type

Description

Select a symmetric cipher algorithm from a list of public keys. This algorithm is present in all key preferences.

Function

void cdk_pklist_release (cdk_keylist_t pkl )

Arguments

cdk_keylist_t pkl: the keylist

Description

Free the memory of the key list.

Function

cdk_error_t cdk_pklist_build (cdk_keylist_t * ret_pkl , cdk_keydb_hd_t db , cdk_strlist_t remusr , int usage )

Arguments

cdk_keylist_t * ret_pkl: the new keylist
cdk_keydb_hd_t db
cdk_strlist_t remusr: the string list of the recipients
int usage: public key usage

Description

Create a public key list based on the recipient names in @remusr.

Function

cdk_error_t cdk_pklist_encrypt (cdk_keylist_t pk_list , cdk_dek_t dek , cdk_stream_t outp )

Arguments

cdk_keylist_t pk_list
cdk_dek_t dek: the data encryption key
cdk_stream_t outp: the stream to write in the data

Description

Encrypt the session key with each key of the list and wrap it into a PUBKEY_ENC packet and write it to @outp.

Function

void cdk_sklist_release (cdk_keylist_t sk_list )

Arguments

cdk_keylist_t sk_list

Description

Free the memory of the secret keylist.

Function

cdk_error_t cdk_sklist_build (cdk_keylist_t * ret_skl , cdk_keydb_hd_t db , cdk_ctx_t hd , cdk_strlist_t locusr , int unlock , unsigned int usage )

Arguments

cdk_keylist_t * ret_skl: return the allocated sec key list.
cdk_keydb_hd_t db: keydb handle
cdk_ctx_t hd: session handle
cdk_strlist_t locusr: local user list
int unlock: 1=unlock secret keys
unsigned int usage: secret key usage.

Function

cdk_error_t cdk_sklist_write_onepass (cdk_keylist_t skl , cdk_stream_t outp , int sigclass , int mdalgo )

Arguments

cdk_keylist_t skl: secret keylist
cdk_stream_t outp: the stream to write in the data
int sigclass: the class of the sig to create
int mdalgo: the message digest algorithm

Description

Write a one-pass signature for each key in the list into @outp.

Function

cdk_error_t cdk_sklist_write (cdk_keylist_t skl , cdk_stream_t outp , gcry_md_hd_t hash , int sigclass , int sigver )

Arguments

cdk_keylist_t skl: secret keylist
cdk_stream_t outp: the stream to write in the data
gcry_md_hd_t hash: opaque handle for the message digest operations
int sigclass: the class of the sig
int sigver: version of the sig

Description

Complete the sig based on @hash and write all signatures to @outp.

Function

cdk_error_t cdk_keyserver_recv_key (const char * host , int port , const byte * keyid , int kid_type , cdk_kbnode_t * ret_key )

Arguments

const char * host: URL or hostname of the keyserver
int port: The port to use for the connection
const byte * keyid: KeyID of the key to retrieve
int kid_type: KeyID type (long, short, fingerprint)
cdk_kbnode_t * ret_key

Description

Receive a key from a keyserver.

Function

const char* cdk_strerror (int ec )

Arguments

int ec: the error number

Description

Return an error text for the given id.

Function

void cdk_set_malloc_hooks (void * (*new_alloc_func )

Arguments

void * (*new_alloc_func

Description

Set private memory hooks for the library.

Function

int cdk_malloc_hook_initialized ( void )

Arguments

void

Description

Return if the malloc hooks are already initialized.

Function

void* cdk_calloc (size_t n , size_t m )

Arguments

size_t n: amount of elements
size_t m: size of one element

Description

Safe wrapper around the c-function calloc.

Function

void cdk_lib_startup ( void )

Arguments

void

Description

Prepare the internal structures of the library. This function should be called before any other CDK function.

Function

void cdk_lib_shutdown ( void )

Arguments

void

Description

Shutdown the library and free all internal and globally used memory and structures. This function should be called in the exit handler of the calling program.

Function

void* cdk_salloc (size_t size , int clear )

Arguments

size_t size: how much bytes should be allocated.
int clear: shall the buffer cleared after the allocation?

Description

Allocated the requested amount of bytes in 'secure' memory.

Function

void cdk_set_log_handler (cdk_log_fnc_t logfnc , void * opaque )

Arguments

cdk_log_fnc_t logfnc: the function pointer
void * opaque: a private values for the function

Description

Set a custom handler for logging.

Function

void cdk_set_log_level (int level )

Arguments

int level

Description

Set the verbosity level.

Function

int cdk_handle_control (cdk_ctx_t hd , int action , int cmd , ... )

Arguments

cdk_ctx_t hd: session handle
int action: flag which indicates whether put or get is requested
int cmd: command id
...

Description

Perform various control operations for the current session.

Function

cdk_error_t cdk_handle_new (cdk_ctx_t * r_ctx )

Arguments

cdk_ctx_t * r_ctx: context to store the handle

Description

create a new session handle.

Function

cdk_error_t cdk_handle_set_keyring (cdk_ctx_t hd , int type , const char * kringname )

Arguments

cdk_ctx_t hd: session handle
int type: public=0 or secret=1 keyring type
const char * kringname: file name of the keyring which shall be used.

Description

Convenient function to set the keyring for the current session.

Function

void cdk_handle_set_keydb (cdk_ctx_t hd , cdk_keydb_hd_t db )

Arguments

cdk_ctx_t hd: session handle
cdk_keydb_hd_t db: the database handle

Description

set the key database handle. the function automatically detects whether this is a public or secret keyring and the right handle is set.

Function

cdk_keydb_hd_t cdk_handle_get_keydb (cdk_ctx_t hd , int type )

Arguments

cdk_ctx_t hd: session handle
int type: type of the keyring

Description

Return the keydb handle from the session handle. The caller should not free these handles.

Function

void cdk_handle_set_passphrase_cb (cdk_ctx_t hd , char * (*cb )

Arguments

cdk_ctx_t hd: session handle
char * (*cb

Description

set the passphrase callback.

Function

cdk_verify_result_t cdk_handle_verify_get_result (cdk_ctx_t hd )

Arguments

cdk_ctx_t hd: the session handle

Description

Return the verify result for the current session. Do not free the pointer.

Function

void cdk_handle_free (cdk_ctx_t hd )

Arguments

cdk_ctx_t hd: the handle

Description

Release the main handle.

Function

const char * cdk_check_version (const char * req_version )

Arguments

const char * req_version: The requested version

Description

Check that the the version of the library is at minimum the requested one and return the version string; return NULL if the condition is not satisfied. If a NULL is passed to this function, no check is done, but the version string is simply returned.

Function

void cdk_strlist_free (cdk_strlist_t sl )

Arguments

cdk_strlist_t sl: the string list

Description

Release the string list object.

Function

cdk_strlist_t cdk_strlist_add (cdk_strlist_t * list , const char * string )

Arguments

cdk_strlist_t * list: destination string list
const char * string: the string to add

Description

Add the given list to the string list.

Function

cdk_strlist_t cdk_strlist_next (cdk_strlist_t root , const char ** r_str )

Arguments

cdk_strlist_t root: the opaque string list.
const char ** r_str: optional argument to store the string data.

Description

Return the next string list node from @root. The optional argument @r_str return the data of the current (!) node.

Function

char* cdk_utf8_encode (const char * string )

Arguments

const char * string

Description

Encode the given string in utf8 and return it.

Function

char * cdk_utf8_decode (const char * string , size_t length , int delim )

Arguments

const char * string: the string to decode
size_t length: the length of the string
int delim: the delimiter

Description

Decode the given utf8 string and return the native representation.

Function

void cdk_pkt_release (cdk_packet_t pkt )

Arguments

cdk_packet_t pkt: the packet

Description

Free the contents of the given package and release the memory of the structure.

Function

cdk_error_t cdk_pkt_alloc (cdk_packet_t * r_pkt , int pkttype )

Arguments

cdk_packet_t * r_pkt: output is the new packet
int pkttype: the requested packet type

Description

Allocate a new packet structure with the given packet type.

Function

void cdk_subpkt_free (cdk_subpkt_t ctx )

Arguments

cdk_subpkt_t ctx: the sub packet node to free

Description

Release the context.

Function

cdk_subpkt_t cdk_subpkt_find (cdk_subpkt_t ctx , size_t type )

Arguments

cdk_subpkt_t ctx: the sub packet node
size_t type: the packet type to find

Description

Find the given packet type in the node. If no packet with this type was found, return null otherwise pointer to the node.

Function

size_t cdk_subpkt_type_count (cdk_subpkt_t ctx , size_t type )

Arguments

cdk_subpkt_t ctx: The sub packet context
size_t type: The sub packet type.

Description

Return the amount of sub packets with this type.

Function

cdk_subpkt_t cdk_subpkt_find_nth (cdk_subpkt_t ctx , size_t type , size_t idx )

Arguments

cdk_subpkt_t ctx: The sub packet context
size_t type: The sub packet type
size_t idx

Description

Return the nth sub packet of the given type.

Function

cdk_subpkt_t cdk_subpkt_new (size_t size )

Arguments

size_t size: the size of the new context

Description

Create a new sub packet node with the size of @size.

Function

const byte* cdk_subpkt_get_data (cdk_subpkt_t ctx , size_t * r_type , size_t * r_nbytes )

Arguments

cdk_subpkt_t ctx: the sub packet node
size_t * r_type: pointer store the packet type
size_t * r_nbytes: pointer to store the packet size

Description

Extract the data from the given sub packet. The type is returned in @r_type and the size in @r_nbytes.

Function

cdk_error_t cdk_subpkt_add (cdk_subpkt_t root , cdk_subpkt_t node )

Arguments

cdk_subpkt_t root: the root node
cdk_subpkt_t node: the node to add

Description

Add the node in @node to the root node @root.

Function

void cdk_subpkt_init (cdk_subpkt_t node , size_t type , const void * buf , size_t buflen )

Arguments

cdk_subpkt_t node: the sub packet node
size_t type: type of the packet which data should be initialized
const void * buf: the buffer with the actual data
size_t buflen: the size of the data

Description

Set the packet data of the given root and set the type of it.

Function

cdk_subpkt_t cdk_subpkt_find_next (cdk_subpkt_t root , size_t type )

Arguments

cdk_subpkt_t root: the base where to begin the iteration
size_t type: the type to find or 0 for the next node.

Description

Try to find the next node after @root with type. If type is 0, the next node will be returned.

Function

cdk_error_t cdk_pk_encrypt (cdk_pubkey_t pk , cdk_pkt_pubkey_enc_t pke , gcry_mpi_t esk )

Arguments

cdk_pubkey_t pk: the public key
cdk_pkt_pubkey_enc_t pke: the public key encrypted packet
gcry_mpi_t esk: the actual session key

Description

Encrypt the session key in @esk and write its encrypted content into the @pke struct.

Function

cdk_error_t cdk_pk_decrypt (cdk_seckey_t sk , cdk_pkt_pubkey_enc_t pke , gcry_mpi_t * r_sk )

Arguments

cdk_seckey_t sk: the secret key
cdk_pkt_pubkey_enc_t pke: public key encrypted packet
gcry_mpi_t * r_sk: the object to store the plain session key

Description

Decrypt the encrypted session key from @pke into @r_sk.

Function

cdk_error_t cdk_pk_sign (cdk_seckey_t sk , cdk_pkt_signature_t sig , const byte * md )

Arguments

cdk_seckey_t sk: secret key
cdk_pkt_signature_t sig: signature
const byte * md: the message digest

Description

Sign the message digest from @md and write the result into @sig.

Function

cdk_error_t cdk_pk_verify (cdk_pubkey_t pk , cdk_pkt_signature_t sig , const byte * md )

Arguments

cdk_pubkey_t pk: the public key
cdk_pkt_signature_t sig: signature
const byte * md: the message digest

Description

Verify the signature in @sig and compare it with the message digest in @md.

Function

int cdk_pk_get_nbits (cdk_pubkey_t pk )

Arguments

cdk_pubkey_t pk: the public key

Description

Return the length of the public key in bits. The meaning of length is actually the size of the 'prime' object in the key. For RSA keys the modulus, for ElG/DSA the size of the public prime.

Function

int cdk_pk_get_npkey (int algo )

Arguments

int algo: The public key algorithm.

Description

Return the number of multiprecison integer forming an public key with the given algorithm.

Function

int cdk_pk_get_nskey (int algo )

Arguments

int algo: the public key algorithm

Description

Return the number of multiprecision integers forming an secret key with the given algorithm.

Function

int cdk_pk_get_nsig (int algo )

Arguments

int algo: the public key algorithm

Description

Return the number of MPIs a signature consists of.

Function

int cdk_pk_get_nenc (int algo )

Arguments

int algo: the public key algorithm

Description

Return the number of MPI's the encrypted data consists of.

Function

cdk_error_t cdk_pk_get_mpi (cdk_pubkey_t pk , size_t idx , byte * buf , size_t buflen , size_t * r_nwritten , size_t * r_nbits )

Arguments

cdk_pubkey_t pk: public key
size_t idx: index of the MPI to retrieve
byte * buf: buffer to hold the raw data
size_t buflen
size_t * r_nwritten: output how large the raw data is
size_t * r_nbits: size of the MPI in bits.

Description

Return the MPI with the given index of the public key.

Function

cdk_error_t cdk_sk_get_mpi (cdk_pkt_seckey_t sk , size_t idx , byte * buf , size_t buflen , size_t * r_nwritten , size_t * r_nbits )

Arguments

cdk_pkt_seckey_t sk: secret key
size_t idx: index of the MPI to retrieve
byte * buf: buffer to hold the raw data
size_t buflen
size_t * r_nwritten: output length of the raw data
size_t * r_nbits: length of the MPI data in bits.

Description

Return the MPI of the given secret key with the index @idx. It is important to check if the key is protected and thus no real MPI data will be returned then.

Function

cdk_error_t cdk_sk_unprotect (cdk_pkt_seckey_t sk , const char * pw )

Arguments

cdk_pkt_seckey_t sk: the secret key
const char * pw: the passphrase

Description

Unprotect the given secret key with the passphrase.

Function

cdk_error_t cdk_sk_protect (cdk_pkt_seckey_t sk , const char * pw )

Arguments

cdk_pkt_seckey_t sk: the secret key
const char * pw: the passphrase to use

Description

Protect the given secret key with a passphrase.

Function

cdk_error_t cdk_pk_from_secret_key (cdk_pkt_seckey_t sk , cdk_pubkey_t * ret_pk )

Arguments

cdk_pkt_seckey_t sk: the secret key
cdk_pubkey_t * ret_pk: the new public key

Description

Create a new public key from a secret key.

Function

cdk_error_t cdk_pk_get_fingerprint (cdk_pubkey_t pk , byte * fpr )

Arguments

cdk_pubkey_t pk: the public key
byte * fpr: the buffer to hold the fingerprint

Description

Return the fingerprint of the given public key. The buffer must be at least 20 octets. This function should be considered deprecated and the new cdk_pk_to_fingerprint() should be used whenever possible to avoid overflows.

Function

cdk_error_t cdk_pk_to_fingerprint (cdk_pubkey_t pk , byte * fprbuf , size_t fprbuflen , size_t * r_nout )

Arguments

cdk_pubkey_t pk: the public key
byte * fprbuf: buffer to save the fingerprint
size_t fprbuflen: buffer size
size_t * r_nout: actual length of the fingerprint.

Description

Calculate a fingerprint of the given key and return it in the given byte array.

Function

u32 cdk_pk_fingerprint_get_keyid (const byte * fpr , size_t fprlen , u32 * keyid )

Arguments

const byte * fpr: the key fingerprint
size_t fprlen: the length of the fingerprint
u32 * keyid

Description

Derive the key ID from the key fingerprint. For version 3 keys, this is not working.

Function

u32 cdk_pk_get_keyid (cdk_pubkey_t pk , u32 * keyid )

Arguments

cdk_pubkey_t pk: the public key
u32 * keyid: buffer to store the key ID

Description

Calculate the key ID of the given public key.

Function

u32 cdk_sk_get_keyid (cdk_pkt_seckey_t sk , u32 * keyid )

Arguments

cdk_pkt_seckey_t sk: the secret key
u32 * keyid: buffer to hold the key ID

Description

Calculate the key ID of the secret key, actually the public key.

Function

u32 cdk_sig_get_keyid (cdk_pkt_signature_t sig , u32 * keyid )

Arguments

cdk_pkt_signature_t sig: the signature
u32 * keyid: buffer to hold the key ID

Description

Retrieve the key ID from the given signature.

Function

cdk_error_t cdk_pubkey_to_sexp (cdk_pubkey_t pk , char ** sexp , size_t * len )

Arguments

cdk_pubkey_t pk: the public key
char ** sexp: where to store the S-expression
size_t * len: the length of sexp

Description

Convert a public key to an S-expression. sexp is allocated by this function, but you have to cdk_free() it yourself. The S-expression is stored in canonical format as used by libgcrypt (GCRYSEXP_FMT_CANON).

Function

cdk_error_t cdk_seckey_to_sexp (cdk_pkt_seckey_t sk , char ** sexp , size_t * len )

Arguments

cdk_pkt_seckey_t sk: the secret key
char ** sexp: where to store the S-expression
size_t * len: the length of sexp

Description

Function

cdk_error_t cdk_pkt_read (cdk_stream_t inp , cdk_packet_t pkt )

Arguments

cdk_stream_t inp: the input stream
cdk_packet_t pkt: allocated packet handle to store the packet

Description

Parse the next packet on the @inp stream and return its contents in @pkt.

Function

cdk_error_t cdk_dek_encode_pkcs1 (cdk_dek_t dek , size_t nbits , gcry_mpi_t * r_enc )

Arguments

cdk_dek_t dek: DEK object
size_t nbits: size of the multi precision integer frame
gcry_mpi_t * r_enc: output of the encoded multiprecision integer

Description

Encode the given random session key in the DEK object into a multiprecision integer.

Function

cdk_error_t cdk_dek_decode_pkcs1 (cdk_dek_t * ret_dek , gcry_mpi_t esk )

Arguments

cdk_dek_t * ret_dek: the decoded DEK object
gcry_mpi_t esk: the pkcs#1 encoded session key.

Description

Decode the given multi precision integer in pkcs#1 and store it into the DEK object.

Function

cdk_error_t cdk_dek_extract (cdk_dek_t * ret_dek , cdk_ctx_t hd , cdk_pkt_pubkey_enc_t enc , cdk_pkt_seckey_t sk )

Arguments

cdk_dek_t * ret_dek
cdk_ctx_t hd
cdk_pkt_pubkey_enc_t enc: the public key encrypted packet
cdk_pkt_seckey_t sk: the secret key.

ret_dek

the raw DEK object

hd

the session handle

Description

Try to extract the DEK from the public key encrypted packet.

Function

cdk_error_t cdk_dek_new (cdk_dek_t * r_dek )

Arguments

cdk_dek_t * r_dek: the new DEK object

Description

Create a new DEK object.

Function

cdk_error_t cdk_dek_set_cipher (cdk_dek_t dek , int algo )

Arguments

cdk_dek_t dek: the DEK object
int algo: the cipher algorithm to use

Description

Set the cipher for the given DEK object.

Function

cdk_error_t cdk_dek_set_key (cdk_dek_t dek , const byte * key , size_t keylen )

Arguments

cdk_dek_t dek: the DEK object
const byte * key: the random session key
size_t keylen: the length of the session key.

Description

Set the random session key for the given DEK object. If @key and @keylen is NULL (0) a random key will be generated. In any case, cdk_dek_set_cipher must be called first.

Function

void cdk_dek_set_mdc_flag (cdk_dek_t dek , int val )

Arguments

cdk_dek_t dek: the DEK object
int val: value to enable or disable the use

Description

Enable or disable the MDC flag for the given DEK object.

Function

void cdk_dek_free (cdk_dek_t dek )

Arguments

cdk_dek_t dek: the DEK object

Description

Release the DEK object.

Function

cdk_error_t cdk_dek_from_passphrase (cdk_dek_t * ret_dek , int cipher_algo , cdk_s2k_t s2k , int rndsalt , const char * pw )

Arguments

cdk_dek_t * ret_dek: the new DEK.
int cipher_algo: symmetric key algorithm to use
cdk_s2k_t s2k: the S2K to use
int rndsalt: 1=create random salt
const char * pw: the passphrase.

Description

Transform a passphrase into a DEK object.

Function

cdk_error_t cdk_s2k_new (cdk_s2k_t * ret_s2k , int mode , int digest_algo , const byte * salt )

Arguments

cdk_s2k_t * ret_s2k: output for the new S2K object
int mode: the S2K mode (simple, salted, iter+salted)
int digest_algo: the hash algorithm
const byte * salt: random salt

Description

Create a new S2K object with the given parameter. The @salt parameter must be always 8 octets.

Function

void cdk_s2k_free (cdk_s2k_t s2k )

Arguments

cdk_s2k_t s2k: the S2K object

Description

Release the given S2K object.

Function

cdk_error_t cdk_pk_check_sigs (cdk_kbnode_t knode , cdk_keydb_hd_t keydb , int * r_status )

Arguments

cdk_kbnode_t knode: the key node
cdk_keydb_hd_t keydb
int * r_status: variable to store the status of the key

Description

Check all signatures. When no key is available for checking, the sigstat is marked as 'NOKEY'. The @r_status contains the key flags which are or-ed or zero when there are no flags.

Function

cdk_error_t cdk_pk_check_self_sig (cdk_kbnode_t knode , int * r_status )

Arguments

cdk_kbnode_t knode: the key node
int * r_status: output the status of the key.

Description

A convenient function to make sure the key is valid. Valid means the self signature is ok.

Function

cdk_error_t cdk_stream_sign (cdk_ctx_t hd , cdk_stream_t inp , cdk_stream_t out , cdk_strlist_t locusr , cdk_strlist_t remusr , int encryptflag , int sigmode )

Arguments

cdk_ctx_t hd: session handle
cdk_stream_t inp: input stream
cdk_stream_t out: output stream
cdk_strlist_t locusr: local user list for signing
cdk_strlist_t remusr
int encryptflag: shall the output be encrypted? (1/0)
int sigmode: signature mode

Description

Sign the data from the STREAM @inp.

Function

cdk_error_t cdk_file_sign (cdk_ctx_t hd , cdk_strlist_t locusr , cdk_strlist_t remusr , const char * file , const char * output , int sigmode , int encryptflag )

Arguments

cdk_ctx_t hd
cdk_strlist_t locusr: List of userid which should be used for signing
cdk_strlist_t remusr: If encrypt is valid, the list of recipients
const char * file: Name of the input file
const char * output: Name of the output file
int sigmode: Signature mode
int encryptflag

Description

Sign a file.

Function

cdk_error_t cdk_stream_open (const char * file , cdk_stream_t * ret_s )

Arguments

const char * file: The file to open
cdk_stream_t * ret_s: The new STREAM object

Description

Create a new stream based on an existing file. The stream is opened in read-only mode.

Function

cdk_error_t cdk_stream_new_from_cbs (cdk_stream_cbs_t cbs , void * opa , cdk_stream_t * ret_s )

Arguments

cdk_stream_cbs_t cbs: the callback context with all user callback functions
void * opa: opaque handle which is passed to all callbacks.
cdk_stream_t * ret_s: the allocated stream

Description

This function creates a stream which uses user callback for the core operations (open, close, read, write, seek).

Function

cdk_error_t cdk_stream_new (const char * file , cdk_stream_t * ret_s )

Arguments

const char * file: The name of the new file
cdk_stream_t * ret_s: The new STREAM object

Function

cdk_error_t cdk_stream_create (const char * file , cdk_stream_t * ret_s )

Arguments

const char * file: the filename
cdk_stream_t * ret_s: the object

Description

The difference to cdk_stream_new is, that no filtering can be used with this kind of stream and everything is written directly to the stream.

Function

cdk_error_t cdk_stream_tmp_new (cdk_stream_t * r_out )

Arguments

cdk_stream_t * r_out: the new temp stream.

Description

Allocate a new tempory stream which is not associated with a file.

Function

cdk_error_t cdk_stream_tmp_from_mem (const void * buf , size_t buflen , cdk_stream_t * r_out )

Arguments

const void * buf: the buffer which shall be written to the temp stream.
size_t buflen: how large the buffer is
cdk_stream_t * r_out: the new stream with the given contents.

Description

Create a new tempory stream with the given contests.

Function

int cdk_stream_is_compressed (cdk_stream_t s )

Arguments

cdk_stream_t s: the stream

Description

Return 0 if the stream is uncompressed, otherwise the compression algorithm.

Function

cdk_error_t cdk_stream_close (cdk_stream_t s )

Arguments

cdk_stream_t s: The STREAM object.

Description

This function work different for read or write streams. When the stream is for reading, the filtering is already done and we can simply close the file and all buffers. But for the case it's a write stream, we need to apply all registered filters now. The file is closed in the filter function and not here.

Function

int cdk_stream_eof (cdk_stream_t s )

Arguments

cdk_stream_t s: The STREAM object.

Description

This function will only work with read streams.

Function

off_t cdk_stream_get_length (cdk_stream_t s )

Arguments

cdk_stream_t s: The STREAM object.

Description

This function should work for both read and write streams. For write streams an additional flush is used to write possible pending data.

Function

cdk_error_t cdk_stream_filter_disable (cdk_stream_t s , int type )

Arguments

cdk_stream_t s: The STREAM object
int type: The numberic filter ID.

Function

int cdk_stream_read (cdk_stream_t s , void * buf , size_t buflen )

Arguments

cdk_stream_t s: The STREAM object.
void * buf: The buffer to insert the readed bytes.
size_t buflen

Description

When this function is called the first time, it can take a while because all filters need to be processed. Please remember that you need to add the filters in reserved order.

Function

int cdk_stream_write (cdk_stream_t s , const void * buf , size_t count )

Arguments

cdk_stream_t s: The STREAM object
const void * buf: The buffer with the values to write.
size_t count: The size of the buffer.

Description

In this function we simply write the bytes to the stream. We can't use the filters here because it would mean they have to support partial flushing.

Function

cdk_error_t cdk_stream_set_armor_flag (cdk_stream_t s , int armor_type )

Arguments

cdk_stream_t s: the stream object
int armor_type

Description

If the file is in read-mode, no armor type needs to be defined (armor_type=0) because the armor filter will be used for decoding existing armor data. For the write mode, @armor_type can be set to any valid armor type (message, key, sig).

Function

cdk_error_t cdk_stream_set_literal_flag (cdk_stream_t s , cdk_lit_format_t mode , const char * fname )

Arguments

cdk_stream_t s: the stream object
cdk_lit_format_t mode: the mode to use (binary, text, unicode)
const char * fname: the file name to store in the packet.

Description

In read mode it kicks off the literal decoding routine to unwrap the data from the packet. The @mode parameter is ignored. In write mode the function can be used to wrap the stream data into a literal packet with the given mode and file name.

Function

cdk_error_t cdk_stream_set_cipher_flag (cdk_stream_t s , cdk_dek_t dek , int use_mdc )

Arguments

cdk_stream_t s: the stream object
cdk_dek_t dek: the data encryption key
int use_mdc: 1 means to use the MDC mode

Description

In read mode it kicks off the cipher filter to decrypt the data from the stream with the key given in @dek. In write mode the stream data will be encrypted with the DEK object and optionally, the @use_mdc parameter can be used to enable the MDC mode.

Function

cdk_error_t cdk_stream_set_compress_flag (cdk_stream_t s , int algo , int level )

Arguments

cdk_stream_t s: the stream object
int algo: the compression algo
int level: level of compression (0..9)

Description

In read mode it kicks off the decompression filter to retrieve the uncompressed data. In write mode the stream data will be compressed with the given algorithm at the given level.

Function

cdk_error_t cdk_stream_set_text_flag (cdk_stream_t s , const char * lf )

Arguments

cdk_stream_t s: the stream object
const char * lf: line ending

Description

Pushes the text filter to store the stream data in cannoncial format.

Function

cdk_error_t cdk_stream_set_hash_flag (cdk_stream_t s , int digest_algo )

Arguments

cdk_stream_t s: the stream object
int digest_algo: the digest algorithm to use

Description

This is for read-only streams. It pushes a digest filter to calculate the digest of the given stream data.

Function

cdk_error_t cdk_stream_enable_cache (cdk_stream_t s , int val )

Arguments

cdk_stream_t s: the stream object
int val: 1=on, 0=off

Description

Enable or disable the cache section of a stream object.

Function

cdk_error_t cdk_stream_kick_off (cdk_stream_t inp , cdk_stream_t out )

Arguments

cdk_stream_t inp: the input stream
cdk_stream_t out: the output stream.

Description

Passes the entire data from @inp into the output stream @out with all the activated filters.

Function

cdk_error_t cdk_stream_mmap_part (cdk_stream_t s , off_t off , size_t len , byte ** ret_buf , size_t * ret_buflen )

Arguments

cdk_stream_t s: the stream
off_t off: the offset where to start
size_t len: how much bytes shall be mapped
byte ** ret_buf: the buffer to store the content
size_t * ret_buflen: length of the buffer

Description

Map the data of the given stream into a memory section. @ret_count contains the length of the buffer.

Function

int cdk_stream_peek (cdk_stream_t inp , byte * buf , size_t buflen )

Arguments

cdk_stream_t inp: the input stream handle
byte * buf
size_t buflen

Description

The function acts like cdk_stream_read with the difference that the file pointer is moved to the old position after the bytes were read.

Function

cdk_error_t cdk_stream_sockopen (const char * host , unsigned short port , cdk_stream_t * ret_out )

Arguments

const char * host: the host to connect to
unsigned short port: the port to use
cdk_stream_t * ret_out: contains the connect stream.

Connect a stream to the given host

port pair.

Function

cdk_error_t cdk_stream_verify (cdk_ctx_t hd , cdk_stream_t inp , cdk_stream_t data , cdk_stream_t out )

Arguments

cdk_ctx_t hd: session handle
cdk_stream_t inp: the input stream
cdk_stream_t data: for detached signatures, this is the data stream @inp is the sig
cdk_stream_t out: where the output shall be written.

Function

cdk_error_t cdk_file_verify (cdk_ctx_t hd , const char * file , const char * data_file , const char * output )

Arguments

cdk_ctx_t hd: the session handle
const char * file: the input file
const char * data_file: for detached signature this is the data file and @file is the sig.
const char * output: the output file

Description

Verify a signature.

Function

cdk_error_t cdk_pkt_write (cdk_stream_t out , cdk_packet_t pkt )

Arguments

cdk_stream_t out: the output stream handle
cdk_packet_t pkt: the packet itself

Description

Write the contents of @pkt into the @out stream. Return 0 on success.