src/message_api.h
author Krista Grothoff <krista@pep-project.org>
Tue, 18 Oct 2016 17:21:51 +0200
changeset 1307 f4a8b0035541
parent 1218 748dd3967cb5
child 1325 5f2e643a4fd7
permissions -rw-r--r--
ENGINE-109: moved get_trustwords, added bool for long (all) vs. short trustword lists
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
vb@1004
    92
typedef enum _PEP_rating {
vb@237
    93
    PEP_rating_undefined = 0,
vb@256
    94
    PEP_rating_cannot_decrypt,
vb@267
    95
    PEP_rating_have_no_key,
vb@237
    96
    PEP_rating_unencrypted,
vb@486
    97
    PEP_rating_unencrypted_for_some,
vb@237
    98
    PEP_rating_unreliable,
vb@237
    99
    PEP_rating_reliable,
vb@237
   100
    PEP_rating_trusted,
vb@237
   101
    PEP_rating_trusted_and_anonymized,
vb@237
   102
    PEP_rating_fully_anonymous,   
vb@189
   103
Edouard@442
   104
    PEP_rating_mistrust = -1,
Edouard@442
   105
    PEP_rating_b0rken = -2,
vb@436
   106
    PEP_rating_under_attack = -3
vb@1004
   107
} PEP_rating;
vb@1004
   108
vb@1004
   109
typedef enum _PEP_color {
vb@1004
   110
    PEP_color_no_color = 0,
vb@1004
   111
    PEP_color_yellow,
vb@1004
   112
    PEP_color_green,
vb@1004
   113
    PEP_color_red = -1,
vb@232
   114
} PEP_color;
vb@189
   115
vb@1007
   116
// color_from_rating - calculate color from rating
vb@1007
   117
//
vb@1007
   118
//  parameters:
vb@1007
   119
//      rating (in)         rating
vb@1007
   120
//
vb@1007
   121
//  return value:           color representing that rating
vb@1007
   122
vb@1004
   123
DYNAMIC_API PEP_color color_from_rating(PEP_rating rating);
vb@1004
   124
Edouard@728
   125
typedef enum _PEP_decrypt_flags {
Edouard@728
   126
    PEP_decrypt_flag_own_private_key = 0x1
Edouard@728
   127
} PEP_decrypt_flags; 
Edouard@728
   128
vb@939
   129
typedef unsigned int PEP_decrypt_flags_t;
Edouard@728
   130
vb@251
   131
// decrypt_message() - decrypt message in memory
vb@251
   132
//
vb@251
   133
//  parameters:
vb@251
   134
//      session (in)        session handle
vb@251
   135
//      src (in)            message to decrypt
vb@251
   136
//      dst (out)           pointer to new decrypted message or NULL on failure
vb@251
   137
//      keylist (out)       stringlist with keyids
roker@1218
   138
//      rating (out)        rating for the message
vb@939
   139
//      flags (out)         flags to signal special decryption features
vb@251
   140
//
vb@251
   141
//  return value:
vb@251
   142
//      error status or PEP_STATUS_OK on success
vb@251
   143
//
vb@251
   144
//	caveat:
vb@251
   145
//	    the ownership of src remains with the caller
vb@251
   146
//	    the ownership of dst goes to the caller
vb@251
   147
//	    the ownership of keylist goes to the caller
vb@330
   148
//	    if src is unencrypted this function returns PEP_UNENCRYPTED and sets
vb@330
   149
//	    dst to NULL
vb@251
   150
vb@251
   151
DYNAMIC_API PEP_STATUS decrypt_message(
vb@251
   152
        PEP_SESSION session,
vb@251
   153
        message *src,
vb@251
   154
        message **dst,
vb@251
   155
        stringlist_t **keylist,
vb@1004
   156
        PEP_rating *rating,
vb@939
   157
        PEP_decrypt_flags_t *flags
Edouard@728
   158
);
vb@251
   159
Edouard@728
   160
// own_message_private_key_details() - details on own key in own message
Edouard@728
   161
//
Edouard@728
   162
//  parameters:
Edouard@728
   163
//      session (in)        session handle
Edouard@728
   164
//      msg (in)            message to decrypt
Edouard@728
   165
//      ident (out)         identity containing uid, address and fpr of key
Edouard@728
   166
//
Edouard@728
   167
//  note:
Edouard@728
   168
//      In order to obtain details about key to be possibly imported
Edouard@728
   169
//      as a replacement of key currently used as own identity, 
Edouard@728
   170
//      application passes message that have been previously flagged by 
Edouard@728
   171
//      decrypt_message() as own message containing own key to this function
Edouard@728
   172
//
Edouard@728
   173
//  return value:
Edouard@728
   174
//      error status or PEP_STATUS_OK on success
Edouard@728
   175
//
Edouard@728
   176
//	caveat:
Edouard@728
   177
//	    the ownership of msg remains with the caller
Edouard@728
   178
//	    the ownership of ident goes to the caller
Edouard@728
   179
//	    msg MUST be encrypted so that this function can check own signature
Edouard@728
   180
Edouard@728
   181
DYNAMIC_API PEP_STATUS own_message_private_key_details(
Edouard@728
   182
        PEP_SESSION session,
Edouard@728
   183
        message *msg,
Edouard@728
   184
        pEp_identity **ident 
Edouard@728
   185
);
vb@251
   186
vb@1009
   187
// outgoing_message_rating() - get rating for an outgoing message
vb@189
   188
//
vb@189
   189
//  parameters:
vb@189
   190
//      session (in)        session handle
vb@1009
   191
//      msg (in)            message to get the rating for
vb@1009
   192
//      rating (out)        rating for the message
vb@189
   193
//
vb@189
   194
//  return value:
vb@189
   195
//      error status or PEP_STATUS_OK on success
vb@190
   196
//
vb@190
   197
//  caveat:
vb@190
   198
//      msg->from must point to a valid pEp_identity
vb@251
   199
//      msg->dir must be PEP_dir_outgoing
vb@251
   200
//      the ownership of msg remains with the caller
vb@189
   201
vb@1009
   202
DYNAMIC_API PEP_STATUS outgoing_message_rating(
vb@189
   203
        PEP_SESSION session,
vb@190
   204
        message *msg,
vb@1004
   205
        PEP_rating *rating
vb@189
   206
    );
vb@189
   207
vb@239
   208
vb@1009
   209
// identity_rating() - get rating for a single identity
vb@239
   210
//
vb@239
   211
//  parameters:
vb@239
   212
//      session (in)        session handle
vb@1009
   213
//      ident (in)          identity to get the rating for
vb@1009
   214
//      rating (out)        rating for the identity
vb@239
   215
//
vb@239
   216
//  return value:
vb@239
   217
//      error status or PEP_STATUS_OK on success
vb@251
   218
//
vb@251
   219
//  caveat:
vb@251
   220
//      the ownership of ident remains with the caller
vb@239
   221
vb@1009
   222
DYNAMIC_API PEP_STATUS identity_rating(
vb@239
   223
        PEP_SESSION session,
vb@239
   224
        pEp_identity *ident,
vb@1004
   225
        PEP_rating *rating
vb@239
   226
    );
vb@239
   227
vb@239
   228
vb@507
   229
// get_binary_path() - retrieve path of cryptotech binary if available
vb@507
   230
//
vb@507
   231
//  parameters:
vb@507
   232
//      tech (in)           cryptotech to get the binary for
vb@507
   233
//      path (out)          path to cryptotech binary or NULL if not available
roker@540
   234
//                          **path is owned by the library, do not change it!
vb@507
   235
DYNAMIC_API PEP_STATUS get_binary_path(PEP_cryptotech tech, const char **path);
vb@507
   236
krista@1307
   237
// get_trustwords() - get full trustwords string for a *pair* of identities
krista@1307
   238
//
krista@1307
   239
//    parameters:
krista@1307
   240
//        session (in)        session handle
krista@1307
   241
//        id1 (in)            identity of first party in communication - fpr can't be NULL  
krista@1307
   242
//        id2 (in)            identity of second party in communication - fpr can't be NULL
krista@1307
   243
//        lang (in)           C string with ISO 639-1 language code
krista@1307
   244
//        words (out)         pointer to C string with all trustwords UTF-8 encoded,
krista@1307
   245
//                            separated by a blank each
krista@1307
   246
//                            NULL if language is not supported or trustword
krista@1307
   247
//                            wordlist is damaged or unavailable
krista@1307
   248
//        wsize (out)         length of full trustwords string
krista@1307
   249
//        full (in)           if true, generate ALL trustwords for these identities.
krista@1307
   250
//                            else, generate a fixed-size subset. (TODO: fixed-minimum-entropy
krista@1307
   251
//                            subset in next version)
krista@1307
   252
//
krista@1307
   253
//    return value:
krista@1307
   254
//        PEP_STATUS_OK            trustwords retrieved
krista@1307
   255
//        PEP_OUT_OF_MEMORY        out of memory
krista@1307
   256
//        PEP_TRUSTWORD_NOT_FOUND  at least one trustword not found
krista@1307
   257
//
krista@1307
   258
//    caveat:
krista@1307
   259
//        the word pointer goes to the ownership of the caller
krista@1307
   260
//        the caller is responsible to free() it (on Windoze use pEp_free())
krista@1307
   261
//
krista@1307
   262
krista@1307
   263
DYNAMIC_API PEP_STATUS get_trustwords(
krista@1307
   264
    PEP_SESSION session, pEp_identity* id1, pEp_identity* id2,
krista@1307
   265
    const char* lang, char **words, size_t *wsize, bool full
krista@1307
   266
);
vb@507
   267
vb@37
   268
#ifdef __cplusplus
vb@37
   269
}
vb@37
   270
#endif
vb@37
   271