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