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