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