pEp.foundation
/
pEpEngine
16
2
Fork 17
Code Issues 22 Pull Requests 2 Releases 48 Wiki Activity

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

Browse Source
doxygen-key-id
Krista 'DarthMama' Bennett 3 years ago
parent 8ecf18b2b7
commit 46064ffd15
41 changed files with 2082 additions and 1592 deletions
Show Stats Download Patch File Download Diff File

26
engine_doxygen.conf
Unescape View File

@ -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

219
src/aux_mime_msg.h
Unescape View File

@ -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,

10
src/base64.h
Unescape View File

@ -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

158
src/baseprotocol.h
Unescape View File

@ -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,

88
src/blacklist.h
Unescape View File

@ -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,

167
src/bloblist.h
Unescape View File

@ -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);

122
src/cryptotech.h
Unescape View File

@ -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

10
src/dynamic_api.h
Unescape View File

@ -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

10
src/email.h
Unescape View File

@ -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

10
src/etpan_mime.h
Unescape View File

@ -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

19
src/fsm_common.h
Unescape View File

@ -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

59
src/growing_buf.h
Unescape View File

@ -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);

136
src/identity_list.h
Unescape View File

@ -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);

85
src/internal_format.h
Unescape View File

@ -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