src/message_api.h
author Krista Bennett <krista@pep-project.org>
Fri, 22 Jun 2018 13:58:07 +0200
changeset 2759 3e2762e73975
parent 2658 b9d02eaf6b90
child 2770 08d7cf271f57
permissions -rw-r--r--
Clarified keylist output 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 bool import_attached_keys(
    16     
    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     
    42 } PEP_encrypt_flags; 
    43 
    44 typedef unsigned int PEP_encrypt_flags_t;
    45 
    46 
    47 // encrypt_message() - encrypt message in memory
    48 //
    49 //  parameters:
    50 //      session (in)        session handle
    51 //      src (in)            message to encrypt
    52 //      extra (in)          extra keys for encryption
    53 //      dst (out)           pointer to new encrypted message or NULL if no
    54 //                          encryption could take place
    55 //      enc_format (in)     encrypted format
    56 //      flags (in)          flags to set special encryption features
    57 //
    58 //  return value:
    59 //      PEP_STATUS_OK                   on success
    60 //      PEP_KEY_HAS_AMBIG_NAME          at least one of the receipient keys has
    61 //                                      an ambiguous name
    62 //      PEP_UNENCRYPTED                 on demand or no recipients with usable
    63 //                                      key, is left unencrypted, and key is
    64 //                                      attached to it
    65 //
    66 //  caveat:
    67 //      the ownershop of src remains with the caller
    68 //      the ownership of dst goes to the caller
    69 DYNAMIC_API PEP_STATUS encrypt_message(
    70         PEP_SESSION session,
    71         message *src,
    72         stringlist_t *extra,
    73         message **dst,
    74         PEP_enc_format enc_format,
    75         PEP_encrypt_flags_t flags
    76     );
    77 
    78 
    79 // encrypt_message_and_add_priv_key() - encrypt message in memory, adding an encrypted private
    80 //                                      key (encrypted separately and sent within the inner message)
    81 //
    82 //  parameters:
    83 //      session (in)        session handle
    84 //      src (in)            message to encrypt
    85 //      dst (out)           pointer to new encrypted message or NULL if no
    86 //                          encryption could take place
    87 //      to_fpr              fingerprint of the recipient key to which the private key
    88 //                          should be encrypted
    89 //      enc_format (in)     encrypted format
    90 //      flags (in)          flags to set special encryption features
    91 //
    92 //  return value:
    93 //      PEP_STATUS_OK                   on success
    94 //      PEP_KEY_HAS_AMBIG_NAME          at least one of the receipient keys has
    95 //                                      an ambiguous name
    96 //      PEP_UNENCRYPTED                 on demand or no recipients with usable
    97 //                                      key, is left unencrypted, and key is
    98 //                                      attached to it
    99 //
   100 //  caveat:
   101 //      the ownershop of src remains with the caller
   102 //      the ownership of dst goes to the caller
   103 DYNAMIC_API PEP_STATUS encrypt_message_and_add_priv_key(
   104         PEP_SESSION session,
   105         message *src,
   106         message **dst,
   107         const char* to_fpr,
   108         PEP_enc_format enc_format,
   109         PEP_encrypt_flags_t flags
   110     );
   111 
   112 
   113 // encrypt_message_for_self() - encrypt message in memory for user's identity only,
   114 //                              ignoring recipients and other identities from
   115 //                              the message
   116 //  parameters:
   117 //      session (in)        session handle
   118 //      target_id (in)      self identity this message should be encrypted for
   119 //      src (in)            message to encrypt
   120 //      extra (in)          extra keys for encryption
   121 //      dst (out)           pointer to new encrypted message or NULL on failure
   122 //      enc_format (in)     encrypted format
   123 //      flags (in)          flags to set special encryption features
   124 //
   125 //  return value:       (FIXME: This may not be correct or complete)
   126 //      PEP_STATUS_OK            on success
   127 //      PEP_KEY_NOT_FOUND        at least one of the receipient keys
   128 //                               could not be found
   129 //      PEP_KEY_HAS_AMBIG_NAME   at least one of the receipient keys has
   130 //                               an ambiguous name
   131 //      PEP_GET_KEY_FAILED       cannot retrieve key
   132 //
   133 //  caveat:
   134 //      the ownership of src remains with the caller
   135 //      the ownership of target_id remains w/ caller            
   136 //      the ownership of dst goes to the caller
   137 //      message is NOT encrypted for identities other than the target_id (and then,
   138 //      only if the target_id refers to self!)
   139 DYNAMIC_API PEP_STATUS encrypt_message_for_self(
   140         PEP_SESSION session,
   141         pEp_identity* target_id,
   142         message *src,
   143         stringlist_t* extra,
   144         message **dst,
   145         PEP_enc_format enc_format,
   146         PEP_encrypt_flags_t flags
   147     );
   148 
   149 
   150 // MIME_encrypt_message() - encrypt a MIME message, with MIME output
   151 //
   152 //  parameters:
   153 //      session (in)            session handle
   154 //      mimetext (in)           MIME encoded text to encrypt
   155 //      size (in)               size of input mime text
   156 //      extra (in)              extra keys for encryption
   157 //      mime_ciphertext (out)   encrypted, encoded message
   158 //      enc_format (in)         encrypted format
   159 //      flags (in)              flags to set special encryption features
   160 //
   161 //  return value:
   162 //      PEP_STATUS_OK           if everything worked
   163 //      PEP_BUFFER_TOO_SMALL    if encoded message size is too big to handle
   164 //      PEP_CANNOT_CREATE_TEMP_FILE
   165 //                              if there are issues with temp files; in
   166 //                              this case errno will contain the underlying
   167 //                              error
   168 //      PEP_OUT_OF_MEMORY       if not enough memory could be allocated
   169 //
   170 //  caveat:
   171 //      the encrypted, encoded mime text will go to the ownership of the caller; mimetext
   172 //      will remain in the ownership of the caller
   173 DYNAMIC_API PEP_STATUS MIME_encrypt_message(
   174     PEP_SESSION session,
   175     const char *mimetext,
   176     size_t size,
   177     stringlist_t* extra,
   178     char** mime_ciphertext,
   179     PEP_enc_format enc_format,
   180     PEP_encrypt_flags_t flags
   181 );
   182 
   183 
   184 // MIME_encrypt_message_for_self() - encrypt MIME message for user's identity only,
   185 //                              ignoring recipients and other identities from
   186 //                              the message, with MIME output
   187 //  parameters:
   188 //      session (in)            session handle
   189 //      target_id (in)          self identity this message should be encrypted for
   190 //      mimetext (in)           MIME encoded text to encrypt
   191 //      size (in)               size of input mime text
   192 //      extra (in)              extra keys for encryption
   193 //      mime_ciphertext (out)   encrypted, encoded message
   194 //      enc_format (in)         encrypted format
   195 //      flags (in)              flags to set special encryption features
   196 //
   197 //  return value:
   198 //      PEP_STATUS_OK           if everything worked
   199 //      PEP_BUFFER_TOO_SMALL    if encoded message size is too big to handle
   200 //      PEP_CANNOT_CREATE_TEMP_FILE
   201 //                              if there are issues with temp files; in
   202 //                              this case errno will contain the underlying
   203 //                              error
   204 //      PEP_OUT_OF_MEMORY       if not enough memory could be allocated
   205 //
   206 //  caveat:
   207 //      the encrypted, encoded mime text will go to the ownership of the caller; mimetext
   208 //      will remain in the ownership of the caller
   209 DYNAMIC_API PEP_STATUS MIME_encrypt_message_for_self(
   210     PEP_SESSION session,
   211     pEp_identity* target_id,
   212     const char *mimetext,
   213     size_t size,
   214     stringlist_t* extra,
   215     char** mime_ciphertext,
   216     PEP_enc_format enc_format,
   217     PEP_encrypt_flags_t flags
   218 );
   219 
   220 
   221 typedef enum _PEP_rating {
   222     PEP_rating_undefined = 0,
   223     PEP_rating_cannot_decrypt,
   224     PEP_rating_have_no_key,
   225     PEP_rating_unencrypted,
   226     PEP_rating_unencrypted_for_some,
   227     PEP_rating_unreliable,
   228     PEP_rating_reliable,
   229     PEP_rating_trusted,
   230     PEP_rating_trusted_and_anonymized,
   231     PEP_rating_fully_anonymous,   
   232 
   233     PEP_rating_mistrust = -1,
   234     PEP_rating_b0rken = -2,
   235     PEP_rating_under_attack = -3
   236 } PEP_rating;
   237 
   238 typedef enum _PEP_color {
   239     PEP_color_no_color = 0,
   240     PEP_color_yellow,
   241     PEP_color_green,
   242     PEP_color_red = -1,
   243 } PEP_color;
   244 
   245 
   246 // color_from_rating - calculate color from rating
   247 //
   248 //  parameters:
   249 //      rating (in)         rating
   250 //
   251 //  return value:           color representing that rating
   252 DYNAMIC_API PEP_color color_from_rating(PEP_rating rating);
   253 
   254 typedef enum _PEP_decrypt_flags {
   255     PEP_decrypt_flag_own_private_key = 0x1,
   256     PEP_decrypt_flag_consume = 0x2,
   257     PEP_decrypt_flag_ignore = 0x4,
   258     PEP_decrypt_flag_src_modified = 0x8,
   259     // input flags    
   260     PEP_decrypt_flag_untrusted_server = 0x100
   261 } PEP_decrypt_flags; 
   262 
   263 typedef unsigned int PEP_decrypt_flags_t;
   264 
   265 
   266 // decrypt_message() - decrypt message in memory
   267 //
   268 //  parameters:
   269 //      session (in)        session handle
   270 //      src (inout)         message to decrypt
   271 //      dst (out)           pointer to new decrypted message or NULL on failure
   272 //      keylist (inout)     in: stringlist with additional keyids for reencryption if needed
   273 //                              (will be freed and replaced with output keylist) 
   274 //                          out: stringlist with keyids used for signing and encryption. first
   275 //                               first key is signer, additional keys are the ones it was encrypted
   276 //                               to. Only signer and whichever of the user's keys was used are 
   277 //                               reliable
   278 //      rating (out)        rating for the message
   279 //      flags (inout)       flags to signal special decryption features
   280 //
   281 //  return value:
   282 //      error status 
   283 //      or PEP_DECRYPTED if message decrypted but not verified
   284 //      or PEP_CANNOT_REENCRYPT if message was decrypted (and possibly
   285 //         verified) but a reencryption operation is expected by the caller
   286 //         and failed
   287 //      or PEP_STATUS_OK on success
   288 //
   289 //  flag values:
   290 //      in:
   291 //          PEP_decrypt_flag_untrusted_server
   292 //              used to signal that decrypt function should engage in behaviour
   293 //              specified for when the server storing the source is untrusted
   294 //      out:
   295 //          PEP_decrypt_flag_own_private_key
   296 //              private key was imported for one of our addresses (NOT trusted
   297 //              or set to be used - handshake/trust is required for that)
   298 //          PEP_decrypt_flag_src_modified
   299 //              indicates that the src object has been modified. At the moment,
   300 //              this is always as a direct result of the behaviour driven
   301 //              by the input flags. This flag is the ONLY value that should be
   302 //              relied upon to see if such changes have taken place.
   303 //          PEP_decrypt_flag_consume
   304 //              used by sync 
   305 //          PEP_decrypt_flag_ignore
   306 //              used by sync 
   307 //
   308 //
   309 // caveat:
   310 //      the ownership of src remains with the caller - however, the contents 
   311 //          might be modified (strings freed and allocated anew or set to NULL,
   312 //          etc) intentionally; when this happens, PEP_decrypt_flag_src_modified
   313 //          is set.
   314 //      the ownership of dst goes to the caller
   315 //      the ownership of keylist goes to the caller
   316 //      if src is unencrypted this function returns PEP_UNENCRYPTED and sets
   317 //         dst to NULL
   318 DYNAMIC_API PEP_STATUS decrypt_message(
   319         PEP_SESSION session,
   320         message *src,
   321         message **dst,
   322         stringlist_t **keylist,
   323         PEP_rating *rating,
   324         PEP_decrypt_flags_t *flags
   325 );
   326 
   327 
   328 // MIME_decrypt_message() - decrypt a MIME message, with MIME output
   329 //
   330 //  parameters:
   331 //      session (in)            session handle
   332 //      mimetext (in)           MIME encoded text to decrypt
   333 //      size (in)               size of mime text to decode (in order to decrypt)
   334 //      mime_plaintext (out)    decrypted, encoded message
   335 //      keylist (inout)         in: stringlist with additional keyids for reencryption if needed
   336 //                                  (will be freed and replaced with output keylist)
   337 //                              out: stringlist with keyids
   338 //      rating (out)            rating for the message
   339 //      flags (inout)           flags to signal special decryption features (see below)
   340 //      modified_src (out)      modified source string, if decrypt had reason to change it
   341 //
   342 //  return value:
   343 //      decrypt status          if everything worked with MIME encode/decode, 
   344 //                              the status of the decryption is returned 
   345 //                              (PEP_STATUS_OK or decryption error status)
   346 //      PEP_BUFFER_TOO_SMALL    if encoded message size is too big to handle
   347 //      PEP_CANNOT_CREATE_TEMP_FILE
   348 //                              if there are issues with temp files; in
   349 //                              this case errno will contain the underlying
   350 //                              error
   351 //      PEP_OUT_OF_MEMORY       if not enough memory could be allocated
   352 //
   353 //  flag values:
   354 //      in:
   355 //          PEP_decrypt_flag_untrusted_server
   356 //              used to signal that decrypt function should engage in behaviour
   357 //              specified for when the server storing the source is untrusted.
   358 //      out:
   359 //          PEP_decrypt_flag_own_private_key
   360 //              private key was imported for one of our addresses (NOT trusted
   361 //              or set to be used - handshake/trust is required for that)
   362 //          PEP_decrypt_flag_src_modified
   363 //              indicates that the modified_src field should contain a modified
   364 //              version of the source, at the moment always as a result of the
   365 //              input flags. 
   366 //          PEP_decrypt_flag_consume
   367 //              used by sync 
   368 //          PEP_decrypt_flag_ignore
   369 //              used by sync 
   370 // 
   371 //  caveat:
   372 //      the decrypted, encoded mime text will go to the ownership of the caller; mimetext
   373 //      will remain in the ownership of the caller
   374 DYNAMIC_API PEP_STATUS MIME_decrypt_message(
   375     PEP_SESSION session,
   376     const char *mimetext,
   377     size_t size,
   378     char** mime_plaintext,
   379     stringlist_t **keylist,
   380     PEP_rating *rating,
   381     PEP_decrypt_flags_t *flags,
   382     char** modified_src
   383 );
   384 
   385 
   386 // own_message_private_key_details() - details on own key in own message
   387 //
   388 //  parameters:
   389 //      session (in)        session handle
   390 //      msg (in)            message to decrypt
   391 //      ident (out)         identity containing uid, address and fpr of key
   392 //
   393 //  note:
   394 //      In order to obtain details about key to be possibly imported
   395 //      as a replacement of key currently used as own identity, 
   396 //      application passes message that have been previously flagged by 
   397 //      decrypt_message() as own message containing own key to this function
   398 //
   399 //  return value:
   400 //      error status or PEP_STATUS_OK on success
   401 //
   402 //  caveat:
   403 //      the ownership of msg remains with the caller
   404 //      the ownership of ident goes to the caller
   405 //      msg MUST be encrypted so that this function can check own signature
   406 DYNAMIC_API PEP_STATUS own_message_private_key_details(
   407         PEP_SESSION session,
   408         message *msg,
   409         pEp_identity **ident 
   410 );
   411 
   412 
   413 // outgoing_message_rating() - get rating for an outgoing message
   414 //
   415 //  parameters:
   416 //      session (in)        session handle
   417 //      msg (in)            message to get the rating for
   418 //      rating (out)        rating for the message
   419 //
   420 //  return value:
   421 //      error status or PEP_STATUS_OK on success
   422 //
   423 //  caveat:
   424 //      msg->from must point to a valid pEp_identity
   425 //      msg->dir must be PEP_dir_outgoing
   426 //      the ownership of msg remains with the caller
   427 DYNAMIC_API PEP_STATUS outgoing_message_rating(
   428         PEP_SESSION session,
   429         message *msg,
   430         PEP_rating *rating
   431     );
   432 
   433 
   434 // identity_rating() - get rating for a single identity
   435 //
   436 //  parameters:
   437 //      session (in)        session handle
   438 //      ident (in)          identity to get the rating for
   439 //      rating (out)        rating for the identity
   440 //
   441 //  return value:
   442 //      error status or PEP_STATUS_OK on success
   443 //
   444 //  caveat:
   445 //      the ownership of ident remains with the caller
   446 DYNAMIC_API PEP_STATUS identity_rating(
   447         PEP_SESSION session,
   448         pEp_identity *ident,
   449         PEP_rating *rating
   450     );
   451 
   452 
   453 // get_binary_path() - retrieve path of cryptotech binary if available
   454 //
   455 //  parameters:
   456 //      tech (in)           cryptotech to get the binary for
   457 //      path (out)          path to cryptotech binary or NULL if not available
   458 //                          **path is owned by the library, do not change it!
   459 DYNAMIC_API PEP_STATUS get_binary_path(PEP_cryptotech tech, const char **path);
   460 
   461 
   462 // get_trustwords() - get full trustwords string for a *pair* of identities
   463 //
   464 //    parameters:
   465 //        session (in)        session handle
   466 //        id1 (in)            identity of first party in communication - fpr can't be NULL  
   467 //        id2 (in)            identity of second party in communication - fpr can't be NULL
   468 //        lang (in)           C string with ISO 639-1 language code
   469 //        words (out)         pointer to C string with all trustwords UTF-8 encoded,
   470 //                            separated by a blank each
   471 //                            NULL if language is not supported or trustword
   472 //                            wordlist is damaged or unavailable
   473 //        wsize (out)         length of full trustwords string
   474 //        full (in)           if true, generate ALL trustwords for these identities.
   475 //                            else, generate a fixed-size subset. (TODO: fixed-minimum-entropy
   476 //                            subset in next version)
   477 //
   478 //    return value:
   479 //        PEP_STATUS_OK            trustwords retrieved
   480 //        PEP_OUT_OF_MEMORY        out of memory
   481 //        PEP_TRUSTWORD_NOT_FOUND  at least one trustword not found
   482 //
   483 //    caveat:
   484 //        the word pointer goes to the ownership of the caller
   485 //        the caller is responsible to free() it (on Windoze use pEp_free())
   486 //
   487 DYNAMIC_API PEP_STATUS get_trustwords(
   488     PEP_SESSION session, const pEp_identity* id1, const pEp_identity* id2,
   489     const char* lang, char **words, size_t *wsize, bool full
   490 );
   491 
   492 
   493 // get_message_trustwords() - get full trustwords string for message sender and reciever identities 
   494 //
   495 //    parameters:
   496 //        session (in)        session handle
   497 //        msg (in)            message to get sender identity from
   498 //        keylist (in)        NULL if message to be decrypted,
   499 //                            keylist returned by decrypt_message() otherwise
   500 //        received_by (in)    identity for account receiving message can't be NULL
   501 //        lang (in)           C string with ISO 639-1 language code
   502 //        words (out)         pointer to C string with all trustwords UTF-8 encoded,
   503 //                            separated by a blank each
   504 //                            NULL if language is not supported or trustword
   505 //                            wordlist is damaged or unavailable
   506 //        full (in)           if true, generate ALL trustwords for these identities.
   507 //                            else, generate a fixed-size subset. (TODO: fixed-minimum-entropy
   508 //                            subset in next version)
   509 //
   510 //    return value:
   511 //        PEP_STATUS_OK            trustwords retrieved
   512 //        PEP_OUT_OF_MEMORY        out of memory
   513 //        PEP_TRUSTWORD_NOT_FOUND  at least one trustword not found
   514 //        error status of decrypt_message() if decryption fails.
   515 //
   516 //    caveat:
   517 //        the word pointer goes to the ownership of the caller
   518 //        the caller is responsible to free() it (on Windoze use pEp_free())
   519 //
   520 DYNAMIC_API PEP_STATUS get_message_trustwords(
   521     PEP_SESSION session, 
   522     message *msg,
   523     stringlist_t *keylist,
   524     pEp_identity* received_by,
   525     const char* lang, char **words, bool full
   526 );
   527 
   528 // re_evaluate_message_rating() - re-evaluate already decrypted message rating
   529 //
   530 //  parameters:
   531 //      session (in)            session handle
   532 //      msg (in)                message to get the rating for
   533 //      x_keylist (in)          decrypted message recipients keys fpr
   534 //      x_enc_status (in)       original rating for the decrypted message
   535 //      rating (out)            rating for the message
   536 //
   537 //  return value:
   538 //      PEP_ILLEGAL_VALUE       if decrypted message doesn't contain 
   539 //                              X-EncStatus optional field and x_enc_status is 
   540 //                              pEp_rating_udefined
   541 //                              or if decrypted message doesn't contain 
   542 //                              X-Keylist optional field and x_keylist is NULL
   543 //      PEP_OUT_OF_MEMORY       if not enough memory could be allocated
   544 //
   545 //  caveat:
   546 //      msg->from must point to a valid pEp_identity
   547 //      the ownership of msg remains with the caller
   548 //	    the ownership of x_keylist remains with to the caller
   549 
   550 DYNAMIC_API PEP_STATUS re_evaluate_message_rating(
   551     PEP_SESSION session,
   552     message *msg,
   553     stringlist_t *x_keylist,
   554     PEP_rating x_enc_status,
   555     PEP_rating *rating
   556 );
   557 #ifdef __cplusplus
   558 }
   559 #endif