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