ENGINE-423: documentation ENGINE-423
authorKrista Bennett <krista@pep-project.org>
Mon, 23 Apr 2018 13:57:14 +0200
branchENGINE-423
changeset 262406472aa7727d
parent 2623 009950d133c1
child 2625 d7dd538d402b
ENGINE-423: documentation
src/message_api.h
     1.1 --- a/src/message_api.h	Mon Apr 23 12:43:31 2018 +0200
     1.2 +++ b/src/message_api.h	Mon Apr 23 13:57:14 2018 +0200
     1.3 @@ -243,23 +243,49 @@
     1.4  //
     1.5  //  parameters:
     1.6  //      session (in)        session handle
     1.7 -//      src (in)            message to decrypt
     1.8 +//      src (inout)         message to decrypt
     1.9  //      dst (out)           pointer to new decrypted message or NULL on failure
    1.10  //      keylist (out)       stringlist with keyids
    1.11  //      rating (out)        rating for the message
    1.12 -//      flags (in/out)         flags to signal special decryption features
    1.13 +//      flags (inout)       flags to signal special decryption features
    1.14  //
    1.15  //  return value:
    1.16  //      error status 
    1.17  //      or PEP_DECRYPTED if message decrypted but not verified
    1.18 +//      or PEP_CANNOT_REENCRYPT if message was decrypted (and possibly
    1.19 +//         verified) but a reencryption operation is expected by the caller
    1.20 +//         and failed
    1.21  //      or PEP_STATUS_OK on success
    1.22  //
    1.23 +//  flag values:
    1.24 +//      in:
    1.25 +//          PEP_decrypt_flag_untrusted_server
    1.26 +//              used to signal that decrypt function should engage in behaviour
    1.27 +//              specified for when the server storing the source is untrusted
    1.28 +//      out:
    1.29 +//          PEP_decrypt_flag_own_private_key
    1.30 +//              private key was imported for one of our addresses (NOT trusted
    1.31 +//              or set to be used - handshake/trust is required for that)
    1.32 +//          PEP_decrypt_flag_src_modified
    1.33 +//              indicates that the src object has been modified. At the moment,
    1.34 +//              this is always as a direct result of the behaviour driven
    1.35 +//              by the input flags. This flag is the ONLY value that should be
    1.36 +//              relied upon to see if such changes have taken place.
    1.37 +//          PEP_decrypt_flag_consume
    1.38 +//              used by sync 
    1.39 +//          PEP_decrypt_flag_ignore
    1.40 +//              used by sync 
    1.41 +//
    1.42 +//
    1.43  // caveat:
    1.44 -//      the ownership of src remains with the caller
    1.45 +//      the ownership of src remains with the caller - however, the contents 
    1.46 +//          might be modified (strings freed and allocated anew or set to NULL,
    1.47 +//          etc) intentionally; when this happens, PEP_decrypt_flag_src_modified
    1.48 +//          is set.
    1.49  //      the ownership of dst goes to the caller
    1.50  //      the ownership of keylist goes to the caller
    1.51  //      if src is unencrypted this function returns PEP_UNENCRYPTED and sets
    1.52 -//      dst to NULL
    1.53 +//         dst to NULL
    1.54  DYNAMIC_API PEP_STATUS decrypt_message(
    1.55          PEP_SESSION session,
    1.56          message *src,
    1.57 @@ -279,7 +305,7 @@
    1.58  //      mime_plaintext (out)    decrypted, encoded message
    1.59  //      keylist (out)           stringlist with keyids
    1.60  //      rating (out)            rating for the message
    1.61 -//      flags (out)             flags to signal special decryption features
    1.62 +//      flags (inout)           flags to signal special decryption features (see below)
    1.63  //      modified_src (out)      modified source string, if decrypt had reason to change it
    1.64  //
    1.65  //  return value:
    1.66 @@ -293,6 +319,24 @@
    1.67  //                              error
    1.68  //      PEP_OUT_OF_MEMORY       if not enough memory could be allocated
    1.69  //
    1.70 +//  flag values:
    1.71 +//      in:
    1.72 +//          PEP_decrypt_flag_untrusted_server
    1.73 +//              used to signal that decrypt function should engage in behaviour
    1.74 +//              specified for when the server storing the source is untrusted.
    1.75 +//      out:
    1.76 +//          PEP_decrypt_flag_own_private_key
    1.77 +//              private key was imported for one of our addresses (NOT trusted
    1.78 +//              or set to be used - handshake/trust is required for that)
    1.79 +//          PEP_decrypt_flag_src_modified
    1.80 +//              indicates that the modified_src field should contain a modified
    1.81 +//              version of the source, at the moment always as a result of the
    1.82 +//              input flags. 
    1.83 +//          PEP_decrypt_flag_consume
    1.84 +//              used by sync 
    1.85 +//          PEP_decrypt_flag_ignore
    1.86 +//              used by sync 
    1.87 +// 
    1.88  //  caveat:
    1.89  //      the decrypted, encoded mime text will go to the ownership of the caller; mimetext
    1.90  //      will remain in the ownership of the caller