src/message_api.h
author Volker Birk <vb@pep-project.org>
Fri, 29 Jul 2016 10:45:13 +0200
branchkeysync
changeset 939 ed7dfdae3031
parent 736 496905895282
child 952 986fd7b2eb8f
permissions -rw-r--r--
changing message_api: adding flags to encrypt_message()
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@939
    21
typedef enum _PEP_encrypt_flags {
vb@939
    22
    PEP_encrypt_flag_force_encryption = 0x1
vb@939
    23
} PEP_encrypt_flags; 
vb@939
    24
vb@939
    25
typedef unsigned int PEP_encrypt_flags_t;
vb@939
    26
vb@39
    27
// encrypt_message() - encrypt message in memory
vb@39
    28
//
vb@39
    29
//  parameters:
vb@48
    30
//      session (in)        session handle
vb@48
    31
//      src (in)            message to encrypt
vb@48
    32
//      extra (in)          extra keys for encryption
vb@83
    33
//      dst (out)           pointer to new encrypted message or NULL on failure
vb@84
    34
//      enc_format (in)     encrypted format
vb@939
    35
//      flags (in)          flags to set special encryption features
vb@39
    36
//
vb@39
    37
//  return value:
vb@48
    38
//      PEP_STATUS_OK                   on success
vb@48
    39
//		PEP_KEY_NOT_FOUND	            at least one of the receipient keys
vb@48
    40
//		                                could not be found
vb@48
    41
//		PEP_KEY_HAS_AMBIG_NAME          at least one of the receipient keys has
vb@48
    42
//		                                an ambiguous name
vb@48
    43
//		PEP_GET_KEY_FAILED		        cannot retrieve key
vb@83
    44
//
vb@83
    45
//	caveat:
vb@251
    46
//	    the ownershop of src remains with the caller
vb@251
    47
//	    the ownership of dst goes to the caller
vb@38
    48
vb@44
    49
DYNAMIC_API PEP_STATUS encrypt_message(
vb@37
    50
        PEP_SESSION session,
vb@113
    51
        message *src,
vb@37
    52
        stringlist_t *extra,
vb@38
    53
        message **dst,
vb@939
    54
        PEP_enc_format enc_format,
vb@939
    55
        PEP_encrypt_flags_t flags
vb@37
    56
    );
vb@37
    57
vb@39
    58
vb@232
    59
typedef enum _PEP_color {
vb@237
    60
    PEP_rating_undefined = 0,
vb@256
    61
    PEP_rating_cannot_decrypt,
vb@267
    62
    PEP_rating_have_no_key,
vb@237
    63
    PEP_rating_unencrypted,
vb@486
    64
    PEP_rating_unencrypted_for_some,
vb@237
    65
    PEP_rating_unreliable,
vb@237
    66
    PEP_rating_reliable,
vb@237
    67
    PEP_rating_yellow = PEP_rating_reliable,
vb@237
    68
    PEP_rating_trusted,
vb@237
    69
    PEP_rating_green = PEP_rating_trusted,
vb@237
    70
    PEP_rating_trusted_and_anonymized,
vb@237
    71
    PEP_rating_fully_anonymous,   
vb@189
    72
Edouard@442
    73
    PEP_rating_mistrust = -1,
Edouard@442
    74
    PEP_rating_red = PEP_rating_mistrust,
Edouard@442
    75
    PEP_rating_b0rken = -2,
vb@436
    76
    PEP_rating_under_attack = -3
vb@232
    77
} PEP_color;
vb@189
    78
Edouard@728
    79
typedef enum _PEP_decrypt_flags {
Edouard@728
    80
    PEP_decrypt_flag_own_private_key = 0x1
Edouard@728
    81
} PEP_decrypt_flags; 
Edouard@728
    82
vb@939
    83
typedef unsigned int PEP_decrypt_flags_t;
Edouard@728
    84
vb@251
    85
// decrypt_message() - decrypt message in memory
vb@251
    86
//
vb@251
    87
//  parameters:
vb@251
    88
//      session (in)        session handle
vb@251
    89
//      src (in)            message to decrypt
vb@251
    90
//      dst (out)           pointer to new decrypted message or NULL on failure
vb@251
    91
//      keylist (out)       stringlist with keyids
vb@251
    92
//      color (out)         color for the message
vb@939
    93
//      flags (out)         flags to signal special decryption features
vb@251
    94
//
vb@251
    95
//  return value:
vb@251
    96
//      error status or PEP_STATUS_OK on success
vb@251
    97
//
vb@251
    98
//	caveat:
vb@251
    99
//	    the ownership of src remains with the caller
vb@251
   100
//	    the ownership of dst goes to the caller
vb@251
   101
//	    the ownership of keylist goes to the caller
vb@330
   102
//	    if src is unencrypted this function returns PEP_UNENCRYPTED and sets
vb@330
   103
//	    dst to NULL
vb@251
   104
vb@251
   105
DYNAMIC_API PEP_STATUS decrypt_message(
vb@251
   106
        PEP_SESSION session,
vb@251
   107
        message *src,
vb@251
   108
        message **dst,
vb@251
   109
        stringlist_t **keylist,
Edouard@728
   110
        PEP_color *color,
vb@939
   111
        PEP_decrypt_flags_t *flags
Edouard@728
   112
);
vb@251
   113
Edouard@728
   114
// own_message_private_key_details() - details on own key in own message
Edouard@728
   115
//
Edouard@728
   116
//  parameters:
Edouard@728
   117
//      session (in)        session handle
Edouard@728
   118
//      msg (in)            message to decrypt
Edouard@728
   119
//      ident (out)         identity containing uid, address and fpr of key
Edouard@728
   120
//
Edouard@728
   121
//  note:
Edouard@728
   122
//      In order to obtain details about key to be possibly imported
Edouard@728
   123
//      as a replacement of key currently used as own identity, 
Edouard@728
   124
//      application passes message that have been previously flagged by 
Edouard@728
   125
//      decrypt_message() as own message containing own key to this function
Edouard@728
   126
//
Edouard@728
   127
//  return value:
Edouard@728
   128
//      error status or PEP_STATUS_OK on success
Edouard@728
   129
//
Edouard@728
   130
//	caveat:
Edouard@728
   131
//	    the ownership of msg remains with the caller
Edouard@728
   132
//	    the ownership of ident goes to the caller
Edouard@728
   133
//	    msg MUST be encrypted so that this function can check own signature
Edouard@728
   134
Edouard@728
   135
DYNAMIC_API PEP_STATUS own_message_private_key_details(
Edouard@728
   136
        PEP_SESSION session,
Edouard@728
   137
        message *msg,
Edouard@728
   138
        pEp_identity **ident 
Edouard@728
   139
);
vb@251
   140
vb@251
   141
// outgoing_message_color() - get color for an outgoing message
vb@189
   142
//
vb@189
   143
//  parameters:
vb@189
   144
//      session (in)        session handle
vb@189
   145
//      msg (in)            message to get the color for
vb@189
   146
//      color (out)         color for the message
vb@189
   147
//
vb@189
   148
//  return value:
vb@189
   149
//      error status or PEP_STATUS_OK on success
vb@190
   150
//
vb@190
   151
//  caveat:
vb@190
   152
//      msg->from must point to a valid pEp_identity
vb@251
   153
//      msg->dir must be PEP_dir_outgoing
vb@251
   154
//      the ownership of msg remains with the caller
vb@189
   155
vb@251
   156
DYNAMIC_API PEP_STATUS outgoing_message_color(
vb@189
   157
        PEP_SESSION session,
vb@190
   158
        message *msg,
vb@232
   159
        PEP_color *color
vb@189
   160
    );
vb@189
   161
vb@239
   162
vb@240
   163
// identity_color() - get color for a single identity
vb@239
   164
//
vb@239
   165
//  parameters:
vb@239
   166
//      session (in)        session handle
vb@239
   167
//      ident (in)          identity to get the color for
vb@239
   168
//      color (out)         color for the identity
vb@239
   169
//
vb@239
   170
//  return value:
vb@239
   171
//      error status or PEP_STATUS_OK on success
vb@251
   172
//
vb@251
   173
//  caveat:
vb@251
   174
//      the ownership of ident remains with the caller
vb@239
   175
vb@240
   176
DYNAMIC_API PEP_STATUS identity_color(
vb@239
   177
        PEP_SESSION session,
vb@239
   178
        pEp_identity *ident,
vb@239
   179
        PEP_color *color
vb@239
   180
    );
vb@239
   181
vb@239
   182
vb@507
   183
// get_binary_path() - retrieve path of cryptotech binary if available
vb@507
   184
//
vb@507
   185
//  parameters:
vb@507
   186
//      tech (in)           cryptotech to get the binary for
vb@507
   187
//      path (out)          path to cryptotech binary or NULL if not available
roker@540
   188
//                          **path is owned by the library, do not change it!
vb@507
   189
DYNAMIC_API PEP_STATUS get_binary_path(PEP_cryptotech tech, const char **path);
vb@507
   190
vb@507
   191
vb@37
   192
#ifdef __cplusplus
vb@37
   193
}
vb@37
   194
#endif
vb@37
   195