more docu sync
authorVolker Birk <vb@pep.foundation>
Sat, 15 Sep 2018 17:40:17 +0200
branchsync
changeset 2946bacb52cb79d0
parent 2945 8c2cc198fc8d
child 2955 3b2500a15709
child 2958 eacaf20a6854
child 2981 39a510d16cdd
more docu
src/pgp_gpg.h
     1.1 --- a/src/pgp_gpg.h	Sat Sep 15 14:36:03 2018 +0200
     1.2 +++ b/src/pgp_gpg.h	Sat Sep 15 17:40:17 2018 +0200
     1.3 @@ -6,7 +6,7 @@
     1.4  #include "pEpEngine.h"
     1.5  
     1.6  
     1.7 -// pgp_init(): initialize PGP backend
     1.8 +// pgp_init() - initialize PGP backend
     1.9  //
    1.10  //  parameters:
    1.11  //      session (in)        session handle
    1.12 @@ -19,7 +19,7 @@
    1.13  PEP_STATUS pgp_init(PEP_SESSION session, bool in_first);
    1.14  
    1.15  
    1.16 -// pgp_release(): release PGP backend
    1.17 +// pgp_release() - release PGP backend
    1.18  //
    1.19  //  paramters:
    1.20  //      session (in)        session handle
    1.21 @@ -28,7 +28,7 @@
    1.22  void pgp_release(PEP_SESSION session, bool out_last);
    1.23  
    1.24  
    1.25 -// pgp_decrypt_and_verify(): decrypt and verify cyphertext
    1.26 +// pgp_decrypt_and_verify() - decrypt and verify cyphertext
    1.27  //
    1.28  //  parameters:
    1.29  //      session (in)        session handle
    1.30 @@ -37,9 +37,24 @@
    1.31  //      dsigtext (in)       pointer to bytes with detached signature
    1.32  //                          or NULL if no detached signature
    1.33  //      dsigsize (in)       size of detached signature in bytes
    1.34 -//      ptext (out)         pointer to receive plaintext
    1.35 -//      psize (out)         size of plaintext delivered
    1.36 -//      keylist (out)       list of keys being used
    1.37 +//      ptext (out)         bytes with cyphertext
    1.38 +//      psize (out)         size of cyphertext in bytes
    1.39 +//      keylist (out)       list of keys being used; first is the key being
    1.40 +//                          used for signing
    1.41 +//
    1.42 +//  return value:
    1.43 +//      PEP_DECRYPTED_AND_VERIFIED      data could be decryped and verified
    1.44 +//      PEP_DECRYPT_SIGNATURE_DOES_NOT_MATCH
    1.45 +//                                      a signature does not match
    1.46 +//      PEP_DECRYPTED                   data could be decrypted but not verified
    1.47 +//      PEP_VERIFIED_AND_TRUSTED        data was unencrypted but perfectly signed
    1.48 +//      PEP_VERIFIED                    data was unencrypted, signature matches
    1.49 +//      PEP_DECRYPT_NO_KEY              data could not be decrypted because a
    1.50 +//                                      key is missing
    1.51 +//      PEP_DECRYPT_WRONG_FORMAT        data format not readable
    1.52 +//      PEP_ILLEGAL_VALUE               parameters wrong
    1.53 +//      PEP_OUT_OF_MEMORY               out of memory error
    1.54 +//      PEP_UNKOWN_ERROR                internal error
    1.55  
    1.56  PEP_STATUS pgp_decrypt_and_verify(
    1.57          PEP_SESSION session,
    1.58 @@ -53,6 +68,26 @@
    1.59      );
    1.60  
    1.61  
    1.62 +// pgp_encrypt_and_sign() - encrypt plaintext and sign
    1.63 +//
    1.64 +//  parameters:
    1.65 +//      session (in)        session handle
    1.66 +//      keylist (in)        first key to sign and encrypt, all other keys to
    1.67 +//                          encrypt
    1.68 +//      ptext (in)          bytes with plaintext
    1.69 +//      psize (in)          size of plaintext in bytes
    1.70 +//      ctext (out)         bytes with ciphertext, ASCII armored
    1.71 +//      csize (out)         size of ciphertext in bytes
    1.72 +//
    1.73 +//  return value:
    1.74 +//      PEP_STATUS_OK                   successful
    1.75 +//      PEP_KEY_NOT_FOUND               key not in keyring
    1.76 +//      PEP_KEY_HAS_AMBIG_NAME          multiple keys match data in keylist
    1.77 +//      PEP_GET_KEY_FAILED              access to keyring failed
    1.78 +//      PEP_ILLEGAL_VALUE               parameters wrong
    1.79 +//      PEP_OUT_OF_MEMORY               out of memory error
    1.80 +//      PEP_UNKOWN_ERROR                internal error
    1.81 +
    1.82  PEP_STATUS pgp_encrypt_and_sign(
    1.83          PEP_SESSION session,
    1.84          const stringlist_t *keylist,
    1.85 @@ -62,6 +97,26 @@
    1.86          size_t *csize
    1.87      );
    1.88  
    1.89 +
    1.90 +// pgp_encrypt_only() - encrypt plaintext
    1.91 +//
    1.92 +//  parameters:
    1.93 +//      session (in)        session handle
    1.94 +//      keylist (in)        keys to encrypt plaintext
    1.95 +//      ptext (in)          bytes with plaintext
    1.96 +//      psize (in)          size of plaintext in bytes
    1.97 +//      ctext (out)         bytes with ciphertext, ASCII armored
    1.98 +//      csize (out)         size of ciphertext in bytes
    1.99 +//
   1.100 +//  return value:
   1.101 +//      PEP_STATUS_OK                   successful
   1.102 +//      PEP_KEY_NOT_FOUND               key not in keyring
   1.103 +//      PEP_KEY_HAS_AMBIG_NAME          multiple keys match data in keylist
   1.104 +//      PEP_GET_KEY_FAILED              access to keyring failed
   1.105 +//      PEP_ILLEGAL_VALUE               parameters wrong
   1.106 +//      PEP_OUT_OF_MEMORY               out of memory error
   1.107 +//      PEP_UNKOWN_ERROR                internal error
   1.108 +
   1.109  PEP_STATUS pgp_encrypt_only(
   1.110          PEP_SESSION session,
   1.111          const stringlist_t *keylist,
   1.112 @@ -72,6 +127,28 @@
   1.113      );
   1.114  
   1.115  
   1.116 +// pgp_verify_text() - verify signed data
   1.117 +//
   1.118 +//  parameters:
   1.119 +//      session (in)        session handle
   1.120 +//      keylist (in)        keys to encrypt plaintext
   1.121 +//      text (in)           data to verify, may include signature
   1.122 +//      size (in)           size of data to verify in bytes
   1.123 +//      signature (in)      detached signature data or NULL
   1.124 +//      sig_size (in)       size of detached signature in bytes
   1.125 +//      keylist (out)       list of keys being used for signing
   1.126 +//
   1.127 +//  return value:
   1.128 +//      PEP_VERIFIED_AND_TRUSTED        data was unencrypted but perfectly signed
   1.129 +//                                      this is depending on PGP trust concept
   1.130 +//      PEP_VERIFIED                    data was unencrypted, signature matches
   1.131 +//      PEP_DECRYPT_NO_KEY              data could not be verified because a
   1.132 +//                                      key is missing
   1.133 +//      PEP_DECRYPT_WRONG_FORMAT        data format not readable
   1.134 +//      PEP_ILLEGAL_VALUE               parameters wrong
   1.135 +//      PEP_OUT_OF_MEMORY               out of memory error
   1.136 +//      PEP_UNKOWN_ERROR                internal error
   1.137 +
   1.138  PEP_STATUS pgp_verify_text(
   1.139          PEP_SESSION session,
   1.140          const char *text,
   1.141 @@ -81,8 +158,25 @@
   1.142          stringlist_t **keylist
   1.143      );
   1.144  
   1.145 +
   1.146 +// pgp_delete_keypair() - delete key or keypair
   1.147 +//
   1.148 +//  parameters:
   1.149 +//      session (in)        session handle
   1.150 +//      fpr (in)            fingerprint of key or keypair to delete
   1.151 +
   1.152  PEP_STATUS pgp_delete_keypair(PEP_SESSION session, const char *fpr);
   1.153  
   1.154 +
   1.155 +// pgp_export_keydata() - export public key data ASCII armored
   1.156 +//
   1.157 +//  parameters:
   1.158 +//      session (in)        session handle
   1.159 +//      fpr (in)            fingerprint of public key to export
   1.160 +//      key_data (out)      ascii armored key data
   1.161 +//      size (out)          size of ascii armored key data
   1.162 +//      secret (in)         additionally export private key data
   1.163 +
   1.164  PEP_STATUS pgp_export_keydata(
   1.165          PEP_SESSION session,
   1.166          const char *fpr,
   1.167 @@ -91,12 +185,21 @@
   1.168          bool secret
   1.169      );
   1.170  
   1.171 +
   1.172 +// pgp_find_keys() - find keys where fprs are matching a pattern
   1.173 +//
   1.174 +//  parameters:
   1.175 +//      session (in)        session handle
   1.176 +//      pattern (in)        UTF-8 string with pattern
   1.177 +//      keylist (out)       list of fprs matching
   1.178 +
   1.179  PEP_STATUS pgp_find_keys(
   1.180          PEP_SESSION session,
   1.181          const char *pattern,
   1.182          stringlist_t **keylist
   1.183      );
   1.184  
   1.185 +
   1.186  PEP_STATUS pgp_list_keyinfo(
   1.187          PEP_SESSION session,
   1.188          const char* pattern,