libkdenetwork Library API Documentation

gpgme.h

00001 /* gpgme.h - Public interface to GnuPG Made Easy.
00002    Copyright (C) 2000 Werner Koch (dd9jn)
00003    Copyright (C) 2001, 2002, 2003, 2004 g10 Code GmbH
00004 
00005    This file is part of GPGME.
00006  
00007    GPGME is free software; you can redistribute it and/or modify it
00008    under the terms of the GNU General Public License as published by
00009    the Free Software Foundation; either version 2 of the License, or
00010    (at your option) any later version.
00011  
00012    GPGME is distributed in the hope that it will be useful, but
00013    WITHOUT ANY WARRANTY; without even the implied warranty of
00014    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00015    General Public License for more details.
00016  
00017    You should have received a copy of the GNU General Public License
00018    along with GPGME; if not, write to the Free Software Foundation,
00019    Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.  */
00020 
00021 #ifndef GPGME_H
00022 #define GPGME_H
00023 
00024 #ifdef __GNUC__
00025 #define _GPGME_INLINE __inline__
00026 #elif __STDC_VERSION__ >= 199901L
00027 #define _GPGME_INLINE inline
00028 #else
00029 #define _GPGME_INLINE
00030 #endif
00031 
00032 /* Include stdio.h for the FILE type definition.  */
00033 #include <stdio.h>
00034 
00035 #ifdef _MSC_VER
00036   typedef long off_t;
00037   typedef long ssize_t;
00038 #else
00039 # include <sys/types.h>
00040 #ifdef _WIN32
00041 typedef long ssize_t;
00042 #endif
00043 #endif
00044 
00045 #ifdef __cplusplus
00046 extern "C" {
00047 #if 0 /* just to make Emacs auto-indent happy */
00048 }
00049 #endif
00050 #endif /* __cplusplus */
00051 
00052 #include <gpg-error.h>
00053 
00054 
00055 /* Check for compiler features.  */
00056 #if __GNUC__
00057 #define _GPGME_GCC_VERSION (__GNUC__ * 10000 \
00058                             + __GNUC_MINOR__ * 100 \
00059                             + __GNUC_PATCHLEVEL__)
00060 
00061 #if _GPGME_GCC_VERSION > 30100
00062 #define _GPGME_DEPRECATED   __attribute__ ((__deprecated__))
00063 #endif
00064 #endif
00065 
00066 #ifndef _GPGME_DEPRECATED
00067 #define _GPGME_DEPRECATED
00068 #endif
00069 
00070 
00071 /* The version of this header should match the one of the library.  Do
00072    not use this symbol in your application, use gpgme_check_version
00073    instead.  The purpose of this macro is to let autoconf (using the
00074    AM_PATH_GPGME macro) check that this header matches the installed
00075    library.  Warning: Do not edit the next line.  configure will do
00076    that for you!  */
00077 #define GPGME_VERSION "0.9.0"
00078 
00079 
00080 /* Some opaque data types used by GPGME.  */
00081 
00082 /* The context holds some global state and configration options, as
00083    well as the results of a crypto operation.  */
00084 struct gpgme_context;
00085 typedef struct gpgme_context *gpgme_ctx_t;
00086 
00087 /* The data object is used by GPGME to exchange arbitrary data.  */
00088 struct gpgme_data;
00089 typedef struct gpgme_data *gpgme_data_t;
00090 
00091 
00092 /* Wrappers for the libgpg-error library.  */
00093 
00094 typedef gpg_error_t gpgme_error_t;
00095 typedef gpg_err_code_t gpgme_err_code_t;
00096 typedef gpg_err_source_t gpgme_err_source_t;
00097 
00098 
00099 static _GPGME_INLINE gpgme_error_t
00100 gpgme_err_make (gpgme_err_source_t source, gpgme_err_code_t code)
00101 {
00102   return gpg_err_make (source, code);
00103 }
00104 
00105 
00106 /* The user can define GPGME_ERR_SOURCE_DEFAULT before including this
00107    file to specify a default source for gpgme_error.  */
00108 #ifndef GPGME_ERR_SOURCE_DEFAULT
00109 #define GPGME_ERR_SOURCE_DEFAULT  GPG_ERR_SOURCE_USER_1
00110 #endif
00111 
00112 static _GPGME_INLINE gpgme_error_t
00113 gpgme_error (gpgme_err_code_t code)
00114 {
00115   return gpgme_err_make (GPGME_ERR_SOURCE_DEFAULT, code);
00116 }
00117 
00118 
00119 static _GPGME_INLINE gpgme_err_code_t
00120 gpgme_err_code (gpgme_error_t err)
00121 {
00122   return gpg_err_code (err);
00123 }
00124 
00125 
00126 static _GPGME_INLINE gpgme_err_source_t
00127 gpgme_err_source (gpgme_error_t err)
00128 {
00129   return gpg_err_source (err);
00130 }
00131 
00132 
00133 /* Return a pointer to a string containing a description of the error
00134    code in the error value ERR.  This function is not thread safe.  */
00135 const char *gpgme_strerror (gpgme_error_t err);
00136 
00137 /* Return the error string for ERR in the user-supplied buffer BUF of
00138    size BUFLEN.  This function is, in contrast to gpg_strerror,
00139    thread-safe if a thread-safe strerror_r() function is provided by
00140    the system.  If the function succeeds, 0 is returned and BUF
00141    contains the string describing the error.  If the buffer was not
00142    large enough, ERANGE is returned and BUF contains as much of the
00143    beginning of the error string as fits into the buffer.  */
00144 int gpgme_strerror_r (gpg_error_t err, char *buf, size_t buflen);
00145 
00146 
00147 /* Return a pointer to a string containing a description of the error
00148    source in the error value ERR.  */
00149 const char *gpgme_strsource (gpgme_error_t err);
00150 
00151 
00152 /* Retrieve the error code for the system error ERR.  This returns
00153    GPG_ERR_UNKNOWN_ERRNO if the system error is not mapped (report
00154    this).  */
00155 gpgme_err_code_t gpgme_err_code_from_errno (int err);
00156 
00157 
00158 /* Retrieve the system error for the error code CODE.  This returns 0
00159    if CODE is not a system error code.  */
00160 int gpgme_err_code_to_errno (gpgme_err_code_t code);
00161 
00162   
00163 /* Return an error value with the error source SOURCE and the system
00164    error ERR.  */
00165 gpgme_error_t gpgme_err_make_from_errno (gpgme_err_source_t source, int err);
00166 
00167 
00168 /* Return an error value with the system error ERR.  */
00169 gpgme_err_code_t gpgme_error_from_errno (int err);
00170 
00171 
00172 /* The possible encoding mode of gpgme_data_t objects.  */
00173 typedef enum
00174   {
00175     GPGME_DATA_ENCODING_NONE   = 0, /* Not specified.  */
00176     GPGME_DATA_ENCODING_BINARY = 1,
00177     GPGME_DATA_ENCODING_BASE64 = 2,
00178     GPGME_DATA_ENCODING_ARMOR  = 3  /* Either PEM or OpenPGP Armor.  */
00179   }
00180 gpgme_data_encoding_t;
00181 
00182 
00183 /* Public key algorithms from libgcrypt.  */
00184 typedef enum
00185   {
00186     GPGME_PK_RSA   = 1,
00187     GPGME_PK_RSA_E = 2,
00188     GPGME_PK_RSA_S = 3,
00189     GPGME_PK_ELG_E = 16,
00190     GPGME_PK_DSA   = 17,
00191     GPGME_PK_ELG   = 20
00192   }
00193 gpgme_pubkey_algo_t;
00194 
00195 
00196 /* Hash algorithms from libgcrypt.  */
00197 typedef enum
00198   {
00199     GPGME_MD_NONE          = 0,  
00200     GPGME_MD_MD5           = 1,
00201     GPGME_MD_SHA1          = 2,
00202     GPGME_MD_RMD160        = 3,
00203     GPGME_MD_MD2           = 5,
00204     GPGME_MD_TIGER         = 6,   /* TIGER/192. */
00205     GPGME_MD_HAVAL         = 7,   /* HAVAL, 5 pass, 160 bit. */
00206     GPGME_MD_SHA256        = 8,
00207     GPGME_MD_SHA384        = 9,
00208     GPGME_MD_SHA512        = 10,
00209     GPGME_MD_MD4           = 301,
00210     GPGME_MD_CRC32     = 302,
00211     GPGME_MD_CRC32_RFC1510 = 303,
00212     GPGME_MD_CRC24_RFC2440 = 304
00213   }
00214 gpgme_hash_algo_t;
00215 
00216 
00217 /* The possible signature stati.  Deprecated, use error value in sig
00218    status.  */
00219 typedef enum
00220   {
00221     GPGME_SIG_STAT_NONE  = 0,
00222     GPGME_SIG_STAT_GOOD  = 1,
00223     GPGME_SIG_STAT_BAD   = 2,
00224     GPGME_SIG_STAT_NOKEY = 3,
00225     GPGME_SIG_STAT_NOSIG = 4,
00226     GPGME_SIG_STAT_ERROR = 5,
00227     GPGME_SIG_STAT_DIFF  = 6,
00228     GPGME_SIG_STAT_GOOD_EXP = 7,
00229     GPGME_SIG_STAT_GOOD_EXPKEY = 8
00230   }
00231 _gpgme_sig_stat_t;
00232 typedef _gpgme_sig_stat_t gpgme_sig_stat_t _GPGME_DEPRECATED;
00233 
00234 
00235 /* The available signature modes.  */
00236 typedef enum
00237   {
00238     GPGME_SIG_MODE_NORMAL = 0,
00239     GPGME_SIG_MODE_DETACH = 1,
00240     GPGME_SIG_MODE_CLEAR  = 2
00241   }
00242 gpgme_sig_mode_t;
00243 
00244 
00245 /* The available key and signature attributes.  Deprecated, use the
00246    individual result structures instead.  */
00247 typedef enum
00248   {
00249     GPGME_ATTR_KEYID        = 1,
00250     GPGME_ATTR_FPR          = 2,
00251     GPGME_ATTR_ALGO         = 3,
00252     GPGME_ATTR_LEN          = 4,
00253     GPGME_ATTR_CREATED      = 5,
00254     GPGME_ATTR_EXPIRE       = 6,
00255     GPGME_ATTR_OTRUST       = 7,
00256     GPGME_ATTR_USERID       = 8,
00257     GPGME_ATTR_NAME         = 9,
00258     GPGME_ATTR_EMAIL        = 10,
00259     GPGME_ATTR_COMMENT      = 11,
00260     GPGME_ATTR_VALIDITY     = 12,
00261     GPGME_ATTR_LEVEL        = 13,
00262     GPGME_ATTR_TYPE         = 14,
00263     GPGME_ATTR_IS_SECRET    = 15,
00264     GPGME_ATTR_KEY_REVOKED  = 16,
00265     GPGME_ATTR_KEY_INVALID  = 17,
00266     GPGME_ATTR_UID_REVOKED  = 18,
00267     GPGME_ATTR_UID_INVALID  = 19,
00268     GPGME_ATTR_KEY_CAPS     = 20,
00269     GPGME_ATTR_CAN_ENCRYPT  = 21,
00270     GPGME_ATTR_CAN_SIGN     = 22,
00271     GPGME_ATTR_CAN_CERTIFY  = 23,
00272     GPGME_ATTR_KEY_EXPIRED  = 24,
00273     GPGME_ATTR_KEY_DISABLED = 25,
00274     GPGME_ATTR_SERIAL       = 26,
00275     GPGME_ATTR_ISSUER       = 27,
00276     GPGME_ATTR_CHAINID      = 28,
00277     GPGME_ATTR_SIG_STATUS   = 29,
00278     GPGME_ATTR_ERRTOK       = 30,
00279     GPGME_ATTR_SIG_SUMMARY  = 31,
00280     GPGME_ATTR_SIG_CLASS    = 32
00281   }
00282 _gpgme_attr_t;
00283 typedef _gpgme_attr_t gpgme_attr_t _GPGME_DEPRECATED;
00284 
00285 
00286 /* The available validities for a trust item or key.  */
00287 typedef enum
00288   {
00289     GPGME_VALIDITY_UNKNOWN   = 0,
00290     GPGME_VALIDITY_UNDEFINED = 1,
00291     GPGME_VALIDITY_NEVER     = 2,
00292     GPGME_VALIDITY_MARGINAL  = 3,
00293     GPGME_VALIDITY_FULL      = 4,
00294     GPGME_VALIDITY_ULTIMATE  = 5
00295   }
00296 gpgme_validity_t;
00297 
00298 
00299 /* The available protocols.  */
00300 typedef enum
00301   {
00302     GPGME_PROTOCOL_OpenPGP = 0,  /* The default mode.  */
00303     GPGME_PROTOCOL_CMS     = 1
00304   }
00305 gpgme_protocol_t;
00306 
00307 
00308 /* The available keylist mode flags.  */
00309 typedef enum
00310   {
00311     GPGME_KEYLIST_MODE_LOCAL  = 1,
00312     GPGME_KEYLIST_MODE_EXTERN = 2,
00313     GPGME_KEYLIST_MODE_SIGS   = 4,
00314     GPGME_KEYLIST_MODE_VALIDATE = 256
00315   }
00316 gpgme_keylist_mode_t;
00317 
00318 
00319 /* The possible stati for the edit operation.  */
00320 typedef enum
00321   {
00322     GPGME_STATUS_EOF,
00323     /* mkstatus processing starts here */
00324     GPGME_STATUS_ENTER,
00325     GPGME_STATUS_LEAVE,
00326     GPGME_STATUS_ABORT,
00327 
00328     GPGME_STATUS_GOODSIG,
00329     GPGME_STATUS_BADSIG,
00330     GPGME_STATUS_ERRSIG,
00331 
00332     GPGME_STATUS_BADARMOR,
00333 
00334     GPGME_STATUS_RSA_OR_IDEA,
00335     GPGME_STATUS_KEYEXPIRED,
00336     GPGME_STATUS_KEYREVOKED,
00337 
00338     GPGME_STATUS_TRUST_UNDEFINED,
00339     GPGME_STATUS_TRUST_NEVER,
00340     GPGME_STATUS_TRUST_MARGINAL,
00341     GPGME_STATUS_TRUST_FULLY,
00342     GPGME_STATUS_TRUST_ULTIMATE,
00343 
00344     GPGME_STATUS_SHM_INFO,
00345     GPGME_STATUS_SHM_GET,
00346     GPGME_STATUS_SHM_GET_BOOL,
00347     GPGME_STATUS_SHM_GET_HIDDEN,
00348 
00349     GPGME_STATUS_NEED_PASSPHRASE,
00350     GPGME_STATUS_VALIDSIG,
00351     GPGME_STATUS_SIG_ID,
00352     GPGME_STATUS_ENC_TO,
00353     GPGME_STATUS_NODATA,
00354     GPGME_STATUS_BAD_PASSPHRASE,
00355     GPGME_STATUS_NO_PUBKEY,
00356     GPGME_STATUS_NO_SECKEY,
00357     GPGME_STATUS_NEED_PASSPHRASE_SYM,
00358     GPGME_STATUS_DECRYPTION_FAILED,
00359     GPGME_STATUS_DECRYPTION_OKAY,
00360     GPGME_STATUS_MISSING_PASSPHRASE,
00361     GPGME_STATUS_GOOD_PASSPHRASE,
00362     GPGME_STATUS_GOODMDC,
00363     GPGME_STATUS_BADMDC,
00364     GPGME_STATUS_ERRMDC,
00365     GPGME_STATUS_IMPORTED,
00366     GPGME_STATUS_IMPORT_OK,
00367     GPGME_STATUS_IMPORT_PROBLEM,
00368     GPGME_STATUS_IMPORT_RES,
00369     GPGME_STATUS_FILE_START,
00370     GPGME_STATUS_FILE_DONE,
00371     GPGME_STATUS_FILE_ERROR,
00372 
00373     GPGME_STATUS_BEGIN_DECRYPTION,
00374     GPGME_STATUS_END_DECRYPTION,
00375     GPGME_STATUS_BEGIN_ENCRYPTION,
00376     GPGME_STATUS_END_ENCRYPTION,
00377 
00378     GPGME_STATUS_DELETE_PROBLEM,
00379     GPGME_STATUS_GET_BOOL,
00380     GPGME_STATUS_GET_LINE,
00381     GPGME_STATUS_GET_HIDDEN,
00382     GPGME_STATUS_GOT_IT,
00383     GPGME_STATUS_PROGRESS,
00384     GPGME_STATUS_SIG_CREATED,
00385     GPGME_STATUS_SESSION_KEY,
00386     GPGME_STATUS_NOTATION_NAME,
00387     GPGME_STATUS_NOTATION_DATA,
00388     GPGME_STATUS_POLICY_URL,
00389     GPGME_STATUS_BEGIN_STREAM,
00390     GPGME_STATUS_END_STREAM,
00391     GPGME_STATUS_KEY_CREATED,
00392     GPGME_STATUS_USERID_HINT,
00393     GPGME_STATUS_UNEXPECTED,
00394     GPGME_STATUS_INV_RECP,
00395     GPGME_STATUS_NO_RECP,
00396     GPGME_STATUS_ALREADY_SIGNED,
00397     GPGME_STATUS_SIGEXPIRED,
00398     GPGME_STATUS_EXPSIG,
00399     GPGME_STATUS_EXPKEYSIG,
00400     GPGME_STATUS_TRUNCATED,
00401     GPGME_STATUS_ERROR,
00402     GPGME_STATUS_NEWSIG,
00403     GPGME_STATUS_REVKEYSIG
00404   }
00405 gpgme_status_code_t;
00406 
00407 
00408 /* The engine information structure.  */
00409 struct _gpgme_engine_info
00410 {
00411   struct _gpgme_engine_info *next;
00412 
00413   /* The protocol ID.  */
00414   gpgme_protocol_t protocol;
00415 
00416   /* The file name of the engine binary.  */
00417   const char *file_name;
00418 
00419   /* The version string of the installed engine.  */
00420   const char *version;
00421 
00422   /* The minimum version required for GPGME.  */
00423   const char *req_version;
00424 };
00425 typedef struct _gpgme_engine_info *gpgme_engine_info_t;
00426 
00427 
00428 /* A subkey from a key.  */
00429 struct _gpgme_subkey
00430 {
00431   struct _gpgme_subkey *next;
00432 
00433   /* True if subkey is revoked.  */
00434   unsigned int revoked : 1;
00435 
00436   /* True if subkey is expired.  */
00437   unsigned int expired : 1;
00438 
00439   /* True if subkey is disabled.  */
00440   unsigned int disabled : 1;
00441 
00442   /* True if subkey is invalid.  */
00443   unsigned int invalid : 1;
00444 
00445   /* True if subkey can be used for encryption.  */
00446   unsigned int can_encrypt : 1;
00447 
00448   /* True if subkey can be used for signing.  */
00449   unsigned int can_sign : 1;
00450 
00451   /* True if subkey can be used for certification.  */
00452   unsigned int can_certify : 1;
00453 
00454   /* True if subkey is secret.  */
00455   unsigned int secret : 1;
00456 
00457   /* True if subkey can be used for authentication.  */
00458   unsigned int can_authenticate : 1;
00459 
00460   /* Internal to GPGME, do not use.  */
00461   unsigned int _unused : 23;
00462   
00463   /* Public key algorithm supported by this subkey.  */
00464   gpgme_pubkey_algo_t pubkey_algo;
00465 
00466   /* Length of the subkey.  */
00467   unsigned int length;
00468 
00469   /* The key ID of the subkey.  */
00470   char *keyid;
00471 
00472   /* Internal to GPGME, do not use.  */
00473   char _keyid[16 + 1];
00474 
00475   /* The fingerprint of the subkey in hex digit form.  */
00476   char *fpr;
00477 
00478   /* The creation timestamp, -1 if invalid, 0 if not available.  */
00479   long int timestamp;
00480 
00481   /* The expiration timestamp, 0 if the subkey does not expire.  */
00482   long int expires;
00483 };
00484 typedef struct _gpgme_subkey *gpgme_subkey_t;
00485 
00486 
00487 /* A signature on a user ID.  */
00488 struct _gpgme_key_sig
00489 {
00490   struct _gpgme_key_sig *next;
00491 
00492   /* True if the signature is a revocation signature.  */
00493   unsigned int revoked : 1;
00494 
00495   /* True if the signature is expired.  */
00496   unsigned int expired : 1;
00497 
00498   /* True if the signature is invalid.  */
00499   unsigned int invalid : 1;
00500 
00501   /* True if the signature should be exported.  */
00502   unsigned int exportable : 1;
00503 
00504   /* Internal to GPGME, do not use.  */
00505   unsigned int _unused : 28;
00506 
00507   /* The public key algorithm used to create the signature.  */
00508   gpgme_pubkey_algo_t pubkey_algo;
00509 
00510   /* The key ID of key used to create the signature.  */
00511   char *keyid;
00512 
00513   /* Internal to GPGME, do not use.  */
00514   char _keyid[16 + 1];
00515 
00516   /* The creation timestamp, -1 if invalid, 0 if not available.  */
00517   long int timestamp;
00518 
00519   /* The expiration timestamp, 0 if the subkey does not expire.  */
00520   long int expires;
00521 
00522   /* Same as in gpgme_signature_t.  */
00523   gpgme_error_t status;
00524 
00525 #ifdef __cplusplus
00526   unsigned int _obsolete_class _GPGME_DEPRECATED;
00527 #else
00528   /* Must be set to SIG_CLASS below.  */
00529   unsigned int class _GPGME_DEPRECATED;
00530 #endif
00531 
00532   /* The user ID string.  */
00533   char *uid;
00534 
00535   /* The name part of the user ID.  */
00536   char *name;
00537 
00538   /* The email part of the user ID.  */
00539   char *email;
00540 
00541   /* The comment part of the user ID.  */
00542   char *comment;
00543 
00544   /* Crypto backend specific signature class.  */
00545   unsigned int sig_class;
00546 };
00547 typedef struct _gpgme_key_sig *gpgme_key_sig_t;
00548 
00549 
00550 /* An user ID from a key.  */
00551 struct _gpgme_user_id
00552 {
00553   struct _gpgme_user_id *next;
00554 
00555   /* True if the user ID is revoked.  */
00556   unsigned int revoked : 1;
00557 
00558   /* True if the user ID is invalid.  */
00559   unsigned int invalid : 1;
00560 
00561   /* Internal to GPGME, do not use.  */
00562   unsigned int _unused : 30;
00563 
00564   /* The validity of the user ID.  */
00565   gpgme_validity_t validity; 
00566 
00567   /* The user ID string.  */
00568   char *uid;
00569 
00570   /* The name part of the user ID.  */
00571   char *name;
00572 
00573   /* The email part of the user ID.  */
00574   char *email;
00575 
00576   /* The comment part of the user ID.  */
00577   char *comment;
00578 
00579   /* The signatures of the user ID.  */
00580   gpgme_key_sig_t signatures;
00581 
00582   /* Internal to GPGME, do not use.  */
00583   gpgme_key_sig_t _last_keysig;
00584 };
00585 typedef struct _gpgme_user_id *gpgme_user_id_t;
00586 
00587 
00588 /* A key from the keyring.  */
00589 struct _gpgme_key
00590 {
00591   /* Internal to GPGME, do not use.  */
00592   unsigned int _refs;
00593 
00594   /* True if key is revoked.  */
00595   unsigned int revoked : 1;
00596 
00597   /* True if key is expired.  */
00598   unsigned int expired : 1;
00599 
00600   /* True if key is disabled.  */
00601   unsigned int disabled : 1;
00602 
00603   /* True if key is invalid.  */
00604   unsigned int invalid : 1;
00605 
00606   /* True if key can be used for encryption.  */
00607   unsigned int can_encrypt : 1;
00608 
00609   /* True if key can be used for signing.  */
00610   unsigned int can_sign : 1;
00611 
00612   /* True if key can be used for certification.  */
00613   unsigned int can_certify : 1;
00614 
00615   /* True if key is secret.  */
00616   unsigned int secret : 1;
00617 
00618   /* True if key can be used for authentication.  */
00619   unsigned int can_authenticate : 1;
00620 
00621   /* Internal to GPGME, do not use.  */
00622   unsigned int _unused : 23;
00623 
00624   /* This is the protocol supported by this key.  */
00625   gpgme_protocol_t protocol;
00626 
00627   /* If protocol is GPGME_PROTOCOL_CMS, this string contains the
00628      issuer serial.  */
00629   char *issuer_serial;
00630 
00631   /* If protocol is GPGME_PROTOCOL_CMS, this string contains the
00632      issuer name.  */
00633   char *issuer_name;
00634 
00635   /* If protocol is GPGME_PROTOCOL_CMS, this string contains the chain
00636      ID.  */
00637   char *chain_id;
00638 
00639   /* If protocol is GPGME_PROTOCOL_OpenPGP, this field contains the
00640      owner trust.  */
00641   gpgme_validity_t owner_trust;
00642 
00643   /* The subkeys of the key.  */
00644   gpgme_subkey_t subkeys;
00645 
00646   /* The user IDs of the key.  */
00647   gpgme_user_id_t uids;
00648 
00649   /* Internal to GPGME, do not use.  */
00650   gpgme_subkey_t _last_subkey;
00651 
00652   /* Internal to GPGME, do not use.  */
00653   gpgme_user_id_t _last_uid;
00654 
00655   /* The keylist mode that was active when listing the key.  */
00656   /* Implementation note: We are using unsigned int here, and not
00657      gpgme_keylist_mode_t, as the latter is currently an enum of
00658      unknown size.  */
00659   unsigned int keylist_mode;
00660 };
00661 typedef struct _gpgme_key *gpgme_key_t;
00662 
00663 
00664 
00665 /* Types for callback functions.  */
00666 
00667 /* Request a passphrase from the user.  */
00668 typedef gpgme_error_t (*gpgme_passphrase_cb_t) (void *hook,
00669                         const char *uid_hint,
00670                         const char *passphrase_info,
00671                         int prev_was_bad, int fd);
00672 
00673 /* Inform the user about progress made.  */
00674 typedef void (*gpgme_progress_cb_t) (void *opaque, const char *what,
00675                      int type, int current, int total);
00676 
00677 /* Interact with the user about an edit operation.  */
00678 typedef gpgme_error_t (*gpgme_edit_cb_t) (void *opaque,
00679                       gpgme_status_code_t status,
00680                       const char *args, int fd);
00681 
00682 
00683 /* Context management functions.  */
00684 
00685 /* Create a new context and return it in CTX.  */
00686 gpgme_error_t gpgme_new (gpgme_ctx_t *ctx);
00687 
00688 /* Release the context CTX.  */
00689 void gpgme_release (gpgme_ctx_t ctx);
00690 
00691 /* Set the protocol to be used by CTX to PROTO.  */
00692 gpgme_error_t gpgme_set_protocol (gpgme_ctx_t ctx, gpgme_protocol_t proto);
00693 
00694 /* Get the protocol used with CTX */
00695 gpgme_protocol_t gpgme_get_protocol (gpgme_ctx_t ctx);
00696 
00697 /* Get the string describing protocol PROTO, or NULL if invalid.  */
00698 const char *gpgme_get_protocol_name (gpgme_protocol_t proto);
00699 
00700 /* If YES is non-zero, enable armor mode in CTX, disable it otherwise.  */
00701 void gpgme_set_armor (gpgme_ctx_t ctx, int yes);
00702 
00703 /* Return non-zero if armor mode is set in CTX.  */
00704 int gpgme_get_armor (gpgme_ctx_t ctx);
00705 
00706 /* If YES is non-zero, enable text mode in CTX, disable it otherwise.  */
00707 void gpgme_set_textmode (gpgme_ctx_t ctx, int yes);
00708 
00709 /* Return non-zero if text mode is set in CTX.  */
00710 int gpgme_get_textmode (gpgme_ctx_t ctx);
00711 
00712 /* Include up to NR_OF_CERTS certificates in an S/MIME message.  */
00713 void gpgme_set_include_certs (gpgme_ctx_t ctx, int nr_of_certs);
00714 
00715 /* Return the number of certs to include in an S/MIME message.  */
00716 int gpgme_get_include_certs (gpgme_ctx_t ctx);
00717 
00718 /* Set keylist mode in CTX to MODE.  */
00719 gpgme_error_t gpgme_set_keylist_mode (gpgme_ctx_t ctx,
00720                       gpgme_keylist_mode_t mode);
00721 
00722 /* Get keylist mode in CTX.  */
00723 gpgme_keylist_mode_t gpgme_get_keylist_mode (gpgme_ctx_t ctx);
00724 
00725 /* Set the passphrase callback function in CTX to CB.  HOOK_VALUE is
00726    passed as first argument to the passphrase callback function.  */
00727 void gpgme_set_passphrase_cb (gpgme_ctx_t ctx,
00728                               gpgme_passphrase_cb_t cb, void *hook_value);
00729 
00730 /* Get the current passphrase callback function in *CB and the current
00731    hook value in *HOOK_VALUE.  */
00732 void gpgme_get_passphrase_cb (gpgme_ctx_t ctx, gpgme_passphrase_cb_t *cb,
00733                   void **hook_value);
00734 
00735 /* Set the progress callback function in CTX to CB.  HOOK_VALUE is
00736    passed as first argument to the progress callback function.  */
00737 void gpgme_set_progress_cb (gpgme_ctx_t c, gpgme_progress_cb_t cb,
00738                 void *hook_value);
00739 
00740 /* Get the current progress callback function in *CB and the current
00741    hook value in *HOOK_VALUE.  */
00742 void gpgme_get_progress_cb (gpgme_ctx_t ctx, gpgme_progress_cb_t *cb,
00743                 void **hook_value);
00744 
00745 /* This function sets the locale for the context CTX, or the default
00746    locale if CTX is a null pointer.  */
00747 gpgme_error_t gpgme_set_locale (gpgme_ctx_t ctx, int category,
00748                 const char *value);
00749 
00750 /* Return a statically allocated string with the name of the public
00751    key algorithm ALGO, or NULL if that name is not known.  */
00752 const char *gpgme_pubkey_algo_name (gpgme_pubkey_algo_t algo);
00753 
00754 /* Return a statically allocated string with the name of the hash
00755    algorithm ALGO, or NULL if that name is not known.  */
00756 const char *gpgme_hash_algo_name (gpgme_hash_algo_t algo);
00757 
00758 
00759 /* Delete all signers from CTX.  */
00760 void gpgme_signers_clear (gpgme_ctx_t ctx);
00761 
00762 /* Add KEY to list of signers in CTX.  */
00763 gpgme_error_t gpgme_signers_add (gpgme_ctx_t ctx, const gpgme_key_t key);
00764 
00765 /* Return the SEQth signer's key in CTX.  */
00766 gpgme_key_t gpgme_signers_enum (const gpgme_ctx_t ctx, int seq);
00767 
00768 /* Retrieve the signature status of signature IDX in CTX after a
00769    successful verify operation in R_STAT (if non-null).  The creation
00770    time stamp of the signature is returned in R_CREATED (if non-null).
00771    The function returns a string containing the fingerprint.
00772    Deprecated, use verify result directly.  */
00773 const char *gpgme_get_sig_status (gpgme_ctx_t ctx, int idx,
00774                                   _gpgme_sig_stat_t *r_stat,
00775                   time_t *r_created) _GPGME_DEPRECATED;
00776 
00777 /* Retrieve certain attributes of a signature.  IDX is the index
00778    number of the signature after a successful verify operation.  WHAT
00779    is an attribute where GPGME_ATTR_EXPIRE is probably the most useful
00780    one.  WHATIDX is to be passed as 0 for most attributes . */
00781 unsigned long gpgme_get_sig_ulong_attr (gpgme_ctx_t c, int idx,
00782                                         _gpgme_attr_t what, int whatidx)
00783      _GPGME_DEPRECATED;
00784 const char *gpgme_get_sig_string_attr (gpgme_ctx_t c, int idx,
00785                        _gpgme_attr_t what, int whatidx)
00786      _GPGME_DEPRECATED;
00787 
00788 
00789 /* Get the key used to create signature IDX in CTX and return it in
00790    R_KEY.  */
00791 gpgme_error_t gpgme_get_sig_key (gpgme_ctx_t ctx, int idx, gpgme_key_t *r_key)
00792      _GPGME_DEPRECATED;
00793 
00794 
00795 /* Run control.  */
00796 
00797 /* The type of an I/O callback function.  */
00798 typedef gpgme_error_t (*gpgme_io_cb_t) (void *data, int fd);
00799 
00800 /* The type of a function that can register FNC as the I/O callback
00801    function for the file descriptor FD with direction dir (0: for writing,
00802    1: for reading).  FNC_DATA should be passed as DATA to FNC.  The
00803    function should return a TAG suitable for the corresponding
00804    gpgme_remove_io_cb_t, and an error value.  */
00805 typedef gpgme_error_t (*gpgme_register_io_cb_t) (void *data, int fd, int dir,
00806                          gpgme_io_cb_t fnc,
00807                          void *fnc_data, void **tag);
00808 
00809 /* The type of a function that can remove a previously registered I/O
00810    callback function given TAG as returned by the register
00811    function.  */
00812 typedef void (*gpgme_remove_io_cb_t) (void *tag);
00813 
00814 typedef enum
00815   {
00816     GPGME_EVENT_START,
00817     GPGME_EVENT_DONE,
00818     GPGME_EVENT_NEXT_KEY,
00819     GPGME_EVENT_NEXT_TRUSTITEM
00820   }
00821 gpgme_event_io_t;
00822 
00823 /* The type of a function that is called when a context finished an
00824    operation.  */
00825 typedef void (*gpgme_event_io_cb_t) (void *data, gpgme_event_io_t type,
00826                      void *type_data);
00827 
00828 struct gpgme_io_cbs
00829 {
00830   gpgme_register_io_cb_t add;
00831   void *add_priv;
00832   gpgme_remove_io_cb_t remove;
00833   gpgme_event_io_cb_t event;
00834   void *event_priv;
00835 };
00836 typedef struct gpgme_io_cbs *gpgme_io_cbs_t;
00837 
00838 /* Set the I/O callback functions in CTX to IO_CBS.  */
00839 void gpgme_set_io_cbs (gpgme_ctx_t ctx, gpgme_io_cbs_t io_cbs);
00840 
00841 /* Get the current I/O callback functions.  */
00842 void gpgme_get_io_cbs (gpgme_ctx_t ctx, gpgme_io_cbs_t io_cbs);
00843 
00844 /* Process the pending operation and, if HANG is non-zero, wait for
00845    the pending operation to finish.  */
00846 gpgme_ctx_t gpgme_wait (gpgme_ctx_t ctx, gpgme_error_t *status, int hang);
00847 
00848 
00849 /* Functions to handle data objects.  */
00850 
00851 /* Read up to SIZE bytes into buffer BUFFER from the data object with
00852    the handle HANDLE.  Return the number of characters read, 0 on EOF
00853    and -1 on error.  If an error occurs, errno is set.  */
00854 typedef ssize_t (*gpgme_data_read_cb_t) (void *handle, void *buffer,
00855                      size_t size);
00856 
00857 /* Write up to SIZE bytes from buffer BUFFER to the data object with
00858    the handle HANDLE.  Return the number of characters written, or -1
00859    on error.  If an error occurs, errno is set.  */
00860 typedef ssize_t (*gpgme_data_write_cb_t) (void *handle, const void *buffer,
00861                       size_t size);
00862 
00863 /* Set the current position from where the next read or write starts
00864    in the data object with the handle HANDLE to OFFSET, relativ to
00865    WHENCE.  */
00866 typedef off_t (*gpgme_data_seek_cb_t) (void *handle, off_t offset, int whence);
00867 
00868 /* Close the data object with the handle DL.  */
00869 typedef void (*gpgme_data_release_cb_t) (void *handle);
00870 
00871 struct gpgme_data_cbs
00872 {
00873   gpgme_data_read_cb_t read;
00874   gpgme_data_write_cb_t write;
00875   gpgme_data_seek_cb_t seek;
00876   gpgme_data_release_cb_t release;
00877 };
00878 typedef struct gpgme_data_cbs *gpgme_data_cbs_t;
00879 
00880 /* Read up to SIZE bytes into buffer BUFFER from the data object with
00881    the handle DH.  Return the number of characters read, 0 on EOF and
00882    -1 on error.  If an error occurs, errno is set.  */
00883 ssize_t gpgme_data_read (gpgme_data_t dh, void *buffer, size_t size);
00884 
00885 /* Write up to SIZE bytes from buffer BUFFER to the data object with
00886    the handle DH.  Return the number of characters written, or -1 on
00887    error.  If an error occurs, errno is set.  */
00888 ssize_t gpgme_data_write (gpgme_data_t dh, const void *buffer, size_t size);
00889 
00890 /* Set the current position from where the next read or write starts
00891    in the data object with the handle DH to OFFSET, relativ to
00892    WHENCE.  */
00893 off_t gpgme_data_seek (gpgme_data_t dh, off_t offset, int whence);
00894 
00895 /* Create a new data buffer and return it in R_DH.  */
00896 gpgme_error_t gpgme_data_new (gpgme_data_t *r_dh);
00897 
00898 /* Destroy the data buffer DH.  */
00899 void gpgme_data_release (gpgme_data_t dh);
00900 
00901 /* Create a new data buffer filled with SIZE bytes starting from
00902    BUFFER.  If COPY is zero, copying is delayed until necessary, and
00903    the data is taken from the original location when needed.  */
00904 gpgme_error_t gpgme_data_new_from_mem (gpgme_data_t *r_dh,
00905                        const char *buffer, size_t size,
00906                        int copy);
00907 
00908 /* Destroy the data buffer DH and return a pointer to its content.
00909    The memory has be to released with free by the user.  It's size is
00910    returned in R_LEN.  */
00911 char *gpgme_data_release_and_get_mem (gpgme_data_t dh, size_t *r_len);
00912 
00913 gpgme_error_t gpgme_data_new_from_cbs (gpgme_data_t *dh,
00914                        gpgme_data_cbs_t cbs,
00915                        void *handle);
00916 
00917 gpgme_error_t gpgme_data_new_from_fd (gpgme_data_t *dh, int fd);
00918 
00919 gpgme_error_t gpgme_data_new_from_stream (gpgme_data_t *dh, FILE *stream);
00920 
00921 /* Return the encoding attribute of the data buffer DH */
00922 gpgme_data_encoding_t gpgme_data_get_encoding (gpgme_data_t dh);
00923 
00924 /* Set the encoding attribute of data buffer DH to ENC */
00925 gpgme_error_t gpgme_data_set_encoding (gpgme_data_t dh,
00926                        gpgme_data_encoding_t enc);
00927 
00928 
00929 
00930 /* Create a new data buffer which retrieves the data from the callback
00931    function READ_CB.  Deprecated, please use gpgme_data_new_from_cbs
00932    instead.  */
00933 gpgme_error_t gpgme_data_new_with_read_cb (gpgme_data_t *r_dh,
00934                        int (*read_cb) (void*,char *,
00935                                size_t,size_t*),
00936                        void *read_cb_value)
00937      _GPGME_DEPRECATED;
00938 
00939 /* Create a new data buffer filled with the content of file FNAME.
00940    COPY must be non-zero.  For delayed read, please use
00941    gpgme_data_new_from_fd or gpgme_data_new_from stream instead.  */
00942 gpgme_error_t gpgme_data_new_from_file (gpgme_data_t *r_dh,
00943                     const char *fname,
00944                     int copy);
00945 
00946 /* Create a new data buffer filled with LENGTH bytes starting from
00947    OFFSET within the file FNAME or stream FP (exactly one must be
00948    non-zero).  */
00949 gpgme_error_t gpgme_data_new_from_filepart (gpgme_data_t *r_dh,
00950                         const char *fname, FILE *fp,
00951                         off_t offset, size_t length);
00952 
00953 /* Reset the read pointer in DH.  Deprecated, please use
00954    gpgme_data_seek instead.  */
00955 gpgme_error_t gpgme_data_rewind (gpgme_data_t dh) _GPGME_DEPRECATED;
00956 
00957 
00958 /* Key and trust functions.  */
00959 
00960 /* Get the key with the fingerprint FPR from the crypto backend.  If
00961    SECRET is true, get the secret key.  */
00962 gpgme_error_t gpgme_get_key (gpgme_ctx_t ctx, const char *fpr,
00963                  gpgme_key_t *r_key, int secret);
00964 
00965 /* Acquire a reference to KEY.  */
00966 void gpgme_key_ref (gpgme_key_t key);
00967 
00968 /* Release a reference to KEY.  If this was the last one the key is
00969    destroyed.  */
00970 void gpgme_key_unref (gpgme_key_t key);
00971 void gpgme_key_release (gpgme_key_t key);
00972 
00973 /* Return the value of the attribute WHAT of KEY, which has to be
00974    representable by a string.  IDX specifies the sub key or user ID
00975    for attributes related to sub keys or user IDs.  Deprecated, use
00976    key structure directly instead. */
00977 const char *gpgme_key_get_string_attr (gpgme_key_t key, _gpgme_attr_t what,
00978                        const void *reserved, int idx)
00979      _GPGME_DEPRECATED;
00980 
00981 /* Return the value of the attribute WHAT of KEY, which has to be
00982    representable by an unsigned integer.  IDX specifies the sub key or
00983    user ID for attributes related to sub keys or user IDs.
00984    Deprecated, use key structure directly instead.  */
00985 unsigned long gpgme_key_get_ulong_attr (gpgme_key_t key, _gpgme_attr_t what,
00986                     const void *reserved, int idx)
00987      _GPGME_DEPRECATED;
00988 
00989 /* Return the value of the attribute WHAT of a signature on user ID
00990    UID_IDX in KEY, which has to be representable by a string.  IDX
00991    specifies the signature.  Deprecated, use key structure directly
00992    instead.  */
00993 const char *gpgme_key_sig_get_string_attr (gpgme_key_t key, int uid_idx,
00994                        _gpgme_attr_t what,
00995                        const void *reserved, int idx)
00996      _GPGME_DEPRECATED;
00997 
00998 /* Return the value of the attribute WHAT of a signature on user ID
00999    UID_IDX in KEY, which has to be representable by an unsigned
01000    integer string.  IDX specifies the signature.  Deprecated, use key
01001    structure directly instead.  */
01002 unsigned long gpgme_key_sig_get_ulong_attr (gpgme_key_t key, int uid_idx,
01003                         _gpgme_attr_t what,
01004                         const void *reserved, int idx)
01005      _GPGME_DEPRECATED;
01006 
01007 
01008 /* Crypto Operations.  */
01009 
01010 /* Cancel a pending asynchronous operation.  */
01011 gpgme_error_t gpgme_cancel (gpgme_ctx_t ctx);
01012 
01013 
01014 struct _gpgme_invalid_key
01015 {
01016   struct _gpgme_invalid_key *next;
01017   char *fpr;
01018   gpgme_error_t reason;
01019 };
01020 typedef struct _gpgme_invalid_key *gpgme_invalid_key_t;
01021 
01022 
01023 /* Encryption.  */
01024 struct _gpgme_op_encrypt_result
01025 {
01026   /* The list of invalid recipients.  */
01027   gpgme_invalid_key_t invalid_recipients;
01028 };
01029 typedef struct _gpgme_op_encrypt_result *gpgme_encrypt_result_t;
01030 
01031 /* Retrieve a pointer to the result of the encrypt operation.  */
01032 gpgme_encrypt_result_t gpgme_op_encrypt_result (gpgme_ctx_t ctx);
01033 
01034 /* The valid encryption flags.  */
01035 typedef enum
01036   {
01037     GPGME_ENCRYPT_ALWAYS_TRUST = 1
01038   }
01039 gpgme_encrypt_flags_t;
01040 
01041 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
01042    store the resulting ciphertext in CIPHER.  */
01043 gpgme_error_t gpgme_op_encrypt_start (gpgme_ctx_t ctx, gpgme_key_t recp[],
01044                       gpgme_encrypt_flags_t flags,
01045                       gpgme_data_t plain, gpgme_data_t cipher);
01046 gpgme_error_t gpgme_op_encrypt (gpgme_ctx_t ctx, gpgme_key_t recp[],
01047                 gpgme_encrypt_flags_t flags,
01048                 gpgme_data_t plain, gpgme_data_t cipher);
01049 
01050 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
01051    store the resulting ciphertext in CIPHER.  Also sign the ciphertext
01052    with the signers in CTX.  */
01053 gpgme_error_t gpgme_op_encrypt_sign_start (gpgme_ctx_t ctx,
01054                        gpgme_key_t recp[],
01055                        gpgme_encrypt_flags_t flags,
01056                        gpgme_data_t plain,
01057                        gpgme_data_t cipher);
01058 gpgme_error_t gpgme_op_encrypt_sign (gpgme_ctx_t ctx, gpgme_key_t recp[],
01059                      gpgme_encrypt_flags_t flags,
01060                      gpgme_data_t plain, gpgme_data_t cipher);
01061 
01062 
01063 /* Decryption.  */
01064 struct _gpgme_op_decrypt_result
01065 {
01066   char *unsupported_algorithm;
01067 
01068   /* Key should not have been used for encryption.  */
01069   unsigned int wrong_key_usage : 1;
01070 
01071   /* Internal to GPGME, do not use.  */
01072   int _unused : 31;
01073 };
01074 typedef struct _gpgme_op_decrypt_result *gpgme_decrypt_result_t;
01075 
01076 /* Retrieve a pointer to the result of the decrypt operation.  */
01077 gpgme_decrypt_result_t gpgme_op_decrypt_result (gpgme_ctx_t ctx);
01078 
01079 /* Decrypt ciphertext CIPHER within CTX and store the resulting
01080    plaintext in PLAIN.  */
01081 gpgme_error_t gpgme_op_decrypt_start (gpgme_ctx_t ctx, gpgme_data_t cipher,
01082                       gpgme_data_t plain);
01083 gpgme_error_t gpgme_op_decrypt (gpgme_ctx_t ctx,
01084                 gpgme_data_t cipher, gpgme_data_t plain);
01085 
01086 /* Decrypt ciphertext CIPHER and make a signature verification within
01087    CTX and store the resulting plaintext in PLAIN.  */
01088 gpgme_error_t gpgme_op_decrypt_verify_start (gpgme_ctx_t ctx,
01089                          gpgme_data_t cipher,
01090                          gpgme_data_t plain);
01091 gpgme_error_t gpgme_op_decrypt_verify (gpgme_ctx_t ctx, gpgme_data_t cipher,
01092                        gpgme_data_t plain);
01093 
01094 
01095 /* Signing.  */
01096 struct _gpgme_new_signature
01097 {
01098   struct _gpgme_new_signature *next;
01099 
01100   /* The type of the signature.  */
01101   gpgme_sig_mode_t type;
01102 
01103   /* The public key algorithm used to create the signature.  */
01104   gpgme_pubkey_algo_t pubkey_algo;
01105 
01106   /* The hash algorithm used to create the signature.  */
01107   gpgme_hash_algo_t hash_algo;
01108 
01109   /* Internal to GPGME, do not use.  Must be set to the same value as
01110      CLASS below.  */
01111   unsigned long _obsolete_class;
01112 
01113   /* Signature creation time.  */
01114   long int timestamp;
01115 
01116   /* The fingerprint of the signature.  */
01117   char *fpr;
01118 
01119 #ifdef __cplusplus
01120   unsigned int _obsolete_class_2;
01121 #else
01122   /* Must be set to SIG_CLASS below.  */
01123   unsigned int class _GPGME_DEPRECATED;
01124 #endif
01125 
01126   /* Crypto backend specific signature class.  */
01127   unsigned int sig_class;
01128 };
01129 typedef struct _gpgme_new_signature *gpgme_new_signature_t;
01130 
01131 struct _gpgme_op_sign_result
01132 {
01133   /* The list of invalid signers.  */
01134   gpgme_invalid_key_t invalid_signers;
01135   gpgme_new_signature_t signatures;
01136 };
01137 typedef struct _gpgme_op_sign_result *gpgme_sign_result_t;
01138 
01139 /* Retrieve a pointer to the result of the signing operation.  */
01140 gpgme_sign_result_t gpgme_op_sign_result (gpgme_ctx_t ctx);
01141 
01142 /* Sign the plaintext PLAIN and store the signature in SIG.  */
01143 gpgme_error_t gpgme_op_sign_start (gpgme_ctx_t ctx,
01144                    gpgme_data_t plain, gpgme_data_t sig,
01145                    gpgme_sig_mode_t mode);
01146 gpgme_error_t gpgme_op_sign (gpgme_ctx_t ctx,
01147                  gpgme_data_t plain, gpgme_data_t sig,
01148                  gpgme_sig_mode_t mode);
01149 
01150 
01151 /* Verify.  */
01152 struct _gpgme_sig_notation
01153 {
01154   struct _gpgme_sig_notation *next;
01155 
01156   /* If NAME is a null pointer, then VALUE contains a policy URL
01157      rather than a notation.  */
01158   char *name;
01159   char *value;
01160 };
01161 typedef struct _gpgme_sig_notation *gpgme_sig_notation_t;
01162 
01163 /* Flags used for the SUMMARY field in a gpgme_signature_t.  */
01164 typedef enum
01165   {
01166     GPGME_SIGSUM_VALID       = 0x0001,  /* The signature is fully valid.  */
01167     GPGME_SIGSUM_GREEN       = 0x0002,  /* The signature is good.  */
01168     GPGME_SIGSUM_RED         = 0x0004,  /* The signature is bad.  */
01169     GPGME_SIGSUM_KEY_REVOKED = 0x0010,  /* One key has been revoked.  */
01170     GPGME_SIGSUM_KEY_EXPIRED = 0x0020,  /* One key has expired.  */
01171     GPGME_SIGSUM_SIG_EXPIRED = 0x0040,  /* The signature has expired.  */
01172     GPGME_SIGSUM_KEY_MISSING = 0x0080,  /* Can't verify: key missing.  */
01173     GPGME_SIGSUM_CRL_MISSING = 0x0100,  /* CRL not available.  */
01174     GPGME_SIGSUM_CRL_TOO_OLD = 0x0200,  /* Available CRL is too old.  */
01175     GPGME_SIGSUM_BAD_POLICY  = 0x0400,  /* A policy was not met.  */
01176     GPGME_SIGSUM_SYS_ERROR   = 0x0800   /* A system error occured.  */
01177   }
01178 gpgme_sigsum_t;
01179 
01180 struct _gpgme_signature
01181 {
01182   struct _gpgme_signature *next;
01183 
01184   /* A summary of the signature status.  */
01185   gpgme_sigsum_t summary;
01186 
01187   /* The fingerprint or key ID of the signature.  */
01188   char *fpr;
01189 
01190   /* The status of the signature.  */
01191   gpgme_error_t status;
01192 
01193   /* Notation data and policy URLs.  */
01194   gpgme_sig_notation_t notations;
01195 
01196   /* Signature creation time.  */
01197   unsigned long timestamp;
01198 
01199   /* Signature exipration time or 0.  */
01200   unsigned long exp_timestamp;
01201 
01202   /* Key should not have been used for signing.  */
01203   unsigned int wrong_key_usage : 1;
01204 
01205   /* Internal to GPGME, do not use.  */
01206   int _unused : 31;
01207 
01208   gpgme_validity_t validity;
01209   gpgme_error_t validity_reason;
01210 };
01211 typedef struct _gpgme_signature *gpgme_signature_t;
01212 
01213 struct _gpgme_op_verify_result
01214 {
01215   gpgme_signature_t signatures;
01216 };
01217 typedef struct _gpgme_op_verify_result *gpgme_verify_result_t;
01218 
01219 /* Retrieve a pointer to the result of the verify operation.  */
01220 gpgme_verify_result_t gpgme_op_verify_result (gpgme_ctx_t ctx);
01221 
01222 /* Verify within CTX that SIG is a valid signature for TEXT.  */
01223 gpgme_error_t gpgme_op_verify_start (gpgme_ctx_t ctx, gpgme_data_t sig,
01224                      gpgme_data_t signed_text,
01225                      gpgme_data_t plaintext);
01226 gpgme_error_t gpgme_op_verify (gpgme_ctx_t ctx, gpgme_data_t sig,
01227                    gpgme_data_t signed_text,
01228                    gpgme_data_t plaintext);
01229 
01230 
01231 /* Import.  */
01232 enum
01233   {
01234     /* The key was new.  */
01235     GPGME_IMPORT_NEW = 1,
01236 
01237     /* The key contained new user IDs.  */
01238     GPGME_IMPORT_UID = 2,
01239 
01240     /* The key contained new signatures.  */
01241     GPGME_IMPORT_SIG = 4,
01242 
01243     /* The key contained new sub keys.  */
01244     GPGME_IMPORT_SUBKEY = 8,
01245 
01246     /* The key contained a secret key.  */
01247     GPGME_IMPORT_SECRET = 16
01248   };
01249 
01250 struct _gpgme_import_status
01251 {
01252   struct _gpgme_import_status *next;
01253 
01254   /* Fingerprint.  */
01255   char *fpr;
01256 
01257   /* If a problem occured, the reason why the key could not be
01258      imported.  Otherwise GPGME_No_Error.  */
01259   gpgme_error_t result;
01260 
01261   /* The result of the import, the GPGME_IMPORT_* values bit-wise
01262      ORed.  0 means the key was already known and no new components
01263      have been added.  */
01264   unsigned int status;
01265 };
01266 typedef struct _gpgme_import_status *gpgme_import_status_t;
01267 
01268 /* Import.  */
01269 struct _gpgme_op_import_result
01270 {
01271   /* Number of considered keys.  */
01272   int considered;
01273 
01274   /* Keys without user ID.  */
01275   int no_user_id;
01276 
01277   /* Imported keys.  */
01278   int imported;
01279 
01280   /* Imported RSA keys.  */
01281   int imported_rsa;
01282 
01283   /* Unchanged keys.  */
01284   int unchanged;
01285 
01286   /* Number of new user ids.  */
01287   int new_user_ids;
01288 
01289   /* Number of new sub keys.  */
01290   int new_sub_keys;
01291 
01292   /* Number of new signatures.  */
01293   int new_signatures;
01294 
01295   /* Number of new revocations.  */
01296   int new_revocations;
01297 
01298   /* Number of secret keys read.  */
01299   int secret_read;
01300 
01301   /* Number of secret keys imported.  */
01302   int secret_imported;
01303 
01304   /* Number of secret keys unchanged.  */
01305   int secret_unchanged;
01306 
01307   /* Number of new keys skipped.  */
01308   int skipped_new_keys;
01309 
01310   /* Number of keys not imported.  */
01311   int not_imported;
01312 
01313   /* List of keys for which an import was attempted.  */
01314   gpgme_import_status_t imports;
01315 };
01316 typedef struct _gpgme_op_import_result *gpgme_import_result_t;
01317 
01318 /* Retrieve a pointer to the result of the import operation.  */
01319 gpgme_import_result_t gpgme_op_import_result (gpgme_ctx_t ctx);
01320 
01321 /* Import the key in KEYDATA into the keyring.  */
01322 gpgme_error_t gpgme_op_import_start (gpgme_ctx_t ctx, gpgme_data_t keydata);
01323 gpgme_error_t gpgme_op_import (gpgme_ctx_t ctx, gpgme_data_t keydata);
01324 gpgme_error_t gpgme_op_import_ext (gpgme_ctx_t ctx, gpgme_data_t keydata,
01325                    int *nr) _GPGME_DEPRECATED;
01326 
01327 
01328 /* Export the keys found by PATTERN into KEYDATA.  */
01329 gpgme_error_t gpgme_op_export_start (gpgme_ctx_t ctx, const char *pattern,
01330                      unsigned int reserved,
01331                      gpgme_data_t keydata);
01332 gpgme_error_t gpgme_op_export (gpgme_ctx_t ctx, const char *pattern,
01333                    unsigned int reserved, gpgme_data_t keydata);
01334 
01335 gpgme_error_t gpgme_op_export_ext_start (gpgme_ctx_t ctx,
01336                      const char *pattern[],
01337                      unsigned int reserved,
01338                      gpgme_data_t keydata);
01339 gpgme_error_t gpgme_op_export_ext (gpgme_ctx_t ctx, const char *pattern[],
01340                    unsigned int reserved,
01341                    gpgme_data_t keydata);
01342 
01343 
01344 /* Key generation.  */
01345 struct _gpgme_op_genkey_result
01346 {
01347   /* A primary key was generated.  */
01348   unsigned int primary : 1;
01349 
01350   /* A sub key was generated.  */
01351   unsigned int sub : 1;
01352 
01353   /* Internal to GPGME, do not use.  */
01354   unsigned int _unused : 30;
01355 
01356   /* The fingerprint of the generated key.  */
01357   char *fpr;
01358 };
01359 typedef struct _gpgme_op_genkey_result *gpgme_genkey_result_t;
01360 
01361 /* Generate a new keypair and add it to the keyring.  PUBKEY and
01362    SECKEY should be null for now.  PARMS specifies what keys should be
01363    generated.  */
01364 gpgme_error_t gpgme_op_genkey_start (gpgme_ctx_t ctx, const char *parms,
01365                      gpgme_data_t pubkey, gpgme_data_t seckey);
01366 gpgme_error_t gpgme_op_genkey (gpgme_ctx_t ctx, const char *parms,
01367                    gpgme_data_t pubkey, gpgme_data_t seckey);
01368 
01369 /* Retrieve a pointer to the result of the genkey operation.  */
01370 gpgme_genkey_result_t gpgme_op_genkey_result (gpgme_ctx_t ctx);
01371 
01372 
01373 /* Delete KEY from the keyring.  If ALLOW_SECRET is non-zero, secret
01374    keys are also deleted.  */
01375 gpgme_error_t gpgme_op_delete_start (gpgme_ctx_t ctx, const gpgme_key_t key,
01376                      int allow_secret);
01377 gpgme_error_t gpgme_op_delete (gpgme_ctx_t ctx, const gpgme_key_t key,
01378                    int allow_secret);
01379 
01380 
01381 /* Edit the key KEY.  Send status and command requests to FNC and
01382    output of edit commands to OUT.  */
01383 gpgme_error_t gpgme_op_edit_start (gpgme_ctx_t ctx, gpgme_key_t key,
01384                    gpgme_edit_cb_t fnc, void *fnc_value,
01385                    gpgme_data_t out);
01386 gpgme_error_t gpgme_op_edit (gpgme_ctx_t ctx, gpgme_key_t key,
01387                  gpgme_edit_cb_t fnc, void *fnc_value,
01388                  gpgme_data_t out);
01389 
01390 /* Edit the card for the key KEY.  Send status and command requests to
01391    FNC and output of edit commands to OUT.  */
01392 gpgme_error_t gpgme_op_card_edit_start (gpgme_ctx_t ctx, gpgme_key_t key,
01393                     gpgme_edit_cb_t fnc, void *fnc_value,
01394                     gpgme_data_t out);
01395 gpgme_error_t gpgme_op_card_edit (gpgme_ctx_t ctx, gpgme_key_t key,
01396                   gpgme_edit_cb_t fnc, void *fnc_value,
01397                   gpgme_data_t out);
01398 
01399 
01400 /* Key management functions.  */
01401 struct _gpgme_op_keylist_result
01402 {
01403   unsigned int truncated : 1;
01404 
01405   /* Internal to GPGME, do not use.  */
01406   unsigned int _unused : 31;
01407 };
01408 typedef struct _gpgme_op_keylist_result *gpgme_keylist_result_t;
01409 
01410 /* Retrieve a pointer to the result of the key listing operation.  */
01411 gpgme_keylist_result_t gpgme_op_keylist_result (gpgme_ctx_t ctx);
01412 
01413 /* Start a keylist operation within CTX, searching for keys which
01414    match PATTERN.  If SECRET_ONLY is true, only secret keys are
01415    returned.  */
01416 gpgme_error_t gpgme_op_keylist_start (gpgme_ctx_t ctx, const char *pattern,
01417                       int secret_only);
01418 gpgme_error_t gpgme_op_keylist_ext_start (gpgme_ctx_t ctx,
01419                       const char *pattern[],
01420                       int secret_only, int reserved);
01421 
01422 /* Return the next key from the keylist in R_KEY.  */
01423 gpgme_error_t gpgme_op_keylist_next (gpgme_ctx_t ctx, gpgme_key_t *r_key);
01424 
01425 /* Terminate a pending keylist operation within CTX.  */
01426 gpgme_error_t gpgme_op_keylist_end (gpgme_ctx_t ctx);
01427 
01428 
01429 /* Trust items and operations.  */
01430 
01431 struct _gpgme_trust_item
01432 {
01433   /* Internal to GPGME, do not use.  */
01434   unsigned int _refs;
01435 
01436   /* The key ID to which the trust item belongs.  */
01437   char *keyid;
01438 
01439   /* Internal to GPGME, do not use.  */
01440   char _keyid[16 + 1];
01441 
01442   /* The type of the trust item, 1 refers to a key, 2 to a user ID.  */
01443   int type;
01444 
01445   /* The trust level.  */
01446   int level;
01447 
01448   /* The owner trust if TYPE is 1.  */
01449   char *owner_trust;
01450 
01451   /* Internal to GPGME, do not use.  */
01452   char _owner_trust[2];
01453 
01454   /* The calculated validity.  */
01455   char *validity;
01456  
01457   /* Internal to GPGME, do not use.  */
01458   char _validity[2];
01459 
01460   /* The user name if TYPE is 2.  */
01461   char *name;
01462 };
01463 typedef struct _gpgme_trust_item *gpgme_trust_item_t;
01464 
01465 /* Start a trustlist operation within CTX, searching for trust items
01466    which match PATTERN.  */
01467 gpgme_error_t gpgme_op_trustlist_start (gpgme_ctx_t ctx,
01468                     const char *pattern, int max_level);
01469 
01470 /* Return the next trust item from the trustlist in R_ITEM.  */
01471 gpgme_error_t gpgme_op_trustlist_next (gpgme_ctx_t ctx,
01472                        gpgme_trust_item_t *r_item);
01473 
01474 /* Terminate a pending trustlist operation within CTX.  */
01475 gpgme_error_t gpgme_op_trustlist_end (gpgme_ctx_t ctx);
01476 
01477 /* Acquire a reference to ITEM.  */
01478 void gpgme_trust_item_ref (gpgme_trust_item_t item);
01479 
01480 /* Release a reference to ITEM.  If this was the last one the trust
01481    item is destroyed.  */
01482 void gpgme_trust_item_unref (gpgme_trust_item_t item);
01483 
01484 /* Release the trust item ITEM.  Deprecated, use
01485    gpgme_trust_item_unref.  */
01486 void gpgme_trust_item_release (gpgme_trust_item_t item) _GPGME_DEPRECATED;
01487 
01488 /* Return the value of the attribute WHAT of ITEM, which has to be
01489    representable by a string.  Deprecated, use trust item structure
01490    directly.  */
01491 const char *gpgme_trust_item_get_string_attr (gpgme_trust_item_t item,
01492                           _gpgme_attr_t what,
01493                           const void *reserved, int idx)
01494      _GPGME_DEPRECATED;
01495 
01496 /* Return the value of the attribute WHAT of KEY, which has to be
01497    representable by an integer.  IDX specifies a running index if the
01498    attribute appears more than once in the key.  Deprecated, use trust
01499    item structure directly.  */
01500 int gpgme_trust_item_get_int_attr (gpgme_trust_item_t item, _gpgme_attr_t what,
01501                    const void *reserved, int idx)
01502      _GPGME_DEPRECATED;
01503 
01504 
01505 /* Various functions.  */
01506 
01507 /* Check that the library fulfills the version requirement.  */
01508 const char *gpgme_check_version (const char *req_version);
01509 
01510 /* Retrieve information about the backend engines.  */
01511 gpgme_error_t gpgme_get_engine_info (gpgme_engine_info_t *engine_info);
01512 
01513 
01514 /* Engine support functions.  */
01515 
01516 /* Verify that the engine implementing PROTO is installed and
01517    available.  */
01518 gpgme_error_t gpgme_engine_check_version (gpgme_protocol_t proto);
01519 
01520 
01521 /* Deprecated types.  */
01522 typedef gpgme_ctx_t GpgmeCtx _GPGME_DEPRECATED;
01523 typedef gpgme_data_t GpgmeData _GPGME_DEPRECATED;
01524 typedef gpgme_error_t GpgmeError _GPGME_DEPRECATED;
01525 typedef gpgme_data_encoding_t GpgmeDataEncoding _GPGME_DEPRECATED;
01526 typedef gpgme_pubkey_algo_t GpgmePubKeyAlgo _GPGME_DEPRECATED;
01527 typedef gpgme_hash_algo_t GpgmeHashAlgo _GPGME_DEPRECATED;
01528 typedef gpgme_sig_stat_t GpgmeSigStat _GPGME_DEPRECATED;
01529 typedef gpgme_sig_mode_t GpgmeSigMode _GPGME_DEPRECATED;
01530 typedef gpgme_attr_t GpgmeAttr _GPGME_DEPRECATED;
01531 typedef gpgme_validity_t GpgmeValidity _GPGME_DEPRECATED;
01532 typedef gpgme_protocol_t GpgmeProtocol _GPGME_DEPRECATED;
01533 typedef gpgme_engine_info_t GpgmeEngineInfo _GPGME_DEPRECATED;
01534 typedef gpgme_subkey_t GpgmeSubkey _GPGME_DEPRECATED;
01535 typedef gpgme_key_sig_t GpgmeKeySig _GPGME_DEPRECATED;
01536 typedef gpgme_user_id_t GpgmeUserID _GPGME_DEPRECATED;
01537 typedef gpgme_key_t GpgmeKey _GPGME_DEPRECATED;
01538 typedef gpgme_passphrase_cb_t GpgmePassphraseCb _GPGME_DEPRECATED;
01539 typedef gpgme_progress_cb_t GpgmeProgressCb _GPGME_DEPRECATED;
01540 typedef gpgme_io_cb_t GpgmeIOCb _GPGME_DEPRECATED;
01541 typedef gpgme_register_io_cb_t GpgmeRegisterIOCb _GPGME_DEPRECATED;
01542 typedef gpgme_remove_io_cb_t GpgmeRemoveIOCb _GPGME_DEPRECATED;
01543 typedef gpgme_event_io_t GpgmeEventIO _GPGME_DEPRECATED;
01544 typedef gpgme_event_io_cb_t GpgmeEventIOCb _GPGME_DEPRECATED;
01545 #define GpgmeIOCbs gpgme_io_cbs
01546 typedef gpgme_data_read_cb_t GpgmeDataReadCb _GPGME_DEPRECATED;
01547 typedef gpgme_data_write_cb_t GpgmeDataWriteCb _GPGME_DEPRECATED;
01548 typedef gpgme_data_seek_cb_t GpgmeDataSeekCb _GPGME_DEPRECATED;
01549 typedef gpgme_data_release_cb_t GpgmeDataReleaseCb _GPGME_DEPRECATED;
01550 #define GpgmeDataCbs gpgme_data_cbs
01551 typedef gpgme_encrypt_result_t GpgmeEncryptResult _GPGME_DEPRECATED;
01552 typedef gpgme_sig_notation_t GpgmeSigNotation _GPGME_DEPRECATED;
01553 typedef gpgme_signature_t GpgmeSignature _GPGME_DEPRECATED;
01554 typedef gpgme_verify_result_t GpgmeVerifyResult _GPGME_DEPRECATED;
01555 typedef gpgme_import_status_t GpgmeImportStatus _GPGME_DEPRECATED;
01556 typedef gpgme_import_result_t GpgmeImportResult _GPGME_DEPRECATED;
01557 typedef gpgme_genkey_result_t GpgmeGenKeyResult _GPGME_DEPRECATED;
01558 typedef gpgme_trust_item_t GpgmeTrustItem _GPGME_DEPRECATED;
01559 typedef gpgme_status_code_t GpgmeStatusCode _GPGME_DEPRECATED;
01560 
01561 #ifdef __cplusplus
01562 }
01563 #endif
01564 #endif /* GPGME_H */
KDE Logo
This file is part of the documentation for libkdenetwork Library Version 3.3.2.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Fri Dec 21 14:21:38 2007 by doxygen 1.4.2 written by Dimitri van Heesch, © 1997-2003