src/message_api.h
author Volker Birk <vb@pep.foundation>
Sat, 30 Dec 2017 16:06:57 +0100
changeset 2338 b70a6082836b
parent 2147 22394e4b5047
child 2477 45e8ed722fec
permissions -rw-r--r--
settings enc_format to PEP_enc_none now legal in encrypt_message()
     1 // This file is under GNU General Public License 3.0
     2 // see LICENSE.txt
     3 
     4 #pragma once
     5 
     6 #include "pEpEngine.h"
     7 #include "keymanagement.h"
     8 #include "message.h"
     9 #include "cryptotech.h"
    10 
    11 #ifdef __cplusplus
    12 extern "C" {
    13 #endif
    14 
    15 
    16 bool import_attached_keys(
    17         PEP_SESSION session, 
    18         const message *msg,
    19         identity_list **private_idents
    20     );
    21 
    22 void attach_own_key(PEP_SESSION session, message *msg);
    23 
    24 PEP_cryptotech determine_encryption_format(message *msg);
    25 
    26 void add_opt_field(message *msg, const char *name, const char *value);
    27 
    28 typedef enum _PEP_encrypt_flags {
    29     // "default" means whatever the default behaviour for the function is.
    30     PEP_encrypt_flag_default = 0x0,
    31     PEP_encrypt_flag_force_encryption = 0x1,
    32 
    33     // This flag is for special use cases and should not be used
    34     // by normal pEp clients!
    35     PEP_encrypt_flag_force_unsigned = 0x2,
    36     PEP_encrypt_flag_force_no_attached_key = 0x4,
    37     
    38     // This is used for outer messages (used to wrap the real message)
    39     // This is only used internally and (eventually) by transport functions
    40     PEP_encrypt_flag_inner_message = 0x8
    41 } PEP_encrypt_flags; 
    42 
    43 typedef unsigned int PEP_encrypt_flags_t;
    44 
    45 
    46 // encrypt_message() - encrypt message in memory
    47 //
    48 //  parameters:
    49 //      session (in)        session handle
    50 //      src (in)            message to encrypt
    51 //      extra (in)          extra keys for encryption
    52 //      dst (out)           pointer to new encrypted message or NULL if no
    53 //                          encryption could take place
    54 //      enc_format (in)     encrypted format
    55 //      flags (in)          flags to set special encryption features
    56 //
    57 //  return value:
    58 //      PEP_STATUS_OK                   on success
    59 //      PEP_KEY_NOT_FOUND               at least one of the receipient keys
    60 //                                      could not be found
    61 //      PEP_KEY_HAS_AMBIG_NAME          at least one of the receipient keys has
    62 //                                      an ambiguous name
    63 //      PEP_GET_KEY_FAILED              cannot retrieve key
    64 //      PEP_UNENCRYPTED                 on demand or no recipients with usable
    65 //                                      key, is left unencrypted, and key is
    66 //                                      attached to it
    67 //
    68 //  caveat:
    69 //      the ownershop of src remains with the caller
    70 //      the ownership of dst goes to the caller
    71 DYNAMIC_API PEP_STATUS encrypt_message(
    72         PEP_SESSION session,
    73         message *src,
    74         stringlist_t *extra,
    75         message **dst,
    76         PEP_enc_format enc_format,
    77         PEP_encrypt_flags_t flags
    78     );
    79 
    80 
    81 // encrypt_message_for_self() - encrypt message in memory for user's identity only,
    82 //                              ignoring recipients and other identities from
    83 //                              the message
    84 //  parameters:
    85 //      session (in)        session handle
    86 //      target_id (in)      self identity this message should be encrypted for
    87 //      src (in)            message to encrypt
    88 //      dst (out)           pointer to new encrypted message or NULL on failure
    89 //      enc_format (in)     encrypted format
    90 //      flags (in)          flags to set special encryption features
    91 //
    92 //  return value:       (FIXME: This may not be correct or complete)
    93 //      PEP_STATUS_OK            on success
    94 //      PEP_KEY_NOT_FOUND        at least one of the receipient keys
    95 //                               could not be found
    96 //      PEP_KEY_HAS_AMBIG_NAME   at least one of the receipient keys has
    97 //                               an ambiguous name
    98 //      PEP_GET_KEY_FAILED       cannot retrieve key
    99 //
   100 //  caveat:
   101 //      the ownership of src remains with the caller
   102 //      the ownership of target_id remains w/ caller            
   103 //      the ownership of dst goes to the caller
   104 //      message is NOT encrypted for identities other than the target_id (and then,
   105 //      only if the target_id refers to self!)
   106 DYNAMIC_API PEP_STATUS encrypt_message_for_self(
   107         PEP_SESSION session,
   108         pEp_identity* target_id,
   109         message *src,
   110         message **dst,
   111         PEP_enc_format enc_format,
   112         PEP_encrypt_flags_t flags
   113     );
   114 
   115 
   116 // MIME_encrypt_message() - encrypt a MIME message, with MIME output
   117 //
   118 //  parameters:
   119 //      session (in)            session handle
   120 //      mimetext (in)           MIME encoded text to encrypt
   121 //      size (in)               size of input mime text
   122 //      extra (in)              extra keys for encryption
   123 //      mime_ciphertext (out)   encrypted, encoded message
   124 //      enc_format (in)         encrypted format
   125 //      flags (in)              flags to set special encryption features
   126 //
   127 //  return value:
   128 //      PEP_STATUS_OK           if everything worked
   129 //      PEP_BUFFER_TOO_SMALL    if encoded message size is too big to handle
   130 //      PEP_CANNOT_CREATE_TEMP_FILE
   131 //                              if there are issues with temp files; in
   132 //                              this case errno will contain the underlying
   133 //                              error
   134 //      PEP_OUT_OF_MEMORY       if not enough memory could be allocated
   135 //
   136 //  caveat:
   137 //      the encrypted, encoded mime text will go to the ownership of the caller; mimetext
   138 //      will remain in the ownership of the caller
   139 DYNAMIC_API PEP_STATUS MIME_encrypt_message(
   140     PEP_SESSION session,
   141     const char *mimetext,
   142     size_t size,
   143     stringlist_t* extra,
   144     char** mime_ciphertext,
   145     PEP_enc_format enc_format,
   146     PEP_encrypt_flags_t flags
   147 );
   148 
   149 
   150 // MIME_encrypt_message_for_self() - encrypt MIME message for user's identity only,
   151 //                              ignoring recipients and other identities from
   152 //                              the message, with MIME output
   153 //  parameters:
   154 //      session (in)            session handle
   155 //      target_id (in)          self identity this message should be encrypted for
   156 //      mimetext (in)           MIME encoded text to encrypt
   157 //      size (in)               size of input mime text
   158 //      mime_ciphertext (out)   encrypted, encoded message
   159 //      enc_format (in)         encrypted format
   160 //      flags (in)              flags to set special encryption features
   161 //
   162 //  return value:
   163 //      PEP_STATUS_OK           if everything worked
   164 //      PEP_BUFFER_TOO_SMALL    if encoded message size is too big to handle
   165 //      PEP_CANNOT_CREATE_TEMP_FILE
   166 //                              if there are issues with temp files; in
   167 //                              this case errno will contain the underlying
   168 //                              error
   169 //      PEP_OUT_OF_MEMORY       if not enough memory could be allocated
   170 //
   171 //  caveat:
   172 //      the encrypted, encoded mime text will go to the ownership of the caller; mimetext
   173 //      will remain in the ownership of the caller
   174 DYNAMIC_API PEP_STATUS MIME_encrypt_message_for_self(
   175     PEP_SESSION session,
   176     pEp_identity* target_id,
   177     const char *mimetext,
   178     size_t size,
   179     char** mime_ciphertext,
   180     PEP_enc_format enc_format,
   181     PEP_encrypt_flags_t flags
   182 );
   183 
   184 
   185 typedef enum _PEP_rating {
   186     PEP_rating_undefined = 0,
   187     PEP_rating_cannot_decrypt,
   188     PEP_rating_have_no_key,
   189     PEP_rating_unencrypted,
   190     PEP_rating_unencrypted_for_some,
   191     PEP_rating_unreliable,
   192     PEP_rating_reliable,
   193     PEP_rating_trusted,
   194     PEP_rating_trusted_and_anonymized,
   195     PEP_rating_fully_anonymous,   
   196 
   197     PEP_rating_mistrust = -1,
   198     PEP_rating_b0rken = -2,
   199     PEP_rating_under_attack = -3
   200 } PEP_rating;
   201 
   202 typedef enum _PEP_color {
   203     PEP_color_no_color = 0,
   204     PEP_color_yellow,
   205     PEP_color_green,
   206     PEP_color_red = -1,
   207 } PEP_color;
   208 
   209 
   210 // color_from_rating - calculate color from rating
   211 //
   212 //  parameters:
   213 //      rating (in)         rating
   214 //
   215 //  return value:           color representing that rating
   216 DYNAMIC_API PEP_color color_from_rating(PEP_rating rating);
   217 
   218 typedef enum _PEP_decrypt_flags {
   219     PEP_decrypt_flag_own_private_key = 0x1,
   220     PEP_decrypt_flag_consume = 0x2,
   221     PEP_decrypt_flag_ignore = 0x4
   222 } PEP_decrypt_flags; 
   223 
   224 typedef unsigned int PEP_decrypt_flags_t;
   225 
   226 
   227 // decrypt_message() - decrypt message in memory
   228 //
   229 //  parameters:
   230 //      session (in)        session handle
   231 //      src (in)            message to decrypt
   232 //      dst (out)           pointer to new decrypted message or NULL on failure
   233 //      keylist (out)       stringlist with keyids
   234 //      rating (out)        rating for the message
   235 //      flags (out)         flags to signal special decryption features
   236 //
   237 //  return value:
   238 //      error status 
   239 //      or PEP_DECRYPTED if message decrypted but not verified
   240 //      or PEP_STATUS_OK on success
   241 //
   242 // caveat:
   243 //      the ownership of src remains with the caller
   244 //      the ownership of dst goes to the caller
   245 //      the ownership of keylist goes to the caller
   246 //      if src is unencrypted this function returns PEP_UNENCRYPTED and sets
   247 //      dst to NULL
   248 DYNAMIC_API PEP_STATUS decrypt_message(
   249         PEP_SESSION session,
   250         message *src,
   251         message **dst,
   252         stringlist_t **keylist,
   253         PEP_rating *rating,
   254         PEP_decrypt_flags_t *flags
   255 );
   256 
   257 
   258 // MIME_decrypt_message() - decrypt a MIME message, with MIME output
   259 //
   260 //  parameters:
   261 //      session (in)            session handle
   262 //      mimetext (in)           MIME encoded text to decrypt
   263 //      size (in)               size of mime text to decode (in order to decrypt)
   264 //      mime_plaintext (out)    decrypted, encoded message
   265 //      keylist (out)           stringlist with keyids
   266 //      rating (out)            rating for the message
   267 //      flags (out)             flags to signal special decryption features
   268 //
   269 //  return value:
   270 //      decrypt status          if everything worked with MIME encode/decode, 
   271 //                              the status of the decryption is returned 
   272 //                              (PEP_STATUS_OK or decryption error status)
   273 //      PEP_BUFFER_TOO_SMALL    if encoded message size is too big to handle
   274 //      PEP_CANNOT_CREATE_TEMP_FILE
   275 //                              if there are issues with temp files; in
   276 //                              this case errno will contain the underlying
   277 //                              error
   278 //      PEP_OUT_OF_MEMORY       if not enough memory could be allocated
   279 //
   280 //  caveat:
   281 //      the decrypted, encoded mime text will go to the ownership of the caller; mimetext
   282 //      will remain in the ownership of the caller
   283 DYNAMIC_API PEP_STATUS MIME_decrypt_message(
   284     PEP_SESSION session,
   285     const char *mimetext,
   286     size_t size,
   287     char** mime_plaintext,
   288     stringlist_t **keylist,
   289     PEP_rating *rating,
   290     PEP_decrypt_flags_t *flags
   291 );
   292 
   293 
   294 // own_message_private_key_details() - details on own key in own message
   295 //
   296 //  parameters:
   297 //      session (in)        session handle
   298 //      msg (in)            message to decrypt
   299 //      ident (out)         identity containing uid, address and fpr of key
   300 //
   301 //  note:
   302 //      In order to obtain details about key to be possibly imported
   303 //      as a replacement of key currently used as own identity, 
   304 //      application passes message that have been previously flagged by 
   305 //      decrypt_message() as own message containing own key to this function
   306 //
   307 //  return value:
   308 //      error status or PEP_STATUS_OK on success
   309 //
   310 //  caveat:
   311 //      the ownership of msg remains with the caller
   312 //      the ownership of ident goes to the caller
   313 //      msg MUST be encrypted so that this function can check own signature
   314 DYNAMIC_API PEP_STATUS own_message_private_key_details(
   315         PEP_SESSION session,
   316         message *msg,
   317         pEp_identity **ident 
   318 );
   319 
   320 
   321 // outgoing_message_rating() - get rating for an outgoing message
   322 //
   323 //  parameters:
   324 //      session (in)        session handle
   325 //      msg (in)            message to get the rating for
   326 //      rating (out)        rating for the message
   327 //
   328 //  return value:
   329 //      error status or PEP_STATUS_OK on success
   330 //
   331 //  caveat:
   332 //      msg->from must point to a valid pEp_identity
   333 //      msg->dir must be PEP_dir_outgoing
   334 //      the ownership of msg remains with the caller
   335 DYNAMIC_API PEP_STATUS outgoing_message_rating(
   336         PEP_SESSION session,
   337         message *msg,
   338         PEP_rating *rating
   339     );
   340 
   341 
   342 // identity_rating() - get rating for a single identity
   343 //
   344 //  parameters:
   345 //      session (in)        session handle
   346 //      ident (in)          identity to get the rating for
   347 //      rating (out)        rating for the identity
   348 //
   349 //  return value:
   350 //      error status or PEP_STATUS_OK on success
   351 //
   352 //  caveat:
   353 //      the ownership of ident remains with the caller
   354 DYNAMIC_API PEP_STATUS identity_rating(
   355         PEP_SESSION session,
   356         pEp_identity *ident,
   357         PEP_rating *rating
   358     );
   359 
   360 
   361 // get_binary_path() - retrieve path of cryptotech binary if available
   362 //
   363 //  parameters:
   364 //      tech (in)           cryptotech to get the binary for
   365 //      path (out)          path to cryptotech binary or NULL if not available
   366 //                          **path is owned by the library, do not change it!
   367 DYNAMIC_API PEP_STATUS get_binary_path(PEP_cryptotech tech, const char **path);
   368 
   369 
   370 // get_trustwords() - get full trustwords string for a *pair* of identities
   371 //
   372 //    parameters:
   373 //        session (in)        session handle
   374 //        id1 (in)            identity of first party in communication - fpr can't be NULL  
   375 //        id2 (in)            identity of second party in communication - fpr can't be NULL
   376 //        lang (in)           C string with ISO 639-1 language code
   377 //        words (out)         pointer to C string with all trustwords UTF-8 encoded,
   378 //                            separated by a blank each
   379 //                            NULL if language is not supported or trustword
   380 //                            wordlist is damaged or unavailable
   381 //        wsize (out)         length of full trustwords string
   382 //        full (in)           if true, generate ALL trustwords for these identities.
   383 //                            else, generate a fixed-size subset. (TODO: fixed-minimum-entropy
   384 //                            subset in next version)
   385 //
   386 //    return value:
   387 //        PEP_STATUS_OK            trustwords retrieved
   388 //        PEP_OUT_OF_MEMORY        out of memory
   389 //        PEP_TRUSTWORD_NOT_FOUND  at least one trustword not found
   390 //
   391 //    caveat:
   392 //        the word pointer goes to the ownership of the caller
   393 //        the caller is responsible to free() it (on Windoze use pEp_free())
   394 //
   395 DYNAMIC_API PEP_STATUS get_trustwords(
   396     PEP_SESSION session, const pEp_identity* id1, const pEp_identity* id2,
   397     const char* lang, char **words, size_t *wsize, bool full
   398 );
   399 
   400 
   401 // get_message_trustwords() - get full trustwords string for message sender and reciever identities 
   402 //
   403 //    parameters:
   404 //        session (in)        session handle
   405 //        msg (in)            message to get sender identity from
   406 //        keylist (in)        NULL if message to be decrypted,
   407 //                            keylist returned by decrypt_message() otherwise
   408 //        received_by (in)    identity for account receiving message can't be NULL
   409 //        lang (in)           C string with ISO 639-1 language code
   410 //        words (out)         pointer to C string with all trustwords UTF-8 encoded,
   411 //                            separated by a blank each
   412 //                            NULL if language is not supported or trustword
   413 //                            wordlist is damaged or unavailable
   414 //        full (in)           if true, generate ALL trustwords for these identities.
   415 //                            else, generate a fixed-size subset. (TODO: fixed-minimum-entropy
   416 //                            subset in next version)
   417 //
   418 //    return value:
   419 //        PEP_STATUS_OK            trustwords retrieved
   420 //        PEP_OUT_OF_MEMORY        out of memory
   421 //        PEP_TRUSTWORD_NOT_FOUND  at least one trustword not found
   422 //        error status of decrypt_message() if decryption fails.
   423 //
   424 //    caveat:
   425 //        the word pointer goes to the ownership of the caller
   426 //        the caller is responsible to free() it (on Windoze use pEp_free())
   427 //
   428 DYNAMIC_API PEP_STATUS get_message_trustwords(
   429     PEP_SESSION session, 
   430     message *msg,
   431     stringlist_t *keylist,
   432     pEp_identity* received_by,
   433     const char* lang, char **words, bool full
   434 );
   435 
   436 // re_evaluate_message_rating() - re-evaluate already decrypted message rating
   437 //
   438 //  parameters:
   439 //      session (in)            session handle
   440 //      msg (in)                message to get the rating for
   441 //      x_keylist (in)          decrypted message recipients keys fpr
   442 //      x_enc_status (in)       original rating for the decrypted message
   443 //      rating (out)            rating for the message
   444 //
   445 //  return value:
   446 //      PEP_ILLEGAL_VALUE       if decrypted message doesn't contain 
   447 //                              X-EncStatus optional field and x_enc_status is 
   448 //                              pEp_rating_udefined
   449 //                              or if decrypted message doesn't contain 
   450 //                              X-Keylist optional field and x_keylist is NULL
   451 //      PEP_OUT_OF_MEMORY       if not enough memory could be allocated
   452 //
   453 //  caveat:
   454 //      msg->from must point to a valid pEp_identity
   455 //      the ownership of msg remains with the caller
   456 //	    the ownership of x_keylist remains with to the caller
   457 
   458 DYNAMIC_API PEP_STATUS re_evaluate_message_rating(
   459     PEP_SESSION session,
   460     message *msg,
   461     stringlist_t *x_keylist,
   462     PEP_rating x_enc_status,
   463     PEP_rating *rating
   464 );
   465 #ifdef __cplusplus
   466 }
   467 #endif