src/message_api.h
author Volker Birk <vb@pep-project.org>
Sat, 25 May 2019 13:41:57 +0200
branchsync
changeset 3743 a66f640552a4
parent 3475 71e0a8ae558f
child 3803 26b82716fb60
child 3875 01d0bda44169
permissions -rw-r--r--
adding get_trustwords_for_fprs()
     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         PEP_SESSION session, 
    17         message *msg,
    18         identity_list **private_idents
    19     );
    20 
    21 void attach_own_key(PEP_SESSION session, message *msg);
    22 
    23 PEP_cryptotech determine_encryption_format(message *msg);
    24 
    25 void add_opt_field(message *msg, const char *name, const char *value);
    26 
    27 typedef enum _PEP_encrypt_flags {
    28     // "default" means whatever the default behaviour for the function is.
    29     PEP_encrypt_flag_default = 0x0,
    30     PEP_encrypt_flag_force_encryption = 0x1,
    31 
    32     // This flag is for special use cases and should not be used
    33     // by normal pEp clients!
    34     PEP_encrypt_flag_force_unsigned = 0x2,
    35     PEP_encrypt_flag_force_no_attached_key = 0x4,
    36     
    37     // This is used for outer messages (used to wrap the real message)
    38     // This is only used internally and (eventually) by transport functions
    39     PEP_encrypt_flag_inner_message = 0x8,
    40     
    41     // This is mainly used by pEp clients to send private keys to 
    42     // their own PGP-only device
    43     PEP_encrypt_flag_force_version_1 = 0x10,
    44     
    45     PEP_encrypt_flag_key_reset_only = 0x20
    46     
    47 } PEP_encrypt_flags; 
    48 
    49 typedef unsigned int PEP_encrypt_flags_t;
    50 
    51 typedef enum _message_wrap_type {
    52     PEP_message_default,    // typical inner/outer message 2.0
    53     PEP_message_transport,  // e.g. for onion layers
    54     PEP_message_key_reset   // for wrapped key reset information
    55 } message_wrap_type;
    56 
    57 // encrypt_message() - encrypt message in memory
    58 //
    59 //  parameters:
    60 //      session (in)        session handle
    61 //      src (inout)         message to encrypt - usually in-only, but can be 
    62 //                          in-out for unencrypted messages; in that case, 
    63 //                          we may attach the key and decorate the message
    64 //      extra (in)          extra keys for encryption
    65 //      dst (out)           pointer to new encrypted message or NULL if no
    66 //                          encryption could take place
    67 //      enc_format (in)     encrypted format
    68 //      flags (in)          flags to set special encryption features
    69 //
    70 //  return value:
    71 //      PEP_STATUS_OK                   on success
    72 //      PEP_KEY_HAS_AMBIG_NAME          at least one of the receipient keys has
    73 //                                      an ambiguous name
    74 //      PEP_UNENCRYPTED                 on demand or no recipients with usable
    75 //                                      key, is left unencrypted, and key is
    76 //                                      attached to it
    77 //
    78 //  caveat:
    79 //      the ownership of src remains with the caller
    80 //      the ownership of dst goes to the caller
    81 
    82 DYNAMIC_API PEP_STATUS encrypt_message(
    83         PEP_SESSION session,
    84         message *src,
    85         stringlist_t *extra,
    86         message **dst,
    87         PEP_enc_format enc_format,
    88         PEP_encrypt_flags_t flags
    89     );
    90 
    91 
    92 // encrypt_message_and_add_priv_key() - encrypt message in memory, adding an encrypted private
    93 //                                      key (encrypted separately and sent within the inner message)
    94 //
    95 //  parameters:
    96 //      session (in)        session handle
    97 //      src (in)            message to encrypt
    98 //      dst (out)           pointer to new encrypted message or NULL if no
    99 //                          encryption could take place
   100 //      to_fpr              fingerprint of the recipient key to which the private key
   101 //                          should be encrypted
   102 //      enc_format (in)     encrypted format
   103 //      flags (in)          flags to set special encryption features
   104 //
   105 //  return value:
   106 //      PEP_STATUS_OK                   on success
   107 //      PEP_KEY_HAS_AMBIG_NAME          at least one of the receipient keys has
   108 //                                      an ambiguous name
   109 //      PEP_UNENCRYPTED                 on demand or no recipients with usable
   110 //                                      key, is left unencrypted, and key is
   111 //                                      attached to it
   112 //
   113 //  caveat:
   114 //      the ownershop of src remains with the caller
   115 //      the ownership of dst goes to the caller
   116 DYNAMIC_API PEP_STATUS encrypt_message_and_add_priv_key(
   117         PEP_SESSION session,
   118         message *src,
   119         message **dst,
   120         const char* to_fpr,
   121         PEP_enc_format enc_format,
   122         PEP_encrypt_flags_t flags
   123     );
   124 
   125 
   126 // encrypt_message_for_self() - encrypt message in memory for user's identity only,
   127 //                              ignoring recipients and other identities from
   128 //                              the message
   129 //  parameters:
   130 //      session (in)        session handle
   131 //      target_id (in)      self identity this message should be encrypted for
   132 //      src (in)            message to encrypt
   133 //      extra (in)          extra keys for encryption
   134 //      dst (out)           pointer to new encrypted message or NULL on failure
   135 //      enc_format (in)     encrypted format
   136 //      flags (in)          flags to set special encryption features
   137 //
   138 //  return value:       (FIXME: This may not be correct or complete)
   139 //      PEP_STATUS_OK            on success
   140 //      PEP_KEY_NOT_FOUND        at least one of the receipient keys
   141 //                               could not be found
   142 //      PEP_KEY_HAS_AMBIG_NAME   at least one of the receipient keys has
   143 //                               an ambiguous name
   144 //      PEP_GET_KEY_FAILED       cannot retrieve key
   145 //
   146 //  caveat:
   147 //      the ownership of src remains with the caller
   148 //      the ownership of target_id remains w/ caller            
   149 //      the ownership of dst goes to the caller
   150 //      message is NOT encrypted for identities other than the target_id (and then,
   151 //      only if the target_id refers to self!)
   152 DYNAMIC_API PEP_STATUS encrypt_message_for_self(
   153         PEP_SESSION session,
   154         pEp_identity* target_id,
   155         message *src,
   156         stringlist_t* extra,
   157         message **dst,
   158         PEP_enc_format enc_format,
   159         PEP_encrypt_flags_t flags
   160     );
   161 
   162 typedef enum _PEP_rating {
   163     PEP_rating_undefined = 0,
   164     PEP_rating_cannot_decrypt,
   165     PEP_rating_have_no_key,
   166     PEP_rating_unencrypted,
   167     PEP_rating_unencrypted_for_some, // don't use this any more
   168     PEP_rating_unreliable,
   169     PEP_rating_reliable,
   170     PEP_rating_trusted,
   171     PEP_rating_trusted_and_anonymized,
   172     PEP_rating_fully_anonymous,   
   173 
   174     PEP_rating_mistrust = -1,
   175     PEP_rating_b0rken = -2,
   176     PEP_rating_under_attack = -3
   177 } PEP_rating;
   178 
   179 typedef enum _PEP_color {
   180     PEP_color_no_color = 0,
   181     PEP_color_yellow,
   182     PEP_color_green,
   183     PEP_color_red = -1,
   184 } PEP_color;
   185 
   186 
   187 // color_from_rating - calculate color from rating
   188 //
   189 //  parameters:
   190 //      rating (in)         rating
   191 //
   192 //  return value:           color representing that rating
   193 DYNAMIC_API PEP_color color_from_rating(PEP_rating rating);
   194 
   195 typedef enum _PEP_decrypt_flags {
   196     PEP_decrypt_flag_own_private_key = 0x1,
   197     PEP_decrypt_flag_consume = 0x2,
   198     PEP_decrypt_flag_ignore = 0x4,
   199     PEP_decrypt_flag_src_modified = 0x8,
   200     // input flags    
   201     PEP_decrypt_flag_untrusted_server = 0x100,
   202     PEP_decrypt_flag_dont_trigger_sync = 0x200,
   203 } PEP_decrypt_flags; 
   204 
   205 typedef unsigned int PEP_decrypt_flags_t;
   206 
   207 
   208 // decrypt_message() - decrypt message in memory
   209 //
   210 //  parameters:
   211 //      session (in)        session handle
   212 //      src (inout)         message to decrypt
   213 //      dst (out)           pointer to new decrypted message or NULL on failure
   214 //      keylist (inout)     in: stringlist with additional keyids for reencryption if needed
   215 //                              (will be freed and replaced with output keylist) 
   216 //                          out: stringlist with keyids used for signing and encryption. first
   217 //                               first key is signer, additional keys are the ones it was encrypted
   218 //                               to. Only signer and whichever of the user's keys was used are 
   219 //                               reliable
   220 //      rating (out)        rating for the message
   221 //      flags (inout)       flags to signal special decryption features
   222 //
   223 //  return value:
   224 //      error status 
   225 //      or PEP_DECRYPTED if message decrypted but not verified
   226 //      or PEP_CANNOT_REENCRYPT if message was decrypted (and possibly
   227 //         verified) but a reencryption operation is expected by the caller
   228 //         and failed
   229 //      or PEP_STATUS_OK on success
   230 //
   231 //  flag values:
   232 //      in:
   233 //          PEP_decrypt_flag_untrusted_server
   234 //              used to signal that decrypt function should engage in behaviour
   235 //              specified for when the server storing the source is untrusted
   236 //      out:
   237 //          PEP_decrypt_flag_own_private_key
   238 //              private key was imported for one of our addresses (NOT trusted
   239 //              or set to be used - handshake/trust is required for that)
   240 //          PEP_decrypt_flag_src_modified
   241 //              indicates that the src object has been modified. At the moment,
   242 //              this is always as a direct result of the behaviour driven
   243 //              by the input flags. This flag is the ONLY value that should be
   244 //              relied upon to see if such changes have taken place.
   245 //          PEP_decrypt_flag_consume
   246 //              used by sync 
   247 //          PEP_decrypt_flag_ignore
   248 //              used by sync 
   249 //
   250 //
   251 // caveat:
   252 //      the ownership of src remains with the caller - however, the contents 
   253 //          might be modified (strings freed and allocated anew or set to NULL,
   254 //          etc) intentionally; when this happens, PEP_decrypt_flag_src_modified
   255 //          is set.
   256 //      the ownership of dst goes to the caller
   257 //      the ownership of keylist goes to the caller
   258 //      if src is unencrypted this function returns PEP_UNENCRYPTED and sets
   259 //         dst to NULL
   260 DYNAMIC_API PEP_STATUS decrypt_message(
   261         PEP_SESSION session,
   262         message *src,
   263         message **dst,
   264         stringlist_t **keylist,
   265         PEP_rating *rating,
   266         PEP_decrypt_flags_t *flags
   267 );
   268 
   269 // own_message_private_key_details() - details on own key in own message
   270 //
   271 //  parameters:
   272 //      session (in)        session handle
   273 //      msg (in)            message to decrypt
   274 //      ident (out)         identity containing uid, address and fpr of key
   275 //
   276 //  note:
   277 //      In order to obtain details about key to be possibly imported
   278 //      as a replacement of key currently used as own identity, 
   279 //      application passes message that have been previously flagged by 
   280 //      decrypt_message() as own message containing own key to this function
   281 //
   282 //  return value:
   283 //      error status or PEP_STATUS_OK on success
   284 //
   285 //  caveat:
   286 //      the ownership of msg remains with the caller
   287 //      the ownership of ident goes to the caller
   288 //      msg MUST be encrypted so that this function can check own signature
   289 DYNAMIC_API PEP_STATUS own_message_private_key_details(
   290         PEP_SESSION session,
   291         message *msg,
   292         pEp_identity **ident 
   293 );
   294 
   295 
   296 // outgoing_message_rating() - get rating for an outgoing message
   297 //
   298 //  parameters:
   299 //      session (in)        session handle
   300 //      msg (in)            message to get the rating for
   301 //      rating (out)        rating for the message
   302 //
   303 //  return value:
   304 //      error status or PEP_STATUS_OK on success
   305 //
   306 //  caveat:
   307 //      msg->from must point to a valid pEp_identity
   308 //      msg->dir must be PEP_dir_outgoing
   309 //      the ownership of msg remains with the caller
   310 DYNAMIC_API PEP_STATUS outgoing_message_rating(
   311         PEP_SESSION session,
   312         message *msg,
   313         PEP_rating *rating
   314     );
   315 
   316 
   317 // outgoing_message_rating_preview() - get rating preview
   318 //
   319 //  parameters:
   320 //      session (in)        session handle
   321 //      msg (in)            message to get the rating for
   322 //      rating (out)        rating preview for the message
   323 //
   324 //  return value:
   325 //      error status or PEP_STATUS_OK on success
   326 //
   327 //  caveat:
   328 //      msg->from must point to a valid pEp_identity
   329 //      msg->dir must be PEP_dir_outgoing
   330 //      the ownership of msg remains with the caller
   331 DYNAMIC_API PEP_STATUS outgoing_message_rating_preview(
   332         PEP_SESSION session,
   333         message *msg,
   334         PEP_rating *rating
   335     );
   336 
   337 // identity_rating() - get rating for a single identity
   338 //
   339 //  parameters:
   340 //      session (in)        session handle
   341 //      ident (in)          identity to get the rating for
   342 //      rating (out)        rating for the identity
   343 //
   344 //  return value:
   345 //      error status or PEP_STATUS_OK on success
   346 //
   347 //  caveat:
   348 //      the ownership of ident remains with the caller
   349 DYNAMIC_API PEP_STATUS identity_rating(
   350         PEP_SESSION session,
   351         pEp_identity *ident,
   352         PEP_rating *rating
   353     );
   354 
   355 
   356 // get_binary_path() - retrieve path of cryptotech binary if available
   357 //
   358 //  parameters:
   359 //      tech (in)           cryptotech to get the binary for
   360 //      path (out)          path to cryptotech binary or NULL if not available
   361 //                          **path is owned by the library, do not change it!
   362 DYNAMIC_API PEP_STATUS get_binary_path(PEP_cryptotech tech, const char **path);
   363 
   364 
   365 // get_trustwords() - get full trustwords string for a *pair* of identities
   366 //
   367 //    parameters:
   368 //        session (in)        session handle
   369 //        id1 (in)            identity of first party in communication - fpr can't be NULL  
   370 //        id2 (in)            identity of second party in communication - fpr can't be NULL
   371 //        lang (in)           C string with ISO 639-1 language code
   372 //        words (out)         pointer to C string with all trustwords UTF-8 encoded,
   373 //                            separated by a blank each
   374 //                            NULL if language is not supported or trustword
   375 //                            wordlist is damaged or unavailable
   376 //        wsize (out)         length of full trustwords string
   377 //        full (in)           if true, generate ALL trustwords for these identities.
   378 //                            else, generate a fixed-size subset. (TODO: fixed-minimum-entropy
   379 //                            subset in next version)
   380 //
   381 //    return value:
   382 //        PEP_STATUS_OK            trustwords retrieved
   383 //        PEP_OUT_OF_MEMORY        out of memory
   384 //        PEP_TRUSTWORD_NOT_FOUND  at least one trustword not found
   385 //
   386 //    caveat:
   387 //        the word pointer goes to the ownership of the caller
   388 //        the caller is responsible to free() it (on Windoze use pEp_free())
   389 //
   390 DYNAMIC_API PEP_STATUS get_trustwords(
   391         PEP_SESSION session, const pEp_identity* id1, const pEp_identity* id2,
   392         const char* lang, char **words, size_t *wsize, bool full
   393     );
   394 
   395 
   396 // get_message_trustwords() - get full trustwords string for message sender and reciever identities 
   397 //
   398 //    parameters:
   399 //        session (in)        session handle
   400 //        msg (in)            message to get sender identity from
   401 //        keylist (in)        NULL if message to be decrypted,
   402 //                            keylist returned by decrypt_message() otherwise
   403 //        received_by (in)    identity for account receiving message can't be NULL
   404 //        lang (in)           C string with ISO 639-1 language code
   405 //        words (out)         pointer to C string with all trustwords UTF-8 encoded,
   406 //                            separated by a blank each
   407 //                            NULL if language is not supported or trustword
   408 //                            wordlist is damaged or unavailable
   409 //        full (in)           if true, generate ALL trustwords for these identities.
   410 //                            else, generate a fixed-size subset. (TODO: fixed-minimum-entropy
   411 //                            subset in next version)
   412 //
   413 //    return value:
   414 //        PEP_STATUS_OK            trustwords retrieved
   415 //        PEP_OUT_OF_MEMORY        out of memory
   416 //        PEP_TRUSTWORD_NOT_FOUND  at least one trustword not found
   417 //        error status of decrypt_message() if decryption fails.
   418 //
   419 //    caveat:
   420 //        the word pointer goes to the ownership of the caller
   421 //        the caller is responsible to free() it (on Windoze use pEp_free())
   422 //
   423 DYNAMIC_API PEP_STATUS get_message_trustwords(
   424         PEP_SESSION session, 
   425         message *msg,
   426         stringlist_t *keylist,
   427         pEp_identity* received_by,
   428         const char* lang, char **words, bool full
   429     );
   430 
   431 // get_trustwords_for_fprs() - get full trustwords string for a pair of fingerprints
   432 //
   433 //    parameters:
   434 //        session (in)        session handle
   435 //        fpr1 (in)           fingerprint 1
   436 //        fpr2 (in)           fingerprint 2
   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_for_fprs(
   457         PEP_SESSION session, const char* fpr1, const char* fpr2,
   458         const char* lang, char **words, size_t *wsize, bool full
   459     );
   460 
   461 // re_evaluate_message_rating() - re-evaluate already decrypted message rating
   462 //
   463 //  parameters:
   464 //      session (in)            session handle
   465 //      msg (in)                message to get the rating for
   466 //      x_keylist (in)          decrypted message recipients keys fpr
   467 //      x_enc_status (in)       original rating for the decrypted message
   468 //      rating (out)            rating for the message
   469 //
   470 //  return value:
   471 //      PEP_ILLEGAL_VALUE       if decrypted message doesn't contain 
   472 //                              X-EncStatus optional field and x_enc_status is 
   473 //                              pEp_rating_udefined
   474 //                              or if decrypted message doesn't contain 
   475 //                              X-Keylist optional field and x_keylist is NULL
   476 //      PEP_OUT_OF_MEMORY       if not enough memory could be allocated
   477 //
   478 //  caveat:
   479 //      msg->from must point to a valid pEp_identity
   480 //      the ownership of msg remains with the caller
   481 //	    the ownership of x_keylist remains with to the caller
   482 
   483 DYNAMIC_API PEP_STATUS re_evaluate_message_rating(
   484     PEP_SESSION session,
   485     message *msg,
   486     stringlist_t *x_keylist,
   487     PEP_rating x_enc_status,
   488     PEP_rating *rating
   489 );
   490 
   491 // get_key_rating_for_user() - get the rating of a certain key for a certain user
   492 //
   493 //  parameters:
   494 //
   495 //      session (in)            session handle
   496 //      user_id (in)            string with user ID
   497 //      fpr (in)                string with fingerprint
   498 //      rating (out)            rating of key for this user
   499 //
   500 //  returns:
   501 //      PEP_RECORD_NOT_FOUND if no trust record for user_id and fpr can be found
   502 
   503 DYNAMIC_API PEP_STATUS get_key_rating_for_user(
   504         PEP_SESSION session,
   505         const char *user_id,
   506         const char *fpr,
   507         PEP_rating *rating
   508     );
   509 
   510 #ifdef __cplusplus
   511 }
   512 #endif