// This file is under GNU General Public License 3.0

 // see LICENSE.txt

 #pragma once

 #include "pEpEngine.h"

 #include "keymanagement.h"

 #include "message.h"

 #include "cryptotech.h"

 #ifdef __cplusplus

 extern "C" {

 #endif

 bool import_attached_keys(

         PEP_SESSION session, 

         message *msg,

         identity_list **private_idents

     );

 void attach_own_key(PEP_SESSION session, message *msg);

 PEP_cryptotech determine_encryption_format(message *msg);

 void add_opt_field(message *msg, const char *name, const char *value);

 typedef enum _PEP_encrypt_flags {

     // "default" means whatever the default behaviour for the function is.

     PEP_encrypt_flag_default = 0x0,

     PEP_encrypt_flag_force_encryption = 0x1,

     // This flag is for special use cases and should not be used

     // by normal pEp clients!

     PEP_encrypt_flag_force_unsigned = 0x2,

     PEP_encrypt_flag_force_no_attached_key = 0x4,

     // This is used for outer messages (used to wrap the real message)

     // This is only used internally and (eventually) by transport functions

     PEP_encrypt_flag_inner_message = 0x8,

     // This is mainly used by pEp clients to send private keys to 

     // their own PGP-only device

     PEP_encrypt_flag_force_version_1 = 0x10,

     PEP_encrypt_flag_key_reset_only = 0x20

 } PEP_encrypt_flags; 

 typedef unsigned int PEP_encrypt_flags_t;

 typedef enum _message_wrap_type {

     PEP_message_default,    // typical inner/outer message 2.0

     PEP_message_transport,  // e.g. for onion layers

     PEP_message_key_reset   // for wrapped key reset information

 } message_wrap_type;

 // encrypt_message() - encrypt message in memory

 //

 //  parameters:

 //      session (in)        session handle

 //      src (inout)         message to encrypt - usually in-only, but can be 

 //                          in-out for unencrypted messages; in that case, 

 //                          we may attach the key and decorate the message

 //      extra (in)          extra keys for encryption

 //      dst (out)           pointer to new encrypted message or NULL if no

 //                          encryption could take place

 //      enc_format (in)     encrypted format

 //      flags (in)          flags to set special encryption features

 //

 //  return value:

 //      PEP_STATUS_OK                   on success

 //      PEP_KEY_HAS_AMBIG_NAME          at least one of the receipient keys has

 //                                      an ambiguous name

 //      PEP_UNENCRYPTED                 on demand or no recipients with usable

 //                                      key, is left unencrypted, and key is

 //                                      attached to it

 //

 //  caveat:

 //      the ownership of src remains with the caller

 //      the ownership of dst goes to the caller

 DYNAMIC_API PEP_STATUS encrypt_message(

         PEP_SESSION session,

         message *src,

         stringlist_t *extra,

         message **dst,

         PEP_enc_format enc_format,

         PEP_encrypt_flags_t flags

     );

 // encrypt_message_and_add_priv_key() - encrypt message in memory, adding an encrypted private

 //                                      key (encrypted separately and sent within the inner message)

 //

 //  parameters:

 //      session (in)        session handle

 //      src (in)            message to encrypt

 //      dst (out)           pointer to new encrypted message or NULL if no

 //                          encryption could take place

 //      to_fpr              fingerprint of the recipient key to which the private key

 //                          should be encrypted

 //      enc_format (in)     encrypted format

 //      flags (in)          flags to set special encryption features

 //

 //  return value:

 //      PEP_STATUS_OK                   on success

 //      PEP_KEY_HAS_AMBIG_NAME          at least one of the receipient keys has

 //                                      an ambiguous name

 //      PEP_UNENCRYPTED                 on demand or no recipients with usable

 //                                      key, is left unencrypted, and key is

 //                                      attached to it

 //

 //  caveat:

 //      the ownershop of src remains with the caller

 //      the ownership of dst goes to the caller

 DYNAMIC_API PEP_STATUS encrypt_message_and_add_priv_key(

         PEP_SESSION session,

         message *src,

         message **dst,

         const char* to_fpr,

         PEP_enc_format enc_format,

         PEP_encrypt_flags_t flags

     );

 // encrypt_message_for_self() - encrypt message in memory for user's identity only,

 //                              ignoring recipients and other identities from

 //                              the message

 //  parameters:

 //      session (in)        session handle

 //      target_id (in)      self identity this message should be encrypted for

 //      src (in)            message to encrypt

 //      extra (in)          extra keys for encryption

 //      dst (out)           pointer to new encrypted message or NULL on failure

 //      enc_format (in)     encrypted format

 //      flags (in)          flags to set special encryption features

 //

 //  return value:       (FIXME: This may not be correct or complete)

 //      PEP_STATUS_OK            on success

 //      PEP_KEY_NOT_FOUND        at least one of the receipient keys

 //                               could not be found

 //      PEP_KEY_HAS_AMBIG_NAME   at least one of the receipient keys has

 //                               an ambiguous name

 //      PEP_GET_KEY_FAILED       cannot retrieve key

 //

 //  caveat:

 //      the ownership of src remains with the caller

 //      the ownership of target_id remains w/ caller            

 //      the ownership of dst goes to the caller

 //      message is NOT encrypted for identities other than the target_id (and then,

 //      only if the target_id refers to self!)

 DYNAMIC_API PEP_STATUS encrypt_message_for_self(

         PEP_SESSION session,

         pEp_identity* target_id,

         message *src,

         stringlist_t* extra,

         message **dst,

         PEP_enc_format enc_format,

         PEP_encrypt_flags_t flags

     );

 typedef enum _PEP_rating {

     PEP_rating_undefined = 0,

     PEP_rating_cannot_decrypt,

     PEP_rating_have_no_key,

     PEP_rating_unencrypted,

     PEP_rating_unencrypted_for_some, // don't use this any more

     PEP_rating_unreliable,

     PEP_rating_reliable,

     PEP_rating_trusted,

     PEP_rating_trusted_and_anonymized,

     PEP_rating_fully_anonymous,   

     PEP_rating_mistrust = -1,

     PEP_rating_b0rken = -2,

     PEP_rating_under_attack = -3

 } PEP_rating;

 typedef enum _PEP_color {

     PEP_color_no_color = 0,

     PEP_color_yellow,

     PEP_color_green,

     PEP_color_red = -1,

 } PEP_color;

 // color_from_rating - calculate color from rating

 //

 //  parameters:

 //      rating (in)         rating

 //

 //  return value:           color representing that rating

 DYNAMIC_API PEP_color color_from_rating(PEP_rating rating);

 typedef enum _PEP_decrypt_flags {

     PEP_decrypt_flag_own_private_key = 0x1,

     PEP_decrypt_flag_consume = 0x2,

     PEP_decrypt_flag_ignore = 0x4,

     PEP_decrypt_flag_src_modified = 0x8,

     // input flags    

     PEP_decrypt_flag_untrusted_server = 0x100,

     PEP_decrypt_flag_dont_trigger_sync = 0x200,

 } PEP_decrypt_flags; 

 typedef unsigned int PEP_decrypt_flags_t;

 // decrypt_message() - decrypt message in memory

 //

 //  parameters:

 //      session (in)        session handle

 //      src (inout)         message to decrypt

 //      dst (out)           pointer to new decrypted message or NULL on failure

 //      keylist (inout)     in: stringlist with additional keyids for reencryption if needed

 //                              (will be freed and replaced with output keylist) 

 //                          out: stringlist with keyids used for signing and encryption. first

 //                               first key is signer, additional keys are the ones it was encrypted

 //                               to. Only signer and whichever of the user's keys was used are 

 //                               reliable

 //      rating (out)        rating for the message

 //      flags (inout)       flags to signal special decryption features

 //

 //  return value:

 //      error status 

 //      or PEP_DECRYPTED if message decrypted but not verified

 //      or PEP_CANNOT_REENCRYPT if message was decrypted (and possibly

 //         verified) but a reencryption operation is expected by the caller

 //         and failed

 //      or PEP_STATUS_OK on success

 //

 //  flag values:

 //      in:

 //          PEP_decrypt_flag_untrusted_server

 //              used to signal that decrypt function should engage in behaviour

 //              specified for when the server storing the source is untrusted

 //      out:

 //          PEP_decrypt_flag_own_private_key

 //              private key was imported for one of our addresses (NOT trusted

 //              or set to be used - handshake/trust is required for that)

 //          PEP_decrypt_flag_src_modified

 //              indicates that the src object has been modified. At the moment,

 //              this is always as a direct result of the behaviour driven

 //              by the input flags. This flag is the ONLY value that should be

 //              relied upon to see if such changes have taken place.

 //          PEP_decrypt_flag_consume

 //              used by sync 

 //          PEP_decrypt_flag_ignore

 //              used by sync 

 //

 //

 // caveat:

 //      the ownership of src remains with the caller - however, the contents 

 //          might be modified (strings freed and allocated anew or set to NULL,

 //          etc) intentionally; when this happens, PEP_decrypt_flag_src_modified

 //          is set.

 //      the ownership of dst goes to the caller

 //      the ownership of keylist goes to the caller

 //      if src is unencrypted this function returns PEP_UNENCRYPTED and sets

 //         dst to NULL

 DYNAMIC_API PEP_STATUS decrypt_message(

         PEP_SESSION session,

         message *src,

         message **dst,

         stringlist_t **keylist,

         PEP_rating *rating,

         PEP_decrypt_flags_t *flags

 );

 // own_message_private_key_details() - details on own key in own message

 //

 //  parameters:

 //      session (in)        session handle

 //      msg (in)            message to decrypt

 //      ident (out)         identity containing uid, address and fpr of key

 //

 //  note:

 //      In order to obtain details about key to be possibly imported

 //      as a replacement of key currently used as own identity, 

 //      application passes message that have been previously flagged by 

 //      decrypt_message() as own message containing own key to this function

 //

 //  return value:

 //      error status or PEP_STATUS_OK on success

 //

 //  caveat:

 //      the ownership of msg remains with the caller

 //      the ownership of ident goes to the caller

 //      msg MUST be encrypted so that this function can check own signature

 DYNAMIC_API PEP_STATUS own_message_private_key_details(

         PEP_SESSION session,

         message *msg,

         pEp_identity **ident 

 );

 // outgoing_message_rating() - get rating for an outgoing message

 //

 //  parameters:

 //      session (in)        session handle

 //      msg (in)            message to get the rating for

 //      rating (out)        rating for the message

 //

 //  return value:

 //      error status or PEP_STATUS_OK on success

 //

 //  caveat:

 //      msg->from must point to a valid pEp_identity

 //      msg->dir must be PEP_dir_outgoing

 //      the ownership of msg remains with the caller

 DYNAMIC_API PEP_STATUS outgoing_message_rating(

         PEP_SESSION session,

         message *msg,

         PEP_rating *rating

     );

 // outgoing_message_rating_preview() - get rating preview

 //

 //  parameters:

 //      session (in)        session handle

 //      msg (in)            message to get the rating for

 //      rating (out)        rating preview for the message

 //

 //  return value:

 //      error status or PEP_STATUS_OK on success

 //

 //  caveat:

 //      msg->from must point to a valid pEp_identity

 //      msg->dir must be PEP_dir_outgoing

 //      the ownership of msg remains with the caller

 DYNAMIC_API PEP_STATUS outgoing_message_rating_preview(

         PEP_SESSION session,

         message *msg,

         PEP_rating *rating

     );

 // identity_rating() - get rating for a single identity

 //

 //  parameters:

 //      session (in)        session handle

 //      ident (in)          identity to get the rating for

 //      rating (out)        rating for the identity

 //

 //  return value:

 //      error status or PEP_STATUS_OK on success

 //

 //  caveat:

 //      the ownership of ident remains with the caller

 DYNAMIC_API PEP_STATUS identity_rating(

         PEP_SESSION session,

         pEp_identity *ident,

         PEP_rating *rating

     );

 // get_binary_path() - retrieve path of cryptotech binary if available

 //

 //  parameters:

 //      tech (in)           cryptotech to get the binary for

 //      path (out)          path to cryptotech binary or NULL if not available

 //                          **path is owned by the library, do not change it!

 DYNAMIC_API PEP_STATUS get_binary_path(PEP_cryptotech tech, const char **path);

 // get_trustwords() - get full trustwords string for a *pair* of identities

 //

 //    parameters:

 //        session (in)        session handle

 //        id1 (in)            identity of first party in communication - fpr can't be NULL  

 //        id2 (in)            identity of second party in communication - fpr can't be NULL

 //        lang (in)           C string with ISO 639-1 language code

 //        words (out)         pointer to C string with all trustwords UTF-8 encoded,

 //                            separated by a blank each

 //                            NULL if language is not supported or trustword

 //                            wordlist is damaged or unavailable

 //        wsize (out)         length of full trustwords string

 //        full (in)           if true, generate ALL trustwords for these identities.

 //                            else, generate a fixed-size subset. (TODO: fixed-minimum-entropy

 //                            subset in next version)

 //

 //    return value:

 //        PEP_STATUS_OK            trustwords retrieved

 //        PEP_OUT_OF_MEMORY        out of memory

 //        PEP_TRUSTWORD_NOT_FOUND  at least one trustword not found

 //

 //    caveat:

 //        the word pointer goes to the ownership of the caller

 //        the caller is responsible to free() it (on Windoze use pEp_free())

 //

 DYNAMIC_API PEP_STATUS get_trustwords(

     PEP_SESSION session, const pEp_identity* id1, const pEp_identity* id2,

     const char* lang, char **words, size_t *wsize, bool full

 );

 // get_message_trustwords() - get full trustwords string for message sender and reciever identities 

 //

 //    parameters:

 //        session (in)        session handle

 //        msg (in)            message to get sender identity from

 //        keylist (in)        NULL if message to be decrypted,

 //                            keylist returned by decrypt_message() otherwise

 //        received_by (in)    identity for account receiving message can't be NULL

 //        lang (in)           C string with ISO 639-1 language code

 //        words (out)         pointer to C string with all trustwords UTF-8 encoded,

 //                            separated by a blank each

 //                            NULL if language is not supported or trustword

 //                            wordlist is damaged or unavailable

 //        full (in)           if true, generate ALL trustwords for these identities.

 //                            else, generate a fixed-size subset. (TODO: fixed-minimum-entropy

 //                            subset in next version)

 //

 //    return value:

 //        PEP_STATUS_OK            trustwords retrieved

 //        PEP_OUT_OF_MEMORY        out of memory

 //        PEP_TRUSTWORD_NOT_FOUND  at least one trustword not found

 //        error status of decrypt_message() if decryption fails.

 //

 //    caveat:

 //        the word pointer goes to the ownership of the caller

 //        the caller is responsible to free() it (on Windoze use pEp_free())

 //

 DYNAMIC_API PEP_STATUS get_message_trustwords(

     PEP_SESSION session, 

     message *msg,

     stringlist_t *keylist,

     pEp_identity* received_by,

     const char* lang, char **words, bool full

 );

 // re_evaluate_message_rating() - re-evaluate already decrypted message rating

 //

 //  parameters:

 //      session (in)            session handle

 //      msg (in)                message to get the rating for

 //      x_keylist (in)          decrypted message recipients keys fpr

 //      x_enc_status (in)       original rating for the decrypted message

 //      rating (out)            rating for the message

 //

 //  return value:

 //      PEP_ILLEGAL_VALUE       if decrypted message doesn't contain 

 //                              X-EncStatus optional field and x_enc_status is 

 //                              pEp_rating_udefined

 //                              or if decrypted message doesn't contain 

 //                              X-Keylist optional field and x_keylist is NULL

 //      PEP_OUT_OF_MEMORY       if not enough memory could be allocated

 //

 //  caveat:

 //      msg->from must point to a valid pEp_identity

 //      the ownership of msg remains with the caller

 //	    the ownership of x_keylist remains with to the caller

 DYNAMIC_API PEP_STATUS re_evaluate_message_rating(

     PEP_SESSION session,

     message *msg,

     stringlist_t *x_keylist,

     PEP_rating x_enc_status,

     PEP_rating *rating

 );

 // get_key_rating_for_user() - get the rating of a certain key for a certain user

 //

 //  parameters:

 //

 //      session (in)            session handle

 //      user_id (in)            string with user ID

 //      fpr (in)                string with fingerprint

 //      rating (out)            rating of key for this user

 //

 //  returns:

 //      PEP_RECORD_NOT_FOUND if no trust record for user_id and fpr can be found

 DYNAMIC_API PEP_STATUS get_key_rating_for_user(

         PEP_SESSION session,

         const char *user_id,

         const char *fpr,

         PEP_rating *rating

     );

 #ifdef __cplusplus

 }

 #endif