src/pgp_gpg.h
author Krista Bennett <krista@pep-project.org>
Fri, 05 Oct 2018 10:23:01 +0200
branchsync
changeset 3001 8c1aafb3ad57
parent 2946 bacb52cb79d0
parent 2978 2b16aa31c35b
child 3137 93877eafa715
permissions -rw-r--r--
Merged in default (including ENGINE-463) - tests pass
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
vb@24
   100
    );
vb@24
   101
vb@2946
   102
vb@2946
   103
// pgp_encrypt_only() - encrypt plaintext
vb@2946
   104
//
vb@2946
   105
//  parameters:
vb@2946
   106
//      session (in)        session handle
vb@2946
   107
//      keylist (in)        keys to encrypt plaintext
vb@2946
   108
//      ptext (in)          bytes with plaintext
vb@2946
   109
//      psize (in)          size of plaintext in bytes
vb@2946
   110
//      ctext (out)         bytes with ciphertext, ASCII armored
vb@2946
   111
//      csize (out)         size of ciphertext in bytes
vb@2946
   112
//
vb@2946
   113
//  return value:
vb@2946
   114
//      PEP_STATUS_OK                   successful
vb@2946
   115
//      PEP_KEY_NOT_FOUND               key not in keyring
vb@2946
   116
//      PEP_KEY_HAS_AMBIG_NAME          multiple keys match data in keylist
vb@2946
   117
//      PEP_GET_KEY_FAILED              access to keyring failed
vb@2946
   118
//      PEP_ILLEGAL_VALUE               parameters wrong
vb@2946
   119
//      PEP_OUT_OF_MEMORY               out of memory error
krista@3001
   120
//      PEP_UNKNOWN_ERROR                internal error
vb@2946
   121
krista@1639
   122
PEP_STATUS pgp_encrypt_only(
vb@2945
   123
        PEP_SESSION session,
vb@2945
   124
        const stringlist_t *keylist,
vb@2945
   125
        const char *ptext,
vb@2945
   126
        size_t psize,
vb@2945
   127
        char **ctext,
vb@2945
   128
        size_t *csize
krista@1639
   129
    );
krista@1639
   130
krista@1639
   131
vb@2946
   132
// pgp_verify_text() - verify signed data
vb@2946
   133
//
vb@2946
   134
//  parameters:
vb@2946
   135
//      session (in)        session handle
vb@2946
   136
//      keylist (in)        keys to encrypt plaintext
vb@2946
   137
//      text (in)           data to verify, may include signature
vb@2946
   138
//      size (in)           size of data to verify in bytes
vb@2946
   139
//      signature (in)      detached signature data or NULL
vb@2946
   140
//      sig_size (in)       size of detached signature in bytes
vb@2946
   141
//      keylist (out)       list of keys being used for signing
vb@2946
   142
//
vb@2946
   143
//  return value:
vb@2946
   144
//      PEP_VERIFIED_AND_TRUSTED        data was unencrypted but perfectly signed
vb@2946
   145
//                                      this is depending on PGP trust concept
vb@2946
   146
//      PEP_VERIFIED                    data was unencrypted, signature matches
vb@2946
   147
//      PEP_DECRYPT_NO_KEY              data could not be verified because a
vb@2946
   148
//                                      key is missing
vb@2946
   149
//      PEP_DECRYPT_WRONG_FORMAT        data format not readable
vb@2946
   150
//      PEP_ILLEGAL_VALUE               parameters wrong
vb@2946
   151
//      PEP_OUT_OF_MEMORY               out of memory error
vb@2946
   152
//      PEP_UNKOWN_ERROR                internal error
vb@2946
   153
vb@24
   154
PEP_STATUS pgp_verify_text(
vb@2945
   155
        PEP_SESSION session,
vb@2945
   156
        const char *text,
vb@2945
   157
        size_t size,
vb@2945
   158
        const char *signature,
vb@2945
   159
        size_t sig_size,
vb@2945
   160
        stringlist_t **keylist
vb@24
   161
    );
vb@24
   162
vb@2946
   163
vb@2946
   164
// pgp_delete_keypair() - delete key or keypair
vb@2946
   165
//
vb@2946
   166
//  parameters:
vb@2946
   167
//      session (in)        session handle
vb@2946
   168
//      fpr (in)            fingerprint of key or keypair to delete
vb@2946
   169
vb@24
   170
PEP_STATUS pgp_delete_keypair(PEP_SESSION session, const char *fpr);
vb@24
   171
vb@2946
   172
vb@2946
   173
// pgp_export_keydata() - export public key data ASCII armored
vb@2946
   174
//
vb@2946
   175
//  parameters:
vb@2946
   176
//      session (in)        session handle
vb@2946
   177
//      fpr (in)            fingerprint of public key to export
vb@2946
   178
//      key_data (out)      ascii armored key data
vb@2946
   179
//      size (out)          size of ascii armored key data
vb@2946
   180
//      secret (in)         additionally export private key data
vb@2946
   181
Edouard@170
   182
PEP_STATUS pgp_export_keydata(
vb@2945
   183
        PEP_SESSION session,
vb@2945
   184
        const char *fpr,
vb@2945
   185
        char **key_data,
vb@2945
   186
        size_t *size,
vb@1103
   187
        bool secret
vb@24
   188
    );
vb@24
   189
vb@2946
   190
vb@2946
   191
// pgp_find_keys() - find keys where fprs are matching a pattern
vb@2946
   192
//
vb@2946
   193
//  parameters:
vb@2946
   194
//      session (in)        session handle
vb@2946
   195
//      pattern (in)        UTF-8 string with pattern
vb@2946
   196
//      keylist (out)       list of fprs matching
vb@2946
   197
vb@24
   198
PEP_STATUS pgp_find_keys(
vb@2945
   199
        PEP_SESSION session,
vb@2945
   200
        const char *pattern,
vb@2945
   201
        stringlist_t **keylist
vb@24
   202
    );
vb@24
   203
vb@2946
   204
krista@1030
   205
PEP_STATUS pgp_list_keyinfo(
vb@2945
   206
        PEP_SESSION session,
vb@2945
   207
        const char* pattern,
vb@2945
   208
        stringpair_list_t** keyinfo_list
krista@1030
   209
    );
krista@1030
   210
vb@24
   211
PEP_STATUS pgp_generate_keypair(
vb@2945
   212
        PEP_SESSION session,
vb@2945
   213
        pEp_identity *identity
vb@24
   214
    );
vb@24
   215
vb@24
   216
PEP_STATUS pgp_get_key_rating(
vb@74
   217
        PEP_SESSION session,
vb@74
   218
        const char *fpr,
vb@74
   219
        PEP_comm_type *comm_type
vb@24
   220
    );
vb@24
   221
vb@2945
   222
PEP_STATUS pgp_import_keydata(
vb@2945
   223
        PEP_SESSION session,
vb@2945
   224
        const char *key_data,
vb@2945
   225
        size_t size,
vb@2945
   226
        identity_list **private_idents
vb@2945
   227
    );
Edouard@728
   228
vb@2945
   229
PEP_STATUS pgp_import_private_keydata(
vb@2945
   230
        PEP_SESSION session,
vb@2945
   231
        const char *key_data,
vb@2945
   232
        size_t size,
vb@2945
   233
        identity_list **private_idents
vb@2945
   234
    );
vb@24
   235
vb@24
   236
PEP_STATUS pgp_recv_key(PEP_SESSION session, const char *pattern);
vb@2945
   237
vb@200
   238
PEP_STATUS pgp_send_key(PEP_SESSION session, const char *pattern);
vb@201
   239
vb@201
   240
PEP_STATUS pgp_renew_key(
vb@201
   241
        PEP_SESSION session,
vb@201
   242
        const char *fpr,
vb@201
   243
        const timestamp *ts
vb@201
   244
    );
vb@201
   245
vb@211
   246
PEP_STATUS pgp_revoke_key(
vb@211
   247
        PEP_SESSION session,
vb@211
   248
        const char *fpr,
vb@211
   249
        const char *reason
vb@211
   250
    );
vb@24
   251
vb@214
   252
PEP_STATUS pgp_key_expired(
vb@214
   253
        PEP_SESSION session,
vb@214
   254
        const char *fpr,
Edouard@701
   255
        const time_t when,
vb@214
   256
        bool *expired
vb@214
   257
    );
vb@214
   258
Edouard@662
   259
PEP_STATUS pgp_key_revoked(
Edouard@662
   260
        PEP_SESSION session,
Edouard@662
   261
        const char *fpr,
Edouard@662
   262
        bool *revoked
Edouard@662
   263
    );
Edouard@662
   264
vb@958
   265
PEP_STATUS pgp_key_created(
vb@958
   266
        PEP_SESSION session,
vb@958
   267
        const char *fpr,
vb@958
   268
        time_t *created
vb@958
   269
    );
vb@958
   270
krista@1357
   271
PEP_STATUS pgp_contains_priv_key(
krista@1357
   272
        PEP_SESSION session, 
krista@1357
   273
        const char *fpr,
vb@2945
   274
        bool *has_private
vb@2945
   275
    );
krista@1357
   276
krista@1357
   277
PEP_STATUS pgp_find_private_keys(
vb@2945
   278
        PEP_SESSION session,
vb@2945
   279
        const char *pattern,
vb@2945
   280
        stringlist_t **keylist
vb@2945
   281
    );
krista@1357
   282
vb@507
   283
PEP_STATUS pgp_binary(const char **path);
krista@1924
   284
krista@2458
   285
// Returns first failure status, if there were any. Keys may have been
krista@2458
   286
// imported into DB regardless of status.
vb@2945
   287
krista@2458
   288
PEP_STATUS pgp_import_ultimately_trusted_keypairs(PEP_SESSION session);
krista@2458
   289
krista@1924
   290
/* Really only internal. */
krista@1924
   291
PEP_STATUS pgp_replace_only_uid(
krista@1924
   292
        PEP_SESSION session,
krista@1924
   293
        const char* fpr,
krista@1924
   294
        const char* realname,
krista@1924
   295
        const char* email
krista@1924
   296
    );
krista@1924
   297
vb@507
   298
#define PGP_BINARY_PATH pgp_binary