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