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