src/message_api.h
author Roker <roker@pep-project.org>
Thu, 18 Aug 2016 17:01:50 +0200
branchkeysync
changeset 1038 18afd03aedf4
parent 1009 3faf72e9e7ab
parent 1034 1ec3384548cb
child 1218 748dd3967cb5
permissions -rw-r--r--
merge default into "keysync" branch
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
vb@251
   138
//      color (out)         color 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
vb@507
   237
vb@37
   238
#ifdef __cplusplus
vb@37
   239
}
vb@37
   240
#endif
vb@37
   241