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

It is suggested to use a name in the following format 'First Name' 'Last Name' ' 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

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_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.