src/keymanagement.h
author Edouard Tisserant <edouard@pep-project.org>
Fri, 18 Nov 2016 00:13:40 +0100
branchENGINE-140_exclude_identity_from_sync
changeset 1406 8d8ae9657388
parent 1394 8659157b681f
child 1412 51341b8d69d0
permissions -rw-r--r--
ENGINE-140 changed identities flags update policy
     1 #pragma once
     2 
     3 #include "pEpEngine.h"
     4 
     5 #ifdef __cplusplus
     6 extern "C" {
     7 #endif
     8 
     9 // update_identity() - update identity information
    10 //
    11 //  parameters:
    12 //      session (in)        session to use
    13 //      identity (inout)    identity information of communication partner
    14 //                          (identity->fpr is OUT ONLY)
    15 //  caveat:
    16 //      if this function returns PEP_ct_unknown or PEP_ct_key_expired in
    17 //      identity->comm_type, the caller must insert the identity into the
    18 //      asynchronous management implementation, so retrieve_next_identity()
    19 //      will return this identity later
    20 //      at least identity->address must be a non-empty UTF-8 string as input
    21 //      update_identity() never writes flags; use set_identity_flags() for
    22 //      writing
    23 //      this function NEVER reads the incoming fpr, only writes to it.
    24 
    25 DYNAMIC_API PEP_STATUS update_identity(
    26         PEP_SESSION session, pEp_identity * identity
    27     );
    28 
    29 
    30 // myself() - ensures that the own identity is being complete
    31 //
    32 //  parameters:
    33 //      session (in)        session to use
    34 //      identity (inout)    identity of local user
    35 //                          at least .address, .username, .user_id must be set
    36 //
    37 //  return value:
    38 //      PEP_STATUS_OK if identity could be completed or was already complete,
    39 //      any other value on error
    40 //
    41 //  caveat:
    42 //      this function generates a keypair on demand; because it's synchronous
    43 //      it can need a decent amount of time to return
    44 //      if you need to do this asynchronous, you need to return an identity
    45 //      with retrieve_next_identity() where pEp_identity.me is true
    46 
    47 DYNAMIC_API PEP_STATUS myself(PEP_SESSION session, pEp_identity * identity);
    48 
    49 PEP_STATUS _myself(PEP_SESSION session, pEp_identity * identity, bool do_keygen, bool ignore_flags);
    50 
    51 // retrieve_next_identity() - callback being called by do_keymanagement()
    52 //
    53 //  parameters:
    54 //      management (in)     data structure to deliver (implementation defined)
    55 //
    56 //  return value:
    57 //      identity to check or NULL to terminate do_keymanagement()
    58 //      if given identity must be created with new_identity()
    59 //      the identity struct is going to the ownership of this library
    60 //      it must not be freed by the callee
    61 //
    62 //  caveat:
    63 //      this callback has to block until an identity or NULL can be returned
    64 //      an implementation is not provided by this library; instead it has to be
    65 //      implemented by the user of this library
    66 
    67 typedef pEp_identity *(*retrieve_next_identity_t)(void *management);
    68 
    69 
    70 // examine_identity() - callback for appending to queue
    71 //
    72 //  parameters:
    73 //      ident (in)          identity to examine
    74 //      management (in)     data structure to deliver (implementation defined)
    75 //
    76 //  return value:
    77 //      0 if identity was added successfully to queue or nonzero otherwise
    78 
    79 typedef int (*examine_identity_t)(pEp_identity *ident, void *management);
    80 
    81 
    82 // register_examine_function() - register examine_identity() callback
    83 //
    84 //  parameters:
    85 //      session (in)            session to use
    86 //      examine_identity (in)   examine_identity() function to register
    87 //      management (in)     data structure to deliver (implementation defined)
    88 
    89 DYNAMIC_API PEP_STATUS register_examine_function(
    90         PEP_SESSION session, 
    91         examine_identity_t examine_identity,
    92         void *management
    93     );
    94 
    95 
    96 // do_keymanagement() - function to be run on an extra thread
    97 //
    98 //  parameters:
    99 //      retrieve_next_identity  pointer to retrieve_next_identity() callback
   100 //                              which returns at least a valid address field in
   101 //                              the identity struct
   102 //      management              management data to give to keymanagement
   103 //                              (implementation defined)
   104 //
   105 //  return value:
   106 //      PEP_STATUS_OK if thread has to terminate successfully or any other
   107 //      value on failure
   108 //
   109 //  caveat:
   110 //      to ensure proper working of this library, a thread has to be started
   111 //      with this function immediately after initialization
   112 //      do_keymanagement() calls retrieve_next_identity(management)
   113 
   114 DYNAMIC_API PEP_STATUS do_keymanagement(
   115         retrieve_next_identity_t retrieve_next_identity,
   116         void *management
   117     );
   118 
   119 
   120 // key_mistrusted() - mark key as being compromized
   121 //
   122 //  parameters:
   123 //      session (in)        session to use
   124 //      ident (in)          person and key which was compromized
   125 
   126 DYNAMIC_API PEP_STATUS key_mistrusted(
   127         PEP_SESSION session,
   128         pEp_identity *ident
   129     );
   130 
   131 
   132 // trust_personal_key() - mark a key as trusted with a person
   133 //
   134 //  parameters:
   135 //      session (in)        session to use
   136 //      ident (in)          person and key to trust in
   137 //
   138 //  caveat:
   139 //      the fields user_id, address and fpr must be supplied
   140 
   141 DYNAMIC_API PEP_STATUS trust_personal_key(
   142         PEP_SESSION session,
   143         pEp_identity *ident
   144     );
   145 
   146 
   147 // key_reset_trust() - undo trust_personal_key and key_mistrusted() for keys
   148 //                     we don't own
   149 //
   150 //  parameters:
   151 //      session (in)        session to use
   152 //      ident (in)          person and key which was compromized
   153 
   154 DYNAMIC_API PEP_STATUS key_reset_trust(
   155         PEP_SESSION session,
   156         pEp_identity *ident
   157     );
   158 
   159 
   160 // own_key_is_listed() - returns true id key is listed as own key
   161 //
   162 //  parameters:
   163 //      session (in)        session to use
   164 //      fpr (in)            fingerprint of key to test
   165 //      bool (out)          flags if key is own
   166 
   167 DYNAMIC_API PEP_STATUS own_key_is_listed(
   168         PEP_SESSION session,
   169         const char *fpr,
   170         bool *listed
   171     );
   172 
   173 
   174 // own_identities_retrieve() - retrieve all own identities
   175 //
   176 //  parameters:
   177 //      session (in)            session to use
   178 //      own_identities (out)    list of own identities
   179 //
   180 //  caveat:
   181 //      the ownership of the copy of own_identities goes to the caller
   182 
   183 DYNAMIC_API PEP_STATUS own_identities_retrieve(
   184         PEP_SESSION session,
   185         identity_list **own_identities
   186     );
   187 
   188 PEP_STATUS contains_priv_key(PEP_SESSION session, const char *fpr,
   189                              bool *has_private);
   190 
   191 // own_keys_retrieve() - retrieve all flagged keypair fingerprints 
   192 //
   193 //  parameters:
   194 //      session (in)            session to use
   195 //      keylist (out)           list of fingerprints
   196 //
   197 //  caveat:
   198 //      the ownership of the list goes to the caller
   199 DYNAMIC_API PEP_STATUS own_keys_retrieve(
   200         PEP_SESSION session,
   201         stringlist_t **keylist
   202       );
   203 
   204 #ifdef __cplusplus
   205 }
   206 #endif
   207