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