src/message_api.h
author Krista Grothoff <krista@pep-project.org>
Mon, 24 Oct 2016 21:31:51 +0200
branchENGINE-128
changeset 1331 fe7e15cae527
parent 1325 5f2e643a4fd7
child 1355 5cc70d0bc348
permissions -rw-r--r--
ENGINE-128: #comment MIME_decrypt_message() and MIME_encrypt_message() are both in. See message_api.h for usage; ping Krista if the api needs to look different.
     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 void add_opt_field(message *msg, const char *name, const char *value);
    21 
    22 typedef enum _PEP_encrypt_flags {
    23     PEP_encrypt_flag_force_encryption = 0x1
    24 } PEP_encrypt_flags; 
    25 
    26 typedef unsigned int PEP_encrypt_flags_t;
    27 
    28 // encrypt_message() - encrypt message in memory
    29 //
    30 //  parameters:
    31 //      session (in)        session handle
    32 //      src (in)            message to encrypt
    33 //      extra (in)          extra keys for encryption
    34 //      dst (out)           pointer to new encrypted message or NULL on failure
    35 //      enc_format (in)     encrypted format
    36 //      flags (in)          flags to set special encryption features
    37 //
    38 //  return value:
    39 //      PEP_STATUS_OK                   on success
    40 //		PEP_KEY_NOT_FOUND	            at least one of the receipient keys
    41 //		                                could not be found
    42 //		PEP_KEY_HAS_AMBIG_NAME          at least one of the receipient keys has
    43 //		                                an ambiguous name
    44 //		PEP_GET_KEY_FAILED		        cannot retrieve key
    45 //
    46 //	caveat:
    47 //	    the ownershop of src remains with the caller
    48 //	    the ownership of dst goes to the caller
    49 
    50 DYNAMIC_API PEP_STATUS encrypt_message(
    51         PEP_SESSION session,
    52         message *src,
    53         stringlist_t *extra,
    54         message **dst,
    55         PEP_enc_format enc_format,
    56         PEP_encrypt_flags_t flags
    57     );
    58 
    59 // encrypt_message_for_self() - encrypt message in memory for user's identity only,
    60 //                              ignoring recipients and other identities from
    61 //                              the message
    62 //  parameters:
    63 //      session (in)        session handle
    64 //      target_id (in)      self identity this message should be encrypted for
    65 //      src (in)            message to encrypt
    66 //      dst (out)           pointer to new encrypted message or NULL on failure
    67 //      enc_format (in)     encrypted format
    68 //
    69 //  return value:       (FIXME: This may not be correct or complete)
    70 //      PEP_STATUS_OK                   on success
    71 //		PEP_KEY_NOT_FOUND	            at least one of the receipient keys
    72 //		                                could not be found
    73 //		PEP_KEY_HAS_AMBIG_NAME          at least one of the receipient keys has
    74 //		                                an ambiguous name
    75 //		PEP_GET_KEY_FAILED		        cannot retrieve key
    76 //
    77 //	caveat:
    78 //	    the ownership of src remains with the caller
    79 //      the ownership of target_id remains w/ caller            
    80 //	    the ownership of dst goes to the caller
    81 //      message is NOT encrypted for identities other than the target_id (and then,
    82 //          only if the target_id refers to self!)
    83 
    84 DYNAMIC_API PEP_STATUS encrypt_message_for_self(
    85         PEP_SESSION session,
    86         pEp_identity* target_id,
    87         message *src,
    88         message **dst,
    89         PEP_enc_format enc_format
    90     );
    91 
    92 // MIME_encrypt_message() - encrypt a MIME message, with MIME output
    93 //
    94 //  parameters:
    95 //      session (in)            session handle
    96 //      mimetext (in)           MIME encoded text to encrypt
    97 //      size (in)               size of input mime text
    98 //      extra (in)              extra keys for encryption
    99 //      mime_ciphertext (out)   encrypted, encoded message
   100 //      enc_format (in)         encrypted format
   101 //      flags (in)              flags to set special encryption features
   102 //
   103 //  return value:
   104 //      PEP_STATUS_OK           if everything worked
   105 //      PEP_BUFFER_TOO_SMALL    if encoded message size is too big to handle
   106 //      PEP_CANNOT_CREATE_TEMP_FILE
   107 //                              if there are issues with temp files; in
   108 //                              this case errno will contain the underlying
   109 //                              error
   110 //      PEP_OUT_OF_MEMORY       if not enough memory could be allocated
   111 //
   112 //  caveat:
   113 //      the encrypted, encoded mime text will go to the ownership of the caller; mimetext
   114 //      will remain in the ownership of the caller
   115 
   116 DYNAMIC_API PEP_STATUS MIME_encrypt_message(
   117     PEP_SESSION session,
   118     const char *mimetext,
   119     size_t size,
   120     stringlist_t* extra,
   121     char** mime_ciphertext,
   122     PEP_enc_format enc_format,
   123     PEP_encrypt_flags_t flags
   124 );
   125 
   126 typedef enum _PEP_rating {
   127     PEP_rating_undefined = 0,
   128     PEP_rating_cannot_decrypt,
   129     PEP_rating_have_no_key,
   130     PEP_rating_unencrypted,
   131     PEP_rating_unencrypted_for_some,
   132     PEP_rating_unreliable,
   133     PEP_rating_reliable,
   134     PEP_rating_trusted,
   135     PEP_rating_trusted_and_anonymized,
   136     PEP_rating_fully_anonymous,   
   137 
   138     PEP_rating_mistrust = -1,
   139     PEP_rating_b0rken = -2,
   140     PEP_rating_under_attack = -3
   141 } PEP_rating;
   142 
   143 typedef enum _PEP_color {
   144     PEP_color_no_color = 0,
   145     PEP_color_yellow,
   146     PEP_color_green,
   147     PEP_color_red = -1,
   148 } PEP_color;
   149 
   150 // color_from_rating - calculate color from rating
   151 //
   152 //  parameters:
   153 //      rating (in)         rating
   154 //
   155 //  return value:           color representing that rating
   156 
   157 DYNAMIC_API PEP_color color_from_rating(PEP_rating rating);
   158 
   159 typedef enum _PEP_decrypt_flags {
   160     PEP_decrypt_flag_own_private_key = 0x1
   161 } PEP_decrypt_flags; 
   162 
   163 typedef unsigned int PEP_decrypt_flags_t;
   164 
   165 // decrypt_message() - decrypt message in memory
   166 //
   167 //  parameters:
   168 //      session (in)        session handle
   169 //      src (in)            message to decrypt
   170 //      dst (out)           pointer to new decrypted message or NULL on failure
   171 //      keylist (out)       stringlist with keyids
   172 //      rating (out)        rating for the message
   173 //      flags (out)         flags to signal special decryption features
   174 //
   175 //  return value:
   176 //      error status or PEP_STATUS_OK on success
   177 //
   178 //	caveat:
   179 //	    the ownership of src remains with the caller
   180 //	    the ownership of dst goes to the caller
   181 //	    the ownership of keylist goes to the caller
   182 //	    if src is unencrypted this function returns PEP_UNENCRYPTED and sets
   183 //	    dst to NULL
   184 
   185 DYNAMIC_API PEP_STATUS decrypt_message(
   186         PEP_SESSION session,
   187         message *src,
   188         message **dst,
   189         stringlist_t **keylist,
   190         PEP_rating *rating,
   191         PEP_decrypt_flags_t *flags
   192 );
   193 
   194 // MIME_decrypt_message() - decrypt a MIME message, with MIME output
   195 //
   196 //  parameters:
   197 //      session (in)            session handle
   198 //      mimetext (in)           MIME encoded text to decrypt
   199 //      size (in)               size of mime text to decode (in order to decrypt)
   200 //      mime_plaintext (out)    decrypted, encoded message
   201 //      keylist (out)           stringlist with keyids
   202 //      rating (out)            rating for the message
   203 //      flags (out)             flags to signal special decryption features
   204 //
   205 //  return value:
   206 //      PEP_STATUS_OK           if everything worked
   207 //      PEP_BUFFER_TOO_SMALL    if encoded message size is too big to handle
   208 //      PEP_CANNOT_CREATE_TEMP_FILE
   209 //                              if there are issues with temp files; in
   210 //                              this case errno will contain the underlying
   211 //                              error
   212 //      PEP_OUT_OF_MEMORY       if not enough memory could be allocated
   213 //
   214 //  caveat:
   215 //      the decrypted, encoded mime text will go to the ownership of the caller; mimetext
   216 //      will remain in the ownership of the caller
   217 
   218 DYNAMIC_API PEP_STATUS MIME_decrypt_message(
   219     PEP_SESSION session,
   220     const char *mimetext,
   221     size_t size,
   222     char** mime_plaintext,
   223     stringlist_t **keylist,
   224     PEP_rating *rating,
   225     PEP_decrypt_flags_t *flags
   226 );
   227 
   228 
   229 // own_message_private_key_details() - details on own key in own message
   230 //
   231 //  parameters:
   232 //      session (in)        session handle
   233 //      msg (in)            message to decrypt
   234 //      ident (out)         identity containing uid, address and fpr of key
   235 //
   236 //  note:
   237 //      In order to obtain details about key to be possibly imported
   238 //      as a replacement of key currently used as own identity, 
   239 //      application passes message that have been previously flagged by 
   240 //      decrypt_message() as own message containing own key to this function
   241 //
   242 //  return value:
   243 //      error status or PEP_STATUS_OK on success
   244 //
   245 //	caveat:
   246 //	    the ownership of msg remains with the caller
   247 //	    the ownership of ident goes to the caller
   248 //	    msg MUST be encrypted so that this function can check own signature
   249 
   250 DYNAMIC_API PEP_STATUS own_message_private_key_details(
   251         PEP_SESSION session,
   252         message *msg,
   253         pEp_identity **ident 
   254 );
   255 
   256 // outgoing_message_rating() - get rating for an outgoing message
   257 //
   258 //  parameters:
   259 //      session (in)        session handle
   260 //      msg (in)            message to get the rating for
   261 //      rating (out)        rating for the message
   262 //
   263 //  return value:
   264 //      error status or PEP_STATUS_OK on success
   265 //
   266 //  caveat:
   267 //      msg->from must point to a valid pEp_identity
   268 //      msg->dir must be PEP_dir_outgoing
   269 //      the ownership of msg remains with the caller
   270 
   271 DYNAMIC_API PEP_STATUS outgoing_message_rating(
   272         PEP_SESSION session,
   273         message *msg,
   274         PEP_rating *rating
   275     );
   276 
   277 
   278 // identity_rating() - get rating for a single identity
   279 //
   280 //  parameters:
   281 //      session (in)        session handle
   282 //      ident (in)          identity to get the rating for
   283 //      rating (out)        rating for the identity
   284 //
   285 //  return value:
   286 //      error status or PEP_STATUS_OK on success
   287 //
   288 //  caveat:
   289 //      the ownership of ident remains with the caller
   290 
   291 DYNAMIC_API PEP_STATUS identity_rating(
   292         PEP_SESSION session,
   293         pEp_identity *ident,
   294         PEP_rating *rating
   295     );
   296 
   297 
   298 // get_binary_path() - retrieve path of cryptotech binary if available
   299 //
   300 //  parameters:
   301 //      tech (in)           cryptotech to get the binary for
   302 //      path (out)          path to cryptotech binary or NULL if not available
   303 //                          **path is owned by the library, do not change it!
   304 DYNAMIC_API PEP_STATUS get_binary_path(PEP_cryptotech tech, const char **path);
   305 
   306 // get_trustwords() - get full trustwords string for a *pair* of identities
   307 //
   308 //    parameters:
   309 //        session (in)        session handle
   310 //        id1 (in)            identity of first party in communication - fpr can't be NULL  
   311 //        id2 (in)            identity of second party in communication - fpr can't be NULL
   312 //        lang (in)           C string with ISO 639-1 language code
   313 //        words (out)         pointer to C string with all trustwords UTF-8 encoded,
   314 //                            separated by a blank each
   315 //                            NULL if language is not supported or trustword
   316 //                            wordlist is damaged or unavailable
   317 //        wsize (out)         length of full trustwords string
   318 //        full (in)           if true, generate ALL trustwords for these identities.
   319 //                            else, generate a fixed-size subset. (TODO: fixed-minimum-entropy
   320 //                            subset in next version)
   321 //
   322 //    return value:
   323 //        PEP_STATUS_OK            trustwords retrieved
   324 //        PEP_OUT_OF_MEMORY        out of memory
   325 //        PEP_TRUSTWORD_NOT_FOUND  at least one trustword not found
   326 //
   327 //    caveat:
   328 //        the word pointer goes to the ownership of the caller
   329 //        the caller is responsible to free() it (on Windoze use pEp_free())
   330 //
   331 
   332 DYNAMIC_API PEP_STATUS get_trustwords(
   333     PEP_SESSION session, pEp_identity* id1, pEp_identity* id2,
   334     const char* lang, char **words, size_t *wsize, bool full
   335 );
   336 
   337 #ifdef __cplusplus
   338 }
   339 #endif
   340