src/message_api.h
author Volker Birk <vb@pep-project.org>
Fri, 29 Jul 2016 10:45:13 +0200
branchkeysync
changeset 939 ed7dfdae3031
parent 736 496905895282
child 952 986fd7b2eb8f
permissions -rw-r--r--
changing message_api: adding flags to encrypt_message()
     1 #pragma once
     2 
     3 #include "pEpEngine.h"
     4 #include "keymanagement.h"
     5 #include "message.h"
     6 #include "cryptotech.h"
     7 
     8 #ifdef __cplusplus
     9 extern "C" {
    10 #endif
    11 
    12 
    13 bool import_attached_keys(
    14         PEP_SESSION session, 
    15         const message *msg,
    16         identity_list **private_idents
    17     );
    18 void attach_own_key(PEP_SESSION session, message *msg);
    19 PEP_cryptotech determine_encryption_format(message *msg);
    20 
    21 typedef enum _PEP_encrypt_flags {
    22     PEP_encrypt_flag_force_encryption = 0x1
    23 } PEP_encrypt_flags; 
    24 
    25 typedef unsigned int PEP_encrypt_flags_t;
    26 
    27 // encrypt_message() - encrypt message in memory
    28 //
    29 //  parameters:
    30 //      session (in)        session handle
    31 //      src (in)            message to encrypt
    32 //      extra (in)          extra keys for encryption
    33 //      dst (out)           pointer to new encrypted message or NULL on failure
    34 //      enc_format (in)     encrypted format
    35 //      flags (in)          flags to set special encryption features
    36 //
    37 //  return value:
    38 //      PEP_STATUS_OK                   on success
    39 //		PEP_KEY_NOT_FOUND	            at least one of the receipient keys
    40 //		                                could not be found
    41 //		PEP_KEY_HAS_AMBIG_NAME          at least one of the receipient keys has
    42 //		                                an ambiguous name
    43 //		PEP_GET_KEY_FAILED		        cannot retrieve key
    44 //
    45 //	caveat:
    46 //	    the ownershop of src remains with the caller
    47 //	    the ownership of dst goes to the caller
    48 
    49 DYNAMIC_API PEP_STATUS encrypt_message(
    50         PEP_SESSION session,
    51         message *src,
    52         stringlist_t *extra,
    53         message **dst,
    54         PEP_enc_format enc_format,
    55         PEP_encrypt_flags_t flags
    56     );
    57 
    58 
    59 typedef enum _PEP_color {
    60     PEP_rating_undefined = 0,
    61     PEP_rating_cannot_decrypt,
    62     PEP_rating_have_no_key,
    63     PEP_rating_unencrypted,
    64     PEP_rating_unencrypted_for_some,
    65     PEP_rating_unreliable,
    66     PEP_rating_reliable,
    67     PEP_rating_yellow = PEP_rating_reliable,
    68     PEP_rating_trusted,
    69     PEP_rating_green = PEP_rating_trusted,
    70     PEP_rating_trusted_and_anonymized,
    71     PEP_rating_fully_anonymous,   
    72 
    73     PEP_rating_mistrust = -1,
    74     PEP_rating_red = PEP_rating_mistrust,
    75     PEP_rating_b0rken = -2,
    76     PEP_rating_under_attack = -3
    77 } PEP_color;
    78 
    79 typedef enum _PEP_decrypt_flags {
    80     PEP_decrypt_flag_own_private_key = 0x1
    81 } PEP_decrypt_flags; 
    82 
    83 typedef unsigned int PEP_decrypt_flags_t;
    84 
    85 // decrypt_message() - decrypt message in memory
    86 //
    87 //  parameters:
    88 //      session (in)        session handle
    89 //      src (in)            message to decrypt
    90 //      dst (out)           pointer to new decrypted message or NULL on failure
    91 //      keylist (out)       stringlist with keyids
    92 //      color (out)         color for the message
    93 //      flags (out)         flags to signal special decryption features
    94 //
    95 //  return value:
    96 //      error status or PEP_STATUS_OK on success
    97 //
    98 //	caveat:
    99 //	    the ownership of src remains with the caller
   100 //	    the ownership of dst goes to the caller
   101 //	    the ownership of keylist goes to the caller
   102 //	    if src is unencrypted this function returns PEP_UNENCRYPTED and sets
   103 //	    dst to NULL
   104 
   105 DYNAMIC_API PEP_STATUS decrypt_message(
   106         PEP_SESSION session,
   107         message *src,
   108         message **dst,
   109         stringlist_t **keylist,
   110         PEP_color *color,
   111         PEP_decrypt_flags_t *flags
   112 );
   113 
   114 // own_message_private_key_details() - details on own key in own message
   115 //
   116 //  parameters:
   117 //      session (in)        session handle
   118 //      msg (in)            message to decrypt
   119 //      ident (out)         identity containing uid, address and fpr of key
   120 //
   121 //  note:
   122 //      In order to obtain details about key to be possibly imported
   123 //      as a replacement of key currently used as own identity, 
   124 //      application passes message that have been previously flagged by 
   125 //      decrypt_message() as own message containing own key to this function
   126 //
   127 //  return value:
   128 //      error status or PEP_STATUS_OK on success
   129 //
   130 //	caveat:
   131 //	    the ownership of msg remains with the caller
   132 //	    the ownership of ident goes to the caller
   133 //	    msg MUST be encrypted so that this function can check own signature
   134 
   135 DYNAMIC_API PEP_STATUS own_message_private_key_details(
   136         PEP_SESSION session,
   137         message *msg,
   138         pEp_identity **ident 
   139 );
   140 
   141 // outgoing_message_color() - get color for an outgoing message
   142 //
   143 //  parameters:
   144 //      session (in)        session handle
   145 //      msg (in)            message to get the color for
   146 //      color (out)         color for the message
   147 //
   148 //  return value:
   149 //      error status or PEP_STATUS_OK on success
   150 //
   151 //  caveat:
   152 //      msg->from must point to a valid pEp_identity
   153 //      msg->dir must be PEP_dir_outgoing
   154 //      the ownership of msg remains with the caller
   155 
   156 DYNAMIC_API PEP_STATUS outgoing_message_color(
   157         PEP_SESSION session,
   158         message *msg,
   159         PEP_color *color
   160     );
   161 
   162 
   163 // identity_color() - get color for a single identity
   164 //
   165 //  parameters:
   166 //      session (in)        session handle
   167 //      ident (in)          identity to get the color for
   168 //      color (out)         color for the identity
   169 //
   170 //  return value:
   171 //      error status or PEP_STATUS_OK on success
   172 //
   173 //  caveat:
   174 //      the ownership of ident remains with the caller
   175 
   176 DYNAMIC_API PEP_STATUS identity_color(
   177         PEP_SESSION session,
   178         pEp_identity *ident,
   179         PEP_color *color
   180     );
   181 
   182 
   183 // get_binary_path() - retrieve path of cryptotech binary if available
   184 //
   185 //  parameters:
   186 //      tech (in)           cryptotech to get the binary for
   187 //      path (out)          path to cryptotech binary or NULL if not available
   188 //                          **path is owned by the library, do not change it!
   189 DYNAMIC_API PEP_STATUS get_binary_path(PEP_cryptotech tech, const char **path);
   190 
   191 
   192 #ifdef __cplusplus
   193 }
   194 #endif
   195