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

All extant documentation in all source files but sqlite3.* now follos doxygen syntax.

Browse Source
pull/73/head
Gernot 1 year ago committed by Luca Saiu
parent 9aa1a3c13e
commit 9faf041877
31 changed files with 279 additions and 205 deletions
Show Stats Download Patch File Download Diff File

3
src/Doxyfile
Unescape View File

@ -265,6 +265,8 @@ TAB_SIZE = 4
ALIASES =
ALIASES += license="\par License:^^"
ALIASES += copyleft="\par Copyleft:^^"
ALIASES += ownership="\attention 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
@ -2258,6 +2260,7 @@ INCLUDE_FILE_PATTERNS =
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
PREDEFINED =DYNAMIC_API=
PREDEFINED +=MAYBE_UNUSED=
# 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

8
src/baseprotocol.h
Unescape View File

@ -1,7 +1,9 @@
/**
* @file baseprotocol.h
* @brief Basic functions for administrative pEp messages (preparation,
* decoration, payload, extraction, etc.). These are used for
* decoration, payload, extraction, etc.).
*
* These are used for
* protocol messages in, for example, key sync and key reset.
* The payloads of these messages are, in general, not human-readable.
* @license GNU General Public License 3.0 - see LICENSE.txt
@ -144,7 +146,9 @@ PEP_STATUS base_extract_message(
/**
* <!-- try_base_prepare_message() -->
*
* @brief Prepare an administrative message with payload. This is the internal function to be used by
* @brief Prepare an administrative 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.

27
src/bloblist.h
Unescape View File

@ -26,7 +26,7 @@ extern "C" {
typedef enum {
PEP_CONTENT_DISP_ATTACHMENT = 0,
PEP_CONTENT_DISP_INLINE = 1,
PEP_CONTENT_DISP_OTHER = -1 // must be affirmatively set
PEP_CONTENT_DISP_OTHER = -1 ///< must be affirmatively set
} content_disposition_type;
/**
@ -36,18 +36,18 @@ typedef enum {
*
*/
typedef struct _bloblist_t {
char *value; // blob
size_t size; // size of blob
char *mime_type; // UTF-8 string of MIME type of blob or
// NULL if unknown
char *filename; // UTF-8 string of file name of blob or
// NULL if unknown
char *value; ///< blob
size_t size; ///< size of blob
char *mime_type; ///< UTF-8 string of MIME type of blob or
///< NULL if unknown
char *filename; ///< UTF-8 string of file name of blob or
///< NULL if unknown
content_disposition_type disposition;
// default is attachment when allocated
// (see mime.h and RFC2183)
struct _bloblist_t *next; // this is a single linked list
void (*release_value)(char *); // pointer to release function;
// pEp_free() if not set
///< default is attachment when allocated
///< (see mime.h and RFC2183)
struct _bloblist_t *next; ///< this is a single linked list
void (*release_value)(char *); ///< pointer to release function;
///< pEp_free() if not set
} bloblist_t;
@ -61,7 +61,8 @@ typedef struct _bloblist_t {
* @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
* @retval pointer to new bloblist_t
* @retval NULL if out of memory
*
* @ownership
* - the ownership of the blob goes to the bloblist struct

46
src/cryptotech.h
Unescape View File

@ -28,8 +28,10 @@ typedef enum _PEP_cryptotech {
} PEP_cryptotech;
/**
* @brief Signature for crypto drivers to implement for decrypt_and_verify()
*
* @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)(
@ -40,8 +42,8 @@ typedef PEP_STATUS (*decrypt_and_verify_t)(
);
/**
* @brief Signature for crypto drivers to implement for verify_text()
* @copydoc verify_text()
* Signature for crypto drivers to implement for verify_text()
* @see verify_text()
*/
typedef PEP_STATUS (*verify_text_t)(
@ -50,8 +52,8 @@ typedef PEP_STATUS (*verify_text_t)(
);
/**
* @brief Signature for crypto drivers to implement for encrypt_and_sign()
* @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)(
@ -60,8 +62,8 @@ typedef PEP_STATUS (*encrypt_and_sign_t)(
);
/**
* @brief Signature for crypto drivers to implement for encrypt_only()
* @copydoc encrypt_only()
* Signature for crypto drivers to implement for encrypt_only()
* @see encrypt_only()
*/
typedef PEP_STATUS (*encrypt_only_t)(
@ -70,8 +72,8 @@ typedef PEP_STATUS (*encrypt_only_t)(
);
/**
* @brief Signature for crypto drivers to implement for sign_only()
* @copydoc sign_only()
* Signature for crypto drivers to implement for sign_only()
* @see sign_only
*/
typedef PEP_STATUS (*sign_only_t)(
@ -80,15 +82,15 @@ typedef PEP_STATUS (*sign_only_t)(
);
/**
* @brief Signature for crypto drivers to implement for delete_keypair()
* @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);
/**
* @brief Signature for crypto drivers to implement for export_key()
* @copydoc export_key()
* Signature for crypto drivers to implement for export_key()
* @see export_key()
*/
typedef PEP_STATUS (*export_key_t)(
@ -97,8 +99,8 @@ typedef PEP_STATUS (*export_key_t)(
);
/**
* @brief Signature for crypto drivers to implement for find_keys()
* @copydoc find_keys()
* Signature for crypto drivers to implement for find_keys()
* @see find_keys()
*/
typedef PEP_STATUS (*find_keys_t)(
@ -106,8 +108,8 @@ typedef PEP_STATUS (*find_keys_t)(
);
/**
* @brief Signature for crypto drivers to implement for generate_keypair()
* @copydoc generate_keypair()
* Signature for crypto drivers to implement for generate_keypair()
* @see generate_keypair()
*/
typedef PEP_STATUS (*generate_keypair_t)(
@ -115,8 +117,8 @@ typedef PEP_STATUS (*generate_keypair_t)(
);
/**
* @brief Signature for crypto drivers to implement for get_key_rating()
* @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)(
@ -126,8 +128,8 @@ typedef PEP_STATUS (*get_key_rating_t)(
);
/**
* @brief Signature for crypto drivers to implement for import_key()
* @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,
@ -135,77 +137,77 @@ typedef PEP_STATUS (*import_key_t)(PEP_SESSION session, const char *key_data,
uint64_t* changed_key_index);
/**
* @brief Signature for crypto drivers to implement for recv_key()
* @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);
/**
* @brief Signature for crypto drivers to implement for send_key()
* @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);
/**
* @brief Signature for crypto drivers to implement for renew_key()
* @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);
/**
* @brief Signature for crypto drivers to implement for revoke_key()
* @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);
/**
* @brief Signature for crypto drivers to implement for key_expired()
* @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);
/**
* @brief Signature for crypto drivers to implement for key_revoked()
* @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);
/**
* @brief Signature for crypto drivers to implement for key_created()
* @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);
/**
* @brief Signature for crypto drivers to implement for binary_path()
* @copydoc binary_path()
* Signature for crypto drivers to implement for binary_path()
* @see binary_path()
*/
typedef PEP_STATUS (*binary_path_t)(const char **path);
/**
* @brief Signature for crypto drivers to implement for contains_priv_key()
* @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);
/**
* @brief Signature for crypto drivers to implement for find_private_keys()
* @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)(
@ -213,8 +215,8 @@ typedef PEP_STATUS (*find_private_keys_t)(
);
/**
* @brief Signature for crypto drivers to implement for config_cipher_suite()
* @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,

5
src/engine_sql.c
Unescape View File

@ -1,3 +1,8 @@
/**
* @file engine_sql.c
* @brief functions to prepare SQL statements
*/
#include "pEp_internal.h"
#include "engine_sql.h"

6
src/engine_sql.h
Unescape View File

@ -1,4 +1,8 @@
#pragma once
/**
* @file engine_sql.h
* @brief functions to SQL statements and strings to feed into prepared statements
*/
#include "pEp_internal.h"
@ -15,7 +19,7 @@ PEP_STATUS pEp_finalize_sql_stmts(PEP_SESSION session);
attribute declrations for every variable. */
#define MAYBE_UNUSED __attribute__((__unused__))
/**
/**
* Strings to feed into prepared statements
*/
static const char *sql_log MAYBE_UNUSED =

3
src/fsm_common.h
Unescape View File

@ -20,6 +20,9 @@ extern "C" {
* @enum fsm_error
*
* @brief TODO
*
* error values -2..-7 are corresponding to
* PEP_SYNC_STATEMACHINE_ERROR - value
*
*/
typedef enum _fsm_error {

21
src/group.h
Unescape View File

@ -3,8 +3,10 @@
/**
* @file group.h
* @brief TODO: Description for doxygen
* @brief In-memory objects and functions for representation of groups
*
* @license This file is under GNU General Public License 3.0 - see LICENSE.txt
*
*/
#include "platform.h"
@ -24,16 +26,11 @@ extern "C" {
*************************************************************************************************/
/**
* @typedef pEp_member
* <!-- pEp_member -->
* @brief memory object for holding information about an invited group member
* and whether they have joined the group
* (groups are persistent and are stored in the management database)
*/
/**
* @struct _pEp_member
* @brief Auxiliary struct for typedef pEp_member
* @see pEp_member
*/
typedef struct _pEp_member {
pEp_identity *ident; //!< member identity
bool joined; //!< boolean for whether the member has accepted the invite
@ -141,6 +138,8 @@ DYNAMIC_API void free_memberlist(member_list *list);
DYNAMIC_API member_list *memberlist_add(member_list *list, pEp_member *member);
/**
* <!-- pEp_group -->
*
* @brief memory object for holding all information about a group
* (groups are persistent and are stored in the management database)
*/
@ -155,7 +154,8 @@ typedef struct _pEp_group {
* <!-- new_group() -->
*
* @brief allocate pEp_group struct.
* This function does not create
*
* @warning This function does not create
* a group in the database, it only allocates the object for
* group representation.
*
@ -182,7 +182,8 @@ DYNAMIC_API pEp_group *new_group(
* <!-- free_group() -->
*
* @brief deallocate pEp_group struct and all objects it points to.
* This function does not dissolve groups, only deallocates the memory object
*
* @warning This function does not dissolve groups, only deallocates the memory object
* representing a group.
*
* @param[in] group group object to be freed
@ -302,7 +303,7 @@ DYNAMIC_API PEP_STATUS group_dissolve(
/**
* <!-- group_invite_member() -->
*
* @brief Invite a member to an existant group, marking the member as invited in the database and
* @brief Invite a member to an extant group, marking the member as invited in the database and
* sending out an invitation to said member
*
* @param[in] session associated session object

14
src/group_internal.h
Unescape View File

@ -1,8 +1,10 @@
/// @file group_internal.h
/// @brief Internal functions for representation of groups
/// @license This file is under GNU General Public License 3.0 - see LICENSE.txt
#ifndef GROUP_INTERNAL_H
#define GROUP_INTERNAL_H
// This file is under GNU General Public License 3.0
// see LICENSE.txt
#include "message_api.h"
#include "../asn.1/Distribution.h"
@ -29,7 +31,7 @@ extern "C" {
* a user_id and address
*
* @retval PEP_STATUS_OK on success
* error on failure
* @retval error on failure
*
* @ownership all arguments belong to the callee
*
@ -61,9 +63,9 @@ PEP_STATUS group_add_member(
/**
* @internal
*
* @param session
* @param group_identity
* @param member_identity
* @param[in] session
* @param[in] group_identity
* @param[in] member_identity
* @return
*/
PEP_STATUS leave_group(

15
src/internal_format.h
Unescape View File

@ -31,13 +31,12 @@ extern "C" {
* @retval PEP_OUT_OF_MEMORY out of memory
*
* @warning call this for the data in an attachment
* for unsupported MIME types this function is returning NULL for code and
* @warning 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
* @warning 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
* @attention code goes into the ownership of the caller
* @see https://dev.pep.foundation/Engine/ElevatedAttachments
*
*/
@ -66,9 +65,9 @@ DYNAMIC_API PEP_STATUS encode_internal(
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval PEP_OUT_OF_MEMORY out of memory
*
* @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
* @warning this functions copies data from the code
* @attention value goes into the ownership of the caller
* @attention mime_type goes into the ownership of the caller
*
*/

9
src/key_reset.h
Unescape View File

@ -23,12 +23,15 @@ extern "C" {
* <!-- key_reset_identity() -->
*
* @brief Reset the default database status for the identity / keypair
* provided. If this corresponds to an own identity and a private key,
* 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 does not, remove the key from the keyring; the key's
* status is completely fresh on next contact from the partner.
*
* If no key is provided, reset the identity default.
* Note that reset keys will be removed as defaults for all users and identities.
*
@ -55,7 +58,9 @@ DYNAMIC_API PEP_STATUS key_reset_identity(
* <!-- key_reset_user() -->
*
* @brief Reset the default database status for the user / keypair
* provided. This will effectively perform key_reset_identity()
* provided.
*
* This will effectively perform key_reset_identity()
* each identity associated with the key and user_id, if a key is
* provided, and for each key (and all of their identities) if an fpr
* is not.

7
src/key_reset_internal.h
Unescape View File

@ -23,13 +23,16 @@ extern "C" {
* <!-- key_reset() -->
*
* @brief Reset the database status for a key, removing all trust information
* and default database connections. For own keys, also revoke the key
* and default database connections.
*
* For own keys, also revoke the key
* and communicate the revocation and new key to partners we have sent
* mail to recently from the specific identity (i.e. address/user_id)
* that contacted them. We also in this case set up information so that
* if someone we mail uses the wrong key and wasn't yet contacted,
* we can send them the reset information from the right address.
* For non-own keys, also remove key from the keyring.
*
* For non-own keys, also remove key from the keyring.
*
* Can be called manually or through another protocol.
*

63
src/keymanagement.h
Unescape View File

@ -35,7 +35,7 @@ extern "C" {
* @warning at least identity->address must be a non-empty UTF-8 string as input
* update_identity() never writes flags; use set_identity_flags() for
* writing
* this function NEVER reads the incoming fpr, only writes to it.
* @warning this function NEVER reads the incoming fpr, only writes to it.
* this function will fail if called on an identity which, with its input
* values, *explicitly* indicates it is an own identity (i.e. .me is set
* to true on input, or a user_id is given AND it is a known own user_id).
@ -44,7 +44,7 @@ extern "C" {
* matching default (i.e. it is forced to search by address only).
* if the identity is known to be an own identity (or the caller wishes
* to make it one), call myself() on the identity instead.
* FIXME: is this next point accurate?
* @warning FIXME: is this next point accurate?
* if this function returns PEP_ct_unknown or PEP_ct_key_expired in
* identity->comm_type, the caller must insert the identity into the
* asynchronous management implementation, so retrieve_next_identity()
@ -105,15 +105,15 @@ DYNAMIC_API PEP_STATUS update_identity(
*
* @warning If an fpr was entered and is not a valid key, the reason for failure
* is immediately returned in the status and, possibly, identity->comm_type
* If a default own user_id exists in the database, an alias will
* @warning If a default own user_id exists in the database, an alias will
* be created for the default for the input user_id. The ENGINE'S default
* user_id is always returned in the .user_id field
* myself() NEVER elects keys from the keyring; it will only choose keys
* @warning myself() NEVER elects keys from the keyring; it will only choose keys
* which have been set up explicitly via myself(), or which were imported
* during a first time DB setup from an OpenPGP keyring (compatibility only)
* this function generates a keypair on demand; because it's synchronous
* it can need a decent amount of time to return
* if you need to do this asynchronous, you need to return an identity
* @warning if you need to do this asynchronous, you need to return an identity
* with retrieve_next_identity() where pEp_identity.me is true
*
* @warning If the identity has no .username but the person with the same
@ -137,7 +137,7 @@ DYNAMIC_API PEP_STATUS myself(PEP_SESSION session, pEp_identity * identity);
*
* @warning ident is INPUT ONLY. If you want updated trust on the identity, you'll have
* to call update_identity or myself respectively after this.
* N.B. If you are calling this on a key that is the identity or user default,
* @warning N.B. If you are calling this on a key that is the identity or user default,
* it will be removed as the default key for ANY identity and user for which
* it is the default. Please keep in mind that the undo in undo_last_mistrust
* will only undo the current identity's / it's user's default, not any
@ -169,8 +169,8 @@ DYNAMIC_API PEP_STATUS key_mistrusted(
* @retval any other value on error
*
* @warning the fields user_id, address and fpr must be supplied
* own identities will result in a return of PEP_ILLEGAL_VALUE.
* for non-own users, this will 1) set the trust bit on its comm type in the DB,
* @warning own identities will result in a return of PEP_ILLEGAL_VALUE.
* @warning for non-own users, this will 1) set the trust bit on its comm type in the DB,
* 2) set this key as the identity default if the current identity default
* is not trusted, and 3) set this key as the user default if the current
* user default is not trusted.
@ -235,7 +235,7 @@ DYNAMIC_API PEP_STATUS trust_own_key(
*
* @warning ident is INPUT ONLY. If you want updated trust on the identity, you'll have
* to call update_identity or myself respectively after this.
* N.B. If you are calling this on a key that is the identity or user default,
* @warning N.B. If you are calling this on a key that is the identity or user default,
* it will be removed as the default key for the identity and user (but is still
* available for key election, it is just not the cached default anymore)
*
@ -405,11 +405,11 @@ DYNAMIC_API PEP_STATUS set_comm_partner_key(PEP_SESSION session,
* @retval any other value on error
*
* @warning the key has to be in the key ring already
* me->address, me->user_id and me->username must be set to valid data
* myself() is called by set_own_key() without key generation
* me->flags are ignored
* me->address must not be an alias
* me->fpr will be ignored and replaced by fpr, but
* @warning me->address, me->user_id and me->username must be set to valid data
* @warning myself() is called by set_own_key() without key generation
* @warning me->flags are ignored
* @warning me->address must not be an alias
* @warning me->fpr will be ignored and replaced by fpr, but
* caller MUST surrender ownership of the me->fpr reference, because
* it may be freed and replaced within the myself call. caller owns
* me->fpr memory again upon return.
@ -428,7 +428,9 @@ DYNAMIC_API PEP_STATUS set_own_key(
*
* @brief Mark a key as an own default key, test to be sure the private key is
* present and can be used, and set or unset the sticky bit as indicated by the boolean
* value. The sticky bit is intended to tell the engine to not automatically remove this
* value.
*
* The sticky bit is intended to tell the engine to not automatically remove this
* key as a default through protocols like sync, for example.
*
* @param[in] session session to use
@ -441,15 +443,15 @@ DYNAMIC_API PEP_STATUS set_own_key(
* false otherwise
*
* @warning the key has to be in the key ring already
* me->address, me->user_id and me->username must be set to valid data
* myself() is called by set_own_key() from within this call without key generation
* me->flags are ignored
* me->address must not be an alias
* me->fpr will be ignored and replaced by fpr, but
* caller MUST surrender ownership of the me->fpr reference, because
* @warning me->address, me->user_id and me->username must be set to valid data
* @warning myself() is called by set_own_key() from within this call without key generation
* @warning me->flags are ignored
* @warning me->address must not be an alias
* @warning me->fpr will be ignored and replaced by fpr, but
* @warning caller MUST surrender ownership of the me->fpr reference, because
* it may be freed and replaced within the myself call. caller owns
* me->fpr memory again upon return.
* CAN GENERATE A PASSPHRASE REQUEST
* @warning CAN GENERATE A PASSPHRASE REQUEST
*
*/
DYNAMIC_API PEP_STATUS set_own_imported_key(
@ -459,23 +461,6 @@ DYNAMIC_API PEP_STATUS set_own_imported_key(
bool sticky
);
//
// clean_own_key_defaults()
//
// Remove any broken, unrenewable expired, or revoked
// own keys from identity and user defaults in the database.
//
// parameters:
// session (in) session to use
//
// return value:
// PEP_STATUS_OK if all went well
// PEP_PASSPHRASE_REQUIRED if a key needs to be renewed
// but cached passphrase isn't present
// PEP_WRONG_PASSPHRASE if passphrase required for expired key renewal
// but passphrase is the wrong one
// Otherwise, database and keyring errors as appropriate
//
/**
* <!-- clean_own_key_defaults() -->
*

10
src/keymanagement_internal.h
Unescape View File

@ -138,14 +138,16 @@ PEP_STATUS get_user_default_key(PEP_SESSION session, const char* user_id,
// Only call on retrieval of previously stored identity!
// Also, we presume that if the stored_identity was sent in
// without an fpr, there wasn't one in the trust DB for this
// identity.
/**
* <!-- get_valid_pubkey() -->
*
* @brief TODO
*
* Only call on retrieval of previously stored identity!
*
* Also, we presume that if the stored_identity was sent in
* without an fpr, there wasn't one in the trust DB for this
* identity.
*
* @param[in] session session handle
* @param[in] stored_identity pEp_identity*

4
src/map_asn1.h
Unescape View File

@ -17,7 +17,9 @@ extern "C" {
#endif
/* For compatibility reasons we have PIdentity as a distinct struct from
/**
* @file map_asn1.h
* For compatibility reasons we have PIdentity as a distinct struct from
Identity. The difference is that PIdentity has some optional fields, notably
fpr.

12
src/message.h
Unescape View File

@ -124,9 +124,9 @@ DYNAMIC_API message *new_message(
* @brief Free message struct
*
* @param[in] msg message struct to free
* NOTA BENE:
* raw data (msg->rawmsg_ref) and referenced other messages (msg->refering_msg_ref)
* aren't freed and remain in the ownership of the caller!
*
* @note raw data (msg->rawmsg_ref) and referenced other messages (msg->refering_msg_ref)
* aren't freed and remain in the ownership of the caller!
*
*
*/
@ -142,9 +142,8 @@ DYNAMIC_API void free_message(message *msg);
* @param[in] msg message to duplicate
*
* @retval pointer to duplicate of message pointed by msg or NULL
* NOTA BENE:
* not owned pointees (msg->rawmsg_ref and msg->refering_msg_ref) are shared!
*
* @note not owned pointees (msg->rawmsg_ref and msg->refering_msg_ref) are shared!
*
*/
@ -203,8 +202,7 @@ DYNAMIC_API void free_message_ref_list(message_ref_list *msg_list);
*
* @brief Duplicate message reference list
*
* paramters:
* src (in) message_ref_list to duplicate
* @param[in] src message_ref_list to duplicate
*
* @retval pointer to new message_ref_list or NULL if out of memory
*

69
src/message_api.h
Unescape View File

@ -25,27 +25,26 @@ extern "C" {
*
*/
typedef enum _PEP_encrypt_flags {
// "default" means whatever the default behaviour for the function is.
/// "default" means whatever the default behaviour for the function is.
PEP_encrypt_flag_default = 0x0,
PEP_encrypt_flag_force_encryption = 0x1,
// This flag is for special use cases and should not be used
// by normal pEp clients!
/// This flag is for special use cases and should not be used by normal pEp clients!
PEP_encrypt_flag_force_unsigned = 0x2,
PEP_encrypt_flag_force_no_attached_key = 0x4,
// This is used for outer messages (used to wrap the real message)
// This is only used internally and (eventually) by transport functions
/// This is used for outer messages (used to wrap the real message)
/// This is only used internally and (eventually) by transport functions
PEP_encrypt_flag_inner_message = 0x8,
// This is mainly used by pEp clients to send private keys to
// their own PGP-only device
/// This is mainly used by pEp clients to send private keys to
/// their own PGP-only device
PEP_encrypt_flag_force_version_1 = 0x10,
PEP_encrypt_flag_key_reset_only = 0x20,
// This flag is used to let internal functions know that an encryption
// call is being used as part of a reencryption operation
/// This flag is used to let internal functions know that an encryption
/// call is being used as part of a reencryption operation
PEP_encrypt_reencrypt = 0x40
} PEP_encrypt_flags;
@ -58,10 +57,10 @@ typedef unsigned int PEP_encrypt_flags_t;
*
*/
typedef enum _message_wrap_type {
PEP_message_unwrapped, // 1.0 or anything we don't wrap
PEP_message_default, // typical inner/outer message 2.0
PEP_message_transport, // e.g. for onion layers
PEP_message_key_reset // for wrapped key reset information
PEP_message_unwrapped, ///< 1.0 or anything we don't wrap
PEP_message_default, ///< typical inner/outer message 2.0
PEP_message_transport, ///< e.g. for onion layers
PEP_message_key_reset ///< for wrapped key reset information
} message_wrap_type;
/**
@ -94,10 +93,9 @@ typedef enum _message_wrap_type {
* @warning the ownership of src remains with the caller
* the ownership of dst goes to the caller
*
* enc_format PEP_enc_inline_EA:
* @warning enc_format PEP_enc_inline_EA:
* internal format of the encrypted attachments is changing, see
* https://dev.pep.foundation/Engine/ElevatedAttachments
*
* https://dev.pep.foundation/Engine/ElevatedAttachments\n
* Only use this for transports without support for attachments
* when attached data must be sent inline
*
@ -139,7 +137,7 @@ DYNAMIC_API PEP_STATUS encrypt_message(
* @retval PEP_UNKNOWN_ERROR
* @retval any other value on error
*
* @warning the ownershop of src remains with the caller
* @warning the ownershop of src remains with the caller\n
* the ownership of dst goes to the caller
*
*/
@ -178,9 +176,9 @@ DYNAMIC_API PEP_STATUS encrypt_message_and_add_priv_key(
* @retval PEP_ILLEGAL_VALUE
* @retval PEP_OUT_OF_MEMORY
*
* @warning the ownership of src remains with the caller
* the ownership of target_id remains w/ caller
* the ownership of dst goes to the caller
* @warning the ownership of src remains with the caller\n
* the ownership of target_id remains w/ caller\n
* the ownership of dst goes to the caller\n
* message is NOT encrypted for identities other than the target_id (and then,
* only if the target_id refers to self!)
*
@ -199,7 +197,7 @@ DYNAMIC_API PEP_STATUS encrypt_message_for_self(
/**
* @enum PEP_color
*
* @brief TODO
* @brief Internal encoding of colors for status bar.
*
*/
typedef enum _PEP_color {
@ -298,8 +296,11 @@ typedef unsigned int PEP_decrypt_flags_t;
* might be modified (strings freed and allocated anew or set to NULL,
* etc) intentionally; when this happens, PEP_decrypt_flag_src_modified
* is set.
*
* @ownership dst goes to the caller
*
* @ownership contents of keylist goes to the caller
*
* @note if src is unencrypted this function returns PEP_UNENCRYPTED and sets
* dst to NULL
* @note if src->enc_format is PEP_enc_inline_EA on input then elevated attachments
@ -361,8 +362,8 @@ DYNAMIC_API PEP_STATUS decrypt_message(
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval any other value on error
*
* @warning the ownership of msg remains with the caller
* the ownership of ident goes to the caller
* @warning the ownership of msg remains with the caller\n
* the ownership of ident goes to the caller\n
* msg MUST be encrypted so that this function can check own signature
*
*/
@ -386,8 +387,8 @@ DYNAMIC_API PEP_STATUS own_message_private_key_details(
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal parameter values
*
* @warning msg->from must point to a valid pEp_identity
* msg->dir must be PEP_dir_outgoing
* @warning msg->from must point to a valid pEp_identity\n
* msg->dir must be PEP_dir_outgoing\n
* the ownership of msg remains with the caller
*
*/
@ -412,8 +413,8 @@ DYNAMIC_API PEP_STATUS sent_message_rating(
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal parameter values
*
* @warning msg->from must point to a valid pEp_identity
* msg->dir must be PEP_dir_outgoing
* @warning msg->from must point to a valid pEp_identity\n
* msg->dir must be PEP_dir_outgoing\n
* the ownership of msg remains with the caller
*
*/
@ -436,8 +437,8 @@ DYNAMIC_API PEP_STATUS outgoing_message_rating(
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal parameter values
*
* @warning msg->from must point to a valid pEp_identity
* msg->dir must be PEP_dir_outgoing
* @warning msg->from must point to a valid pEp_identity\n
* msg->dir must be PEP_dir_outgoing\n
* the ownership of msg remains with the caller
*
*/
@ -507,7 +508,7 @@ DYNAMIC_API PEP_STATUS get_binary_path(PEP_cryptotech tech, const char **path);
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval PEP_TRUSTWORD_NOT_FOUND at least one trustword not found
*
* @warning the word pointer goes to the ownership of the caller
* @warning the word pointer goes to the ownership of the caller.
* the caller is responsible to free() it (on Windoze use pEp_free())
*
*/
@ -543,7 +544,7 @@ DYNAMIC_API PEP_STATUS get_trustwords(
* @retval PEP_CANNOT_FIND_IDENTITY identity not found
* @retval error status of decrypt_message() if decryption fails.
*
* @warning the word pointer goes to the ownership of the caller
* @warning the word pointer goes to the ownership of the caller.
* the caller is responsible to free() it (on Windoze use pEp_free())
*
*/
@ -578,7 +579,7 @@ DYNAMIC_API PEP_STATUS get_message_trustwords(
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval PEP_TRUSTWORD_NOT_FOUND at least one trustword not found
*
* @warning the word pointer goes to the ownership of the caller
* @warning the word pointer goes to the ownership of the caller.
* the caller is responsible to free() it (on Windoze use pEp_free())
*
*/
@ -607,8 +608,8 @@ DYNAMIC_API PEP_STATUS get_trustwords_for_fprs(
* @retval PEP_OUT_OF_MEMORY if not enough memory could be allocated
* @retval any other value on error
*
* @warning msg->from must point to a valid pEp_identity
* the ownership of msg remains with the caller
* @warning msg->from must point to a valid pEp_identity\n
* the ownership of msg remains with the caller\n
* the ownership of x_keylist remains with to the caller
*
*/

6
src/message_api_internal.h
Unescape View File

@ -1,6 +1,6 @@
//
// Created by Krista Bennett on 14.04.21.
//
/// @file message_api_internal.h
/// @author Created by Krista Bennett on 14.04.21.
///
#ifndef MESSAGE_API_INTERNAL_H
#define MESSAGE_API_INTERNAL_H

2
src/message_codec.h
Unescape View File

@ -1,5 +1,5 @@
/**
* @file ASN1Message_codec.h
* @file message_codec.h
* @brief Definitions for ASN1Message encode and decode functions which transform message payloads to
* and from PER-encoded data, and XER text to and from PER
*

6
src/mime.h
Unescape View File

@ -57,9 +57,9 @@ DYNAMIC_API bool is_PGP_message_text(const char *text);
* @retval PEP_OUT_OF_MEMORY if not enough memory could be allocated
* @retval PEP_ILLEGAL_VALUE illegal parameter values
*
* @warning the resulttext will go to the ownership of the caller
* the message will remain in the ownership of the caller
* omit_fields is true for payload of PGP/MIME messages
* @warning the resulttext will go to the ownership of the caller\n
* the message will remain in the ownership of the caller\n
* omit_fields is true for payload of PGP/MIME messages\n
* also: note that the encryption type will be used to determine what
* gets encoded from the message struct, so if using this on an
* already-encrypted message, set the enc_format of the msg to PEP_enc_none.

6
src/pEpEngine.h
Unescape View File

@ -1861,7 +1861,7 @@ DYNAMIC_API PEP_STATUS is_pEp_user(PEP_SESSION session,
DYNAMIC_API const char *per_user_relative_directory(void);
/**
/**
* <!-- per_user_directory() -->
*
* @brief Returns the directory for pEp management db.
@ -1984,7 +1984,7 @@ DYNAMIC_API PEP_STATUS config_passphrase_for_new_keys(PEP_SESSION session,
*
* @brief Set the default encryption format for this identity.
*
* (value only MIGHT be used, and only in the case where the
* (value only MIGHT be used, and only in the case where the
* message enc_format is PEP_enc_auto. It will be used
* opportunistically in the case on a first-come, first-serve
* basis in the order of to_list, cc_list, and bcc_list. We take
@ -2049,7 +2049,7 @@ DYNAMIC_API PEP_STATUS get_replacement_fpr(
*
* @brief TODO
*
* This ONLY sets the *user* flag, and creates a shell identity if necessary.
* This ONLY sets the *user* flag, and creates a shell identity if necessary.
*
* @param[in] session session handle
* @param[in] user pEp_identity*

10
src/pEpEngine_internal.h
Unescape View File

@ -675,11 +675,11 @@ PEP_STATUS exists_identity_entry(PEP_SESSION session, pEp_identity* identity,
bool* exists);
/**
*
* @param session
* @param identity
* @param username
* @return
* <!-- force_set_identity_username() -->
* @param[in] session PEP_SESSION
* @param[in] identity pEp_identity*
* @param[in] username const char*
* @return PEP_STATUS
*/
PEP_STATUS force_set_identity_username(PEP_SESSION session, pEp_identity* identity, const char* username);

8
src/pEp_string.h
Unescape View File

@ -19,14 +19,16 @@ extern "C" {
* <!-- new_string() -->
*
* @brief Allocate a new string
*
* * calling with str and len is equivalent to strndup()
* * calling with str but len=0 is equivalent to strdup()
* * calling with str=NULL is equivalent to calloc()
*
* @param[in] src string to copy or NULL
* @param[in] len length of newly created string or 0 for default
*
* @retval pointer to string object or NULL if out of memory
* calling with str and len is equivalent to strndup()
* calling with str but len=0 is equivalent to strdup()
* calling with str=NULL is equivalent to calloc()
*
*
*
*/

22
src/platform_disable_attributes.h
Unescape View File

@ -1,15 +1,21 @@
#ifndef PLATFORM_DISABLE_ATTRIBUTES_H
#define PLATFORM_DISABLE_ATTRIBUTES_H
/* Disable GNU-style attributes for functions, variables, types and label
(https://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html ), turning them
into noops. This lets the code compile with compilers not supporting
attributes, while keeping them enabled where they matter.
/**
* @file platform_disable_attributes.h
*
* @brief Disable GNU-style attributes for functions, variables, types and label
* (https://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html ), turning them
* into noops.
*
* This lets the code compile with compilers not supporting
* attributes, while keeping them enabled where they matter.
*
* This header is included by platform-specific code where needed: it is not
* for the user to directly see.
* */
This header is included by platform-specific code where needed: it is not
for the user to directly see. */
/* Notice that this definition is extremely conservative: supporting exactly
/** @brief Notice that this definition is extremely conservative: supporting exactly
one argument would suffice. */
#define __attribute__(...) /* nothing */
#define attribute __attribute__

21
src/platform_unix.h
Unescape View File

@ -61,9 +61,10 @@ extern "C" {
* <!-- unix_local_db() -->
*
* @brief TODO
* The returned pointed refers memory managed by
* the engine, which will remain valid until
* the next call to reset_path_cache.
*
* The returned pointed refers memory managed by
* the engine, which will remain valid until
* the next call to reset_path_cache.
*
*/
const char *unix_local_db(void);
@ -72,9 +73,10 @@ const char *unix_local_db(void);
* <!-- unix_system_db() -->
*
* @brief TODO
* The returned pointed refers memory managed by
* the engine, which will remain valid until
* the next call to reset_path_cache.
*
* The returned pointed refers memory managed by
* the engine, which will remain valid until
* the next call to reset_path_cache.
*
*/
const char *unix_system_db(void);
@ -95,9 +97,10 @@ char *stpcpy(char *, const char *);
* <!-- android_system_db() -->
*
* @brief TODO
* The returned pointed refers memory managed by
* the engine, which will remain valid until
* the next call to reset_path_cache.
*
* The returned pointed refers memory managed by
* the engine, which will remain valid until
* the next call to reset_path_cache.
*/
const char *android_system_db(void);
#define SYSTEM_DB android_system_db()

4
src/platform_windows.h
Unescape View File

@ -106,7 +106,9 @@ int mkstemp(char *templ);
* @brief TODO
*
* @param[in] timeptr timestamp*
*
*
* @note It does _not_ respect timeptr->tm_gmtoff, so it behaves the same as its POSIX original.
* Use timegm_with_gmtoff() from <pEp/timestamp.h> or that.
*/
DYNAMIC_API time_t timegm(timestamp *timeptr);

5
src/sqlite3.h
Unescape View File

@ -1,5 +1,6 @@
/** @file */
/** @brief File description for doxygen missing. FIXME */
/** @file
* @brief sqlite3 interface
*/
/*
** 2001-09-15

4
src/status_to_string.h
Unescape View File

@ -22,7 +22,8 @@ extern "C" {
*
* @brief TODO
*
* @param[in] status PEP_STATUS
* @param[in] status PEP_STATUS
* @retval char* string representation of status
*
*/
static inline const char *pEp_status_to_string(PEP_STATUS status) {
@ -137,6 +138,7 @@ static inline const char *pEp_status_to_string(PEP_STATUS status) {
* @brief TODO
*
* @param[in] ct PEP_comm_type
* @retval char* string representation of ct
*
*/
static inline const char *pEp_comm_type_to_string(PEP_comm_type ct) {

5
src/timestamp.h
Unescape View File

@ -16,7 +16,7 @@ extern "C" {
#ifdef WIN32
// this struct is compatible to struct tm
/// @brief this struct is compatible to struct tm. WIN32 only.
typedef struct _timestamp {
int tm_sec;
int tm_min;
@ -40,9 +40,10 @@ typedef struct tm timestamp;
*
* @brief Convert the broken-out time into time_t, and respect tm_gmtoff
*
* @param[in] ts pointer to timestamp to parse
*
* @retval time_t that holds the usual "seconds since epoch"
*
*
*/
DYNAMIC_API time_t timegm_with_gmtoff(const timestamp* ts);

29
src/transport.h
Unescape View File

@ -22,7 +22,7 @@ extern "C" {