src/message_api.h
author Krista Bennett <krista@pep-project.org>
Fri, 04 May 2018 16:30:21 +0200
branchlocal_cpptest
changeset 2652 43b913f99a27
parent 2643 ec3bb2ae2fdf
child 2656 f8d31769b769
permissions -rw-r--r--
Shelving broken things to break other things
     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     
    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 (out)       stringlist with keyids
   273 //      rating (out)        rating for the message
   274 //      flags (inout)       flags to signal special decryption features
   275 //
   276 //  return value:
   277 //      error status 
   278 //      or PEP_DECRYPTED if message decrypted but not verified
   279 //      or PEP_CANNOT_REENCRYPT if message was decrypted (and possibly
   280 //         verified) but a reencryption operation is expected by the caller
   281 //         and failed
   282 //      or PEP_STATUS_OK on success
   283 //
   284 //  flag values:
   285 //      in:
   286 //          PEP_decrypt_flag_untrusted_server
   287 //              used to signal that decrypt function should engage in behaviour
   288 //              specified for when the server storing the source is untrusted
   289 //      out:
   290 //          PEP_decrypt_flag_own_private_key
   291 //              private key was imported for one of our addresses (NOT trusted
   292 //              or set to be used - handshake/trust is required for that)
   293 //          PEP_decrypt_flag_src_modified
   294 //              indicates that the src object has been modified. At the moment,
   295 //              this is always as a direct result of the behaviour driven
   296 //              by the input flags. This flag is the ONLY value that should be
   297 //              relied upon to see if such changes have taken place.
   298 //          PEP_decrypt_flag_consume
   299 //              used by sync 
   300 //          PEP_decrypt_flag_ignore
   301 //              used by sync 
   302 //
   303 //
   304 // caveat:
   305 //      the ownership of src remains with the caller - however, the contents 
   306 //          might be modified (strings freed and allocated anew or set to NULL,
   307 //          etc) intentionally; when this happens, PEP_decrypt_flag_src_modified
   308 //          is set.
   309 //      the ownership of dst goes to the caller
   310 //      the ownership of keylist goes to the caller
   311 //      if src is unencrypted this function returns PEP_UNENCRYPTED and sets
   312 //         dst to NULL
   313 DYNAMIC_API PEP_STATUS decrypt_message(
   314         PEP_SESSION session,
   315         message *src,
   316         message **dst,
   317         stringlist_t **keylist,
   318         PEP_rating *rating,
   319         PEP_decrypt_flags_t *flags
   320 );
   321 
   322 
   323 // MIME_decrypt_message() - decrypt a MIME message, with MIME output
   324 //
   325 //  parameters:
   326 //      session (in)            session handle
   327 //      mimetext (in)           MIME encoded text to decrypt
   328 //      size (in)               size of mime text to decode (in order to decrypt)
   329 //      mime_plaintext (out)    decrypted, encoded message
   330 //      keylist (out)           stringlist with keyids
   331 //      rating (out)            rating for the message
   332 //      flags (inout)           flags to signal special decryption features (see below)
   333 //      modified_src (out)      modified source string, if decrypt had reason to change it
   334 //
   335 //  return value:
   336 //      decrypt status          if everything worked with MIME encode/decode, 
   337 //                              the status of the decryption is returned 
   338 //                              (PEP_STATUS_OK or decryption error status)
   339 //      PEP_BUFFER_TOO_SMALL    if encoded message size is too big to handle
   340 //      PEP_CANNOT_CREATE_TEMP_FILE
   341 //                              if there are issues with temp files; in
   342 //                              this case errno will contain the underlying
   343 //                              error
   344 //      PEP_OUT_OF_MEMORY       if not enough memory could be allocated
   345 //
   346 //  flag values:
   347 //      in:
   348 //          PEP_decrypt_flag_untrusted_server
   349 //              used to signal that decrypt function should engage in behaviour
   350 //              specified for when the server storing the source is untrusted.
   351 //      out:
   352 //          PEP_decrypt_flag_own_private_key
   353 //              private key was imported for one of our addresses (NOT trusted
   354 //              or set to be used - handshake/trust is required for that)
   355 //          PEP_decrypt_flag_src_modified
   356 //              indicates that the modified_src field should contain a modified
   357 //              version of the source, at the moment always as a result of the
   358 //              input flags. 
   359 //          PEP_decrypt_flag_consume
   360 //              used by sync 
   361 //          PEP_decrypt_flag_ignore
   362 //              used by sync 
   363 // 
   364 //  caveat:
   365 //      the decrypted, encoded mime text will go to the ownership of the caller; mimetext
   366 //      will remain in the ownership of the caller
   367 DYNAMIC_API PEP_STATUS MIME_decrypt_message(
   368     PEP_SESSION session,
   369     const char *mimetext,
   370     size_t size,
   371     char** mime_plaintext,
   372     stringlist_t **keylist,
   373     PEP_rating *rating,
   374     PEP_decrypt_flags_t *flags,
   375     char** modified_src
   376 );
   377 
   378 
   379 // own_message_private_key_details() - details on own key in own message
   380 //
   381 //  parameters:
   382 //      session (in)        session handle
   383 //      msg (in)            message to decrypt
   384 //      ident (out)         identity containing uid, address and fpr of key
   385 //
   386 //  note:
   387 //      In order to obtain details about key to be possibly imported
   388 //      as a replacement of key currently used as own identity, 
   389 //      application passes message that have been previously flagged by 
   390 //      decrypt_message() as own message containing own key to this function
   391 //
   392 //  return value:
   393 //      error status or PEP_STATUS_OK on success
   394 //
   395 //  caveat:
   396 //      the ownership of msg remains with the caller
   397 //      the ownership of ident goes to the caller
   398 //      msg MUST be encrypted so that this function can check own signature
   399 DYNAMIC_API PEP_STATUS own_message_private_key_details(
   400         PEP_SESSION session,
   401         message *msg,
   402         pEp_identity **ident 
   403 );
   404 
   405 
   406 // outgoing_message_rating() - get rating for an outgoing message
   407 //
   408 //  parameters:
   409 //      session (in)        session handle
   410 //      msg (in)            message to get the rating for
   411 //      rating (out)        rating for the message
   412 //
   413 //  return value:
   414 //      error status or PEP_STATUS_OK on success
   415 //
   416 //  caveat:
   417 //      msg->from must point to a valid pEp_identity
   418 //      msg->dir must be PEP_dir_outgoing
   419 //      the ownership of msg remains with the caller
   420 DYNAMIC_API PEP_STATUS outgoing_message_rating(
   421         PEP_SESSION session,
   422         message *msg,
   423         PEP_rating *rating
   424     );
   425 
   426 
   427 // identity_rating() - get rating for a single identity
   428 //
   429 //  parameters:
   430 //      session (in)        session handle
   431 //      ident (in)          identity to get the rating for
   432 //      rating (out)        rating for the identity
   433 //
   434 //  return value:
   435 //      error status or PEP_STATUS_OK on success
   436 //
   437 //  caveat:
   438 //      the ownership of ident remains with the caller
   439 DYNAMIC_API PEP_STATUS identity_rating(
   440         PEP_SESSION session,
   441         pEp_identity *ident,
   442         PEP_rating *rating
   443     );
   444 
   445 
   446 // get_binary_path() - retrieve path of cryptotech binary if available
   447 //
   448 //  parameters:
   449 //      tech (in)           cryptotech to get the binary for
   450 //      path (out)          path to cryptotech binary or NULL if not available
   451 //                          **path is owned by the library, do not change it!
   452 DYNAMIC_API PEP_STATUS get_binary_path(PEP_cryptotech tech, const char **path);
   453 
   454 
   455 // get_trustwords() - get full trustwords string for a *pair* of identities
   456 //
   457 //    parameters:
   458 //        session (in)        session handle
   459 //        id1 (in)            identity of first party in communication - fpr can't be NULL  
   460 //        id2 (in)            identity of second party in communication - fpr can't be NULL
   461 //        lang (in)           C string with ISO 639-1 language code
   462 //        words (out)         pointer to C string with all trustwords UTF-8 encoded,
   463 //                            separated by a blank each
   464 //                            NULL if language is not supported or trustword
   465 //                            wordlist is damaged or unavailable
   466 //        wsize (out)         length of full trustwords string
   467 //        full (in)           if true, generate ALL trustwords for these identities.
   468 //                            else, generate a fixed-size subset. (TODO: fixed-minimum-entropy
   469 //                            subset in next version)
   470 //
   471 //    return value:
   472 //        PEP_STATUS_OK            trustwords retrieved
   473 //        PEP_OUT_OF_MEMORY        out of memory
   474 //        PEP_TRUSTWORD_NOT_FOUND  at least one trustword not found
   475 //
   476 //    caveat:
   477 //        the word pointer goes to the ownership of the caller
   478 //        the caller is responsible to free() it (on Windoze use pEp_free())
   479 //
   480 DYNAMIC_API PEP_STATUS get_trustwords(
   481     PEP_SESSION session, const pEp_identity* id1, const pEp_identity* id2,
   482     const char* lang, char **words, size_t *wsize, bool full
   483 );
   484 
   485 
   486 // get_message_trustwords() - get full trustwords string for message sender and reciever identities 
   487 //
   488 //    parameters:
   489 //        session (in)        session handle
   490 //        msg (in)            message to get sender identity from
   491 //        keylist (in)        NULL if message to be decrypted,
   492 //                            keylist returned by decrypt_message() otherwise
   493 //        received_by (in)    identity for account receiving message can't be NULL
   494 //        lang (in)           C string with ISO 639-1 language code
   495 //        words (out)         pointer to C string with all trustwords UTF-8 encoded,
   496 //                            separated by a blank each
   497 //                            NULL if language is not supported or trustword
   498 //                            wordlist is damaged or unavailable
   499 //        full (in)           if true, generate ALL trustwords for these identities.
   500 //                            else, generate a fixed-size subset. (TODO: fixed-minimum-entropy
   501 //                            subset in next version)
   502 //
   503 //    return value:
   504 //        PEP_STATUS_OK            trustwords retrieved
   505 //        PEP_OUT_OF_MEMORY        out of memory
   506 //        PEP_TRUSTWORD_NOT_FOUND  at least one trustword not found
   507 //        error status of decrypt_message() if decryption fails.
   508 //
   509 //    caveat:
   510 //        the word pointer goes to the ownership of the caller
   511 //        the caller is responsible to free() it (on Windoze use pEp_free())
   512 //
   513 DYNAMIC_API PEP_STATUS get_message_trustwords(
   514     PEP_SESSION session, 
   515     message *msg,
   516     stringlist_t *keylist,
   517     pEp_identity* received_by,
   518     const char* lang, char **words, bool full
   519 );
   520 
   521 // re_evaluate_message_rating() - re-evaluate already decrypted message rating
   522 //
   523 //  parameters:
   524 //      session (in)            session handle
   525 //      msg (in)                message to get the rating for
   526 //      x_keylist (in)          decrypted message recipients keys fpr
   527 //      x_enc_status (in)       original rating for the decrypted message
   528 //      rating (out)            rating for the message
   529 //
   530 //  return value:
   531 //      PEP_ILLEGAL_VALUE       if decrypted message doesn't contain 
   532 //                              X-EncStatus optional field and x_enc_status is 
   533 //                              pEp_rating_udefined
   534 //                              or if decrypted message doesn't contain 
   535 //                              X-Keylist optional field and x_keylist is NULL
   536 //      PEP_OUT_OF_MEMORY       if not enough memory could be allocated
   537 //
   538 //  caveat:
   539 //      msg->from must point to a valid pEp_identity
   540 //      the ownership of msg remains with the caller
   541 //	    the ownership of x_keylist remains with to the caller
   542 
   543 DYNAMIC_API PEP_STATUS re_evaluate_message_rating(
   544     PEP_SESSION session,
   545     message *msg,
   546     stringlist_t *x_keylist,
   547     PEP_rating x_enc_status,
   548     PEP_rating *rating
   549 );
   550 #ifdef __cplusplus
   551 }
   552 #endif