src/message_api.h
author Krista 'DarthMama' Bennett <krista@pep.foundation>
Tue, 29 Jan 2019 19:19:30 +0100
branchENGINE-448
changeset 3254 6e7f6bc9460a
parent 3181 f63edcd70676
child 3270 d8aea79654c3
permissions -rw-r--r--
ENGINE-448: made key removal much less aggressive. NetPGP will still be a problem, but versions built against gpg will now only remove actual keys
vb@1513
     1
// This file is under GNU General Public License 3.0
vb@1513
     2
// see LICENSE.txt
vb@1513
     3
vb@39
     4
#pragma once
vb@39
     5
vb@102
     6
#include "pEpEngine.h"
vb@102
     7
#include "keymanagement.h"
vb@101
     8
#include "message.h"
vb@259
     9
#include "cryptotech.h"
vb@101
    10
vb@37
    11
#ifdef __cplusplus
vb@37
    12
extern "C" {
vb@37
    13
#endif
vb@37
    14
Edouard@734
    15
bool import_attached_keys(
krista@2658
    16
    
Edouard@728
    17
        PEP_SESSION session, 
krista@3254
    18
        message *msg,
Edouard@728
    19
        identity_list **private_idents
Edouard@728
    20
    );
roker@1869
    21
vb@236
    22
void attach_own_key(PEP_SESSION session, message *msg);
roker@1869
    23
vb@258
    24
PEP_cryptotech determine_encryption_format(message *msg);
roker@1869
    25
vb@952
    26
void add_opt_field(message *msg, const char *name, const char *value);
Edouard@736
    27
vb@939
    28
typedef enum _PEP_encrypt_flags {
krista@1639
    29
    // "default" means whatever the default behaviour for the function is.
krista@1639
    30
    PEP_encrypt_flag_default = 0x0,
markus@1633
    31
    PEP_encrypt_flag_force_encryption = 0x1,
markus@1633
    32
markus@1633
    33
    // This flag is for special use cases and should not be used
markus@1633
    34
    // by normal pEp clients!
krista@1640
    35
    PEP_encrypt_flag_force_unsigned = 0x2,
krista@2121
    36
    PEP_encrypt_flag_force_no_attached_key = 0x4,
krista@2121
    37
    
krista@2121
    38
    // This is used for outer messages (used to wrap the real message)
krista@2121
    39
    // This is only used internally and (eventually) by transport functions
krista@2770
    40
    PEP_encrypt_flag_inner_message = 0x8,
krista@2770
    41
    
krista@2770
    42
    // This is mainly used by pEp clients to send private keys to 
krista@2770
    43
    // their own PGP-only device
krista@2932
    44
    PEP_encrypt_flag_force_version_1 = 0x10
krista@2612
    45
    
vb@939
    46
} PEP_encrypt_flags; 
vb@939
    47
vb@939
    48
typedef unsigned int PEP_encrypt_flags_t;
vb@235
    49
roker@1869
    50
vb@39
    51
// encrypt_message() - encrypt message in memory
vb@39
    52
//
vb@39
    53
//  parameters:
vb@48
    54
//      session (in)        session handle
krista@3181
    55
//      src (inout)         message to encrypt - usually in-only, but can be 
krista@3181
    56
//                          in-out for unencrypted messages; in that case, 
krista@3181
    57
//                          we may attach the key and decorate the message
vb@48
    58
//      extra (in)          extra keys for encryption
vb@2338
    59
//      dst (out)           pointer to new encrypted message or NULL if no
vb@2338
    60
//                          encryption could take place
vb@84
    61
//      enc_format (in)     encrypted format
vb@939
    62
//      flags (in)          flags to set special encryption features
vb@39
    63
//
vb@39
    64
//  return value:
vb@48
    65
//      PEP_STATUS_OK                   on success
edouard@1854
    66
//      PEP_KEY_HAS_AMBIG_NAME          at least one of the receipient keys has
edouard@1854
    67
//                                      an ambiguous name
vb@2338
    68
//      PEP_UNENCRYPTED                 on demand or no recipients with usable
vb@2338
    69
//                                      key, is left unencrypted, and key is
vb@2338
    70
//                                      attached to it
vb@83
    71
//
roker@1869
    72
//  caveat:
roker@1869
    73
//      the ownershop of src remains with the caller
roker@1869
    74
//      the ownership of dst goes to the caller
vb@44
    75
DYNAMIC_API PEP_STATUS encrypt_message(
vb@37
    76
        PEP_SESSION session,
vb@113
    77
        message *src,
vb@37
    78
        stringlist_t *extra,
vb@38
    79
        message **dst,
vb@939
    80
        PEP_enc_format enc_format,
vb@939
    81
        PEP_encrypt_flags_t flags
vb@37
    82
    );
vb@37
    83
roker@1869
    84
krista@2625
    85
// encrypt_message_and_add_priv_key() - encrypt message in memory, adding an encrypted private
krista@2625
    86
//                                      key (encrypted separately and sent within the inner message)
krista@2625
    87
//
krista@2625
    88
//  parameters:
krista@2625
    89
//      session (in)        session handle
krista@2625
    90
//      src (in)            message to encrypt
krista@2625
    91
//      dst (out)           pointer to new encrypted message or NULL if no
krista@2625
    92
//                          encryption could take place
krista@2643
    93
//      to_fpr              fingerprint of the recipient key to which the private key
krista@2643
    94
//                          should be encrypted
krista@2625
    95
//      enc_format (in)     encrypted format
krista@2625
    96
//      flags (in)          flags to set special encryption features
krista@2625
    97
//
krista@2625
    98
//  return value:
krista@2625
    99
//      PEP_STATUS_OK                   on success
krista@2625
   100
//      PEP_KEY_HAS_AMBIG_NAME          at least one of the receipient keys has
krista@2625
   101
//                                      an ambiguous name
krista@2625
   102
//      PEP_UNENCRYPTED                 on demand or no recipients with usable
krista@2625
   103
//                                      key, is left unencrypted, and key is
krista@2625
   104
//                                      attached to it
krista@2625
   105
//
krista@2625
   106
//  caveat:
krista@2625
   107
//      the ownershop of src remains with the caller
krista@2625
   108
//      the ownership of dst goes to the caller
krista@2592
   109
DYNAMIC_API PEP_STATUS encrypt_message_and_add_priv_key(
krista@2592
   110
        PEP_SESSION session,
krista@2592
   111
        message *src,
krista@2592
   112
        message **dst,
krista@2592
   113
        const char* to_fpr,
krista@2594
   114
        PEP_enc_format enc_format,
krista@2594
   115
        PEP_encrypt_flags_t flags
krista@2592
   116
    );
krista@2592
   117
krista@2592
   118
krista@1034
   119
// encrypt_message_for_self() - encrypt message in memory for user's identity only,
krista@1034
   120
//                              ignoring recipients and other identities from
krista@1034
   121
//                              the message
krista@994
   122
//  parameters:
krista@994
   123
//      session (in)        session handle
krista@995
   124
//      target_id (in)      self identity this message should be encrypted for
krista@994
   125
//      src (in)            message to encrypt
krista@2588
   126
//      extra (in)          extra keys for encryption
krista@994
   127
//      dst (out)           pointer to new encrypted message or NULL on failure
krista@994
   128
//      enc_format (in)     encrypted format
markus@1634
   129
//      flags (in)          flags to set special encryption features
krista@994
   130
//
krista@994
   131
//  return value:       (FIXME: This may not be correct or complete)
roker@1869
   132
//      PEP_STATUS_OK            on success
roker@1869
   133
//      PEP_KEY_NOT_FOUND        at least one of the receipient keys
roker@1869
   134
//                               could not be found
roker@1869
   135
//      PEP_KEY_HAS_AMBIG_NAME   at least one of the receipient keys has
roker@1869
   136
//                               an ambiguous name
roker@1869
   137
//      PEP_GET_KEY_FAILED       cannot retrieve key
krista@994
   138
//
roker@1869
   139
//  caveat:
roker@1869
   140
//      the ownership of src remains with the caller
krista@994
   141
//      the ownership of target_id remains w/ caller            
roker@1869
   142
//      the ownership of dst goes to the caller
krista@995
   143
//      message is NOT encrypted for identities other than the target_id (and then,
roker@1869
   144
//      only if the target_id refers to self!)
krista@995
   145
DYNAMIC_API PEP_STATUS encrypt_message_for_self(
krista@994
   146
        PEP_SESSION session,
krista@994
   147
        pEp_identity* target_id,
krista@994
   148
        message *src,
krista@2588
   149
        stringlist_t* extra,
krista@994
   150
        message **dst,
markus@1633
   151
        PEP_enc_format enc_format,
markus@1633
   152
        PEP_encrypt_flags_t flags
krista@994
   153
    );
vb@39
   154
roker@1869
   155
krista@1325
   156
// MIME_encrypt_message() - encrypt a MIME message, with MIME output
krista@1325
   157
//
krista@1325
   158
//  parameters:
krista@1325
   159
//      session (in)            session handle
krista@1325
   160
//      mimetext (in)           MIME encoded text to encrypt
krista@1331
   161
//      size (in)               size of input mime text
krista@1325
   162
//      extra (in)              extra keys for encryption
krista@1325
   163
//      mime_ciphertext (out)   encrypted, encoded message
krista@1325
   164
//      enc_format (in)         encrypted format
krista@1325
   165
//      flags (in)              flags to set special encryption features
krista@1325
   166
//
krista@1325
   167
//  return value:
krista@1325
   168
//      PEP_STATUS_OK           if everything worked
krista@1325
   169
//      PEP_BUFFER_TOO_SMALL    if encoded message size is too big to handle
krista@1325
   170
//      PEP_CANNOT_CREATE_TEMP_FILE
krista@1325
   171
//                              if there are issues with temp files; in
krista@1325
   172
//                              this case errno will contain the underlying
krista@1325
   173
//                              error
krista@1325
   174
//      PEP_OUT_OF_MEMORY       if not enough memory could be allocated
krista@1325
   175
//
krista@1325
   176
//  caveat:
krista@1325
   177
//      the encrypted, encoded mime text will go to the ownership of the caller; mimetext
krista@1325
   178
//      will remain in the ownership of the caller
krista@1325
   179
DYNAMIC_API PEP_STATUS MIME_encrypt_message(
krista@1325
   180
    PEP_SESSION session,
krista@1325
   181
    const char *mimetext,
krista@1325
   182
    size_t size,
krista@1325
   183
    stringlist_t* extra,
krista@1325
   184
    char** mime_ciphertext,
krista@1325
   185
    PEP_enc_format enc_format,
krista@1325
   186
    PEP_encrypt_flags_t flags
krista@1325
   187
);
krista@1325
   188
roker@1869
   189
krista@1641
   190
// MIME_encrypt_message_for_self() - encrypt MIME message for user's identity only,
krista@1641
   191
//                              ignoring recipients and other identities from
krista@1641
   192
//                              the message, with MIME output
krista@1641
   193
//  parameters:
krista@1641
   194
//      session (in)            session handle
roker@1869
   195
//      target_id (in)          self identity this message should be encrypted for
krista@1641
   196
//      mimetext (in)           MIME encoded text to encrypt
krista@1641
   197
//      size (in)               size of input mime text
krista@2588
   198
//      extra (in)              extra keys for encryption
krista@1641
   199
//      mime_ciphertext (out)   encrypted, encoded message
krista@1641
   200
//      enc_format (in)         encrypted format
krista@1641
   201
//      flags (in)              flags to set special encryption features
krista@1641
   202
//
krista@1641
   203
//  return value:
krista@1641
   204
//      PEP_STATUS_OK           if everything worked
krista@1641
   205
//      PEP_BUFFER_TOO_SMALL    if encoded message size is too big to handle
krista@1641
   206
//      PEP_CANNOT_CREATE_TEMP_FILE
krista@1641
   207
//                              if there are issues with temp files; in
krista@1641
   208
//                              this case errno will contain the underlying
krista@1641
   209
//                              error
krista@1641
   210
//      PEP_OUT_OF_MEMORY       if not enough memory could be allocated
krista@1641
   211
//
krista@1641
   212
//  caveat:
krista@1641
   213
//      the encrypted, encoded mime text will go to the ownership of the caller; mimetext
krista@1641
   214
//      will remain in the ownership of the caller
krista@1641
   215
DYNAMIC_API PEP_STATUS MIME_encrypt_message_for_self(
krista@1641
   216
    PEP_SESSION session,
krista@1641
   217
    pEp_identity* target_id,
krista@1641
   218
    const char *mimetext,
krista@1641
   219
    size_t size,
krista@2588
   220
    stringlist_t* extra,
krista@1641
   221
    char** mime_ciphertext,
krista@1641
   222
    PEP_enc_format enc_format,
krista@1641
   223
    PEP_encrypt_flags_t flags
krista@1641
   224
);
krista@1641
   225
krista@1641
   226
vb@1004
   227
typedef enum _PEP_rating {
vb@237
   228
    PEP_rating_undefined = 0,
vb@256
   229
    PEP_rating_cannot_decrypt,
vb@267
   230
    PEP_rating_have_no_key,
vb@237
   231
    PEP_rating_unencrypted,
vb@486
   232
    PEP_rating_unencrypted_for_some,
vb@237
   233
    PEP_rating_unreliable,
vb@237
   234
    PEP_rating_reliable,
vb@237
   235
    PEP_rating_trusted,
vb@237
   236
    PEP_rating_trusted_and_anonymized,
vb@237
   237
    PEP_rating_fully_anonymous,   
vb@189
   238
Edouard@442
   239
    PEP_rating_mistrust = -1,
Edouard@442
   240
    PEP_rating_b0rken = -2,
vb@436
   241
    PEP_rating_under_attack = -3
vb@1004
   242
} PEP_rating;
vb@1004
   243
vb@1004
   244
typedef enum _PEP_color {
vb@1004
   245
    PEP_color_no_color = 0,
vb@1004
   246
    PEP_color_yellow,
vb@1004
   247
    PEP_color_green,
vb@1004
   248
    PEP_color_red = -1,
vb@232
   249
} PEP_color;
vb@189
   250
roker@1869
   251
vb@1007
   252
// color_from_rating - calculate color from rating
vb@1007
   253
//
vb@1007
   254
//  parameters:
vb@1007
   255
//      rating (in)         rating
vb@1007
   256
//
vb@1007
   257
//  return value:           color representing that rating
vb@1004
   258
DYNAMIC_API PEP_color color_from_rating(PEP_rating rating);
vb@1004
   259
Edouard@728
   260
typedef enum _PEP_decrypt_flags {
edouard@1355
   261
    PEP_decrypt_flag_own_private_key = 0x1,
edouard@1369
   262
    PEP_decrypt_flag_consume = 0x2,
krista@2623
   263
    PEP_decrypt_flag_ignore = 0x4,
krista@2623
   264
    PEP_decrypt_flag_src_modified = 0x8,
krista@2623
   265
    // input flags    
krista@2623
   266
    PEP_decrypt_flag_untrusted_server = 0x100
Edouard@728
   267
} PEP_decrypt_flags; 
Edouard@728
   268
vb@939
   269
typedef unsigned int PEP_decrypt_flags_t;
Edouard@728
   270
roker@1869
   271
vb@251
   272
// decrypt_message() - decrypt message in memory
vb@251
   273
//
vb@251
   274
//  parameters:
vb@251
   275
//      session (in)        session handle
krista@2624
   276
//      src (inout)         message to decrypt
vb@251
   277
//      dst (out)           pointer to new decrypted message or NULL on failure
krista@2658
   278
//      keylist (inout)     in: stringlist with additional keyids for reencryption if needed
krista@2656
   279
//                              (will be freed and replaced with output keylist) 
krista@2759
   280
//                          out: stringlist with keyids used for signing and encryption. first
krista@2759
   281
//                               first key is signer, additional keys are the ones it was encrypted
krista@2759
   282
//                               to. Only signer and whichever of the user's keys was used are 
krista@2759
   283
//                               reliable
roker@1218
   284
//      rating (out)        rating for the message
krista@2624
   285
//      flags (inout)       flags to signal special decryption features
vb@251
   286
//
vb@251
   287
//  return value:
edouard@1858
   288
//      error status 
edouard@1858
   289
//      or PEP_DECRYPTED if message decrypted but not verified
krista@2624
   290
//      or PEP_CANNOT_REENCRYPT if message was decrypted (and possibly
krista@2624
   291
//         verified) but a reencryption operation is expected by the caller
krista@2624
   292
//         and failed
edouard@1858
   293
//      or PEP_STATUS_OK on success
vb@251
   294
//
krista@2624
   295
//  flag values:
krista@2624
   296
//      in:
krista@2624
   297
//          PEP_decrypt_flag_untrusted_server
krista@2624
   298
//              used to signal that decrypt function should engage in behaviour
krista@2624
   299
//              specified for when the server storing the source is untrusted
krista@2624
   300
//      out:
krista@2624
   301
//          PEP_decrypt_flag_own_private_key
krista@2624
   302
//              private key was imported for one of our addresses (NOT trusted
krista@2624
   303
//              or set to be used - handshake/trust is required for that)
krista@2624
   304
//          PEP_decrypt_flag_src_modified
krista@2624
   305
//              indicates that the src object has been modified. At the moment,
krista@2624
   306
//              this is always as a direct result of the behaviour driven
krista@2624
   307
//              by the input flags. This flag is the ONLY value that should be
krista@2624
   308
//              relied upon to see if such changes have taken place.
krista@2624
   309
//          PEP_decrypt_flag_consume
krista@2624
   310
//              used by sync 
krista@2624
   311
//          PEP_decrypt_flag_ignore
krista@2624
   312
//              used by sync 
krista@2624
   313
//
krista@2624
   314
//
roker@1869
   315
// caveat:
krista@2624
   316
//      the ownership of src remains with the caller - however, the contents 
krista@2624
   317
//          might be modified (strings freed and allocated anew or set to NULL,
krista@2624
   318
//          etc) intentionally; when this happens, PEP_decrypt_flag_src_modified
krista@2624
   319
//          is set.
roker@1869
   320
//      the ownership of dst goes to the caller
roker@1869
   321
//      the ownership of keylist goes to the caller
roker@1869
   322
//      if src is unencrypted this function returns PEP_UNENCRYPTED and sets
krista@2624
   323
//         dst to NULL
vb@251
   324
DYNAMIC_API PEP_STATUS decrypt_message(
vb@251
   325
        PEP_SESSION session,
vb@251
   326
        message *src,
vb@251
   327
        message **dst,
vb@251
   328
        stringlist_t **keylist,
vb@1004
   329
        PEP_rating *rating,
vb@939
   330
        PEP_decrypt_flags_t *flags
Edouard@728
   331
);
vb@251
   332
roker@1869
   333
krista@1325
   334
// MIME_decrypt_message() - decrypt a MIME message, with MIME output
krista@1325
   335
//
krista@1325
   336
//  parameters:
krista@1325
   337
//      session (in)            session handle
krista@1325
   338
//      mimetext (in)           MIME encoded text to decrypt
krista@1331
   339
//      size (in)               size of mime text to decode (in order to decrypt)
krista@1325
   340
//      mime_plaintext (out)    decrypted, encoded message
krista@2658
   341
//      keylist (inout)         in: stringlist with additional keyids for reencryption if needed
krista@2658
   342
//                                  (will be freed and replaced with output keylist)
krista@2658
   343
//                              out: stringlist with keyids
krista@1325
   344
//      rating (out)            rating for the message
krista@2624
   345
//      flags (inout)           flags to signal special decryption features (see below)
krista@2623
   346
//      modified_src (out)      modified source string, if decrypt had reason to change it
krista@1325
   347
//
krista@1325
   348
//  return value:
krista@1644
   349
//      decrypt status          if everything worked with MIME encode/decode, 
krista@1644
   350
//                              the status of the decryption is returned 
krista@1644
   351
//                              (PEP_STATUS_OK or decryption error status)
krista@1325
   352
//      PEP_BUFFER_TOO_SMALL    if encoded message size is too big to handle
krista@1325
   353
//      PEP_CANNOT_CREATE_TEMP_FILE
krista@1325
   354
//                              if there are issues with temp files; in
krista@1325
   355
//                              this case errno will contain the underlying
krista@1325
   356
//                              error
krista@1325
   357
//      PEP_OUT_OF_MEMORY       if not enough memory could be allocated
krista@1325
   358
//
krista@2624
   359
//  flag values:
krista@2624
   360
//      in:
krista@2624
   361
//          PEP_decrypt_flag_untrusted_server
krista@2624
   362
//              used to signal that decrypt function should engage in behaviour
krista@2624
   363
//              specified for when the server storing the source is untrusted.
krista@2624
   364
//      out:
krista@2624
   365
//          PEP_decrypt_flag_own_private_key
krista@2624
   366
//              private key was imported for one of our addresses (NOT trusted
krista@2624
   367
//              or set to be used - handshake/trust is required for that)
krista@2624
   368
//          PEP_decrypt_flag_src_modified
krista@2624
   369
//              indicates that the modified_src field should contain a modified
krista@2624
   370
//              version of the source, at the moment always as a result of the
krista@2624
   371
//              input flags. 
krista@2624
   372
//          PEP_decrypt_flag_consume
krista@2624
   373
//              used by sync 
krista@2624
   374
//          PEP_decrypt_flag_ignore
krista@2624
   375
//              used by sync 
krista@2624
   376
// 
krista@1325
   377
//  caveat:
krista@1325
   378
//      the decrypted, encoded mime text will go to the ownership of the caller; mimetext
krista@1325
   379
//      will remain in the ownership of the caller
krista@1325
   380
DYNAMIC_API PEP_STATUS MIME_decrypt_message(
krista@1325
   381
    PEP_SESSION session,
krista@1325
   382
    const char *mimetext,
krista@1325
   383
    size_t size,
krista@1325
   384
    char** mime_plaintext,
krista@1325
   385
    stringlist_t **keylist,
krista@1325
   386
    PEP_rating *rating,
krista@2623
   387
    PEP_decrypt_flags_t *flags,
krista@2623
   388
    char** modified_src
krista@1325
   389
);
krista@1325
   390
krista@1325
   391
Edouard@728
   392
// own_message_private_key_details() - details on own key in own message
Edouard@728
   393
//
Edouard@728
   394
//  parameters:
Edouard@728
   395
//      session (in)        session handle
Edouard@728
   396
//      msg (in)            message to decrypt
Edouard@728
   397
//      ident (out)         identity containing uid, address and fpr of key
Edouard@728
   398
//
Edouard@728
   399
//  note:
Edouard@728
   400
//      In order to obtain details about key to be possibly imported
Edouard@728
   401
//      as a replacement of key currently used as own identity, 
Edouard@728
   402
//      application passes message that have been previously flagged by 
Edouard@728
   403
//      decrypt_message() as own message containing own key to this function
Edouard@728
   404
//
Edouard@728
   405
//  return value:
Edouard@728
   406
//      error status or PEP_STATUS_OK on success
Edouard@728
   407
//
roker@1869
   408
//  caveat:
roker@1869
   409
//      the ownership of msg remains with the caller
roker@1869
   410
//      the ownership of ident goes to the caller
roker@1869
   411
//      msg MUST be encrypted so that this function can check own signature
Edouard@728
   412
DYNAMIC_API PEP_STATUS own_message_private_key_details(
Edouard@728
   413
        PEP_SESSION session,
Edouard@728
   414
        message *msg,
Edouard@728
   415
        pEp_identity **ident 
Edouard@728
   416
);
vb@251
   417
roker@1869
   418
vb@1009
   419
// outgoing_message_rating() - get rating for an outgoing message
vb@189
   420
//
vb@189
   421
//  parameters:
vb@189
   422
//      session (in)        session handle
vb@1009
   423
//      msg (in)            message to get the rating for
vb@1009
   424
//      rating (out)        rating for the message
vb@189
   425
//
vb@189
   426
//  return value:
vb@189
   427
//      error status or PEP_STATUS_OK on success
vb@190
   428
//
vb@190
   429
//  caveat:
vb@190
   430
//      msg->from must point to a valid pEp_identity
vb@251
   431
//      msg->dir must be PEP_dir_outgoing
vb@251
   432
//      the ownership of msg remains with the caller
vb@1009
   433
DYNAMIC_API PEP_STATUS outgoing_message_rating(
vb@189
   434
        PEP_SESSION session,
vb@190
   435
        message *msg,
vb@1004
   436
        PEP_rating *rating
vb@189
   437
    );
vb@189
   438
vb@239
   439
vb@2929
   440
// outgoing_message_rating_preview() - get rating preview
vb@2929
   441
//
vb@2929
   442
//  parameters:
vb@2929
   443
//      session (in)        session handle
vb@2929
   444
//      msg (in)            message to get the rating for
vb@2929
   445
//      rating (out)        rating preview for the message
vb@2929
   446
//
vb@2929
   447
//  return value:
vb@2929
   448
//      error status or PEP_STATUS_OK on success
vb@2929
   449
//
vb@2929
   450
//  caveat:
vb@2929
   451
//      msg->from must point to a valid pEp_identity
vb@2929
   452
//      msg->dir must be PEP_dir_outgoing
vb@2929
   453
//      the ownership of msg remains with the caller
vb@2929
   454
DYNAMIC_API PEP_STATUS outgoing_message_rating_preview(
vb@2929
   455
        PEP_SESSION session,
vb@2929
   456
        message *msg,
vb@2929
   457
        PEP_rating *rating
vb@2929
   458
    );
vb@2929
   459
vb@1009
   460
// identity_rating() - get rating for a single identity
vb@239
   461
//
vb@239
   462
//  parameters:
vb@239
   463
//      session (in)        session handle
vb@1009
   464
//      ident (in)          identity to get the rating for
vb@1009
   465
//      rating (out)        rating for the identity
vb@239
   466
//
vb@239
   467
//  return value:
vb@239
   468
//      error status or PEP_STATUS_OK on success
vb@251
   469
//
vb@251
   470
//  caveat:
vb@251
   471
//      the ownership of ident remains with the caller
vb@1009
   472
DYNAMIC_API PEP_STATUS identity_rating(
vb@239
   473
        PEP_SESSION session,
vb@239
   474
        pEp_identity *ident,
vb@1004
   475
        PEP_rating *rating
vb@239
   476
    );
vb@239
   477
vb@239
   478
vb@507
   479
// get_binary_path() - retrieve path of cryptotech binary if available
vb@507
   480
//
vb@507
   481
//  parameters:
vb@507
   482
//      tech (in)           cryptotech to get the binary for
vb@507
   483
//      path (out)          path to cryptotech binary or NULL if not available
roker@540
   484
//                          **path is owned by the library, do not change it!
vb@507
   485
DYNAMIC_API PEP_STATUS get_binary_path(PEP_cryptotech tech, const char **path);
vb@507
   486
roker@1869
   487
krista@1307
   488
// get_trustwords() - get full trustwords string for a *pair* of identities
krista@1307
   489
//
krista@1307
   490
//    parameters:
krista@1307
   491
//        session (in)        session handle
krista@1307
   492
//        id1 (in)            identity of first party in communication - fpr can't be NULL  
krista@1307
   493
//        id2 (in)            identity of second party in communication - fpr can't be NULL
krista@1307
   494
//        lang (in)           C string with ISO 639-1 language code
krista@1307
   495
//        words (out)         pointer to C string with all trustwords UTF-8 encoded,
krista@1307
   496
//                            separated by a blank each
krista@1307
   497
//                            NULL if language is not supported or trustword
krista@1307
   498
//                            wordlist is damaged or unavailable
krista@1307
   499
//        wsize (out)         length of full trustwords string
krista@1307
   500
//        full (in)           if true, generate ALL trustwords for these identities.
krista@1307
   501
//                            else, generate a fixed-size subset. (TODO: fixed-minimum-entropy
krista@1307
   502
//                            subset in next version)
krista@1307
   503
//
krista@1307
   504
//    return value:
krista@1307
   505
//        PEP_STATUS_OK            trustwords retrieved
krista@1307
   506
//        PEP_OUT_OF_MEMORY        out of memory
krista@1307
   507
//        PEP_TRUSTWORD_NOT_FOUND  at least one trustword not found
krista@1307
   508
//
krista@1307
   509
//    caveat:
krista@1307
   510
//        the word pointer goes to the ownership of the caller
krista@1307
   511
//        the caller is responsible to free() it (on Windoze use pEp_free())
krista@1307
   512
//
krista@1307
   513
DYNAMIC_API PEP_STATUS get_trustwords(
roker@1509
   514
    PEP_SESSION session, const pEp_identity* id1, const pEp_identity* id2,
krista@1307
   515
    const char* lang, char **words, size_t *wsize, bool full
krista@1307
   516
);
vb@507
   517
roker@1869
   518
edouard@1553
   519
// get_message_trustwords() - get full trustwords string for message sender and reciever identities 
edouard@1553
   520
//
edouard@1553
   521
//    parameters:
edouard@1553
   522
//        session (in)        session handle
edouard@1553
   523
//        msg (in)            message to get sender identity from
edouard@1553
   524
//        keylist (in)        NULL if message to be decrypted,
edouard@1553
   525
//                            keylist returned by decrypt_message() otherwise
edouard@1553
   526
//        received_by (in)    identity for account receiving message can't be NULL
edouard@1553
   527
//        lang (in)           C string with ISO 639-1 language code
edouard@1553
   528
//        words (out)         pointer to C string with all trustwords UTF-8 encoded,
edouard@1553
   529
//                            separated by a blank each
edouard@1553
   530
//                            NULL if language is not supported or trustword
edouard@1553
   531
//                            wordlist is damaged or unavailable
edouard@1553
   532
//        full (in)           if true, generate ALL trustwords for these identities.
edouard@1553
   533
//                            else, generate a fixed-size subset. (TODO: fixed-minimum-entropy
edouard@1553
   534
//                            subset in next version)
edouard@1553
   535
//
edouard@1553
   536
//    return value:
edouard@1553
   537
//        PEP_STATUS_OK            trustwords retrieved
edouard@1553
   538
//        PEP_OUT_OF_MEMORY        out of memory
edouard@1553
   539
//        PEP_TRUSTWORD_NOT_FOUND  at least one trustword not found
edouard@1553
   540
//        error status of decrypt_message() if decryption fails.
edouard@1553
   541
//
edouard@1553
   542
//    caveat:
edouard@1553
   543
//        the word pointer goes to the ownership of the caller
edouard@1553
   544
//        the caller is responsible to free() it (on Windoze use pEp_free())
edouard@1553
   545
//
edouard@1553
   546
DYNAMIC_API PEP_STATUS get_message_trustwords(
edouard@1553
   547
    PEP_SESSION session, 
edouard@1553
   548
    message *msg,
edouard@1553
   549
    stringlist_t *keylist,
edouard@1553
   550
    pEp_identity* received_by,
edouard@1553
   551
    const char* lang, char **words, bool full
edouard@1553
   552
);
edouard@1553
   553
edouard@1815
   554
// re_evaluate_message_rating() - re-evaluate already decrypted message rating
edouard@1815
   555
//
edouard@1815
   556
//  parameters:
edouard@1815
   557
//      session (in)            session handle
edouard@1815
   558
//      msg (in)                message to get the rating for
edouard@1815
   559
//      x_keylist (in)          decrypted message recipients keys fpr
edouard@1815
   560
//      x_enc_status (in)       original rating for the decrypted message
edouard@1815
   561
//      rating (out)            rating for the message
edouard@1815
   562
//
edouard@1815
   563
//  return value:
edouard@1815
   564
//      PEP_ILLEGAL_VALUE       if decrypted message doesn't contain 
edouard@1815
   565
//                              X-EncStatus optional field and x_enc_status is 
edouard@1815
   566
//                              pEp_rating_udefined
edouard@1815
   567
//                              or if decrypted message doesn't contain 
edouard@1815
   568
//                              X-Keylist optional field and x_keylist is NULL
edouard@1815
   569
//      PEP_OUT_OF_MEMORY       if not enough memory could be allocated
edouard@1815
   570
//
edouard@1815
   571
//  caveat:
edouard@1815
   572
//      msg->from must point to a valid pEp_identity
edouard@1815
   573
//      the ownership of msg remains with the caller
edouard@1815
   574
//	    the ownership of x_keylist remains with to the caller
edouard@1815
   575
edouard@1815
   576
DYNAMIC_API PEP_STATUS re_evaluate_message_rating(
edouard@1815
   577
    PEP_SESSION session,
edouard@1815
   578
    message *msg,
edouard@1815
   579
    stringlist_t *x_keylist,
edouard@1815
   580
    PEP_rating x_enc_status,
edouard@1815
   581
    PEP_rating *rating
edouard@1815
   582
);
vb@37
   583
#ifdef __cplusplus
vb@37
   584
}
vb@37
   585
#endif