src/pgp_gpg.h
author Volker Birk <vb@pep.foundation>
Sat, 15 Sep 2018 17:40:17 +0200
branchsync
changeset 2946 bacb52cb79d0
parent 2945 8c2cc198fc8d
child 3001 8c1aafb3ad57
permissions -rw-r--r--
more docu
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
vb@2946
    44
//
vb@2946
    45
//  return value:
vb@2946
    46
//      PEP_DECRYPTED_AND_VERIFIED      data could be decryped and verified
vb@2946
    47
//      PEP_DECRYPT_SIGNATURE_DOES_NOT_MATCH
vb@2946
    48
//                                      a signature does not match
vb@2946
    49
//      PEP_DECRYPTED                   data could be decrypted but not verified
vb@2946
    50
//      PEP_VERIFIED_AND_TRUSTED        data was unencrypted but perfectly signed
vb@2946
    51
//      PEP_VERIFIED                    data was unencrypted, signature matches
vb@2946
    52
//      PEP_DECRYPT_NO_KEY              data could not be decrypted because a
vb@2946
    53
//                                      key is missing
vb@2946
    54
//      PEP_DECRYPT_WRONG_FORMAT        data format not readable
vb@2946
    55
//      PEP_ILLEGAL_VALUE               parameters wrong
vb@2946
    56
//      PEP_OUT_OF_MEMORY               out of memory error
vb@2946
    57
//      PEP_UNKOWN_ERROR                internal error
vb@2945
    58
vb@24
    59
PEP_STATUS pgp_decrypt_and_verify(
vb@2945
    60
        PEP_SESSION session,
vb@2945
    61
        const char *ctext,
vb@2945
    62
        size_t csize,
vb@2945
    63
        const char *dsigtext,
vb@2945
    64
        size_t dsigsize,
vb@2945
    65
        char **ptext,
vb@2945
    66
        size_t *psize,
vb@2945
    67
        stringlist_t **keylist
vb@24
    68
    );
vb@24
    69
vb@2945
    70
vb@2946
    71
// pgp_encrypt_and_sign() - encrypt plaintext and sign
vb@2946
    72
//
vb@2946
    73
//  parameters:
vb@2946
    74
//      session (in)        session handle
vb@2946
    75
//      keylist (in)        first key to sign and encrypt, all other keys to
vb@2946
    76
//                          encrypt
vb@2946
    77
//      ptext (in)          bytes with plaintext
vb@2946
    78
//      psize (in)          size of plaintext in bytes
vb@2946
    79
//      ctext (out)         bytes with ciphertext, ASCII armored
vb@2946
    80
//      csize (out)         size of ciphertext in bytes
vb@2946
    81
//
vb@2946
    82
//  return value:
vb@2946
    83
//      PEP_STATUS_OK                   successful
vb@2946
    84
//      PEP_KEY_NOT_FOUND               key not in keyring
vb@2946
    85
//      PEP_KEY_HAS_AMBIG_NAME          multiple keys match data in keylist
vb@2946
    86
//      PEP_GET_KEY_FAILED              access to keyring failed
vb@2946
    87
//      PEP_ILLEGAL_VALUE               parameters wrong
vb@2946
    88
//      PEP_OUT_OF_MEMORY               out of memory error
vb@2946
    89
//      PEP_UNKOWN_ERROR                internal error
vb@2946
    90
vb@24
    91
PEP_STATUS pgp_encrypt_and_sign(
vb@2945
    92
        PEP_SESSION session,
vb@2945
    93
        const stringlist_t *keylist,
vb@2945
    94
        const char *ptext,
vb@2945
    95
        size_t psize,
vb@2945
    96
        char **ctext,
vb@2945
    97
        size_t *csize
vb@24
    98
    );
vb@24
    99
vb@2946
   100
vb@2946
   101
// pgp_encrypt_only() - encrypt plaintext
vb@2946
   102
//
vb@2946
   103
//  parameters:
vb@2946
   104
//      session (in)        session handle
vb@2946
   105
//      keylist (in)        keys to encrypt plaintext
vb@2946
   106
//      ptext (in)          bytes with plaintext
vb@2946
   107
//      psize (in)          size of plaintext in bytes
vb@2946
   108
//      ctext (out)         bytes with ciphertext, ASCII armored
vb@2946
   109
//      csize (out)         size of ciphertext in bytes
vb@2946
   110
//
vb@2946
   111
//  return value:
vb@2946
   112
//      PEP_STATUS_OK                   successful
vb@2946
   113
//      PEP_KEY_NOT_FOUND               key not in keyring
vb@2946
   114
//      PEP_KEY_HAS_AMBIG_NAME          multiple keys match data in keylist
vb@2946
   115
//      PEP_GET_KEY_FAILED              access to keyring failed
vb@2946
   116
//      PEP_ILLEGAL_VALUE               parameters wrong
vb@2946
   117
//      PEP_OUT_OF_MEMORY               out of memory error
vb@2946
   118
//      PEP_UNKOWN_ERROR                internal error
vb@2946
   119
krista@1639
   120
PEP_STATUS pgp_encrypt_only(
vb@2945
   121
        PEP_SESSION session,
vb@2945
   122
        const stringlist_t *keylist,
vb@2945
   123
        const char *ptext,
vb@2945
   124
        size_t psize,
vb@2945
   125
        char **ctext,
vb@2945
   126
        size_t *csize
krista@1639
   127
    );
krista@1639
   128
krista@1639
   129
vb@2946
   130
// pgp_verify_text() - verify signed data
vb@2946
   131
//
vb@2946
   132
//  parameters:
vb@2946
   133
//      session (in)        session handle
vb@2946
   134
//      keylist (in)        keys to encrypt plaintext
vb@2946
   135
//      text (in)           data to verify, may include signature
vb@2946
   136
//      size (in)           size of data to verify in bytes
vb@2946
   137
//      signature (in)      detached signature data or NULL
vb@2946
   138
//      sig_size (in)       size of detached signature in bytes
vb@2946
   139
//      keylist (out)       list of keys being used for signing
vb@2946
   140
//
vb@2946
   141
//  return value:
vb@2946
   142
//      PEP_VERIFIED_AND_TRUSTED        data was unencrypted but perfectly signed
vb@2946
   143
//                                      this is depending on PGP trust concept
vb@2946
   144
//      PEP_VERIFIED                    data was unencrypted, signature matches
vb@2946
   145
//      PEP_DECRYPT_NO_KEY              data could not be verified because a
vb@2946
   146
//                                      key is missing
vb@2946
   147
//      PEP_DECRYPT_WRONG_FORMAT        data format not readable
vb@2946
   148
//      PEP_ILLEGAL_VALUE               parameters wrong
vb@2946
   149
//      PEP_OUT_OF_MEMORY               out of memory error
vb@2946
   150
//      PEP_UNKOWN_ERROR                internal error
vb@2946
   151
vb@24
   152
PEP_STATUS pgp_verify_text(
vb@2945
   153
        PEP_SESSION session,
vb@2945
   154
        const char *text,
vb@2945
   155
        size_t size,
vb@2945
   156
        const char *signature,
vb@2945
   157
        size_t sig_size,
vb@2945
   158
        stringlist_t **keylist
vb@24
   159
    );
vb@24
   160
vb@2946
   161
vb@2946
   162
// pgp_delete_keypair() - delete key or keypair
vb@2946
   163
//
vb@2946
   164
//  parameters:
vb@2946
   165
//      session (in)        session handle
vb@2946
   166
//      fpr (in)            fingerprint of key or keypair to delete
vb@2946
   167
vb@24
   168
PEP_STATUS pgp_delete_keypair(PEP_SESSION session, const char *fpr);
vb@24
   169
vb@2946
   170
vb@2946
   171
// pgp_export_keydata() - export public key data ASCII armored
vb@2946
   172
//
vb@2946
   173
//  parameters:
vb@2946
   174
//      session (in)        session handle
vb@2946
   175
//      fpr (in)            fingerprint of public key to export
vb@2946
   176
//      key_data (out)      ascii armored key data
vb@2946
   177
//      size (out)          size of ascii armored key data
vb@2946
   178
//      secret (in)         additionally export private key data
vb@2946
   179
Edouard@170
   180
PEP_STATUS pgp_export_keydata(
vb@2945
   181
        PEP_SESSION session,
vb@2945
   182
        const char *fpr,
vb@2945
   183
        char **key_data,
vb@2945
   184
        size_t *size,
vb@1103
   185
        bool secret
vb@24
   186
    );
vb@24
   187
vb@2946
   188
vb@2946
   189
// pgp_find_keys() - find keys where fprs are matching a pattern
vb@2946
   190
//
vb@2946
   191
//  parameters:
vb@2946
   192
//      session (in)        session handle
vb@2946
   193
//      pattern (in)        UTF-8 string with pattern
vb@2946
   194
//      keylist (out)       list of fprs matching
vb@2946
   195
vb@24
   196
PEP_STATUS pgp_find_keys(
vb@2945
   197
        PEP_SESSION session,
vb@2945
   198
        const char *pattern,
vb@2945
   199
        stringlist_t **keylist
vb@24
   200
    );
vb@24
   201
vb@2946
   202
krista@1030
   203
PEP_STATUS pgp_list_keyinfo(
vb@2945
   204
        PEP_SESSION session,
vb@2945
   205
        const char* pattern,
vb@2945
   206
        stringpair_list_t** keyinfo_list
krista@1030
   207
    );
krista@1030
   208
vb@24
   209
PEP_STATUS pgp_generate_keypair(
vb@2945
   210
        PEP_SESSION session,
vb@2945
   211
        pEp_identity *identity
vb@24
   212
    );
vb@24
   213
vb@24
   214
PEP_STATUS pgp_get_key_rating(
vb@74
   215
        PEP_SESSION session,
vb@74
   216
        const char *fpr,
vb@74
   217
        PEP_comm_type *comm_type
vb@24
   218
    );
vb@24
   219
vb@2945
   220
PEP_STATUS pgp_import_keydata(
vb@2945
   221
        PEP_SESSION session,
vb@2945
   222
        const char *key_data,
vb@2945
   223
        size_t size,
vb@2945
   224
        identity_list **private_idents
vb@2945
   225
    );
Edouard@728
   226
vb@2945
   227
PEP_STATUS pgp_import_private_keydata(
vb@2945
   228
        PEP_SESSION session,
vb@2945
   229
        const char *key_data,
vb@2945
   230
        size_t size,
vb@2945
   231
        identity_list **private_idents
vb@2945
   232
    );
vb@24
   233
vb@24
   234
PEP_STATUS pgp_recv_key(PEP_SESSION session, const char *pattern);
vb@2945
   235
vb@200
   236
PEP_STATUS pgp_send_key(PEP_SESSION session, const char *pattern);
vb@201
   237
vb@201
   238
PEP_STATUS pgp_renew_key(
vb@201
   239
        PEP_SESSION session,
vb@201
   240
        const char *fpr,
vb@201
   241
        const timestamp *ts
vb@201
   242
    );
vb@201
   243
vb@211
   244
PEP_STATUS pgp_revoke_key(
vb@211
   245
        PEP_SESSION session,
vb@211
   246
        const char *fpr,
vb@211
   247
        const char *reason
vb@211
   248
    );
vb@24
   249
vb@214
   250
PEP_STATUS pgp_key_expired(
vb@214
   251
        PEP_SESSION session,
vb@214
   252
        const char *fpr,
Edouard@701
   253
        const time_t when,
vb@214
   254
        bool *expired
vb@214
   255
    );
vb@214
   256
Edouard@662
   257
PEP_STATUS pgp_key_revoked(
Edouard@662
   258
        PEP_SESSION session,
Edouard@662
   259
        const char *fpr,
Edouard@662
   260
        bool *revoked
Edouard@662
   261
    );
Edouard@662
   262
vb@958
   263
PEP_STATUS pgp_key_created(
vb@958
   264
        PEP_SESSION session,
vb@958
   265
        const char *fpr,
vb@958
   266
        time_t *created
vb@958
   267
    );
vb@958
   268
krista@1357
   269
PEP_STATUS pgp_contains_priv_key(
krista@1357
   270
        PEP_SESSION session, 
krista@1357
   271
        const char *fpr,
vb@2945
   272
        bool *has_private
vb@2945
   273
    );
krista@1357
   274
krista@1357
   275
PEP_STATUS pgp_find_private_keys(
vb@2945
   276
        PEP_SESSION session,
vb@2945
   277
        const char *pattern,
vb@2945
   278
        stringlist_t **keylist
vb@2945
   279
    );
krista@1357
   280
vb@507
   281
PEP_STATUS pgp_binary(const char **path);
krista@1924
   282
krista@2458
   283
// Returns first failure status, if there were any. Keys may have been
krista@2458
   284
// imported into DB regardless of status.
vb@2945
   285
krista@2458
   286
PEP_STATUS pgp_import_ultimately_trusted_keypairs(PEP_SESSION session);
krista@2458
   287
krista@1924
   288
/* Really only internal. */
krista@1924
   289
PEP_STATUS pgp_replace_only_uid(
krista@1924
   290
        PEP_SESSION session,
krista@1924
   291
        const char* fpr,
krista@1924
   292
        const char* realname,
krista@1924
   293
        const char* email
krista@1924
   294
    );
krista@1924
   295
vb@507
   296
#define PGP_BINARY_PATH pgp_binary