src/keymanagement.h
author Volker Birk <vb@pep-project.org>
Fri, 17 May 2019 17:59:06 +0200
branchsync
changeset 3720 9ed76a79d784
parent 3583 3c796707c727
child 4286 471cebdff1c6
child 4322 76806e5aebb2
permissions -rw-r--r--
...
     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), and at least
    18 //                          .address must be set. 
    19 //                          If .username is set, it will be used to set or patch
    20 //                          the username record for this identity.                         
    21 //  return value:
    22 //      PEP_STATUS_OK if identity could be updated,
    23 //      PEP_ILLEGAL_VALUE if called with illegal inputs, including an identity
    24 //                        with .me set or with an own user_id specified in the
    25 //                        *input* (see caveats) 
    26 //      PEP_KEY_UNSUITABLE if a default key was found for this identity, no
    27 //                         other acceptable keys were found; if this is returned,
    28 //                         the reason for rejecting the first default key found
    29 //                         may be found in the comm_type
    30 //      any other value on error
    31 //
    32 //  caveat:
    33 //      at least identity->address must be a non-empty UTF-8 string as input
    34 //      update_identity() never writes flags; use set_identity_flags() for
    35 //      writing
    36 //      this function NEVER reads the incoming fpr, only writes to it.
    37 //      this function will fail if called on an identity which, with its input
    38 //      values, *explicitly* indicates it is an own identity (i.e. .me is set
    39 //      to true on input, or a user_id is given AND it is a known own user_id).
    40 //      however, it can RETURN an own identity if this is not indicated a
    41 //      priori, and in fact will do so with prejudice when not faced with a
    42 //      matching default (i.e. it is forced to search by address only).
    43 //      if the identity is known to be an own identity (or the caller wishes
    44 //      to make it one), call myself() on the identity instead.
    45 //
    46 //      FIXME: is this next point accurate?
    47 //      if this function returns PEP_ct_unknown or PEP_ct_key_expired in
    48 //      identity->comm_type, the caller must insert the identity into the
    49 //      asynchronous management implementation, so retrieve_next_identity()
    50 //      will return this identity later
    51 //      END FIXME
    52 
    53 DYNAMIC_API PEP_STATUS update_identity(
    54         PEP_SESSION session, pEp_identity * identity
    55     );
    56 
    57 // TODO: remove
    58 // initialise_own_identities () - ensures that an own identity is complete
    59 //
    60 //  parameters:
    61 //      session (in)        session to use
    62 //      my_idents (inout)   identities of local user to quick-set
    63 //                          For these, at least .address must be set.
    64 //                          if no .user_id is set, AND the DB doesn't contain
    65 //                          a default user_id, PEP_OWN_USERID will be used and
    66 //                          become the perennial default for the DB.
    67 //
    68 //  return value:
    69 //      PEP_STATUS_OK if identity could be set,
    70 //      any other value on error
    71 //
    72 //  caveat:
    73 //      this function does NOT generate keypairs. It is intended to
    74 //      precede running of the engine on actual messages. It effectively
    75 //      behaves like myself(), but when there would normally be key generation
    76 //      (when there is no valid key, for example),
    77 //      it instead stores an identity without keys.
    78 //
    79 //      N.B. to adapter devs - this function is likely unnecessary, so please
    80 //      do not put work into exposing it yet. Tickets will be filed if need be.
    81 
    82 // DYNAMIC_API PEP_STATUS initialise_own_identities(PEP_SESSION session,
    83 //                                                  identity_list* my_idents);
    84 
    85 // myself() - ensures that an own identity is complete
    86 //
    87 //  parameters:
    88 //      session (in)        session to use
    89 //      identity (inout)    identity of local user
    90 //                          both .address and .user_id must be set.
    91 //                          if .fpr is set, an attempt will be made to make
    92 //                          that the default key for this identity after key
    93 //                          validation
    94 //                          if .fpr is not set, key retrieval is performed
    95 //                          If .username is set, it will be used to set or patch
    96 //                          the username record for this identity.                         
    97 //
    98 //  return value:
    99 //      PEP_STATUS_OK if identity could be completed or was already complete,
   100 //      any other value on error
   101 //  caveat:
   102 //      If an fpr was entered and is not a valid key, the reason for failure
   103 //      is immediately returned in the status and, possibly, identity->comm_type
   104 //      If a default own user_id exists in the database, an alias will 
   105 //      be created for the default for the input user_id. The ENGINE'S default
   106 //      user_id is always returned in the .user_id field
   107 //      myself() NEVER elects keys from the keyring; it will only choose keys
   108 //      which have been set up explicitly via myself(), or which were imported
   109 //      during a first time DB setup from an OpenPGP keyring (compatibility only) 
   110 //      this function generates a keypair on demand; because it's synchronous
   111 //      it can need a decent amount of time to return
   112 //      if you need to do this asynchronous, you need to return an identity
   113 //      with retrieve_next_identity() where pEp_identity.me is true
   114 
   115 DYNAMIC_API PEP_STATUS myself(PEP_SESSION session, pEp_identity * identity);
   116 
   117 PEP_STATUS _myself(PEP_SESSION session, 
   118                    pEp_identity * identity, 
   119                    bool do_keygen, 
   120                    bool ignore_flags,
   121                    bool read_only);
   122 
   123 // retrieve_next_identity() - callback being called by do_keymanagement()
   124 //
   125 //  parameters:
   126 //      management (in)     data structure to deliver (implementation defined)
   127 //
   128 //  return value:
   129 //      identity to check or NULL to terminate do_keymanagement()
   130 //      if given identity must be created with new_identity()
   131 //      the identity struct is going to the ownership of this library
   132 //      it must not be freed by the callee
   133 //
   134 //  caveat:
   135 //      this callback has to block until an identity or NULL can be returned
   136 //      an implementation is not provided by this library; instead it has to be
   137 //      implemented by the user of this library
   138 
   139 typedef pEp_identity *(*retrieve_next_identity_t)(void *management);
   140 
   141 
   142 // examine_identity() - callback for appending to queue
   143 //
   144 //  parameters:
   145 //      ident (in)          identity to examine
   146 //      management (in)     data structure to deliver (implementation defined)
   147 //
   148 //  return value:
   149 //      0 if identity was added successfully to queue or nonzero otherwise
   150 
   151 typedef int (*examine_identity_t)(pEp_identity *ident, void *management);
   152 
   153 
   154 // register_examine_function() - register examine_identity() callback
   155 //
   156 //  parameters:
   157 //      session (in)            session to use
   158 //      examine_identity (in)   examine_identity() function to register
   159 //      management (in)     data structure to deliver (implementation defined)
   160 
   161 DYNAMIC_API PEP_STATUS register_examine_function(
   162         PEP_SESSION session, 
   163         examine_identity_t examine_identity,
   164         void *management
   165     );
   166 
   167 
   168 // do_keymanagement() - function to be run on an extra thread
   169 //
   170 //  parameters:
   171 //      retrieve_next_identity (in) pointer to retrieve_next_identity()
   172 //                                  callback which returns at least a valid
   173 //                                  address field in the identity struct
   174 //
   175 //  return value:
   176 //      PEP_STATUS_OK if thread has to terminate successfully or any other
   177 //      value on failure
   178 //
   179 //  caveat:
   180 //      to ensure proper working of this library, a thread has to be started
   181 //      with this function immediately after initialization
   182 //
   183 //      do_keymanagement() calls retrieve_next_identity(management)
   184 //
   185 //      messageToSend can only be null if no transport is application based
   186 //      if transport system is not used it must not be NULL
   187 
   188 DYNAMIC_API PEP_STATUS do_keymanagement(
   189         retrieve_next_identity_t retrieve_next_identity,
   190         void *management
   191     );
   192 
   193 
   194 // key_mistrusted() - mark key as being compromised
   195 //
   196 //  parameters:
   197 //      session (in)        session to use
   198 //      ident (in)          person and key which was compromised
   199 //  caveat:
   200 //      ident is INPUT ONLY. If you want updated trust on the identity, you'll have
   201 //      to call update_identity or myself respectively after this.
   202 //      N.B. If you are calling this on a key that is the identity or user default,
   203 //      it will be removed as the default key for ANY identity and user for which
   204 //      it is the default. Please keep in mind that the undo in undo_last_mistrust
   205 //      will only undo the current identity's / it's user's default, not any
   206 //      other identities which may be impacted (this will not affect most use
   207 //      cases)
   208 
   209 DYNAMIC_API PEP_STATUS key_mistrusted(
   210         PEP_SESSION session,
   211         pEp_identity *ident
   212     );
   213 
   214 // trust_personal_key() - mark a key as trusted for a user
   215 //
   216 //  parameters:
   217 //      session (in)        session to use
   218 //      ident (in)          person and key to trust in - this must not be an
   219 //                          own_identity in which the .me flag is set or
   220 //                          the user_id is an own user_id.
   221 //
   222 //  caveat:
   223 //      the fields user_id, address and fpr must be supplied
   224 //      own identities will result in a return of PEP_ILLEGAL_VALUE.
   225 //      for non-own users, this will 1) set the trust bit on its comm type in the DB,
   226 //      2) set this key as the identity default if the current identity default
   227 //      is not trusted, and 3) set this key as the user default if the current
   228 //      user default is not trusted.
   229 
   230 DYNAMIC_API PEP_STATUS trust_personal_key(
   231         PEP_SESSION session,
   232         pEp_identity *ident
   233     );
   234 
   235 // trust_own_key() - mark a key as trusted for self, generally
   236 //                   used when we need to trust a public key
   237 //                   associated with outselves for issues like
   238 //                   manual key import
   239 //  parameters:
   240 //      session (in)        session to use
   241 //      ident (in)          own ident containing fpr to trust
   242 //
   243 //  caveat:
   244 //      if this is a public key only, keep in mind that if
   245 //      the private part of the keypair is later added,
   246 //      it will not undergo separate trust evaluation. This
   247 //      is fine - even desired - as long as the semantics
   248 //      of this function are understood as both trusting
   249 //      the key and verifying it as an own key. This will
   250 //      NEVER cause replacement of or setting of a default
   251 //      *alone*. However, if a private key is ever associated
   252 //      with this fpr, please keep in mind that trusting it
   253 //      here makes it an eligible key for selection for    
   254 //      encryption later. So use this function on purpose with
   255 //      an understanding of what you're doing!
   256 //
   257 DYNAMIC_API PEP_STATUS trust_own_key(
   258         PEP_SESSION session,
   259         pEp_identity *ident
   260     );
   261 
   262 
   263 // key_reset_trust() - reset trust bit or explicitly mistrusted status for an identity and
   264 //                     its accompanying key/user_id pair.
   265 //  parameters:
   266 //      session (in)        session to use
   267 //      ident (in)          identity for person and key whose trust status is to be reset
   268 //
   269 //  caveat:
   270 //      ident is INPUT ONLY. If you want updated trust on the identity, you'll have
   271 //      to call update_identity or myself respectively after this.
   272 //      N.B. If you are calling this on a key that is the identity or user default,
   273 //      it will be removed as the default key for the identity and user (but is still
   274 //      available for key election, it is just not the cached default anymore)
   275 
   276 DYNAMIC_API PEP_STATUS key_reset_trust(
   277         PEP_SESSION session,
   278         pEp_identity *ident
   279     );
   280 
   281 // own_key_is_listed() - returns true id key is listed as own key
   282 //
   283 //  parameters:
   284 //      session (in)        session to use
   285 //      fpr (in)            fingerprint of key to test
   286 //      listed (out)        flags if key is own
   287 
   288 DYNAMIC_API PEP_STATUS own_key_is_listed(
   289         PEP_SESSION session,
   290         const char *fpr,
   291         bool *listed
   292     );
   293 
   294 
   295 // _own_identities_retrieve() - retrieve all own identities
   296 //
   297 //  parameters:
   298 //      session (in)            session to use
   299 //      own_identities (out)    list of own identities
   300 //      excluded_flags (int)    flags to exclude from results
   301 //
   302 //  caveat:
   303 //      the ownership of the copy of own_identities goes to the caller
   304 
   305 DYNAMIC_API PEP_STATUS _own_identities_retrieve(
   306         PEP_SESSION session,
   307         identity_list **own_identities,
   308         identity_flags_t excluded_flags
   309     );
   310 
   311 // own_identities_retrieve() - retrieve all own identities
   312 //
   313 //  parameters:
   314 //      session (in)            session to use
   315 //      own_identities (out)    list of own identities
   316 //
   317 //  caveat:
   318 //      the ownership of the copy of own_identities goes to the caller
   319 
   320 DYNAMIC_API PEP_STATUS own_identities_retrieve(
   321         PEP_SESSION session,
   322         identity_list **own_identities
   323     );
   324 
   325 PEP_STATUS contains_priv_key(PEP_SESSION session, const char *fpr,
   326                              bool *has_private);
   327 
   328 // _own_keys_retrieve() - retrieve all flagged keypair fingerprints 
   329 //
   330 //  parameters:
   331 //      session (in)            session to use
   332 //      keylist (out)           list of fingerprints
   333 //      excluded_flags (in)     flags to exclude from results
   334 //      private_only (in)       if true, return only fprs for
   335 //                              which we have the secret part
   336 //  caveat:
   337 //      the ownership of the list goes to the caller
   338 DYNAMIC_API PEP_STATUS _own_keys_retrieve(
   339         PEP_SESSION session,
   340         stringlist_t **keylist,
   341         identity_flags_t excluded_flags,
   342         bool private_only
   343       );
   344 
   345 // own_keys_retrieve() - retrieve all flagged public/private keypair fingerprints 
   346 //
   347 //  parameters:
   348 //      session (in)            session to use
   349 //      keylist (out)           list of fingerprints
   350 //
   351 //  caveat:
   352 //      the ownership of the list goes to the caller
   353 //      this function does not return keys without a private key part
   354 //
   355 DYNAMIC_API PEP_STATUS own_keys_retrieve(
   356         PEP_SESSION session,
   357         stringlist_t **keylist
   358       );
   359 
   360 // set_own_key() - mark a key as own key
   361 //
   362 //  parameters:
   363 //      session (in)            session to use
   364 //      me (inout)              own identity this key is used for
   365 //      fpr (in)                fingerprint of the key to mark as own key
   366 //
   367 //  caveat:
   368 //      the key has to be in the key ring already
   369 //      me->address, me->user_id and me->username must be set to valid data
   370 //      myself() is called by set_own_key() without key generation
   371 //      me->flags are ignored
   372 //      me->address must not be an alias
   373 //      me->fpr will be ignored and replaced by fpr
   374 
   375 DYNAMIC_API PEP_STATUS set_own_key(
   376        PEP_SESSION session,
   377        pEp_identity *me,
   378        const char *fpr
   379     );
   380 
   381 PEP_STATUS get_all_keys_for_user(PEP_SESSION session, 
   382                                  const char* user_id,
   383                                  stringlist_t** keys);
   384 
   385 
   386 //PEP_STATUS _myself(PEP_SESSION session, pEp_identity * identity, bool do_keygen, bool ignore_flags);
   387 
   388 PEP_STATUS add_mistrusted_key(PEP_SESSION session, const char* fpr);
   389 PEP_STATUS delete_mistrusted_key(PEP_SESSION session, const char* fpr);
   390 PEP_STATUS is_mistrusted_key(PEP_SESSION session, const char* fpr, bool* mistrusted);
   391 PEP_STATUS get_user_default_key(PEP_SESSION session, const char* user_id,
   392                                 char** default_key);
   393 
   394 
   395 
   396 
   397 // Only call on retrieval of previously stored identity!
   398 // Also, we presume that if the stored_identity was sent in
   399 // without an fpr, there wasn't one in the trust DB for this
   400 // identity.
   401 PEP_STATUS get_valid_pubkey(PEP_SESSION session,
   402                             pEp_identity* stored_identity,
   403                             bool* is_identity_default,
   404                             bool* is_user_default,
   405                             bool* is_address_default,
   406                             bool check_blacklist);
   407 
   408 #ifdef __cplusplus
   409 }
   410 #endif