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