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