doxygen: added a whole lot of automated doc. Needs tweaking and more.

2 years ago · 46064ffd15
--- a/engine_doxygen.conf
+++ b/engine_doxygen.conf
@ -262,6 +262,9 @@ TAB_SIZE               = 4
 # a double escape (\\{ and \\})

 ALIASES                +=	"license=@par License:^^"
 ALIASES                +=	"copyleft=@par Copyleft:^^"
 ALIASES                +=	"ownership=@par Ownership^^"


 # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources
 # only. Doxygen will then generate output that is more tailored for C. For
@ -855,9 +858,6 @@ FILE_PATTERNS          = *.c \
                         *.cxx \
                         *.cpp \
                         *.c++ \
                         *.java \
                         *.ddl \
                         *.odl \
                         *.h \
                         *.hh \
                         *.hxx \
@ -867,23 +867,7 @@ FILE_PATTERNS          = *.c \
                         *.markdown \
                         *.md \
                         *.mm \
                         *.dox \
                         *.doc \
                         *.txt \
                         *.py \
                         *.pyw \
                         *.f90 \
                         *.f95 \
                         *.f03 \
                         *.f08 \
                         *.f18 \
                         *.f \
                         *.for \
                         *.vhd \
                         *.vhdl \
                         *.ucf \
                         *.qsf \
                         *.ice
                         *.txt

 # The RECURSIVE tag can be used to specify whether or not subdirectories should
 # be searched for input files as well.
@ -2162,7 +2146,7 @@ INCLUDE_FILE_PATTERNS  =
 # recursively expanded use the := operator instead of the = operator.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.

 PREDEFINED             =
 PREDEFINED             = ENIGMAIL_MAY_USE_THIS

 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The
--- a/src/aux_mime_msg.h
+++ b/src/aux_mime_msg.h
@ -1,8 +1,12 @@
 /** @file */
 /** @brief File description for doxygen missing. FIXME */

 // This file is under GNU General Public License 3.0
 // see LICENSE.txt
 /**
 * @file      aux_mime_msg.h
 * 
 * @brief     Auxilliary file which provides the MIME* functions for the enigmail/pEp implementation and some tests.
 *            Provides access to pEp functions for messages fed in in MIME string format instead of
 *            through the message struct.
 * 
 * @license   GNU General Public License 3.0 - see LICENSE.txt
 */

 #pragma once

@ -17,29 +21,31 @@
 extern "C" {
 #endif

 // MIME_encrypt_message() - encrypt a MIME message, with MIME output
 //
 //  parameters:
 //      session (in)            session handle
 //      mimetext (in)           MIME encoded text to encrypt
 //      size (in)               size of input mime text
 //      extra (in)              extra keys for encryption
 //      mime_ciphertext (out)   encrypted, encoded message
 //      enc_format (in)         encrypted format
 //      flags (in)              flags to set special encryption features
 //
 //  return value:
 //      PEP_STATUS_OK           if everything worked
 //      PEP_BUFFER_TOO_SMALL    if encoded message size is too big to handle
 //      PEP_CANNOT_CREATE_TEMP_FILE
 //                              if there are issues with temp files; in
 //                              this case errno will contain the underlying
 //                              error
 //      PEP_OUT_OF_MEMORY       if not enough memory could be allocated
 //
 //  caveat:
 //      the encrypted, encoded mime text will go to the ownership of the caller; mimetext
 //      will remain in the ownership of the caller
 /**
 *  <!--       MIME_encrypt_message()       -->
 *  
 *  @brief Encrypt a MIME message, with MIME output
 *  
 *  @param[in]     session            session handle
 *  @param[in]     mimetext           MIME encoded text to encrypt
 *  @param[in]     size               size of input mime text
 *  @param[in]     extra              extra keys for encryption
 *  @param[out]    mime_ciphertext    encrypted, encoded message
 *  @param[in]     enc_format         encrypted format
 *  @param[in]     flags              flags to set special encryption features
 *  
 *  @retval PEP_STATUS_OK                   if everything worked
 *  @retval PEP_BUFFER_TOO_SMALL            if encoded message size is too big to handle
 *  @retval PEP_CANNOT_CREATE_TEMP_FILE     if there are issues with temp files; in
 *                                          this case errno will contain the underlying
 *                                          error
 *  @retval PEP_OUT_OF_MEMORY       if not enough memory could be allocated
 *  
 *  @ownership 
 *  -  the encrypted, encoded mime text will go to the ownership of the caller 
 *  -  the original mimetext will remain in the ownership of the caller
 *  
 */
 DYNAMIC_API PEP_STATUS MIME_encrypt_message(
    PEP_SESSION session,
    const char *mimetext,
@ -51,31 +57,34 @@ DYNAMIC_API PEP_STATUS MIME_encrypt_message(
 );


 // MIME_encrypt_message_for_self() - encrypt MIME message for user's identity only,
 //                              ignoring recipients and other identities from
 //                              the message, with MIME output
 //  parameters:
 //      session (in)            session handle
 //      target_id (in)          self identity this message should be encrypted for
 //      mimetext (in)           MIME encoded text to encrypt
 //      size (in)               size of input mime text
 //      extra (in)              extra keys for encryption
 //      mime_ciphertext (out)   encrypted, encoded message
 //      enc_format (in)         encrypted format
 //      flags (in)              flags to set special encryption features
 //
 //  return value:
 //      PEP_STATUS_OK           if everything worked
 //      PEP_BUFFER_TOO_SMALL    if encoded message size is too big to handle
 //      PEP_CANNOT_CREATE_TEMP_FILE
 //                              if there are issues with temp files; in
 //                              this case errno will contain the underlying
 //                              error
 //      PEP_OUT_OF_MEMORY       if not enough memory could be allocated
 //
 //  caveat:
 //      the encrypted, encoded mime text will go to the ownership of the caller; mimetext
 //      will remain in the ownership of the caller
 /**
 *  <!--       MIME_encrypt_message_for_self()       -->
 *  
 *  @brief Encrypt MIME message for user's identity only,
 *         ignoring recipients and other identities from
 *         the message, with MIME output
 *  
 *  @param[in]     session            session handle
 *  @param[in]     target_id          self identity this message should be encrypted for
 *  @param[in]     mimetext           MIME encoded text to encrypt
 *  @param[in]     size               size of input mime text
 *  @param[in]     extra              extra keys for encryption
 *  @param[out]    mime_ciphertext    encrypted, encoded message
 *  @param[in]     enc_format         encrypted format
 *  @param[in]     flags              flags to set special encryption features
 *  
 *  @retval PEP_STATUS_OK                   if everything worked
 *  @retval PEP_BUFFER_TOO_SMALL            if encoded message size is too big to handle
 *  @retval PEP_CANNOT_CREATE_TEMP_FILE     if there are issues with temp files; in
 *                                          this case errno will contain the underlying
 *                                          error
 *  @retval PEP_OUT_OF_MEMORY       if not enough memory could be allocated
 *  
 *  @ownership 
 *  -  the encrypted, encoded mime text will go to the ownership of the caller 
 *  -  the original mimetext will remain in the ownership of the caller
 *  
 */
 DYNAMIC_API PEP_STATUS MIME_encrypt_message_for_self(
    PEP_SESSION session,
    pEp_identity* target_id,
@ -89,52 +98,64 @@ DYNAMIC_API PEP_STATUS MIME_encrypt_message_for_self(



 // MIME_decrypt_message() - decrypt a MIME message, with MIME output
 //
 //  parameters:
 //      session (in)            session handle
 //      mimetext (in)           MIME encoded text to decrypt
 //      size (in)               size of mime text to decode (in order to decrypt)
 //      mime_plaintext (out)    decrypted, encoded message
 //      keylist (inout)         in: stringlist with additional keyids for reencryption if needed
 //                                  (will be freed and replaced with output keylist)
 //                              out: stringlist with keyids
 //      rating (out)            rating for the message
 //      flags (inout)           flags to signal special decryption features (see below)
 //      modified_src (out)      modified source string, if decrypt had reason to change it
 //
 //  return value:
 //      decrypt status          if everything worked with MIME encode/decode, 
 //                              the status of the decryption is returned 
 //                              (PEP_STATUS_OK or decryption error status)
 //      PEP_BUFFER_TOO_SMALL    if encoded message size is too big to handle
 //      PEP_CANNOT_CREATE_TEMP_FILE
 //                              if there are issues with temp files; in
 //                              this case errno will contain the underlying
 //                              error
 //      PEP_OUT_OF_MEMORY       if not enough memory could be allocated
 //
 //  flag values:
 //      in:
 //          PEP_decrypt_flag_untrusted_server
 //              used to signal that decrypt function should engage in behaviour
 //              specified for when the server storing the source is untrusted.
 //      out:
 //          PEP_decrypt_flag_own_private_key
 //              private key was imported for one of our addresses (NOT trusted
 //              or set to be used - handshake/trust is required for that)
 //          PEP_decrypt_flag_src_modified
 //              indicates that the modified_src field should contain a modified
 //              version of the source, at the moment always as a result of the
 //              input flags. 
 //          PEP_decrypt_flag_consume
 //              used by sync 
 //          PEP_decrypt_flag_ignore
 //              used by sync 
 // 
 //  caveat:
 //      the decrypted, encoded mime text will go to the ownership of the caller; mimetext
 //      will remain in the ownership of the caller
 /**
 *  <!--       MIME_decrypt_message()       -->
 *  
 *  @brief Decrypt a MIME message, with MIME output
 *  
 *  @param[in]     session           session handle
 *  @param[in]     mimetext          MIME encoded text to decrypt
 *  @param[in]     size              size of mime text to decode (in order to decrypt)
 *  @param[out]    mime_plaintext    decrypted, encoded message
 *  @param[in,out] keylist           in: stringlist with additional keyids for reencryption if needed
 *                                   (will be freed and replaced with output keylist)
 *                                   out: stringlist with keyids
 *  @param[out]    rating            rating for the message
 *  @param[in,out] flags             flags to signal special decryption features (see below)
 *  @param[out]    modified_src      modified source string, if decrypt had reason to change it
 *  
 *  @retval decrypt status                  if everything worked with MIME encode/decode, 
 *                                          the status of the decryption is returned 
 *                                          (PEP_STATUS_OK or decryption error status)
 *  @retval PEP_BUFFER_TOO_SMALL            if encoded message size is too big to handle
 *  @retval PEP_CANNOT_CREATE_TEMP_FILE     if there are issues with temp files; in
 *                                          this case errno will contain the underlying
 *                                          error
 *  @retval PEP_OUT_OF_MEMORY               if not enough memory could be allocated
 *  
 *  @note Flags above are as follows:
 *  @verbatim
 *  ---------------------------------------------------------------------------------------------|
 *  Incoming flags                                                                               |
 *  ---------------------------------------------------------------------------------------------|
 *  Flag                                  | Description                                          |                     
 *  --------------------------------------|------------------------------------------------------|
 *  PEP_decrypt_flag_untrusted_server     | used to signal that decrypt function should engage   |
 *                                        | in behaviour specified for when the server storing   |
 *                                        | the source is untrusted.                             |
 *  ---------------------------------------------------------------------------------------------|
 *  Outgoing flags                                                                               |
 *  ---------------------------------------------------------------------------------------------|
 *  PEP_decrypt_flag_own_private_key      | private key was imported for one of our addresses    |
 *                                        | (NOT trusted or set to be used - handshake/trust is  |
 *                                        | required for that)                                   |
 *                                        |                                                      |
 *  PEP_decrypt_flag_src_modified         | indicates that the modified_src field should contain | 
 *                                        | a modified version of the source, at the moment      | 
 *                                        | always as a result of the input flags.               |
 *                                        |                                                      |
 *  PEP_decrypt_flag_consume              | used by sync to indicate this was a pEp internal     |
 *                                        | message and should be consumed externally without    |
 *                                        | showing it as a normal message to the user           |
 *                                        |                                                      |
 *  PEP_decrypt_flag_ignore               | used by sync                                         |
 *  ---------------------------------------------------------------------------------------------| @endverbatim
 * 
 *  @ownership 
 *  - the decrypted, encoded mime text will go to the ownership of the caller
 *  - the original mimetext will remain in the ownership of the caller
 *  
 */
 DYNAMIC_API PEP_STATUS MIME_decrypt_message(
    PEP_SESSION session,
    const char *mimetext,
--- a/src/base64.h
+++ b/src/base64.h
@ -1,8 +1,8 @@
 /** @file */
 /** @brief File description for doxygen missing. FIXME */

 // This file is under GNU General Public License 3.0
 // see LICENSE.txt
 /**
 * @file    base64.h
 * @brief   Convert base64 to a binary blob
 * @license GNU General Public License 3.0 - see LICENSE.txt
 */

 #pragma once

--- a/src/baseprotocol.h
+++ b/src/baseprotocol.h
@ -1,8 +1,8 @@
 /** @file */
 /** @brief File description for doxygen missing. FIXME */

 // This file is under GNU General Public License 3.0
 // see LICENSE.txt
 /**
 * @file     baseprotocol.h
 * @brief    base protocol (FIXME: derived from filename)
 * @license  GNU General Public License 3.0 - see LICENSE.txt
 */

 #pragma once

@ -21,22 +21,26 @@ typedef enum _base_protocol_type {
 } base_protocol_type;


 // base_decorate_message() - decorate a message with payload
 //
 //  parameters:
 //      session (in)    session handle
 //      msg (inout)     message to decorate
 //      type (in)       base protocol type
 //      payload (in)    payload to send
 //      size (in)       size of payload
 //      fpr (in)        optional key to sign or NULL
 //
 //  returns:
 //      PEP_STATUS_OK and result on success or an error on failure
 //
 //  caveat:
 //      on success (and only then) payload goes to the ownership of the msg
 //      the ownership of the msg remains with the caller
 /**
 *  <!--       base_decorate_message()       -->
 *  
 *  @brief Decorate a message with payload
 *  
 *  @param[in]     session    session handle
 *  @param[in,out] msg        message to decorate (contains return result on success)
 *  @param[in]     type       base protocol type
 *  @param[in]     payload    payload to send
 *  @param[in]     size       size of payload
 *  @param[in]     fpr        optional key to sign or NULL
 *  
 *  @retval PEP_STATUS_OK     on success 
 *  @retval error_status      on failure
 *  
 *  @ownership 
 *  - On success (and only then), ownership of the payload is assigned to the msg structure
 *  - Ownership of the msg remains with the caller
 *  
 */

 PEP_STATUS base_decorate_message(
        PEP_SESSION session,
@ -48,24 +52,28 @@ PEP_STATUS base_decorate_message(
    );


 // base_prepare_message() - prepare a sync message with payload
 //
 //  parameters:
 //      session (in)    session handle
 //      me (in)         identity to use for the sender
 //      partner (in)    identity to use for the receiver
 //      type (in)       base protocol type
 //      payload (in)    payload to send
 //      size (in)       size of payload
 //      fpr (in)        optional key to sign or NULL
 //      result (out)    message with payload
 //
 //  returns:
 //      PEP_STATUS_OK and result on success or an error on failure
 //
 //  caveat:
 //      on success (and only then) payload goes to the ownership of the result
 //      the ownership of the result goes to the caller
 /**
 *  <!--       base_prepare_message()       -->
 *  
 *  @brief Prepare a sync message with payload
 *  
 *  @param[in]     session    session handle
 *  @param[in]     me         identity to use for the sender
 *  @param[in]     partner    identity to use for the receiver
 *  @param[in]     type       base protocol type
 *  @param[in]     payload    payload to send
 *  @param[in]     size       size of payload
 *  @param[in]     fpr        optional key to sign or NULL
 *  @param[out]    result     returned message with payload on success
 *  
 *  @retval PEP_STATUS_OK       on success
 *  @retval error_status        on failure
 *  
 *  @ownership 
 *  - On (and only on) success, ownership of payload is assigned to the result structure
 *  - Ownership of the result goes to the caller
 *  
 */

 PEP_STATUS base_prepare_message(
        PEP_SESSION session,
@ -79,25 +87,30 @@ PEP_STATUS base_prepare_message(
    );


 // base_extract_message() - extract a sync message from a pEp message
 //
 //  parameters:
 //      session (in)    session handle
 //      msg (in)        message to analyze
 //      type (in)       base protocol type to extract
 //      size (out)      size of extracted payload or 0 if not found
 //      payload (out)   extraced payload
 //      fpr (out)       if message was correctly signed then fpr of signature's
 //                      key, otherwise NULL
 //
 //  returns:
 //      PEP_STATUS_OK and payload == NULL if no sync message
 //      PEP_STATUS_OK and payload, size if sync message found
 //      any other value on error
 //
 //  caveat:
 //      payload may point to msg attachment, the ownership does not change
 //      if fpr != NULL the ownership goes to the caller
 /**
 *  <!--       base_extract_message()       -->
 *  
 *  @brief Extract a sync message from a pEp message
 *  
 *  @param[in]     session    session handle
 *  @param[in]     msg        message to analyze
 *  @param[in]     type       base protocol type to extract
 *  @param[out]    size       size of extracted payload, or 0 if not found
 *  @param[out]    payload    extracted payload, if sync message is found. 
 *                            otherwise, NULL
 *  @param[out]    fpr        if message was correctly signed then fpr of signature's
 *                            key, otherwise NULL
 *  
 *  @retval PEP_STATUS_OK     if no error occurred, whether or not sync message was found
 *  @retval error_status      any other value on error
 *  
 *  @ownership
 *  - Payload may point to msg attachment, but the ownership does not change
 *  - If fpr != NULL the ownership goes to the caller
 * 
 *  @todo Volker, expand this definition from sync message. What do we call these? Administrative messages? - K
 *  
 */

 PEP_STATUS base_extract_message(
        PEP_SESSION session,
@ -109,10 +122,31 @@ PEP_STATUS base_extract_message(
    );


 // this is the internal function to be used by asynchronous network protocol
 // implementations
 //
 // this function is calling messageToSend(NULL) in case there is a missing or wrong passphrase
 /**
 *  <!--       try_base_prepare_message()       -->
 *  
 *  @brief Prepare a sync message with payload. This is the internal function to be used by 
 *         asynchronous network protocol implementations. This function differs from 
 *         base_prepare_message in that it calls messageToSend(NULL) in case there is a missing 
 *         or wrong passphrase, but more explanation is required here.
 *  
 *  @param[in]     session    session handle
 *  @param[in]     me         identity to use for the sender
 *  @param[in]     partner    identity to use for the receiver
 *  @param[in]     type       base protocol type
 *  @param[in]     payload    payload to send
 *  @param[in]     size       size of payload
 *  @param[in]     fpr        optional key to sign or NULL
 *  @param[out]    result     returned message with payload on success
 *  
 *  @ownership 
 *  - On (and only on) success, ownership of payload is assigned to the result structure
 *  - Ownership of the result goes to the caller
 * 
 *  @todo Volker, I need a better explanation of the use case here to document correctly - K
 * 
 *  @see base_prepare_message()
 */

 PEP_STATUS try_base_prepare_message(
        PEP_SESSION session,
--- a/src/blacklist.h
+++ b/src/blacklist.h
@ -1,8 +1,8 @@
 /** @file */
 /** @brief File description for doxygen missing. FIXME */

 // This file is under GNU General Public License 3.0
 // see LICENSE.txt
 /**
 * @file    blacklist.h
 * @brief   blacklist (FIXME: derived from filename)
 * @license GNU General Public License 3.0 - see LICENSE.txt
 */

 #pragma once

@ -12,37 +12,50 @@
 extern "C" {
 #endif

 // blacklist_add() - add to blacklist
 //
 //  parameters:
 //      session (in)        session to use
 //      fpr (in)            fingerprint of key to blacklist
 //
 //  caveat:
 //      there is no point in blacklisting an own key; for any own
 //      identity, this will be ignored. The correct function to use
 //      for own keys in this event is "key_reset_trust".
 //      Also, this is only effective for OpenPGP-level trust. If
 //      this key is for a pEp user, the blacklist is ignored.
 /**
 *  <!--       blacklist_add()       -->
 *  
 *  @brief Add to blacklist
 *  
 *  @param[in]     session    session to use
 *  @param[in]     fpr        fingerprint of key to blacklist
 *  
 *  @warning there is no point in blacklisting an own key; for any own
 *           identity, this will be ignored. The correct function to use
 *           for own keys in this event is "key_reset_trust".
 *           Also, this is only effective for OpenPGP-level trust. If
 *           this key is for a pEp user, the blacklist is ignored.
 *  
 */

 DYNAMIC_API PEP_STATUS blacklist_add(PEP_SESSION session, const char *fpr);


 // blacklist_delete() - delete from blacklist
 //
 //  parameters:
 //      session (in)        session to use
 //      fpr (in)            fingerprint of key to be removed from blacklist
 /**
 *  <!--       blacklist_delete()       -->
 *  
 *  @brief Delete from blacklist
 *  
 *  @param[in]     session    session to use
 *  @param[in]     fpr        fingerprint of key to be removed from blacklist
 *  
 *  
 */

 DYNAMIC_API PEP_STATUS blacklist_delete(PEP_SESSION session, const char *fpr);


 // blacklist_is_listed() - is_listed in blacklist
 //
 //  parameters:
 //      session (in)        session to use
 //      fpr (in)            fingerprint of key to blacklist
 //      bool (out)          flags if key is blacklisted
 /**
 *  <!--       blacklist_is_listed()       -->
 *  
 *  @brief Is listed in blacklist
 *  
 *  @param[in]     session    session to use
 *  @param[in]     fpr        fingerprint of key to blacklist
 *  @param[out]    bool       flags if key is blacklisted
 *  
 *  
 */

 DYNAMIC_API PEP_STATUS blacklist_is_listed(
        PEP_SESSION session,
@ -51,14 +64,17 @@ DYNAMIC_API PEP_STATUS blacklist_is_listed(
    );


 // blacklist_retrieve() - retrieve full blacklist of key fingerprints
 //
 //  parameters:
 //      session (in)        session to use
 //      blacklist (out)     copy of blacklist
 //
 //  caveat:
 //      the ownership of the copy of blacklist goes to the caller
 /**
 *  <!--       blacklist_retrieve()       -->
 *  
 *  @brief Retrieve full blacklist of key fingerprints
 *  
 *  @param[in]     session      session to use
 *  @param[out]    blacklist    copy of blacklist
 *  
 *  @ownership the ownership of the copy of blacklist goes to the caller
 *  
 */

 DYNAMIC_API PEP_STATUS blacklist_retrieve(
        PEP_SESSION session,
--- a/src/bloblist.h
+++ b/src/bloblist.h
@ -1,8 +1,9 @@
 /** @file */
 /** @brief File description for doxygen missing. FIXME */

 // This file is under GNU General Public License 3.0
 // see LICENSE.txt
 /**
 * @file    bloblist.h
 * @brief   functions for list structure to hold data of unspecified format (hence,
 *          "blob list"); can contain addition format information in structure's mime info
 * @license GNU General Public License 3.0 - see LICENSE.txt
 */

 #pragma once

@ -37,94 +38,118 @@ typedef struct _bloblist_t {
 } bloblist_t;


 // new_bloblist() - allocate a new bloblist
 //
 //  parameters:
 //      blob (in)       blob to add to the list
 //      size (in)       size of the blob
 //      mime_type (in)  MIME type of the blob data or NULL if unknown
 //      filename (in)  file name of origin of blob data or NULL if unknown
 //
 //  return value:
 //      pointer to new bloblist_t or NULL if out of memory
 //
 //  caveat:
 //      the ownership of the blob goes to the bloblist; mime_type and filename
 //      are being copied, the originals remain in the ownership of the caller
 //
 //      if blob is on a different heap then after the call release_value has to
 //      be set by the adapter; this is relevant on operating systems with
 //      multiple heaps like Microsoft Windows
 /**
 *  <!--       new_bloblist()       -->
 *  
 *  @brief Allocate a new bloblist
 *  
 *  @param[in]     blob         blob to add to the list
 *  @param[in]     size         size of the blob
 *  @param[in]     mime_type    MIME type of the blob data or NULL if unknown
 *  @param[in]     filename     file name of origin of blob data or NULL if unknown
 *  
 *  @retval pointer to new bloblist_t or NULL if out of memory
 *  
 *  @ownership 
 *  -  the ownership of the blob goes to the bloblist struct
 *  -  mime_type and filename are copied (copies belong to bloblist struct, 
 *     the originals remain in the ownership of the caller)
 * 
 * @warning  if blob is on a different heap, then after the call, release_value has to
 *           be set by the adapter; this is relevant on operating systems with
 *           multiple heaps like Microsoft Windows
 *  
 */

 DYNAMIC_API bloblist_t *new_bloblist(char *blob, size_t size, const char *mime_type,
        const char *filename);


 // free_bloblist() - free bloblist
 //
 //  parameters:
 //      bloblist (in)   bloblist to free
 /**
 *  <!--       free_bloblist()       -->
 *  
 *  @brief Free bloblist
 *  
 *  @param[in]     bloblist    bloblist to free
 *  
 *  
 */

 DYNAMIC_API void free_bloblist(bloblist_t *bloblist);


 // bloblist_dup() - duplicate bloblist
 //
 //  parameters:
 //      src (in)    bloblist to duplicate
 //
 //  return value:
 //      pointer to a new bloblist_t or NULL if out of memory
 //
 //  caveat:
 //      this is an expensive operation because all blobs are copied
 /**
 *  <!--       bloblist_dup()       -->
 *  
 *  @brief Duplicate bloblist
 *  
 *  @param[in]     src    bloblist to duplicate
 *  
 *  @retval pointer to a new bloblist_t or NULL if out of memory
 *  
 *  @warning this is an expensive operation because all blobs are copied
 *  
 */

 DYNAMIC_API bloblist_t *bloblist_dup(const bloblist_t *src);


 // bloblist_add() - add reference to a blob to bloblist
 //
 //  parameters:
 //      bloblist (in)   bloblist to add to
 //      blob (in)       blob
 //      size (in)       size of the blob
 //      mime_type (in)  MIME type of the blob or NULL if unknown
 //      filename (in)  file name of the blob or NULL if unknown
 //
 //  return value:
 //      pointer to the last element of bloblist or NULL if out of memory or
 //      NULL passed in as blob value
 //
 //  caveat:
 //      the ownership of the blob goes to the bloblist; mime_type and filename
 //      are being copied, the originals remain in the ownership of the caller.
 //      bloblist input parameter equal to NULL or with value == NULL is a valid
 //      empty input list.
 //
 //      If there is release_value set in bloblist it is copied to the added
 //      leaf
 /**
 *  <!--       bloblist_add()       -->
 *  
 *  @brief Add reference to a blob to bloblist
 *  
 *  @param[in]     bloblist     bloblist to add to
 *  @param[in]     blob         blob
 *  @param[in]     size         size of the blob
 *  @param[in]     mime_type    MIME type of the blob or NULL if unknown
 *  @param[in]     filename     file name of the blob or NULL if unknown
 *  
 *  @retval pointer to the last element of bloblist or NULL if out of memory or
 *  @retval NULL passed in as blob value
 *  
 *  @ownership 
 *  - the ownership of the blob goes to the bloblist struct 
 *  - mime_type and filename are copied and belong to the bloblist struct, the originals remain in the ownership of the caller.
 *           
 *  @note Bloblist input parameter equal to NULL or with value == NULL is a valid
 *        empty input list.
 * 
 *  @note If there is release_value set in bloblist it is copied to the added
 *        leaf
 *  
 */

 DYNAMIC_API bloblist_t *bloblist_add(bloblist_t *bloblist, char *blob, size_t size,
        const char *mime_type, const char *filename);


 // bloblist_length() - get length of bloblist
 //
 //  parameters:
 //      bloblist (in)   bloblist struct to determine length of
 //
 //  return value:
 //      length of bloblist in number of elements
 /**
 *  <!--       bloblist_length()       -->
 *  
 *  @brief Get length of bloblist
 *  
 *  @param[in]     bloblist    bloblist struct to determine length of
 *  
 *  @retval length of bloblist in number of elements
 *  
 *  
 */

 DYNAMIC_API int bloblist_length(const bloblist_t *bloblist);


 // set_blob_content_disposition() - set blob content disposition and parameters
 //                                  when necessary
 //
 //  parameters:
 //      blob (in)               bloblist struct to change disposition for
 //      disposition (in)        disposition type (see enum)
 /**
 *  <!--       set_blob_content_disposition()       -->
 *  
 *  @brief Set blob content disposition and parameters
 *         when necessary
 *  
 *  @param[in]     blob           bloblist struct to change disposition for
 *  @param[in]     disposition    disposition type (see enum)
 *  
 *  
 */

 DYNAMIC_API void set_blob_disposition(bloblist_t* blob, 
        content_disposition_type disposition);
--- a/src/cryptotech.h
+++ b/src/cryptotech.h
@ -1,8 +1,9 @@
 /** @file */
 /** @brief File description for doxygen missing. FIXME */

 // This file is under GNU General Public License 3.0
 // see LICENSE.txt
 /**
 * @file    cryptotech.h
 * @brief   cryptotech function typedefs and structures for crypto drivers 
 *          to implement and interface with engine
 * @license GNU General Public License 3.0 - see LICENSE.txt
 */

 #pragma once

@ -19,6 +20,11 @@ typedef enum _PEP_cryptotech {
    PEP_crypt__count
 } PEP_cryptotech;

 /**
 *  @copydoc decrypt_and_verify()
 *  Signature for crypto drivers to implement for decrypt_and_verify()
 *  @see decrypt_and_verify()
 */
 typedef PEP_STATUS (*decrypt_and_verify_t)(
        PEP_SESSION session, const char *ctext, size_t csize,
        const char *dsigtext, size_t dsigsize,
@ -26,82 +32,188 @@ typedef PEP_STATUS (*decrypt_and_verify_t)(
        char **filename_ptr 
    );

 /**
 *  @copydoc verify_text()
 *  Signature for crypto drivers to implement for verify_text()
 *  @see verify_text()
 */
 typedef PEP_STATUS (*verify_text_t)(
        PEP_SESSION session, const char *text, size_t size,
        const char *signature, size_t sig_size, stringlist_t **keylist
    );

 /**
 *  @copydoc encrypt_and_sign()
 *  Signature for crypto drivers to implement for encrypt_and_sign()
 *  @see encrypt_and_sign()
 */
 typedef PEP_STATUS (*encrypt_and_sign_t)(
        PEP_SESSION session, const stringlist_t *keylist, const char *ptext,
        size_t psize, char **ctext, size_t *csize
    );

 /**
 *  @copydoc encrypt_only()
 *  Signature for crypto drivers to implement for encrypt_only()
 *  @see encrypt_only()
 */
 typedef PEP_STATUS (*encrypt_only_t)(
        PEP_SESSION session, const stringlist_t *keylist, const char *ptext,
        size_t psize, char **ctext, size_t *csize
    );

 /**
 *  @copydoc sign_only()
 *  Signature for crypto drivers to implement for sign_only()
 *  @see sign_only
 */
 typedef PEP_STATUS (*sign_only_t)(
        PEP_SESSION session, const char* fpr, const char *ptext,
        size_t psize, char **stext, size_t *ssize
    );

 /**
 *  @copydoc delete_keypair()
 *  Signature for crypto drivers to implement for delete_keypair()
 *  @see delete_keypair()
 */
 typedef PEP_STATUS (*delete_keypair_t)(PEP_SESSION session, const char *fpr);

 /**
 *  @copydoc export_key()
 *  Signature for crypto drivers to implement for export_key()
 *  @see export_key()
 */
 typedef PEP_STATUS (*export_key_t)(
        PEP_SESSION session, const char *fpr, char **key_data, size_t *size,
        bool secret
    );

 /**
 *  @copydoc find_keys()
 *  Signature for crypto drivers to implement for find_keys()
 *  @see find_keys()
 */
 typedef PEP_STATUS (*find_keys_t)(
        PEP_SESSION session, const char *pattern, stringlist_t **keylist
    );

 /**
 *  @copydoc generate_keypair()
 *  Signature for crypto drivers to implement for generate_keypair()
 *  @see generate_keypair()
 */
 typedef PEP_STATUS (*generate_keypair_t)(
        PEP_SESSION session, pEp_identity *identity
    );

 /**
 *  @copydoc get_key_rating()
 *  Signature for crypto drivers to implement for get_key_rating()
 *  @see get_key_rating()
 */
 typedef PEP_STATUS (*get_key_rating_t)(
        PEP_SESSION session,
        const char *fpr,
        PEP_comm_type *comm_type
    );

 /**
 *  @copydoc import_key()
 *  Signature for crypto drivers to implement for import_key()
 *  @see import_key()
 */
 typedef PEP_STATUS (*import_key_t)(PEP_SESSION session, const char *key_data,
        size_t size, identity_list **private_keys, stringlist_t** imported_keys,
        uint64_t* changed_key_index);

 /**
 *  @copydoc recv_key()
 *  Signature for crypto drivers to implement for recv_key()
 *  @see recv_key()
 */
 typedef PEP_STATUS (*recv_key_t)(PEP_SESSION session, const char *pattern);

 /**
 *  @copydoc send_key()
 *  Signature for crypto drivers to implement for send_key()
 *  @see send_key()
 */
 typedef PEP_STATUS (*send_key_t)(PEP_SESSION session, const char *pattern);

 /**
 *  @copydoc renew_key()
 *  Signature for crypto drivers to implement for renew_key()
 *  @see renew_key()
 */
 typedef PEP_STATUS (*renew_key_t)(PEP_SESSION session, const char *fpr,
        const timestamp *ts);

 /**
 *  @copydoc revoke_key()
 *  Signature for crypto drivers to implement for revoke_key()
 *  @see revoke_key()
 */
 typedef PEP_STATUS (*revoke_key_t)(PEP_SESSION session, const char *fpr,
        const char *reason);

 /**
 *  @copydoc key_expired()
 *  Signature for crypto drivers to implement for key_expired()
 *  @see key_expired()
 */
 typedef PEP_STATUS (*key_expired_t)(PEP_SESSION session, const char *fpr,
        const time_t when, bool *expired);

 /**
 *  @copydoc key_revoked()
 *  Signature for crypto drivers to implement for key_revoked()
 *  @see key_revoked()
 */
 typedef PEP_STATUS (*key_revoked_t)(PEP_SESSION session, const char *fpr,
        bool *revoked);

 /**
 *  @copydoc key_created()
 *  Signature for crypto drivers to implement for key_created()
 *  @see key_created()
 */
 typedef PEP_STATUS (*key_created_t)(PEP_SESSION session, const char *fpr,
        time_t *created);

 /**
 *  @copydoc binary_path()
 *  Signature for crypto drivers to implement for binary_path()
 *  @see binary_path()
 */
 typedef PEP_STATUS (*binary_path_t)(const char **path);

 /**
 *  @copydoc contains_priv_key()
 *  Signature for crypto drivers to implement for contains_priv_key()
 *  @see contains_priv_key()
 */
 typedef PEP_STATUS (*contains_priv_key_t)(PEP_SESSION session, const char *fpr,
        bool *has_private);

 /**
 *  @copydoc find_private_keys()
 *  Signature for crypto drivers to implement for find_private_keys()
 *  @see find_private_keys()
 */
 typedef PEP_STATUS (*find_private_keys_t)(
    PEP_SESSION session, const char *pattern, stringlist_t **keylist
 );

 /**
 *  @copydoc config_cipher_suite()
 *  Signature for crypto drivers to implement for config_cipher_suite()
 *  @see config_cipher_suite()
 */
 typedef PEP_STATUS (*config_cipher_suite_t)(PEP_SESSION session,
        PEP_CIPHER_SUITE suite);


 typedef struct _PEP_cryptotech_t {
    uint8_t id;
    // the following are default values; comm_type may vary with key length or b0rken crypto
--- a/src/dynamic_api.h
+++ b/src/dynamic_api.h
@ -1,8 +1,8 @@
 /** @file */
 /** @brief File description for doxygen missing. FIXME */

 // This file is under GNU General Public License 3.0
 // see LICENSE.txt
 /**
 * @file    dynamic_api.h
 * @brief   dynamic api (FIXME: derived from filename)
 * @license GNU General Public License 3.0 - see LICENSE.txt
 */

 #pragma once

--- a/src/email.h
+++ b/src/email.h
@ -1,8 +1,8 @@
 /** @file */
 /** @brief File description for doxygen missing. FIXME */

 // This file is under GNU General Public License 3.0
 // see LICENSE.txt
 /**
 * @file    email.h
 * @brief   email (FIXME: derived from filename)
 * @license GNU General Public License 3.0 - see LICENSE.txt
 */

 #pragma once

--- a/src/etpan_mime.h
+++ b/src/etpan_mime.h
@ -1,8 +1,8 @@
 /** @file */
 /** @brief File description for doxygen missing. FIXME */

 // This file is under GNU General Public License 3.0
 // see LICENSE.txt
 /**
 * @file    etpan_mime.h
 * @brief   Driver for the libetpan MIME implementation (@see mime.h for the general API)
 * @license GNU General Public License 3.0 - see LICENSE.txt
 */

 #pragma once

--- a/src/fsm_common.h
+++ b/src/fsm_common.h
@ -1,15 +1,10 @@
 /** @file */
 /** @brief File description for doxygen missing. FIXME */

 // This file is under GNU General Public License 3.0
 // see LICENSE.txt

 // generate state machine code

 // Copyleft (c) 2017-2018, pEp foundation

 // Written by Volker Birk

 /**
 * @file     src/fsm_common.h
 * @brief    Generate state machine code
 * @license  GNU General Public License 3.0 - see LICENSE.txt
 * @copyleft (c) 2017-2018, pEp foundation 
 * @author   Volker Birk
 */

 #pragma once

--- a/src/growing_buf.h
+++ b/src/growing_buf.h
@ -1,8 +1,9 @@
 /** @file */
 /** @brief File description for doxygen missing. FIXME */

 // This file is under GNU General Public License 3.0
 // see LICENSE.txt
 /**
 * @file    growing_buf.h
 * @brief   growing buffer, which is needed by the ASN.1 implementation
 *          i.e. for encoding to XER
 * @license GNU General Public License 3.0 - see LICENSE.txt
 */

 #pragma once

@ -24,31 +25,45 @@ typedef struct growing_buf {
 } growing_buf_t;


 // new_growing_buf() - allocate a new growing buffer
 //
 //  return value:
 //      new buffer or NULL if out of memory
 /**
 *  <!--       new_growing_buf()       -->
 *  
 *  @brief Allocate a new growing buffer
 *  
 *  @retval new buffer or NULL if out of memory
 *  
 *  
 */

 growing_buf_t *new_growing_buf(void);


 // free_growing_buf() - free growing buffer
 //
 //  parameters:
 //      buf (in)            buffer to free
 /**
 *  <!--       free_growing_buf()       -->
 *  
 *  @brief Free growing buffer
 *  
 *  @param[in]     buf    buffer to free
 *  
 *  
 */

 void free_growing_buf(growing_buf_t *buf);


 // growing_buf_consume() - append new data to growing buffer
 //
 //  parameters:
 //      src (in)            new data
 //      size (in)           size of new data
 //      dst (in)            growing buffer where new data will be appended
 //
 //  return value:
 //      1 on succes, -1 on failure
 /**
 *  <!--       growing_buf_consume()       -->
 *  
 *  @brief Append new data to growing buffer
 *  
 *  @param[in]     src     new data
 *  @param[in]     size    size of new data
 *  @param[in]     dst     growing buffer where new data will be appended
 *  
 *  @retval 1 on succes, -1 on failure
 *  
 *  
 */

 int growing_buf_consume(const void *src, size_t size, growing_buf_t *dst);

--- a/src/identity_list.h
+++ b/src/identity_list.h
@ -1,8 +1,8 @@
 /** @file */
 /** @brief File description for doxygen missing. FIXME */

 // This file is under GNU General Public License 3.0
 // see LICENSE.txt
 /**
 * @file    identity_list.h
 * @brief   identity list functions and data structures (@see pEpIdentity)
 * @license GNU General Public License 3.0 - see LICENSE.txt
 */

 #pragma once

@ -13,77 +13,95 @@ extern "C" {
 #endif


 // new_identity_list() - allocate a new identity list
 //
 //  parameters:
 //      ident (in)          identity to move for first element
 //
 //  return value:
 //      new identity_list or NULL if out of memory
 //
 //  caveat:
 //      ident is being moved if the function succeeds, the caller loses
 //      ownership
 /**
 *  <!--       new_identity_list()       -->
 *  
 *  @brief Allocate a new identity list
 *  
 *  @param[in]     ident    identity to move for first element
 *  
 *  @retval        new identity_list or NULL if out of memory
 *  
 *  @warning       ident is being moved if the function succeeds, the caller loses
 *                 ownership
 *  
 */

 DYNAMIC_API identity_list *new_identity_list(pEp_identity *ident);


 // identity_list_dup() - duplicate identity_list (deep copy)
 //
 //  parameters:
 //      id_list (in)        identity_list to copy
 //
 //  return value:
 //      new identity_list or NULL if out of memory
 /**
 *  <!--       identity_list_dup()       -->
 *  
 *  @brief Duplicate identity_list (deep copy)
 *  
 *  @param[in]     id_list    identity_list to copy
 *  
 *  @retval        new identity_list or NULL if out of memory
 *  
 *  
 */

 DYNAMIC_API identity_list *identity_list_dup(const identity_list *src);


 // free_identity_list() - free memory allocated by identity_list
 //
 //  parameters:
 //      id_list (in)        identity_list to free
 //
 //  caveat:
 //      this function frees all identities in the list additional to the
 //      identity_list itself
 /**
 *  <!--       free_identity_list()       -->
 *  
 *  @brief Free memory allocated by identity_list
 *  
 *  @param[in]     id_list    identity_list to free
 *  
 *  @warning this function frees all identities in the list additional to the
 *           identity_list itself
 *  
 */

 DYNAMIC_API void free_identity_list(identity_list *id_list);


 // identity_list_add - add identity to an identity_list
 //
 //  parameters:
 //      id_list (in)        identity_list to add to
 //      ident (in)          identity being added
 //
 //  return value:
 //      pointer to the last element in identity_list or NULL if out of memory
 //
 //  caveat:
 //      ident is being moved, the caller loses ownership if the function is
 //      successful
 /**
 *  <!--       identity_list_add()       -->
 *  
 *  @brief Add identity to an identity_list
 *  
 *  @param[in]     id_list    identity_list to add to
 *  @param[in]     ident      identity being added
 *  
 *  @retval pointer to the last element in identity_list or NULL if out of memory
 *  
 *  @warning ident is being moved, the caller loses ownership if the function is
 *           successful
 *  
 */

 DYNAMIC_API identity_list *identity_list_add(identity_list *id_list, pEp_identity *ident);

 // identity_list_add - join second identity_list to the first.
 //
 //  parameters:
 //      first_list (in)             identity_list to add to
 //      second_list (in)            identity list to add
 //
 //  return value:
 //      pointer to the HEAD of the new list, or NULL if both lists are empty.
 //
 /**
 *  <!--       identity_list_add()       -->
 *  
 *  @brief Join second identity_list to the first.
 *  
 *  @param[in]     first_list     identity_list to add to
 *  @param[in]     second_list    identity list to add
 *  
 *  @retval pointer to the HEAD of the new list, or NULL if both lists are empty.
 *  
 *  
 */
 DYNAMIC_API identity_list *identity_list_join(identity_list *first_list, identity_list* second_list);

 // identity_list_length() - get length of identity_list
 //
 //  parameters:
 //      id_list (in)        identity_list struct to determine length of
 //
 //  return value:
 //      length of identity_list in number of elements
 /**
 *  <!--       identity_list_length()       -->
 *  
 *  @brief Get length of identity_list
 *  
 *  @param[in]     id_list    identity_list struct to determine length of
 *  
 *  @retval length of identity_list in number of elements
 *  
 *  
 */

 DYNAMIC_API int identity_list_length(const identity_list *id_list);

--- a/src/internal_format.h
+++ b/src/internal_format.h
@ -1,8 +1,8 @@
 /** @file */
 /** @brief File description for doxygen missing. FIXME */

 // This file is under GNU General Public License 3.0
 // see LICENSE.txt
 /**
 * @file    internal_format.h
 * @brief   internal format (FIXME: derived from filename)
 * @license GNU General Public License 3.0 - see LICENSE.txt
 */

 #pragma once

@ -13,28 +13,27 @@
 extern "C" {
 #endif

 // encode_internal() - encode to the internal message format
 //
 //  parameters:
 //      value (in)          blob
 //      size (in)           size of value
 //      mime_type (in)      string of MIME type
 //      code (out)          blob in Internal Message Format
 //      code_size (out)     size of code
 //
 //  caveat:
 //      call this for the data in an attachment
 //
 //      for unsupported MIME types this function is returning NULL for code and
 //      does not fail
 //
 //      for supported MIME types this function is creating the internal message
 //      format by copying the data in value
 //
 //      code goes into the ownership of the caller
 //
 //  see also:
 //      https://dev.pep.foundation/Engine/ElevatedAttachments
 /**
 *  <!--       encode_internal()       -->
 *  
 *  @brief Encode to the internal message format
 *  
 *  @param[in]     value        blob
 *  @param[in]     size         size of value
 *  @param[in]     mime_type    string of MIME type
 *  @param[out]    code         blob in Internal Message Format
 *  @param[out]    code_size    size of code
 *  
 *  @warning call this for the data in an attachment
 *           for unsupported MIME types this function is returning NULL for code and
 *           does not fail
 *           for supported MIME types this function is creating the internal message
 *           format by copying the data in value
 *           code goes into the ownership of the caller
 *           see also:
 *           https://dev.pep.foundation/Engine/ElevatedAttachments
 *  
 */

 DYNAMIC_API PEP_STATUS encode_internal(
        const char *value,
@ -45,21 +44,23 @@ DYNAMIC_API PEP_STATUS encode_internal(
    );


 // decode_internal() - decode from internal message format
 //
 //  parameters:
 //      code (in)           blob in Internal Message Format
 //      code_size (in)      size of code
 //      tech (in)           crypto tech for MIME type, PEP_crypt_none for auto
 //      value (out)         blob or string for longmsg
 //      size (out)          size of value
 //      mime_type (out)     string with MIME type or NULL for longmsg
 //
 //  caveat:
 //      this functions copies data from the code
 //
 //      value goes into the ownership of the caller
 //      mime_type goes into the ownership of the caller
 /**
 *  <!--       decode_internal()       -->
 *  
 *  @brief Decode from internal message format
 *  
 *  @param[in]     code         blob in Internal Message Format
 *  @param[in]     code_size    size of code
 *  @param[in]     tech         crypto tech for MIME type, PEP_crypt_none for auto
 *  @param[out]    value        blob or string for longmsg
 *  @param[out]    size         size of value
 *  @param[out]    mime_type    string with MIME type or NULL for longmsg
 *  
 *  @warning this functions copies data from the code
 *           value goes into the ownership of the caller
 *           mime_type goes into the ownership of the caller
 *  
 */

 DYNAMIC_API PEP_STATUS decode_internal(
        const char *code,
--- a/src/key_reset.h
+++ b/src/key_reset.h
@ -1,8 +1,9 @@
 /** @file */
 /** @brief File description for doxygen missing. FIXME */

 // This file is under GNU General Public License 3.0
 // see LICENSE.txt
 /**
 * @file    key_reset.h
 * @brief   Functions for resetting partner key defaults and trust and mistrusting and revoking own keys, 
 *          as well as functions to inform partners of own revoked keys and their replacements
 * @license GNU General Public License 3.0 - see LICENSE.txt
 */

 #pragma once

@ -17,55 +18,59 @@
 extern "C" {
 #endif

 // key_reset_identity() - reset the default database status for the identity / keypair
 //                        provided. If this corresponds to an own identity and a private key,
 //                        also revoke the key, generate a new one, and communicate the 
 //                        reset to recently contacted pEp partners for this identity.
 //
 //                        If it <