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