// 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