src/message_api.h
author Volker Birk <vb@pep.foundation>
Thu, 11 Aug 2016 21:48:26 +0200
branchkeysync
changeset 1004 9828752c0751
parent 1001 42e0841b71f0
child 1007 f322a5b6bd26
permissions -rw-r--r--
changing rating and color
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@994
    59
// encrypt_message_for_identity() - encrypt message for one particular identity in memory
krista@994
    60
//                     (to be used, for example, to save message drafts
krista@994
    61
//                      encrypted with owner ID)
krista@994
    62
//
krista@994
    63
//  parameters:
krista@994
    64
//      session (in)        session handle
krista@995
    65
//      target_id (in)      self identity this message should be encrypted for
krista@994
    66
//      src (in)            message to encrypt
krista@994
    67
//      dst (out)           pointer to new encrypted message or NULL on failure
krista@994
    68
//      enc_format (in)     encrypted format
krista@994
    69
//
krista@994
    70
//  return value:       (FIXME: This may not be correct or complete)
krista@994
    71
//      PEP_STATUS_OK                   on success
krista@994
    72
//		PEP_KEY_NOT_FOUND	            at least one of the receipient keys
krista@994
    73
//		                                could not be found
krista@994
    74
//		PEP_KEY_HAS_AMBIG_NAME          at least one of the receipient keys has
krista@994
    75
//		                                an ambiguous name
krista@994
    76
//		PEP_GET_KEY_FAILED		        cannot retrieve key
krista@994
    77
//
krista@994
    78
//	caveat:
krista@994
    79
//	    the ownership of src remains with the caller
krista@994
    80
//      the ownership of target_id remains w/ caller            
krista@994
    81
//	    the ownership of dst goes to the caller
krista@995
    82
//      message is NOT encrypted for identities other than the target_id (and then,
krista@995
    83
//          only if the target_id refers to self!)
krista@994
    84
krista@995
    85
DYNAMIC_API PEP_STATUS encrypt_message_for_self(
krista@994
    86
        PEP_SESSION session,
krista@994
    87
        pEp_identity* target_id,
krista@994
    88
        message *src,
krista@994
    89
        message **dst,
krista@994
    90
        PEP_enc_format enc_format
krista@994
    91
    );
vb@39
    92
vb@1004
    93
typedef enum _PEP_rating {
vb@237
    94
    PEP_rating_undefined = 0,
vb@256
    95
    PEP_rating_cannot_decrypt,
vb@267
    96
    PEP_rating_have_no_key,
vb@237
    97
    PEP_rating_unencrypted,
vb@486
    98
    PEP_rating_unencrypted_for_some,
vb@237
    99
    PEP_rating_unreliable,
vb@237
   100
    PEP_rating_reliable,
vb@237
   101
    PEP_rating_trusted,
vb@237
   102
    PEP_rating_trusted_and_anonymized,
vb@237
   103
    PEP_rating_fully_anonymous,   
vb@189
   104
Edouard@442
   105
    PEP_rating_mistrust = -1,
Edouard@442
   106
    PEP_rating_b0rken = -2,
vb@436
   107
    PEP_rating_under_attack = -3
vb@1004
   108
} PEP_rating;
vb@1004
   109
vb@1004
   110
typedef enum _PEP_color {
vb@1004
   111
    PEP_color_no_color = 0,
vb@1004
   112
    PEP_color_yellow,
vb@1004
   113
    PEP_color_green,
vb@1004
   114
    PEP_color_red = -1,
vb@232
   115
} PEP_color;
vb@189
   116
vb@1004
   117
DYNAMIC_API PEP_color color_from_rating(PEP_rating rating);
vb@1004
   118
Edouard@728
   119
typedef enum _PEP_decrypt_flags {
Edouard@728
   120
    PEP_decrypt_flag_own_private_key = 0x1
Edouard@728
   121
} PEP_decrypt_flags; 
Edouard@728
   122
vb@939
   123
typedef unsigned int PEP_decrypt_flags_t;
Edouard@728
   124
vb@251
   125
// decrypt_message() - decrypt message in memory
vb@251
   126
//
vb@251
   127
//  parameters:
vb@251
   128
//      session (in)        session handle
vb@251
   129
//      src (in)            message to decrypt
vb@251
   130
//      dst (out)           pointer to new decrypted message or NULL on failure
vb@251
   131
//      keylist (out)       stringlist with keyids
vb@251
   132
//      color (out)         color for the message
vb@939
   133
//      flags (out)         flags to signal special decryption features
vb@251
   134
//
vb@251
   135
//  return value:
vb@251
   136
//      error status or PEP_STATUS_OK on success
vb@251
   137
//
vb@251
   138
//	caveat:
vb@251
   139
//	    the ownership of src remains with the caller
vb@251
   140
//	    the ownership of dst goes to the caller
vb@251
   141
//	    the ownership of keylist goes to the caller
vb@330
   142
//	    if src is unencrypted this function returns PEP_UNENCRYPTED and sets
vb@330
   143
//	    dst to NULL
vb@251
   144
vb@251
   145
DYNAMIC_API PEP_STATUS decrypt_message(
vb@251
   146
        PEP_SESSION session,
vb@251
   147
        message *src,
vb@251
   148
        message **dst,
vb@251
   149
        stringlist_t **keylist,
vb@1004
   150
        PEP_rating *rating,
vb@939
   151
        PEP_decrypt_flags_t *flags
Edouard@728
   152
);
vb@251
   153
Edouard@728
   154
// own_message_private_key_details() - details on own key in own message
Edouard@728
   155
//
Edouard@728
   156
//  parameters:
Edouard@728
   157
//      session (in)        session handle
Edouard@728
   158
//      msg (in)            message to decrypt
Edouard@728
   159
//      ident (out)         identity containing uid, address and fpr of key
Edouard@728
   160
//
Edouard@728
   161
//  note:
Edouard@728
   162
//      In order to obtain details about key to be possibly imported
Edouard@728
   163
//      as a replacement of key currently used as own identity, 
Edouard@728
   164
//      application passes message that have been previously flagged by 
Edouard@728
   165
//      decrypt_message() as own message containing own key to this function
Edouard@728
   166
//
Edouard@728
   167
//  return value:
Edouard@728
   168
//      error status or PEP_STATUS_OK on success
Edouard@728
   169
//
Edouard@728
   170
//	caveat:
Edouard@728
   171
//	    the ownership of msg remains with the caller
Edouard@728
   172
//	    the ownership of ident goes to the caller
Edouard@728
   173
//	    msg MUST be encrypted so that this function can check own signature
Edouard@728
   174
Edouard@728
   175
DYNAMIC_API PEP_STATUS own_message_private_key_details(
Edouard@728
   176
        PEP_SESSION session,
Edouard@728
   177
        message *msg,
Edouard@728
   178
        pEp_identity **ident 
Edouard@728
   179
);
vb@251
   180
vb@251
   181
// outgoing_message_color() - get color for an outgoing message
vb@189
   182
//
vb@189
   183
//  parameters:
vb@189
   184
//      session (in)        session handle
vb@189
   185
//      msg (in)            message to get the color for
vb@1004
   186
//      rating (out)        color for the message
vb@189
   187
//
vb@189
   188
//  return value:
vb@189
   189
//      error status or PEP_STATUS_OK on success
vb@190
   190
//
vb@190
   191
//  caveat:
vb@190
   192
//      msg->from must point to a valid pEp_identity
vb@251
   193
//      msg->dir must be PEP_dir_outgoing
vb@251
   194
//      the ownership of msg remains with the caller
vb@189
   195
vb@251
   196
DYNAMIC_API PEP_STATUS outgoing_message_color(
vb@189
   197
        PEP_SESSION session,
vb@190
   198
        message *msg,
vb@1004
   199
        PEP_rating *rating
vb@189
   200
    );
vb@189
   201
vb@239
   202
vb@240
   203
// identity_color() - get color for a single identity
vb@239
   204
//
vb@239
   205
//  parameters:
vb@239
   206
//      session (in)        session handle
vb@239
   207
//      ident (in)          identity to get the color for
vb@239
   208
//      color (out)         color for the identity
vb@239
   209
//
vb@239
   210
//  return value:
vb@239
   211
//      error status or PEP_STATUS_OK on success
vb@251
   212
//
vb@251
   213
//  caveat:
vb@251
   214
//      the ownership of ident remains with the caller
vb@239
   215
vb@240
   216
DYNAMIC_API PEP_STATUS identity_color(
vb@239
   217
        PEP_SESSION session,
vb@239
   218
        pEp_identity *ident,
vb@1004
   219
        PEP_rating *rating
vb@239
   220
    );
vb@239
   221
vb@239
   222
vb@507
   223
// get_binary_path() - retrieve path of cryptotech binary if available
vb@507
   224
//
vb@507
   225
//  parameters:
vb@507
   226
//      tech (in)           cryptotech to get the binary for
vb@507
   227
//      path (out)          path to cryptotech binary or NULL if not available
roker@540
   228
//                          **path is owned by the library, do not change it!
vb@507
   229
DYNAMIC_API PEP_STATUS get_binary_path(PEP_cryptotech tech, const char **path);
vb@507
   230
vb@507
   231
vb@37
   232
#ifdef __cplusplus
vb@37
   233
}
vb@37
   234
#endif
vb@37
   235