src/pgp_gpg.h
author Dirk Zimmermann <dz@pep.security>
Thu, 11 Apr 2019 10:46:46 +0200
branchIOS-1482
changeset 3505 3fe4b41696d3
parent 3137 93877eafa715
child 3689 6ea4a0524c38
permissions -rw-r--r--
IOS-1482 close branch
vb@1513
     1
// This file is under GNU General Public License 3.0
vb@1513
     2
// see LICENSE.txt
vb@1513
     3
vb@24
     4
#pragma once
vb@24
     5
vb@24
     6
#include "pEpEngine.h"
vb@24
     7
vb@2945
     8
vb@2946
     9
// pgp_init() - initialize PGP backend
vb@2945
    10
//
vb@2945
    11
//  parameters:
vb@2945
    12
//      session (in)        session handle
vb@2945
    13
//      in_first (in)       true if this is the first session
vb@2945
    14
//
vb@2945
    15
//  return value:
vb@2945
    16
//      PEP_STATUS_OK if PGP backend was successfully initialized
vb@2945
    17
//      or any other value on error
vb@2945
    18
vb@62
    19
PEP_STATUS pgp_init(PEP_SESSION session, bool in_first);
vb@2945
    20
vb@2945
    21
vb@2946
    22
// pgp_release() - release PGP backend
vb@2945
    23
//
vb@2945
    24
//  paramters:
vb@2945
    25
//      session (in)        session handle
vb@2945
    26
//      out_last (in)       true if this is the last session to release
vb@2945
    27
vb@62
    28
void pgp_release(PEP_SESSION session, bool out_last);
vb@24
    29
vb@2945
    30
vb@2946
    31
// pgp_decrypt_and_verify() - decrypt and verify cyphertext
vb@2945
    32
//
vb@2945
    33
//  parameters:
vb@2945
    34
//      session (in)        session handle
vb@2945
    35
//      ctext (in)          bytes with ciphertext
vb@2945
    36
//      csize (in)          size of ciphertext in bytes
vb@2945
    37
//      dsigtext (in)       pointer to bytes with detached signature
vb@2945
    38
//                          or NULL if no detached signature
vb@2945
    39
//      dsigsize (in)       size of detached signature in bytes
vb@2946
    40
//      ptext (out)         bytes with cyphertext
vb@2946
    41
//      psize (out)         size of cyphertext in bytes
vb@2946
    42
//      keylist (out)       list of keys being used; first is the key being
vb@2946
    43
//                          used for signing
krista@3001
    44
//	filename (out)	    PGP filename, when rendered (Optional, only necessary for some PGP implementations (e.g. Symantec),
krista@3001
    45
//                          *** Mostly internal ***
vb@2946
    46
//  return value:
vb@2946
    47
//      PEP_DECRYPTED_AND_VERIFIED      data could be decryped and verified
vb@2946
    48
//      PEP_DECRYPT_SIGNATURE_DOES_NOT_MATCH
vb@2946
    49
//                                      a signature does not match
vb@2946
    50
//      PEP_DECRYPTED                   data could be decrypted but not verified
vb@2946
    51
//      PEP_VERIFIED_AND_TRUSTED        data was unencrypted but perfectly signed
vb@2946
    52
//      PEP_VERIFIED                    data was unencrypted, signature matches
vb@2946
    53
//      PEP_DECRYPT_NO_KEY              data could not be decrypted because a
vb@2946
    54
//                                      key is missing
vb@2946
    55
//      PEP_DECRYPT_WRONG_FORMAT        data format not readable
vb@2946
    56
//      PEP_ILLEGAL_VALUE               parameters wrong
vb@2946
    57
//      PEP_OUT_OF_MEMORY               out of memory error
vb@2946
    58
//      PEP_UNKOWN_ERROR                internal error
vb@2945
    59
vb@24
    60
PEP_STATUS pgp_decrypt_and_verify(
vb@2945
    61
        PEP_SESSION session,
vb@2945
    62
        const char *ctext,
vb@2945
    63
        size_t csize,
vb@2945
    64
        const char *dsigtext,
vb@2945
    65
        size_t dsigsize,
vb@2945
    66
        char **ptext,
vb@2945
    67
        size_t *psize,
krista@3001
    68
        stringlist_t **keylist,
krista@2978
    69
        char** filename_ptr
vb@24
    70
    );
vb@24
    71
vb@2945
    72
vb@2946
    73
// pgp_encrypt_and_sign() - encrypt plaintext and sign
vb@2946
    74
//
vb@2946
    75
//  parameters:
vb@2946
    76
//      session (in)        session handle
vb@2946
    77
//      keylist (in)        first key to sign and encrypt, all other keys to
vb@2946
    78
//                          encrypt
vb@2946
    79
//      ptext (in)          bytes with plaintext
vb@2946
    80
//      psize (in)          size of plaintext in bytes
vb@2946
    81
//      ctext (out)         bytes with ciphertext, ASCII armored
vb@2946
    82
//      csize (out)         size of ciphertext in bytes
vb@2946
    83
//
vb@2946
    84
//  return value:
vb@2946
    85
//      PEP_STATUS_OK                   successful
vb@2946
    86
//      PEP_KEY_NOT_FOUND               key not in keyring
vb@2946
    87
//      PEP_KEY_HAS_AMBIG_NAME          multiple keys match data in keylist
vb@2946
    88
//      PEP_GET_KEY_FAILED              access to keyring failed
vb@2946
    89
//      PEP_ILLEGAL_VALUE               parameters wrong
vb@2946
    90
//      PEP_OUT_OF_MEMORY               out of memory error
vb@2946
    91
//      PEP_UNKOWN_ERROR                internal error
vb@2946
    92
vb@24
    93
PEP_STATUS pgp_encrypt_and_sign(
vb@2945
    94
        PEP_SESSION session,
vb@2945
    95
        const stringlist_t *keylist,
vb@2945
    96
        const char *ptext,
vb@2945
    97
        size_t psize,
vb@2945
    98
        char **ctext,
vb@2945
    99
        size_t *csize
krista@1639
   100
    );
krista@1639
   101
krista@3131
   102
PEP_STATUS pgp_sign_only(
krista@3131
   103
        PEP_SESSION session, const char* fpr, const char *ptext,
krista@3131
   104
        size_t psize, char **stext, size_t *ssize
krista@3131
   105
    );
krista@1639
   106
vb@2946
   107
// pgp_encrypt_only() - encrypt plaintext
vb@2946
   108
//
vb@2946
   109
//  parameters:
vb@2946
   110
//      session (in)        session handle
vb@2946
   111
//      keylist (in)        keys to encrypt plaintext
vb@2946
   112
//      ptext (in)          bytes with plaintext
vb@2946
   113
//      psize (in)          size of plaintext in bytes
vb@2946
   114
//      ctext (out)         bytes with ciphertext, ASCII armored
vb@2946
   115
//      csize (out)         size of ciphertext in bytes
vb@2946
   116
//
vb@2946
   117
//  return value:
vb@2946
   118
//      PEP_STATUS_OK                   successful
vb@2946
   119
//      PEP_KEY_NOT_FOUND               key not in keyring
vb@2946
   120
//      PEP_KEY_HAS_AMBIG_NAME          multiple keys match data in keylist
vb@2946
   121
//      PEP_GET_KEY_FAILED              access to keyring failed
vb@2946
   122
//      PEP_ILLEGAL_VALUE               parameters wrong
vb@2946
   123
//      PEP_OUT_OF_MEMORY               out of memory error
krista@3001
   124
//      PEP_UNKNOWN_ERROR                internal error
vb@2946
   125
krista@2978
   126
PEP_STATUS pgp_encrypt_only(
vb@2945
   127
        PEP_SESSION session,
vb@2945
   128
        const stringlist_t *keylist,
vb@2945
   129
        const char *ptext,
vb@2945
   130
        size_t psize,
vb@2945
   131
        char **ctext,
vb@2945
   132
        size_t *csize
krista@2978
   133
    );
krista@2978
   134
krista@2978
   135
vb@2946
   136
// pgp_verify_text() - verify signed data
vb@2946
   137
//
vb@2946
   138
//  parameters:
vb@2946
   139
//      session (in)        session handle
vb@2946
   140
//      keylist (in)        keys to encrypt plaintext
vb@2946
   141
//      text (in)           data to verify, may include signature
vb@2946
   142
//      size (in)           size of data to verify in bytes
vb@2946
   143
//      signature (in)      detached signature data or NULL
vb@2946
   144
//      sig_size (in)       size of detached signature in bytes
vb@2946
   145
//      keylist (out)       list of keys being used for signing
vb@2946
   146
//
vb@2946
   147
//  return value:
vb@2946
   148
//      PEP_VERIFIED_AND_TRUSTED        data was unencrypted but perfectly signed
vb@2946
   149
//                                      this is depending on PGP trust concept
vb@2946
   150
//      PEP_VERIFIED                    data was unencrypted, signature matches
vb@2946
   151
//      PEP_DECRYPT_NO_KEY              data could not be verified because a
vb@2946
   152
//                                      key is missing
vb@2946
   153
//      PEP_DECRYPT_WRONG_FORMAT        data format not readable
vb@2946
   154
//      PEP_ILLEGAL_VALUE               parameters wrong
vb@2946
   155
//      PEP_OUT_OF_MEMORY               out of memory error
vb@2946
   156
//      PEP_UNKOWN_ERROR                internal error
vb@2946
   157
vb@24
   158
PEP_STATUS pgp_verify_text(
vb@2945
   159
        PEP_SESSION session,
vb@2945
   160
        const char *text,
vb@2945
   161
        size_t size,
vb@2945
   162
        const char *signature,
vb@2945
   163
        size_t sig_size,
vb@2945
   164
        stringlist_t **keylist
vb@24
   165
    );
vb@24
   166
vb@2946
   167
vb@2946
   168
// pgp_delete_keypair() - delete key or keypair
vb@2946
   169
//
vb@2946
   170
//  parameters:
vb@2946
   171
//      session (in)        session handle
vb@2946
   172
//      fpr (in)            fingerprint of key or keypair to delete
vb@2946
   173
vb@24
   174
PEP_STATUS pgp_delete_keypair(PEP_SESSION session, const char *fpr);
vb@24
   175
vb@2946
   176
vb@2946
   177
// pgp_export_keydata() - export public key data ASCII armored
vb@2946
   178
//
vb@2946
   179
//  parameters:
vb@2946
   180
//      session (in)        session handle
vb@2946
   181
//      fpr (in)            fingerprint of public key to export
vb@2946
   182
//      key_data (out)      ascii armored key data
vb@2946
   183
//      size (out)          size of ascii armored key data
vb@2946
   184
//      secret (in)         additionally export private key data
vb@2946
   185
Edouard@170
   186
PEP_STATUS pgp_export_keydata(
vb@2945
   187
        PEP_SESSION session,
vb@2945
   188
        const char *fpr,
vb@2945
   189
        char **key_data,
vb@2945
   190
        size_t *size,
vb@1103
   191
        bool secret
vb@24
   192
    );
vb@24
   193
vb@2946
   194
vb@2946
   195
// pgp_find_keys() - find keys where fprs are matching a pattern
vb@2946
   196
//
vb@2946
   197
//  parameters:
vb@2946
   198
//      session (in)        session handle
vb@2946
   199
//      pattern (in)        UTF-8 string with pattern
vb@2946
   200
//      keylist (out)       list of fprs matching
vb@2946
   201
vb@24
   202
PEP_STATUS pgp_find_keys(
vb@2945
   203
        PEP_SESSION session,
vb@2945
   204
        const char *pattern,
vb@2945
   205
        stringlist_t **keylist
vb@24
   206
    );
vb@24
   207
vb@2946
   208
krista@1030
   209
PEP_STATUS pgp_list_keyinfo(
vb@2945
   210
        PEP_SESSION session,
vb@2945
   211
        const char* pattern,
vb@2945
   212
        stringpair_list_t** keyinfo_list
krista@1030
   213
    );
krista@1030
   214
vb@24
   215
PEP_STATUS pgp_generate_keypair(
vb@2945
   216
        PEP_SESSION session,
vb@2945
   217
        pEp_identity *identity
vb@24
   218
    );
vb@24
   219
vb@24
   220
PEP_STATUS pgp_get_key_rating(
vb@74
   221
        PEP_SESSION session,
vb@74
   222
        const char *fpr,
vb@74
   223
        PEP_comm_type *comm_type
vb@24
   224
    );
vb@24
   225
vb@2945
   226
PEP_STATUS pgp_import_keydata(
vb@2945
   227
        PEP_SESSION session,
vb@2945
   228
        const char *key_data,
vb@2945
   229
        size_t size,
vb@2945
   230
        identity_list **private_idents
vb@2945
   231
    );
Edouard@728
   232
vb@2945
   233
PEP_STATUS pgp_import_private_keydata(
vb@2945
   234
        PEP_SESSION session,
vb@2945
   235
        const char *key_data,
vb@2945
   236
        size_t size,
vb@2945
   237
        identity_list **private_idents
vb@2945
   238
    );
vb@24
   239
vb@24
   240
PEP_STATUS pgp_recv_key(PEP_SESSION session, const char *pattern);
vb@2945
   241
vb@200
   242
PEP_STATUS pgp_send_key(PEP_SESSION session, const char *pattern);
vb@201
   243
vb@201
   244
PEP_STATUS pgp_renew_key(
vb@201
   245
        PEP_SESSION session,
vb@201
   246
        const char *fpr,
vb@201
   247
        const timestamp *ts
vb@201
   248
    );
vb@201
   249
vb@211
   250
PEP_STATUS pgp_revoke_key(
vb@211
   251
        PEP_SESSION session,
vb@211
   252
        const char *fpr,
vb@211
   253
        const char *reason
vb@211
   254
    );
vb@24
   255
vb@214
   256
PEP_STATUS pgp_key_expired(
vb@214
   257
        PEP_SESSION session,
vb@214
   258
        const char *fpr,
Edouard@701
   259
        const time_t when,
vb@214
   260
        bool *expired
vb@214
   261
    );
vb@214
   262
Edouard@662
   263
PEP_STATUS pgp_key_revoked(
Edouard@662
   264
        PEP_SESSION session,
Edouard@662
   265
        const char *fpr,
Edouard@662
   266
        bool *revoked
Edouard@662
   267
    );
Edouard@662
   268
vb@958
   269
PEP_STATUS pgp_key_created(
vb@958
   270
        PEP_SESSION session,
vb@958
   271
        const char *fpr,
vb@958
   272
        time_t *created
vb@958
   273
    );
vb@958
   274
krista@1357
   275
PEP_STATUS pgp_contains_priv_key(
krista@1357
   276
        PEP_SESSION session, 
krista@1357
   277
        const char *fpr,
vb@2945
   278
        bool *has_private
vb@2945
   279
    );
krista@1357
   280
krista@1357
   281
PEP_STATUS pgp_find_private_keys(
vb@2945
   282
        PEP_SESSION session,
vb@2945
   283
        const char *pattern,
vb@2945
   284
        stringlist_t **keylist
vb@2945
   285
    );
krista@1357
   286
vb@507
   287
PEP_STATUS pgp_binary(const char **path);
krista@1924
   288
krista@2458
   289
// Returns first failure status, if there were any. Keys may have been
krista@2458
   290
// imported into DB regardless of status.
vb@2945
   291
krista@2458
   292
PEP_STATUS pgp_import_ultimately_trusted_keypairs(PEP_SESSION session);
krista@2458
   293
krista@1924
   294
/* Really only internal. */
krista@1924
   295
PEP_STATUS pgp_replace_only_uid(
krista@1924
   296
        PEP_SESSION session,
krista@1924
   297
        const char* fpr,
krista@1924
   298
        const char* realname,
krista@1924
   299
        const char* email
krista@1924
   300
    );
krista@1924
   301
vb@507
   302
#define PGP_BINARY_PATH pgp_binary