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