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