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