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