ENGINE-332: documentation fixes ENGINE-332
authorKrista Bennett <krista@pep-project.org>
Thu, 25 Jan 2018 02:35:59 +0100
branchENGINE-332
changeset 2447b817f153633c
parent 2446 75d5cac2761a
child 2448 b51c2cbb5bf8
child 2449 b5acdc14167e
ENGINE-332: documentation fixes
src/keymanagement.h
test/trust_manipulation_test.cc
     1.1 --- a/src/keymanagement.h	Wed Jan 24 18:29:58 2018 +0100
     1.2 +++ b/src/keymanagement.h	Thu Jan 25 02:35:59 2018 +0100
     1.3 @@ -189,6 +189,15 @@
     1.4  //  parameters:
     1.5  //      session (in)        session to use
     1.6  //      ident (in)          person and key which was compromised
     1.7 +//  caveat:
     1.8 +//      ident is INPUT ONLY. If you want updated trust on the identity, you'll have
     1.9 +//      to call update_identity or myself respectively after this.
    1.10 +//      N.B. If you are calling this on a key that is the identity or user default,
    1.11 +//      it will be removed as the default key for ANY identity and user for which
    1.12 +//      it is the default. Please keep in mind that the undo in undo_last_mistrust
    1.13 +//      will only undo the current identity's / it's user's default, not any
    1.14 +//      other identities which may be impacted (this will not affect most use
    1.15 +//      cases)
    1.16  
    1.17  DYNAMIC_API PEP_STATUS key_mistrusted(
    1.18          PEP_SESSION session,
    1.19 @@ -214,7 +223,7 @@
    1.20  DYNAMIC_API PEP_STATUS undo_last_mistrust(PEP_SESSION session);
    1.21  
    1.22  
    1.23 -// trust_personal_key() - mark a key as trusted with a person
    1.24 +// trust_personal_key() - mark a key as trusted for a user
    1.25  //
    1.26  //  parameters:
    1.27  //      session (in)        session to use
    1.28 @@ -222,6 +231,11 @@
    1.29  //
    1.30  //  caveat:
    1.31  //      the fields user_id, address and fpr must be supplied
    1.32 +//      for non-own users, this will 1) set the trust bit on its comm type in the DN,
    1.33 +//      2) set this key as the identity default if the current identity default
    1.34 +//      is not trusted, and 3) set this key as the user default if the current
    1.35 +//      user default is not trusted.
    1.36 +//      For an own user, this is simply a call to myself().
    1.37  
    1.38  DYNAMIC_API PEP_STATUS trust_personal_key(
    1.39          PEP_SESSION session,
    1.40 @@ -234,6 +248,13 @@
    1.41  //  parameters:
    1.42  //      session (in)        session to use
    1.43  //      ident (in)          identity for person and key whose trust status is to be reset
    1.44 +//
    1.45 +//  caveat:
    1.46 +//      ident is INPUT ONLY. If you want updated trust on the identity, you'll have
    1.47 +//      to call update_identity or myself respectively after this.
    1.48 +//      N.B. If you are calling this on a key that is the identity or user default,
    1.49 +//      it will be removed as the default key for the identity and user (but is still
    1.50 +//      available for key election, it is just not the cached default anymore)
    1.51  
    1.52  DYNAMIC_API PEP_STATUS key_reset_trust(
    1.53          PEP_SESSION session,
     2.1 --- a/test/trust_manipulation_test.cc	Wed Jan 24 18:29:58 2018 +0100
     2.2 +++ b/test/trust_manipulation_test.cc	Thu Jan 25 02:35:59 2018 +0100
     2.3 @@ -101,6 +101,7 @@
     2.4      assert(user->comm_type == PEP_ct_key_not_found);
     2.5      cout << "Yup, we trust no keys from " << uniqname << endl;
     2.6      
     2.7 +    cout << "TODO: Add cases where we have multiple user_ids addressing a single key, and multiple identities with that key + mistrust" << endl;
     2.8      cout << "Passed all of our exciting messing with the trust DB. Moving on..." << endl;
     2.9   
    2.10      free(user_id);