ENGINE-328 - doc bugs fixed
authorKrista Bennett <krista@pep-project.org>
Fri, 19 Jan 2018 11:01:39 +0100
changeset 24157410f7666976
parent 2414 71de06af5121
child 2416 448d74f8eb90
child 2418 05678e77bc6a
ENGINE-328 - doc bugs fixed
src/blacklist.h
src/keymanagement.h
     1.1 --- a/src/blacklist.h	Thu Jan 18 16:45:01 2018 +0100
     1.2 +++ b/src/blacklist.h	Fri Jan 19 11:01:39 2018 +0100
     1.3 @@ -14,6 +14,13 @@
     1.4  //  parameters:
     1.5  //      session (in)        session to use
     1.6  //      fpr (in)            fingerprint of key to blacklist
     1.7 +//
     1.8 +//  caveat:
     1.9 +//      there is no point in blacklisting an own key; for any own
    1.10 +//      identity, this will be ignored. The correct function to use
    1.11 +//      for own keys in this event is "key_reset_trust".
    1.12 +//      Also, this is only effective for OpenPGP-level trust. If
    1.13 +//      this key is for a pEp user, the blacklist is ignored.
    1.14  
    1.15  DYNAMIC_API PEP_STATUS blacklist_add(PEP_SESSION session, const char *fpr);
    1.16  
     2.1 --- a/src/keymanagement.h	Thu Jan 18 16:45:01 2018 +0100
     2.2 +++ b/src/keymanagement.h	Fri Jan 19 11:01:39 2018 +0100
     2.3 @@ -14,21 +14,41 @@
     2.4  //  parameters:
     2.5  //      session (in)        session to use
     2.6  //      identity (inout)    identity information of communication partner
     2.7 -//                          (identity->fpr is OUT ONLY)
     2.8 +//                          (identity->fpr is OUT ONLY), and at least
     2.9 +//                          .address must be set. 
    2.10 +//                          If .username is set, it will be used to set or patch
    2.11 +//                          the username record for this identity.                         
    2.12  //  return value:
    2.13  //      PEP_STATUS_OK if identity could be updated,
    2.14 -//      PEP_GET_KEY_FAILED for own identity that must be completed (myself())
    2.15 +//      PEP_ILLEGAL_VALUE if called with illegal inputs, including an identity
    2.16 +//                        with .me set or with an own user_id specified in the
    2.17 +//                        *input* (see caveats) 
    2.18 +//      PEP_KEY_UNSUITABLE if a default key was found for this identity, no
    2.19 +//                         other acceptable keys were found; if this is returned,
    2.20 +//                         the reason for rejecting the first default key found
    2.21 +//                         may be found in the comm_type
    2.22  //      any other value on error
    2.23  //
    2.24  //  caveat:
    2.25 +//      at least identity->address must be a non-empty UTF-8 string as input
    2.26 +//      update_identity() never writes flags; use set_identity_flags() for
    2.27 +//      writing
    2.28 +//      this function NEVER reads the incoming fpr, only writes to it.
    2.29 +//      this function will fail if called on an identity which, with its input
    2.30 +//      values, *explicitly* indicates it is an own identity (i.e. .me is set
    2.31 +//      to true on input, or a user_id is given AND it is a known own user_id).
    2.32 +//      however, it can RETURN an own identity if this is not indicated a
    2.33 +//      priori, and in fact will do so with prejudice when not faced with a
    2.34 +//      matching default (i.e. it is forced to search by address only).
    2.35 +//      if the identity is known to be an own identity (or the caller wishes
    2.36 +//      to make it one), call myself() on the identity instead.
    2.37 +//
    2.38 +//      FIXME: is this next point accurate?
    2.39  //      if this function returns PEP_ct_unknown or PEP_ct_key_expired in
    2.40  //      identity->comm_type, the caller must insert the identity into the
    2.41  //      asynchronous management implementation, so retrieve_next_identity()
    2.42  //      will return this identity later
    2.43 -//      at least identity->address must be a non-empty UTF-8 string as input
    2.44 -//      update_identity() never writes flags; use set_identity_flags() for
    2.45 -//      writing
    2.46 -//      this function NEVER reads the incoming fpr, only writes to it.
    2.47 +//      END FIXME
    2.48  
    2.49  DYNAMIC_API PEP_STATUS update_identity(
    2.50          PEP_SESSION session, pEp_identity * identity
    2.51 @@ -55,6 +75,9 @@
    2.52  //      (when there is no valid key, for example),
    2.53  //      it instead stores an identity without keys.
    2.54  //
    2.55 +//      N.B. to adapter devs - this function is likely unnecessary, so please
    2.56 +//      do not put work into exposing it yet. Tickets will be filed if need be.
    2.57 +
    2.58  DYNAMIC_API PEP_STATUS initialise_own_identities(PEP_SESSION session,
    2.59                                                   identity_list* my_idents);
    2.60  
    2.61 @@ -63,17 +86,26 @@
    2.62  //  parameters:
    2.63  //      session (in)        session to use
    2.64  //      identity (inout)    identity of local user
    2.65 -//                          at least .address must be set.
    2.66 -//                          if no .user_id is set, AND the DB doesn't contain
    2.67 -//                          a user_id, PEP_OWN_USERID will be used.
    2.68 -//                          if no .username is set and none is in the DB,
    2.69 -//                          username will be set to "Anonymous"
    2.70 +//                          both .address and .user_id must be set.
    2.71 +//                          if .fpr is set, an attempt will be made to make
    2.72 +//                          that the default key for this identity after key
    2.73 +//                          validation
    2.74 +//                          if .fpr is not set, key retrieval is performed
    2.75 +//                          If .username is set, it will be used to set or patch
    2.76 +//                          the username record for this identity.                         
    2.77  //
    2.78  //  return value:
    2.79  //      PEP_STATUS_OK if identity could be completed or was already complete,
    2.80  //      any other value on error
    2.81 -//
    2.82  //  caveat:
    2.83 +//      If an fpr was entered and is not a valid key, the reason for failure
    2.84 +//      is immediately returned in the status and, possibly, identity->comm_type
    2.85 +//      If a default own user_id exists in the database, an alias will 
    2.86 +//      be created for the default for the input user_id. The ENGINE'S default
    2.87 +//      user_id is always returned in the .user_id field
    2.88 +//      myself() NEVER elects keys from the keyring; it will only choose keys
    2.89 +//      which have been set up explicitly via myself(), or which were imported
    2.90 +//      during a first time DB setup from an OpenPGP keyring (compatibility only) 
    2.91  //      this function generates a keypair on demand; because it's synchronous
    2.92  //      it can need a decent amount of time to return
    2.93  //      if you need to do this asynchronous, you need to return an identity