buff
/
pEpEngine
forked from pEp.foundation/pEpEngine
1
0
Fork 0
Code Issues 0 Pull Requests 0 Projects 0 Releases 32 Wiki Activity
Browse Source

more comments

doxygen_doc
Sofia Balicka 1 year ago
parent
dfdee25ff4
commit
ce528b3c46
23 changed files with 565 additions and 213 deletions
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. +3
    -3
      src/baseprotocol.h
  2. +3
    -3
      src/etpan_mime.c
  3. +5
    -5
      src/identity_list.c
  4. +4
    -0
      src/identity_list.h
  5. +5
    -5
      src/internal_format.c
  6. +8
    -0
      src/internal_format.h
  7. +35
    -13
      src/key_reset.c
  8. +47
    -7
      src/key_reset.h
  9. +46
    -21
      src/keymanagement.c
  10. +113
    -40
      src/keymanagement.h
  11. +6
    -5
      src/keyreset_command.c
  12. +5
    -5
      src/labeled_int_list.c
  13. +5
    -5
      src/map_asn1.c
  14. +8
    -12
      src/map_asn1.h
  15. +7
    -5
      src/message.c
  16. +3
    -3
      src/message.h
  17. +162
    -45
      src/message_api.c
  18. +45
    -10
      src/message_api.h
  19. +9
    -7
      src/mime.c
  20. +9
    -9
      src/mime.h
  21. +6
    -5
      src/openpgp_compat.c
  22. +4
    -0
      src/openpgp_compat.h
  23. +27
    -5
      src/pEpEngine.h

+ 3
- 3
src/baseprotocol.h View File

@ -80,7 +80,7 @@ PEP_STATUS base_decorate_message(
*
* @retval PEP_STATUS_OK on success
* @retval PEP_OUT_OF_MEMORY out of memory
* @retval PEP_ILLEGAL_VALUE illegal or missing parameter values
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval any other value on failure
*
* @ownership
@ -117,7 +117,7 @@ PEP_STATUS base_prepare_message(
*
* @retval PEP_STATUS_OK jif no error occurred, whether or not sync message was found
* @retval PEP_OUT_OF_MEMORY out of memory
* @retval PEP_ILLEGAL_VALUE illegal or missing parameter values
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval error_status any other value on error
*
* @ownership
@ -157,7 +157,7 @@ PEP_STATUS base_extract_message(
*
* @retval PEP_STATUS_OK if no error occurred, whether or not sync message was found
* @retval PEP_OUT_OF_MEMORY out of memory
* @retval PEP_ILLEGAL_VALUE illegal or missing parameter values
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval error_status any other value on error
*
* @ownership


+ 3
- 3
src/etpan_mime.c View File

@ -2700,7 +2700,7 @@ pEp_error:
* @param[in] *size size_t
*
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal or missing parameter values
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval PEP_OUT_OF_MEMORY out of memory
* @retval any other value on error
*/
@ -2844,7 +2844,7 @@ static PEP_STATUS interpret_protected_headers(
* @param[in] *msg message
*
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal or missing parameter values
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval any other value on error
*
*/
@ -2946,7 +2946,7 @@ static bool _is_marked_as_attachment(struct mailmime_fields *fields)
* @param[in] *has_possible_pEp_msg bool
*
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal or missing parameter values
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval PEP_OUT_OF_MEMORY out of memory
* @retval any other value on error
*/


+ 5
- 5
src/identity_list.c 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.c
* @brief implementation of identity list functions
* @license GNU General Public License 3.0 - see LICENSE.txt
*/
#include "pEp_internal.h"


+ 4
- 0
src/identity_list.h View File

@ -114,6 +114,10 @@ DYNAMIC_API int identity_list_length(const identity_list *id_list);
*
* @param[in] id_list identity_list*
* @param[in] user_id const char*
*
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval PEP_OUT_OF_MEMORY out of memory
*
*/
PEP_STATUS set_all_userids_in_list(identity_list* id_list, const char* user_id);


+ 5
- 5
src/internal_format.c 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.c
* @brief internal format (FIXME: derived from filename)
* @license GNU General Public License 3.0 - see LICENSE.txt
*/
#include "platform.h"


+ 8
- 0
src/internal_format.h View File

@ -26,6 +26,10 @@ extern "C" {
* @param[out] code blob in Internal Message Format
* @param[out] code_size size of code
*
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @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
* does not fail
@ -58,6 +62,10 @@ DYNAMIC_API PEP_STATUS encode_internal(
* @param[out] size size of value
* @param[out] mime_type string with MIME type or NULL for longmsg
*
* @retval PEP_STATUS_OK
* @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


+ 35
- 13
src/key_reset.c 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 key_reset.c
* @brief Implementation of functions for resetting partner key defaults and trust and mistrusting and revoking own keys,
* as well as of functions to inform partners of own revoked keys and their replacements
* @license GNU General Public License 3.0 - see LICENSE.txt
*/
#include "pEp_internal.h"
#include "dynamic_api.h"
@ -45,14 +46,18 @@ static void _add_auto_consume(message* msg) {
*
* @brief TODO
*
* @param[in] session PEP_SESSION
* @param[in] session session handle
* @param[in] *reset_ident constpEp_identity
* @param[in] *old_fpr constchar
* @param[in] *new_fpr constchar
* @param[in] **key_attachments bloblist_t
* @param[in] *old_fpr constchar
* @param[in] *new_fpr constchar
* @param[in] **key_attachments bloblist_t
* @param[in] **command_list keyreset_command_list
* @param[in] include_secret bool
*
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval PEP_OUT_OF_MEMORY out of memory
* @retval any other value on error
*/
static PEP_STATUS _generate_reset_structs(PEP_SESSION session,
const pEp_identity* reset_ident,
@ -172,6 +177,8 @@ pEp_error:
* @param[in] *old_fpr constchar
* @param[in] **dst message
*
* @retval PEP_STATUS_OK
* @retval any other value on error
*/
static PEP_STATUS _generate_own_commandlist_msg(PEP_SESSION session,
identity_list* from_idents,
@ -264,7 +271,7 @@ pEp_error:
*
* @brief TODO
*
* @param[in] session PEP_SESSION
* @param[in] session session handle
* @param[in] *from_ident constpEp_identity
* @param[in] *to_ident constpEp_identity
* @param[in] *old_fpr constchar
@ -272,6 +279,10 @@ pEp_error:
* @param[in] is_private bool
* @param[in] **dst message
*
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval PEP_OUT_OF_MEMORY out of memory
* @retval any other value on error
*/
static PEP_STATUS _generate_keyreset_command_message(PEP_SESSION session,
const pEp_identity* from_ident,
@ -1007,6 +1018,9 @@ DYNAMIC_API PEP_STATUS key_reset_all_own_keys(PEP_SESSION session) {
* @param[in] *idents identity_list
* @param[in] **filtered identity_list
*
* @retval PEP_STATUS_OK
* @retval PEP_OUT_OF_MEMORY out of memory
* @retval any other value on error
*/
static PEP_STATUS _dup_grouped_only(identity_list* idents, identity_list** filtered) {
if (!idents)
@ -1048,9 +1062,13 @@ static PEP_STATUS _dup_grouped_only(identity_list* idents, identity_list** filte
*
* @brief TODO
*
* @param[in] session PEP_SESSION
* @param[in] session session handle
* @param[in] *key constchar
*
* @retval PEP_STATUS_OK
* @retval PEP_PASSPHRASE_FOR_NEW_KEYS_REQUIRED
* @retval PEP_KEY_NOT_FOUND
* @retval any other value on error
*/
static PEP_STATUS _check_own_reset_passphrase_readiness(PEP_SESSION session,
const char* key) {
@ -1120,11 +1138,15 @@ static PEP_STATUS _check_own_reset_passphrase_readiness(PEP_SESSION session,
*
* @brief TODO
*
* @param[in] session PEP_SESSION
* @param[in] session session handle
* @param[in] *key_idents identity_list
* @param[in] *old_key constchar
* @param[in] grouped_only bool
*
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval PEP_SYNC_NO_MESSAGE_SEND_CALLBACK
* @retval any other value on error
*/
static PEP_STATUS _key_reset_device_group_for_shared_key(PEP_SESSION session,
identity_list* key_idents,
@ -1882,5 +1904,5 @@ enomem:
the_end:
ASN_STRUCT_FREE(asn_DEF_Distribution, dist);
return status;
return status
}

+ 47
- 7
src/key_reset.h View File

@ -40,6 +40,10 @@ extern "C" {
* Note: ident->fpr field will be ignored.
*
*
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval PEP_OUT_OF_MEMORY out of memory
* @retval any other value on error
*/
DYNAMIC_API PEP_STATUS key_reset_identity(
PEP_SESSION session,
@ -71,6 +75,10 @@ DYNAMIC_API PEP_STATUS key_reset_identity(
* call key_reset_all_own_keys ***
*
*
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval PEP_OUT_OF_MEMORY out of memory
* @retval any other value on error
*/
//
@ -108,7 +116,7 @@ DYNAMIC_API PEP_STATUS key_reset_all_own_keys(PEP_SESSION session);
*
* @brief TODO
*
* @param[in] session PEP_SESSION
* @param[in] session session handle
*
*/
DYNAMIC_API PEP_STATUS key_reset_own_grouped_keys(PEP_SESSION session);
@ -146,6 +154,10 @@ DYNAMIC_API PEP_STATUS key_reset_own_grouped_keys(PEP_SESSION session);
* and this function should probably be removed from the dynamic api
*
*
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval PEP_OUT_OF_MEMORY out of memory
* @retval any other value on error
*/
PEP_STATUS key_reset(
PEP_SESSION session,
@ -165,12 +177,15 @@ PEP_STATUS key_reset_own_and_deliver_revocations(PEP_SESSION session,
*
* @brief TODO
*
* @param[in] session PEP_SESSION
* @param[in] session session handle
* @param[in] from_addr const char*
* @param[in] user_id const char*
* @param[in] revoked_fpr const char*
* @param[in] contacted bool*
*
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval any other value on error
*/
PEP_STATUS has_key_reset_been_sent(
PEP_SESSION session,
@ -184,11 +199,14 @@ PEP_STATUS has_key_reset_been_sent(
*
* @brief TODO
*
* @param[in] session PEP_SESSION
* @param[in] session session handle
* @param[in] own_address const char*
* @param[in] revoke_fpr const char*
* @param[in] contact_id const char*
*
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval PEP_UNKNOWN_DB_ERROR
*/
PEP_STATUS set_reset_contact_notified(
PEP_SESSION session,
@ -202,10 +220,18 @@ PEP_STATUS set_reset_contact_notified(
*
* @brief TODO
*
* @param[in] session PEP_SESSION
* @param[in] session session handle
* @param[in] reset_msg message*
*
*/
*
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval PEP_OUT_OF_MEMORY out of memory
* @retval PEP_MALFORMED_KEY_RESET_MSG
* @retval PEP_KEY_NOT_RESET
* @retval PEP_UNKNOWN_ERROR
* @retval any other value on error
* */
PEP_STATUS receive_key_reset(PEP_SESSION session,
message* reset_msg);
@ -214,13 +240,17 @@ PEP_STATUS receive_key_reset(PEP_SESSION session,
*
* @brief TODO
*
* @param[in] session PEP_SESSION
* @param[in] session session handle
* @param[in] dst message**
* @param[in] own_identity pEp_identity*
* @param[in] recip pEp_identity*
* @param[in] old_fpr const char*
* @param[in] new_fpr const char*
*
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval PEP_UNKNOWN_ERROR
* @retval any other value on error
*/
PEP_STATUS create_standalone_key_reset_message(PEP_SESSION session,
message** dst,
@ -235,11 +265,15 @@ PEP_STATUS create_standalone_key_reset_message(PEP_SESSION session,
*
* @brief TODO
*
* @param[in] session PEP_SESSION
* @param[in] session session handle
* @param[in] from_ident pEp_identity*
* @param[in] old_fpr const char*
* @param[in] new_fpr const char*
*
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval PEP_SYNC_NO_MESSAGE_SEND_CALLBACK
* @retval any other value on error
*/
PEP_STATUS send_key_reset_to_recents(PEP_SESSION session,
pEp_identity* from_ident,
@ -255,6 +289,9 @@ PEP_STATUS send_key_reset_to_recents(PEP_SESSION session,
* @param[in] cmds char**
* @param[in] size size_t*
*
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval any other value on error
*/
PEP_STATUS key_reset_commands_to_PER(const keyreset_command_list *command_list, char **cmds, size_t *size);
/**
@ -266,6 +303,9 @@ PEP_STATUS key_reset_commands_to_PER(const keyreset_command_list *command_list,
* @param[in] size size_t
* @param[in] command_list keyreset_command_list**
*
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval any other value on error
*/
PEP_STATUS PER_to_key_reset_commands(const char *cmds, size_t size, keyreset_command_list **command_list);


+ 46
- 21
src/keymanagement.c 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 keymanagement.c
* @brief Implementation of functions to manage keys
* (and identities when in relation to keys)
* @license GNU General Public License 3.0 - see LICENSE.txt
*/
#include "platform.h"
@ -51,10 +52,12 @@ static bool key_matches_address(PEP_SESSION session, const char* address,
*
* @brief TODO
*
* @param[in] session PEP_SESSION
* @param[in] *identity pEp_identity
* @param[in] session session handle
* @param[in] *identity pEp_identity
* @param[in] check_blacklist bool
*
* @retval PEP_STATUS_OK
* @retval PEP_OUT_OF_MEMORY out of memory
*/
PEP_STATUS elect_pubkey(
PEP_SESSION session, pEp_identity * identity, bool check_blacklist
@ -131,12 +134,20 @@ PEP_STATUS elect_pubkey(
*
* @brief TODO
*
* @param[in] session PEP_SESSION
* @param[in] *ident pEp_identity
* @param[in] check_blacklist bool
* @param[in] own_must_contain_private bool
* @param[in] renew_private bool
* @param[in] session session handle
* @param[in] *ident pEp_identity
* @param[in] check_blacklist bool
* @param[in] own_must_contain_private bool
* @param[in] renew_private bool
*
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval PEP_OUT_OF_MEMORY out of memory
* @retval PEP_KEY_UNSUITABLE
* @retval PEP_PASSPHRASE_REQUIRED
* @retval PEP_WRONG_PASSPHRASE
* @retval any other value on error
*
*/
static PEP_STATUS validate_fpr(PEP_SESSION session,
pEp_identity* ident,
@ -548,7 +559,7 @@ static void transfer_ident_lang_and_flags(pEp_identity* new_ident,
*
* @brief TODO
*
* @param[in] session PEP_SESSION
* @param[in] session session handle
* @param[in] *identity pEp_identity
*
*/
@ -588,11 +599,14 @@ static void adjust_pEp_trust_status(PEP_SESSION session, pEp_identity* identity)
*
* @brief TODO
*
* @param[in] session PEP_SESSION
* @param[in] session session handle
* @param[in] *return_id pEp_identity
* @param[in] *stored_ident pEp_identity
* @param[in] store bool
* @param[in] *stored_ident pEp_identity
* @param[in] store bool
*
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval any other value on error
*/
static PEP_STATUS prepare_updated_identity(PEP_SESSION session,
pEp_identity* return_id,
@ -1128,9 +1142,13 @@ pEp_free:
*
* @brief TODO
*
* @param[in] session PEP_SESSION
* @param[in] *identity pEp_identity
* @param[in] session session handle
* @param[in] *identity pEp_identity
*
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval PEP_OUT_OF_MEMORY out of memory
* @retval any other value on error
*/
PEP_STATUS elect_ownkey(
PEP_SESSION session, pEp_identity * identity
@ -1212,10 +1230,13 @@ PEP_STATUS elect_ownkey(
*
* @brief TODO
*
* @param[in] session PEP_SESSION
* @param[in] *fpr char
* @param[in] session session handle
* @param[in] *fpr char
* @param[in] *is_usable bool
*
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval any other value on error
*/
PEP_STATUS _has_usable_priv_key(PEP_SESSION session, char* fpr,
bool* is_usable) {
@ -2245,9 +2266,13 @@ PEP_STATUS is_mistrusted_key(PEP_SESSION session, const char* fpr,
*
* @brief TODO
*
* @param[in] session PEP_SESSION
* @param[in] session session handle
* @param[in] *ident pEp_identity
*
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval PEP_OUT_OF_MEMORY out of memory
* @retval any other value on error
*/
static PEP_STATUS _wipe_default_key_if_invalid(PEP_SESSION session,
pEp_identity* ident) {


+ 113
- 40
src/keymanagement.h View File

@ -28,12 +28,12 @@ extern "C" {
*
* @retval PEP_STATUS_OK if identity could be updated,
* @retval PEP_ILLEGAL_VALUE if called with illegal inputs, including an identity
* @retval with .me set or with an own user_id specified in the
* @retval *input* (see caveats)
* with .me set or with an own user_id specified in the
* *input* (see caveats)
* @retval PEP_KEY_UNSUITABLE if a default key was found for this identity, no
* @retval other acceptable keys were found; if this is returned,
* @retval the reason for rejecting the first default key found
* @retval may be found in the comm_type
* other acceptable keys were found; if this is returned,
* the reason for rejecting the first default key found
* may be found in the comm_type
* @retval any other value on error
*
* @warning at least identity->address must be a non-empty UTF-8 string as input
@ -105,6 +105,8 @@ DYNAMIC_API PEP_STATUS update_identity(
* the username record for this identity.
*
* @retval PEP_STATUS_OK if identity could be completed or was already complete,
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval PEP_OUT_OF_MEMORY out of memory
* @retval any other value on error
*
* @warning If an fpr was entered and is not a valid key, the reason for failure
@ -129,13 +131,17 @@ DYNAMIC_API PEP_STATUS myself(PEP_SESSION session, pEp_identity * identity);
*
* @brief TODO
*
* @param[in] session PEP_SESSION
* @param[in] session session handle
* @param[in] identity pEp_identity*
* @param[in] do_keygen bool
* @param[in] do_renew bool
* @param[in] ignore_flags bool
* @param[in] read_only bool
*
* @retval PEP_STATUS_OK if identity could be completed or was already complete,
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval PEP_OUT_OF_MEMORY out of memory
* @retval any other value on error
*/
PEP_STATUS _myself(PEP_SESSION session,
pEp_identity * identity,
@ -152,9 +158,9 @@ PEP_STATUS _myself(PEP_SESSION session,
* @param[in] management data structure to deliver (implementation defined)
*
* @retval identity to check or NULL to terminate do_keymanagement()
* @retval if given identity must be created with new_identity()
* @retval the identity struct is going to the ownership of this library
* @retval it must not be freed by the callee
* if given identity must be created with new_identity()
* the identity struct is going to the ownership of this library
* it must not be freed by the callee
*
* @warning this callback has to block until an identity or NULL can be returned
* an implementation is not provided by this library; instead it has to be
@ -190,6 +196,8 @@ typedef int (*examine_identity_t)(pEp_identity *ident, void *management);
* @param[in] examine_identity examine_identity() function to register
* @param[in] management data structure to deliver (implementation defined)
*
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal parameter values
*
*/
@ -209,8 +217,10 @@ DYNAMIC_API PEP_STATUS register_examine_function(
* callback which returns at least a valid
* address field in the identity struct
*
* @retval PEP_STATUS_OK if thread has to terminate successfully or any other
* @retval value on failure
* @retval PEP_STATUS_OK if thread has to terminate successfully
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval PEP_OUT_OF_MEMORY out of memory
* @retval any other value on failure
*
* @warning to ensure proper working of this library, a thread has to be started
* with this function immediately after initialization
@ -259,7 +269,14 @@ DYNAMIC_API PEP_STATUS key_mistrusted(
* @param[in] ident person and key to trust in - this must not be an
* own_identity in which the .me flag is set or
* the user_id is an own user_id.
*
*
* @retval PEP_STATUS_OK
* @retval PEP_KEY_UNSUITABLE
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval PEP_OUT_OF_MEMORY out of memory
* @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,
@ -285,6 +302,12 @@ DYNAMIC_API PEP_STATUS trust_personal_key(
* @param[in] session session to use
* @param[in] ident own ident containing fpr to trust
*
* @retval PEP_STATUS_OK
* @retval PEP_KEY_UNSUITABLE
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval PEP_OUT_OF_MEMORY out of memory
* @retval any other value on error
*
* @warning if this is a public key only, keep in mind that if
* the private part of the keypair is later added,
* it will not undergo separate trust evaluation. This
@ -314,6 +337,11 @@ DYNAMIC_API PEP_STATUS trust_own_key(
* @param[in] session session to use
* @param[in] ident identity for person and key whose trust status is to be reset
*
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval PEP_OUT_OF_MEMORY out of memory
* @retval any other value on error
*
* @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,
@ -336,6 +364,9 @@ DYNAMIC_API PEP_STATUS key_reset_trust(
* @param[in] fpr fingerprint of key to test
* @param[out] listed flags if key is own
*
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval any other value on error
*
*/
@ -353,8 +384,13 @@ DYNAMIC_API PEP_STATUS own_key_is_listed(
*
* @param[in] session session to use
* @param[out] own_identities list of own identities
* excluded_flags (int) flags to exclude from results
* @param[in] excluded_flags flags to exclude from results
*
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval PEP_OUT_OF_MEMORY out of memory
* @retval any other value on error
*
* @warning the ownership of the copy of own_identities goes to the caller
*
*/
@ -373,6 +409,11 @@ DYNAMIC_API PEP_STATUS _own_identities_retrieve(
* @param[in] session session to use
* @param[out] own_identities list of own identities
*
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval PEP_OUT_OF_MEMORY out of memory
* @retval any other value on error
*
* @warning the ownership of the copy of own_identities goes to the caller
*
*/
@ -387,10 +428,13 @@ DYNAMIC_API PEP_STATUS own_identities_retrieve(
*
* @brief TODO
*
* @param[in] session PEP_SESSION
* @param[in] session session handle
* @param[in] fpr const char*
* @param[in] has_private bool*
*
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval any other value on error
*/
PEP_STATUS contains_priv_key(PEP_SESSION session, const char *fpr,
bool *has_private);
@ -405,6 +449,10 @@ PEP_STATUS contains_priv_key(PEP_SESSION session, const char *fpr,
* @param[in] excluded_flags flags to exclude from results
* @param[in] private_only if true, return only fprs for
* which we have the secret part
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval PEP_OUT_OF_MEMORY out of memory
* @retval any other value on error
*
* @warning the ownership of the list goes to the caller
*
@ -424,6 +472,11 @@ DYNAMIC_API PEP_STATUS _own_keys_retrieve(
* @param[in] session session to use
* @param[out] keylist list of fingerprints
*
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval PEP_OUT_OF_MEMORY out of memory
* @retval any other value on error
*
* @warning the ownership of the list goes to the caller
* this function does not return keys without a private key part
*
@ -442,6 +495,12 @@ DYNAMIC_API PEP_STATUS own_keys_retrieve(
* @param[in,out] me own identity this key is used for
* @param[in] fpr fingerprint of the key to mark as own key
*
* @retval PEP_STATUS_OK
* @retval PEP_KEY_UNSUITABLE
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval PEP_OUT_OF_MEMORY out of memory
* @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
@ -460,29 +519,23 @@ DYNAMIC_API PEP_STATUS set_own_key(
const char *fpr
);
//
// 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() -->
*
* @brief TODO
* @brief Remove any broken, unrenewable expired, or revoked
* own keys from identity and user defaults in the database.
*
* @param[in] session session handle
*
* @retval PEP_STATUS_OK if all went well
* @retval PEP_ILLEGAL_VALUE illegal parameter values
*
* @retval PEP_PASSPHRASE_REQUIRED if a key needs to be renewed
* but cached passphrase isn't present
* @retval PEP_WRONG_PASSPHRASE if passphrase required for expired key renewal
* but passphrase is the wrong one
* @retval Otherwise, database and keyring errors as appropriate
*
* @param[in] session PEP_SESSION
*
*/
DYNAMIC_API PEP_STATUS clean_own_key_defaults(PEP_SESSION session);
@ -492,10 +545,15 @@ DYNAMIC_API PEP_STATUS clean_own_key_defaults(PEP_SESSION session);
*
* @brief TODO
*
* @param[in] session PEP_SESSION
* @param[in] session session handle
* @param[in] user_id const char*
* @param[in] keys stringlist_t**
*
*
* @retval PEP_STATUS_OK
* @retval PEP_KEY_NOT_FOUND
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval any other value on error
*/
PEP_STATUS get_all_keys_for_user(PEP_SESSION session,
const char* user_id,
@ -509,19 +567,25 @@ PEP_STATUS get_all_keys_for_user(PEP_SESSION session,
*
* @brief TODO
*
* @param[in] session PEP_SESSION
* @param[in] session session handle
* @param[in] fpr const char*
*
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval PEP_CANNOT_SET_PGP_KEYPAIR
*/
PEP_STATUS add_mistrusted_key(PEP_SESSION session, const char* fpr);
/**
* <!-- delete_mistrusted_key() -->
*
* @brief TODO
*
* @param[in] session PEP_SESSION
*
* @param[in] session session handle
* @param[in] fpr const char*
*
*
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval PEP_UNKNOWN_ERROR
*/
PEP_STATUS delete_mistrusted_key(PEP_SESSION session, const char* fpr);
/**
@ -529,10 +593,13 @@ PEP_STATUS delete_mistrusted_key(PEP_SESSION session, const char* fpr);
*
* @brief TODO
*
* @param[in] session PEP_SESSION
* @param[in] session session handle
* @param[in] fpr const char*
* @param[in] mistrusted bool*
*
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval PEP_UNKNOWN_ERROR
*/
PEP_STATUS is_mistrusted_key(PEP_SESSION session, const char* fpr, bool* mistrusted);
/**
@ -540,10 +607,13 @@ PEP_STATUS is_mistrusted_key(PEP_SESSION session, const char* fpr, bool* mistrus
*
* @brief TODO
*
* @param[in] session PEP_SESSION
* @param[in] session session handle
* @param[in] user_id const char*
* @param[in] default_key char**
*
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval PEP_GET_KEY_FAILED
*/
PEP_STATUS get_user_default_key(PEP_SESSION session, const char* user_id,
char** default_key);
@ -560,13 +630,16 @@ PEP_STATUS get_user_default_key(PEP_SESSION session, const char* user_id,
*
* @brief TODO
*
* @param[in] session PEP_SESSION
* @param[in] session session handle
* @param[in] stored_identity pEp_identity*
* @param[in] is_identity_default bool*
* @param[in] is_user_default bool*
* @param[in] is_address_default bool*
* @param[in] check_blacklist bool
*
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval any other value on error
*/
PEP_STATUS get_valid_pubkey(PEP_SESSION session,
pEp_identity* stored_identity,


+ 6
- 5
src/keyreset_command.c 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 keyreset_command.c
* @brief implementation of keyreset command structure and list memory,
* manipulation and informational functions
* @license GNU General Public License 3.0 - see LICENSE.txt
*/
#include "pEp_internal.h"


+ 5
- 5
src/labeled_int_list.c 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 labeled_int_list.c
* @brief list structure which binds ints to labels
* @license GNU General Public License 3.0 - see LICENSE.txt
*/
#include <stdbool.h>
#include <stdlib.h>


+ 5
- 5
src/map_asn1.c 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 map_asn1.c
* @brief map asn1 to pEp structs and back
* @license GNU General Public License 3.0 - see LICENSE.txt
*/
#include "pEp_internal.h"
#include "map_asn1.h"


+ 8
- 12
src/map_asn1.h View File

@ -22,9 +22,8 @@ extern "C" {
*
* @brief Convert pEp_identity into ASN.1 Identity_t
*
* params:
* ident (in) pEp_identity to convert
* result (inout) Identity_t to update or NULL to alloc a new one
* @param ident[in] pEp_identity to convert
* @param result[in,out] Identity_t to update or NULL to alloc a new one
*
* @retval pointer to updated or allocated result
*
@ -43,9 +42,8 @@ Identity_t *Identity_from_Struct(
*
* @brief Convert ASN.1 Identity_t into pEp_identity
*
* params:
* ident (in) Identity_t to convert
* result (inout) pEp_identity to update or NULL to alloc a new one
* @param ident[in] Identity_t to convert
* @param result[inout] pEp_identity to update or NULL to alloc a new one
*
* @retval pointer to updated or allocated result
*
@ -61,9 +59,8 @@ pEp_identity *Identity_to_Struct(Identity_t *ident, pEp_identity *result);
*
* @brief Convert identity_list_t into ASN.1 IdentityList_t
*
* params:
* list (in) identity_list to convert
* result (inout) IdentityList_t to update or NULL to alloc a new one
* @param list[in] identity_list to convert
* @param result[inout] IdentityList_t to update or NULL to alloc a new one
*
* @retval pointer to updated or allocated result
*
@ -81,9 +78,8 @@ IdentityList_t *IdentityList_from_identity_list(
*
* @brief Convert ASN.1 IdentityList_t to identity_list_t
*
* params:
* list (in) ASN.1 IdentityList_t to convert
* result (inout) identity_list_t to update or NULL to alloc a new one
* @param list[in] ASN.1 IdentityList_t to convert
* @param result[inout] identity_list_t to update or NULL to alloc a new one
*
* @retval pointer to updated or allocated result
*


+ 7
- 5
src/message.c View File

@ -1,8 +1,10 @@
/** @file */
/** @brief File description for doxygen missing. FIXME */
// This file is under GNU General Public License 3.0
// see LICENSE.txt
/**
* @file message.c
* @brief implementation of the pEp message structure and functions used to represent messages and pass message
* information back and forth between the engine and its customers. Includes memory management
* for said structs.
* @license GNU General Public License 3.0 - see LICENSE.txt
*/
#include "pEp_internal.h"


+ 3
- 3
src/message.h View File

@ -141,8 +141,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
* @retval NOTA BENE:
* @retval not owned pointees (msg->rawmsg_ref and msg->refering_msg_ref) are shared!
* NOTA BENE:
* not owned pointees (msg->rawmsg_ref and msg->refering_msg_ref) are shared!
*
*
*/
@ -224,7 +224,7 @@ DYNAMIC_API message_ref_list *message_ref_list_dup(
* @param[in] msg message to add a reference to
*
* @retval pointer to the last element of message_ref_list or NULL if out of
* @retval memory
* memory
*
*
*/


+ 162
- 45
src/message_api.c 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 message_api.c
* @brief implementation of pEp engine API for message handling and evaluation and related functions
* @license GNU General Public License 3.0 - see LICENSE.txt
*/
#include "pEp_internal.h"
#include "message_api.h"
@ -39,7 +39,8 @@ double _pEp_log2_36;
* @brief TODO
*
* @param[in] *msg constmessage
*
*
* @retval bool
*/
static bool is_a_pEpmessage(const message *msg)
{
@ -255,6 +256,7 @@ void replace_opt_field(message *msg,
*
* @param[in] *msg message
*
* @retval bool
*/
static bool sync_message_attached(message *msg)
{
@ -276,10 +278,15 @@ static bool sync_message_attached(message *msg)
*
* @brief TODO
*
* @param[in] session PEP_SESSION
* @param[in] session session handle
* @param[in] *msg message
* @param[in] rating PEP_rating
*
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval PEP_OUT_OF_MEMORY out of memory
* @retval PEP_SYNC_NO_CHANNEL
* @retval any other value on error
*/
PEP_STATUS set_receiverRating(PEP_SESSION session, message *msg, PEP_rating rating)
{
@ -316,10 +323,14 @@ PEP_STATUS set_receiverRating(PEP_SESSION session, message *msg, PEP_rating rati
*
* @brief TODO
*
* @param[in] session PEP_SESSION
* @param[in] session session handle
* @param[in] *msg message
* @param[in] *rating PEP_rating
*
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval PEP_SYNC_NO_CHANNEL
* @retval any other value on error
*/
PEP_STATUS get_receiverRating(PEP_SESSION session, message *msg, PEP_rating *rating)
{
@ -394,7 +405,8 @@ void decorate_message(
* @brief TODO
*
* @param[in] *uri char
*
*
* @retval bool
*/
static char* _get_resource_ptr_noown(char* uri) {
char* uri_delim = strstr(uri, "://");
@ -413,7 +425,8 @@ static char* _get_resource_ptr_noown(char* uri) {
*
* @param[in] *s1 const char
* @param[in] *s2 const char
*
*
* @retval bool
*/
static bool string_equality(const char *s1, const char *s2)
{
@ -435,6 +448,7 @@ static bool string_equality(const char *s1, const char *s2)
* @param[in] *bl constbloblist_t
* @param[in] *mt constchar
*
* @retval bool
*/
static bool is_mime_type(const bloblist_t *bl, const char *mt)
{
@ -458,7 +472,8 @@ static bool is_mime_type(const bloblist_t *bl, const char *mt)
*
* @param[in] *bl constbloblist_t
* @param[in] *fe constchar
*
*
* @retval
*/
static bool is_fileending(const bloblist_t *bl, const char *fe)
{
@ -594,6 +609,8 @@ static char * combine_short_and_long(const char *shortmsg, const char *longmsg)
*
* @param[in] *msg message
*
* @retval PEP_STATUS_OK
* @retval PEP_OUT_OF_MEMORY out of memory
*/
static PEP_STATUS replace_subject(message* msg) {
unsigned char pEpstr[] = PEP_SUBJ_STRING;
@ -733,6 +750,9 @@ static char* message_id_prand_part(void) {
*
* @param[in] *msg message
*
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval PEP_OUT_OF_MEMORY out of memory
*/
static PEP_STATUS generate_message_id(message* msg) {
@ -835,6 +855,8 @@ enomem:
* @param[in] **data char
* @param[in] **modified_msg char
*
* @retval PEP_STATUS_OK
* @retval PEP_OUT_OF_MEMORY out of memory
*/
static PEP_STATUS get_data_from_encapsulated_line(const char* plaintext, const char* key,
const size_t keylen, char** data,
@ -969,6 +991,9 @@ enomem:
* @param[in] *dst message
* @param[in] *src constmessage
*
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval PEP_OUT_OF_MEMORY out of memory
*/
static PEP_STATUS copy_fields(message *dst, const message *src)
{
@ -1336,6 +1361,9 @@ enomem:
* @param[in] *dst message
* @param[in] flags PEP_encrypt_flags_t
*
* @retval PEP_STATUS_OK
* @retval PEP_OUT_OF_MEMORY out of memory
* @retval any other value on error
*/
static PEP_STATUS encrypt_PGP_inline(
PEP_SESSION session,
@ -1472,6 +1500,9 @@ static PEP_STATUS encrypt_PGP_inline(
* @param[in] flags PEP_encrypt_flags_t
* @param[in] wrap_type message_wrap_type
*
* @retval PEP_STATUS_OK
* @retval PEP_OUT_OF_MEMORY out of memory
* @retval any other value on error
*/
static PEP_STATUS encrypt_PGP_MIME(
PEP_SESSION session,
@ -1636,6 +1667,7 @@ DYNAMIC_API PEP_rating rating_from_comm_type(PEP_comm_type ct)
*
* @param[in] *blob constbloblist_t
*
* @retval bool
*/
static bool is_encrypted_attachment(const bloblist_t *blob)
{
@ -1675,6 +1707,7 @@ static bool is_encrypted_attachment(const bloblist_t *blob)
*
* @param[in] *blob constbloblist_t
*
* @retval bool
*/
static bool is_encrypted_html_attachment(const bloblist_t *blob)
{
@ -1728,6 +1761,7 @@ static char * without_double_ending(const char *filename)
*
* @param[in] status PEP_STATUS
*
* @retval PEP_rating rating value for comm type ct
*/
static PEP_rating decrypt_rating(PEP_STATUS status)
{
@ -1982,6 +2016,7 @@ static PEP_comm_type _get_comm_type_preview(
*
* @param[in] *bl constbloblist_t
*
* @retval bool
*/
static bool is_key(const bloblist_t *bl)
{
@ -2064,12 +2099,13 @@ static bool compare_first_n_bytes(const char* first, const char* second, size_t
*
* @brief TODO
*
* @param[in] session PEP_SESSION
* @param[in] session session handle
* @param[in] *msg message
* @param[in] **private_idents identity_list
* @param[in] **imported_key_list stringlist_t
* @param[in] *changed_keys uint64_t
*
* @retval bool
*/
bool import_attached_keys(
PEP_SESSION session,
@ -2197,7 +2233,12 @@ bool import_attached_keys(
* @param[in] session PEP_SESSION
* @param[in] *fpr constchar
* @param[in] *msg message
*
*
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval PEP_KEY_NOT_FOUND key not found
* @retval PEP_OUT_OF_MEMORY out of memory
* @retval any other value on error
*/
PEP_STATUS _attach_key(PEP_SESSION session, const char* fpr, message *msg)
{
@ -2331,10 +2372,13 @@ static void _cleanup_src(message* src, bool remove_attached_key) {
*
* @brief TODO
*
* @param[in] session PEP_SESSION
* @param[in] session session handle
* @param[in] *id_list identity_list
* @param[in] enc_format PEP_enc_format
*
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal parameter value
* @retval PEP_CANNOT_SET_IDENTITY
*/
static PEP_STATUS id_list_set_enc_format(PEP_SESSION session, identity_list* id_list, PEP_enc_format enc_format) {
PEP_STATUS status = PEP_STATUS_OK;
@ -2392,10 +2436,11 @@ DYNAMIC_API PEP_STATUS probe_encrypt(PEP_SESSION session, const char *fpr)
*
* <!-- failed_test() -->
*
* @brief TODO
* @brief returns true if status indicates failure
*
* @param[in] status PEP_STATUS
*
* @retval bool
*/
static bool failed_test(PEP_STATUS status)
{
@ -2427,6 +2472,10 @@ static bool failed_test(PEP_STATUS status)
* @param[in] *dest_keys_found bool
* @param[in] suppress_update_for_bcc bool
*
* @retval PEP_STATUS_OK
* @retval PEP_ILLEGAL_VALUE illegal parameter values
* @retval PEP_UNKNOWN_DB_ERROR;
* @retval any other value on error
*/
static PEP_STATUS _update_state_for_ident_list(
PEP_SESSION session,
@ -3231,9 +3280,10 @@ pEp_error:
*
* @brief TODO
*
* @param[in] *msg message
* @param[in] **signature_blob bloblist_t
* @param[in] *msg message
* @param[in,out] **signature_blob bloblist_t
*
* @retval PEP_STATUS_OK
*/
static PEP_STATUS _get_detached_signature(message* msg,
bloblist_t** signature_blob) {
@ -3260,11 +3310,14 @@ static PEP_STATUS _get_detached_signature(message* msg,
*
* @brief TODO
*
* @param[in] *ptext constchar
* @param[in] psize constsize_t
* @param[in] **stext char
* @param[in] *ssize size_t
* @param[in] *ptext constchar
* @param[in] psize constsize_t
* @param[in,out] **stext char
* @param[in,out] *ssize size_t
*
* @retval PEP_STATUS_OK
* @retval PEP_UNKNOWN_ERROR
* @retval PEP_OUT_OF_MEMORY out of memory
*/
static PEP_STATUS _get_signed_text(const char* ptext, const size_t psize,
char** stext, size_t* ssize) {
@ -3348,11 +3401,14 @@ static PEP_STATUS _get_signed_text(const char* ptext, const size_t psize,
*
* @brief TODO
*
* @param[in] session PEP_SESSION
* @param[in] **verify_in stringlist_t
* @param[in] **keylist_in_out stringlist_t
* @param[in] *from pEp_identity
* @param[in] session session handle
* @param[in] **verify_in stringlist_t
* @param[in,out] **keylist_in_out stringlist_t
* @param[in,out] *from pEp_identity
*
* @retval PEP_STATUS_OK
* @retval PEP_KEY_NOT_FOUND
* @retval any other value on error
*/
static PEP_STATUS combine_keylists(PEP_SESSION session, stringlist_t** verify_in,
stringlist_t** keylist_in_out,
@ -3387,6 +3443,7 @@ static PEP_STATUS combine_keylists(PEP_SESSION session, stringlist_t** verify_in
status = PEP_KEY_NOT_FOUND;
goto free;
}
return false;
verify_curr = orig_verify;
@ -3440,11 +3497,15 @@ free:
*
* @brief TODO
*
* @param[in] session PEP_SESSION
* @param[in] *rating PEP_rating
* @param[in] *sender pEp_identity
* @param[in] session session handle
* @param[in] *rating PEP_rating
* @param[in] *sender pEp_identity