gpgme/gpgme.h

   1 /* gpgme.h - Public interface to GnuPG Made Easy.
   2    Copyright (C) 2000 Werner Koch (dd9jn)
   3    Copyright (C) 2001, 2002, 2003 g10 Code GmbH
   4
   5    This file is part of GPGME.
   6
   7    GPGME is free software; you can redistribute it and/or modify it
   8    under the terms of the GNU General Public License as published by
   9    the Free Software Foundation; either version 2 of the License, or
  10    (at your option) any later version.
  11
  12    GPGME is distributed in the hope that it will be useful, but
  13    WITHOUT ANY WARRANTY; without even the implied warranty of
  14    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15    General Public License for more details.
  16
  17    You should have received a copy of the GNU General Public License
  18    along with GPGME; if not, write to the Free Software Foundation,
  19    Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.  */
  20
  21 #ifndef GPGME_H
  22 #define GPGME_H
  23
  24 #include <stdio.h> /* For FILE *.  */
  25 #ifdef _MSC_VER
  26   typedef long off_t;
  27   typedef long ssize_t;
  28 #else
  29 # include <sys/types.h>
  30 #endif
  31
  32 #ifdef __cplusplus
  33 extern "C" {
  34 #if 0 /* just to make Emacs auto-indent happy */
  35 }
  36 #endif
  37 #endif
  38
  39
  40 /* The version of this header should match the one of the library.  Do
  41    not use this symbol in your application, use gpgme_check_version
  42    instead.  The purpose of this macro is to let autoconf (using the
  43    AM_PATH_GPGME macro) check that this header matches the installed
  44    library.  Warning: Do not edit the next line.  configure will do
  45    that for you!  */
  46 #define GPGME_VERSION "0.4.1"
  47
  48
  49 /* The opaque data types used by GPGME.  */
  50
  51 /* The context holds some global state and configration options as
  52    well as the results of a crypto operation.  */
  53 struct gpgme_context_s;
  54 typedef struct gpgme_context_s *GpgmeCtx;
  55
  56 /* The data object used by GPGME to exchange arbitrary data.  */
  57 struct gpgme_data_s;
  58 typedef struct gpgme_data_s *GpgmeData;
  59
  60 /* A list of recipients to be used in an encryption operation.  */
  61 struct gpgme_recipients_s;
  62 typedef struct gpgme_recipients_s *GpgmeRecipients;
  63
  64 /* A key from the keyring.  */
  65 struct gpgme_key_s;
  66 typedef struct gpgme_key_s *GpgmeKey;
  67
  68 /* A trust item.  */
  69 struct gpgme_trust_item_s;
  70 typedef struct gpgme_trust_item_s *GpgmeTrustItem;
  71
  72
  73 /* The error numbers used by GPGME.  */
  74 typedef enum
  75   {
  76     GPGME_EOF                     = -1,
  77     GPGME_No_Error                = 0x0000,
  78     GPGME_General_Error           = 0x0001,
  79     GPGME_Out_Of_Core             = 0x0002,
  80     GPGME_Invalid_Value           = 0x0003,
  81     GPGME_No_Request              = 0x0004,
  82     GPGME_Exec_Error              = 0x0005,
  83     GPGME_Too_Many_Procs          = 0x0006,
  84     GPGME_Pipe_Error              = 0x0007,
  85     GPGME_No_Data                 = 0x0008,
  86     GPGME_Conflict                = 0x0009,
  87     GPGME_Not_Implemented         = 0x000a,
  88     GPGME_Read_Error              = 0x000b,
  89     GPGME_Write_Error             = 0x000c,
  90     GPGME_Invalid_Type            = 0x000d,
  91     GPGME_Invalid_Mode            = 0x000e,
  92     GPGME_File_Error              = 0x000f, /* errno is set in this case.  */
  93     GPGME_Decryption_Failed       = 0x0010,
  94     GPGME_Bad_Passphrase          = 0x0011,
  95     GPGME_Canceled                = 0x0012,
  96     GPGME_Invalid_Key             = 0x0013,
  97     GPGME_Invalid_Engine          = 0x0014,
  98     GPGME_No_UserID               = 0x0015,
  99     GPGME_Invalid_UserID          = 0x0016,
 100   }
 101 GpgmeError;
 102
 103 /* The possible types of GpgmeData objects.  */
 104 typedef enum
 105   {
 106     GPGME_DATA_TYPE_NONE = 0,
 107     GPGME_DATA_TYPE_MEM  = 1,
 108     GPGME_DATA_TYPE_FD   = 2,
 109     GPGME_DATA_TYPE_FILE = 3,
 110     GPGME_DATA_TYPE_CB   = 4
 111   }
 112 GpgmeDataType;
 113
 114 /* The possible encoding mode of GpgmeData objects.  */
 115 typedef enum
 116   {
 117     GPGME_DATA_ENCODING_NONE   = 0,     /* I.e. not specified.  */
 118     GPGME_DATA_ENCODING_BINARY = 1,
 119     GPGME_DATA_ENCODING_BASE64 = 2,
 120     GPGME_DATA_ENCODING_ARMOR  = 3      /* Either PEM or OpenPGP Armor.  */
 121   }
 122 GpgmeDataEncoding;
 123
 124 /* The possible signature stati.  */
 125 typedef enum
 126   {
 127     GPGME_SIG_STAT_NONE  = 0,
 128     GPGME_SIG_STAT_GOOD  = 1,
 129     GPGME_SIG_STAT_BAD   = 2,
 130     GPGME_SIG_STAT_NOKEY = 3,
 131     GPGME_SIG_STAT_NOSIG = 4,
 132     GPGME_SIG_STAT_ERROR = 5,
 133     GPGME_SIG_STAT_DIFF  = 6,
 134     GPGME_SIG_STAT_GOOD_EXP = 7,
 135     GPGME_SIG_STAT_GOOD_EXPKEY = 8
 136   }
 137 GpgmeSigStat;
 138
 139 /* Flags used with the GPGME_ATTR_SIG_SUMMARY.  */
 140 enum
 141   {
 142     GPGME_SIGSUM_VALID       = 0x0001,  /* The signature is fully valid.  */
 143     GPGME_SIGSUM_GREEN       = 0x0002,  /* The signature is good.  */
 144     GPGME_SIGSUM_RED         = 0x0004,  /* The signature is bad.  */
 145     GPGME_SIGSUM_KEY_REVOKED = 0x0010,  /* One key has been revoked.  */
 146     GPGME_SIGSUM_KEY_EXPIRED = 0x0020,  /* One key has expired.  */
 147     GPGME_SIGSUM_SIG_EXPIRED = 0x0040,  /* The signature has expired.  */
 148     GPGME_SIGSUM_KEY_MISSING = 0x0080,  /* Can't verify: key missing.  */
 149     GPGME_SIGSUM_CRL_MISSING = 0x0100,  /* CRL not available.  */
 150     GPGME_SIGSUM_CRL_TOO_OLD = 0x0200,  /* Available CRL is too old.  */
 151     GPGME_SIGSUM_BAD_POLICY  = 0x0400,  /* A policy was not met.  */
 152     GPGME_SIGSUM_SYS_ERROR   = 0x0800   /* A system error occured.  */
 153   };
 154
 155
 156 /* The available signature modes.  */
 157 typedef enum
 158   {
 159     GPGME_SIG_MODE_NORMAL = 0,
 160     GPGME_SIG_MODE_DETACH = 1,
 161     GPGME_SIG_MODE_CLEAR  = 2
 162   }
 163 GpgmeSigMode;
 164
 165 /* The available key and signature attributes.  */
 166 typedef enum
 167   {
 168     GPGME_ATTR_KEYID        = 1,
 169     GPGME_ATTR_FPR          = 2,
 170     GPGME_ATTR_ALGO         = 3,
 171     GPGME_ATTR_LEN          = 4,
 172     GPGME_ATTR_CREATED      = 5,
 173     GPGME_ATTR_EXPIRE       = 6,
 174     GPGME_ATTR_OTRUST       = 7,
 175     GPGME_ATTR_USERID       = 8,
 176     GPGME_ATTR_NAME         = 9,
 177     GPGME_ATTR_EMAIL        = 10,
 178     GPGME_ATTR_COMMENT      = 11,
 179     GPGME_ATTR_VALIDITY     = 12,
 180     GPGME_ATTR_LEVEL        = 13,
 181     GPGME_ATTR_TYPE         = 14,
 182     GPGME_ATTR_IS_SECRET    = 15,
 183     GPGME_ATTR_KEY_REVOKED  = 16,
 184     GPGME_ATTR_KEY_INVALID  = 17,
 185     GPGME_ATTR_UID_REVOKED  = 18,
 186     GPGME_ATTR_UID_INVALID  = 19,
 187     GPGME_ATTR_KEY_CAPS     = 20,
 188     GPGME_ATTR_CAN_ENCRYPT  = 21,
 189     GPGME_ATTR_CAN_SIGN     = 22,
 190     GPGME_ATTR_CAN_CERTIFY  = 23,
 191     GPGME_ATTR_KEY_EXPIRED  = 24,
 192     GPGME_ATTR_KEY_DISABLED = 25,
 193     GPGME_ATTR_SERIAL       = 26,
 194     GPGME_ATTR_ISSUER       = 27,
 195     GPGME_ATTR_CHAINID      = 28,
 196     GPGME_ATTR_SIG_STATUS   = 29,
 197     GPGME_ATTR_ERRTOK       = 30,
 198     GPGME_ATTR_SIG_SUMMARY  = 31,
 199     GPGME_ATTR_SIG_CLASS    = 32
 200   }
 201 GpgmeAttr;
 202
 203 /* The available validities for a trust item or key.  */
 204 typedef enum
 205   {
 206     GPGME_VALIDITY_UNKNOWN   = 0,
 207     GPGME_VALIDITY_UNDEFINED = 1,
 208     GPGME_VALIDITY_NEVER     = 2,
 209     GPGME_VALIDITY_MARGINAL  = 3,
 210     GPGME_VALIDITY_FULL      = 4,
 211     GPGME_VALIDITY_ULTIMATE  = 5
 212   }
 213 GpgmeValidity;
 214
 215 /* The available protocols.  */
 216 typedef enum
 217   {
 218     GPGME_PROTOCOL_OpenPGP = 0,  /* The default mode.  */
 219     GPGME_PROTOCOL_CMS     = 1,
 220   }
 221 GpgmeProtocol;
 222
 223 \f
 224 /* The possible stati for the edit operation.  */
 225 typedef enum
 226   {
 227     GPGME_STATUS_EOF,
 228     /* mkstatus processing starts here */
 229     GPGME_STATUS_ENTER,
 230     GPGME_STATUS_LEAVE,
 231     GPGME_STATUS_ABORT,
 232
 233     GPGME_STATUS_GOODSIG,
 234     GPGME_STATUS_BADSIG,
 235     GPGME_STATUS_ERRSIG,
 236
 237     GPGME_STATUS_BADARMOR,
 238
 239     GPGME_STATUS_RSA_OR_IDEA,
 240     GPGME_STATUS_KEYEXPIRED,
 241     GPGME_STATUS_KEYREVOKED,
 242
 243     GPGME_STATUS_TRUST_UNDEFINED,
 244     GPGME_STATUS_TRUST_NEVER,
 245     GPGME_STATUS_TRUST_MARGINAL,
 246     GPGME_STATUS_TRUST_FULLY,
 247     GPGME_STATUS_TRUST_ULTIMATE,
 248
 249     GPGME_STATUS_SHM_INFO,
 250     GPGME_STATUS_SHM_GET,
 251     GPGME_STATUS_SHM_GET_BOOL,
 252     GPGME_STATUS_SHM_GET_HIDDEN,
 253
 254     GPGME_STATUS_NEED_PASSPHRASE,
 255     GPGME_STATUS_VALIDSIG,
 256     GPGME_STATUS_SIG_ID,
 257     GPGME_STATUS_ENC_TO,
 258     GPGME_STATUS_NODATA,
 259     GPGME_STATUS_BAD_PASSPHRASE,
 260     GPGME_STATUS_NO_PUBKEY,
 261     GPGME_STATUS_NO_SECKEY,
 262     GPGME_STATUS_NEED_PASSPHRASE_SYM,
 263     GPGME_STATUS_DECRYPTION_FAILED,
 264     GPGME_STATUS_DECRYPTION_OKAY,
 265     GPGME_STATUS_MISSING_PASSPHRASE,
 266     GPGME_STATUS_GOOD_PASSPHRASE,
 267     GPGME_STATUS_GOODMDC,
 268     GPGME_STATUS_BADMDC,
 269     GPGME_STATUS_ERRMDC,
 270     GPGME_STATUS_IMPORTED,
 271     GPGME_STATUS_IMPORT_OK,
 272     GPGME_STATUS_IMPORT_PROBLEM,
 273     GPGME_STATUS_IMPORT_RES,
 274     GPGME_STATUS_FILE_START,
 275     GPGME_STATUS_FILE_DONE,
 276     GPGME_STATUS_FILE_ERROR,
 277
 278     GPGME_STATUS_BEGIN_DECRYPTION,
 279     GPGME_STATUS_END_DECRYPTION,
 280     GPGME_STATUS_BEGIN_ENCRYPTION,
 281     GPGME_STATUS_END_ENCRYPTION,
 282
 283     GPGME_STATUS_DELETE_PROBLEM,
 284     GPGME_STATUS_GET_BOOL,
 285     GPGME_STATUS_GET_LINE,
 286     GPGME_STATUS_GET_HIDDEN,
 287     GPGME_STATUS_GOT_IT,
 288     GPGME_STATUS_PROGRESS,
 289     GPGME_STATUS_SIG_CREATED,
 290     GPGME_STATUS_SESSION_KEY,
 291     GPGME_STATUS_NOTATION_NAME,
 292     GPGME_STATUS_NOTATION_DATA,
 293     GPGME_STATUS_POLICY_URL,
 294     GPGME_STATUS_BEGIN_STREAM,
 295     GPGME_STATUS_END_STREAM,
 296     GPGME_STATUS_KEY_CREATED,
 297     GPGME_STATUS_USERID_HINT,
 298     GPGME_STATUS_UNEXPECTED,
 299     GPGME_STATUS_INV_RECP,
 300     GPGME_STATUS_NO_RECP,
 301     GPGME_STATUS_ALREADY_SIGNED,
 302     GPGME_STATUS_SIGEXPIRED,
 303     GPGME_STATUS_EXPSIG,
 304     GPGME_STATUS_EXPKEYSIG,
 305     GPGME_STATUS_TRUNCATED,
 306     GPGME_STATUS_ERROR
 307   }
 308 GpgmeStatusCode;
 309
 310 /* The available keylist mode flags.  */
 311 #define GPGME_KEYLIST_MODE_LOCAL  1
 312 #define GPGME_KEYLIST_MODE_EXTERN 2
 313 #define GPGME_KEYLIST_MODE_SIGS   4
 314
 315 /* The engine information structure.  */
 316 struct _gpgme_engine_info
 317 {
 318   struct _gpgme_engine_info *next;
 319
 320   /* The protocol ID.  */
 321   GpgmeProtocol protocol;
 322
 323   /* The file name of the engine binary.  */
 324   const char *file_name;
 325
 326   /* The version string of the installed engine.  */
 327   const char *version;
 328
 329   /* The minimum version required for GPGME.  */
 330   const char *req_version;
 331 };
 332 typedef struct _gpgme_engine_info *GpgmeEngineInfo;
 333
 334
 335 /* Types for callback functions.  */
 336
 337 /* Request a passphrase from the user.  */
 338 typedef GpgmeError (*GpgmePassphraseCb) (void *hook, const char *desc,
 339                                          void **r_hd, const char **result);
 340
 341 /* Inform the user about progress made.  */
 342 typedef void (*GpgmeProgressCb) (void *opaque, const char *what,
 343                                  int type, int current, int total);
 344
 345 /* Interact with the user about an edit operation.  */
 346 typedef GpgmeError (*GpgmeEditCb) (void *opaque, GpgmeStatusCode status,
 347                                    const char *args, const char **reply);
 348
 349 /* Context management functions.  */
 350
 351 /* Create a new context and return it in CTX.  */
 352 GpgmeError gpgme_new (GpgmeCtx *ctx);
 353
 354 /* Release the context CTX.  */
 355 void gpgme_release (GpgmeCtx ctx);
 356
 357 /* Retrieve more info about performed signature check.  */
 358 char *gpgme_get_notation (GpgmeCtx ctx);
 359
 360 /* Set the protocol to be used by CTX to PROTO.  */
 361 GpgmeError gpgme_set_protocol (GpgmeCtx ctx, GpgmeProtocol proto);
 362
 363 /* Get the protocol used with CTX */
 364 GpgmeProtocol gpgme_get_protocol (GpgmeCtx ctx);
 365
 366 /* Get the string describing protocol PROTO, or NULL if invalid.  */
 367 const char *gpgme_get_protocol_name (GpgmeProtocol proto);
 368
 369 /* If YES is non-zero, enable armor mode in CTX, disable it otherwise.  */
 370 void gpgme_set_armor (GpgmeCtx ctx, int yes);
 371
 372 /* Return non-zero if armor mode is set in CTX.  */
 373 int gpgme_get_armor (GpgmeCtx ctx);
 374
 375 /* If YES is non-zero, enable text mode in CTX, disable it otherwise.  */
 376 void gpgme_set_textmode (GpgmeCtx ctx, int yes);
 377
 378 /* Return non-zero if text mode is set in CTX.  */
 379 int gpgme_get_textmode (GpgmeCtx ctx);
 380
 381 /* Include up to NR_OF_CERTS certificates in an S/MIME message.  */
 382 void gpgme_set_include_certs (GpgmeCtx ctx, int nr_of_certs);
 383
 384 /* Return the number of certs to include in an S/MIME message.  */
 385 int gpgme_get_include_certs (GpgmeCtx ctx);
 386
 387 /* Set keylist mode in CTX to MODE.  */
 388 GpgmeError gpgme_set_keylist_mode (GpgmeCtx ctx, int mode);
 389
 390 /* Get keylist mode in CTX.  */
 391 int gpgme_get_keylist_mode (GpgmeCtx ctx);
 392
 393 /* Set the passphrase callback function in CTX to CB.  HOOK_VALUE is
 394    passed as first argument to the passphrase callback function.  */
 395 void gpgme_set_passphrase_cb (GpgmeCtx ctx,
 396                               GpgmePassphraseCb cb, void *hook_value);
 397
 398 /* Get the current passphrase callback function in *CB and the current
 399    hook value in *HOOK_VALUE.  */
 400 void gpgme_get_passphrase_cb (GpgmeCtx ctx, GpgmePassphraseCb *cb,
 401                               void **hook_value);
 402
 403 /* Set the progress callback function in CTX to CB.  HOOK_VALUE is
 404    passed as first argument to the progress callback function.  */
 405 void gpgme_set_progress_cb (GpgmeCtx c, GpgmeProgressCb cb, void *hook_value);
 406
 407 /* Get the current progress callback function in *CB and the current
 408    hook value in *HOOK_VALUE.  */
 409 void gpgme_get_progress_cb (GpgmeCtx ctx, GpgmeProgressCb *cb,
 410                             void **hook_value);
 411
 412 /* Delete all signers from CTX.  */
 413 void gpgme_signers_clear (GpgmeCtx ctx);
 414
 415 /* Add KEY to list of signers in CTX.  */
 416 GpgmeError gpgme_signers_add (GpgmeCtx ctx, const GpgmeKey key);
 417
 418 /* Return the SEQth signer's key in CTX.  */
 419 GpgmeKey gpgme_signers_enum (const GpgmeCtx ctx, int seq);
 420
 421 /* Retrieve the signature status of signature IDX in CTX after a
 422    successful verify operation in R_STAT (if non-null).  The creation
 423    time stamp of the signature is returned in R_CREATED (if non-null).
 424    The function returns a string containing the fingerprint.  */
 425 const char *gpgme_get_sig_status (GpgmeCtx ctx, int idx,
 426                                   GpgmeSigStat *r_stat, time_t *r_created);
 427
 428 /* Retrieve certain attributes of a signature.  IDX is the index
 429    number of the signature after a successful verify operation.  WHAT
 430    is an attribute where GPGME_ATTR_EXPIRE is probably the most useful
 431    one.  WHATIDX is to be passed as 0 for most attributes . */
 432 unsigned long gpgme_get_sig_ulong_attr (GpgmeCtx c, int idx,
 433                                         GpgmeAttr what, int whatidx);
 434 const char *gpgme_get_sig_string_attr (GpgmeCtx c, int idx,
 435                                       GpgmeAttr what, int whatidx);
 436
 437
 438 /* Get the key used to create signature IDX in CTX and return it in
 439    R_KEY.  */
 440 GpgmeError gpgme_get_sig_key (GpgmeCtx ctx, int idx, GpgmeKey *r_key);
 441
 442 /* Return a string with more info about the last crypto operating in CTX.
 443    RESERVED should be zero.  The user has to free the string.  */
 444 char *gpgme_get_op_info (GpgmeCtx ctx, int reserved);
 445
 446
 447 /* Run control.  */
 448
 449 /* The type of an I/O callback function.  */
 450 typedef GpgmeError (*GpgmeIOCb) (void *data, int fd);
 451
 452 /* The type of a function that can register FNC as the I/O callback
 453    function for the file descriptor FD with direction dir (0: for writing,
 454    1: for reading).  FNC_DATA should be passed as DATA to FNC.  The
 455    function should return a TAG suitable for the corresponding
 456    GpgmeRemoveIOCb, and an error value.  */
 457 typedef GpgmeError (*GpgmeRegisterIOCb) (void *data, int fd, int dir,
 458                                          GpgmeIOCb fnc, void *fnc_data,
 459                                          void **tag);
 460
 461 /* The type of a function that can remove a previously registered I/O
 462    callback function given TAG as returned by the register
 463    function.  */
 464 typedef void (*GpgmeRemoveIOCb) (void *tag);
 465
 466 typedef enum { GPGME_EVENT_START,
 467                GPGME_EVENT_DONE,
 468                GPGME_EVENT_NEXT_KEY,
 469                GPGME_EVENT_NEXT_TRUSTITEM } GpgmeEventIO;
 470
 471 /* The type of a function that is called when a context finished an
 472    operation.  */
 473 typedef void (*GpgmeEventIOCb) (void *data, GpgmeEventIO type,
 474                                 void *type_data);
 475
 476 struct GpgmeIOCbs
 477 {
 478   GpgmeRegisterIOCb add;
 479   void *add_priv;
 480   GpgmeRemoveIOCb remove;
 481   GpgmeEventIOCb event;
 482   void *event_priv;
 483 };
 484
 485 /* Set the I/O callback functions in CTX to IO_CBS.  */
 486 void gpgme_set_io_cbs (GpgmeCtx ctx, struct GpgmeIOCbs *io_cbs);
 487
 488 /* Get the current I/O callback functions.  */
 489 void gpgme_get_io_cbs (GpgmeCtx ctx, struct GpgmeIOCbs *io_cbs);
 490
 491 /* Process the pending operation and, if HANG is non-zero, wait for
 492    the pending operation to finish.  */
 493 GpgmeCtx gpgme_wait (GpgmeCtx ctx, GpgmeError *status, int hang);
 494
 495
 496 /* Functions to handle recipients.  */
 497
 498 /* Create a new recipients set and return it in R_RSET.  */
 499 GpgmeError gpgme_recipients_new (GpgmeRecipients *r_rset);
 500
 501 /* Release the recipients set RSET.  */
 502 void gpgme_recipients_release (GpgmeRecipients rset);
 503
 504 /* Add NAME to the recipients set RSET.  */
 505 GpgmeError gpgme_recipients_add_name (GpgmeRecipients rset, const char *name);
 506
 507 /* Add NAME with validity AL to the recipients set RSET.  */
 508 GpgmeError gpgme_recipients_add_name_with_validity (GpgmeRecipients rset,
 509                                                     const char *name,
 510                                                     GpgmeValidity val);
 511
 512 /* Return the number of recipients in RSET.  */
 513 unsigned int gpgme_recipients_count (const GpgmeRecipients rset);
 514
 515 /* Create a new enumeration handle for the recipients set RSET and
 516    return it in ITER.  */
 517 GpgmeError gpgme_recipients_enum_open (const GpgmeRecipients rset,
 518                                        void **iter);
 519
 520 /* Return the next recipient from the recipient set RSET in the
 521    enumerator ITER.  */
 522 const char *gpgme_recipients_enum_read (const GpgmeRecipients rset,
 523                                         void **iter);
 524
 525 /* Destroy the enumerator ITER for the recipient set RSET.  */
 526 GpgmeError gpgme_recipients_enum_close (const GpgmeRecipients rset,
 527                                         void **iter);
 528
 529
 530 /* Functions to handle data objects.  */
 531
 532 /* Read up to SIZE bytes into buffer BUFFER from the data object with
 533    the handle HANDLE.  Return the number of characters read, 0 on EOF
 534    and -1 on error.  If an error occurs, errno is set.  */
 535 typedef ssize_t (*GpgmeDataReadCb) (void *handle, void *buffer, size_t size);
 536
 537 /* Write up to SIZE bytes from buffer BUFFER to the data object with
 538    the handle HANDLE.  Return the number of characters written, or -1
 539    on error.  If an error occurs, errno is set.  */
 540 typedef ssize_t (*GpgmeDataWriteCb) (void *handle, const void *buffer,
 541                                      size_t size);
 542
 543 /* Set the current position from where the next read or write starts
 544    in the data object with the handle HANDLE to OFFSET, relativ to
 545    WHENCE.  */
 546 typedef off_t (*GpgmeDataSeekCb) (void *handle, off_t offset, int whence);
 547
 548 /* Close the data object with the handle DL.  */
 549 typedef void (*GpgmeDataReleaseCb) (void *handle);
 550
 551 struct GpgmeDataCbs
 552 {
 553   GpgmeDataReadCb read;
 554   GpgmeDataWriteCb write;
 555   GpgmeDataSeekCb seek;
 556   GpgmeDataReleaseCb release;
 557 };
 558
 559 /* Read up to SIZE bytes into buffer BUFFER from the data object with
 560    the handle DH.  Return the number of characters read, 0 on EOF and
 561    -1 on error.  If an error occurs, errno is set.  */
 562 ssize_t gpgme_data_read (GpgmeData dh, void *buffer, size_t size);
 563
 564 /* Write up to SIZE bytes from buffer BUFFER to the data object with
 565    the handle DH.  Return the number of characters written, or -1 on
 566    error.  If an error occurs, errno is set.  */
 567 ssize_t gpgme_data_write (GpgmeData dh, const void *buffer, size_t size);
 568
 569 /* Set the current position from where the next read or write starts
 570    in the data object with the handle DH to OFFSET, relativ to
 571    WHENCE.  */
 572 off_t gpgme_data_seek (GpgmeData dh, off_t offset, int whence);
 573
 574 /* Create a new data buffer and return it in R_DH.  */
 575 GpgmeError gpgme_data_new (GpgmeData *r_dh);
 576
 577 /* Destroy the data buffer DH.  */
 578 void gpgme_data_release (GpgmeData dh);
 579
 580 /* Create a new data buffer filled with SIZE bytes starting from
 581    BUFFER.  If COPY is zero, copying is delayed until necessary, and
 582    the data is taken from the original location when needed.  */
 583 GpgmeError gpgme_data_new_from_mem (GpgmeData *r_dh,
 584                                     const char *buffer, size_t size,
 585                                     int copy);
 586
 587 /* Destroy the data buffer DH and return a pointer to its content.
 588    The memory has be to released with free by the user.  It's size is
 589    returned in R_LEN.  */
 590 char *gpgme_data_release_and_get_mem (GpgmeData dh, size_t *r_len);
 591
 592 GpgmeError gpgme_data_new_from_cbs (GpgmeData *dh,
 593                                     struct GpgmeDataCbs *cbs,
 594                                     void *handle);
 595
 596 GpgmeError gpgme_data_new_from_fd (GpgmeData *dh, int fd);
 597
 598 GpgmeError gpgme_data_new_from_stream (GpgmeData *dh, FILE *stream);
 599
 600 /* Return the encoding attribute of the data buffer DH */
 601 GpgmeDataEncoding gpgme_data_get_encoding (GpgmeData dh);
 602
 603 /* Set the encoding attribute of data buffer DH to ENC */
 604 GpgmeError gpgme_data_set_encoding (GpgmeData dh, GpgmeDataEncoding enc);
 605
 606
 607
 608 /* Create a new data buffer which retrieves the data from the callback
 609    function READ_CB.  Deprecated, please use gpgme_data_new_from_cbs
 610    instead.  */
 611 GpgmeError gpgme_data_new_with_read_cb (GpgmeData *r_dh,
 612                                         int (*read_cb) (void*,char *,size_t,size_t*),
 613                                         void *read_cb_value);
 614
 615 /* Create a new data buffer filled with the content of file FNAME.
 616    COPY must be non-zero.  For delayed read, please use
 617    gpgme_data_new_from_fd or gpgme_data_new_from stream instead.  */
 618 GpgmeError gpgme_data_new_from_file (GpgmeData *r_dh,
 619                                      const char *fname,
 620                                      int copy);
 621
 622 /* Create a new data buffer filled with LENGTH bytes starting from
 623    OFFSET within the file FNAME or stream FP (exactly one must be
 624    non-zero).  */
 625 GpgmeError gpgme_data_new_from_filepart (GpgmeData *r_dh,
 626                                          const char *fname, FILE *fp,
 627                                          off_t offset, size_t length);
 628
 629 /* Reset the read pointer in DH.  Deprecated, please use
 630    gpgme_data_seek instead.  */
 631 GpgmeError gpgme_data_rewind (GpgmeData dh);
 632
 633
 634 /* Key and trust functions.  */
 635
 636 /* Get the key with the fingerprint FPR from the key cache or from the
 637    crypto backend.  If FORCE_UPDATE is true, force a refresh of the
 638    key from the crypto backend and replace the key in the cache, if
 639    any.  If SECRET is true, get the secret key.  */
 640 GpgmeError gpgme_get_key (GpgmeCtx ctx, const char *fpr, GpgmeKey *r_key,
 641                           int secret, int force_update);
 642
 643 /* Acquire a reference to KEY.  */
 644 void gpgme_key_ref (GpgmeKey key);
 645
 646 /* Release a reference to KEY.  If this was the last one the key is
 647    destroyed.  */
 648 void gpgme_key_unref (GpgmeKey key);
 649 void gpgme_key_release (GpgmeKey key);
 650
 651 /* Get the data from key KEY in a XML string, which has to be released
 652    with free by the user.  */
 653 char *gpgme_key_get_as_xml (GpgmeKey key);
 654
 655 /* Return the value of the attribute WHAT of KEY, which has to be
 656    representable by a string.  IDX specifies the sub key or
 657    user ID for attributes related to sub keys or user IDs.  */
 658 const char *gpgme_key_get_string_attr (GpgmeKey key, GpgmeAttr what,
 659                                        const void *reserved, int idx);
 660
 661 /* Return the value of the attribute WHAT of KEY, which has to be
 662    representable by an unsigned integer.  IDX specifies the sub key or
 663    user ID for attributes related to sub keys or user IDs.  */
 664 unsigned long gpgme_key_get_ulong_attr (GpgmeKey key, GpgmeAttr what,
 665                                         const void *reserved, int idx);
 666
 667 /* Return the value of the attribute WHAT of a signature on user ID
 668    UID_IDX in KEY, which has to be representable by a string.  IDX
 669    specifies the signature.  */
 670 const char *gpgme_key_sig_get_string_attr (GpgmeKey key, int uid_idx,
 671                                            GpgmeAttr what,
 672                                            const void *reserved, int idx);
 673
 674 /* Return the value of the attribute WHAT of a signature on user ID
 675    UID_IDX in KEY, which has to be representable by an unsigned
 676    integer string.  IDX specifies the signature.  */
 677 unsigned long gpgme_key_sig_get_ulong_attr (GpgmeKey key, int uid_idx,
 678                                             GpgmeAttr what,
 679                                             const void *reserved, int idx);
 680
 681
 682 /* Release the trust item ITEM.  */
 683 void gpgme_trust_item_release (GpgmeTrustItem item);
 684
 685 /* Return the value of the attribute WHAT of ITEM, which has to be
 686    representable by a string.  */
 687 const char *gpgme_trust_item_get_string_attr (GpgmeTrustItem item,
 688                                               GpgmeAttr what,
 689                                               const void *reserved, int idx);
 690
 691 /* Return the value of the attribute WHAT of KEY, which has to be
 692    representable by an integer.  IDX specifies a running index if the
 693    attribute appears more than once in the key.  */
 694 int gpgme_trust_item_get_int_attr (GpgmeTrustItem item, GpgmeAttr what,
 695                                    const void *reserved, int idx);
 696
 697
 698 /* Crypto operation function.  */
 699
 700 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
 701    store the resulting ciphertext in CIPHER.  */
 702 GpgmeError gpgme_op_encrypt_start (GpgmeCtx ctx,
 703                                    GpgmeRecipients recp,
 704                                    GpgmeData plain, GpgmeData cipher);
 705 GpgmeError gpgme_op_encrypt (GpgmeCtx ctx,
 706                              GpgmeRecipients recp,
 707                              GpgmeData plain, GpgmeData cipher);
 708
 709 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
 710    store the resulting ciphertext in CIPHER.  Also sign the ciphertext
 711    with the signers in CTX.  */
 712 GpgmeError gpgme_op_encrypt_sign_start (GpgmeCtx ctx,
 713                                         GpgmeRecipients recp,
 714                                         GpgmeData plain, GpgmeData cipher);
 715 GpgmeError gpgme_op_encrypt_sign (GpgmeCtx ctx,
 716                                   GpgmeRecipients recp,
 717                                   GpgmeData plain, GpgmeData cipher);
 718
 719 /* Decrypt ciphertext CIPHER within CTX and store the resulting
 720    plaintext in PLAIN.  */
 721 GpgmeError gpgme_op_decrypt_start (GpgmeCtx ctx,
 722                                    GpgmeData cipher, GpgmeData plain);
 723 GpgmeError gpgme_op_decrypt (GpgmeCtx ctx,
 724                              GpgmeData cipher, GpgmeData plain);
 725
 726 /* Decrypt ciphertext CIPHER and make a signature verification within
 727    CTX and store the resulting plaintext in PLAIN.  */
 728 GpgmeError gpgme_op_decrypt_verify_start (GpgmeCtx ctx,
 729                                           GpgmeData cipher, GpgmeData plain);
 730 GpgmeError gpgme_op_decrypt_verify (GpgmeCtx ctx,
 731                                     GpgmeData cipher, GpgmeData plain);
 732
 733 /* Sign the plaintext PLAIN and store the signature in SIG.  Only
 734    detached signatures are supported for now.  */
 735 GpgmeError gpgme_op_sign_start (GpgmeCtx ctx,
 736                                 GpgmeData plain, GpgmeData sig,
 737                                 GpgmeSigMode mode);
 738 GpgmeError gpgme_op_sign (GpgmeCtx ctx,
 739                           GpgmeData plain, GpgmeData sig,
 740                           GpgmeSigMode mode);
 741
 742 /* Verify within CTX that SIG is a valid signature for TEXT.  */
 743 GpgmeError gpgme_op_verify_start (GpgmeCtx ctx, GpgmeData sig,
 744                                   GpgmeData signed_text, GpgmeData plaintext);
 745 GpgmeError gpgme_op_verify (GpgmeCtx ctx, GpgmeData sig,
 746                             GpgmeData signed_text, GpgmeData plaintext);
 747
 748 /* Import the key in KEYDATA into the keyring.  */
 749 GpgmeError gpgme_op_import_start (GpgmeCtx ctx, GpgmeData keydata);
 750 GpgmeError gpgme_op_import (GpgmeCtx ctx, GpgmeData keydata);
 751 GpgmeError gpgme_op_import_ext (GpgmeCtx ctx, GpgmeData keydata, int *nr);
 752
 753 /* Export the keys listed in RECP into KEYDATA.  */
 754 GpgmeError gpgme_op_export_start (GpgmeCtx ctx, GpgmeRecipients recp,
 755                                   GpgmeData keydata);
 756 GpgmeError gpgme_op_export (GpgmeCtx ctx, GpgmeRecipients recp,
 757                             GpgmeData keydata);
 758
 759 \f
 760 /* Key generation.  */
 761 struct _gpgme_op_genkey_result
 762 {
 763   /* A primary key was generated.  */
 764   unsigned int primary : 1;
 765
 766   /* A sub key was generated.  */
 767   unsigned int sub : 1;
 768
 769   /* Internal to GPGME, do not use.  */
 770   unsigned int _unused : 30;
 771
 772   /* The fingerprint of the generated key.  */
 773   char *fpr;
 774 };
 775 typedef struct _gpgme_op_genkey_result *GpgmeGenKeyResult;
 776
 777 /* Generate a new keypair and add it to the keyring.  PUBKEY and
 778    SECKEY should be null for now.  PARMS specifies what keys should be
 779    generated.  */
 780 GpgmeError gpgme_op_genkey_start (GpgmeCtx ctx, const char *parms,
 781                                   GpgmeData pubkey, GpgmeData seckey);
 782 GpgmeError gpgme_op_genkey (GpgmeCtx ctx, const char *parms,
 783                             GpgmeData pubkey, GpgmeData seckey);
 784
 785 /* Retrieve a pointer to the result of the genkey operation.  */
 786 GpgmeGenKeyResult gpgme_op_genkey_result (GpgmeCtx ctx);
 787
 788 \f
 789 /* Delete KEY from the keyring.  If ALLOW_SECRET is non-zero, secret
 790    keys are also deleted.  */
 791 GpgmeError gpgme_op_delete_start (GpgmeCtx ctx, const GpgmeKey key,
 792                                   int allow_secret);
 793 GpgmeError gpgme_op_delete (GpgmeCtx ctx, const GpgmeKey key,
 794                             int allow_secret);
 795
 796 /* Edit the key KEY.  Send status and command requests to FNC and
 797    output of edit commands to OUT.  */
 798 GpgmeError gpgme_op_edit_start (GpgmeCtx ctx, GpgmeKey key,
 799                           GpgmeEditCb fnc, void *fnc_value,
 800                           GpgmeData out);
 801 GpgmeError gpgme_op_edit (GpgmeCtx ctx, GpgmeKey key,
 802                           GpgmeEditCb fnc, void *fnc_value,
 803                           GpgmeData out);
 804
 805 /* Key management functions */
 806
 807 /* Start a keylist operation within CTX, searching for keys which
 808    match PATTERN.  If SECRET_ONLY is true, only secret keys are
 809    returned.  */
 810 GpgmeError gpgme_op_keylist_start (GpgmeCtx ctx,
 811                                    const char *pattern, int secret_only);
 812 GpgmeError gpgme_op_keylist_ext_start (GpgmeCtx ctx, const char *pattern[],
 813                                        int secret_only, int reserved);
 814
 815 /* Return the next key from the keylist in R_KEY.  */
 816 GpgmeError gpgme_op_keylist_next (GpgmeCtx ctx, GpgmeKey *r_key);
 817
 818 /* Terminate a pending keylist operation within CTX.  */
 819 GpgmeError gpgme_op_keylist_end (GpgmeCtx ctx);
 820
 821
 822 /* Start a trustlist operation within CTX, searching for trust items
 823    which match PATTERN.  */
 824 GpgmeError gpgme_op_trustlist_start (GpgmeCtx ctx,
 825                                      const char *pattern, int max_level);
 826
 827 /* Return the next trust item from the trustlist in R_ITEM.  */
 828 GpgmeError gpgme_op_trustlist_next (GpgmeCtx ctx, GpgmeTrustItem *r_item);
 829
 830 /* Terminate a pending trustlist operation within CTX.  */
 831 GpgmeError gpgme_op_trustlist_end (GpgmeCtx ctx);
 832
 833
 834 /* Various functions.  */
 835
 836 /* Check that the library fulfills the version requirement.  */
 837 const char *gpgme_check_version (const char *req_version);
 838
 839 /* Retrieve information about the backend engines.  */
 840 GpgmeError gpgme_get_engine_info (GpgmeEngineInfo *engine_info);
 841
 842 /* Return a string describing ERR.  */
 843 const char *gpgme_strerror (GpgmeError err);
 844
 845
 846 /* Engine support functions.  */
 847
 848 /* Verify that the engine implementing PROTO is installed and
 849    available.  */
 850 GpgmeError gpgme_engine_check_version (GpgmeProtocol proto);
 851
 852
 853 #ifdef __cplusplus
 854 }
 855 #endif
 856 #endif /* GPGME_H */