src/key_reset.h
branchENGINE-398
changeset 2948 3f66f366dc5f
parent 2947 4b525ec0f95c
child 2950 753276eb09ec
     1.1 --- a/src/key_reset.h	Fri Sep 14 20:18:53 2018 +0200
     1.2 +++ b/src/key_reset.h	Mon Sep 17 15:31:48 2018 +0200
     1.3 @@ -15,48 +15,33 @@
     1.4  extern "C" {
     1.5  #endif
     1.6  
     1.7 -// FIXME: Proper docs!
     1.8 -//  Algorithm:
     1.9 -// 
    1.10 -//     Key Reset trigger; either manually or in another protocol, parameter key (optional)
    1.11 -// 
    1.12 -//     if identity given:
    1.13 -// 
    1.14 -//     key reset for one identity
    1.15 -// 
    1.16 -//     else
    1.17 -// 
    1.18 -//     For identity in own identities
    1.19 -// 
    1.20 -//     key reset for one identitiy
    1.21 -// 
    1.22 -//     Key Reset for identity:
    1.23 -// 
    1.24 -//     if own identity:
    1.25 -// 
    1.26 -//     Create revocation
    1.27 -// 
    1.28 -//     add to revocation list
    1.29 -// 
    1.30 -//     mistrust fpr from trust
    1.31 -// 
    1.32 -//     Remove fpr from ALL identities
    1.33 -// 
    1.34 -//     Remove fpr from ALL users
    1.35 -// 
    1.36 -//     generate new key
    1.37 -// 
    1.38 -//     for all active communication partners:
    1.39 -// 
    1.40 -//     active_send revocation
    1.41 -// 
    1.42 -//     else
    1.43 -// 
    1.44 -//     remove fpr from all identities
    1.45 -// 
    1.46 -//     remove fpr from all users
    1.47 -// 
    1.48 -//     delete key from key ring
    1.49 +// key_reset() - reset the database status for a key, removing all trust information
    1.50 +//               and default database connections. For own keys, also revoke the key
    1.51 +//               and communicate the revocation and new key to partners we have sent
    1.52 +//               mail to recently from the specific identity (i.e. address/user_id)
    1.53 +//               that contacted them. We also in this case set up information so that
    1.54 +//               if someone we mail uses the wrong key and wasn't yet contacted,
    1.55 +//               we can send them the reset information from the right address.
    1.56 +//
    1.57 +//               Can be called manually or through another protocol.
    1.58 +//
    1.59 +//  parameters:
    1.60 +//      session (in)            session handle
    1.61 +//      fpr (in)                fingerprint of key to reset. If NULL and ident is NULL,
    1.62 +//                              we reset all keys for the own user. If NULL and ident is
    1.63 +//                              an own identity, we reset the default key for that
    1.64 +//                              identity. If that own identity has no default key, we
    1.65 +//                              reset the user default.
    1.66 +//                              if it is NULL and there is a non-own identity, this is
    1.67 +//                              currently undefined and will return an error. Later, we
    1.68 +//                              may decide on semantics for it (e.g. remove all keys
    1.69 +//                              in the DB for that identity)
    1.70 +//      ident (in)              identity for which the key reset should occur.
    1.71 +//                              if NULL and fpr is non-NULL, we'll reset the key for all
    1.72 +//                              associated identities. If both ident and fpr are NULL, see 
    1.73 +//                              the fpr arg documentation.
    1.74 +//
    1.75 +//
    1.76  DYNAMIC_API PEP_STATUS key_reset(
    1.77          PEP_SESSION session,
    1.78          const char* fpr,