src/gpgme.h.in

   1 /* gpgme.h - Public interface to GnuPG Made Easy.                   -*- c -*-
   2  * Copyright (C) 2000 Werner Koch (dd9jn)
   3  * Copyright (C) 2001-2017 g10 Code GmbH
   4  *
   5  * This file is part of GPGME.
   6  *
   7  * GPGME is free software; you can redistribute it and/or modify it
   8  * under the terms of the GNU Lesser General Public License as
   9  * published by the Free Software Foundation; either version 2.1 of
  10  * the License, or (at your option) any later version.
  11  *
  12  * GPGME is distributed in the hope that it will be useful, but
  13  * WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Lesser General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Lesser General Public
  18  * License along with this program; if not, see <http://www.gnu.org/licenses/>.
  19  *
  20  * Generated from gpgme.h.in for @GPGME_CONFIG_HOST@.
  21  */
  22
  23 #ifndef GPGME_H
  24 #define GPGME_H
  25
  26 /* Include stdio.h for the FILE type definition.  */
  27 #include <stdio.h>
  28 #include <time.h>
  29 #include <gpg-error.h>
  30
  31 #ifdef __cplusplus
  32 extern "C" {
  33 #if 0 /*(Make Emacsen's auto-indent happy.)*/
  34 }
  35 #endif
  36 #endif /* __cplusplus */
  37
  38
  39 /* The version of this header should match the one of the library.  Do
  40    not use this symbol in your application, use gpgme_check_version
  41    instead.  The purpose of this macro is to let autoconf (using the
  42    AM_PATH_GPGME macro) check that this header matches the installed
  43    library.  */
  44 #define GPGME_VERSION "@PACKAGE_VERSION@"
  45
  46 /* The version number of this header.  It may be used to handle minor
  47    API incompatibilities.  */
  48 #define GPGME_VERSION_NUMBER @VERSION_NUMBER@
  49
  50
  51 /* System specific typedefs.  */
  52 @INSERT__TYPEDEFS_FOR_GPGME_H@
  53
  54
  55 \f
  56 /*
  57  * Check for compiler features.
  58  */
  59 #ifdef GPGRT_INLINE
  60 # define _GPGME_INLINE GPGRT_INLINE
  61 #elif defined(__GNUC__)
  62 # define _GPGME_INLINE __inline__
  63 #elif defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L
  64 # define _GPGME_INLINE inline
  65 #else
  66 # define _GPGME_INLINE
  67 #endif
  68
  69
  70 /* The deprecated macro takes the version number of GPGME which
  71  * introduced the deprecation as parameter for documentation.  */
  72 #ifdef GPGRT_ATTR_DEPRECATED
  73 # define _GPGME_DEPRECATED(a,b) GPGRT_ATTR_DEPRECATED
  74 #elif defined(__GNUC__)
  75 # define _GPGME_GCC_VERSION (__GNUC__ * 10000 \
  76                              + __GNUC_MINOR__ * 100 \
  77                              + __GNUC_PATCHLEVEL__)
  78
  79 # if _GPGME_GCC_VERSION > 30100
  80 #  define _GPGME_DEPRECATED(a,b)  __attribute__ ((__deprecated__))
  81 # else
  82 #  define _GPGME_DEPRECATED(a,b)
  83 # endif
  84 #else
  85 # define _GPGME_DEPRECATED(a,b)
  86 #endif
  87
  88
  89 /* The macro _GPGME_DEPRECATED_OUTSIDE_GPGME suppresses warnings for
  90    fields we must access in GPGME for ABI compatibility.  */
  91 #ifdef _GPGME_IN_GPGME
  92 #define _GPGME_DEPRECATED_OUTSIDE_GPGME(a,b)
  93 #else
  94 #define _GPGME_DEPRECATED_OUTSIDE_GPGME(a,b) _GPGME_DEPRECATED(a,b)
  95 #endif
  96
  97
  98 /* Check for a matching _FILE_OFFSET_BITS definition.  */
  99 #if @NEED__FILE_OFFSET_BITS@
 100 #ifndef _FILE_OFFSET_BITS
 101 #error GPGME was compiled with _FILE_OFFSET_BITS = @NEED__FILE_OFFSET_BITS@, please see the section "Largefile support (LFS)" in the GPGME manual.
 102 #else
 103 #if (_FILE_OFFSET_BITS) != (@NEED__FILE_OFFSET_BITS@)
 104 #error GPGME was compiled with a different value for _FILE_OFFSET_BITS, namely @NEED__FILE_OFFSET_BITS@, please see the section "Largefile support (LFS)" in the GPGME manual.
 105 #endif
 106 #endif
 107 #endif
 108
 109
 110 \f
 111 /*
 112  * Some opaque data types used by GPGME.
 113  */
 114
 115 /* The context holds some global state and configuration options, as
 116    well as the results of a crypto operation.  */
 117 struct gpgme_context;
 118 typedef struct gpgme_context *gpgme_ctx_t;
 119
 120 /* The data object is used by GPGME to exchange arbitrary data.  */
 121 struct gpgme_data;
 122 typedef struct gpgme_data *gpgme_data_t;
 123
 124
 125 \f
 126 /*
 127  * Wrappers for the libgpg-error library.
 128  */
 129
 130 typedef gpg_error_t gpgme_error_t;
 131 typedef gpg_err_code_t gpgme_err_code_t;
 132 typedef gpg_err_source_t gpgme_err_source_t;
 133
 134
 135 static _GPGME_INLINE gpgme_error_t
 136 gpgme_err_make (gpgme_err_source_t source, gpgme_err_code_t code)
 137 {
 138   return gpg_err_make (source, code);
 139 }
 140
 141
 142 /* The user can define GPGME_ERR_SOURCE_DEFAULT before including this
 143    file to specify a default source for gpgme_error.  */
 144 #ifndef GPGME_ERR_SOURCE_DEFAULT
 145 #define GPGME_ERR_SOURCE_DEFAULT  GPG_ERR_SOURCE_USER_1
 146 #endif
 147
 148 static _GPGME_INLINE gpgme_error_t
 149 gpgme_error (gpgme_err_code_t code)
 150 {
 151   return gpgme_err_make (GPGME_ERR_SOURCE_DEFAULT, code);
 152 }
 153
 154
 155 static _GPGME_INLINE gpgme_err_code_t
 156 gpgme_err_code (gpgme_error_t err)
 157 {
 158   return gpg_err_code (err);
 159 }
 160
 161
 162 static _GPGME_INLINE gpgme_err_source_t
 163 gpgme_err_source (gpgme_error_t err)
 164 {
 165   return gpg_err_source (err);
 166 }
 167
 168
 169 /* Return a pointer to a string containing a description of the error
 170    code in the error value ERR.  This function is not thread safe.  */
 171 const char *gpgme_strerror (gpgme_error_t err);
 172
 173 /* Return the error string for ERR in the user-supplied buffer BUF of
 174    size BUFLEN.  This function is, in contrast to gpg_strerror,
 175    thread-safe if a thread-safe strerror_r() function is provided by
 176    the system.  If the function succeeds, 0 is returned and BUF
 177    contains the string describing the error.  If the buffer was not
 178    large enough, ERANGE is returned and BUF contains as much of the
 179    beginning of the error string as fits into the buffer.  */
 180 int gpgme_strerror_r (gpg_error_t err, char *buf, size_t buflen);
 181
 182 /* Return a pointer to a string containing a description of the error
 183    source in the error value ERR.  */
 184 const char *gpgme_strsource (gpgme_error_t err);
 185
 186 /* Retrieve the error code for the system error ERR.  This returns
 187    GPG_ERR_UNKNOWN_ERRNO if the system error is not mapped (report
 188    this).  */
 189 gpgme_err_code_t gpgme_err_code_from_errno (int err);
 190
 191 /* Retrieve the system error for the error code CODE.  This returns 0
 192    if CODE is not a system error code.  */
 193 int gpgme_err_code_to_errno (gpgme_err_code_t code);
 194
 195 /* Retrieve the error code directly from the ERRNO variable.  This
 196    returns GPG_ERR_UNKNOWN_ERRNO if the system error is not mapped
 197    (report this) and GPG_ERR_MISSING_ERRNO if ERRNO has the value 0. */
 198 gpgme_err_code_t gpgme_err_code_from_syserror (void);
 199
 200 /* Set the ERRNO variable.  This function is the preferred way to set
 201    ERRNO due to peculiarities on WindowsCE.  */
 202 void gpgme_err_set_errno (int err);
 203
 204 /* Return an error value with the error source SOURCE and the system
 205    error ERR.  FIXME: Should be inline.  */
 206 gpgme_error_t gpgme_err_make_from_errno (gpgme_err_source_t source, int err);
 207
 208 /* Return an error value with the system error ERR.  FIXME: Should be inline.  */
 209 gpgme_error_t gpgme_error_from_errno (int err);
 210
 211
 212 static _GPGME_INLINE gpgme_error_t
 213 gpgme_error_from_syserror (void)
 214 {
 215   return gpgme_error (gpgme_err_code_from_syserror ());
 216 }
 217
 218
 219 \f
 220 /*
 221  * Various constants and types
 222  */
 223
 224 /* The possible encoding mode of gpgme_data_t objects.  */
 225 typedef enum
 226   {
 227     GPGME_DATA_ENCODING_NONE   = 0,     /* Not specified.  */
 228     GPGME_DATA_ENCODING_BINARY = 1,
 229     GPGME_DATA_ENCODING_BASE64 = 2,
 230     GPGME_DATA_ENCODING_ARMOR  = 3,     /* Either PEM or OpenPGP Armor.  */
 231     GPGME_DATA_ENCODING_URL    = 4,     /* LF delimited URL list.        */
 232     GPGME_DATA_ENCODING_URLESC = 5,     /* Ditto, but percent escaped.   */
 233     GPGME_DATA_ENCODING_URL0   = 6,     /* Nul delimited URL list.       */
 234     GPGME_DATA_ENCODING_MIME   = 7      /* Data is a MIME part.          */
 235   }
 236 gpgme_data_encoding_t;
 237
 238
 239 /* Known data types.  */
 240 typedef enum
 241   {
 242     GPGME_DATA_TYPE_INVALID      = 0,   /* Not detected.  */
 243     GPGME_DATA_TYPE_UNKNOWN      = 1,
 244     GPGME_DATA_TYPE_PGP_SIGNED   = 0x10,
 245     GPGME_DATA_TYPE_PGP_ENCRYPTED= 0x11,
 246     GPGME_DATA_TYPE_PGP_OTHER    = 0x12,
 247     GPGME_DATA_TYPE_PGP_KEY      = 0x13,
 248     GPGME_DATA_TYPE_PGP_SIGNATURE= 0x18, /* Detached signature */
 249     GPGME_DATA_TYPE_CMS_SIGNED   = 0x20,
 250     GPGME_DATA_TYPE_CMS_ENCRYPTED= 0x21,
 251     GPGME_DATA_TYPE_CMS_OTHER    = 0x22,
 252     GPGME_DATA_TYPE_X509_CERT    = 0x23,
 253     GPGME_DATA_TYPE_PKCS12       = 0x24,
 254   }
 255 gpgme_data_type_t;
 256
 257
 258 /* Public key algorithms.  */
 259 typedef enum
 260   {
 261     GPGME_PK_RSA   = 1,
 262     GPGME_PK_RSA_E = 2,
 263     GPGME_PK_RSA_S = 3,
 264     GPGME_PK_ELG_E = 16,
 265     GPGME_PK_DSA   = 17,
 266     GPGME_PK_ECC   = 18,
 267     GPGME_PK_ELG   = 20,
 268     GPGME_PK_ECDSA = 301,
 269     GPGME_PK_ECDH  = 302,
 270     GPGME_PK_EDDSA = 303
 271   }
 272 gpgme_pubkey_algo_t;
 273
 274
 275 /* Hash algorithms (the values match those from libgcrypt).  */
 276 typedef enum
 277   {
 278     GPGME_MD_NONE          = 0,
 279     GPGME_MD_MD5           = 1,
 280     GPGME_MD_SHA1          = 2,
 281     GPGME_MD_RMD160        = 3,
 282     GPGME_MD_MD2           = 5,
 283     GPGME_MD_TIGER         = 6,   /* TIGER/192. */
 284     GPGME_MD_HAVAL         = 7,   /* HAVAL, 5 pass, 160 bit. */
 285     GPGME_MD_SHA256        = 8,
 286     GPGME_MD_SHA384        = 9,
 287     GPGME_MD_SHA512        = 10,
 288     GPGME_MD_SHA224        = 11,
 289     GPGME_MD_MD4           = 301,
 290     GPGME_MD_CRC32         = 302,
 291     GPGME_MD_CRC32_RFC1510 = 303,
 292     GPGME_MD_CRC24_RFC2440 = 304
 293   }
 294 gpgme_hash_algo_t;
 295
 296
 297 /* The available signature modes.  */
 298 typedef enum
 299   {
 300     GPGME_SIG_MODE_NORMAL = 0,
 301     GPGME_SIG_MODE_DETACH = 1,
 302     GPGME_SIG_MODE_CLEAR  = 2
 303   }
 304 gpgme_sig_mode_t;
 305
 306
 307 /* The available validities for a trust item or key.  */
 308 typedef enum
 309   {
 310     GPGME_VALIDITY_UNKNOWN   = 0,
 311     GPGME_VALIDITY_UNDEFINED = 1,
 312     GPGME_VALIDITY_NEVER     = 2,
 313     GPGME_VALIDITY_MARGINAL  = 3,
 314     GPGME_VALIDITY_FULL      = 4,
 315     GPGME_VALIDITY_ULTIMATE  = 5
 316   }
 317 gpgme_validity_t;
 318
 319
 320 /* The TOFU policies. */
 321 typedef enum
 322   {
 323     GPGME_TOFU_POLICY_NONE    = 0,
 324     GPGME_TOFU_POLICY_AUTO    = 1,
 325     GPGME_TOFU_POLICY_GOOD    = 2,
 326     GPGME_TOFU_POLICY_UNKNOWN = 3,
 327     GPGME_TOFU_POLICY_BAD     = 4,
 328     GPGME_TOFU_POLICY_ASK     = 5
 329   }
 330 gpgme_tofu_policy_t;
 331
 332
 333 /* The key origin values. */
 334 typedef enum
 335   {
 336     GPGME_KEYORG_UNKNOWN      = 0,
 337     GPGME_KEYORG_KS           = 1,
 338     GPGME_KEYORG_DANE         = 3,
 339     GPGME_KEYORG_WKD          = 4,
 340     GPGME_KEYORG_URL          = 5,
 341     GPGME_KEYORG_FILE         = 6,
 342     GPGME_KEYORG_SELF         = 7,
 343     GPGME_KEYORG_OTHER        = 31
 344   }
 345 gpgme_keyorg_t;
 346
 347
 348 /* The available protocols.  */
 349 typedef enum
 350   {
 351     GPGME_PROTOCOL_OpenPGP = 0,  /* The default mode.  */
 352     GPGME_PROTOCOL_CMS     = 1,
 353     GPGME_PROTOCOL_GPGCONF = 2,  /* Special code for gpgconf.  */
 354     GPGME_PROTOCOL_ASSUAN  = 3,  /* Low-level access to an Assuan server.  */
 355     GPGME_PROTOCOL_G13     = 4,
 356     GPGME_PROTOCOL_UISERVER= 5,
 357     GPGME_PROTOCOL_SPAWN   = 6,  /* Direct access to any program.  */
 358     GPGME_PROTOCOL_DEFAULT = 254,
 359     GPGME_PROTOCOL_UNKNOWN = 255
 360   }
 361 gpgme_protocol_t;
 362 /* Convenience macro for the surprisingly mixed spelling.  */
 363 #define GPGME_PROTOCOL_OPENPGP GPGME_PROTOCOL_OpenPGP
 364
 365
 366 /* The available keylist mode flags.  */
 367 #define GPGME_KEYLIST_MODE_LOCAL                1
 368 #define GPGME_KEYLIST_MODE_EXTERN               2
 369 #define GPGME_KEYLIST_MODE_SIGS                 4
 370 #define GPGME_KEYLIST_MODE_SIG_NOTATIONS        8
 371 #define GPGME_KEYLIST_MODE_WITH_SECRET          16
 372 #define GPGME_KEYLIST_MODE_WITH_TOFU            32
 373 #define GPGME_KEYLIST_MODE_EPHEMERAL            128
 374 #define GPGME_KEYLIST_MODE_VALIDATE             256
 375
 376 typedef unsigned int gpgme_keylist_mode_t;
 377
 378
 379 /* The pinentry modes. */
 380 typedef enum
 381   {
 382     GPGME_PINENTRY_MODE_DEFAULT  = 0,
 383     GPGME_PINENTRY_MODE_ASK      = 1,
 384     GPGME_PINENTRY_MODE_CANCEL   = 2,
 385     GPGME_PINENTRY_MODE_ERROR    = 3,
 386     GPGME_PINENTRY_MODE_LOOPBACK = 4
 387   }
 388 gpgme_pinentry_mode_t;
 389
 390
 391 /* The available export mode flags.  */
 392 #define GPGME_EXPORT_MODE_EXTERN                2
 393 #define GPGME_EXPORT_MODE_MINIMAL               4
 394 #define GPGME_EXPORT_MODE_SECRET               16
 395 #define GPGME_EXPORT_MODE_RAW                  32
 396 #define GPGME_EXPORT_MODE_PKCS12               64
 397
 398 typedef unsigned int gpgme_export_mode_t;
 399
 400
 401 /* Flags for the audit log functions.  */
 402 #define GPGME_AUDITLOG_HTML      1
 403 #define GPGME_AUDITLOG_WITH_HELP 128
 404
 405
 406 /* The available signature notation flags.  */
 407 #define GPGME_SIG_NOTATION_HUMAN_READABLE       1
 408 #define GPGME_SIG_NOTATION_CRITICAL             2
 409
 410 typedef unsigned int gpgme_sig_notation_flags_t;
 411
 412 /* An object to hold information about notation data.  This structure
 413  * shall be considered read-only and an application must not allocate
 414  * such a structure on its own.  */
 415 struct _gpgme_sig_notation
 416 {
 417   struct _gpgme_sig_notation *next;
 418
 419   /* If NAME is a null pointer, then VALUE contains a policy URL
 420      rather than a notation.  */
 421   char *name;
 422
 423   /* The value of the notation data.  */
 424   char *value;
 425
 426   /* The length of the name of the notation data.  */
 427   int name_len;
 428
 429   /* The length of the value of the notation data.  */
 430   int value_len;
 431
 432   /* The accumulated flags.  */
 433   gpgme_sig_notation_flags_t flags;
 434
 435   /* Notation data is human-readable.  */
 436   unsigned int human_readable : 1;
 437
 438   /* Notation data is critical.  */
 439   unsigned int critical : 1;
 440
 441   /* Internal to GPGME, do not use.  */
 442   int _unused : 30;
 443 };
 444 typedef struct _gpgme_sig_notation *gpgme_sig_notation_t;
 445
 446
 447 \f
 448 /*
 449  * Public structures.
 450  */
 451
 452 /* The engine information structure.
 453  * This structure shall be considered read-only and an application
 454  * must not allocate such a structure on its own.  */
 455 struct _gpgme_engine_info
 456 {
 457   struct _gpgme_engine_info *next;
 458
 459   /* The protocol ID.  */
 460   gpgme_protocol_t protocol;
 461
 462   /* The file name of the engine binary.  */
 463   char *file_name;
 464
 465   /* The version string of the installed engine.  */
 466   char *version;
 467
 468   /* The minimum version required for GPGME.  */
 469   const char *req_version;
 470
 471   /* The home directory used, or NULL if default.  */
 472   char *home_dir;
 473 };
 474 typedef struct _gpgme_engine_info *gpgme_engine_info_t;
 475
 476
 477 /* An object with TOFU information.
 478  * This structure shall be considered read-only and an application
 479  * must not allocate such a structure on its own.  */
 480 struct _gpgme_tofu_info
 481 {
 482   struct _gpgme_tofu_info *next;
 483
 484   /* The TOFU validity:
 485    *  0 := conflict
 486    *  1 := key without history
 487    *  2 := key with too little history
 488    *  3 := key with enough history for basic trust
 489    *  4 := key with a lot of history
 490    */
 491   unsigned int validity : 3;
 492
 493   /* The TOFU policy (gpgme_tofu_policy_t).  */
 494   unsigned int policy : 4;
 495
 496   unsigned int _rfu : 25;
 497
 498   /* Number of signatures seen for this binding.  Capped at USHRT_MAX.  */
 499   unsigned short signcount;
 500   /* Number of encryptions done with this binding.  Capped at USHRT_MAX.  */
 501   unsigned short encrcount;
 502
 503   /* Number of seconds since Epoch when the first and the most
 504    * recently seen message were verified/decrypted.  0 means unknown. */
 505   unsigned long signfirst;
 506   unsigned long signlast;
 507   unsigned long encrfirst;
 508   unsigned long encrlast;
 509
 510   /* If non-NULL a human readable string summarizing the TOFU data. */
 511   char *description;
 512 };
 513 typedef struct _gpgme_tofu_info *gpgme_tofu_info_t;
 514
 515
 516 /* A subkey from a key.
 517  * This structure shall be considered read-only and an application
 518  * must not allocate such a structure on its own.  */
 519 struct _gpgme_subkey
 520 {
 521   struct _gpgme_subkey *next;
 522
 523   /* True if subkey is revoked.  */
 524   unsigned int revoked : 1;
 525
 526   /* True if subkey is expired.  */
 527   unsigned int expired : 1;
 528
 529   /* True if subkey is disabled.  */
 530   unsigned int disabled : 1;
 531
 532   /* True if subkey is invalid.  */
 533   unsigned int invalid : 1;
 534
 535   /* True if subkey can be used for encryption.  */
 536   unsigned int can_encrypt : 1;
 537
 538   /* True if subkey can be used for signing.  */
 539   unsigned int can_sign : 1;
 540
 541   /* True if subkey can be used for certification.  */
 542   unsigned int can_certify : 1;
 543
 544   /* True if subkey is secret.  */
 545   unsigned int secret : 1;
 546
 547   /* True if subkey can be used for authentication.  */
 548   unsigned int can_authenticate : 1;
 549
 550   /* True if subkey is qualified for signatures according to German law.  */
 551   unsigned int is_qualified : 1;
 552
 553   /* True if the secret key is stored on a smart card.  */
 554   unsigned int is_cardkey : 1;
 555
 556   /* True if the key is compliant to the de-vs mode.  */
 557   unsigned int is_de_vs : 1;
 558
 559   /* Internal to GPGME, do not use.  */
 560   unsigned int _unused : 20;
 561
 562   /* Public key algorithm supported by this subkey.  */
 563   gpgme_pubkey_algo_t pubkey_algo;
 564
 565   /* Length of the subkey.  */
 566   unsigned int length;
 567
 568   /* The key ID of the subkey.  */
 569   char *keyid;
 570
 571   /* Internal to GPGME, do not use.  */
 572   char _keyid[16 + 1];
 573
 574   /* The fingerprint of the subkey in hex digit form.  */
 575   char *fpr;
 576
 577   /* The creation timestamp, -1 if invalid, 0 if not available.  */
 578   long int timestamp;
 579
 580   /* The expiration timestamp, 0 if the subkey does not expire.  */
 581   long int expires;
 582
 583   /* The serial number of a smart card holding this key or NULL.  */
 584   char *card_number;
 585
 586   /* The name of the curve for ECC algorithms or NULL.  */
 587   char *curve;
 588
 589   /* The keygrip of the subkey in hex digit form or NULL if not availabale.  */
 590   char *keygrip;
 591 };
 592 typedef struct _gpgme_subkey *gpgme_subkey_t;
 593
 594
 595 /* A signature on a user ID.
 596  * This structure shall be considered read-only and an application
 597  * must not allocate such a structure on its own.  */
 598 struct _gpgme_key_sig
 599 {
 600   struct _gpgme_key_sig *next;
 601
 602   /* True if the signature is a revocation signature.  */
 603   unsigned int revoked : 1;
 604
 605   /* True if the signature is expired.  */
 606   unsigned int expired : 1;
 607
 608   /* True if the signature is invalid.  */
 609   unsigned int invalid : 1;
 610
 611   /* True if the signature should be exported.  */
 612   unsigned int exportable : 1;
 613
 614   /* Internal to GPGME, do not use.  */
 615   unsigned int _unused : 28;
 616
 617   /* The public key algorithm used to create the signature.  */
 618   gpgme_pubkey_algo_t pubkey_algo;
 619
 620   /* The key ID of key used to create the signature.  */
 621   char *keyid;
 622
 623   /* Internal to GPGME, do not use.  */
 624   char _keyid[16 + 1];
 625
 626   /* The creation timestamp, -1 if invalid, 0 if not available.  */
 627   long int timestamp;
 628
 629   /* The expiration timestamp, 0 if the subkey does not expire.  */
 630   long int expires;
 631
 632   /* Same as in gpgme_signature_t.  */
 633   gpgme_error_t status;
 634
 635 #ifdef __cplusplus
 636   unsigned int _obsolete_class _GPGME_DEPRECATED(0,4);
 637 #else
 638   /* Must be set to SIG_CLASS below.  */
 639   unsigned int class _GPGME_DEPRECATED_OUTSIDE_GPGME(0,4);
 640 #endif
 641
 642   /* The user ID string.  */
 643   char *uid;
 644
 645   /* The name part of the user ID.  */
 646   char *name;
 647
 648   /* The email part of the user ID.  */
 649   char *email;
 650
 651   /* The comment part of the user ID.  */
 652   char *comment;
 653
 654   /* Crypto backend specific signature class.  */
 655   unsigned int sig_class;
 656
 657   /* Notation data and policy URLs.  */
 658   gpgme_sig_notation_t notations;
 659
 660   /* Internal to GPGME, do not use.  */
 661   gpgme_sig_notation_t _last_notation;
 662 };
 663 typedef struct _gpgme_key_sig *gpgme_key_sig_t;
 664
 665
 666 /* An user ID from a key.
 667  * This structure shall be considered read-only and an application
 668  * must not allocate such a structure on its own.  */
 669 struct _gpgme_user_id
 670 {
 671   struct _gpgme_user_id *next;
 672
 673   /* True if the user ID is revoked.  */
 674   unsigned int revoked : 1;
 675
 676   /* True if the user ID is invalid.  */
 677   unsigned int invalid : 1;
 678
 679   /* Internal to GPGME, do not use.  */
 680   unsigned int _unused : 25;
 681
 682   /* Origin of this user ID.  */
 683   unsigned int origin : 5;
 684
 685   /* The validity of the user ID.  */
 686   gpgme_validity_t validity;
 687
 688   /* The user ID string.  */
 689   char *uid;
 690
 691   /* The name part of the user ID.  */
 692   char *name;
 693
 694   /* The email part of the user ID.  */
 695   char *email;
 696
 697   /* The comment part of the user ID.  */
 698   char *comment;
 699
 700   /* The signatures of the user ID.  */
 701   gpgme_key_sig_t signatures;
 702
 703   /* Internal to GPGME, do not use.  */
 704   gpgme_key_sig_t _last_keysig;
 705
 706   /* The mail address (addr-spec from RFC5322) of the UID string.
 707    * This is general the same as the EMAIL part of this struct but
 708    * might be slightly different.  If no mail address is available
 709    * NULL is stored.  */
 710   char *address;
 711
 712   /* The malloced TOFU information or NULL.  */
 713   gpgme_tofu_info_t tofu;
 714
 715   /* Time of the last refresh of this user id.  0 if unknown.  */
 716   unsigned long last_update;
 717 };
 718 typedef struct _gpgme_user_id *gpgme_user_id_t;
 719
 720
 721 /* A key from the keyring.
 722  * This structure shall be considered read-only and an application
 723  * must not allocate such a structure on its own.  */
 724 struct _gpgme_key
 725 {
 726   /* Internal to GPGME, do not use.  */
 727   unsigned int _refs;
 728
 729   /* True if key is revoked.  */
 730   unsigned int revoked : 1;
 731
 732   /* True if key is expired.  */
 733   unsigned int expired : 1;
 734
 735   /* True if key is disabled.  */
 736   unsigned int disabled : 1;
 737
 738   /* True if key is invalid.  */
 739   unsigned int invalid : 1;
 740
 741   /* True if key can be used for encryption.  */
 742   unsigned int can_encrypt : 1;
 743
 744   /* True if key can be used for signing.  */
 745   unsigned int can_sign : 1;
 746
 747   /* True if key can be used for certification.  */
 748   unsigned int can_certify : 1;
 749
 750   /* True if key is secret.  */
 751   unsigned int secret : 1;
 752
 753   /* True if key can be used for authentication.  */
 754   unsigned int can_authenticate : 1;
 755
 756   /* True if subkey is qualified for signatures according to German law.  */
 757   unsigned int is_qualified : 1;
 758
 759   /* Internal to GPGME, do not use.  */
 760   unsigned int _unused : 17;
 761
 762   /* Origin of this key.  */
 763   unsigned int origin : 5;
 764
 765   /* This is the protocol supported by this key.  */
 766   gpgme_protocol_t protocol;
 767
 768   /* If protocol is GPGME_PROTOCOL_CMS, this string contains the
 769      issuer serial.  */
 770   char *issuer_serial;
 771
 772   /* If protocol is GPGME_PROTOCOL_CMS, this string contains the
 773      issuer name.  */
 774   char *issuer_name;
 775
 776   /* If protocol is GPGME_PROTOCOL_CMS, this string contains the chain
 777      ID.  */
 778   char *chain_id;
 779
 780   /* If protocol is GPGME_PROTOCOL_OpenPGP, this field contains the
 781      owner trust.  */
 782   gpgme_validity_t owner_trust;
 783
 784   /* The subkeys of the key.  */
 785   gpgme_subkey_t subkeys;
 786
 787   /* The user IDs of the key.  */
 788   gpgme_user_id_t uids;
 789
 790   /* Internal to GPGME, do not use.  */
 791   gpgme_subkey_t _last_subkey;
 792
 793   /* Internal to GPGME, do not use.  */
 794   gpgme_user_id_t _last_uid;
 795
 796   /* The keylist mode that was active when listing the key.  */
 797   gpgme_keylist_mode_t keylist_mode;
 798
 799   /* This field gives the fingerprint of the primary key.  Note that
 800    * this is a copy of the FPR of the first subkey.  We need it here
 801    * to allow for an incomplete key object.  */
 802   char *fpr;
 803
 804   /* Time of the last refresh of the entire key.  0 if unknown.  */
 805   unsigned long last_update;
 806 };
 807 typedef struct _gpgme_key *gpgme_key_t;
 808
 809
 810 /* An invalid key object.
 811  * This structure shall be considered read-only and an application
 812  * must not allocate such a structure on its own.  */
 813 struct _gpgme_invalid_key
 814 {
 815   struct _gpgme_invalid_key *next;
 816
 817   /* The string used to request the key.  Despite the name this may
 818    * not be a fingerprint.  */
 819   char *fpr;
 820
 821   /* The error code.  */
 822   gpgme_error_t reason;
 823 };
 824 typedef struct _gpgme_invalid_key *gpgme_invalid_key_t;
 825
 826
 827 \f
 828 /*
 829  * Types for callback functions.
 830  */
 831
 832 /* Request a passphrase from the user.  */
 833 typedef gpgme_error_t (*gpgme_passphrase_cb_t) (void *hook,
 834                                                 const char *uid_hint,
 835                                                 const char *passphrase_info,
 836                                                 int prev_was_bad, int fd);
 837
 838 /* Inform the user about progress made.  */
 839 typedef void (*gpgme_progress_cb_t) (void *opaque, const char *what,
 840                                      int type, int current, int total);
 841
 842 /* Status messages from gpg. */
 843 typedef gpgme_error_t (*gpgme_status_cb_t) (void *opaque, const char *keyword,
 844                                             const char *args);
 845
 846 /* Interact with the user about an edit operation.  */
 847 typedef gpgme_error_t (*gpgme_interact_cb_t) (void *opaque,
 848                                               const char *keyword,
 849                                               const char *args, int fd);
 850
 851
 852 \f
 853 /*
 854  * Context management functions.
 855  */
 856
 857 /* Create a new context and return it in CTX.  */
 858 gpgme_error_t gpgme_new (gpgme_ctx_t *ctx);
 859
 860 /* Release the context CTX.  */
 861 void gpgme_release (gpgme_ctx_t ctx);
 862
 863 /* Set the flag NAME for CTX to VALUE.  */
 864 gpgme_error_t gpgme_set_ctx_flag (gpgme_ctx_t ctx,
 865                                   const char *name, const char *value);
 866
 867 /* Get the value of the flag NAME from CTX.  */
 868 const char *gpgme_get_ctx_flag (gpgme_ctx_t ctx, const char *name);
 869
 870 /* Set the protocol to be used by CTX to PROTO.  */
 871 gpgme_error_t gpgme_set_protocol (gpgme_ctx_t ctx, gpgme_protocol_t proto);
 872
 873 /* Get the protocol used with CTX */
 874 gpgme_protocol_t gpgme_get_protocol (gpgme_ctx_t ctx);
 875
 876 /* Set the crypto protocol to be used by CTX to PROTO.
 877    gpgme_set_protocol actually sets the backend engine.  This sets the
 878    crypto protocol used in engines that support more than one crypto
 879    prococol (for example, an UISERVER can support OpenPGP and CMS).
 880    This is reset to the default with gpgme_set_protocol.  */
 881 gpgme_error_t gpgme_set_sub_protocol (gpgme_ctx_t ctx,
 882                                       gpgme_protocol_t proto);
 883
 884 /* Get the sub protocol.  */
 885 gpgme_protocol_t gpgme_get_sub_protocol (gpgme_ctx_t ctx);
 886
 887 /* Get the string describing protocol PROTO, or NULL if invalid.  */
 888 const char *gpgme_get_protocol_name (gpgme_protocol_t proto);
 889
 890 /* If YES is non-zero, enable armor mode in CTX, disable it otherwise.  */
 891 void gpgme_set_armor (gpgme_ctx_t ctx, int yes);
 892
 893 /* Return non-zero if armor mode is set in CTX.  */
 894 int gpgme_get_armor (gpgme_ctx_t ctx);
 895
 896 /* If YES is non-zero, enable text mode in CTX, disable it otherwise.  */
 897 void gpgme_set_textmode (gpgme_ctx_t ctx, int yes);
 898
 899 /* Return non-zero if text mode is set in CTX.  */
 900 int gpgme_get_textmode (gpgme_ctx_t ctx);
 901
 902 /* If YES is non-zero, enable offline mode in CTX, disable it otherwise.  */
 903 void gpgme_set_offline (gpgme_ctx_t ctx, int yes);
 904
 905 /* Return non-zero if offline mode is set in CTX.  */
 906 int gpgme_get_offline (gpgme_ctx_t ctx);
 907
 908 /* Use whatever the default of the backend crypto engine is.  */
 909 #define GPGME_INCLUDE_CERTS_DEFAULT     -256
 910
 911 /* Include up to NR_OF_CERTS certificates in an S/MIME message.  */
 912 void gpgme_set_include_certs (gpgme_ctx_t ctx, int nr_of_certs);
 913
 914 /* Return the number of certs to include in an S/MIME message.  */
 915 int gpgme_get_include_certs (gpgme_ctx_t ctx);
 916
 917 /* Set keylist mode in CTX to MODE.  */
 918 gpgme_error_t gpgme_set_keylist_mode (gpgme_ctx_t ctx,
 919                                       gpgme_keylist_mode_t mode);
 920
 921 /* Get keylist mode in CTX.  */
 922 gpgme_keylist_mode_t gpgme_get_keylist_mode (gpgme_ctx_t ctx);
 923
 924 /* Set the pinentry mode for CTX to MODE. */
 925 gpgme_error_t gpgme_set_pinentry_mode (gpgme_ctx_t ctx,
 926                                        gpgme_pinentry_mode_t mode);
 927
 928 /* Get the pinentry mode of CTX.  */
 929 gpgme_pinentry_mode_t gpgme_get_pinentry_mode (gpgme_ctx_t ctx);
 930
 931 /* Set the passphrase callback function in CTX to CB.  HOOK_VALUE is
 932    passed as first argument to the passphrase callback function.  */
 933 void gpgme_set_passphrase_cb (gpgme_ctx_t ctx,
 934                               gpgme_passphrase_cb_t cb, void *hook_value);
 935
 936 /* Get the current passphrase callback function in *CB and the current
 937    hook value in *HOOK_VALUE.  */
 938 void gpgme_get_passphrase_cb (gpgme_ctx_t ctx, gpgme_passphrase_cb_t *cb,
 939                               void **hook_value);
 940
 941 /* Set the progress callback function in CTX to CB.  HOOK_VALUE is
 942    passed as first argument to the progress callback function.  */
 943 void gpgme_set_progress_cb (gpgme_ctx_t c, gpgme_progress_cb_t cb,
 944                             void *hook_value);
 945
 946 /* Get the current progress callback function in *CB and the current
 947    hook value in *HOOK_VALUE.  */
 948 void gpgme_get_progress_cb (gpgme_ctx_t ctx, gpgme_progress_cb_t *cb,
 949                             void **hook_value);
 950
 951 /* Set the status callback function in CTX to CB.  HOOK_VALUE is
 952    passed as first argument to the status callback function.  */
 953 void gpgme_set_status_cb (gpgme_ctx_t c, gpgme_status_cb_t cb,
 954                           void *hook_value);
 955
 956 /* Get the current status callback function in *CB and the current
 957    hook value in *HOOK_VALUE.  */
 958 void gpgme_get_status_cb (gpgme_ctx_t ctx, gpgme_status_cb_t *cb,
 959                           void **hook_value);
 960
 961 /* This function sets the locale for the context CTX, or the default
 962    locale if CTX is a null pointer.  */
 963 gpgme_error_t gpgme_set_locale (gpgme_ctx_t ctx, int category,
 964                                 const char *value);
 965
 966 /* Get the information about the configured engines.  A pointer to the
 967    first engine in the statically allocated linked list is returned.
 968    The returned data is valid until the next gpgme_ctx_set_engine_info.  */
 969 gpgme_engine_info_t gpgme_ctx_get_engine_info (gpgme_ctx_t ctx);
 970
 971 /* Set the engine info for the context CTX, protocol PROTO, to the
 972    file name FILE_NAME and the home directory HOME_DIR.  */
 973 gpgme_error_t gpgme_ctx_set_engine_info (gpgme_ctx_t ctx,
 974                                          gpgme_protocol_t proto,
 975                                          const char *file_name,
 976                                          const char *home_dir);
 977
 978 /* Delete all signers from CTX.  */
 979 void gpgme_signers_clear (gpgme_ctx_t ctx);
 980
 981 /* Add KEY to list of signers in CTX.  */
 982 gpgme_error_t gpgme_signers_add (gpgme_ctx_t ctx, const gpgme_key_t key);
 983
 984 /* Return the number of signers in CTX.  */
 985 unsigned int gpgme_signers_count (const gpgme_ctx_t ctx);
 986
 987 /* Return the SEQth signer's key in CTX.  */
 988 gpgme_key_t gpgme_signers_enum (const gpgme_ctx_t ctx, int seq);
 989
 990 /* Clear all notation data from the context.  */
 991 void gpgme_sig_notation_clear (gpgme_ctx_t ctx);
 992
 993 /* Add the human-readable notation data with name NAME and value VALUE
 994    to the context CTX, using the flags FLAGS.  If NAME is NULL, then
 995    VALUE should be a policy URL.  The flag
 996    GPGME_SIG_NOTATION_HUMAN_READABLE is forced to be true for notation
 997    data, and false for policy URLs.  */
 998 gpgme_error_t gpgme_sig_notation_add (gpgme_ctx_t ctx, const char *name,
 999                                       const char *value,
1000                                       gpgme_sig_notation_flags_t flags);
1001
1002 /* Get the sig notations for this context.  */
1003 gpgme_sig_notation_t gpgme_sig_notation_get (gpgme_ctx_t ctx);
1004
1005 /* Store a sender address in the context.  */
1006 gpgme_error_t gpgme_set_sender (gpgme_ctx_t ctx, const char *address);
1007
1008 /* Get the sender address from the context.  */
1009 const char *gpgme_get_sender (gpgme_ctx_t ctx);
1010
1011
1012 \f
1013 /*
1014  * Run control.
1015  */
1016
1017 /* The type of an I/O callback function.  */
1018 typedef gpgme_error_t (*gpgme_io_cb_t) (void *data, int fd);
1019
1020 /* The type of a function that can register FNC as the I/O callback
1021    function for the file descriptor FD with direction dir (0: for writing,
1022    1: for reading).  FNC_DATA should be passed as DATA to FNC.  The
1023    function should return a TAG suitable for the corresponding
1024    gpgme_remove_io_cb_t, and an error value.  */
1025 typedef gpgme_error_t (*gpgme_register_io_cb_t) (void *data, int fd, int dir,
1026                                                  gpgme_io_cb_t fnc,
1027                                                  void *fnc_data, void **tag);
1028
1029 /* The type of a function that can remove a previously registered I/O
1030    callback function given TAG as returned by the register
1031    function.  */
1032 typedef void (*gpgme_remove_io_cb_t) (void *tag);
1033
1034 typedef enum
1035   {
1036     GPGME_EVENT_START,
1037     GPGME_EVENT_DONE,
1038     GPGME_EVENT_NEXT_KEY,
1039     GPGME_EVENT_NEXT_TRUSTITEM
1040   }
1041 gpgme_event_io_t;
1042
1043 struct gpgme_io_event_done_data
1044 {
1045   /* A fatal IPC error or an operational error in state-less
1046      protocols.  */
1047   gpgme_error_t err;
1048
1049   /* An operational errors in session-based protocols.  */
1050   gpgme_error_t op_err;
1051 };
1052 typedef struct gpgme_io_event_done_data *gpgme_io_event_done_data_t;
1053
1054 /* The type of a function that is called when a context finished an
1055    operation.  */
1056 typedef void (*gpgme_event_io_cb_t) (void *data, gpgme_event_io_t type,
1057                                      void *type_data);
1058
1059 struct gpgme_io_cbs
1060 {
1061   gpgme_register_io_cb_t add;
1062   void *add_priv;
1063   gpgme_remove_io_cb_t remove;
1064   gpgme_event_io_cb_t event;
1065   void *event_priv;
1066 };
1067 typedef struct gpgme_io_cbs *gpgme_io_cbs_t;
1068
1069 /* Set the I/O callback functions in CTX to IO_CBS.  */
1070 void gpgme_set_io_cbs (gpgme_ctx_t ctx, gpgme_io_cbs_t io_cbs);
1071
1072 /* Get the current I/O callback functions.  */
1073 void gpgme_get_io_cbs (gpgme_ctx_t ctx, gpgme_io_cbs_t io_cbs);
1074
1075 /* Wrappers around the internal I/O functions for use with
1076    gpgme_passphrase_cb_t and gpgme_interact_cb_t.  */
1077 @API__SSIZE_T@ gpgme_io_read (int fd, void *buffer, size_t count);
1078 @API__SSIZE_T@ gpgme_io_write (int fd, const void *buffer, size_t count);
1079 int     gpgme_io_writen (int fd, const void *buffer, size_t count);
1080
1081 /* Process the pending operation and, if HANG is non-zero, wait for
1082    the pending operation to finish.  */
1083 gpgme_ctx_t gpgme_wait (gpgme_ctx_t ctx, gpgme_error_t *status, int hang);
1084
1085 gpgme_ctx_t gpgme_wait_ext (gpgme_ctx_t ctx, gpgme_error_t *status,
1086                             gpgme_error_t *op_err, int hang);
1087
1088 /* Cancel a pending asynchronous operation.  */
1089 gpgme_error_t gpgme_cancel (gpgme_ctx_t ctx);
1090
1091 /* Cancel a pending operation asynchronously.  */
1092 gpgme_error_t gpgme_cancel_async (gpgme_ctx_t ctx);
1093
1094
1095 \f
1096 /*
1097  * Functions to handle data objects.
1098  */
1099
1100 /* Read up to SIZE bytes into buffer BUFFER from the data object with
1101    the handle HANDLE.  Return the number of characters read, 0 on EOF
1102    and -1 on error.  If an error occurs, errno is set.  */
1103 typedef @API__SSIZE_T@ (*gpgme_data_read_cb_t) (void *handle, void *buffer,
1104                                          size_t size);
1105
1106 /* Write up to SIZE bytes from buffer BUFFER to the data object with
1107    the handle HANDLE.  Return the number of characters written, or -1
1108    on error.  If an error occurs, errno is set.  */
1109 typedef @API__SSIZE_T@ (*gpgme_data_write_cb_t) (void *handle, const void *buffer,
1110                                           size_t size);
1111
1112 /* Set the current position from where the next read or write starts
1113    in the data object with the handle HANDLE to OFFSET, relativ to
1114    WHENCE.  Returns the new offset in bytes from the beginning of the
1115    data object.  */
1116 typedef @API__OFF_T@ (*gpgme_data_seek_cb_t) (void *handle,
1117                                        @API__OFF_T@ offset, int whence);
1118
1119 /* Close the data object with the handle HANDLE.  */
1120 typedef void (*gpgme_data_release_cb_t) (void *handle);
1121
1122 struct gpgme_data_cbs
1123 {
1124   gpgme_data_read_cb_t read;
1125   gpgme_data_write_cb_t write;
1126   gpgme_data_seek_cb_t seek;
1127   gpgme_data_release_cb_t release;
1128 };
1129 typedef struct gpgme_data_cbs *gpgme_data_cbs_t;
1130
1131 /* Read up to SIZE bytes into buffer BUFFER from the data object with
1132    the handle DH.  Return the number of characters read, 0 on EOF and
1133    -1 on error.  If an error occurs, errno is set.  */
1134 @API__SSIZE_T@ gpgme_data_read (gpgme_data_t dh, void *buffer, size_t size);
1135
1136 /* Write up to SIZE bytes from buffer BUFFER to the data object with
1137    the handle DH.  Return the number of characters written, or -1 on
1138    error.  If an error occurs, errno is set.  */
1139 @API__SSIZE_T@ gpgme_data_write (gpgme_data_t dh, const void *buffer, size_t size);
1140
1141 /* Set the current position from where the next read or write starts
1142    in the data object with the handle DH to OFFSET, relativ to WHENCE.
1143    Returns the new offset in bytes from the beginning of the data
1144    object.  */
1145 @API__OFF_T@ gpgme_data_seek (gpgme_data_t dh, @API__OFF_T@ offset, int whence);
1146
1147 /* Create a new data buffer and return it in R_DH.  */
1148 gpgme_error_t gpgme_data_new (gpgme_data_t *r_dh);
1149
1150 /* Destroy the data buffer DH.  */
1151 void gpgme_data_release (gpgme_data_t dh);
1152
1153 /* Create a new data buffer filled with SIZE bytes starting from
1154    BUFFER.  If COPY is zero, copying is delayed until necessary, and
1155    the data is taken from the original location when needed.  */
1156 gpgme_error_t gpgme_data_new_from_mem (gpgme_data_t *r_dh,
1157                                        const char *buffer, size_t size,
1158                                        int copy);
1159
1160 /* Destroy the data buffer DH and return a pointer to its content.
1161    The memory has be to released with gpgme_free() by the user.  It's
1162    size is returned in R_LEN.  */
1163 char *gpgme_data_release_and_get_mem (gpgme_data_t dh, size_t *r_len);
1164
1165 /* Release the memory returned by gpgme_data_release_and_get_mem() and
1166    some other functions.  */
1167 void gpgme_free (void *buffer);
1168
1169 gpgme_error_t gpgme_data_new_from_cbs (gpgme_data_t *dh,
1170                                        gpgme_data_cbs_t cbs,
1171                                        void *handle);
1172
1173 gpgme_error_t gpgme_data_new_from_fd (gpgme_data_t *dh, int fd);
1174
1175 gpgme_error_t gpgme_data_new_from_stream (gpgme_data_t *dh, FILE *stream);
1176
1177 /* Return the encoding attribute of the data buffer DH */
1178 gpgme_data_encoding_t gpgme_data_get_encoding (gpgme_data_t dh);
1179
1180 /* Set the encoding attribute of data buffer DH to ENC */
1181 gpgme_error_t gpgme_data_set_encoding (gpgme_data_t dh,
1182                                        gpgme_data_encoding_t enc);
1183
1184 /* Get the file name associated with the data object with handle DH, or
1185    NULL if there is none.  */
1186 char *gpgme_data_get_file_name (gpgme_data_t dh);
1187
1188 /* Set the file name associated with the data object with handle DH to
1189    FILE_NAME.  */
1190 gpgme_error_t gpgme_data_set_file_name (gpgme_data_t dh,
1191                                         const char *file_name);
1192
1193 /* Set a flag for the data object DH.  See the manual for details.  */
1194 gpg_error_t gpgme_data_set_flag (gpgme_data_t dh,
1195                                  const char *name, const char *value);
1196
1197 /* Try to identify the type of the data in DH.  */
1198 gpgme_data_type_t gpgme_data_identify (gpgme_data_t dh, int reserved);
1199
1200
1201 /* Create a new data buffer filled with the content of file FNAME.
1202    COPY must be non-zero.  For delayed read, please use
1203    gpgme_data_new_from_fd or gpgme_data_new_from_stream instead.  */
1204 gpgme_error_t gpgme_data_new_from_file (gpgme_data_t *r_dh,
1205                                         const char *fname,
1206                                         int copy);
1207
1208 /* Create a new data buffer filled with LENGTH bytes starting from
1209    OFFSET within the file FNAME or stream FP (exactly one must be
1210    non-zero).  */
1211 gpgme_error_t gpgme_data_new_from_filepart (gpgme_data_t *r_dh,
1212                                             const char *fname, FILE *fp,
1213                                             @API__OFF_T@ offset, size_t length);
1214
1215 /* Convenience function to do a gpgme_data_seek (dh, 0, SEEK_SET).  */
1216 gpgme_error_t gpgme_data_rewind (gpgme_data_t dh);
1217
1218
1219 \f
1220 /*
1221  * Key and trust functions.
1222  */
1223
1224 /* Get the key with the fingerprint FPR from the crypto backend.  If
1225    SECRET is true, get the secret key.  */
1226 gpgme_error_t gpgme_get_key (gpgme_ctx_t ctx, const char *fpr,
1227                              gpgme_key_t *r_key, int secret);
1228
1229 /* Create a dummy key to specify an email address.  */
1230 gpgme_error_t gpgme_key_from_uid (gpgme_key_t *key, const char *name);
1231
1232 /* Acquire a reference to KEY.  */
1233 void gpgme_key_ref (gpgme_key_t key);
1234
1235 /* Release a reference to KEY.  If this was the last one the key is
1236    destroyed.  */
1237 void gpgme_key_unref (gpgme_key_t key);
1238 void gpgme_key_release (gpgme_key_t key);
1239
1240
1241 \f
1242 /*
1243  * Encryption.
1244  */
1245
1246 /* An object to return results from an encryption operation.
1247  * This structure shall be considered read-only and an application
1248  * must not allocate such a structure on its own.  */
1249 struct _gpgme_op_encrypt_result
1250 {
1251   /* The list of invalid recipients.  */
1252   gpgme_invalid_key_t invalid_recipients;
1253 };
1254 typedef struct _gpgme_op_encrypt_result *gpgme_encrypt_result_t;
1255
1256 /* Retrieve a pointer to the result of the encrypt operation.  */
1257 gpgme_encrypt_result_t gpgme_op_encrypt_result (gpgme_ctx_t ctx);
1258
1259 /* The valid encryption flags.  */
1260 typedef enum
1261   {
1262     GPGME_ENCRYPT_ALWAYS_TRUST = 1,
1263     GPGME_ENCRYPT_NO_ENCRYPT_TO = 2,
1264     GPGME_ENCRYPT_PREPARE = 4,
1265     GPGME_ENCRYPT_EXPECT_SIGN = 8,
1266     GPGME_ENCRYPT_NO_COMPRESS = 16,
1267     GPGME_ENCRYPT_SYMMETRIC = 32,
1268     GPGME_ENCRYPT_THROW_KEYIDS = 64,
1269     GPGME_ENCRYPT_WRAP = 128
1270   }
1271 gpgme_encrypt_flags_t;
1272
1273 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
1274    store the resulting ciphertext in CIPHER.  */
1275 gpgme_error_t gpgme_op_encrypt_start (gpgme_ctx_t ctx, gpgme_key_t recp[],
1276                                       gpgme_encrypt_flags_t flags,
1277                                       gpgme_data_t plain, gpgme_data_t cipher);
1278 gpgme_error_t gpgme_op_encrypt (gpgme_ctx_t ctx, gpgme_key_t recp[],
1279                                 gpgme_encrypt_flags_t flags,
1280                                 gpgme_data_t plain, gpgme_data_t cipher);
1281
1282 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
1283    store the resulting ciphertext in CIPHER.  Also sign the ciphertext
1284    with the signers in CTX.  */
1285 gpgme_error_t gpgme_op_encrypt_sign_start (gpgme_ctx_t ctx,
1286                                            gpgme_key_t recp[],
1287                                            gpgme_encrypt_flags_t flags,
1288                                            gpgme_data_t plain,
1289                                            gpgme_data_t cipher);
1290 gpgme_error_t gpgme_op_encrypt_sign (gpgme_ctx_t ctx, gpgme_key_t recp[],
1291                                      gpgme_encrypt_flags_t flags,
1292                                      gpgme_data_t plain, gpgme_data_t cipher);
1293
1294 \f
1295 /*
1296  * Decryption.
1297  */
1298
1299 /* An object to hold information about a recipient.
1300  * This structure shall be considered read-only and an application
1301  * must not allocate such a structure on its own.  */
1302 struct _gpgme_recipient
1303 {
1304   struct _gpgme_recipient *next;
1305
1306   /* The key ID of key for which the text was encrypted.  */
1307   char *keyid;
1308
1309   /* Internal to GPGME, do not use.  */
1310   char _keyid[16 + 1];
1311
1312   /* The public key algorithm of the recipient key.  */
1313   gpgme_pubkey_algo_t pubkey_algo;
1314
1315   /* The status of the recipient.  */
1316   gpgme_error_t status;
1317 };
1318 typedef struct _gpgme_recipient *gpgme_recipient_t;
1319
1320 /* An object to return results from a decryption operation.
1321  * This structure shall be considered read-only and an application
1322  * must not allocate such a structure on its own.  */
1323 struct _gpgme_op_decrypt_result
1324 {
1325   char *unsupported_algorithm;
1326
1327   /* Key should not have been used for encryption.  */
1328   unsigned int wrong_key_usage : 1;
1329
1330   /* True if the message was encrypted in compliance to the de-vs
1331    * mode.  */
1332   unsigned int is_de_vs : 1;
1333
1334   /* Internal to GPGME, do not use.  */
1335   int _unused : 30;
1336
1337   gpgme_recipient_t recipients;
1338
1339   /* The original file name of the plaintext message, if
1340      available.  */
1341   char *file_name;
1342
1343   /* A textual representation of the session key used to decrypt the
1344    * message, if available */
1345   char *session_key;
1346 };
1347 typedef struct _gpgme_op_decrypt_result *gpgme_decrypt_result_t;
1348
1349 /* Retrieve a pointer to the result of the decrypt operation.  */
1350 gpgme_decrypt_result_t gpgme_op_decrypt_result (gpgme_ctx_t ctx);
1351
1352 /* The valid decryption flags.  */
1353 typedef enum
1354   {
1355     GPGME_DECRYPT_VERIFY = 1,
1356     GPGME_DECRYPT_UNWRAP = 128
1357   }
1358 gpgme_decrypt_flags_t;
1359
1360 /* Decrypt ciphertext CIPHER within CTX and store the resulting
1361    plaintext in PLAIN.  */
1362 gpgme_error_t gpgme_op_decrypt_start (gpgme_ctx_t ctx, gpgme_data_t cipher,
1363                                       gpgme_data_t plain);
1364 gpgme_error_t gpgme_op_decrypt (gpgme_ctx_t ctx,
1365                                 gpgme_data_t cipher, gpgme_data_t plain);
1366
1367 /* Decrypt ciphertext CIPHER and make a signature verification within
1368    CTX and store the resulting plaintext in PLAIN.  */
1369 gpgme_error_t gpgme_op_decrypt_verify_start (gpgme_ctx_t ctx,
1370                                              gpgme_data_t cipher,
1371                                              gpgme_data_t plain);
1372 gpgme_error_t gpgme_op_decrypt_verify (gpgme_ctx_t ctx, gpgme_data_t cipher,
1373                                        gpgme_data_t plain);
1374
1375 /* Decrypt ciphertext CIPHER within CTX and store the resulting
1376  * plaintext in PLAIN.  With the flag GPGME_DECRYPT_VERIFY also do a
1377  * signature verification pn the plaintext.  */
1378 gpgme_error_t gpgme_op_decrypt_ext_start (gpgme_ctx_t ctx,
1379                                           gpgme_decrypt_flags_t flags,
1380                                           gpgme_data_t cipher,
1381                                           gpgme_data_t plain);
1382 gpgme_error_t gpgme_op_decrypt_ext (gpgme_ctx_t ctx,
1383                                     gpgme_decrypt_flags_t flags,
1384                                     gpgme_data_t cipher,
1385                                     gpgme_data_t plain);
1386
1387
1388 \f
1389 /*
1390  * Signing.
1391  */
1392
1393 /* An object with signatures data.
1394  * This structure shall be considered read-only and an application
1395  * must not allocate such a structure on its own.  */
1396 struct _gpgme_new_signature
1397 {
1398   struct _gpgme_new_signature *next;
1399
1400   /* The type of the signature.  */
1401   gpgme_sig_mode_t type;
1402
1403   /* The public key algorithm used to create the signature.  */
1404   gpgme_pubkey_algo_t pubkey_algo;
1405
1406   /* The hash algorithm used to create the signature.  */
1407   gpgme_hash_algo_t hash_algo;
1408
1409   /* Internal to GPGME, do not use.  Must be set to the same value as
1410      CLASS below.  */
1411   unsigned long _obsolete_class;
1412
1413   /* Signature creation time.  */
1414   long int timestamp;
1415
1416   /* The fingerprint of the signature.  */
1417   char *fpr;
1418
1419 #ifdef __cplusplus
1420   unsigned int _obsolete_class_2;
1421 #else
1422   /* Must be set to SIG_CLASS below.  */
1423   unsigned int class _GPGME_DEPRECATED_OUTSIDE_GPGME(0,4);
1424 #endif
1425
1426   /* Crypto backend specific signature class.  */
1427   unsigned int sig_class;
1428 };
1429 typedef struct _gpgme_new_signature *gpgme_new_signature_t;
1430
1431
1432 /* An object to return results from a signing operation.
1433  * This structure shall be considered read-only and an application
1434  * must not allocate such a structure on its own.  */
1435 struct _gpgme_op_sign_result
1436 {
1437   /* The list of invalid signers.  */
1438   gpgme_invalid_key_t invalid_signers;
1439   gpgme_new_signature_t signatures;
1440 };
1441 typedef struct _gpgme_op_sign_result *gpgme_sign_result_t;
1442
1443 /* Retrieve a pointer to the result of the signing operation.  */
1444 gpgme_sign_result_t gpgme_op_sign_result (gpgme_ctx_t ctx);
1445
1446 /* Sign the plaintext PLAIN and store the signature in SIG.  */
1447 gpgme_error_t gpgme_op_sign_start (gpgme_ctx_t ctx,
1448                                    gpgme_data_t plain, gpgme_data_t sig,
1449                                    gpgme_sig_mode_t mode);
1450 gpgme_error_t gpgme_op_sign (gpgme_ctx_t ctx,
1451                              gpgme_data_t plain, gpgme_data_t sig,
1452                              gpgme_sig_mode_t mode);
1453
1454 \f
1455 /*
1456  * Verify.
1457  */
1458
1459 /* Flags used for the SUMMARY field in a gpgme_signature_t.  */
1460 typedef enum
1461   {
1462     GPGME_SIGSUM_VALID       = 0x0001,  /* The signature is fully valid.  */
1463     GPGME_SIGSUM_GREEN       = 0x0002,  /* The signature is good.  */
1464     GPGME_SIGSUM_RED         = 0x0004,  /* The signature is bad.  */
1465     GPGME_SIGSUM_KEY_REVOKED = 0x0010,  /* One key has been revoked.  */
1466     GPGME_SIGSUM_KEY_EXPIRED = 0x0020,  /* One key has expired.  */
1467     GPGME_SIGSUM_SIG_EXPIRED = 0x0040,  /* The signature has expired.  */
1468     GPGME_SIGSUM_KEY_MISSING = 0x0080,  /* Can't verify: key missing.  */
1469     GPGME_SIGSUM_CRL_MISSING = 0x0100,  /* CRL not available.  */
1470     GPGME_SIGSUM_CRL_TOO_OLD = 0x0200,  /* Available CRL is too old.  */
1471     GPGME_SIGSUM_BAD_POLICY  = 0x0400,  /* A policy was not met.  */
1472     GPGME_SIGSUM_SYS_ERROR   = 0x0800,  /* A system error occurred.  */
1473     GPGME_SIGSUM_TOFU_CONFLICT=0x1000   /* Tofu conflict detected.  */
1474   }
1475 gpgme_sigsum_t;
1476
1477
1478 /* An object to hold the verification status of a signature.
1479  * This structure shall be considered read-only and an application
1480  * must not allocate such a structure on its own.  */
1481 struct _gpgme_signature
1482 {
1483   struct _gpgme_signature *next;
1484
1485   /* A summary of the signature status.  */
1486   gpgme_sigsum_t summary;
1487
1488   /* The fingerprint of the signature.  This can be a subkey.  */
1489   char *fpr;
1490
1491   /* The status of the signature.  */
1492   gpgme_error_t status;
1493
1494   /* Notation data and policy URLs.  */
1495   gpgme_sig_notation_t notations;
1496
1497   /* Signature creation time.  */
1498   unsigned long timestamp;
1499
1500   /* Signature expiration time or 0.  */
1501   unsigned long exp_timestamp;
1502
1503   /* Key should not have been used for signing.  */
1504   unsigned int wrong_key_usage : 1;
1505
1506   /* PKA status: 0 = not available, 1 = bad, 2 = okay, 3 = RFU. */
1507   unsigned int pka_trust : 2;
1508
1509   /* Validity has been verified using the chain model. */
1510   unsigned int chain_model : 1;
1511
1512   /* True if the signature is in compliance to the de-vs mode.  */
1513   unsigned int is_de_vs : 1;
1514
1515   /* Internal to GPGME, do not use.  */
1516   int _unused : 27;
1517
1518   gpgme_validity_t validity;
1519   gpgme_error_t validity_reason;
1520
1521   /* The public key algorithm used to create the signature.  */
1522   gpgme_pubkey_algo_t pubkey_algo;
1523
1524   /* The hash algorithm used to create the signature.  */
1525   gpgme_hash_algo_t hash_algo;
1526
1527   /* The mailbox from the PKA information or NULL. */
1528   char *pka_address;
1529
1530   /* If non-NULL, a possible incomplete key object with the data
1531    * available for the signature.  */
1532   gpgme_key_t key;
1533 };
1534 typedef struct _gpgme_signature *gpgme_signature_t;
1535
1536 /* An object to return the results of a verify operation.
1537  * This structure shall be considered read-only and an application
1538  * must not allocate such a structure on its own.  */
1539 struct _gpgme_op_verify_result
1540 {
1541   gpgme_signature_t signatures;
1542
1543   /* The original file name of the plaintext message, if
1544      available.  */
1545   char *file_name;
1546 };
1547 typedef struct _gpgme_op_verify_result *gpgme_verify_result_t;
1548
1549 /* Retrieve a pointer to the result of the verify operation.  */
1550 gpgme_verify_result_t gpgme_op_verify_result (gpgme_ctx_t ctx);
1551
1552 /* Verify within CTX that SIG is a valid signature for TEXT.  */
1553 gpgme_error_t gpgme_op_verify_start (gpgme_ctx_t ctx, gpgme_data_t sig,
1554                                      gpgme_data_t signed_text,
1555                                      gpgme_data_t plaintext);
1556 gpgme_error_t gpgme_op_verify (gpgme_ctx_t ctx, gpgme_data_t sig,
1557                                gpgme_data_t signed_text,
1558                                gpgme_data_t plaintext);
1559
1560 \f
1561 /*
1562  * Import/Export
1563  */
1564
1565 #define GPGME_IMPORT_NEW        1  /* The key was new.  */
1566 #define GPGME_IMPORT_UID        2  /* The key contained new user IDs.  */
1567 #define GPGME_IMPORT_SIG        4  /* The key contained new signatures.  */
1568 #define GPGME_IMPORT_SUBKEY     8  /* The key contained new sub keys.  */
1569 #define GPGME_IMPORT_SECRET    16  /* The key contained a secret key.  */
1570
1571
1572 /* An object to hold results for one imported key.
1573  * This structure shall be considered read-only and an application
1574  * must not allocate such a structure on its own.  */
1575 struct _gpgme_import_status
1576 {
1577   struct _gpgme_import_status *next;
1578
1579   /* Fingerprint.  */
1580   char *fpr;
1581
1582   /* If a problem occurred, the reason why the key could not be
1583      imported.  Otherwise GPGME_No_Error.  */
1584   gpgme_error_t result;
1585
1586   /* The result of the import, the GPGME_IMPORT_* values bit-wise
1587      ORed.  0 means the key was already known and no new components
1588      have been added.  */
1589   unsigned int status;
1590 };
1591 typedef struct _gpgme_import_status *gpgme_import_status_t;
1592
1593 /* Import result object.
1594  * This structure shall be considered read-only and an application
1595  * must not allocate such a structure on its own.  */
1596 struct _gpgme_op_import_result
1597 {
1598   /* Number of considered keys.  */
1599   int considered;
1600
1601   /* Keys without user ID.  */
1602   int no_user_id;
1603
1604   /* Imported keys.  */
1605   int imported;
1606
1607   /* Imported RSA keys.  */
1608   int imported_rsa;
1609
1610   /* Unchanged keys.  */
1611   int unchanged;
1612
1613   /* Number of new user ids.  */
1614   int new_user_ids;
1615
1616   /* Number of new sub keys.  */
1617   int new_sub_keys;
1618
1619   /* Number of new signatures.  */
1620   int new_signatures;
1621
1622   /* Number of new revocations.  */
1623   int new_revocations;
1624
1625   /* Number of secret keys read.  */
1626   int secret_read;
1627
1628   /* Number of secret keys imported.  */
1629   int secret_imported;
1630
1631   /* Number of secret keys unchanged.  */
1632   int secret_unchanged;
1633
1634   /* Number of new keys skipped.  */
1635   int skipped_new_keys;
1636
1637   /* Number of keys not imported.  */
1638   int not_imported;
1639
1640   /* List of keys for which an import was attempted.  */
1641   gpgme_import_status_t imports;
1642 };
1643 typedef struct _gpgme_op_import_result *gpgme_import_result_t;
1644
1645 /* Retrieve a pointer to the result of the import operation.  */
1646 gpgme_import_result_t gpgme_op_import_result (gpgme_ctx_t ctx);
1647
1648 /* Import the key in KEYDATA into the keyring.  */
1649 gpgme_error_t gpgme_op_import_start (gpgme_ctx_t ctx, gpgme_data_t keydata);
1650 gpgme_error_t gpgme_op_import (gpgme_ctx_t ctx, gpgme_data_t keydata);
1651
1652 /* Import the keys from the array KEYS into the keyring.  */
1653 gpgme_error_t gpgme_op_import_keys_start (gpgme_ctx_t ctx, gpgme_key_t keys[]);
1654 gpgme_error_t gpgme_op_import_keys (gpgme_ctx_t ctx, gpgme_key_t keys[]);
1655
1656
1657 /* Export the keys found by PATTERN into KEYDATA.  */
1658 gpgme_error_t gpgme_op_export_start (gpgme_ctx_t ctx, const char *pattern,
1659                                      gpgme_export_mode_t mode,
1660                                      gpgme_data_t keydata);
1661 gpgme_error_t gpgme_op_export (gpgme_ctx_t ctx, const char *pattern,
1662                                gpgme_export_mode_t mode,
1663                                gpgme_data_t keydata);
1664
1665 gpgme_error_t gpgme_op_export_ext_start (gpgme_ctx_t ctx,
1666                                          const char *pattern[],
1667                                          gpgme_export_mode_t mode,
1668                                          gpgme_data_t keydata);
1669 gpgme_error_t gpgme_op_export_ext (gpgme_ctx_t ctx, const char *pattern[],
1670                                    gpgme_export_mode_t mode,
1671                                    gpgme_data_t keydata);
1672
1673 /* Export the keys from the array KEYS into KEYDATA.  */
1674 gpgme_error_t gpgme_op_export_keys_start (gpgme_ctx_t ctx,
1675                                           gpgme_key_t keys[],
1676                                           gpgme_export_mode_t mode,
1677                                           gpgme_data_t keydata);
1678 gpgme_error_t gpgme_op_export_keys (gpgme_ctx_t ctx,
1679                                     gpgme_key_t keys[],
1680                                     gpgme_export_mode_t mode,
1681                                     gpgme_data_t keydata);
1682
1683
1684 \f
1685 /*
1686  * Key generation.
1687  */
1688
1689 /* Flags for the key creation functions.  */
1690 #define GPGME_CREATE_SIGN       (1 << 0)  /* Allow usage: signing.     */
1691 #define GPGME_CREATE_ENCR       (1 << 1)  /* Allow usage: encryption.  */
1692 #define GPGME_CREATE_CERT       (1 << 2)  /* Allow usage: certification.  */
1693 #define GPGME_CREATE_AUTH       (1 << 3)  /* Allow usage: authentication.  */
1694 #define GPGME_CREATE_NOPASSWD   (1 << 7)  /* Create w/o passphrase.    */
1695 #define GPGME_CREATE_SELFSIGNED (1 << 8)  /* Create self-signed cert.  */
1696 #define GPGME_CREATE_NOSTORE    (1 << 9)  /* Do not store the key.     */
1697 #define GPGME_CREATE_WANTPUB    (1 << 10) /* Return the public key.    */
1698 #define GPGME_CREATE_WANTSEC    (1 << 11) /* Return the secret key.    */
1699 #define GPGME_CREATE_FORCE      (1 << 12) /* Force creation.           */
1700 #define GPGME_CREATE_NOEXPIRE   (1 << 13) /* Create w/o expiration.    */
1701
1702 /* An object to return result from a key generation.
1703  * This structure shall be considered read-only and an application
1704  * must not allocate such a structure on its own.  */
1705 struct _gpgme_op_genkey_result
1706 {
1707   /* A primary key was generated.  */
1708   unsigned int primary : 1;
1709
1710   /* A sub key was generated.  */
1711   unsigned int sub : 1;
1712
1713   /* A user id was generated.  */
1714   unsigned int uid : 1;
1715
1716   /* Internal to GPGME, do not use.  */
1717   unsigned int _unused : 29;
1718
1719   /* The fingerprint of the generated key.  */
1720   char *fpr;
1721
1722   /* A memory data object with the created public key.  Only set when
1723    * GPGME_CREATE_WANTPUB has been used. */
1724   gpgme_data_t pubkey;
1725
1726   /* A memory data object with the created secret key.  Only set when
1727    * GPGME_CREATE_WANTSEC has been used. */
1728   gpgme_data_t seckey;
1729 };
1730 typedef struct _gpgme_op_genkey_result *gpgme_genkey_result_t;
1731
1732 /* Generate a new keypair and add it to the keyring.  PUBKEY and
1733    SECKEY should be null for now.  PARMS specifies what keys should be
1734    generated.  */
1735 gpgme_error_t gpgme_op_genkey_start (gpgme_ctx_t ctx, const char *parms,
1736                                      gpgme_data_t pubkey, gpgme_data_t seckey);
1737 gpgme_error_t gpgme_op_genkey (gpgme_ctx_t ctx, const char *parms,
1738                                gpgme_data_t pubkey, gpgme_data_t seckey);
1739
1740 /* Generate a key pair using the modern interface.  */
1741 gpgme_error_t gpgme_op_createkey_start (gpgme_ctx_t ctx,
1742                                         const char *userid,
1743                                         const char *algo,
1744                                         unsigned long reserved,
1745                                         unsigned long expires,
1746                                         gpgme_key_t certkey,
1747                                         unsigned int flags);
1748 gpgme_error_t gpgme_op_createkey       (gpgme_ctx_t ctx,
1749                                         const char *userid,
1750                                         const char *algo,
1751                                         unsigned long reserved,
1752                                         unsigned long expires,
1753                                         gpgme_key_t certkey,
1754                                         unsigned int flags);
1755 /* Add a new subkey to KEY.  */
1756 gpgme_error_t gpgme_op_createsubkey_start (gpgme_ctx_t ctx,
1757                                            gpgme_key_t key,
1758                                            const char *algo,
1759                                            unsigned long reserved,
1760                                            unsigned long expires,
1761                                            unsigned int flags);
1762 gpgme_error_t gpgme_op_createsubkey       (gpgme_ctx_t ctx,
1763                                            gpgme_key_t key,
1764                                            const char *algo,
1765                                            unsigned long reserved,
1766                                            unsigned long expires,
1767                                            unsigned int flags);
1768
1769 /* Add USERID to an existing KEY.  */
1770 gpgme_error_t gpgme_op_adduid_start (gpgme_ctx_t ctx,
1771                                      gpgme_key_t key, const char *userid,
1772                                      unsigned int reserved);
1773 gpgme_error_t gpgme_op_adduid       (gpgme_ctx_t ctx,
1774                                      gpgme_key_t key, const char *userid,
1775                                      unsigned int reserved);
1776
1777 /* Revoke a USERID from a KEY.  */
1778 gpgme_error_t gpgme_op_revuid_start (gpgme_ctx_t ctx,
1779                                      gpgme_key_t key, const char *userid,
1780                                      unsigned int reserved);
1781 gpgme_error_t gpgme_op_revuid       (gpgme_ctx_t ctx,
1782                                      gpgme_key_t key, const char *userid,
1783                                      unsigned int reserved);
1784
1785 /* Set a flag on the USERID of KEY.  See the manual for supported flags.  */
1786 gpgme_error_t gpgme_op_set_uid_flag_start (gpgme_ctx_t ctx,
1787                                            gpgme_key_t key, const char *userid,
1788                                            const char *name, const char *value);
1789 gpgme_error_t gpgme_op_set_uid_flag       (gpgme_ctx_t ctx,
1790                                            gpgme_key_t key, const char *userid,
1791                                            const char *name, const char *value);
1792
1793
1794 /* Retrieve a pointer to the result of a genkey, createkey, or
1795  * createsubkey operation.  */
1796 gpgme_genkey_result_t gpgme_op_genkey_result (gpgme_ctx_t ctx);
1797
1798
1799 /* Delete KEY from the keyring.  If ALLOW_SECRET is non-zero, secret
1800    keys are also deleted.  */
1801 gpgme_error_t gpgme_op_delete_start (gpgme_ctx_t ctx, const gpgme_key_t key,
1802                                      int allow_secret);
1803 gpgme_error_t gpgme_op_delete (gpgme_ctx_t ctx, const gpgme_key_t key,
1804                                int allow_secret);
1805
1806 /* Flags for the key delete functions.  */
1807 #define GPGME_DELETE_ALLOW_SECRET (1 << 0)  /* Also delete secret key.     */
1808 #define GPGME_DELETE_FORCE        (1 << 1)  /* Do not ask user to confirm.  */
1809
1810 gpgme_error_t gpgme_op_delete_ext_start (gpgme_ctx_t ctx, const gpgme_key_t key,
1811                                          unsigned int flags);
1812 gpgme_error_t gpgme_op_delete_ext (gpgme_ctx_t ctx, const gpgme_key_t key,
1813                                    unsigned int flags);
1814
1815 \f
1816 /*
1817  * Key signing interface
1818  */
1819
1820 /* Flags for the key signing functions.  */
1821 #define GPGME_KEYSIGN_LOCAL     (1 << 7)  /* Create a local signature.  */
1822 #define GPGME_KEYSIGN_LFSEP     (1 << 8)  /* Indicate LF separated user ids. */
1823 #define GPGME_KEYSIGN_NOEXPIRE  (1 << 9)  /* Force no expiration.  */
1824
1825
1826 /* Sign the USERID of KEY using the current set of signers.  */
1827 gpgme_error_t gpgme_op_keysign_start (gpgme_ctx_t ctx,
1828                                       gpgme_key_t key, const char *userid,
1829                                       unsigned long expires,
1830                                       unsigned int flags);
1831 gpgme_error_t gpgme_op_keysign       (gpgme_ctx_t ctx,
1832                                       gpgme_key_t key, const char *userid,
1833                                       unsigned long expires,
1834                                       unsigned int flags);
1835
1836
1837
1838 \f
1839 /*
1840  * Key edit interface
1841  */
1842
1843 /* Flags to select the mode of the interact.  */
1844 #define GPGME_INTERACT_CARD   (1 << 0)  /* Use --card-edit mode. */
1845
1846
1847 /* Edit the KEY.  Send status and command requests to FNC and
1848    output of edit commands to OUT.  */
1849 gpgme_error_t gpgme_op_interact_start (gpgme_ctx_t ctx,
1850                                        gpgme_key_t key,
1851                                        unsigned int flags,
1852                                        gpgme_interact_cb_t fnc,
1853                                        void *fnc_value,
1854                                        gpgme_data_t out);
1855 gpgme_error_t gpgme_op_interact (gpgme_ctx_t ctx, gpgme_key_t key,
1856                                  unsigned int flags,
1857                                  gpgme_interact_cb_t fnc,
1858                                  void *fnc_value,
1859                                  gpgme_data_t out);
1860
1861
1862 /* Set the Tofu policy of KEY to POLCIY.  */
1863 gpgme_error_t gpgme_op_tofu_policy_start (gpgme_ctx_t ctx,
1864                                           gpgme_key_t key,
1865                                           gpgme_tofu_policy_t policy);
1866 gpgme_error_t gpgme_op_tofu_policy       (gpgme_ctx_t ctx,
1867                                           gpgme_key_t key,
1868                                           gpgme_tofu_policy_t policy);
1869
1870
1871
1872 \f
1873 /*
1874  * Key listing
1875  */
1876
1877 /* An object to return results from a key listing operation.
1878  * This structure shall be considered read-only and an application
1879  * must not allocate such a structure on its own.  */
1880 struct _gpgme_op_keylist_result
1881 {
1882   unsigned int truncated : 1;
1883
1884   /* Internal to GPGME, do not use.  */
1885   unsigned int _unused : 31;
1886 };
1887 typedef struct _gpgme_op_keylist_result *gpgme_keylist_result_t;
1888
1889 /* Retrieve a pointer to the result of the key listing operation.  */
1890 gpgme_keylist_result_t gpgme_op_keylist_result (gpgme_ctx_t ctx);
1891
1892 /* Start a keylist operation within CTX, searching for keys which
1893  * match PATTERN.  If SECRET_ONLY is true, only secret keys are
1894  * returned.  */
1895 gpgme_error_t gpgme_op_keylist_start (gpgme_ctx_t ctx, const char *pattern,
1896                                       int secret_only);
1897 gpgme_error_t gpgme_op_keylist_ext_start (gpgme_ctx_t ctx,
1898                                           const char *pattern[],
1899                                           int secret_only, int reserved);
1900
1901 /* List the keys contained in DATA.  */
1902 gpgme_error_t gpgme_op_keylist_from_data_start (gpgme_ctx_t ctx,
1903                                                 gpgme_data_t data,
1904                                                 int reserved);
1905
1906 /* Return the next key from the keylist in R_KEY.  */
1907 gpgme_error_t gpgme_op_keylist_next (gpgme_ctx_t ctx, gpgme_key_t *r_key);
1908
1909 /* Terminate a pending keylist operation within CTX.  */
1910 gpgme_error_t gpgme_op_keylist_end (gpgme_ctx_t ctx);
1911
1912
1913 \f
1914 /*
1915  * Protecting keys
1916  */
1917
1918 /* Change the passphrase for KEY.  FLAGS is reserved for future use
1919    and must be passed as 0.  */
1920 gpgme_error_t gpgme_op_passwd_start (gpgme_ctx_t ctx, gpgme_key_t key,
1921                                      unsigned int flags);
1922 gpgme_error_t gpgme_op_passwd (gpgme_ctx_t ctx, gpgme_key_t key,
1923                                unsigned int flags);
1924
1925
1926 \f
1927 /*
1928  * Trust items and operations.
1929  */
1930
1931 /* An object to hold data of a trust item.
1932  * This structure shall be considered read-only and an application
1933  * must not allocate such a structure on its own.  */
1934 struct _gpgme_trust_item
1935 {
1936   /* Internal to GPGME, do not use.  */
1937   unsigned int _refs;
1938
1939   /* The key ID to which the trust item belongs.  */
1940   char *keyid;
1941
1942   /* Internal to GPGME, do not use.  */
1943   char _keyid[16 + 1];
1944
1945   /* The type of the trust item, 1 refers to a key, 2 to a user ID.  */
1946   int type;
1947
1948   /* The trust level.  */
1949   int level;
1950
1951   /* The owner trust if TYPE is 1.  */
1952   char *owner_trust;
1953
1954   /* Internal to GPGME, do not use.  */
1955   char _owner_trust[2];
1956
1957   /* The calculated validity.  */
1958   char *validity;
1959
1960   /* Internal to GPGME, do not use.  */
1961   char _validity[2];
1962
1963   /* The user name if TYPE is 2.  */
1964   char *name;
1965 };
1966 typedef struct _gpgme_trust_item *gpgme_trust_item_t;
1967
1968 /* Start a trustlist operation within CTX, searching for trust items
1969    which match PATTERN.  */
1970 gpgme_error_t gpgme_op_trustlist_start (gpgme_ctx_t ctx,
1971                                         const char *pattern, int max_level);
1972
1973 /* Return the next trust item from the trustlist in R_ITEM.  */
1974 gpgme_error_t gpgme_op_trustlist_next (gpgme_ctx_t ctx,
1975                                        gpgme_trust_item_t *r_item);
1976
1977 /* Terminate a pending trustlist operation within CTX.  */
1978 gpgme_error_t gpgme_op_trustlist_end (gpgme_ctx_t ctx);
1979
1980 /* Acquire a reference to ITEM.  */
1981 void gpgme_trust_item_ref (gpgme_trust_item_t item);
1982
1983 /* Release a reference to ITEM.  If this was the last one the trust
1984    item is destroyed.  */
1985 void gpgme_trust_item_unref (gpgme_trust_item_t item);
1986
1987
1988 \f
1989 /*
1990  * Audit log
1991  */
1992
1993 /* Return the auditlog for the current session.  This may be called
1994    after a successful or failed operation.  If no audit log is
1995    available GPG_ERR_NO_DATA is returned.  */
1996 gpgme_error_t gpgme_op_getauditlog_start (gpgme_ctx_t ctx, gpgme_data_t output,
1997                                           unsigned int flags);
1998 gpgme_error_t gpgme_op_getauditlog (gpgme_ctx_t ctx, gpgme_data_t output,
1999                                     unsigned int flags);
2000
2001
2002 \f
2003 /*
2004  * Spawn interface
2005  */
2006
2007 /* Flags for the spawn operations.  */
2008 #define GPGME_SPAWN_DETACHED      1
2009 #define GPGME_SPAWN_ALLOW_SET_FG  2
2010
2011
2012 /* Run the command FILE with the arguments in ARGV.  Connect stdin to
2013    DATAIN, stdout to DATAOUT, and STDERR to DATAERR.  If one the data
2014    streams is NULL, connect to /dev/null instead.  */
2015 gpgme_error_t gpgme_op_spawn_start (gpgme_ctx_t ctx,
2016                                     const char *file, const char *argv[],
2017                                     gpgme_data_t datain,
2018                                     gpgme_data_t dataout, gpgme_data_t dataerr,
2019                                     unsigned int flags);
2020 gpgme_error_t gpgme_op_spawn (gpgme_ctx_t ctx,
2021                               const char *file, const char *argv[],
2022                               gpgme_data_t datain,
2023                               gpgme_data_t dataout, gpgme_data_t dataerr,
2024                               unsigned int flags);
2025
2026 \f
2027 /*
2028  * Low-level Assuan protocol access.
2029  */
2030 typedef gpgme_error_t (*gpgme_assuan_data_cb_t)
2031      (void *opaque, const void *data, size_t datalen);
2032
2033 typedef gpgme_error_t (*gpgme_assuan_inquire_cb_t)
2034      (void *opaque, const char *name, const char *args,
2035       gpgme_data_t *r_data);
2036
2037 typedef gpgme_error_t (*gpgme_assuan_status_cb_t)
2038      (void *opaque, const char *status, const char *args);
2039
2040 /* Send the Assuan COMMAND and return results via the callbacks.
2041    Asynchronous variant. */
2042 gpgme_error_t gpgme_op_assuan_transact_start (gpgme_ctx_t ctx,
2043                                               const char *command,
2044                                               gpgme_assuan_data_cb_t data_cb,
2045                                               void *data_cb_value,
2046                                               gpgme_assuan_inquire_cb_t inq_cb,
2047                                               void *inq_cb_value,
2048                                               gpgme_assuan_status_cb_t stat_cb,
2049                                               void *stat_cb_value);
2050
2051 /* Send the Assuan COMMAND and return results via the callbacks.
2052    Synchronous variant. */
2053 gpgme_error_t gpgme_op_assuan_transact_ext (gpgme_ctx_t ctx,
2054                                             const char *command,
2055                                             gpgme_assuan_data_cb_t data_cb,
2056                                             void *data_cb_value,
2057                                             gpgme_assuan_inquire_cb_t inq_cb,
2058                                             void *inq_cb_value,
2059                                             gpgme_assuan_status_cb_t stat_cb,
2060                                             void *stat_cb_value,
2061                                             gpgme_error_t *op_err);
2062
2063 \f
2064 /*
2065  * Crypto container support.
2066  */
2067
2068 /* An object to return results from a VFS mount operation.
2069  * This structure shall be considered read-only and an application
2070  * must not allocate such a structure on its own.  */
2071 struct _gpgme_op_vfs_mount_result
2072 {
2073   char *mount_dir;
2074 };
2075 typedef struct _gpgme_op_vfs_mount_result *gpgme_vfs_mount_result_t;
2076
2077 gpgme_vfs_mount_result_t gpgme_op_vfs_mount_result (gpgme_ctx_t ctx);
2078
2079 /* The container is automatically unmounted when the context is reset
2080    or destroyed.  Transmission errors are returned directly,
2081    operational errors are returned in OP_ERR.  */
2082 gpgme_error_t gpgme_op_vfs_mount (gpgme_ctx_t ctx, const char *container_file,
2083                                   const char *mount_dir, unsigned int flags,
2084                                   gpgme_error_t *op_err);
2085
2086 gpgme_error_t gpgme_op_vfs_create (gpgme_ctx_t ctx, gpgme_key_t recp[],
2087                                    const char *container_file,
2088                                    unsigned int flags, gpgme_error_t *op_err);
2089
2090 \f
2091 /*
2092  * Interface to gpgconf(1).
2093  */
2094
2095 /* The expert level at which a configuration option or group of
2096    options should be displayed.  See the gpgconf(1) documentation for
2097    more details.  */
2098 typedef enum
2099   {
2100     GPGME_CONF_BASIC = 0,
2101     GPGME_CONF_ADVANCED = 1,
2102     GPGME_CONF_EXPERT = 2,
2103     GPGME_CONF_INVISIBLE = 3,
2104     GPGME_CONF_INTERNAL = 4
2105   }
2106 gpgme_conf_level_t;
2107
2108
2109 /* The data type of a configuration option argument.  See the gpgconf(1)
2110    documentation for more details.  */
2111 typedef enum
2112   {
2113     /* Basic types.  */
2114     GPGME_CONF_NONE = 0,
2115     GPGME_CONF_STRING = 1,
2116     GPGME_CONF_INT32 = 2,
2117     GPGME_CONF_UINT32 = 3,
2118
2119     /* Complex types.  */
2120     GPGME_CONF_FILENAME = 32,
2121     GPGME_CONF_LDAP_SERVER = 33,
2122     GPGME_CONF_KEY_FPR = 34,
2123     GPGME_CONF_PUB_KEY = 35,
2124     GPGME_CONF_SEC_KEY = 36,
2125     GPGME_CONF_ALIAS_LIST = 37
2126   }
2127 gpgme_conf_type_t;
2128
2129 /* For now, compatibility.  */
2130 #define GPGME_CONF_PATHNAME GPGME_CONF_FILENAME
2131
2132
2133 /* This represents a single argument for a configuration option.
2134    Which of the members of value is used depends on the ALT_TYPE.  */
2135 typedef struct gpgme_conf_arg
2136 {
2137   struct gpgme_conf_arg *next;
2138   /* True if the option appears without an (optional) argument.  */
2139   unsigned int no_arg;
2140   union
2141   {
2142     unsigned int count;
2143     unsigned int uint32;
2144     int int32;
2145     char *string;
2146   } value;
2147 } *gpgme_conf_arg_t;
2148
2149
2150 /* The flags of a configuration option.  See the gpgconf
2151    documentation for details.  */
2152 #define GPGME_CONF_GROUP        (1 << 0)
2153 #define GPGME_CONF_OPTIONAL     (1 << 1)
2154 #define GPGME_CONF_LIST         (1 << 2)
2155 #define GPGME_CONF_RUNTIME      (1 << 3)
2156 #define GPGME_CONF_DEFAULT      (1 << 4)
2157 #define GPGME_CONF_DEFAULT_DESC (1 << 5)
2158 #define GPGME_CONF_NO_ARG_DESC  (1 << 6)
2159 #define GPGME_CONF_NO_CHANGE    (1 << 7)
2160
2161
2162 /* The representation of a single configuration option.  See the
2163    gpg-conf documentation for details.  */
2164 typedef struct gpgme_conf_opt
2165 {
2166   struct gpgme_conf_opt *next;
2167
2168   /* The option name.  */
2169   char *name;
2170
2171   /* The flags for this option.  */
2172   unsigned int flags;
2173
2174   /* The level of this option.  */
2175   gpgme_conf_level_t level;
2176
2177   /* The localized description of this option.  */
2178   char *description;
2179
2180   /* The type and alternate type of this option.  */
2181   gpgme_conf_type_t type;
2182   gpgme_conf_type_t alt_type;
2183
2184   /* The localized (short) name of the argument, if any.  */
2185   char *argname;
2186
2187   /* The default value.  */
2188   gpgme_conf_arg_t default_value;
2189   char *default_description;
2190
2191   /* The default value if the option is not set.  */
2192   gpgme_conf_arg_t no_arg_value;
2193   char *no_arg_description;
2194
2195   /* The current value if the option is set.  */
2196   gpgme_conf_arg_t value;
2197
2198   /* The new value, if any.  NULL means reset to default.  */
2199   int change_value;
2200   gpgme_conf_arg_t new_value;
2201
2202   /* Free for application use.  */
2203   void *user_data;
2204 } *gpgme_conf_opt_t;
2205
2206
2207 /* The representation of a component that can be configured.  See the
2208    gpg-conf documentation for details.  */
2209 typedef struct gpgme_conf_comp
2210 {
2211   struct gpgme_conf_comp *next;
2212
2213   /* Internal to GPGME, do not use!  */
2214   gpgme_conf_opt_t *_last_opt_p;
2215
2216   /* The component name.  */
2217   char *name;
2218
2219   /* A human-readable description for the component.  */
2220   char *description;
2221
2222   /* The program name (an absolute path to the program).  */
2223   char *program_name;
2224
2225   /* A linked list of options for this component.  */
2226   struct gpgme_conf_opt *options;
2227 } *gpgme_conf_comp_t;
2228
2229
2230 /* Allocate a new gpgme_conf_arg_t.  If VALUE is NULL, a "no arg
2231    default" is prepared.  If type is a string type, VALUE should point
2232    to the string.  Else, it should point to an unsigned or signed
2233    integer respectively.  */
2234 gpgme_error_t gpgme_conf_arg_new (gpgme_conf_arg_t *arg_p,
2235                                   gpgme_conf_type_t type, const void *value);
2236
2237 /* This also releases all chained argument structures!  */
2238 void gpgme_conf_arg_release (gpgme_conf_arg_t arg, gpgme_conf_type_t type);
2239
2240 /* Register a change for the value of OPT to ARG.  If RESET is 1 (do
2241    not use any values but 0 or 1), ARG is ignored and the option is
2242    not changed (reverting a previous change).  Otherwise, if ARG is
2243    NULL, the option is cleared or reset to its default. The change
2244    is done with gpgconf's --runtime option to immediately take effect. */
2245 gpgme_error_t gpgme_conf_opt_change (gpgme_conf_opt_t opt, int reset,
2246                                      gpgme_conf_arg_t arg);
2247
2248 /* Release a set of configurations.  */
2249 void gpgme_conf_release (gpgme_conf_comp_t conf);
2250
2251 /* Retrieve the current configurations.  */
2252 gpgme_error_t gpgme_op_conf_load (gpgme_ctx_t ctx, gpgme_conf_comp_t *conf_p);
2253
2254 /* Save the configuration of component comp.  This function does not
2255    follow chained components!  */
2256 gpgme_error_t gpgme_op_conf_save (gpgme_ctx_t ctx, gpgme_conf_comp_t comp);
2257
2258 /* Retrieve the configured directory.  */
2259 gpgme_error_t gpgme_op_conf_dir(gpgme_ctx_t ctx, const char *what,
2260                                 char **result);
2261
2262
2263 /* Information about software versions.
2264  * This structure shall be considered read-only and an application
2265  * must not allocate such a structure on its own.  */
2266 typedef struct _gpgme_op_query_swdb_result
2267 {
2268   /* RFU */
2269   struct _gpgme_op_query_swdb_result *next;
2270
2271   /* The name of the package (e.g. "gpgme", "gnupg") */
2272   char *name;
2273
2274   /* The version number of the installed version.  */
2275   char *iversion;
2276
2277   /* The time the online info was created.  */
2278   unsigned long created;
2279
2280   /* The time the online info was retrieved.  */
2281   unsigned long retrieved;
2282
2283   /* This bit is set if an error occured or some of the information
2284    * in this structure may not be set.  */
2285   unsigned int warning : 1;
2286
2287   /* An update is available.  */
2288   unsigned int update : 1;
2289
2290   /* The update is important.  */
2291   unsigned int urgent : 1;
2292
2293   /* No information at all available.  */
2294   unsigned int noinfo : 1;
2295
2296   /* The package name is not known. */
2297   unsigned int unknown : 1;
2298
2299   /* The information here is too old.  */
2300   unsigned int tooold : 1;
2301
2302   /* Other error.  */
2303   unsigned int error : 1;
2304
2305   unsigned int _reserved : 25;
2306
2307   /* The version number of the latest released version.  */
2308   char *version;
2309
2310   /* The release date of that version.  */
2311   unsigned long reldate;
2312
2313 } *gpgme_query_swdb_result_t;
2314
2315
2316 /* Run the gpgconf --query-swdb command.  */
2317 gpgme_error_t gpgme_op_query_swdb (gpgme_ctx_t ctx,
2318                                    const char *name, const char *iversion,
2319                                    unsigned int reserved);
2320
2321 /* Return the result from the last query_swdb operation.  */
2322 gpgme_query_swdb_result_t gpgme_op_query_swdb_result (gpgme_ctx_t ctx);
2323
2324
2325
2326 \f
2327 /*
2328  * Various functions.
2329  */
2330
2331 /* Set special global flags; consult the manual before use.  */
2332 int gpgme_set_global_flag (const char *name, const char *value);
2333
2334 /* Check that the library fulfills the version requirement.  Note:
2335    This is here only for the case where a user takes a pointer from
2336    the old version of this function.  The new version and macro for
2337    run-time checks are below.  */
2338 const char *gpgme_check_version (const char *req_version);
2339
2340 /* Check that the library fulfills the version requirement and check
2341    for struct layout mismatch involving bitfields.  */
2342 const char *gpgme_check_version_internal (const char *req_version,
2343                                           size_t offset_sig_validity);
2344
2345 #define gpgme_check_version(req_version)                                \
2346   gpgme_check_version_internal (req_version,                            \
2347                                 offsetof (struct _gpgme_signature, validity))
2348
2349 /* Return the default values for various directories.  */
2350 const char *gpgme_get_dirinfo (const char *what);
2351
2352 /* Get the information about the configured and installed engines.  A
2353    pointer to the first engine in the statically allocated linked list
2354    is returned in *INFO.  If an error occurs, it is returned.  The
2355    returned data is valid until the next gpgme_set_engine_info.  */
2356 gpgme_error_t gpgme_get_engine_info (gpgme_engine_info_t *engine_info);
2357
2358 /* Set the default engine info for the protocol PROTO to the file name
2359    FILE_NAME and the home directory HOME_DIR.  */
2360 gpgme_error_t gpgme_set_engine_info (gpgme_protocol_t proto,
2361                                      const char *file_name,
2362                                      const char *home_dir);
2363
2364 /* Verify that the engine implementing PROTO is installed and
2365    available.  */
2366 gpgme_error_t gpgme_engine_check_version (gpgme_protocol_t proto);
2367
2368
2369 /* Reference counting for result objects.  */
2370 void gpgme_result_ref (void *result);
2371 void gpgme_result_unref (void *result);
2372
2373 /* Return a public key algorithm string (e.g. "rsa2048").  Caller must
2374    free using gpgme_free.  */
2375 char *gpgme_pubkey_algo_string (gpgme_subkey_t subkey);
2376
2377 /* Return a statically allocated string with the name of the public
2378    key algorithm ALGO, or NULL if that name is not known.  */
2379 const char *gpgme_pubkey_algo_name (gpgme_pubkey_algo_t algo);
2380
2381 /* Return a statically allocated string with the name of the hash
2382    algorithm ALGO, or NULL if that name is not known.  */
2383 const char *gpgme_hash_algo_name (gpgme_hash_algo_t algo);
2384
2385 /* Return the addr-spec from a user id.  Caller must free the result
2386  * with gpgme_free. */
2387 char *gpgme_addrspec_from_uid (const char *uid);
2388
2389
2390 \f
2391 /*
2392  * Deprecated types, constants and functions.
2393  */
2394
2395 /* The possible stati for gpgme_op_edit.  The use of that function and
2396  * these status codes are deprecated in favor of gpgme_op_interact. */
2397 typedef enum
2398   {
2399     GPGME_STATUS_EOF = 0,
2400     /* mkstatus processing starts here */
2401     GPGME_STATUS_ENTER = 1,
2402     GPGME_STATUS_LEAVE = 2,
2403     GPGME_STATUS_ABORT = 3,
2404
2405     GPGME_STATUS_GOODSIG = 4,
2406     GPGME_STATUS_BADSIG = 5,
2407     GPGME_STATUS_ERRSIG = 6,
2408
2409     GPGME_STATUS_BADARMOR = 7,
2410
2411     GPGME_STATUS_RSA_OR_IDEA = 8,      /* (legacy) */
2412     GPGME_STATUS_KEYEXPIRED = 9,
2413     GPGME_STATUS_KEYREVOKED = 10,
2414
2415     GPGME_STATUS_TRUST_UNDEFINED = 11,
2416     GPGME_STATUS_TRUST_NEVER = 12,
2417     GPGME_STATUS_TRUST_MARGINAL = 13,
2418     GPGME_STATUS_TRUST_FULLY = 14,
2419     GPGME_STATUS_TRUST_ULTIMATE = 15,
2420
2421     GPGME_STATUS_SHM_INFO = 16,        /* (legacy) */
2422     GPGME_STATUS_SHM_GET = 17,         /* (legacy) */
2423     GPGME_STATUS_SHM_GET_BOOL = 18,    /* (legacy) */
2424     GPGME_STATUS_SHM_GET_HIDDEN = 19,  /* (legacy) */
2425
2426     GPGME_STATUS_NEED_PASSPHRASE = 20,
2427     GPGME_STATUS_VALIDSIG = 21,
2428     GPGME_STATUS_SIG_ID = 22,
2429     GPGME_STATUS_ENC_TO = 23,
2430     GPGME_STATUS_NODATA = 24,
2431     GPGME_STATUS_BAD_PASSPHRASE = 25,
2432     GPGME_STATUS_NO_PUBKEY = 26,
2433     GPGME_STATUS_NO_SECKEY = 27,
2434     GPGME_STATUS_NEED_PASSPHRASE_SYM = 28,
2435     GPGME_STATUS_DECRYPTION_FAILED = 29,
2436     GPGME_STATUS_DECRYPTION_OKAY = 30,
2437     GPGME_STATUS_MISSING_PASSPHRASE = 31,
2438     GPGME_STATUS_GOOD_PASSPHRASE = 32,
2439     GPGME_STATUS_GOODMDC = 33,
2440     GPGME_STATUS_BADMDC = 34,
2441     GPGME_STATUS_ERRMDC = 35,
2442     GPGME_STATUS_IMPORTED = 36,
2443     GPGME_STATUS_IMPORT_OK = 37,
2444     GPGME_STATUS_IMPORT_PROBLEM = 38,
2445     GPGME_STATUS_IMPORT_RES = 39,
2446     GPGME_STATUS_FILE_START = 40,
2447     GPGME_STATUS_FILE_DONE = 41,
2448     GPGME_STATUS_FILE_ERROR = 42,
2449
2450     GPGME_STATUS_BEGIN_DECRYPTION = 43,
2451     GPGME_STATUS_END_DECRYPTION = 44,
2452     GPGME_STATUS_BEGIN_ENCRYPTION = 45,
2453     GPGME_STATUS_END_ENCRYPTION = 46,
2454
2455     GPGME_STATUS_DELETE_PROBLEM = 47,
2456     GPGME_STATUS_GET_BOOL = 48,
2457     GPGME_STATUS_GET_LINE = 49,
2458     GPGME_STATUS_GET_HIDDEN = 50,
2459     GPGME_STATUS_GOT_IT = 51,
2460     GPGME_STATUS_PROGRESS = 52,
2461     GPGME_STATUS_SIG_CREATED = 53,
2462     GPGME_STATUS_SESSION_KEY = 54,
2463     GPGME_STATUS_NOTATION_NAME = 55,
2464     GPGME_STATUS_NOTATION_DATA = 56,
2465     GPGME_STATUS_POLICY_URL = 57,
2466     GPGME_STATUS_BEGIN_STREAM = 58,    /* (legacy) */
2467     GPGME_STATUS_END_STREAM = 59,      /* (legacy) */
2468     GPGME_STATUS_KEY_CREATED = 60,
2469     GPGME_STATUS_USERID_HINT = 61,
2470     GPGME_STATUS_UNEXPECTED = 62,
2471     GPGME_STATUS_INV_RECP = 63,
2472     GPGME_STATUS_NO_RECP = 64,
2473     GPGME_STATUS_ALREADY_SIGNED = 65,
2474     GPGME_STATUS_SIGEXPIRED = 66,      /* (legacy) */
2475     GPGME_STATUS_EXPSIG = 67,
2476     GPGME_STATUS_EXPKEYSIG = 68,
2477     GPGME_STATUS_TRUNCATED = 69,
2478     GPGME_STATUS_ERROR = 70,
2479     GPGME_STATUS_NEWSIG = 71,
2480     GPGME_STATUS_REVKEYSIG = 72,
2481     GPGME_STATUS_SIG_SUBPACKET = 73,
2482     GPGME_STATUS_NEED_PASSPHRASE_PIN = 74,
2483     GPGME_STATUS_SC_OP_FAILURE = 75,
2484     GPGME_STATUS_SC_OP_SUCCESS = 76,
2485     GPGME_STATUS_CARDCTRL = 77,
2486     GPGME_STATUS_BACKUP_KEY_CREATED = 78,
2487     GPGME_STATUS_PKA_TRUST_BAD = 79,
2488     GPGME_STATUS_PKA_TRUST_GOOD = 80,
2489     GPGME_STATUS_PLAINTEXT = 81,
2490     GPGME_STATUS_INV_SGNR = 82,
2491     GPGME_STATUS_NO_SGNR = 83,
2492     GPGME_STATUS_SUCCESS = 84,
2493     GPGME_STATUS_DECRYPTION_INFO = 85,
2494     GPGME_STATUS_PLAINTEXT_LENGTH = 86,
2495     GPGME_STATUS_MOUNTPOINT = 87,
2496     GPGME_STATUS_PINENTRY_LAUNCHED = 88,
2497     GPGME_STATUS_ATTRIBUTE = 89,
2498     GPGME_STATUS_BEGIN_SIGNING = 90,
2499     GPGME_STATUS_KEY_NOT_CREATED = 91,
2500     GPGME_STATUS_INQUIRE_MAXLEN = 92,
2501     GPGME_STATUS_FAILURE = 93,
2502     GPGME_STATUS_KEY_CONSIDERED = 94,
2503     GPGME_STATUS_TOFU_USER = 95,
2504     GPGME_STATUS_TOFU_STATS = 96,
2505     GPGME_STATUS_TOFU_STATS_LONG = 97,
2506     GPGME_STATUS_NOTATION_FLAGS = 98,
2507     GPGME_STATUS_DECRYPTION_COMPLIANCE_MODE = 99,
2508     GPGME_STATUS_VERIFICATION_COMPLIANCE_MODE = 100
2509   }
2510 gpgme_status_code_t;
2511
2512 /* The callback type used by the deprecated functions gpgme_op_edit
2513  * and gpgme_op_card_edit.  */
2514 typedef gpgme_error_t (*gpgme_edit_cb_t) (void *opaque,
2515                                           gpgme_status_code_t status,
2516                                           const char *args, int fd);
2517
2518 gpgme_error_t gpgme_op_edit_start (gpgme_ctx_t ctx, gpgme_key_t key,
2519                                    gpgme_edit_cb_t fnc, void *fnc_value,
2520                                    gpgme_data_t out) _GPGME_DEPRECATED(1,7);
2521 gpgme_error_t gpgme_op_edit       (gpgme_ctx_t ctx, gpgme_key_t key,
2522                                    gpgme_edit_cb_t fnc, void *fnc_value,
2523                                    gpgme_data_t out) _GPGME_DEPRECATED(1,7);
2524 gpgme_error_t gpgme_op_card_edit_start (gpgme_ctx_t ctx, gpgme_key_t key,
2525                                         gpgme_edit_cb_t fnc, void *fnc_value,
2526                                         gpgme_data_t out)
2527                                         _GPGME_DEPRECATED(1,7);
2528 gpgme_error_t gpgme_op_card_edit       (gpgme_ctx_t ctx, gpgme_key_t key,
2529                                         gpgme_edit_cb_t fnc, void *fnc_value,
2530                                         gpgme_data_t out)
2531                                         _GPGME_DEPRECATED(1,7);
2532
2533 /* The possible signature stati.  Deprecated, use error value in sig
2534    status.  */
2535 typedef enum
2536   {
2537     GPGME_SIG_STAT_NONE  = 0,
2538     GPGME_SIG_STAT_GOOD  = 1,
2539     GPGME_SIG_STAT_BAD   = 2,
2540     GPGME_SIG_STAT_NOKEY = 3,
2541     GPGME_SIG_STAT_NOSIG = 4,
2542     GPGME_SIG_STAT_ERROR = 5,
2543     GPGME_SIG_STAT_DIFF  = 6,
2544     GPGME_SIG_STAT_GOOD_EXP = 7,
2545     GPGME_SIG_STAT_GOOD_EXPKEY = 8
2546   }
2547 _gpgme_sig_stat_t;
2548 typedef _gpgme_sig_stat_t gpgme_sig_stat_t _GPGME_DEPRECATED(0,4);
2549
2550 /* The available key and signature attributes.  Deprecated, use the
2551    individual result structures instead.  */
2552 typedef enum
2553   {
2554     GPGME_ATTR_KEYID        = 1,
2555     GPGME_ATTR_FPR          = 2,
2556     GPGME_ATTR_ALGO         = 3,
2557     GPGME_ATTR_LEN          = 4,
2558     GPGME_ATTR_CREATED      = 5,
2559     GPGME_ATTR_EXPIRE       = 6,
2560     GPGME_ATTR_OTRUST       = 7,
2561     GPGME_ATTR_USERID       = 8,
2562     GPGME_ATTR_NAME         = 9,
2563     GPGME_ATTR_EMAIL        = 10,
2564     GPGME_ATTR_COMMENT      = 11,
2565     GPGME_ATTR_VALIDITY     = 12,
2566     GPGME_ATTR_LEVEL        = 13,
2567     GPGME_ATTR_TYPE         = 14,
2568     GPGME_ATTR_IS_SECRET    = 15,
2569     GPGME_ATTR_KEY_REVOKED  = 16,
2570     GPGME_ATTR_KEY_INVALID  = 17,
2571     GPGME_ATTR_UID_REVOKED  = 18,
2572     GPGME_ATTR_UID_INVALID  = 19,
2573     GPGME_ATTR_KEY_CAPS     = 20,
2574     GPGME_ATTR_CAN_ENCRYPT  = 21,
2575     GPGME_ATTR_CAN_SIGN     = 22,
2576     GPGME_ATTR_CAN_CERTIFY  = 23,
2577     GPGME_ATTR_KEY_EXPIRED  = 24,
2578     GPGME_ATTR_KEY_DISABLED = 25,
2579     GPGME_ATTR_SERIAL       = 26,
2580     GPGME_ATTR_ISSUER       = 27,
2581     GPGME_ATTR_CHAINID      = 28,
2582     GPGME_ATTR_SIG_STATUS   = 29,
2583     GPGME_ATTR_ERRTOK       = 30,
2584     GPGME_ATTR_SIG_SUMMARY  = 31,
2585     GPGME_ATTR_SIG_CLASS    = 32
2586   }
2587 _gpgme_attr_t;
2588 typedef _gpgme_attr_t gpgme_attr_t _GPGME_DEPRECATED(0,4);
2589
2590 /* Retrieve the signature status of signature IDX in CTX after a
2591    successful verify operation in R_STAT (if non-null).  The creation
2592    time stamp of the signature is returned in R_CREATED (if non-null).
2593    The function returns a string containing the fingerprint.
2594    Deprecated, use verify result directly.  */
2595 const char *gpgme_get_sig_status (gpgme_ctx_t ctx, int idx,
2596                                   _gpgme_sig_stat_t *r_stat,
2597                                   time_t *r_created) _GPGME_DEPRECATED(0,4);
2598
2599 /* Retrieve certain attributes of a signature.  IDX is the index
2600    number of the signature after a successful verify operation.  WHAT
2601    is an attribute where GPGME_ATTR_EXPIRE is probably the most useful
2602    one.  WHATIDX is to be passed as 0 for most attributes . */
2603 unsigned long gpgme_get_sig_ulong_attr (gpgme_ctx_t c, int idx,
2604                                         _gpgme_attr_t what, int whatidx)
2605      _GPGME_DEPRECATED(0,4);
2606 const char *gpgme_get_sig_string_attr (gpgme_ctx_t c, int idx,
2607                                        _gpgme_attr_t what, int whatidx)
2608      _GPGME_DEPRECATED(0,4);
2609
2610
2611 /* Get the key used to create signature IDX in CTX and return it in
2612    R_KEY.  */
2613 gpgme_error_t gpgme_get_sig_key (gpgme_ctx_t ctx, int idx, gpgme_key_t *r_key)
2614      _GPGME_DEPRECATED(0,4);
2615
2616 /* Create a new data buffer which retrieves the data from the callback
2617    function READ_CB.  Deprecated, please use gpgme_data_new_from_cbs
2618    instead.  */
2619 gpgme_error_t gpgme_data_new_with_read_cb (gpgme_data_t *r_dh,
2620                                            int (*read_cb) (void*,char *,
2621                                                            size_t,size_t*),
2622                                            void *read_cb_value)
2623      _GPGME_DEPRECATED(0,4);
2624
2625 /* Return the value of the attribute WHAT of KEY, which has to be
2626    representable by a string.  IDX specifies the sub key or user ID
2627    for attributes related to sub keys or user IDs.  Deprecated, use
2628    key structure directly instead. */
2629 const char *gpgme_key_get_string_attr (gpgme_key_t key, _gpgme_attr_t what,
2630                                        const void *reserved, int idx)
2631      _GPGME_DEPRECATED(0,4);
2632
2633 /* Return the value of the attribute WHAT of KEY, which has to be
2634    representable by an unsigned integer.  IDX specifies the sub key or
2635    user ID for attributes related to sub keys or user IDs.
2636    Deprecated, use key structure directly instead.  */
2637 unsigned long gpgme_key_get_ulong_attr (gpgme_key_t key, _gpgme_attr_t what,
2638                                         const void *reserved, int idx)
2639      _GPGME_DEPRECATED(0,4);
2640
2641 /* Return the value of the attribute WHAT of a signature on user ID
2642    UID_IDX in KEY, which has to be representable by a string.  IDX
2643    specifies the signature.  Deprecated, use key structure directly
2644    instead.  */
2645 const char *gpgme_key_sig_get_string_attr (gpgme_key_t key, int uid_idx,
2646                                            _gpgme_attr_t what,
2647                                            const void *reserved, int idx)
2648      _GPGME_DEPRECATED(0,4);
2649
2650 /* Return the value of the attribute WHAT of a signature on user ID
2651    UID_IDX in KEY, which has to be representable by an unsigned
2652    integer string.  IDX specifies the signature.  Deprecated, use key
2653    structure directly instead.  */
2654 unsigned long gpgme_key_sig_get_ulong_attr (gpgme_key_t key, int uid_idx,
2655                                             _gpgme_attr_t what,
2656                                             const void *reserved, int idx)
2657      _GPGME_DEPRECATED(0,4);
2658
2659
2660 gpgme_error_t gpgme_op_import_ext (gpgme_ctx_t ctx, gpgme_data_t keydata,
2661                                    int *nr) _GPGME_DEPRECATED(0,4);
2662
2663 /* Release the trust item ITEM.  Deprecated, use
2664    gpgme_trust_item_unref.  */
2665 void gpgme_trust_item_release (gpgme_trust_item_t item) _GPGME_DEPRECATED(0,4);
2666
2667 /* Return the value of the attribute WHAT of ITEM, which has to be
2668    representable by a string.  Deprecated, use trust item structure
2669    directly.  */
2670 const char *gpgme_trust_item_get_string_attr (gpgme_trust_item_t item,
2671                                               _gpgme_attr_t what,
2672                                               const void *reserved, int idx)
2673      _GPGME_DEPRECATED(0,4);
2674
2675 /* Return the value of the attribute WHAT of KEY, which has to be
2676    representable by an integer.  IDX specifies a running index if the
2677    attribute appears more than once in the key.  Deprecated, use trust
2678    item structure directly.  */
2679 int gpgme_trust_item_get_int_attr (gpgme_trust_item_t item, _gpgme_attr_t what,
2680                                    const void *reserved, int idx)
2681      _GPGME_DEPRECATED(0,4);
2682
2683 /* Compat.
2684  * This structure shall be considered read-only and an application
2685  * must not allocate such a structure on its own.  */
2686 struct _gpgme_op_assuan_result
2687 {
2688   /* Deprecated.  Use the second value in a DONE event or the
2689      synchronous variant gpgme_op_assuan_transact_ext.  */
2690   gpgme_error_t err _GPGME_DEPRECATED_OUTSIDE_GPGME(1,2);
2691 };
2692 typedef struct _gpgme_op_assuan_result *gpgme_assuan_result_t;
2693
2694
2695 /* Return the result of the last Assuan command. */
2696 gpgme_assuan_result_t gpgme_op_assuan_result (gpgme_ctx_t ctx)
2697   _GPGME_DEPRECATED(1,2);
2698
2699 gpgme_error_t
2700 gpgme_op_assuan_transact (gpgme_ctx_t ctx,
2701                               const char *command,
2702                               gpgme_assuan_data_cb_t data_cb,
2703                               void *data_cb_value,
2704                               gpgme_assuan_inquire_cb_t inq_cb,
2705                               void *inq_cb_value,
2706                               gpgme_assuan_status_cb_t status_cb,
2707                           void *status_cb_value) _GPGME_DEPRECATED(1,2);
2708
2709
2710
2711 typedef gpgme_ctx_t GpgmeCtx _GPGME_DEPRECATED(0,4);
2712 typedef gpgme_data_t GpgmeData _GPGME_DEPRECATED(0,4);
2713 typedef gpgme_error_t GpgmeError _GPGME_DEPRECATED(0,4);
2714 typedef gpgme_data_encoding_t GpgmeDataEncoding _GPGME_DEPRECATED(0,4);
2715 typedef gpgme_pubkey_algo_t GpgmePubKeyAlgo _GPGME_DEPRECATED(0,4);
2716 typedef gpgme_hash_algo_t GpgmeHashAlgo _GPGME_DEPRECATED(0,4);
2717 typedef gpgme_sig_stat_t GpgmeSigStat _GPGME_DEPRECATED(0,4);
2718 typedef gpgme_sig_mode_t GpgmeSigMode _GPGME_DEPRECATED(0,4);
2719 typedef gpgme_attr_t GpgmeAttr _GPGME_DEPRECATED(0,4);
2720 typedef gpgme_validity_t GpgmeValidity _GPGME_DEPRECATED(0,4);
2721 typedef gpgme_protocol_t GpgmeProtocol _GPGME_DEPRECATED(0,4);
2722 typedef gpgme_engine_info_t GpgmeEngineInfo _GPGME_DEPRECATED(0,4);
2723 typedef gpgme_subkey_t GpgmeSubkey _GPGME_DEPRECATED(0,4);
2724 typedef gpgme_key_sig_t GpgmeKeySig _GPGME_DEPRECATED(0,4);
2725 typedef gpgme_user_id_t GpgmeUserID _GPGME_DEPRECATED(0,4);
2726 typedef gpgme_key_t GpgmeKey _GPGME_DEPRECATED(0,4);
2727 typedef gpgme_passphrase_cb_t GpgmePassphraseCb _GPGME_DEPRECATED(0,4);
2728 typedef gpgme_progress_cb_t GpgmeProgressCb _GPGME_DEPRECATED(0,4);
2729 typedef gpgme_io_cb_t GpgmeIOCb _GPGME_DEPRECATED(0,4);
2730 typedef gpgme_register_io_cb_t GpgmeRegisterIOCb _GPGME_DEPRECATED(0,4);
2731 typedef gpgme_remove_io_cb_t GpgmeRemoveIOCb _GPGME_DEPRECATED(0,4);
2732 typedef gpgme_event_io_t GpgmeEventIO _GPGME_DEPRECATED(0,4);
2733 typedef gpgme_event_io_cb_t GpgmeEventIOCb _GPGME_DEPRECATED(0,4);
2734 #define GpgmeIOCbs gpgme_io_cbs
2735 typedef gpgme_data_read_cb_t GpgmeDataReadCb _GPGME_DEPRECATED(0,4);
2736 typedef gpgme_data_write_cb_t GpgmeDataWriteCb _GPGME_DEPRECATED(0,4);
2737 typedef gpgme_data_seek_cb_t GpgmeDataSeekCb _GPGME_DEPRECATED(0,4);
2738 typedef gpgme_data_release_cb_t GpgmeDataReleaseCb _GPGME_DEPRECATED(0,4);
2739 #define GpgmeDataCbs gpgme_data_cbs
2740 typedef gpgme_encrypt_result_t GpgmeEncryptResult _GPGME_DEPRECATED(0,4);
2741 typedef gpgme_sig_notation_t GpgmeSigNotation _GPGME_DEPRECATED(0,4);
2742 typedef gpgme_signature_t GpgmeSignature _GPGME_DEPRECATED(0,4);
2743 typedef gpgme_verify_result_t GpgmeVerifyResult _GPGME_DEPRECATED(0,4);
2744 typedef gpgme_import_status_t GpgmeImportStatus _GPGME_DEPRECATED(0,4);
2745 typedef gpgme_import_result_t GpgmeImportResult _GPGME_DEPRECATED(0,4);
2746 typedef gpgme_genkey_result_t GpgmeGenKeyResult _GPGME_DEPRECATED(0,4);
2747 typedef gpgme_trust_item_t GpgmeTrustItem _GPGME_DEPRECATED(0,4);
2748 typedef gpgme_status_code_t GpgmeStatusCode _GPGME_DEPRECATED(0,4);
2749
2750 #ifdef __cplusplus
2751 }
2752 #endif
2753 #endif /* GPGME_H */
2754 /*
2755 @emacs_local_vars_begin@
2756 @emacs_local_vars_read_only@
2757 @emacs_local_vars_end@
2758 */