src/keymanagement.h
author Krista Grothoff <krista@pep-project.org>
Sat, 24 Sep 2016 18:09:18 +0200
branchENGINE-27
changeset 1185 4b01328f3cf2
parent 932 d35b292fe141
child 955 060272dfaaeb
child 1220 f992b45d7e08
permissions -rw-r--r--
ENGINE-27: update_identity no longer pays attention to the input identity's fpr, but pulls one from elect_pubkey.
     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 //
    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 
    24 DYNAMIC_API PEP_STATUS update_identity(
    25         PEP_SESSION session, pEp_identity * identity
    26     );
    27 
    28 
    29 // myself() - ensures that the own identity is being complete
    30 //
    31 //  parameters:
    32 //      session (in)        session to use
    33 //      identity (inout)    identity of local user
    34 //                          at least .address, .username, .user_id must be set
    35 //
    36 //  return value:
    37 //      PEP_STATUS_OK if identity could be completed or was already complete,
    38 //      any other value on error
    39 //
    40 //  caveat:
    41 //      this function generates a keypair on demand; because it's synchronous
    42 //      it can need a decent amount of time to return
    43 //      if you need to do this asynchronous, you need to return an identity
    44 //      with retrieve_next_identity() where pEp_identity.me is true
    45 //      myself() never writes flags; use set_identity_flags() for writing
    46 
    47 DYNAMIC_API PEP_STATUS myself(PEP_SESSION session, pEp_identity * identity);
    48 
    49 
    50 // retrieve_next_identity() - callback being called by do_keymanagement()
    51 //
    52 //  parameters:
    53 //      management (in)     data structure to deliver (implementation defined)
    54 //
    55 //  return value:
    56 //      identity to check or NULL to terminate do_keymanagement()
    57 //      if given identity must be created with new_identity()
    58 //      the identity struct is going to the ownership of this library
    59 //      it must not be freed by the callee
    60 //
    61 //  caveat:
    62 //      this callback has to block until an identity or NULL can be returned
    63 //      an implementation is not provided by this library; instead it has to be
    64 //      implemented by the user of this library
    65 
    66 typedef pEp_identity *(*retrieve_next_identity_t)(void *management);
    67 
    68 
    69 // examine_identity() - callback for appending to queue
    70 //
    71 //  parameters:
    72 //      ident (in)          identity to examine
    73 //      management (in)     data structure to deliver (implementation defined)
    74 //
    75 //  return value:
    76 //      0 if identity was added successfully to queue or nonzero otherwise
    77 
    78 typedef int (*examine_identity_t)(pEp_identity *ident, void *management);
    79 
    80 
    81 // register_examine_function() - register examine_identity() callback
    82 //
    83 //  parameters:
    84 //      session (in)            session to use
    85 //      examine_identity (in)   examine_identity() function to register
    86 //      management (in)     data structure to deliver (implementation defined)
    87 
    88 DYNAMIC_API PEP_STATUS register_examine_function(
    89         PEP_SESSION session, 
    90         examine_identity_t examine_identity,
    91         void *management
    92     );
    93 
    94 
    95 // do_keymanagement() - function to be run on an extra thread
    96 //
    97 //  parameters:
    98 //      retrieve_next_identity  pointer to retrieve_next_identity() callback
    99 //                              which returns at least a valid address field in
   100 //                              the identity struct
   101 //      management              management data to give to keymanagement
   102 //                              (implementation defined)
   103 //
   104 //  return value:
   105 //      PEP_STATUS_OK if thread has to terminate successfully or any other
   106 //      value on failure
   107 //
   108 //  caveat:
   109 //      to ensure proper working of this library, a thread has to be started
   110 //      with this function immediately after initialization
   111 //      do_keymanagement() calls retrieve_next_identity(management)
   112 
   113 DYNAMIC_API PEP_STATUS do_keymanagement(
   114         retrieve_next_identity_t retrieve_next_identity,
   115         void *management
   116     );
   117 
   118 
   119 // key_compromized() - mark key as being compromized
   120 //
   121 //  parameters:
   122 //      session (in)        session to use
   123 //      ident (in)          person and key which was compromized
   124 
   125 DYNAMIC_API PEP_STATUS key_compromized(
   126         PEP_SESSION session,
   127         pEp_identity *ident
   128     );
   129 
   130 
   131 // trust_personal_key() - mark a key as trusted with a person
   132 //
   133 //  parameters:
   134 //      session (in)        session to use
   135 //      ident (in)          person and key to trust in
   136 //
   137 //  caveat:
   138 //      the fields user_id, address and fpr must be supplied
   139 
   140 DYNAMIC_API PEP_STATUS trust_personal_key(
   141         PEP_SESSION session,
   142         pEp_identity *ident
   143     );
   144 
   145 
   146 // key_reset_trust() - undo trust_personal_key and key_compromized() for keys
   147 //                     we don't own
   148 //
   149 //  parameters:
   150 //      session (in)        session to use
   151 //      ident (in)          person and key which was compromized
   152 
   153 DYNAMIC_API PEP_STATUS key_reset_trust(
   154         PEP_SESSION session,
   155         pEp_identity *ident
   156     );
   157 
   158 
   159 // own_key_is_listed() - returns true id key is listed as own key
   160 //
   161 //  parameters:
   162 //      session (in)        session to use
   163 //      fpr (in)            fingerprint of key to test
   164 //      bool (out)          flags if key is own
   165 
   166 DYNAMIC_API PEP_STATUS own_key_is_listed(
   167         PEP_SESSION session,
   168         const char *fpr,
   169         bool *listed
   170     );
   171 
   172 
   173 // own_key_retrieve() - retrieve all own keys fingerprints
   174 //
   175 //  parameters:
   176 //      session (in)        session to use
   177 //      own_key (out)     copy of own_key
   178 //
   179 //  caveat:
   180 //      the ownership of the copy of own_key goes to the caller
   181 
   182 DYNAMIC_API PEP_STATUS own_key_retrieve(
   183         PEP_SESSION session,
   184         stringlist_t **own_key
   185     );
   186 
   187 #ifdef __cplusplus
   188 }
   189 #endif
   190