gpgme/gpgme.h

   1 /* gpgme.h - Public interface to GnuPG Made Easy.
   2    Copyright (C) 2000 Werner Koch (dd9jn)
   3    Copyright (C) 2001, 2002, 2003, 2004, 2005 g10 Code GmbH
   4
   5    This file is part of GPGME.
   6
   7    GPGME is free software; you can redistribute it and/or modify it
   8    under the terms of the GNU Lesser General Public License as
   9    published by the Free Software Foundation; either version 2.1 of
  10    the License, or (at your option) any later version.
  11
  12    GPGME is distributed in the hope that it will be useful, but
  13    WITHOUT ANY WARRANTY; without even the implied warranty of
  14    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15    Lesser General Public License for more details.
  16
  17    You should have received a copy of the GNU Lesser General Public
  18    License along with this program; if not, write to the Free Software
  19    Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
  20    02111-1307, USA.  */
  21
  22 #ifndef GPGME_H
  23 #define GPGME_H
  24
  25 #ifdef __GNUC__
  26 #define _GPGME_INLINE __inline__
  27 #elif __STDC_VERSION__ >= 199901L
  28 #define _GPGME_INLINE inline
  29 #else
  30 #define _GPGME_INLINE
  31 #endif
  32
  33 /* Include stdio.h for the FILE type definition.  */
  34 #include <stdio.h>
  35
  36 #ifdef _MSC_VER
  37   typedef long off_t;
  38   typedef long ssize_t;
  39 #else
  40 # include <sys/types.h>
  41 #endif
  42
  43 #ifdef __cplusplus
  44 extern "C" {
  45 #if 0 /* just to make Emacs auto-indent happy */
  46 }
  47 #endif
  48 #endif /* __cplusplus */
  49
  50 #include <gpg-error.h>
  51
  52 \f
  53 /* Check for compiler features.  */
  54 #if __GNUC__
  55 #define _GPGME_GCC_VERSION (__GNUC__ * 10000 \
  56                             + __GNUC_MINOR__ * 100 \
  57                             + __GNUC_PATCHLEVEL__)
  58
  59 #if _GPGME_GCC_VERSION > 30100
  60 #define _GPGME_DEPRECATED       __attribute__ ((__deprecated__))
  61 #endif
  62 #endif
  63
  64 #ifndef _GPGME_DEPRECATED
  65 #define _GPGME_DEPRECATED
  66 #endif
  67
  68 \f
  69 /* The version of this header should match the one of the library.  Do
  70    not use this symbol in your application, use gpgme_check_version
  71    instead.  The purpose of this macro is to let autoconf (using the
  72    AM_PATH_GPGME macro) check that this header matches the installed
  73    library.  Warning: Do not edit the next line.  configure will do
  74    that for you!  */
  75 #define GPGME_VERSION "1.1.5-cvs1228"
  76
  77
  78 \f
  79 /* Some opaque data types used by GPGME.  */
  80
  81 /* The context holds some global state and configration options, as
  82    well as the results of a crypto operation.  */
  83 struct gpgme_context;
  84 typedef struct gpgme_context *gpgme_ctx_t;
  85
  86 /* The data object is used by GPGME to exchange arbitrary data.  */
  87 struct gpgme_data;
  88 typedef struct gpgme_data *gpgme_data_t;
  89
  90 \f
  91 /* Wrappers for the libgpg-error library.  */
  92
  93 typedef gpg_error_t gpgme_error_t;
  94 typedef gpg_err_code_t gpgme_err_code_t;
  95 typedef gpg_err_source_t gpgme_err_source_t;
  96
  97
  98 static _GPGME_INLINE gpgme_error_t
  99 gpgme_err_make (gpgme_err_source_t source, gpgme_err_code_t code)
 100 {
 101   return gpg_err_make (source, code);
 102 }
 103
 104
 105 /* The user can define GPGME_ERR_SOURCE_DEFAULT before including this
 106    file to specify a default source for gpgme_error.  */
 107 #ifndef GPGME_ERR_SOURCE_DEFAULT
 108 #define GPGME_ERR_SOURCE_DEFAULT  GPG_ERR_SOURCE_USER_1
 109 #endif
 110
 111 static _GPGME_INLINE gpgme_error_t
 112 gpgme_error (gpgme_err_code_t code)
 113 {
 114   return gpgme_err_make (GPGME_ERR_SOURCE_DEFAULT, code);
 115 }
 116
 117
 118 static _GPGME_INLINE gpgme_err_code_t
 119 gpgme_err_code (gpgme_error_t err)
 120 {
 121   return gpg_err_code (err);
 122 }
 123
 124
 125 static _GPGME_INLINE gpgme_err_source_t
 126 gpgme_err_source (gpgme_error_t err)
 127 {
 128   return gpg_err_source (err);
 129 }
 130
 131
 132 /* Return a pointer to a string containing a description of the error
 133    code in the error value ERR.  This function is not thread safe.  */
 134 const char *gpgme_strerror (gpgme_error_t err);
 135
 136 /* Return the error string for ERR in the user-supplied buffer BUF of
 137    size BUFLEN.  This function is, in contrast to gpg_strerror,
 138    thread-safe if a thread-safe strerror_r() function is provided by
 139    the system.  If the function succeeds, 0 is returned and BUF
 140    contains the string describing the error.  If the buffer was not
 141    large enough, ERANGE is returned and BUF contains as much of the
 142    beginning of the error string as fits into the buffer.  */
 143 int gpgme_strerror_r (gpg_error_t err, char *buf, size_t buflen);
 144
 145
 146 /* Return a pointer to a string containing a description of the error
 147    source in the error value ERR.  */
 148 const char *gpgme_strsource (gpgme_error_t err);
 149
 150
 151 /* Retrieve the error code for the system error ERR.  This returns
 152    GPG_ERR_UNKNOWN_ERRNO if the system error is not mapped (report
 153    this).  */
 154 gpgme_err_code_t gpgme_err_code_from_errno (int err);
 155
 156
 157 /* Retrieve the system error for the error code CODE.  This returns 0
 158    if CODE is not a system error code.  */
 159 int gpgme_err_code_to_errno (gpgme_err_code_t code);
 160
 161
 162 /* Return an error value with the error source SOURCE and the system
 163    error ERR.  */
 164 gpgme_error_t gpgme_err_make_from_errno (gpgme_err_source_t source, int err);
 165
 166
 167 /* Return an error value with the system error ERR.  */
 168 gpgme_err_code_t gpgme_error_from_errno (int err);
 169
 170 \f
 171 /* The possible encoding mode of gpgme_data_t objects.  */
 172 typedef enum
 173   {
 174     GPGME_DATA_ENCODING_NONE   = 0,     /* Not specified.  */
 175     GPGME_DATA_ENCODING_BINARY = 1,
 176     GPGME_DATA_ENCODING_BASE64 = 2,
 177     GPGME_DATA_ENCODING_ARMOR  = 3      /* Either PEM or OpenPGP Armor.  */
 178   }
 179 gpgme_data_encoding_t;
 180
 181 \f
 182 /* Public key algorithms from libgcrypt.  */
 183 typedef enum
 184   {
 185     GPGME_PK_RSA   = 1,
 186     GPGME_PK_RSA_E = 2,
 187     GPGME_PK_RSA_S = 3,
 188     GPGME_PK_ELG_E = 16,
 189     GPGME_PK_DSA   = 17,
 190     GPGME_PK_ELG   = 20
 191   }
 192 gpgme_pubkey_algo_t;
 193
 194
 195 /* Hash algorithms from libgcrypt.  */
 196 typedef enum
 197   {
 198     GPGME_MD_NONE          = 0,
 199     GPGME_MD_MD5           = 1,
 200     GPGME_MD_SHA1          = 2,
 201     GPGME_MD_RMD160        = 3,
 202     GPGME_MD_MD2           = 5,
 203     GPGME_MD_TIGER         = 6,   /* TIGER/192. */
 204     GPGME_MD_HAVAL         = 7,   /* HAVAL, 5 pass, 160 bit. */
 205     GPGME_MD_SHA256        = 8,
 206     GPGME_MD_SHA384        = 9,
 207     GPGME_MD_SHA512        = 10,
 208     GPGME_MD_MD4           = 301,
 209     GPGME_MD_CRC32         = 302,
 210     GPGME_MD_CRC32_RFC1510 = 303,
 211     GPGME_MD_CRC24_RFC2440 = 304
 212   }
 213 gpgme_hash_algo_t;
 214
 215 \f
 216 /* The possible signature stati.  Deprecated, use error value in sig
 217    status.  */
 218 typedef enum
 219   {
 220     GPGME_SIG_STAT_NONE  = 0,
 221     GPGME_SIG_STAT_GOOD  = 1,
 222     GPGME_SIG_STAT_BAD   = 2,
 223     GPGME_SIG_STAT_NOKEY = 3,
 224     GPGME_SIG_STAT_NOSIG = 4,
 225     GPGME_SIG_STAT_ERROR = 5,
 226     GPGME_SIG_STAT_DIFF  = 6,
 227     GPGME_SIG_STAT_GOOD_EXP = 7,
 228     GPGME_SIG_STAT_GOOD_EXPKEY = 8
 229   }
 230 _gpgme_sig_stat_t;
 231 typedef _gpgme_sig_stat_t gpgme_sig_stat_t _GPGME_DEPRECATED;
 232
 233
 234 /* The available signature modes.  */
 235 typedef enum
 236   {
 237     GPGME_SIG_MODE_NORMAL = 0,
 238     GPGME_SIG_MODE_DETACH = 1,
 239     GPGME_SIG_MODE_CLEAR  = 2
 240   }
 241 gpgme_sig_mode_t;
 242
 243 \f
 244 /* The available key and signature attributes.  Deprecated, use the
 245    individual result structures instead.  */
 246 typedef enum
 247   {
 248     GPGME_ATTR_KEYID        = 1,
 249     GPGME_ATTR_FPR          = 2,
 250     GPGME_ATTR_ALGO         = 3,
 251     GPGME_ATTR_LEN          = 4,
 252     GPGME_ATTR_CREATED      = 5,
 253     GPGME_ATTR_EXPIRE       = 6,
 254     GPGME_ATTR_OTRUST       = 7,
 255     GPGME_ATTR_USERID       = 8,
 256     GPGME_ATTR_NAME         = 9,
 257     GPGME_ATTR_EMAIL        = 10,
 258     GPGME_ATTR_COMMENT      = 11,
 259     GPGME_ATTR_VALIDITY     = 12,
 260     GPGME_ATTR_LEVEL        = 13,
 261     GPGME_ATTR_TYPE         = 14,
 262     GPGME_ATTR_IS_SECRET    = 15,
 263     GPGME_ATTR_KEY_REVOKED  = 16,
 264     GPGME_ATTR_KEY_INVALID  = 17,
 265     GPGME_ATTR_UID_REVOKED  = 18,
 266     GPGME_ATTR_UID_INVALID  = 19,
 267     GPGME_ATTR_KEY_CAPS     = 20,
 268     GPGME_ATTR_CAN_ENCRYPT  = 21,
 269     GPGME_ATTR_CAN_SIGN     = 22,
 270     GPGME_ATTR_CAN_CERTIFY  = 23,
 271     GPGME_ATTR_KEY_EXPIRED  = 24,
 272     GPGME_ATTR_KEY_DISABLED = 25,
 273     GPGME_ATTR_SERIAL       = 26,
 274     GPGME_ATTR_ISSUER       = 27,
 275     GPGME_ATTR_CHAINID      = 28,
 276     GPGME_ATTR_SIG_STATUS   = 29,
 277     GPGME_ATTR_ERRTOK       = 30,
 278     GPGME_ATTR_SIG_SUMMARY  = 31,
 279     GPGME_ATTR_SIG_CLASS    = 32
 280   }
 281 _gpgme_attr_t;
 282 typedef _gpgme_attr_t gpgme_attr_t _GPGME_DEPRECATED;
 283
 284 \f
 285 /* The available validities for a trust item or key.  */
 286 typedef enum
 287   {
 288     GPGME_VALIDITY_UNKNOWN   = 0,
 289     GPGME_VALIDITY_UNDEFINED = 1,
 290     GPGME_VALIDITY_NEVER     = 2,
 291     GPGME_VALIDITY_MARGINAL  = 3,
 292     GPGME_VALIDITY_FULL      = 4,
 293     GPGME_VALIDITY_ULTIMATE  = 5
 294   }
 295 gpgme_validity_t;
 296
 297 \f
 298 /* The available protocols.  */
 299 typedef enum
 300   {
 301     GPGME_PROTOCOL_OpenPGP = 0,  /* The default mode.  */
 302     GPGME_PROTOCOL_CMS     = 1
 303   }
 304 gpgme_protocol_t;
 305
 306 \f
 307 /* The available keylist mode flags.  */
 308 #define GPGME_KEYLIST_MODE_LOCAL                1
 309 #define GPGME_KEYLIST_MODE_EXTERN               2
 310 #define GPGME_KEYLIST_MODE_SIGS                 4
 311 #define GPGME_KEYLIST_MODE_SIG_NOTATIONS        8
 312 #define GPGME_KEYLIST_MODE_VALIDATE             256
 313
 314 typedef unsigned int gpgme_keylist_mode_t;
 315
 316 \f
 317 /* Signature notations.  */
 318
 319 /* The available signature notation flags.  */
 320 #define GPGME_SIG_NOTATION_HUMAN_READABLE       1
 321 #define GPGME_SIG_NOTATION_CRITICAL             2
 322
 323 typedef unsigned int gpgme_sig_notation_flags_t;
 324
 325 struct _gpgme_sig_notation
 326 {
 327   struct _gpgme_sig_notation *next;
 328
 329   /* If NAME is a null pointer, then VALUE contains a policy URL
 330      rather than a notation.  */
 331   char *name;
 332
 333   /* The value of the notation data.  */
 334   char *value;
 335
 336   /* The length of the name of the notation data.  */
 337   int name_len;
 338
 339   /* The length of the value of the notation data.  */
 340   int value_len;
 341
 342   /* The accumulated flags.  */
 343   gpgme_sig_notation_flags_t flags;
 344
 345   /* Notation data is human-readable.  */
 346   unsigned int human_readable : 1;
 347
 348   /* Notation data is critical.  */
 349   unsigned int critical : 1;
 350
 351   /* Internal to GPGME, do not use.  */
 352   int _unused : 30;
 353 };
 354 typedef struct _gpgme_sig_notation *gpgme_sig_notation_t;
 355
 356 \f
 357 /* The possible stati for the edit operation.  */
 358 typedef enum
 359   {
 360     GPGME_STATUS_EOF,
 361     /* mkstatus processing starts here */
 362     GPGME_STATUS_ENTER,
 363     GPGME_STATUS_LEAVE,
 364     GPGME_STATUS_ABORT,
 365
 366     GPGME_STATUS_GOODSIG,
 367     GPGME_STATUS_BADSIG,
 368     GPGME_STATUS_ERRSIG,
 369
 370     GPGME_STATUS_BADARMOR,
 371
 372     GPGME_STATUS_RSA_OR_IDEA,
 373     GPGME_STATUS_KEYEXPIRED,
 374     GPGME_STATUS_KEYREVOKED,
 375
 376     GPGME_STATUS_TRUST_UNDEFINED,
 377     GPGME_STATUS_TRUST_NEVER,
 378     GPGME_STATUS_TRUST_MARGINAL,
 379     GPGME_STATUS_TRUST_FULLY,
 380     GPGME_STATUS_TRUST_ULTIMATE,
 381
 382     GPGME_STATUS_SHM_INFO,
 383     GPGME_STATUS_SHM_GET,
 384     GPGME_STATUS_SHM_GET_BOOL,
 385     GPGME_STATUS_SHM_GET_HIDDEN,
 386
 387     GPGME_STATUS_NEED_PASSPHRASE,
 388     GPGME_STATUS_VALIDSIG,
 389     GPGME_STATUS_SIG_ID,
 390     GPGME_STATUS_ENC_TO,
 391     GPGME_STATUS_NODATA,
 392     GPGME_STATUS_BAD_PASSPHRASE,
 393     GPGME_STATUS_NO_PUBKEY,
 394     GPGME_STATUS_NO_SECKEY,
 395     GPGME_STATUS_NEED_PASSPHRASE_SYM,
 396     GPGME_STATUS_DECRYPTION_FAILED,
 397     GPGME_STATUS_DECRYPTION_OKAY,
 398     GPGME_STATUS_MISSING_PASSPHRASE,
 399     GPGME_STATUS_GOOD_PASSPHRASE,
 400     GPGME_STATUS_GOODMDC,
 401     GPGME_STATUS_BADMDC,
 402     GPGME_STATUS_ERRMDC,
 403     GPGME_STATUS_IMPORTED,
 404     GPGME_STATUS_IMPORT_OK,
 405     GPGME_STATUS_IMPORT_PROBLEM,
 406     GPGME_STATUS_IMPORT_RES,
 407     GPGME_STATUS_FILE_START,
 408     GPGME_STATUS_FILE_DONE,
 409     GPGME_STATUS_FILE_ERROR,
 410
 411     GPGME_STATUS_BEGIN_DECRYPTION,
 412     GPGME_STATUS_END_DECRYPTION,
 413     GPGME_STATUS_BEGIN_ENCRYPTION,
 414     GPGME_STATUS_END_ENCRYPTION,
 415
 416     GPGME_STATUS_DELETE_PROBLEM,
 417     GPGME_STATUS_GET_BOOL,
 418     GPGME_STATUS_GET_LINE,
 419     GPGME_STATUS_GET_HIDDEN,
 420     GPGME_STATUS_GOT_IT,
 421     GPGME_STATUS_PROGRESS,
 422     GPGME_STATUS_SIG_CREATED,
 423     GPGME_STATUS_SESSION_KEY,
 424     GPGME_STATUS_NOTATION_NAME,
 425     GPGME_STATUS_NOTATION_DATA,
 426     GPGME_STATUS_POLICY_URL,
 427     GPGME_STATUS_BEGIN_STREAM,
 428     GPGME_STATUS_END_STREAM,
 429     GPGME_STATUS_KEY_CREATED,
 430     GPGME_STATUS_USERID_HINT,
 431     GPGME_STATUS_UNEXPECTED,
 432     GPGME_STATUS_INV_RECP,
 433     GPGME_STATUS_NO_RECP,
 434     GPGME_STATUS_ALREADY_SIGNED,
 435     GPGME_STATUS_SIGEXPIRED,
 436     GPGME_STATUS_EXPSIG,
 437     GPGME_STATUS_EXPKEYSIG,
 438     GPGME_STATUS_TRUNCATED,
 439     GPGME_STATUS_ERROR,
 440     GPGME_STATUS_NEWSIG,
 441     GPGME_STATUS_REVKEYSIG,
 442     GPGME_STATUS_SIG_SUBPACKET,
 443     GPGME_STATUS_NEED_PASSPHRASE_PIN,
 444     GPGME_STATUS_SC_OP_FAILURE,
 445     GPGME_STATUS_SC_OP_SUCCESS,
 446     GPGME_STATUS_CARDCTRL,
 447     GPGME_STATUS_BACKUP_KEY_CREATED,
 448     GPGME_STATUS_PKA_TRUST_BAD,
 449     GPGME_STATUS_PKA_TRUST_GOOD,
 450
 451     GPGME_STATUS_PLAINTEXT
 452   }
 453 gpgme_status_code_t;
 454
 455 \f
 456 /* The engine information structure.  */
 457 struct _gpgme_engine_info
 458 {
 459   struct _gpgme_engine_info *next;
 460
 461   /* The protocol ID.  */
 462   gpgme_protocol_t protocol;
 463
 464   /* The file name of the engine binary.  */
 465   char *file_name;
 466
 467   /* The version string of the installed engine.  */
 468   char *version;
 469
 470   /* The minimum version required for GPGME.  */
 471   const char *req_version;
 472
 473   /* The home directory used, or NULL if default.  */
 474   char *home_dir;
 475 };
 476 typedef struct _gpgme_engine_info *gpgme_engine_info_t;
 477
 478 \f
 479 /* A subkey from a key.  */
 480 struct _gpgme_subkey
 481 {
 482   struct _gpgme_subkey *next;
 483
 484   /* True if subkey is revoked.  */
 485   unsigned int revoked : 1;
 486
 487   /* True if subkey is expired.  */
 488   unsigned int expired : 1;
 489
 490   /* True if subkey is disabled.  */
 491   unsigned int disabled : 1;
 492
 493   /* True if subkey is invalid.  */
 494   unsigned int invalid : 1;
 495
 496   /* True if subkey can be used for encryption.  */
 497   unsigned int can_encrypt : 1;
 498
 499   /* True if subkey can be used for signing.  */
 500   unsigned int can_sign : 1;
 501
 502   /* True if subkey can be used for certification.  */
 503   unsigned int can_certify : 1;
 504
 505   /* True if subkey is secret.  */
 506   unsigned int secret : 1;
 507
 508   /* True if subkey can be used for authentication.  */
 509   unsigned int can_authenticate : 1;
 510
 511   /* True if subkey is qualified for signatures according to German law.  */
 512   unsigned int is_qualified : 1;
 513
 514   /* Internal to GPGME, do not use.  */
 515   unsigned int _unused : 22;
 516
 517   /* Public key algorithm supported by this subkey.  */
 518   gpgme_pubkey_algo_t pubkey_algo;
 519
 520   /* Length of the subkey.  */
 521   unsigned int length;
 522
 523   /* The key ID of the subkey.  */
 524   char *keyid;
 525
 526   /* Internal to GPGME, do not use.  */
 527   char _keyid[16 + 1];
 528
 529   /* The fingerprint of the subkey in hex digit form.  */
 530   char *fpr;
 531
 532   /* The creation timestamp, -1 if invalid, 0 if not available.  */
 533   long int timestamp;
 534
 535   /* The expiration timestamp, 0 if the subkey does not expire.  */
 536   long int expires;
 537 };
 538 typedef struct _gpgme_subkey *gpgme_subkey_t;
 539
 540
 541 /* A signature on a user ID.  */
 542 struct _gpgme_key_sig
 543 {
 544   struct _gpgme_key_sig *next;
 545
 546   /* True if the signature is a revocation signature.  */
 547   unsigned int revoked : 1;
 548
 549   /* True if the signature is expired.  */
 550   unsigned int expired : 1;
 551
 552   /* True if the signature is invalid.  */
 553   unsigned int invalid : 1;
 554
 555   /* True if the signature should be exported.  */
 556   unsigned int exportable : 1;
 557
 558   /* Internal to GPGME, do not use.  */
 559   unsigned int _unused : 28;
 560
 561   /* The public key algorithm used to create the signature.  */
 562   gpgme_pubkey_algo_t pubkey_algo;
 563
 564   /* The key ID of key used to create the signature.  */
 565   char *keyid;
 566
 567   /* Internal to GPGME, do not use.  */
 568   char _keyid[16 + 1];
 569
 570   /* The creation timestamp, -1 if invalid, 0 if not available.  */
 571   long int timestamp;
 572
 573   /* The expiration timestamp, 0 if the subkey does not expire.  */
 574   long int expires;
 575
 576   /* Same as in gpgme_signature_t.  */
 577   gpgme_error_t status;
 578
 579 #ifdef __cplusplus
 580   unsigned int _obsolete_class _GPGME_DEPRECATED;
 581 #else
 582   /* Must be set to SIG_CLASS below.  */
 583   unsigned int class _GPGME_DEPRECATED;
 584 #endif
 585
 586   /* The user ID string.  */
 587   char *uid;
 588
 589   /* The name part of the user ID.  */
 590   char *name;
 591
 592   /* The email part of the user ID.  */
 593   char *email;
 594
 595   /* The comment part of the user ID.  */
 596   char *comment;
 597
 598   /* Crypto backend specific signature class.  */
 599   unsigned int sig_class;
 600
 601   /* Notation data and policy URLs.  */
 602   gpgme_sig_notation_t notations;
 603
 604   /* Internal to GPGME, do not use.  */
 605   gpgme_sig_notation_t _last_notation;
 606 };
 607 typedef struct _gpgme_key_sig *gpgme_key_sig_t;
 608
 609
 610 /* An user ID from a key.  */
 611 struct _gpgme_user_id
 612 {
 613   struct _gpgme_user_id *next;
 614
 615   /* True if the user ID is revoked.  */
 616   unsigned int revoked : 1;
 617
 618   /* True if the user ID is invalid.  */
 619   unsigned int invalid : 1;
 620
 621   /* Internal to GPGME, do not use.  */
 622   unsigned int _unused : 30;
 623
 624   /* The validity of the user ID.  */
 625   gpgme_validity_t validity;
 626
 627   /* The user ID string.  */
 628   char *uid;
 629
 630   /* The name part of the user ID.  */
 631   char *name;
 632
 633   /* The email part of the user ID.  */
 634   char *email;
 635
 636   /* The comment part of the user ID.  */
 637   char *comment;
 638
 639   /* The signatures of the user ID.  */
 640   gpgme_key_sig_t signatures;
 641
 642   /* Internal to GPGME, do not use.  */
 643   gpgme_key_sig_t _last_keysig;
 644 };
 645 typedef struct _gpgme_user_id *gpgme_user_id_t;
 646
 647
 648 /* A key from the keyring.  */
 649 struct _gpgme_key
 650 {
 651   /* Internal to GPGME, do not use.  */
 652   unsigned int _refs;
 653
 654   /* True if key is revoked.  */
 655   unsigned int revoked : 1;
 656
 657   /* True if key is expired.  */
 658   unsigned int expired : 1;
 659
 660   /* True if key is disabled.  */
 661   unsigned int disabled : 1;
 662
 663   /* True if key is invalid.  */
 664   unsigned int invalid : 1;
 665
 666   /* True if key can be used for encryption.  */
 667   unsigned int can_encrypt : 1;
 668
 669   /* True if key can be used for signing.  */
 670   unsigned int can_sign : 1;
 671
 672   /* True if key can be used for certification.  */
 673   unsigned int can_certify : 1;
 674
 675   /* True if key is secret.  */
 676   unsigned int secret : 1;
 677
 678   /* True if key can be used for authentication.  */
 679   unsigned int can_authenticate : 1;
 680
 681   /* True if subkey is qualified for signatures according to German law.  */
 682   unsigned int is_qualified : 1;
 683
 684   /* Internal to GPGME, do not use.  */
 685   unsigned int _unused : 22;
 686
 687   /* This is the protocol supported by this key.  */
 688   gpgme_protocol_t protocol;
 689
 690   /* If protocol is GPGME_PROTOCOL_CMS, this string contains the
 691      issuer serial.  */
 692   char *issuer_serial;
 693
 694   /* If protocol is GPGME_PROTOCOL_CMS, this string contains the
 695      issuer name.  */
 696   char *issuer_name;
 697
 698   /* If protocol is GPGME_PROTOCOL_CMS, this string contains the chain
 699      ID.  */
 700   char *chain_id;
 701
 702   /* If protocol is GPGME_PROTOCOL_OpenPGP, this field contains the
 703      owner trust.  */
 704   gpgme_validity_t owner_trust;
 705
 706   /* The subkeys of the key.  */
 707   gpgme_subkey_t subkeys;
 708
 709   /* The user IDs of the key.  */
 710   gpgme_user_id_t uids;
 711
 712   /* Internal to GPGME, do not use.  */
 713   gpgme_subkey_t _last_subkey;
 714
 715   /* Internal to GPGME, do not use.  */
 716   gpgme_user_id_t _last_uid;
 717
 718   /* The keylist mode that was active when listing the key.  */
 719   gpgme_keylist_mode_t keylist_mode;
 720 };
 721 typedef struct _gpgme_key *gpgme_key_t;
 722
 723
 724 \f
 725 /* Types for callback functions.  */
 726
 727 /* Request a passphrase from the user.  */
 728 typedef gpgme_error_t (*gpgme_passphrase_cb_t) (void *hook,
 729                                                 const char *uid_hint,
 730                                                 const char *passphrase_info,
 731                                                 int prev_was_bad, int fd);
 732
 733 /* Inform the user about progress made.  */
 734 typedef void (*gpgme_progress_cb_t) (void *opaque, const char *what,
 735                                      int type, int current, int total);
 736
 737 /* Interact with the user about an edit operation.  */
 738 typedef gpgme_error_t (*gpgme_edit_cb_t) (void *opaque,
 739                                           gpgme_status_code_t status,
 740                                           const char *args, int fd);
 741
 742 \f
 743 /* Context management functions.  */
 744
 745 /* Create a new context and return it in CTX.  */
 746 gpgme_error_t gpgme_new (gpgme_ctx_t *ctx);
 747
 748 /* Release the context CTX.  */
 749 void gpgme_release (gpgme_ctx_t ctx);
 750
 751 /* Set the protocol to be used by CTX to PROTO.  */
 752 gpgme_error_t gpgme_set_protocol (gpgme_ctx_t ctx, gpgme_protocol_t proto);
 753
 754 /* Get the protocol used with CTX */
 755 gpgme_protocol_t gpgme_get_protocol (gpgme_ctx_t ctx);
 756
 757 /* Get the string describing protocol PROTO, or NULL if invalid.  */
 758 const char *gpgme_get_protocol_name (gpgme_protocol_t proto);
 759
 760 /* If YES is non-zero, enable armor mode in CTX, disable it otherwise.  */
 761 void gpgme_set_armor (gpgme_ctx_t ctx, int yes);
 762
 763 /* Return non-zero if armor mode is set in CTX.  */
 764 int gpgme_get_armor (gpgme_ctx_t ctx);
 765
 766 /* If YES is non-zero, enable text mode in CTX, disable it otherwise.  */
 767 void gpgme_set_textmode (gpgme_ctx_t ctx, int yes);
 768
 769 /* Return non-zero if text mode is set in CTX.  */
 770 int gpgme_get_textmode (gpgme_ctx_t ctx);
 771
 772 /* Use whatever the default of the backend crypto engine is.  */
 773 #define GPGME_INCLUDE_CERTS_DEFAULT     -256
 774
 775 /* Include up to NR_OF_CERTS certificates in an S/MIME message.  */
 776 void gpgme_set_include_certs (gpgme_ctx_t ctx, int nr_of_certs);
 777
 778 /* Return the number of certs to include in an S/MIME message.  */
 779 int gpgme_get_include_certs (gpgme_ctx_t ctx);
 780
 781 /* Set keylist mode in CTX to MODE.  */
 782 gpgme_error_t gpgme_set_keylist_mode (gpgme_ctx_t ctx,
 783                                       gpgme_keylist_mode_t mode);
 784
 785 /* Get keylist mode in CTX.  */
 786 gpgme_keylist_mode_t gpgme_get_keylist_mode (gpgme_ctx_t ctx);
 787
 788 /* Set the passphrase callback function in CTX to CB.  HOOK_VALUE is
 789    passed as first argument to the passphrase callback function.  */
 790 void gpgme_set_passphrase_cb (gpgme_ctx_t ctx,
 791                               gpgme_passphrase_cb_t cb, void *hook_value);
 792
 793 /* Get the current passphrase callback function in *CB and the current
 794    hook value in *HOOK_VALUE.  */
 795 void gpgme_get_passphrase_cb (gpgme_ctx_t ctx, gpgme_passphrase_cb_t *cb,
 796                               void **hook_value);
 797
 798 /* Set the progress callback function in CTX to CB.  HOOK_VALUE is
 799    passed as first argument to the progress callback function.  */
 800 void gpgme_set_progress_cb (gpgme_ctx_t c, gpgme_progress_cb_t cb,
 801                             void *hook_value);
 802
 803 /* Get the current progress callback function in *CB and the current
 804    hook value in *HOOK_VALUE.  */
 805 void gpgme_get_progress_cb (gpgme_ctx_t ctx, gpgme_progress_cb_t *cb,
 806                             void **hook_value);
 807
 808 /* This function sets the locale for the context CTX, or the default
 809    locale if CTX is a null pointer.  */
 810 gpgme_error_t gpgme_set_locale (gpgme_ctx_t ctx, int category,
 811                                 const char *value);
 812
 813 /* Get the information about the configured engines.  A pointer to the
 814    first engine in the statically allocated linked list is returned.
 815    The returned data is valid until the next gpgme_ctx_set_engine_info.  */
 816 gpgme_engine_info_t gpgme_ctx_get_engine_info (gpgme_ctx_t ctx);
 817
 818 /* Set the engine info for the context CTX, protocol PROTO, to the
 819    file name FILE_NAME and the home directory HOME_DIR.  */
 820 gpgme_error_t gpgme_ctx_set_engine_info (gpgme_ctx_t ctx,
 821                                          gpgme_protocol_t proto,
 822                                          const char *file_name,
 823                                          const char *home_dir);
 824
 825 \f
 826 /* Return a statically allocated string with the name of the public
 827    key algorithm ALGO, or NULL if that name is not known.  */
 828 const char *gpgme_pubkey_algo_name (gpgme_pubkey_algo_t algo);
 829
 830 /* Return a statically allocated string with the name of the hash
 831    algorithm ALGO, or NULL if that name is not known.  */
 832 const char *gpgme_hash_algo_name (gpgme_hash_algo_t algo);
 833
 834 \f
 835 /* Delete all signers from CTX.  */
 836 void gpgme_signers_clear (gpgme_ctx_t ctx);
 837
 838 /* Add KEY to list of signers in CTX.  */
 839 gpgme_error_t gpgme_signers_add (gpgme_ctx_t ctx, const gpgme_key_t key);
 840
 841 /* Return the SEQth signer's key in CTX.  */
 842 gpgme_key_t gpgme_signers_enum (const gpgme_ctx_t ctx, int seq);
 843
 844 /* Retrieve the signature status of signature IDX in CTX after a
 845    successful verify operation in R_STAT (if non-null).  The creation
 846    time stamp of the signature is returned in R_CREATED (if non-null).
 847    The function returns a string containing the fingerprint.
 848    Deprecated, use verify result directly.  */
 849 const char *gpgme_get_sig_status (gpgme_ctx_t ctx, int idx,
 850                                   _gpgme_sig_stat_t *r_stat,
 851                                   time_t *r_created) _GPGME_DEPRECATED;
 852
 853 /* Retrieve certain attributes of a signature.  IDX is the index
 854    number of the signature after a successful verify operation.  WHAT
 855    is an attribute where GPGME_ATTR_EXPIRE is probably the most useful
 856    one.  WHATIDX is to be passed as 0 for most attributes . */
 857 unsigned long gpgme_get_sig_ulong_attr (gpgme_ctx_t c, int idx,
 858                                         _gpgme_attr_t what, int whatidx)
 859      _GPGME_DEPRECATED;
 860 const char *gpgme_get_sig_string_attr (gpgme_ctx_t c, int idx,
 861                                        _gpgme_attr_t what, int whatidx)
 862      _GPGME_DEPRECATED;
 863
 864
 865 /* Get the key used to create signature IDX in CTX and return it in
 866    R_KEY.  */
 867 gpgme_error_t gpgme_get_sig_key (gpgme_ctx_t ctx, int idx, gpgme_key_t *r_key)
 868      _GPGME_DEPRECATED;
 869
 870 \f
 871 /* Clear all notation data from the context.  */
 872 void gpgme_sig_notation_clear (gpgme_ctx_t ctx);
 873
 874 /* Add the human-readable notation data with name NAME and value VALUE
 875    to the context CTX, using the flags FLAGS.  If NAME is NULL, then
 876    VALUE should be a policy URL.  The flag
 877    GPGME_SIG_NOTATION_HUMAN_READABLE is forced to be true for notation
 878    data, and false for policy URLs.  */
 879 gpgme_error_t gpgme_sig_notation_add (gpgme_ctx_t ctx, const char *name,
 880                                       const char *value,
 881                                       gpgme_sig_notation_flags_t flags);
 882
 883 /* Get the sig notations for this context.  */
 884 gpgme_sig_notation_t gpgme_sig_notation_get (gpgme_ctx_t ctx);
 885
 886 \f
 887 /* Run control.  */
 888
 889 /* The type of an I/O callback function.  */
 890 typedef gpgme_error_t (*gpgme_io_cb_t) (void *data, int fd);
 891
 892 /* The type of a function that can register FNC as the I/O callback
 893    function for the file descriptor FD with direction dir (0: for writing,
 894    1: for reading).  FNC_DATA should be passed as DATA to FNC.  The
 895    function should return a TAG suitable for the corresponding
 896    gpgme_remove_io_cb_t, and an error value.  */
 897 typedef gpgme_error_t (*gpgme_register_io_cb_t) (void *data, int fd, int dir,
 898                                                  gpgme_io_cb_t fnc,
 899                                                  void *fnc_data, void **tag);
 900
 901 /* The type of a function that can remove a previously registered I/O
 902    callback function given TAG as returned by the register
 903    function.  */
 904 typedef void (*gpgme_remove_io_cb_t) (void *tag);
 905
 906 typedef enum
 907   {
 908     GPGME_EVENT_START,
 909     GPGME_EVENT_DONE,
 910     GPGME_EVENT_NEXT_KEY,
 911     GPGME_EVENT_NEXT_TRUSTITEM
 912   }
 913 gpgme_event_io_t;
 914
 915 /* The type of a function that is called when a context finished an
 916    operation.  */
 917 typedef void (*gpgme_event_io_cb_t) (void *data, gpgme_event_io_t type,
 918                                      void *type_data);
 919
 920 struct gpgme_io_cbs
 921 {
 922   gpgme_register_io_cb_t add;
 923   void *add_priv;
 924   gpgme_remove_io_cb_t remove;
 925   gpgme_event_io_cb_t event;
 926   void *event_priv;
 927 };
 928 typedef struct gpgme_io_cbs *gpgme_io_cbs_t;
 929
 930 /* Set the I/O callback functions in CTX to IO_CBS.  */
 931 void gpgme_set_io_cbs (gpgme_ctx_t ctx, gpgme_io_cbs_t io_cbs);
 932
 933 /* Get the current I/O callback functions.  */
 934 void gpgme_get_io_cbs (gpgme_ctx_t ctx, gpgme_io_cbs_t io_cbs);
 935
 936 /* Process the pending operation and, if HANG is non-zero, wait for
 937    the pending operation to finish.  */
 938 gpgme_ctx_t gpgme_wait (gpgme_ctx_t ctx, gpgme_error_t *status, int hang);
 939
 940 \f
 941 /* Functions to handle data objects.  */
 942
 943 /* Read up to SIZE bytes into buffer BUFFER from the data object with
 944    the handle HANDLE.  Return the number of characters read, 0 on EOF
 945    and -1 on error.  If an error occurs, errno is set.  */
 946 typedef ssize_t (*gpgme_data_read_cb_t) (void *handle, void *buffer,
 947                                          size_t size);
 948
 949 /* Write up to SIZE bytes from buffer BUFFER to the data object with
 950    the handle HANDLE.  Return the number of characters written, or -1
 951    on error.  If an error occurs, errno is set.  */
 952 typedef ssize_t (*gpgme_data_write_cb_t) (void *handle, const void *buffer,
 953                                           size_t size);
 954
 955 /* Set the current position from where the next read or write starts
 956    in the data object with the handle HANDLE to OFFSET, relativ to
 957    WHENCE.  */
 958 typedef off_t (*gpgme_data_seek_cb_t) (void *handle, off_t offset, int whence);
 959
 960 /* Close the data object with the handle DL.  */
 961 typedef void (*gpgme_data_release_cb_t) (void *handle);
 962
 963 struct gpgme_data_cbs
 964 {
 965   gpgme_data_read_cb_t read;
 966   gpgme_data_write_cb_t write;
 967   gpgme_data_seek_cb_t seek;
 968   gpgme_data_release_cb_t release;
 969 };
 970 typedef struct gpgme_data_cbs *gpgme_data_cbs_t;
 971
 972 /* Read up to SIZE bytes into buffer BUFFER from the data object with
 973    the handle DH.  Return the number of characters read, 0 on EOF and
 974    -1 on error.  If an error occurs, errno is set.  */
 975 ssize_t gpgme_data_read (gpgme_data_t dh, void *buffer, size_t size);
 976
 977 /* Write up to SIZE bytes from buffer BUFFER to the data object with
 978    the handle DH.  Return the number of characters written, or -1 on
 979    error.  If an error occurs, errno is set.  */
 980 ssize_t gpgme_data_write (gpgme_data_t dh, const void *buffer, size_t size);
 981
 982 /* Set the current position from where the next read or write starts
 983    in the data object with the handle DH to OFFSET, relativ to
 984    WHENCE.  */
 985 off_t gpgme_data_seek (gpgme_data_t dh, off_t offset, int whence);
 986
 987 /* Create a new data buffer and return it in R_DH.  */
 988 gpgme_error_t gpgme_data_new (gpgme_data_t *r_dh);
 989
 990 /* Destroy the data buffer DH.  */
 991 void gpgme_data_release (gpgme_data_t dh);
 992
 993 /* Create a new data buffer filled with SIZE bytes starting from
 994    BUFFER.  If COPY is zero, copying is delayed until necessary, and
 995    the data is taken from the original location when needed.  */
 996 gpgme_error_t gpgme_data_new_from_mem (gpgme_data_t *r_dh,
 997                                        const char *buffer, size_t size,
 998                                        int copy);
 999
1000 /* Destroy the data buffer DH and return a pointer to its content.
1001    The memory has be to released with gpgme_free() by the user.  It's
1002    size is returned in R_LEN.  */
1003 char *gpgme_data_release_and_get_mem (gpgme_data_t dh, size_t *r_len);
1004
1005 /* Release the memory returned by gpgme_data_release_and_get_mem().  */
1006 void gpgme_free (void *buffer);
1007
1008 gpgme_error_t gpgme_data_new_from_cbs (gpgme_data_t *dh,
1009                                        gpgme_data_cbs_t cbs,
1010                                        void *handle);
1011
1012 gpgme_error_t gpgme_data_new_from_fd (gpgme_data_t *dh, int fd);
1013
1014 gpgme_error_t gpgme_data_new_from_stream (gpgme_data_t *dh, FILE *stream);
1015
1016 /* Return the encoding attribute of the data buffer DH */
1017 gpgme_data_encoding_t gpgme_data_get_encoding (gpgme_data_t dh);
1018
1019 /* Set the encoding attribute of data buffer DH to ENC */
1020 gpgme_error_t gpgme_data_set_encoding (gpgme_data_t dh,
1021                                        gpgme_data_encoding_t enc);
1022
1023 /* Get the file name associated with the data object with handle DH, or
1024    NULL if there is none.  */
1025 char *gpgme_data_get_file_name (gpgme_data_t dh);
1026
1027 /* Set the file name associated with the data object with handle DH to
1028    FILE_NAME.  */
1029 gpgme_error_t gpgme_data_set_file_name (gpgme_data_t dh,
1030                                         const char *file_name);
1031
1032
1033 /* Create a new data buffer which retrieves the data from the callback
1034    function READ_CB.  Deprecated, please use gpgme_data_new_from_cbs
1035    instead.  */
1036 gpgme_error_t gpgme_data_new_with_read_cb (gpgme_data_t *r_dh,
1037                                            int (*read_cb) (void*,char *,
1038                                                            size_t,size_t*),
1039                                            void *read_cb_value)
1040      _GPGME_DEPRECATED;
1041
1042 /* Create a new data buffer filled with the content of file FNAME.
1043    COPY must be non-zero.  For delayed read, please use
1044    gpgme_data_new_from_fd or gpgme_data_new_from stream instead.  */
1045 gpgme_error_t gpgme_data_new_from_file (gpgme_data_t *r_dh,
1046                                         const char *fname,
1047                                         int copy);
1048
1049 /* Create a new data buffer filled with LENGTH bytes starting from
1050    OFFSET within the file FNAME or stream FP (exactly one must be
1051    non-zero).  */
1052 gpgme_error_t gpgme_data_new_from_filepart (gpgme_data_t *r_dh,
1053                                             const char *fname, FILE *fp,
1054                                             off_t offset, size_t length);
1055
1056 /* Reset the read pointer in DH.  Deprecated, please use
1057    gpgme_data_seek instead.  */
1058 gpgme_error_t gpgme_data_rewind (gpgme_data_t dh) _GPGME_DEPRECATED;
1059
1060 \f
1061 /* Key and trust functions.  */
1062
1063 /* Get the key with the fingerprint FPR from the crypto backend.  If
1064    SECRET is true, get the secret key.  */
1065 gpgme_error_t gpgme_get_key (gpgme_ctx_t ctx, const char *fpr,
1066                              gpgme_key_t *r_key, int secret);
1067
1068 /* Acquire a reference to KEY.  */
1069 void gpgme_key_ref (gpgme_key_t key);
1070
1071 /* Release a reference to KEY.  If this was the last one the key is
1072    destroyed.  */
1073 void gpgme_key_unref (gpgme_key_t key);
1074 void gpgme_key_release (gpgme_key_t key);
1075
1076 /* Return the value of the attribute WHAT of KEY, which has to be
1077    representable by a string.  IDX specifies the sub key or user ID
1078    for attributes related to sub keys or user IDs.  Deprecated, use
1079    key structure directly instead. */
1080 const char *gpgme_key_get_string_attr (gpgme_key_t key, _gpgme_attr_t what,
1081                                        const void *reserved, int idx)
1082      _GPGME_DEPRECATED;
1083
1084 /* Return the value of the attribute WHAT of KEY, which has to be
1085    representable by an unsigned integer.  IDX specifies the sub key or
1086    user ID for attributes related to sub keys or user IDs.
1087    Deprecated, use key structure directly instead.  */
1088 unsigned long gpgme_key_get_ulong_attr (gpgme_key_t key, _gpgme_attr_t what,
1089                                         const void *reserved, int idx)
1090      _GPGME_DEPRECATED;
1091
1092 /* Return the value of the attribute WHAT of a signature on user ID
1093    UID_IDX in KEY, which has to be representable by a string.  IDX
1094    specifies the signature.  Deprecated, use key structure directly
1095    instead.  */
1096 const char *gpgme_key_sig_get_string_attr (gpgme_key_t key, int uid_idx,
1097                                            _gpgme_attr_t what,
1098                                            const void *reserved, int idx)
1099      _GPGME_DEPRECATED;
1100
1101 /* Return the value of the attribute WHAT of a signature on user ID
1102    UID_IDX in KEY, which has to be representable by an unsigned
1103    integer string.  IDX specifies the signature.  Deprecated, use key
1104    structure directly instead.  */
1105 unsigned long gpgme_key_sig_get_ulong_attr (gpgme_key_t key, int uid_idx,
1106                                             _gpgme_attr_t what,
1107                                             const void *reserved, int idx)
1108      _GPGME_DEPRECATED;
1109
1110 \f
1111 /* Crypto Operations.  */
1112
1113 /* Cancel a pending asynchronous operation.  */
1114 gpgme_error_t gpgme_cancel (gpgme_ctx_t ctx);
1115
1116 \f
1117 struct _gpgme_invalid_key
1118 {
1119   struct _gpgme_invalid_key *next;
1120   char *fpr;
1121   gpgme_error_t reason;
1122 };
1123 typedef struct _gpgme_invalid_key *gpgme_invalid_key_t;
1124
1125 \f
1126 /* Encryption.  */
1127 struct _gpgme_op_encrypt_result
1128 {
1129   /* The list of invalid recipients.  */
1130   gpgme_invalid_key_t invalid_recipients;
1131 };
1132 typedef struct _gpgme_op_encrypt_result *gpgme_encrypt_result_t;
1133
1134 /* Retrieve a pointer to the result of the encrypt operation.  */
1135 gpgme_encrypt_result_t gpgme_op_encrypt_result (gpgme_ctx_t ctx);
1136
1137 /* The valid encryption flags.  */
1138 typedef enum
1139   {
1140     GPGME_ENCRYPT_ALWAYS_TRUST = 1
1141   }
1142 gpgme_encrypt_flags_t;
1143
1144 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
1145    store the resulting ciphertext in CIPHER.  */
1146 gpgme_error_t gpgme_op_encrypt_start (gpgme_ctx_t ctx, gpgme_key_t recp[],
1147                                       gpgme_encrypt_flags_t flags,
1148                                       gpgme_data_t plain, gpgme_data_t cipher);
1149 gpgme_error_t gpgme_op_encrypt (gpgme_ctx_t ctx, gpgme_key_t recp[],
1150                                 gpgme_encrypt_flags_t flags,
1151                                 gpgme_data_t plain, gpgme_data_t cipher);
1152
1153 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
1154    store the resulting ciphertext in CIPHER.  Also sign the ciphertext
1155    with the signers in CTX.  */
1156 gpgme_error_t gpgme_op_encrypt_sign_start (gpgme_ctx_t ctx,
1157                                            gpgme_key_t recp[],
1158                                            gpgme_encrypt_flags_t flags,
1159                                            gpgme_data_t plain,
1160                                            gpgme_data_t cipher);
1161 gpgme_error_t gpgme_op_encrypt_sign (gpgme_ctx_t ctx, gpgme_key_t recp[],
1162                                      gpgme_encrypt_flags_t flags,
1163                                      gpgme_data_t plain, gpgme_data_t cipher);
1164
1165 \f
1166 /* Decryption.  */
1167
1168 struct _gpgme_recipient
1169 {
1170   struct _gpgme_recipient *next;
1171
1172   /* The key ID of key for which the text was encrypted.  */
1173   char *keyid;
1174
1175   /* Internal to GPGME, do not use.  */
1176   char _keyid[16 + 1];
1177
1178   /* The public key algorithm of the recipient key.  */
1179   gpgme_pubkey_algo_t pubkey_algo;
1180
1181   /* The status of the recipient.  */
1182   gpgme_error_t status;
1183 };
1184 typedef struct _gpgme_recipient *gpgme_recipient_t;
1185
1186 struct _gpgme_op_decrypt_result
1187 {
1188   char *unsupported_algorithm;
1189
1190   /* Key should not have been used for encryption.  */
1191   unsigned int wrong_key_usage : 1;
1192
1193   /* Internal to GPGME, do not use.  */
1194   int _unused : 31;
1195
1196   gpgme_recipient_t recipients;
1197
1198   /* The original file name of the plaintext message, if
1199      available.  */
1200   char *file_name;
1201 };
1202 typedef struct _gpgme_op_decrypt_result *gpgme_decrypt_result_t;
1203
1204 /* Retrieve a pointer to the result of the decrypt operation.  */
1205 gpgme_decrypt_result_t gpgme_op_decrypt_result (gpgme_ctx_t ctx);
1206
1207 /* Decrypt ciphertext CIPHER within CTX and store the resulting
1208    plaintext in PLAIN.  */
1209 gpgme_error_t gpgme_op_decrypt_start (gpgme_ctx_t ctx, gpgme_data_t cipher,
1210                                       gpgme_data_t plain);
1211 gpgme_error_t gpgme_op_decrypt (gpgme_ctx_t ctx,
1212                                 gpgme_data_t cipher, gpgme_data_t plain);
1213
1214 /* Decrypt ciphertext CIPHER and make a signature verification within
1215    CTX and store the resulting plaintext in PLAIN.  */
1216 gpgme_error_t gpgme_op_decrypt_verify_start (gpgme_ctx_t ctx,
1217                                              gpgme_data_t cipher,
1218                                              gpgme_data_t plain);
1219 gpgme_error_t gpgme_op_decrypt_verify (gpgme_ctx_t ctx, gpgme_data_t cipher,
1220                                        gpgme_data_t plain);
1221
1222 \f
1223 /* Signing.  */
1224 struct _gpgme_new_signature
1225 {
1226   struct _gpgme_new_signature *next;
1227
1228   /* The type of the signature.  */
1229   gpgme_sig_mode_t type;
1230
1231   /* The public key algorithm used to create the signature.  */
1232   gpgme_pubkey_algo_t pubkey_algo;
1233
1234   /* The hash algorithm used to create the signature.  */
1235   gpgme_hash_algo_t hash_algo;
1236
1237   /* Internal to GPGME, do not use.  Must be set to the same value as
1238      CLASS below.  */
1239   unsigned long _obsolete_class;
1240
1241   /* Signature creation time.  */
1242   long int timestamp;
1243
1244   /* The fingerprint of the signature.  */
1245   char *fpr;
1246
1247 #ifdef __cplusplus
1248   unsigned int _obsolete_class_2;
1249 #else
1250   /* Must be set to SIG_CLASS below.  */
1251   unsigned int class _GPGME_DEPRECATED;
1252 #endif
1253
1254   /* Crypto backend specific signature class.  */
1255   unsigned int sig_class;
1256 };
1257 typedef struct _gpgme_new_signature *gpgme_new_signature_t;
1258
1259 struct _gpgme_op_sign_result
1260 {
1261   /* The list of invalid signers.  */
1262   gpgme_invalid_key_t invalid_signers;
1263   gpgme_new_signature_t signatures;
1264 };
1265 typedef struct _gpgme_op_sign_result *gpgme_sign_result_t;
1266
1267 /* Retrieve a pointer to the result of the signing operation.  */
1268 gpgme_sign_result_t gpgme_op_sign_result (gpgme_ctx_t ctx);
1269
1270 /* Sign the plaintext PLAIN and store the signature in SIG.  */
1271 gpgme_error_t gpgme_op_sign_start (gpgme_ctx_t ctx,
1272                                    gpgme_data_t plain, gpgme_data_t sig,
1273                                    gpgme_sig_mode_t mode);
1274 gpgme_error_t gpgme_op_sign (gpgme_ctx_t ctx,
1275                              gpgme_data_t plain, gpgme_data_t sig,
1276                              gpgme_sig_mode_t mode);
1277
1278 \f
1279 /* Verify.  */
1280
1281 /* Flags used for the SUMMARY field in a gpgme_signature_t.  */
1282 typedef enum
1283   {
1284     GPGME_SIGSUM_VALID       = 0x0001,  /* The signature is fully valid.  */
1285     GPGME_SIGSUM_GREEN       = 0x0002,  /* The signature is good.  */
1286     GPGME_SIGSUM_RED         = 0x0004,  /* The signature is bad.  */
1287     GPGME_SIGSUM_KEY_REVOKED = 0x0010,  /* One key has been revoked.  */
1288     GPGME_SIGSUM_KEY_EXPIRED = 0x0020,  /* One key has expired.  */
1289     GPGME_SIGSUM_SIG_EXPIRED = 0x0040,  /* The signature has expired.  */
1290     GPGME_SIGSUM_KEY_MISSING = 0x0080,  /* Can't verify: key missing.  */
1291     GPGME_SIGSUM_CRL_MISSING = 0x0100,  /* CRL not available.  */
1292     GPGME_SIGSUM_CRL_TOO_OLD = 0x0200,  /* Available CRL is too old.  */
1293     GPGME_SIGSUM_BAD_POLICY  = 0x0400,  /* A policy was not met.  */
1294     GPGME_SIGSUM_SYS_ERROR   = 0x0800   /* A system error occured.  */
1295   }
1296 gpgme_sigsum_t;
1297
1298 struct _gpgme_signature
1299 {
1300   struct _gpgme_signature *next;
1301
1302   /* A summary of the signature status.  */
1303   gpgme_sigsum_t summary;
1304
1305   /* The fingerprint or key ID of the signature.  */
1306   char *fpr;
1307
1308   /* The status of the signature.  */
1309   gpgme_error_t status;
1310
1311   /* Notation data and policy URLs.  */
1312   gpgme_sig_notation_t notations;
1313
1314   /* Signature creation time.  */
1315   unsigned long timestamp;
1316
1317   /* Signature exipration time or 0.  */
1318   unsigned long exp_timestamp;
1319
1320   /* Key should not have been used for signing.  */
1321   unsigned int wrong_key_usage : 1;
1322
1323   /* PKA status: 0 = not available, 1 = bad, 2 = okay, 3 = RFU. */
1324   unsigned int pka_trust : 2;
1325
1326   /* Internal to GPGME, do not use.  */
1327   int _unused : 29;
1328
1329   gpgme_validity_t validity;
1330   gpgme_error_t validity_reason;
1331
1332   /* The public key algorithm used to create the signature.  */
1333   gpgme_pubkey_algo_t pubkey_algo;
1334
1335   /* The hash algorithm used to create the signature.  */
1336   gpgme_hash_algo_t hash_algo;
1337
1338   /* The mailbox from the PKA information or NULL. */
1339   char *pka_address;
1340 };
1341 typedef struct _gpgme_signature *gpgme_signature_t;
1342
1343 struct _gpgme_op_verify_result
1344 {
1345   gpgme_signature_t signatures;
1346
1347   /* The original file name of the plaintext message, if
1348      available.  */
1349   char *file_name;
1350 };
1351 typedef struct _gpgme_op_verify_result *gpgme_verify_result_t;
1352
1353 /* Retrieve a pointer to the result of the verify operation.  */
1354 gpgme_verify_result_t gpgme_op_verify_result (gpgme_ctx_t ctx);
1355
1356 /* Verify within CTX that SIG is a valid signature for TEXT.  */
1357 gpgme_error_t gpgme_op_verify_start (gpgme_ctx_t ctx, gpgme_data_t sig,
1358                                      gpgme_data_t signed_text,
1359                                      gpgme_data_t plaintext);
1360 gpgme_error_t gpgme_op_verify (gpgme_ctx_t ctx, gpgme_data_t sig,
1361                                gpgme_data_t signed_text,
1362                                gpgme_data_t plaintext);
1363
1364 \f
1365 /* Import.  */
1366
1367 /* The key was new.  */
1368 #define GPGME_IMPORT_NEW        1
1369
1370 /* The key contained new user IDs.  */
1371 #define GPGME_IMPORT_UID        2
1372
1373 /* The key contained new signatures.  */
1374 #define GPGME_IMPORT_SIG        4
1375
1376 /* The key contained new sub keys.  */
1377 #define GPGME_IMPORT_SUBKEY     8
1378
1379 /* The key contained a secret key.  */
1380 #define GPGME_IMPORT_SECRET     16
1381
1382
1383 struct _gpgme_import_status
1384 {
1385   struct _gpgme_import_status *next;
1386
1387   /* Fingerprint.  */
1388   char *fpr;
1389
1390   /* If a problem occured, the reason why the key could not be
1391      imported.  Otherwise GPGME_No_Error.  */
1392   gpgme_error_t result;
1393
1394   /* The result of the import, the GPGME_IMPORT_* values bit-wise
1395      ORed.  0 means the key was already known and no new components
1396      have been added.  */
1397   unsigned int status;
1398 };
1399 typedef struct _gpgme_import_status *gpgme_import_status_t;
1400
1401 /* Import.  */
1402 struct _gpgme_op_import_result
1403 {
1404   /* Number of considered keys.  */
1405   int considered;
1406
1407   /* Keys without user ID.  */
1408   int no_user_id;
1409
1410   /* Imported keys.  */
1411   int imported;
1412
1413   /* Imported RSA keys.  */
1414   int imported_rsa;
1415
1416   /* Unchanged keys.  */
1417   int unchanged;
1418
1419   /* Number of new user ids.  */
1420   int new_user_ids;
1421
1422   /* Number of new sub keys.  */
1423   int new_sub_keys;
1424
1425   /* Number of new signatures.  */
1426   int new_signatures;
1427
1428   /* Number of new revocations.  */
1429   int new_revocations;
1430
1431   /* Number of secret keys read.  */
1432   int secret_read;
1433
1434   /* Number of secret keys imported.  */
1435   int secret_imported;
1436
1437   /* Number of secret keys unchanged.  */
1438   int secret_unchanged;
1439
1440   /* Number of new keys skipped.  */
1441   int skipped_new_keys;
1442
1443   /* Number of keys not imported.  */
1444   int not_imported;
1445
1446   /* List of keys for which an import was attempted.  */
1447   gpgme_import_status_t imports;
1448 };
1449 typedef struct _gpgme_op_import_result *gpgme_import_result_t;
1450
1451 /* Retrieve a pointer to the result of the import operation.  */
1452 gpgme_import_result_t gpgme_op_import_result (gpgme_ctx_t ctx);
1453
1454 /* Import the key in KEYDATA into the keyring.  */
1455 gpgme_error_t gpgme_op_import_start (gpgme_ctx_t ctx, gpgme_data_t keydata);
1456 gpgme_error_t gpgme_op_import (gpgme_ctx_t ctx, gpgme_data_t keydata);
1457 gpgme_error_t gpgme_op_import_ext (gpgme_ctx_t ctx, gpgme_data_t keydata,
1458                                    int *nr) _GPGME_DEPRECATED;
1459
1460 \f
1461 /* Export the keys found by PATTERN into KEYDATA.  */
1462 gpgme_error_t gpgme_op_export_start (gpgme_ctx_t ctx, const char *pattern,
1463                                      unsigned int reserved,
1464                                      gpgme_data_t keydata);
1465 gpgme_error_t gpgme_op_export (gpgme_ctx_t ctx, const char *pattern,
1466                                unsigned int reserved, gpgme_data_t keydata);
1467
1468 gpgme_error_t gpgme_op_export_ext_start (gpgme_ctx_t ctx,
1469                                          const char *pattern[],
1470                                          unsigned int reserved,
1471                                          gpgme_data_t keydata);
1472 gpgme_error_t gpgme_op_export_ext (gpgme_ctx_t ctx, const char *pattern[],
1473                                    unsigned int reserved,
1474                                    gpgme_data_t keydata);
1475
1476 \f
1477 /* Key generation.  */
1478 struct _gpgme_op_genkey_result
1479 {
1480   /* A primary key was generated.  */
1481   unsigned int primary : 1;
1482
1483   /* A sub key was generated.  */
1484   unsigned int sub : 1;
1485
1486   /* Internal to GPGME, do not use.  */
1487   unsigned int _unused : 30;
1488
1489   /* The fingerprint of the generated key.  */
1490   char *fpr;
1491 };
1492 typedef struct _gpgme_op_genkey_result *gpgme_genkey_result_t;
1493
1494 /* Generate a new keypair and add it to the keyring.  PUBKEY and
1495    SECKEY should be null for now.  PARMS specifies what keys should be
1496    generated.  */
1497 gpgme_error_t gpgme_op_genkey_start (gpgme_ctx_t ctx, const char *parms,
1498                                      gpgme_data_t pubkey, gpgme_data_t seckey);
1499 gpgme_error_t gpgme_op_genkey (gpgme_ctx_t ctx, const char *parms,
1500                                gpgme_data_t pubkey, gpgme_data_t seckey);
1501
1502 /* Retrieve a pointer to the result of the genkey operation.  */
1503 gpgme_genkey_result_t gpgme_op_genkey_result (gpgme_ctx_t ctx);
1504
1505 \f
1506 /* Delete KEY from the keyring.  If ALLOW_SECRET is non-zero, secret
1507    keys are also deleted.  */
1508 gpgme_error_t gpgme_op_delete_start (gpgme_ctx_t ctx, const gpgme_key_t key,
1509                                      int allow_secret);
1510 gpgme_error_t gpgme_op_delete (gpgme_ctx_t ctx, const gpgme_key_t key,
1511                                int allow_secret);
1512
1513 \f
1514 /* Edit the key KEY.  Send status and command requests to FNC and
1515    output of edit commands to OUT.  */
1516 gpgme_error_t gpgme_op_edit_start (gpgme_ctx_t ctx, gpgme_key_t key,
1517                                    gpgme_edit_cb_t fnc, void *fnc_value,
1518                                    gpgme_data_t out);
1519 gpgme_error_t gpgme_op_edit (gpgme_ctx_t ctx, gpgme_key_t key,
1520                              gpgme_edit_cb_t fnc, void *fnc_value,
1521                              gpgme_data_t out);
1522
1523 /* Edit the card for the key KEY.  Send status and command requests to
1524    FNC and output of edit commands to OUT.  */
1525 gpgme_error_t gpgme_op_card_edit_start (gpgme_ctx_t ctx, gpgme_key_t key,
1526                                         gpgme_edit_cb_t fnc, void *fnc_value,
1527                                         gpgme_data_t out);
1528 gpgme_error_t gpgme_op_card_edit (gpgme_ctx_t ctx, gpgme_key_t key,
1529                                   gpgme_edit_cb_t fnc, void *fnc_value,
1530                                   gpgme_data_t out);
1531
1532 \f
1533 /* Key management functions.  */
1534 struct _gpgme_op_keylist_result
1535 {
1536   unsigned int truncated : 1;
1537
1538   /* Internal to GPGME, do not use.  */
1539   unsigned int _unused : 31;
1540 };
1541 typedef struct _gpgme_op_keylist_result *gpgme_keylist_result_t;
1542
1543 /* Retrieve a pointer to the result of the key listing operation.  */
1544 gpgme_keylist_result_t gpgme_op_keylist_result (gpgme_ctx_t ctx);
1545
1546 /* Start a keylist operation within CTX, searching for keys which
1547    match PATTERN.  If SECRET_ONLY is true, only secret keys are
1548    returned.  */
1549 gpgme_error_t gpgme_op_keylist_start (gpgme_ctx_t ctx, const char *pattern,
1550                                       int secret_only);
1551 gpgme_error_t gpgme_op_keylist_ext_start (gpgme_ctx_t ctx,
1552                                           const char *pattern[],
1553                                           int secret_only, int reserved);
1554
1555 /* Return the next key from the keylist in R_KEY.  */
1556 gpgme_error_t gpgme_op_keylist_next (gpgme_ctx_t ctx, gpgme_key_t *r_key);
1557
1558 /* Terminate a pending keylist operation within CTX.  */
1559 gpgme_error_t gpgme_op_keylist_end (gpgme_ctx_t ctx);
1560
1561 \f
1562 /* Trust items and operations.  */
1563
1564 struct _gpgme_trust_item
1565 {
1566   /* Internal to GPGME, do not use.  */
1567   unsigned int _refs;
1568
1569   /* The key ID to which the trust item belongs.  */
1570   char *keyid;
1571
1572   /* Internal to GPGME, do not use.  */
1573   char _keyid[16 + 1];
1574
1575   /* The type of the trust item, 1 refers to a key, 2 to a user ID.  */
1576   int type;
1577
1578   /* The trust level.  */
1579   int level;
1580
1581   /* The owner trust if TYPE is 1.  */
1582   char *owner_trust;
1583
1584   /* Internal to GPGME, do not use.  */
1585   char _owner_trust[2];
1586
1587   /* The calculated validity.  */
1588   char *validity;
1589
1590   /* Internal to GPGME, do not use.  */
1591   char _validity[2];
1592
1593   /* The user name if TYPE is 2.  */
1594   char *name;
1595 };
1596 typedef struct _gpgme_trust_item *gpgme_trust_item_t;
1597
1598 /* Start a trustlist operation within CTX, searching for trust items
1599    which match PATTERN.  */
1600 gpgme_error_t gpgme_op_trustlist_start (gpgme_ctx_t ctx,
1601                                         const char *pattern, int max_level);
1602
1603 /* Return the next trust item from the trustlist in R_ITEM.  */
1604 gpgme_error_t gpgme_op_trustlist_next (gpgme_ctx_t ctx,
1605                                        gpgme_trust_item_t *r_item);
1606
1607 /* Terminate a pending trustlist operation within CTX.  */
1608 gpgme_error_t gpgme_op_trustlist_end (gpgme_ctx_t ctx);
1609
1610 /* Acquire a reference to ITEM.  */
1611 void gpgme_trust_item_ref (gpgme_trust_item_t item);
1612
1613 /* Release a reference to ITEM.  If this was the last one the trust
1614    item is destroyed.  */
1615 void gpgme_trust_item_unref (gpgme_trust_item_t item);
1616
1617 /* Release the trust item ITEM.  Deprecated, use
1618    gpgme_trust_item_unref.  */
1619 void gpgme_trust_item_release (gpgme_trust_item_t item) _GPGME_DEPRECATED;
1620
1621 /* Return the value of the attribute WHAT of ITEM, which has to be
1622    representable by a string.  Deprecated, use trust item structure
1623    directly.  */
1624 const char *gpgme_trust_item_get_string_attr (gpgme_trust_item_t item,
1625                                               _gpgme_attr_t what,
1626                                               const void *reserved, int idx)
1627      _GPGME_DEPRECATED;
1628
1629 /* Return the value of the attribute WHAT of KEY, which has to be
1630    representable by an integer.  IDX specifies a running index if the
1631    attribute appears more than once in the key.  Deprecated, use trust
1632    item structure directly.  */
1633 int gpgme_trust_item_get_int_attr (gpgme_trust_item_t item, _gpgme_attr_t what,
1634                                    const void *reserved, int idx)
1635      _GPGME_DEPRECATED;
1636
1637 \f
1638 /* Various functions.  */
1639
1640 /* Check that the library fulfills the version requirement.  */
1641 const char *gpgme_check_version (const char *req_version);
1642
1643 /* Get the information about the configured and installed engines.  A
1644    pointer to the first engine in the statically allocated linked list
1645    is returned in *INFO.  If an error occurs, it is returned.  The
1646    returned data is valid until the next gpgme_set_engine_info.  */
1647 gpgme_error_t gpgme_get_engine_info (gpgme_engine_info_t *engine_info);
1648
1649 /* Set the default engine info for the protocol PROTO to the file name
1650    FILE_NAME and the home directory HOME_DIR.  */
1651 gpgme_error_t gpgme_set_engine_info (gpgme_protocol_t proto,
1652                                      const char *file_name,
1653                                      const char *home_dir);
1654
1655 \f
1656 /* Engine support functions.  */
1657
1658 /* Verify that the engine implementing PROTO is installed and
1659    available.  */
1660 gpgme_error_t gpgme_engine_check_version (gpgme_protocol_t proto);
1661
1662 \f
1663 /* Deprecated types.  */
1664 typedef gpgme_ctx_t GpgmeCtx _GPGME_DEPRECATED;
1665 typedef gpgme_data_t GpgmeData _GPGME_DEPRECATED;
1666 typedef gpgme_error_t GpgmeError _GPGME_DEPRECATED;
1667 typedef gpgme_data_encoding_t GpgmeDataEncoding _GPGME_DEPRECATED;
1668 typedef gpgme_pubkey_algo_t GpgmePubKeyAlgo _GPGME_DEPRECATED;
1669 typedef gpgme_hash_algo_t GpgmeHashAlgo _GPGME_DEPRECATED;
1670 typedef gpgme_sig_stat_t GpgmeSigStat _GPGME_DEPRECATED;
1671 typedef gpgme_sig_mode_t GpgmeSigMode _GPGME_DEPRECATED;
1672 typedef gpgme_attr_t GpgmeAttr _GPGME_DEPRECATED;
1673 typedef gpgme_validity_t GpgmeValidity _GPGME_DEPRECATED;
1674 typedef gpgme_protocol_t GpgmeProtocol _GPGME_DEPRECATED;
1675 typedef gpgme_engine_info_t GpgmeEngineInfo _GPGME_DEPRECATED;
1676 typedef gpgme_subkey_t GpgmeSubkey _GPGME_DEPRECATED;
1677 typedef gpgme_key_sig_t GpgmeKeySig _GPGME_DEPRECATED;
1678 typedef gpgme_user_id_t GpgmeUserID _GPGME_DEPRECATED;
1679 typedef gpgme_key_t GpgmeKey _GPGME_DEPRECATED;
1680 typedef gpgme_passphrase_cb_t GpgmePassphraseCb _GPGME_DEPRECATED;
1681 typedef gpgme_progress_cb_t GpgmeProgressCb _GPGME_DEPRECATED;
1682 typedef gpgme_io_cb_t GpgmeIOCb _GPGME_DEPRECATED;
1683 typedef gpgme_register_io_cb_t GpgmeRegisterIOCb _GPGME_DEPRECATED;
1684 typedef gpgme_remove_io_cb_t GpgmeRemoveIOCb _GPGME_DEPRECATED;
1685 typedef gpgme_event_io_t GpgmeEventIO _GPGME_DEPRECATED;
1686 typedef gpgme_event_io_cb_t GpgmeEventIOCb _GPGME_DEPRECATED;
1687 #define GpgmeIOCbs gpgme_io_cbs
1688 typedef gpgme_data_read_cb_t GpgmeDataReadCb _GPGME_DEPRECATED;
1689 typedef gpgme_data_write_cb_t GpgmeDataWriteCb _GPGME_DEPRECATED;
1690 typedef gpgme_data_seek_cb_t GpgmeDataSeekCb _GPGME_DEPRECATED;
1691 typedef gpgme_data_release_cb_t GpgmeDataReleaseCb _GPGME_DEPRECATED;
1692 #define GpgmeDataCbs gpgme_data_cbs
1693 typedef gpgme_encrypt_result_t GpgmeEncryptResult _GPGME_DEPRECATED;
1694 typedef gpgme_sig_notation_t GpgmeSigNotation _GPGME_DEPRECATED;
1695 typedef gpgme_signature_t GpgmeSignature _GPGME_DEPRECATED;
1696 typedef gpgme_verify_result_t GpgmeVerifyResult _GPGME_DEPRECATED;
1697 typedef gpgme_import_status_t GpgmeImportStatus _GPGME_DEPRECATED;
1698 typedef gpgme_import_result_t GpgmeImportResult _GPGME_DEPRECATED;
1699 typedef gpgme_genkey_result_t GpgmeGenKeyResult _GPGME_DEPRECATED;
1700 typedef gpgme_trust_item_t GpgmeTrustItem _GPGME_DEPRECATED;
1701 typedef gpgme_status_code_t GpgmeStatusCode _GPGME_DEPRECATED;
1702
1703 #ifdef __cplusplus
1704 }
1705 #endif
1706 #endif /* GPGME_H */