1This is gpgme.info, produced by makeinfo version 6.5 from gpgme.texi. 2 3Copyright © 2002–2008, 2010, 2012–2018 g10 Code GmbH. 4 5 Permission is granted to copy, distribute and/or modify this 6 document under the terms of the GNU General Public License as 7 published by the Free Software Foundation; either version 3 of the 8 License, or (at your option) any later version. The text of the 9 license can be found in the section entitled “Copying”. 10 11 This document is distributed in the hope that it will be useful, but 12WITHOUT ANY WARRANTY; without even the implied warranty of 13MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General 14Public License for more details. 15INFO-DIR-SECTION GNU Libraries 16START-INFO-DIR-ENTRY 17* GPGME: (gpgme). Adding support for cryptography to your program. 18END-INFO-DIR-ENTRY 19 20 This file documents the GPGME library. 21 22 This is Edition 1.14.1-beta35, last updated 13 December 2019, of ‘The 23‘GnuPG Made Easy’ Reference Manual’, for Version 1.14.1-beta35. 24 25 Copyright © 2002–2008, 2010, 2012–2018 g10 Code GmbH. 26 27 Permission is granted to copy, distribute and/or modify this 28 document under the terms of the GNU General Public License as 29 published by the Free Software Foundation; either version 3 of the 30 License, or (at your option) any later version. The text of the 31 license can be found in the section entitled “Copying”. 32 33 This document is distributed in the hope that it will be useful, but 34WITHOUT ANY WARRANTY; without even the implied warranty of 35MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General 36Public License for more details. 37 38 39File: gpgme.info, Node: Top, Next: Introduction, Up: (dir) 40 41Main Menu 42********* 43 44This is Edition 1.14.1-beta35, last updated 13 December 2019, of ‘The 45‘GnuPG Made Easy’ Reference Manual’, for Version 1.14.1-beta35 of the 46GPGME library. 47 48* Menu: 49 50* Introduction:: How to use this manual. 51* Preparation:: What you should do before using the library. 52* Protocols and Engines:: Supported crypto protocols. 53* Algorithms:: Supported algorithms. 54* Error Handling:: Error numbers and their meanings. 55* Exchanging Data:: Passing data to and from GPGME. 56* Contexts:: Handling GPGME contexts. 57 58Appendices 59 60* UI Server Protocol:: The GnuPG UI Server Protocol. 61* Debugging:: How to solve problems. 62* Deprecated Functions:: Documentation of deprecated functions. 63 64* Library Copying:: The GNU Lesser General Public License says 65 how you can copy and share ‘GnuPG Made Easy’. 66* Copying:: The GNU General Public License says how you 67 can copy and share this manual. 68 69Indices 70 71* Concept Index:: Index of concepts and programs. 72* Function and Data Index:: Index of functions, variables and data types. 73 74 — The Detailed Node Listing — 75 76Introduction 77 78* Getting Started:: Purpose of the manual, and how to use it. 79* Features:: Reasons to install and use GPGME. 80* Overview:: Basic architecture of the GPGME library. 81 82Preparation 83 84* Header:: What header file you need to include. 85* Building the Source:: Compiler options to be used. 86* Largefile Support (LFS):: How to use GPGME with LFS. 87* Using Automake:: Compiler options to be used the easy way. 88* Using Libtool:: Avoiding compiler options entirely. 89* Library Version Check:: Getting and verifying the library version. 90* Signal Handling:: How GPGME affects signal handling. 91* Multi-Threading:: How GPGME can be used in an MT environment. 92 93Protocols and Engines 94 95* Engine Version Check:: Verifying the engine version. 96* Engine Information:: Obtaining more information about the engines. 97* Engine Configuration:: Changing the engine configuration. 98* OpenPGP:: Support for the OpenPGP protocol. 99* Cryptographic Message Syntax:: Support for the CMS. 100 101Algorithms 102 103* Public Key Algorithms:: A list of all public key algorithms. 104* Hash Algorithms:: A list of all hash algorithms. 105 106Error Handling 107 108* Error Values:: The error value and what it means. 109* Error Codes:: A list of important error codes. 110* Error Sources:: A list of important error sources. 111* Error Strings:: How to get a descriptive string from a value. 112 113Exchanging Data 114 115* Creating Data Buffers:: Creating new data buffers. 116* Destroying Data Buffers:: Releasing data buffers. 117* Manipulating Data Buffers:: Operations on data buffers. 118 119Creating Data Buffers 120 121* Memory Based Data Buffers:: Creating memory based data buffers. 122* File Based Data Buffers:: Creating file based data buffers. 123* Callback Based Data Buffers:: Creating callback based data buffers. 124 125Manipulating Data Buffers 126 127* Data Buffer I/O Operations:: I/O operations on data buffers. 128* Data Buffer Meta-Data:: Meta-data manipulation of data buffers. 129* Data Buffer Convenience:: Convenience function for data buffers. 130 131Contexts 132 133* Creating Contexts:: Creating new GPGME contexts. 134* Destroying Contexts:: Releasing GPGME contexts. 135* Result Management:: Managing the result of crypto operations. 136* Context Attributes:: Setting properties of a context. 137* Key Management:: Managing keys with GPGME. 138* Crypto Operations:: Using a context for cryptography. 139* Miscellaneous:: Miscellaneous operations. 140* Run Control:: Controlling how operations are run. 141 142Context Attributes 143 144* Protocol Selection:: Selecting the protocol used by a context. 145* Crypto Engine:: Configuring the crypto engine. 146* Setting the Sender:: How to tell the engine the sender. 147* ASCII Armor:: Requesting ASCII armored output. 148* Text Mode:: Choosing canonical text mode. 149* Offline Mode:: Choosing offline mode. 150* Included Certificates:: Including a number of certificates. 151* Key Listing Mode:: Selecting key listing mode. 152* Passphrase Callback:: Getting the passphrase from the user. 153* Progress Meter Callback:: Being informed about the progress. 154* Status Message Callback:: Status messages received from gpg. 155* Locale:: Setting the locale of a context. 156 157Key Management 158 159* Key objects:: Description of the key structures. 160* Listing Keys:: Browsing the list of available keys. 161* Information About Keys:: Requesting detailed information about keys. 162* Manipulating Keys:: Operations on keys. 163* Generating Keys:: Creating new key pairs. 164* Signing Keys:: Adding key signatures to public keys. 165* Exporting Keys:: Retrieving key data from the key ring. 166* Importing Keys:: Adding keys to the key ring. 167* Deleting Keys:: Removing keys from the key ring. 168* Changing Passphrases:: Change the passphrase of a key. 169* Changing TOFU Data:: Changing data pertaining to TOFU. 170* Advanced Key Editing:: Advanced key edit operation. 171 172Crypto Operations 173 174* Decrypt:: Decrypting a ciphertext. 175* Verify:: Verifying a signature. 176* Decrypt and Verify:: Decrypting a signed ciphertext. 177* Sign:: Creating a signature. 178* Encrypt:: Encrypting a plaintext. 179 180Sign 181 182* Selecting Signers:: How to choose the keys to sign with. 183* Creating a Signature:: How to create a signature. 184* Signature Notation Data:: How to add notation data to a signature. 185 186Encrypt 187 188* Encrypting a Plaintext:: How to encrypt a plaintext. 189 190Miscellaneous 191 192* Running other Programs:: Running other Programs. 193* Using the Assuan protocol:: Using the Assuan protocol. 194* Checking for updates:: How to check for software updates. 195 196Run Control 197 198* Waiting For Completion:: Waiting until an operation is completed. 199* Using External Event Loops:: Advanced control over what happens when. 200* Cancellation:: How to end pending operations prematurely. 201 202Using External Event Loops 203 204* I/O Callback Interface:: How I/O callbacks are registered. 205* Registering I/O Callbacks:: How to use I/O callbacks for a context. 206* I/O Callback Example:: An example how to use I/O callbacks. 207* I/O Callback Example GTK+:: How to integrate GPGME in GTK+. 208* I/O Callback Example GDK:: How to integrate GPGME in GDK. 209* I/O Callback Example Qt:: How to integrate GPGME in Qt. 210 211 212 213File: gpgme.info, Node: Introduction, Next: Preparation, Prev: Top, Up: Top 214 2151 Introduction 216************** 217 218‘GnuPG Made Easy’ (GPGME) is a C language library that allows to add 219support for cryptography to a program. It is designed to make access to 220public key crypto engines like GnuPG or GpgSM easier for applications. 221GPGME provides a high-level crypto API for encryption, decryption, 222signing, signature verification and key management. 223 224 GPGME uses GnuPG and GpgSM as its backends to support OpenPGP and the 225Cryptographic Message Syntax (CMS). 226 227* Menu: 228 229* Getting Started:: Purpose of the manual, and how to use it. 230* Features:: Reasons to install and use GPGME. 231* Overview:: Basic architecture of the GPGME library. 232 233 234File: gpgme.info, Node: Getting Started, Next: Features, Up: Introduction 235 2361.1 Getting Started 237=================== 238 239This manual documents the GPGME library programming interface. All 240functions and data types provided by the library are explained. 241 242 The reader is assumed to possess basic knowledge about cryptography 243in general, and public key cryptography in particular. The underlying 244cryptographic engines that are used by the library are not explained, 245but where necessary, special features or requirements by an engine are 246mentioned as far as they are relevant to GPGME or its users. 247 248 This manual can be used in several ways. If read from the beginning 249to the end, it gives a good introduction into the library and how it can 250be used in an application. Forward references are included where 251necessary. Later on, the manual can be used as a reference manual to 252get just the information needed about any particular interface of the 253library. Experienced programmers might want to start looking at the 254examples at the end of the manual, and then only read up those parts of 255the interface which are unclear. 256 257 The documentation for the language bindings is currently not included 258in this manual. Those languages bindings follow the general programming 259model of GPGME but may provide some extra high level abstraction on top 260of the GPGME style API. For now please see the README files in the 261‘lang/’ directory of the source distribution. 262 263 264File: gpgme.info, Node: Features, Next: Overview, Prev: Getting Started, Up: Introduction 265 2661.2 Features 267============ 268 269GPGME has a couple of advantages over other libraries doing a similar 270job, and over implementing support for GnuPG or other crypto engines 271into your application directly. 272 273it’s free software 274 Anybody can use, modify, and redistribute it under the terms of the 275 GNU Lesser General Public License (*note Library Copying::). 276 277it’s flexible 278 GPGME provides transparent support for several cryptographic 279 protocols by different engines. Currently, GPGME supports the 280 OpenPGP protocol using GnuPG as the backend, and the Cryptographic 281 Message Syntax using GpgSM as the backend. 282 283it’s easy 284 GPGME hides the differences between the protocols and engines from 285 the programmer behind an easy-to-use interface. This way the 286 programmer can focus on the other parts of the program, and still 287 integrate strong cryptography in his application. Once support for 288 GPGME has been added to a program, it is easy to add support for 289 other crypto protocols once GPGME backends provide them. 290 291it’s language friendly 292 GPGME comes with languages bindings for several common programming 293 languages: Common Lisp, C++, Python 2, and Python 3. 294 295 296File: gpgme.info, Node: Overview, Prev: Features, Up: Introduction 297 2981.3 Overview 299============ 300 301GPGME provides a data abstraction that is used to pass data to the 302crypto engine, and receive returned data from it. Data can be read from 303memory or from files, but it can also be provided by a callback 304function. 305 306 The actual cryptographic operations are always set within a context. 307A context provides configuration parameters that define the behaviour of 308all operations performed within it. Only one operation per context is 309allowed at any time, but when one operation is finished, you can run the 310next operation in the same context. There can be more than one context, 311and all can run different operations at the same time. 312 313 Furthermore, GPGME has rich key management facilities including 314listing keys, querying their attributes, generating, importing, 315exporting and deleting keys, and acquiring information about the trust 316path. 317 318 With some precautions, GPGME can be used in a multi-threaded 319environment, although it is not completely thread safe and thus needs 320the support of the application. 321 322 323File: gpgme.info, Node: Preparation, Next: Protocols and Engines, Prev: Introduction, Up: Top 324 3252 Preparation 326************* 327 328To use GPGME, you have to perform some changes to your sources and the 329build system. The necessary changes are small and explained in the 330following sections. At the end of this chapter, it is described how the 331library is initialized, and how the requirements of the library are 332verified. 333 334* Menu: 335 336* Header:: What header file you need to include. 337* Building the Source:: Compiler options to be used. 338* Largefile Support (LFS):: How to use GPGME with LFS. 339* Using Automake:: Compiler options to be used the easy way. 340* Using Libtool:: Avoiding compiler options entirely. 341* Library Version Check:: Getting and verifying the library version. 342* Signal Handling:: How GPGME affects signal handling. 343* Multi-Threading:: How GPGME can be used in an MT environment. 344 345 346File: gpgme.info, Node: Header, Next: Building the Source, Up: Preparation 347 3482.1 Header 349========== 350 351All interfaces (data types and functions) of the library are defined in 352the header file ‘gpgme.h’. You must include this in all programs using 353the library, either directly or through some other header file, like 354this: 355 356 #include <gpgme.h> 357 358 The name space of GPGME is ‘gpgme_*’ for function names and data 359types and ‘GPGME_*’ for other symbols. Symbols internal to GPGME take 360the form ‘_gpgme_*’ and ‘_GPGME_*’. 361 362 Because GPGME makes use of the GPG Error library, using GPGME will 363also use the ‘GPG_ERR_*’ name space directly, and the ‘gpg_err*’, 364‘gpg_str*’, and ‘gpgrt_*’ name space indirectly. 365 366 367File: gpgme.info, Node: Building the Source, Next: Largefile Support (LFS), Prev: Header, Up: Preparation 368 3692.2 Building the Source 370======================= 371 372If you want to compile a source file including the ‘gpgme.h’ header 373file, you must make sure that the compiler can find it in the directory 374hierarchy. This is accomplished by adding the path to the directory in 375which the header file is located to the compilers include file search 376path (via the ‘-I’ option). 377 378 However, the path to the include file is determined at the time the 379source is configured. To solve this problem, gpgme ships with a small 380helper program ‘gpgme-config’ that knows about the path to the include 381file and other configuration options. The options that need to be added 382to the compiler invocation at compile time are output by the ‘--cflags’ 383option to ‘gpgme-config’. The following example shows how it can be 384used at the command line: 385 386 gcc -c foo.c `gpgme-config --cflags` 387 388 Adding the output of ‘gpgme-config --cflags’ to the compiler command 389line will ensure that the compiler can find the GPGME header file. 390 391 A similar problem occurs when linking the program with the library. 392Again, the compiler has to find the library files. For this to work, 393the path to the library files has to be added to the library search path 394(via the ‘-L’ option). For this, the option ‘--libs’ to ‘gpgme-config’ 395can be used. For convenience, this option also outputs all other 396options that are required to link the program with GPGME (in particular, 397the ‘-lgpgme’ option). The example shows how to link ‘foo.o’ with the 398GPGME library to a program ‘foo’. 399 400 gcc -o foo foo.o `gpgme-config --libs` 401 402 Of course you can also combine both examples to a single command by 403specifying both options to ‘gpgme-config’: 404 405 gcc -o foo foo.c `gpgme-config --cflags --libs` 406 407 If you need to detect the installed language bindings you can use 408list them using: 409 410 gpgme-config --print-lang 411 412 or test for the availability using 413 414 gpgme-config --have-lang=python && echo 'Bindings for Pythons available' 415 416 417File: gpgme.info, Node: Largefile Support (LFS), Next: Using Automake, Prev: Building the Source, Up: Preparation 418 4192.3 Largefile Support (LFS) 420=========================== 421 422GPGME is compiled with largefile support by default, if it is available 423on the system. This means that GPGME supports files larger than two 424gigabyte in size, if the underlying operating system can. On some 425systems, largefile support is already the default. On such systems, 426nothing special is required. However, some systems provide only support 427for files up to two gigabyte in size by default. Support for larger 428file sizes has to be specifically enabled. 429 430 To make a difficult situation even more complex, such systems provide 431two different types of largefile support. You can either get all 432relevant functions replaced with alternatives that are largefile 433capable, or you can get new functions and data types for largefile 434support added. Those new functions have the same name as their 435smallfile counterparts, but with a suffix of 64. 436 437 An example: The data type ‘off_t’ is 32 bit wide on GNU/Linux PC 438systems. To address offsets in large files, you can either enable 439largefile support add-on. Then a new data type ‘off64_t’ is provided, 440which is 64 bit wide. Or you can replace the existing ‘off_t’ data type 441with its 64 bit wide counterpart. All occurrences of ‘off_t’ are then 442automagically replaced. 443 444 As if matters were not complex enough, there are also two different 445types of file descriptors in such systems. This is important because if 446file descriptors are exchanged between programs that use a different 447maximum file size, certain errors must be produced on some file 448descriptors to prevent subtle overflow bugs from occurring. 449 450 As you can see, supporting two different maximum file sizes at the 451same time is not at all an easy task. However, the maximum file size 452does matter for GPGME, because some data types it uses in its interfaces 453are affected by that. For example, the ‘off_t’ data type is used in the 454‘gpgme_data_seek’ function, to match its POSIX counterpart. This 455affects the call-frame of the function, and thus the ABI of the library. 456Furthermore, file descriptors can be exchanged between GPGME and the 457application. 458 459 For you as the user of the library, this means that your program must 460be compiled in the same file size mode as the library. Luckily, there 461is absolutely no valid reason for new programs to not enable largefile 462support by default and just use that. The compatibility modes (small 463file sizes or dual mode) can be considered an historic artefact, only 464useful to allow for a transitional period. 465 466 On POSIX platforms GPGME is compiled using largefile support by 467default. This means that your application must do the same, at least as 468far as it is relevant for using the ‘gpgme.h’ header file. All types in 469this header files refer to their largefile counterparts, if they are 470different from any default types on the system. 471 472 On 32 and 64 bit Windows platforms ‘off_t’ is declared as 32 bit 473signed integer. There is no specific support for LFS in the C library. 474The recommendation from Microsoft is to use the native interface 475(‘CreateFile’ et al.) for large files. Released binary versions of 476GPGME (libgpgme-11.dll) have always been build with a 32 bit ‘off_t’. 477To avoid an ABI break we stick to this convention for 32 bit Windows by 478using ‘long’ there. GPGME versions for 64 bit Windows have never been 479released and thus we are able to use ‘int64_t’ instead of ‘off_t’ there. 480For easier migration the typedef ‘gpgme_off_t’ has been defined. The 481reason we cannot use ‘off_t’ directly is that some toolchains (e.g. 482mingw64) introduce a POSIX compatible hack for ‘off_t’. Some widely 483used toolkits make use of this hack and in turn GPGME would need to use 484it also. However, this would introduce an ABI break and existing 485software making use of libgpgme might suffer from a severe break. Thus 486with version 1.4.2 we redefined all functions using ‘off_t’ to use 487‘gpgme_off_t’ which is defined as explained above. This way we keep the 488ABI well defined and independent of any toolchain hacks. The bottom 489line is that LFS support in GPGME is only available on 64 bit versions 490of Windows. 491 492 On POSIX platforms you can enable largefile support, if it is 493different from the default on the system the application is compiled on, 494by using the Autoconf macro ‘AC_SYS_LARGEFILE’. If you do this, then 495you don’t need to worry about anything else: It will just work. In this 496case you might also want to use ‘AC_FUNC_FSEEKO’ to take advantage of 497some new interfaces, and ‘AC_TYPE_OFF_T’ (just in case). 498 499 If you do not use Autoconf, you can define the preprocessor symbol 500‘_FILE_OFFSET_BITS’ to 64 _before_ including any header files, for 501example by specifying the option ‘-D_FILE_OFFSET_BITS=64’ on the 502compiler command line. You will also want to define the preprocessor 503symbol ‘LARGEFILE_SOURCE’ to 1 in this case, to take advantage of some 504new interfaces. 505 506 If you do not want to do either of the above, you probably know 507enough about the issue to invent your own solution. Just keep in mind 508that the GPGME header file expects that largefile support is enabled, if 509it is available. In particular, we do not support dual mode 510(‘_LARGEFILE64_SOURCE’). 511 512 513File: gpgme.info, Node: Using Automake, Next: Using Libtool, Prev: Largefile Support (LFS), Up: Preparation 514 5152.4 Using Automake 516================== 517 518It is much easier if you use GNU Automake instead of writing your own 519Makefiles. If you do that you do not have to worry about finding and 520invoking the ‘gpgme-config’ script at all. GPGME provides an extension 521to Automake that does all the work for you. 522 523 -- Macro: AM_PATH_GPGME ([MINIMUM-VERSION], [ACTION-IF-FOUND], 524 [ACTION-IF-NOT-FOUND]) 525 -- Macro: AM_PATH_GPGME_PTH ([MINIMUM-VERSION], [ACTION-IF-FOUND], 526 [ACTION-IF-NOT-FOUND]) 527 -- Macro: AM_PATH_GPGME_PTHREAD ([MINIMUM-VERSION], [ACTION-IF-FOUND], 528 [ACTION-IF-NOT-FOUND]) 529 Check whether GPGME (at least version MINIMUM-VERSION, if given) 530 exists on the host system. If it is found, execute 531 ACTION-IF-FOUND, otherwise do ACTION-IF-NOT-FOUND, if given. 532 533 Additionally, the function defines ‘GPGME_CFLAGS’ to the flags 534 needed for compilation of the program to find the ‘gpgme.h’ header 535 file, and ‘GPGME_LIBS’ to the linker flags needed to link the 536 program to the GPGME library. If the used helper script does not 537 match the target type you are building for a warning is printed and 538 the string ‘libgcrypt’ is appended to the variable 539 ‘gpg_config_script_warn’. 540 541 ‘AM_PATH_GPGME_PTH’ checks for the version of GPGME that can be 542 used with GNU Pth, and defines ‘GPGME_PTH_CFLAGS’ and 543 ‘GPGME_PTH_LIBS’. 544 545 ‘AM_PATH_GPGME_PTHREAD’ checks for the version of GPGME that can be 546 used with the native pthread implementation, and defines 547 ‘GPGME_PTHREAD_CFLAGS’ and ‘GPGME_PTHREAD_LIBS’. Since version 548 1.8.0 this is no longer required to GPGME_PTHREAD as GPGME itself 549 is thread safe. 550 551 This macro searches for ‘gpgme-config’ along the PATH. If you are 552 cross-compiling, it is useful to set the environment variable 553 ‘SYSROOT’ to the top directory of your target. The macro will then 554 first look for the helper program in the ‘bin’ directory below that 555 top directory. An absolute directory name must be used for 556 ‘SYSROOT’. Finally, if the configure command line option 557 ‘--with-gpgme-prefix’ is used, only its value is used for the top 558 directory below which the helper script is expected. 559 560 You can use the defined Autoconf variables like this in your 561‘Makefile.am’: 562 563 AM_CPPFLAGS = $(GPGME_CFLAGS) 564 LDADD = $(GPGME_LIBS) 565 566 567File: gpgme.info, Node: Using Libtool, Next: Library Version Check, Prev: Using Automake, Up: Preparation 568 5692.5 Using Libtool 570================= 571 572The easiest way is to just use GNU Libtool. If you use libtool, and 573link to ‘libgpgme.la’, ‘libgpgme-pth.la’ or ‘libgpgme-pthread.la’ 574respectively, everything will be done automatically by Libtool. 575 576 577File: gpgme.info, Node: Library Version Check, Next: Signal Handling, Prev: Using Libtool, Up: Preparation 578 5792.6 Library Version Check 580========================= 581 582 -- Function: const char * gpgme_check_version 583 (const char *REQUIRED_VERSION) 584 The function ‘gpgme_check_version’ has four purposes. It can be 585 used to retrieve the version number of the library. In addition it 586 can verify that the version number is higher than a certain 587 required version number. In either case, the function initializes 588 some sub-systems, and for this reason alone it must be invoked 589 early in your program, before you make use of the other functions 590 in GPGME. The last purpose is to run selftests. 591 592 As a side effect for W32 based systems, the socket layer will get 593 initialized. 594 595 If REQUIRED_VERSION is ‘NULL’, the function returns a pointer to a 596 statically allocated string containing the version number of the 597 library. 598 599 If REQUIRED_VERSION is not ‘NULL’, it should point to a string 600 containing a version number, and the function checks that the 601 version of the library is at least as high as the version number 602 provided. In this case, the function returns a pointer to a 603 statically allocated string containing the version number of the 604 library. If REQUIRED_VERSION is not a valid version number, or if 605 the version requirement is not met, the function returns ‘NULL’. 606 607 If you use a version of a library that is backwards compatible with 608 older releases, but contains additional interfaces which your 609 program uses, this function provides a run-time check if the 610 necessary features are provided by the installed version of the 611 library. 612 613 If a selftest fails, the function may still succeed. Selftest 614 errors are returned later when invoking ‘gpgme_new’ or 615 ‘gpgme-data_new’, so that a detailed error code can be returned 616 (historically, ‘gpgme_check_version’ does not return a detailed 617 error code). 618 619 -- Function: int gpgme_set_global_flag (const char *NAME, 620 const char *VALUE) 621 622 SINCE: 1.4.0 623 624 On some systems it is not easy to set environment variables and 625 thus hard to use GPGME’s internal trace facility for debugging. 626 This function has been introduced as an alternative way to enable 627 debugging and for a couple of other rarely used tweaks. It is 628 important to assure that only one thread accesses GPGME functions 629 between a call to this function and after the return from the call 630 to ‘gpgme_check_version’. 631 632 All currently supported features require that this function is 633 called as early as possible — even before ‘gpgme_check_version’. 634 The features are identified by the following values for NAME: 635 636 ‘debug’ 637 To enable debugging use the string “debug” for NAME and VALUE 638 identical to the value used with the environment variable 639 ‘GPGME_DEBUG’. 640 641 ‘disable-gpgconf’ 642 Using this feature with any VALUE disables the detection of 643 the gpgconf program and thus forces GPGME to fallback into the 644 simple OpenPGP only mode. It may be used to force the use of 645 GnuPG-1 on systems which have both GPG versions installed. 646 Note that in general the use of ‘gpgme_set_engine_info’ is a 647 better way to select a specific engine version. 648 649 ‘gpgconf-name’ 650 ‘gpg-name’ 651 Set the name of the gpgconf respective gpg binary. The 652 defaults are ‘GNU/GnuPG/gpgconf’ and ‘GNU/GnuPG/gpg’. Under 653 Unix the leading directory part is ignored. Under Windows the 654 leading directory part is used as the default installation 655 directory; the ‘.exe’ suffix is added by GPGME. Use forward 656 slashed even under Windows. 657 658 ‘require-gnupg’ 659 Set the minimum version of the required GnuPG engine. If that 660 version is not met, GPGME fails early instead of trying to use 661 the existent version. The given version must be a string with 662 major, minor, and micro number. Example: "2.1.0". 663 664 ‘w32-inst-dir’ 665 On Windows GPGME needs to know its installation directory to 666 find its spawn helper. This is in general no problem because 667 a DLL has this information. Some applications however link 668 statically to GPGME and thus GPGME can only figure out the 669 installation directory of this application which may be wrong 670 in certain cases. By supplying an installation directory as 671 value to this flag, GPGME will assume that that directory is 672 the installation directory. This flag has no effect on 673 non-Windows platforms. 674 675 This function returns ‘0’ on success. In contrast to other 676 functions the non-zero return value on failure does not convey any 677 error code. For setting “debug” the only possible error cause is 678 an out of memory condition; which would exhibit itself later 679 anyway. Thus the return value may be ignored. 680 681 After initializing GPGME, you should set the locale information to 682the locale required for your output terminal. This locale information 683is needed for example for the curses and Gtk pinentry. Here is an 684example of a complete initialization: 685 686 #include <locale.h> 687 #include <gpgme.h> 688 689 void 690 init_gpgme (void) 691 { 692 /* Initialize the locale environment. */ 693 setlocale (LC_ALL, ""); 694 gpgme_check_version (NULL); 695 gpgme_set_locale (NULL, LC_CTYPE, setlocale (LC_CTYPE, NULL)); 696 #ifdef LC_MESSAGES 697 gpgme_set_locale (NULL, LC_MESSAGES, setlocale (LC_MESSAGES, NULL)); 698 #endif 699 } 700 701 Note that you are highly recommended to initialize the locale 702settings like this. GPGME can not do this for you because it would not 703be thread safe. The conditional on LC_MESSAGES is only necessary for 704portability to W32 systems. 705 706 707File: gpgme.info, Node: Signal Handling, Next: Multi-Threading, Prev: Library Version Check, Up: Preparation 708 7092.7 Signal Handling 710=================== 711 712The GPGME library communicates with child processes (the crypto 713engines). If a child process dies unexpectedly, for example due to a 714bug, or system problem, a ‘SIGPIPE’ signal will be delivered to the 715application. The default action is to abort the program. To protect 716against this, ‘gpgme_check_version’ sets the ‘SIGPIPE’ signal action to 717‘SIG_IGN’, which means that the signal will be ignored. 718 719 GPGME will only do that if the signal action for ‘SIGPIPE’ is 720‘SIG_DEF’ at the time ‘gpgme_check_version’ is called. If it is 721something different, ‘GPGME’ will take no action. 722 723 This means that if your application does not install any signal 724handler for ‘SIGPIPE’, you don’t need to take any precautions. If you 725do install a signal handler for ‘SIGPIPE’, you must be prepared to 726handle any ‘SIGPIPE’ events that occur due to GPGME writing to a defunct 727pipe. Furthermore, if your application is multi-threaded, and you 728install a signal action for ‘SIGPIPE’, you must make sure you do this 729either before ‘gpgme_check_version’ is called or afterwards. 730 731 732File: gpgme.info, Node: Multi-Threading, Prev: Signal Handling, Up: Preparation 733 7342.8 Multi-Threading 735=================== 736 737The GPGME library is mostly thread-safe, and can be used in a 738multi-threaded environment but there are some requirements for 739multi-threaded use: 740 741 • The function ‘gpgme_check_version’ must be called before any other 742 function in the library, because it initializes the thread support 743 subsystem in GPGME. To achieve this in multi-threaded programs, 744 you must synchronize the memory with respect to other threads that 745 also want to use GPGME. For this, it is sufficient to call 746 ‘gpgme_check_version’ before creating the other threads using 747 GPGME(1). 748 749 • Any ‘gpgme_data_t’ and ‘gpgme_ctx_t’ object must only be accessed 750 by one thread at a time. If multiple threads want to deal with the 751 same object, the caller has to make sure that operations on that 752 object are fully synchronized. 753 754 • Only one thread at any time is allowed to call ‘gpgme_wait’. If 755 multiple threads call this function, the caller must make sure that 756 all invocations are fully synchronized. It is safe to start 757 asynchronous operations while a thread is running in gpgme_wait. 758 759 • The function ‘gpgme_strerror’ is not thread safe. You have to use 760 ‘gpgme_strerror_r’ instead. 761 762 ---------- Footnotes ---------- 763 764 (1) At least this is true for POSIX threads, as ‘pthread_create’ is a 765function that synchronizes memory with respects to other threads. There 766are many functions which have this property, a complete list can be 767found in POSIX, IEEE Std 1003.1-2003, Base Definitions, Issue 6, in the 768definition of the term “Memory Synchronization”. For other thread 769packages other, more relaxed or more strict rules may apply. 770 771 772File: gpgme.info, Node: Protocols and Engines, Next: Algorithms, Prev: Preparation, Up: Top 773 7743 Protocols and Engines 775*********************** 776 777GPGME supports several cryptographic protocols, however, it does not 778implement them. Rather it uses backends (also called engines) which 779implement the protocol. GPGME uses inter-process communication to pass 780data back and forth between the application and the backend, but the 781details of the communication protocol and invocation of the backend is 782completely hidden by the interface. All complexity is handled by GPGME. 783Where an exchange of information between the application and the backend 784is necessary, GPGME provides the necessary callback function hooks and 785further interfaces. 786 787 -- Data type: enum gpgme_protocol_t 788 The ‘gpgme_protocol_t’ type specifies the set of possible protocol 789 values that are supported by GPGME. The following protocols are 790 supported: 791 792 ‘GPGME_PROTOCOL_OpenPGP’ 793 ‘GPGME_PROTOCOL_OPENPGP’ 794 This specifies the OpenPGP protocol. 795 796 ‘GPGME_PROTOCOL_CMS’ 797 This specifies the Cryptographic Message Syntax. 798 799 ‘GPGME_PROTOCOL_GPGCONF’ 800 Under development. Please ask on <gnupg-devel@gnupg.org> for 801 help. 802 803 ‘GPGME_PROTOCOL_ASSUAN’ 804 SINCE: 1.2.0 805 806 This specifies the raw Assuan protocol. 807 808 ‘GPGME_PROTOCOL_G13’ 809 SINCE: 1.3.0 810 811 Under development. Please ask on <gnupg-devel@gnupg.org> for 812 help. 813 814 ‘GPGME_PROTOCOL_UISERVER’ 815 Under development. Please ask on <gnupg-devel@gnupg.org> for 816 help. 817 818 ‘GPGME_PROTOCOL_SPAWN’ 819 SINCE: 1.5.0 820 821 Special protocol for use with ‘gpgme_op_spawn’. 822 823 ‘GPGME_PROTOCOL_UNKNOWN’ 824 Reserved for future extension. You may use this to indicate 825 that the used protocol is not known to the application. 826 Currently, GPGME does not accept this value in any operation, 827 though, except for ‘gpgme_get_protocol_name’. 828 829 -- Function: const char * gpgme_get_protocol_name 830 (gpgme_protocol_t PROTOCOL) 831 The function ‘gpgme_get_protocol_name’ returns a statically 832 allocated string describing the protocol PROTOCOL, or ‘NULL’ if the 833 protocol number is not valid. 834 835* Menu: 836 837* Engine Version Check:: Verifying the engine version. 838* Engine Information:: Obtaining more information about the engines. 839* Engine Configuration:: Changing the engine configuration. 840* OpenPGP:: Support for the OpenPGP protocol. 841* Cryptographic Message Syntax:: Support for the CMS. 842* Assuan:: Support for the raw Assuan protocol. 843 844 845File: gpgme.info, Node: Engine Version Check, Next: Engine Information, Up: Protocols and Engines 846 8473.1 Engine Version Check 848======================== 849 850 -- Function: const char * gpgme_get_dirinfo (cons char *WHAT) 851 SINCE: 1.5.0 852 853 The function ‘gpgme_get_dirinfo’ returns a statically allocated 854 string with the value associated to WHAT. The returned values are 855 the defaults and won’t change even after ‘gpgme_set_engine_info’ 856 has been used to configure a different engine. ‘NULL’ is returned 857 if no value is available. Commonly supported values for WHAT are: 858 859 ‘homedir’ 860 Return the default home directory. 861 862 ‘sysconfdir’ 863 Return the name of the system configuration directory 864 865 ‘bindir’ 866 Return the name of the directory with GnuPG program files. 867 868 ‘libdir’ 869 Return the name of the directory with GnuPG related library 870 files. 871 872 ‘libexecdir’ 873 Return the name of the directory with GnuPG helper program 874 files. 875 876 ‘datadir’ 877 Return the name of the directory with GnuPG shared data. 878 879 ‘localedir’ 880 Return the name of the directory with GnuPG locale data. 881 882 ‘agent-socket’ 883 Return the name of the socket to connect to the gpg-agent. 884 885 ‘agent-ssh-socket’ 886 Return the name of the socket to connect to the ssh-agent 887 component of gpg-agent. 888 889 ‘dirmngr-socket’ 890 Return the name of the socket to connect to the dirmngr. 891 892 ‘uiserver-socket’ 893 Return the name of the socket to connect to the user interface 894 server. 895 896 ‘gpgconf-name’ 897 Return the file name of the engine configuration tool. 898 899 ‘gpg-name’ 900 Return the file name of the OpenPGP engine. 901 902 ‘gpgsm-name’ 903 Return the file name of the CMS engine. 904 905 ‘g13-name’ 906 Return the name of the file container encryption engine. 907 908 ‘gpg-wks-client-name’ 909 Return the name of the Web Key Service tool. 910 911 -- Function: gpgme_error_t gpgme_engine_check_version 912 (gpgme_protocol_t PROTOCOL) 913 The function ‘gpgme_engine_check_version’ verifies that the engine 914 implementing the protocol PROTOCOL is installed in the expected 915 path and meets the version requirement of GPGME. 916 917 This function returns the error code ‘GPG_ERR_NO_ERROR’ if the 918 engine is available and ‘GPG_ERR_INV_ENGINE’ if it is not. 919 920 921File: gpgme.info, Node: Engine Information, Next: Engine Configuration, Prev: Engine Version Check, Up: Protocols and Engines 922 9233.2 Engine Information 924====================== 925 926 -- Data type: gpgme_engine_info_t 927 The ‘gpgme_engine_info_t’ type specifies a pointer to a structure 928 describing a crypto engine. The structure contains the following 929 elements: 930 931 ‘gpgme_engine_info_t next’ 932 This is a pointer to the next engine info structure in the 933 linked list, or ‘NULL’ if this is the last element. 934 935 ‘gpgme_protocol_t protocol’ 936 This is the protocol for which the crypto engine is used. You 937 can convert this to a string with ‘gpgme_get_protocol_name’ 938 for printing. 939 940 ‘const char *file_name’ 941 This is a string holding the file name of the executable of 942 the crypto engine. Currently, it is never ‘NULL’, but using 943 ‘NULL’ is reserved for future use, so always check before you 944 use it. 945 946 ‘const char *home_dir’ 947 This is a string holding the directory name of the crypto 948 engine’s configuration directory. If it is ‘NULL’, then the 949 default directory is used. See ‘gpgme_get_dirinfo’ on how to 950 get the default directory. 951 952 ‘const char *version’ 953 This is a string containing the version number of the crypto 954 engine. It might be ‘NULL’ if the version number can not be 955 determined, for example because the executable doesn’t exist 956 or is invalid. 957 958 ‘const char *req_version’ 959 This is a string containing the minimum required version 960 number of the crypto engine for GPGME to work correctly. This 961 is the version number that ‘gpgme_engine_check_version’ 962 verifies against. Currently, it is never ‘NULL’, but using 963 ‘NULL’ is reserved for future use, so always check before you 964 use it. 965 966 -- Function: gpgme_error_t gpgme_get_engine_info 967 (gpgme_engine_info_t *INFO) 968 The function ‘gpgme_get_engine_info’ returns a linked list of 969 engine info structures in INFO. Each info structure describes the 970 defaults of one configured backend. 971 972 The memory for the info structures is allocated the first time this 973 function is invoked, and must not be freed by the caller. 974 975 This function returns the error code ‘GPG_ERR_NO_ERROR’ if 976 successful, and a system error if the memory could not be 977 allocated. 978 979 Here is an example how you can provide more diagnostics if you 980receive an error message which indicates that the crypto engine is 981invalid. 982 983 gpgme_ctx_t ctx; 984 gpgme_error_t err; 985 986 [...] 987 988 if (gpgme_err_code (err) == GPG_ERR_INV_ENGINE) 989 { 990 gpgme_engine_info_t info; 991 err = gpgme_get_engine_info (&info); 992 if (!err) 993 { 994 while (info && info->protocol != gpgme_get_protocol (ctx)) 995 info = info->next; 996 if (!info) 997 fprintf (stderr, "GPGME compiled without support for protocol %s", 998 gpgme_get_protocol_name (info->protocol)); 999 else if (info->file_name && !info->version) 1000 fprintf (stderr, "Engine %s not installed properly", 1001 info->file_name); 1002 else if (info->file_name && info->version && info->req_version) 1003 fprintf (stderr, "Engine %s version %s installed, " 1004 "but at least version %s required", info->file_name, 1005 info->version, info->req_version); 1006 else 1007 fprintf (stderr, "Unknown problem with engine for protocol %s", 1008 gpgme_get_protocol_name (info->protocol)); 1009 } 1010 } 1011 1012 1013File: gpgme.info, Node: Engine Configuration, Next: OpenPGP, Prev: Engine Information, Up: Protocols and Engines 1014 10153.3 Engine Configuration 1016======================== 1017 1018You can change the configuration of a backend engine, and thus change 1019the executable program and configuration directory to be used. You can 1020make these changes the default or set them for some contexts 1021individually. 1022 1023 -- Function: gpgme_error_t gpgme_set_engine_info 1024 (gpgme_protocol_t PROTO, const char *FILE_NAME, 1025 const char *HOME_DIR) 1026 SINCE: 1.1.0 1027 1028 The function ‘gpgme_set_engine_info’ changes the default 1029 configuration of the crypto engine implementing the protocol PROTO. 1030 1031 FILE_NAME is the file name of the executable program implementing 1032 this protocol, and HOME_DIR is the directory name of the 1033 configuration directory for this crypto engine. If HOME_DIR is 1034 ‘NULL’, the engine’s default will be used. 1035 1036 The new defaults are not applied to already created GPGME contexts. 1037 1038 This function returns the error code ‘GPG_ERR_NO_ERROR’ if 1039 successful, or an error code on failure. 1040 1041 The functions ‘gpgme_ctx_get_engine_info’ and 1042‘gpgme_ctx_set_engine_info’ can be used to change the engine 1043configuration per context. *Note Crypto Engine::. 1044 1045 1046File: gpgme.info, Node: OpenPGP, Next: Cryptographic Message Syntax, Prev: Engine Configuration, Up: Protocols and Engines 1047 10483.4 OpenPGP 1049=========== 1050 1051OpenPGP is implemented by GnuPG, the GNU Privacy Guard. This is the 1052first protocol that was supported by GPGME. 1053 1054 The OpenPGP protocol is specified by ‘GPGME_PROTOCOL_OpenPGP’. 1055 1056 1057File: gpgme.info, Node: Cryptographic Message Syntax, Next: Assuan, Prev: OpenPGP, Up: Protocols and Engines 1058 10593.5 Cryptographic Message Syntax 1060================================ 1061 1062CMS is implemented by GpgSM, the S/MIME implementation for GnuPG. 1063 1064 The CMS protocol is specified by ‘GPGME_PROTOCOL_CMS’. 1065 1066 1067File: gpgme.info, Node: Assuan, Prev: Cryptographic Message Syntax, Up: Protocols and Engines 1068 10693.6 Assuan 1070========== 1071 1072Assuan is the RPC library used by the various GnuPG components. The 1073Assuan protocol allows one to talk to arbitrary Assuan servers using 1074GPGME. *Note Using the Assuan protocol::. 1075 1076 The ASSUAN protocol is specified by ‘GPGME_PROTOCOL_ASSUAN’. 1077 1078 1079File: gpgme.info, Node: Algorithms, Next: Error Handling, Prev: Protocols and Engines, Up: Top 1080 10814 Algorithms 1082************ 1083 1084The crypto backends support a variety of algorithms used in public key 1085cryptography.(1) The following sections list the identifiers used to 1086denote such an algorithm. 1087 1088* Menu: 1089 1090* Public Key Algorithms:: A list of all public key algorithms. 1091* Hash Algorithms:: A list of all hash algorithms. 1092 1093 ---------- Footnotes ---------- 1094 1095 (1) Some engines also provide symmetric only encryption; see the 1096description of the encryption function on how to use this. 1097 1098 1099File: gpgme.info, Node: Public Key Algorithms, Next: Hash Algorithms, Up: Algorithms 1100 11014.1 Public Key Algorithms 1102========================= 1103 1104Public key algorithms are used for encryption, decryption, signing and 1105verification of signatures. 1106 1107 -- Data type: enum gpgme_pubkey_algo_t 1108 The ‘gpgme_pubkey_algo_t’ type specifies the set of all public key 1109 algorithms that are supported by GPGME. Possible values are: 1110 1111 ‘GPGME_PK_RSA’ 1112 This value indicates the RSA (Rivest, Shamir, Adleman) 1113 algorithm. 1114 1115 ‘GPGME_PK_RSA_E’ 1116 Deprecated. This value indicates the RSA (Rivest, Shamir, 1117 Adleman) algorithm for encryption and decryption only. 1118 1119 ‘GPGME_PK_RSA_S’ 1120 Deprecated. This value indicates the RSA (Rivest, Shamir, 1121 Adleman) algorithm for signing and verification only. 1122 1123 ‘GPGME_PK_DSA’ 1124 This value indicates DSA, the Digital Signature Algorithm. 1125 1126 ‘GPGME_PK_ELG’ 1127 This value indicates ElGamal. 1128 1129 ‘GPGME_PK_ELG_E’ 1130 This value also indicates ElGamal and is used specifically in 1131 GnuPG. 1132 1133 ‘GPGME_PK_ECC’ 1134 SINCE: 1.5.0 1135 1136 This value is a generic indicator for ellipic curve 1137 algorithms. 1138 1139 ‘GPGME_PK_ECDSA’ 1140 SINCE: 1.3.0 1141 1142 This value indicates ECDSA, the Elliptic Curve Digital 1143 Signature Algorithm as defined by FIPS 186-2 and RFC-6637. 1144 1145 ‘GPGME_PK_ECDH’ 1146 SINCE: 1.3.0 1147 1148 This value indicates ECDH, the Eliptic Curve Diffie-Hellmann 1149 encryption algorithm as defined by RFC-6637. 1150 1151 ‘GPGME_PK_EDDSA’ 1152 SINCE: 1.7.0 1153 1154 This value indicates the EdDSA algorithm. 1155 1156 -- Function: const char * gpgme_pubkey_algo_name 1157 (gpgme_pubkey_algo_t ALGO) 1158 The function ‘gpgme_pubkey_algo_name’ returns a pointer to a 1159 statically allocated string containing a description of the public 1160 key algorithm ALGO. This string can be used to output the name of 1161 the public key algorithm to the user. 1162 1163 If ALGO is not a valid public key algorithm, ‘NULL’ is returned. 1164 1165 -- Function: char * gpgme_pubkey_algo_string (gpgme_subkey_t KEY) 1166 SINCE: 1.7.0 1167 1168 The function ‘gpgme_pubkey_algo_string’ is a convenience function 1169 to build and return an algorithm string in the same way GnuPG does 1170 (e.g. “rsa2048” or “ed25519”). The caller must free the result 1171 using ‘gpgme_free’. On error (e.g. invalid argument or memory 1172 exhausted), the function returns NULL and sets ‘ERRNO’. 1173 1174 1175File: gpgme.info, Node: Hash Algorithms, Prev: Public Key Algorithms, Up: Algorithms 1176 11774.2 Hash Algorithms 1178=================== 1179 1180Hash (message digest) algorithms are used to compress a long message to 1181make it suitable for public key cryptography. 1182 1183 -- Data type: enum gpgme_hash_algo_t 1184 The ‘gpgme_hash_algo_t’ type specifies the set of all hash 1185 algorithms that are supported by GPGME. Possible values are: 1186 1187 ‘GPGME_MD_MD5’ 1188 ‘GPGME_MD_SHA1’ 1189 ‘GPGME_MD_RMD160’ 1190 ‘GPGME_MD_MD2’ 1191 ‘GPGME_MD_TIGER’ 1192 ‘GPGME_MD_HAVAL’ 1193 ‘GPGME_MD_SHA256’ 1194 ‘GPGME_MD_SHA384’ 1195 ‘GPGME_MD_SHA512’ 1196 ‘GPGME_MD_SHA224’ 1197 SINCE: 1.5.0 1198 1199 ‘GPGME_MD_MD4’ 1200 ‘GPGME_MD_CRC32’ 1201 ‘GPGME_MD_CRC32_RFC1510’ 1202 ‘GPGME_MD_CRC24_RFC2440’ 1203 1204 -- Function: const char * gpgme_hash_algo_name (gpgme_hash_algo_t ALGO) 1205 The function ‘gpgme_hash_algo_name’ returns a pointer to a 1206 statically allocated string containing a description of the hash 1207 algorithm ALGO. This string can be used to output the name of the 1208 hash algorithm to the user. 1209 1210 If ALGO is not a valid hash algorithm, ‘NULL’ is returned. 1211 1212 1213File: gpgme.info, Node: Error Handling, Next: Exchanging Data, Prev: Algorithms, Up: Top 1214 12155 Error Handling 1216**************** 1217 1218Many functions in GPGME can return an error if they fail. For this 1219reason, the application should always catch the error condition and take 1220appropriate measures, for example by releasing the resources and passing 1221the error up to the caller, or by displaying a descriptive message to 1222the user and cancelling the operation. 1223 1224 Some error values do not indicate a system error or an error in the 1225operation, but the result of an operation that failed properly. For 1226example, if you try to decrypt a tempered message, the decryption will 1227fail. Another error value actually means that the end of a data buffer 1228or list has been reached. The following descriptions explain for many 1229error codes what they mean usually. Some error values have specific 1230meanings if returned by a certain functions. Such cases are described 1231in the documentation of those functions. 1232 1233 GPGME uses the ‘libgpg-error’ library. This allows to share the 1234error codes with other components of the GnuPG system, and thus pass 1235error values transparently from the crypto engine, or some helper 1236application of the crypto engine, to the user. This way no information 1237is lost. As a consequence, GPGME does not use its own identifiers for 1238error codes, but uses those provided by ‘libgpg-error’. They usually 1239start with ‘GPG_ERR_’. 1240 1241 However, GPGME does provide aliases for the functions defined in 1242libgpg-error, which might be preferred for name space consistency. 1243 1244* Menu: 1245 1246* Error Values:: The error value and what it means. 1247* Error Sources:: A list of important error sources. 1248* Error Codes:: A list of important error codes. 1249* Error Strings:: How to get a descriptive string from a value. 1250 1251 1252File: gpgme.info, Node: Error Values, Next: Error Sources, Up: Error Handling 1253 12545.1 Error Values 1255================ 1256 1257 -- Data type: gpgme_err_code_t 1258 The ‘gpgme_err_code_t’ type is an alias for the ‘libgpg-error’ type 1259 ‘gpg_err_code_t’. The error code indicates the type of an error, 1260 or the reason why an operation failed. 1261 1262 A list of important error codes can be found in the next section. 1263 1264 -- Data type: gpgme_err_source_t 1265 The ‘gpgme_err_source_t’ type is an alias for the ‘libgpg-error’ 1266 type ‘gpg_err_source_t’. The error source has not a precisely 1267 defined meaning. Sometimes it is the place where the error 1268 happened, sometimes it is the place where an error was encoded into 1269 an error value. Usually the error source will give an indication 1270 to where to look for the problem. This is not always true, but it 1271 is attempted to achieve this goal. 1272 1273 A list of important error sources can be found in the next section. 1274 1275 -- Data type: gpgme_error_t 1276 The ‘gpgme_error_t’ type is an alias for the ‘libgpg-error’ type 1277 ‘gpg_error_t’. An error value like this has always two components, 1278 an error code and an error source. Both together form the error 1279 value. 1280 1281 Thus, the error value can not be directly compared against an error 1282 code, but the accessor functions described below must be used. 1283 However, it is guaranteed that only 0 is used to indicate success 1284 (‘GPG_ERR_NO_ERROR’), and that in this case all other parts of the 1285 error value are set to 0, too. 1286 1287 Note that in GPGME, the error source is used purely for 1288 diagnostical purposes. Only the error code should be checked to 1289 test for a certain outcome of a function. The manual only 1290 documents the error code part of an error value. The error source 1291 is left unspecified and might be anything. 1292 1293 -- Function: static inline gpgme_err_code_t gpgme_err_code 1294 (gpgme_error_t ERR) 1295 The static inline function ‘gpgme_err_code’ returns the 1296 ‘gpgme_err_code_t’ component of the error value ERR. This function 1297 must be used to extract the error code from an error value in order 1298 to compare it with the ‘GPG_ERR_*’ error code macros. 1299 1300 -- Function: static inline gpgme_err_source_t gpgme_err_source 1301 (gpgme_error_t ERR) 1302 The static inline function ‘gpgme_err_source’ returns the 1303 ‘gpgme_err_source_t’ component of the error value ERR. This 1304 function must be used to extract the error source from an error 1305 value in order to compare it with the ‘GPG_ERR_SOURCE_*’ error 1306 source macros. 1307 1308 -- Function: static inline gpgme_error_t gpgme_err_make 1309 (gpgme_err_source_t SOURCE, gpgme_err_code_t CODE) 1310 The static inline function ‘gpgme_err_make’ returns the error value 1311 consisting of the error source SOURCE and the error code CODE. 1312 1313 This function can be used in callback functions to construct an 1314 error value to return it to the library. 1315 1316 -- Function: static inline gpgme_error_t gpgme_error 1317 (gpgme_err_code_t CODE) 1318 The static inline function ‘gpgme_error’ returns the error value 1319 consisting of the default error source and the error code CODE. 1320 1321 For GPGME applications, the default error source is 1322 ‘GPG_ERR_SOURCE_USER_1’. You can define ‘GPGME_ERR_SOURCE_DEFAULT’ 1323 before including ‘gpgme.h’ to change this default. 1324 1325 This function can be used in callback functions to construct an 1326 error value to return it to the library. 1327 1328 The ‘libgpg-error’ library provides error codes for all system error 1329numbers it knows about. If ERR is an unknown error number, the error 1330code ‘GPG_ERR_UNKNOWN_ERRNO’ is used. The following functions can be 1331used to construct error values from system errnor numbers. 1332 1333 -- Function: gpgme_error_t gpgme_err_make_from_errno 1334 (gpgme_err_source_t SOURCE, int ERR) 1335 The function ‘gpgme_err_make_from_errno’ is like ‘gpgme_err_make’, 1336 but it takes a system error like ‘errno’ instead of a 1337 ‘gpgme_err_code_t’ error code. 1338 1339 -- Function: gpgme_error_t gpgme_error_from_errno (int ERR) 1340 The function ‘gpgme_error_from_errno’ is like ‘gpgme_error’, but it 1341 takes a system error like ‘errno’ instead of a ‘gpgme_err_code_t’ 1342 error code. 1343 1344 Sometimes you might want to map system error numbers to error codes 1345directly, or map an error code representing a system error back to the 1346system error number. The following functions can be used to do that. 1347 1348 -- Function: gpgme_err_code_t gpgme_err_code_from_errno (int ERR) 1349 The function ‘gpgme_err_code_from_errno’ returns the error code for 1350 the system error ERR. If ERR is not a known system error, the 1351 function returns ‘GPG_ERR_UNKNOWN_ERRNO’. 1352 1353 -- Function: int gpgme_err_code_to_errno (gpgme_err_code_t ERR) 1354 The function ‘gpgme_err_code_to_errno’ returns the system error for 1355 the error code ERR. If ERR is not an error code representing a 1356 system error, or if this system error is not defined on this 1357 system, the function returns ‘0’. 1358 1359 1360File: gpgme.info, Node: Error Sources, Next: Error Codes, Prev: Error Values, Up: Error Handling 1361 13625.2 Error Sources 1363================= 1364 1365The library ‘libgpg-error’ defines an error source for every component 1366of the GnuPG system. The error source part of an error value is not 1367well defined. As such it is mainly useful to improve the diagnostic 1368error message for the user. 1369 1370 If the error code part of an error value is ‘0’, the whole error 1371value will be ‘0’. In this case the error source part is of course 1372‘GPG_ERR_SOURCE_UNKNOWN’. 1373 1374 The list of error sources that might occur in applications using 1375GPGME is: 1376 1377‘GPG_ERR_SOURCE_UNKNOWN’ 1378 The error source is not known. The value of this error source is 1379 ‘0’. 1380 1381‘GPG_ERR_SOURCE_GPGME’ 1382 The error source is GPGME itself. This is the default for errors 1383 that occur in the GPGME library. 1384 1385‘GPG_ERR_SOURCE_GPG’ 1386 The error source is GnuPG, which is the crypto engine used for the 1387 OpenPGP protocol. 1388 1389‘GPG_ERR_SOURCE_GPGSM’ 1390 The error source is GPGSM, which is the crypto engine used for the 1391 CMS protocol. 1392 1393‘GPG_ERR_SOURCE_GCRYPT’ 1394 The error source is ‘libgcrypt’, which is used by crypto engines to 1395 perform cryptographic operations. 1396 1397‘GPG_ERR_SOURCE_GPGAGENT’ 1398 The error source is ‘gpg-agent’, which is used by crypto engines to 1399 perform operations with the secret key. 1400 1401‘GPG_ERR_SOURCE_PINENTRY’ 1402 The error source is ‘pinentry’, which is used by ‘gpg-agent’ to 1403 query the passphrase to unlock a secret key. 1404 1405‘GPG_ERR_SOURCE_SCD’ 1406 The error source is the SmartCard Daemon, which is used by 1407 ‘gpg-agent’ to delegate operations with the secret key to a 1408 SmartCard. 1409 1410‘GPG_ERR_SOURCE_KEYBOX’ 1411 The error source is ‘libkbx’, a library used by the crypto engines 1412 to manage local keyrings. 1413 1414‘GPG_ERR_SOURCE_USER_1’ 1415‘GPG_ERR_SOURCE_USER_2’ 1416‘GPG_ERR_SOURCE_USER_3’ 1417‘GPG_ERR_SOURCE_USER_4’ 1418 These error sources are not used by any GnuPG component and can be 1419 used by other software. For example, applications using GPGME can 1420 use them to mark error values coming from callback handlers. Thus 1421 ‘GPG_ERR_SOURCE_USER_1’ is the default for errors created with 1422 ‘gpgme_error’ and ‘gpgme_error_from_errno’, unless you define 1423 ‘GPGME_ERR_SOURCE_DEFAULT’ before including ‘gpgme.h’. 1424 1425 1426File: gpgme.info, Node: Error Codes, Next: Error Strings, Prev: Error Sources, Up: Error Handling 1427 14285.3 Error Codes 1429=============== 1430 1431The library ‘libgpg-error’ defines many error values. Most of them are 1432not used by ‘GPGME’ directly, but might be returned by GPGME because it 1433received them from the crypto engine. The below list only includes such 1434error codes that have a specific meaning in ‘GPGME’, or which are so 1435common that you should know about them. 1436 1437‘GPG_ERR_EOF’ 1438 This value indicates the end of a list, buffer or file. 1439 1440‘GPG_ERR_NO_ERROR’ 1441 This value indicates success. The value of this error code is ‘0’. 1442 Also, it is guaranteed that an error value made from the error code 1443 ‘0’ will be ‘0’ itself (as a whole). This means that the error 1444 source information is lost for this error code, however, as this 1445 error code indicates that no error occurred, this is generally not 1446 a problem. 1447 1448‘GPG_ERR_GENERAL’ 1449 This value means that something went wrong, but either there is not 1450 enough information about the problem to return a more useful error 1451 value, or there is no separate error value for this type of 1452 problem. 1453 1454‘GPG_ERR_ENOMEM’ 1455 This value means that an out-of-memory condition occurred. 1456 1457‘GPG_ERR_E...’ 1458 System errors are mapped to GPG_ERR_FOO where FOO is the symbol for 1459 the system error. 1460 1461‘GPG_ERR_INV_VALUE’ 1462 This value means that some user provided data was out of range. 1463 This can also refer to objects. For example, if an empty 1464 ‘gpgme_data_t’ object was expected, but one containing data was 1465 provided, this error value is returned. 1466 1467‘GPG_ERR_UNUSABLE_PUBKEY’ 1468 This value means that some recipients for a message were invalid. 1469 1470‘GPG_ERR_UNUSABLE_SECKEY’ 1471 This value means that some signers were invalid. 1472 1473‘GPG_ERR_NO_DATA’ 1474 This value means that a ‘gpgme_data_t’ object which was expected to 1475 have content was found empty. 1476 1477‘GPG_ERR_CONFLICT’ 1478 This value means that a conflict of some sort occurred. 1479 1480‘GPG_ERR_NOT_IMPLEMENTED’ 1481 This value indicates that the specific function (or operation) is 1482 not implemented. This error should never happen. It can only 1483 occur if you use certain values or configuration options which do 1484 not work, but for which we think that they should work at some 1485 later time. 1486 1487‘GPG_ERR_DECRYPT_FAILED’ 1488 This value indicates that a decryption operation was unsuccessful. 1489 1490‘GPG_ERR_BAD_PASSPHRASE’ 1491 This value means that the user did not provide a correct passphrase 1492 when requested. 1493 1494‘GPG_ERR_CANCELED’ 1495 This value means that the operation was canceled. 1496 1497‘GPG_ERR_INV_ENGINE’ 1498 This value means that the engine that implements the desired 1499 protocol is currently not available. This can either be because 1500 the sources were configured to exclude support for this engine, or 1501 because the engine is not installed properly. 1502 1503‘GPG_ERR_AMBIGUOUS_NAME’ 1504 This value indicates that a user ID or other specifier did not 1505 specify a unique key. 1506 1507‘GPG_ERR_WRONG_KEY_USAGE’ 1508 This value indicates that a key is not used appropriately. 1509 1510‘GPG_ERR_CERT_REVOKED’ 1511 This value indicates that a key signature was revoced. 1512 1513‘GPG_ERR_CERT_EXPIRED’ 1514 This value indicates that a key signature expired. 1515 1516‘GPG_ERR_NO_CRL_KNOWN’ 1517 This value indicates that no certificate revocation list is known 1518 for the certificate. 1519 1520‘GPG_ERR_NO_POLICY_MATCH’ 1521 This value indicates that a policy issue occurred. 1522 1523‘GPG_ERR_NO_SECKEY’ 1524 This value indicates that no secret key for the user ID is 1525 available. 1526 1527‘GPG_ERR_MISSING_CERT’ 1528 This value indicates that a key could not be imported because the 1529 issuer certificate is missing. 1530 1531‘GPG_ERR_BAD_CERT_CHAIN’ 1532 This value indicates that a key could not be imported because its 1533 certificate chain is not good, for example it could be too long. 1534 1535‘GPG_ERR_UNSUPPORTED_ALGORITHM’ 1536 This value means a verification failed because the cryptographic 1537 algorithm is not supported by the crypto backend. 1538 1539‘GPG_ERR_BAD_SIGNATURE’ 1540 This value means a verification failed because the signature is 1541 bad. 1542 1543‘GPG_ERR_NO_PUBKEY’ 1544 This value means a verification failed because the public key is 1545 not available. 1546 1547‘GPG_ERR_USER_1’ 1548‘GPG_ERR_USER_2’ 1549‘...’ 1550‘GPG_ERR_USER_16’ 1551 These error codes are not used by any GnuPG component and can be 1552 freely used by other software. Applications using GPGME might use 1553 them to mark specific errors returned by callback handlers if no 1554 suitable error codes (including the system errors) for these errors 1555 exist already. 1556 1557 1558File: gpgme.info, Node: Error Strings, Prev: Error Codes, Up: Error Handling 1559 15605.4 Error Strings 1561================= 1562 1563 -- Function: const char * gpgme_strerror (gpgme_error_t ERR) 1564 The function ‘gpgme_strerror’ returns a pointer to a statically 1565 allocated string containing a description of the error code 1566 contained in the error value ERR. This string can be used to 1567 output a diagnostic message to the user. 1568 1569 This function is not thread safe. Use ‘gpgme_strerror_r’ in 1570 multi-threaded programs. 1571 1572 -- Function: int gpgme_strerror_r (gpgme_error_t ERR, char *BUF, 1573 size_t BUFLEN) 1574 The function ‘gpgme_strerror_r’ returns the error string for ERR in 1575 the user-supplied buffer BUF of size BUFLEN. This function is, in 1576 contrast to ‘gpgme_strerror’, thread-safe if a thread-safe 1577 ‘strerror_r’ function is provided by the system. If the function 1578 succeeds, 0 is returned and BUF contains the string describing the 1579 error. If the buffer was not large enough, ERANGE is returned and 1580 BUF contains as much of the beginning of the error string as fits 1581 into the buffer. 1582 1583 -- Function: const char * gpgme_strsource (gpgme_error_t ERR) 1584 The function ‘gpgme_strerror’ returns a pointer to a statically 1585 allocated string containing a description of the error source 1586 contained in the error value ERR. This string can be used to 1587 output a diagnostic message to the user. 1588 1589 The following example illustrates the use of ‘gpgme_strerror’: 1590 1591 gpgme_ctx_t ctx; 1592 gpgme_error_t err = gpgme_new (&ctx); 1593 if (err) 1594 { 1595 fprintf (stderr, "%s: creating GpgME context failed: %s: %s\n", 1596 argv[0], gpgme_strsource (err), gpgme_strerror (err)); 1597 exit (1); 1598 } 1599 1600 1601File: gpgme.info, Node: Exchanging Data, Next: Contexts, Prev: Error Handling, Up: Top 1602 16036 Exchanging Data 1604***************** 1605 1606A lot of data has to be exchanged between the user and the crypto 1607engine, like plaintext messages, ciphertext, signatures and information 1608about the keys. The technical details about exchanging the data 1609information are completely abstracted by GPGME. The user provides and 1610receives the data via ‘gpgme_data_t’ objects, regardless of the 1611communication protocol between GPGME and the crypto engine in use. 1612 1613 -- Data type: gpgme_data_t 1614 The ‘gpgme_data_t’ type is a handle for a container for generic 1615 data, which is used by GPGME to exchange data with the user. 1616 1617 ‘gpgme_data_t’ objects do not provide notifications on events. It is 1618assumed that read and write operations are blocking until data is 1619available. If this is undesirable, the application must ensure that all 1620GPGME data operations always have data available, for example by using 1621memory buffers or files rather than pipes or sockets. This might be 1622relevant, for example, if the external event loop mechanism is used. 1623 1624 -- Data type: gpgme_off_t 1625 SINCE: 1.4.1 1626 1627 On POSIX platforms the ‘gpgme_off_t’ type is an alias for ‘off_t’; 1628 it may be used interchangeable. On Windows platforms ‘gpgme_off_t’ 1629 is defined as a long (i.e. 32 bit) for 32 bit Windows and as a 64 1630 bit signed integer for 64 bit Windows. 1631 1632 -- Data type: gpgme_ssize_t 1633 The ‘gpgme_ssize_t’ type is an alias for ‘ssize_t’. It has only 1634 been introduced to overcome portability problems pertaining to the 1635 declaration of ‘ssize_t’ by different toolchains. 1636 1637* Menu: 1638 1639* Creating Data Buffers:: Creating new data buffers. 1640* Destroying Data Buffers:: Releasing data buffers. 1641* Manipulating Data Buffers:: Operations on data buffers. 1642 1643 1644File: gpgme.info, Node: Creating Data Buffers, Next: Destroying Data Buffers, Up: Exchanging Data 1645 16466.1 Creating Data Buffers 1647========================= 1648 1649Data objects can be based on memory, files, or callback functions 1650provided by the user. Not all operations are supported by all objects. 1651 1652* Menu: 1653 1654* Memory Based Data Buffers:: Creating memory based data buffers. 1655* File Based Data Buffers:: Creating file based data buffers. 1656* Callback Based Data Buffers:: Creating callback based data buffers. 1657 1658 1659File: gpgme.info, Node: Memory Based Data Buffers, Next: File Based Data Buffers, Up: Creating Data Buffers 1660 16616.1.1 Memory Based Data Buffers 1662------------------------------- 1663 1664Memory based data objects store all data in allocated memory. This is 1665convenient, but only practical for an amount of data that is a fraction 1666of the available physical memory. The data has to be copied from its 1667source and to its destination, which can often be avoided by using one 1668of the other data object 1669 1670 -- Function: gpgme_error_t gpgme_data_new (gpgme_data_t *DH) 1671 The function ‘gpgme_data_new’ creates a new ‘gpgme_data_t’ object 1672 and returns a handle for it in DH. The data object is memory based 1673 and initially empty. 1674 1675 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the data 1676 object was successfully created, ‘GPG_ERR_INV_VALUE’ if DH is not a 1677 valid pointer, and ‘GPG_ERR_ENOMEM’ if not enough memory is 1678 available. 1679 1680 -- Function: gpgme_error_t gpgme_data_new_from_mem (gpgme_data_t *DH, 1681 const char *BUFFER, size_t SIZE, int COPY) 1682 The function ‘gpgme_data_new_from_mem’ creates a new ‘gpgme_data_t’ 1683 object and fills it with SIZE bytes starting from BUFFER. 1684 1685 If COPY is not zero, a private copy of the data is made. If COPY 1686 is zero, the data is taken from the specified buffer as needed, and 1687 the user has to ensure that the buffer remains valid for the whole 1688 life span of the data object. 1689 1690 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the data 1691 object was successfully created, ‘GPG_ERR_INV_VALUE’ if DH or 1692 BUFFER is not a valid pointer, and ‘GPG_ERR_ENOMEM’ if not enough 1693 memory is available. 1694 1695 -- Function: gpgme_error_t gpgme_data_new_from_file (gpgme_data_t *DH, 1696 const char *FILENAME, int COPY) 1697 The function ‘gpgme_data_new_from_file’ creates a new 1698 ‘gpgme_data_t’ object and fills it with the content of the file 1699 FILENAME. 1700 1701 If COPY is not zero, the whole file is read in at initialization 1702 time and the file is not used anymore after that. This is the only 1703 mode supported currently. Later, a value of zero for COPY might 1704 cause all reads to be delayed until the data is needed, but this is 1705 not yet implemented. 1706 1707 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the data 1708 object was successfully created, ‘GPG_ERR_INV_VALUE’ if DH or 1709 FILENAME is not a valid pointer, ‘GPG_ERR_NOT_IMPLEMENTED’ if CODE 1710 is zero, and ‘GPG_ERR_ENOMEM’ if not enough memory is available. 1711 1712 -- Function: gpgme_error_t gpgme_data_new_from_filepart 1713 (gpgme_data_t *DH, const char *FILENAME, FILE *FP, 1714 off_t OFFSET, size_t LENGTH) 1715 The function ‘gpgme_data_new_from_filepart’ creates a new 1716 ‘gpgme_data_t’ object and fills it with a part of the file 1717 specified by FILENAME or FP. 1718 1719 Exactly one of FILENAME and FP must be non-zero, the other must be 1720 zero. The argument that is not zero specifies the file from which 1721 LENGTH bytes are read into the data object, starting from OFFSET. 1722 1723 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the data 1724 object was successfully created, ‘GPG_ERR_INV_VALUE’ if DH and 1725 exactly one of FILENAME and FP is not a valid pointer, and 1726 ‘GPG_ERR_ENOMEM’ if not enough memory is available. 1727 1728 1729File: gpgme.info, Node: File Based Data Buffers, Next: Callback Based Data Buffers, Prev: Memory Based Data Buffers, Up: Creating Data Buffers 1730 17316.1.2 File Based Data Buffers 1732----------------------------- 1733 1734File based data objects operate directly on file descriptors or streams. 1735Only a small amount of data is stored in core at any time, so the size 1736of the data objects is not limited by GPGME. 1737 1738 -- Function: gpgme_error_t gpgme_data_new_from_fd (gpgme_data_t *DH, 1739 int FD) 1740 The function ‘gpgme_data_new_from_fd’ creates a new ‘gpgme_data_t’ 1741 object and uses the file descriptor FD to read from (if used as an 1742 input data object) and write to (if used as an output data object). 1743 1744 When using the data object as an input buffer, the function might 1745 read a bit more from the file descriptor than is actually needed by 1746 the crypto engine in the desired operation because of internal 1747 buffering. 1748 1749 Note that GPGME assumes that the file descriptor is set to blocking 1750 mode. Errors during I/O operations, except for EINTR, are usually 1751 fatal for crypto operations. 1752 1753 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the data 1754 object was successfully created, and ‘GPG_ERR_ENOMEM’ if not enough 1755 memory is available. 1756 1757 -- Function: gpgme_error_t gpgme_data_new_from_stream 1758 (gpgme_data_t *DH, FILE *STREAM) 1759 The function ‘gpgme_data_new_from_stream’ creates a new 1760 ‘gpgme_data_t’ object and uses the I/O stream STREAM to read from 1761 (if used as an input data object) and write to (if used as an 1762 output data object). 1763 1764 When using the data object as an input buffer, the function might 1765 read a bit more from the stream than is actually needed by the 1766 crypto engine in the desired operation because of internal 1767 buffering. 1768 1769 Note that GPGME assumes that the stream is in blocking mode. 1770 Errors during I/O operations, except for EINTR, are usually fatal 1771 for crypto operations. 1772 1773 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the data 1774 object was successfully created, and ‘GPG_ERR_ENOMEM’ if not enough 1775 memory is available. 1776 1777 -- Function: gpgme_error_t gpgme_data_new_from_estream 1778 (gpgme_data_t *DH, gpgrt_stream_t STREAM) 1779 The function ‘gpgme_data_new_from_estream’ creates a new 1780 ‘gpgme_data_t’ object and uses the gpgrt stream STREAM to read from 1781 (if used as an input data object) and write to (if used as an 1782 output data object). 1783 1784 When using the data object as an input buffer, the function might 1785 read a bit more from the stream than is actually needed by the 1786 crypto engine in the desired operation because of internal 1787 buffering. 1788 1789 Note that GPGME assumes that the stream is in blocking mode. 1790 Errors during I/O operations, except for EINTR, are usually fatal 1791 for crypto operations. 1792 1793 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the data 1794 object was successfully created, and ‘GPG_ERR_ENOMEM’ if not enough 1795 memory is available. 1796 1797 1798File: gpgme.info, Node: Callback Based Data Buffers, Prev: File Based Data Buffers, Up: Creating Data Buffers 1799 18006.1.3 Callback Based Data Buffers 1801--------------------------------- 1802 1803If neither memory nor file based data objects are a good fit for your 1804application, you can implement the functions a data object provides 1805yourself and create a data object from these callback functions. 1806 1807 -- Data type: ssize_t (*gpgme_data_read_cb_t) (void *HANDLE, 1808 void *BUFFER, size_t SIZE) 1809 The ‘gpgme_data_read_cb_t’ type is the type of functions which 1810 GPGME calls if it wants to read data from a user-implemented data 1811 object. The function should read up to SIZE bytes from the current 1812 read position into the space starting at BUFFER. The HANDLE is 1813 provided by the user at data object creation time. 1814 1815 Note that GPGME assumes that the read blocks until data is 1816 available. Errors during I/O operations, except for EINTR, are 1817 usually fatal for crypto operations. 1818 1819 The function should return the number of bytes read, 0 on EOF, and 1820 -1 on error. If an error occurs, ERRNO should be set to describe 1821 the type of the error. 1822 1823 -- Data type: ssize_t (*gpgme_data_write_cb_t) (void *HANDLE, 1824 const void *BUFFER, size_t SIZE) 1825 The ‘gpgme_data_write_cb_t’ type is the type of functions which 1826 GPGME calls if it wants to write data to a user-implemented data 1827 object. The function should write up to SIZE bytes to the current 1828 write position from the space starting at BUFFER. The HANDLE is 1829 provided by the user at data object creation time. 1830 1831 Note that GPGME assumes that the write blocks until data is 1832 available. Errors during I/O operations, except for EINTR, are 1833 usually fatal for crypto operations. 1834 1835 The function should return the number of bytes written, and -1 on 1836 error. If an error occurs, ERRNO should be set to describe the 1837 type of the error. 1838 1839 -- Data type: off_t (*gpgme_data_seek_cb_t) (void *HANDLE, 1840 off_t OFFSET, int WHENCE) 1841 The ‘gpgme_data_seek_cb_t’ type is the type of functions which 1842 GPGME calls if it wants to change the current read/write position 1843 in a user-implemented data object, just like the ‘lseek’ function. 1844 1845 The function should return the new read/write position, and -1 on 1846 error. If an error occurs, ERRNO should be set to describe the 1847 type of the error. 1848 1849 -- Data type: void (*gpgme_data_release_cb_t) (void *HANDLE) 1850 The ‘gpgme_data_release_cb_t’ type is the type of functions which 1851 GPGME calls if it wants to destroy a user-implemented data object. 1852 The HANDLE is provided by the user at data object creation time. 1853 1854 -- Data type: struct gpgme_data_cbs 1855 This structure is used to store the data callback interface 1856 functions described above. It has the following members: 1857 1858 ‘gpgme_data_read_cb_t read’ 1859 This is the function called by GPGME to read data from the 1860 data object. It is only required for input data object. 1861 1862 ‘gpgme_data_write_cb_t write’ 1863 This is the function called by GPGME to write data to the data 1864 object. It is only required for output data object. 1865 1866 ‘gpgme_data_seek_cb_t seek’ 1867 This is the function called by GPGME to change the current 1868 read/write pointer in the data object (if available). It is 1869 optional. 1870 1871 ‘gpgme_data_release_cb_t release’ 1872 This is the function called by GPGME to release a data object. 1873 It is optional. 1874 1875 -- Function: gpgme_error_t gpgme_data_new_from_cbs (gpgme_data_t *DH, 1876 gpgme_data_cbs_t CBS, void *HANDLE) 1877 The function ‘gpgme_data_new_from_cbs’ creates a new ‘gpgme_data_t’ 1878 object and uses the user-provided callback functions to operate on 1879 the data object. 1880 1881 The handle HANDLE is passed as first argument to the callback 1882 functions. This can be used to identify this data object. 1883 1884 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the data 1885 object was successfully created, and ‘GPG_ERR_ENOMEM’ if not enough 1886 memory is available. 1887 1888 1889File: gpgme.info, Node: Destroying Data Buffers, Next: Manipulating Data Buffers, Prev: Creating Data Buffers, Up: Exchanging Data 1890 18916.2 Destroying Data Buffers 1892=========================== 1893 1894 -- Function: void gpgme_data_release (gpgme_data_t DH) 1895 The function ‘gpgme_data_release’ destroys the data object with the 1896 handle DH. It releases all associated resources that were not 1897 provided by the user in the first place. 1898 1899 -- Function: char * gpgme_data_release_and_get_mem (gpgme_data_t DH, 1900 size_t *LENGTH) 1901 The function ‘gpgme_data_release_and_get_mem’ is like 1902 ‘gpgme_data_release’, except that it returns the data buffer and 1903 its length that was provided by the object. 1904 1905 The user has to release the buffer with ‘gpgme_free’. In case the 1906 user provided the data buffer in non-copy mode, a copy will be made 1907 for this purpose. 1908 1909 In case an error returns, or there is no suitable data buffer that 1910 can be returned to the user, the function will return ‘NULL’. In 1911 any case, the data object DH is destroyed. 1912 1913 -- Function: void gpgme_free (void *BUFFER) 1914 SINCE: 1.1.1 1915 1916 The function ‘gpgme_free’ releases the memory returned by 1917 ‘gpgme_data_release_and_get_mem’ and ‘gpgme_pubkey_algo_string’. 1918 It should be used instead of the system libraries ‘free’ function 1919 in case different allocators are used by a program. This is often 1920 the case if gpgme is used under Windows as a DLL. 1921 1922 1923File: gpgme.info, Node: Manipulating Data Buffers, Prev: Destroying Data Buffers, Up: Exchanging Data 1924 19256.3 Manipulating Data Buffers 1926============================= 1927 1928Data buffers contain data and meta-data. The following operations can 1929be used to manipulate both. 1930 1931* Menu: 1932 1933* Data Buffer I/O Operations:: I/O operations on data buffers. 1934* Data Buffer Meta-Data:: Meta-data manipulation of data buffers. 1935* Data Buffer Convenience:: Convenience function for data buffers. 1936 1937 1938File: gpgme.info, Node: Data Buffer I/O Operations, Next: Data Buffer Meta-Data, Up: Manipulating Data Buffers 1939 19406.3.1 Data Buffer I/O Operations 1941-------------------------------- 1942 1943 -- Function: ssize_t gpgme_data_read (gpgme_data_t DH, void *BUFFER, 1944 size_t LENGTH) 1945 The function ‘gpgme_data_read’ reads up to LENGTH bytes from the 1946 data object with the handle DH into the space starting at BUFFER. 1947 1948 If no error occurs, the actual amount read is returned. If the end 1949 of the data object is reached, the function returns 0. 1950 1951 In all other cases, the function returns -1 and sets ERRNO. 1952 1953 -- Function: ssize_t gpgme_data_write (gpgme_data_t DH, 1954 const void *BUFFER, size_t SIZE) 1955 The function ‘gpgme_data_write’ writes up to SIZE bytes starting 1956 from BUFFER into the data object with the handle DH at the current 1957 write position. 1958 1959 The function returns the number of bytes actually written, or -1 if 1960 an error occurs. If an error occurs, ERRNO is set. 1961 1962 -- Function: off_t gpgme_data_seek (gpgme_data_t DH, off_t OFFSET, 1963 int WHENCE) 1964 The function ‘gpgme_data_seek’ changes the current read/write 1965 position. 1966 1967 The WHENCE argument specifies how the OFFSET should be interpreted. 1968 It must be one of the following symbolic constants: 1969 1970 ‘SEEK_SET’ 1971 Specifies that OFFSET is a count of characters from the 1972 beginning of the data object. 1973 1974 ‘SEEK_CUR’ 1975 Specifies that OFFSET is a count of characters from the 1976 current file position. This count may be positive or 1977 negative. 1978 1979 ‘SEEK_END’ 1980 Specifies that OFFSET is a count of characters from the end of 1981 the data object. A negative count specifies a position within 1982 the current extent of the data object; a positive count 1983 specifies a position past the current end. If you set the 1984 position past the current end, and actually write data, you 1985 will extend the data object with zeros up to that position. 1986 1987 If successful, the function returns the resulting file position, 1988 measured in bytes from the beginning of the data object. You can 1989 use this feature together with ‘SEEK_CUR’ to read the current 1990 read/write position. 1991 1992 If the function fails, -1 is returned and ERRNO is set. 1993 1994 1995File: gpgme.info, Node: Data Buffer Meta-Data, Next: Data Buffer Convenience, Prev: Data Buffer I/O Operations, Up: Manipulating Data Buffers 1996 19976.3.2 Data Buffer Meta-Data 1998--------------------------- 1999 2000 -- Function: char * gpgme_data_get_file_name (gpgme_data_t DH) 2001 SINCE: 1.1.0 2002 2003 The function ‘gpgme_data_get_file_name’ returns a pointer to a 2004 string containing the file name associated with the data object. 2005 The file name will be stored in the output when encrypting or 2006 signing the data and will be returned to the user when decrypting 2007 or verifying the output data. 2008 2009 If no error occurs, the string containing the file name is 2010 returned. Otherwise, ‘NULL’ will be returned. 2011 2012 -- Function: gpgme_error_t gpgme_data_set_file_name (gpgme_data_t DH, 2013 const char *FILE_NAME) 2014 SINCE: 1.1.0 2015 2016 The function ‘gpgme_data_set_file_name’ sets the file name 2017 associated with the data object. The file name will be stored in 2018 the output when encrypting or signing the data and will be returned 2019 to the user when decrypting or verifying the output data. 2020 2021 The function returns the error code ‘GPG_ERR_INV_VALUE’ if DH is 2022 not a valid pointer and ‘GPG_ERR_ENOMEM’ if not enough memory is 2023 available. 2024 2025 -- Data type: enum gpgme_data_encoding_t 2026 The ‘gpgme_data_encoding_t’ type specifies the encoding of a 2027 ‘gpgme_data_t’ object. For input data objects, the encoding is 2028 useful to give the backend a hint on the type of data. For output 2029 data objects, the encoding can specify the output data format on 2030 certain operations. Please note that not all backends support all 2031 encodings on all operations. The following data types are 2032 available: 2033 2034 ‘GPGME_DATA_ENCODING_NONE’ 2035 This specifies that the encoding is not known. This is the 2036 default for a new data object. The backend will try its best 2037 to detect the encoding automatically. 2038 2039 ‘GPGME_DATA_ENCODING_BINARY’ 2040 This specifies that the data is encoding in binary form; i.e. 2041 there is no special encoding. 2042 2043 ‘GPGME_DATA_ENCODING_BASE64’ 2044 This specifies that the data is encoded using the Base-64 2045 encoding scheme as used by MIME and other protocols. 2046 2047 ‘GPGME_DATA_ENCODING_ARMOR’ 2048 This specifies that the data is encoded in an armored form as 2049 used by OpenPGP and PEM. 2050 2051 ‘GPGME_DATA_ENCODING_MIME’ 2052 SINCE: 1.7.0 2053 2054 This specifies that the data is encoded as a MIME part. 2055 2056 ‘GPGME_DATA_ENCODING_URL’ 2057 SINCE: 1.2.0 2058 2059 The data is a list of linefeed delimited URLs. This is only 2060 useful with ‘gpgme_op_import’. 2061 2062 ‘GPGME_DATA_ENCODING_URL0’ 2063 SINCE: 1.2.0 2064 2065 The data is a list of binary zero delimited URLs. This is 2066 only useful with ‘gpgme_op_import’. 2067 2068 ‘GPGME_DATA_ENCODING_URLESC’ 2069 SINCE: 1.2.0 2070 2071 The data is a list of linefeed delimited URLs with all control 2072 and space characters percent escaped. This mode is is not yet 2073 implemented. 2074 2075 -- Function: gpgme_data_encoding_t gpgme_data_get_encoding 2076 (gpgme_data_t DH) 2077 The function ‘gpgme_data_get_encoding’ returns the encoding of the 2078 data object with the handle DH. If DH is not a valid pointer (e.g. 2079 ‘NULL’) ‘GPGME_DATA_ENCODING_NONE’ is returned. 2080 2081 -- Function: gpgme_error_t gpgme_data_set_encoding 2082 (gpgme_data_t DH, gpgme_data_encoding_t ENC) 2083 The function ‘gpgme_data_set_encoding’ changes the encoding of the 2084 data object with the handle DH to ENC. 2085 2086 -- Function: gpgme_error_t gpgme_data_set_flag (gpgme_data_t DH, 2087 const char *NAME, const char *VALUE) 2088 2089 SINCE: 1.7.0 2090 2091 Some minor properties of the data object can be controlled with 2092 flags set by this function. The properties are identified by the 2093 following values for NAME: 2094 2095 ‘size-hint’ 2096 The value is a decimal number with the length gpgme shall 2097 assume for this data object. This is useful if the data is 2098 provided by callbacks or via file descriptors but the 2099 applications knows the total size of the data. If this is set 2100 the OpenPGP engine may use this to decide on buffer allocation 2101 strategies and to provide a total value for its progress 2102 information. 2103 2104 This function returns ‘0’ on success. 2105 2106 2107File: gpgme.info, Node: Data Buffer Convenience, Prev: Data Buffer Meta-Data, Up: Manipulating Data Buffers 2108 21096.3.3 Data Buffer Convenience Functions 2110--------------------------------------- 2111 2112 -- Data type: enum gpgme_data_type_t 2113 SINCE: 1.4.3 2114 2115 The ‘gpgme_data_type_t’ type is used to return the detected type of 2116 the content of a data buffer. 2117 2118‘GPGME_DATA_TYPE_INVALID’ 2119 This is returned by ‘gpgme_data_identify’ if it was not possible to 2120 identify the data. Reasons for this might be a non-seekable stream 2121 or a memory problem. The value is 0. 2122‘GPGME_DATA_TYPE_UNKNOWN’ 2123 The type of the data is not known. 2124‘GPGME_DATA_TYPE_PGP_SIGNED’ 2125 The data is an OpenPGP signed message. This may be a binary 2126 signature, a detached one or a cleartext signature. 2127‘GPGME_DATA_TYPE_PGP_ENCRYPTED’ 2128 SINCE: 1.7.0 2129 2130 The data is an OpenPGP encrypted message. 2131‘GPGME_DATA_TYPE_PGP_SIGNATURE’ 2132 SINCE: 1.7.0 2133 2134 The data is an OpenPGP detached signature. 2135‘GPGME_DATA_TYPE_PGP_OTHER’ 2136 This is a generic OpenPGP message. In most cases this will be 2137 encrypted data. 2138‘GPGME_DATA_TYPE_PGP_KEY’ 2139 This is an OpenPGP key (private or public). 2140‘GPGME_DATA_TYPE_CMS_SIGNED’ 2141 This is a CMS signed message. 2142‘GPGME_DATA_TYPE_CMS_ENCRYPTED’ 2143 This is a CMS encrypted (enveloped data) message. 2144‘GPGME_DATA_TYPE_CMS_OTHER’ 2145 This is used for other CMS message types. 2146‘GPGME_DATA_TYPE_X509_CERT’ 2147 The data is a X.509 certificate 2148‘GPGME_DATA_TYPE_PKCS12’ 2149 The data is a PKCS#12 message. This is commonly used to exchange 2150 private keys for X.509. 2151 2152 -- Function: gpgme_data_type_t gpgme_data_identify (gpgme_data_t DH) 2153 SINCE: 1.4.3 2154 2155 The function ‘gpgme_data_identify’ returns the type of the data 2156 with the handle DH. If it is not possible to perform the 2157 identification, the function returns zero 2158 (‘GPGME_DATA_TYPE_INVALID’). Note that depending on how the data 2159 object has been created the identification may not be possible or 2160 the data object may change its internal state (file pointer moved). 2161 For file or memory based data object, the state should not change. 2162 2163 2164File: gpgme.info, Node: Contexts, Next: UI Server Protocol, Prev: Exchanging Data, Up: Top 2165 21667 Contexts 2167********** 2168 2169All cryptographic operations in GPGME are performed within a context, 2170which contains the internal state of the operation as well as 2171configuration parameters. By using several contexts you can run several 2172cryptographic operations in parallel, with different configuration. 2173 2174 -- Data type: gpgme_ctx_t 2175 The ‘gpgme_ctx_t’ type is a handle for a GPGME context, which is 2176 used to hold the configuration, status and result of cryptographic 2177 operations. 2178 2179* Menu: 2180 2181* Creating Contexts:: Creating new GPGME contexts. 2182* Destroying Contexts:: Releasing GPGME contexts. 2183* Result Management:: Managing the result of crypto operations. 2184* Context Attributes:: Setting properties of a context. 2185* Key Management:: Managing keys with GPGME. 2186* Crypto Operations:: Using a context for cryptography. 2187* Miscellaneous:: Miscellaneous operations 2188* Run Control:: Controlling how operations are run. 2189 2190 2191File: gpgme.info, Node: Creating Contexts, Next: Destroying Contexts, Up: Contexts 2192 21937.1 Creating Contexts 2194===================== 2195 2196 -- Function: gpgme_error_t gpgme_new (gpgme_ctx_t *CTX) 2197 The function ‘gpgme_new’ creates a new ‘gpgme_ctx_t’ object and 2198 returns a handle for it in CTX. 2199 2200 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the 2201 context was successfully created, ‘GPG_ERR_INV_VALUE’ if CTX is not 2202 a valid pointer, and ‘GPG_ERR_ENOMEM’ if not enough memory is 2203 available. Also, it returns ‘GPG_ERR_NOT_OPERATIONAL’ if 2204 ‘gpgme_check_version’ was not called to initialize GPGME, and 2205 ‘GPG_ERR_SELFTEST_FAILED’ if a selftest failed. Currently, the 2206 only selftest is for Windows MingW32 targets to see if 2207 ‘-mms-bitfields’ was used (as required). 2208 2209 2210File: gpgme.info, Node: Destroying Contexts, Next: Result Management, Prev: Creating Contexts, Up: Contexts 2211 22127.2 Destroying Contexts 2213======================= 2214 2215 -- Function: void gpgme_release (gpgme_ctx_t CTX) 2216 The function ‘gpgme_release’ destroys the context with the handle 2217 CTX and releases all associated resources. 2218 2219 2220File: gpgme.info, Node: Result Management, Next: Context Attributes, Prev: Destroying Contexts, Up: Contexts 2221 22227.3 Result Management 2223===================== 2224 2225The detailed result of an operation is returned in operation-specific 2226structures such as ‘gpgme_decrypt_result_t’. The corresponding 2227retrieval functions such as ‘gpgme_op_decrypt_result’ provide static 2228access to the results after an operation completes. Those structures 2229shall be considered read-only and an application must not allocate such 2230a structure on its own. The following interfaces make it possible to 2231detach a result structure from its associated context and give it a 2232lifetime beyond that of the current operation or context. 2233 2234 -- Function: void gpgme_result_ref (void *RESULT) 2235 SINCE: 1.2.0 2236 2237 The function ‘gpgme_result_ref’ acquires an additional reference 2238 for the result RESULT, which may be of any type ‘gpgme_*_result_t’. 2239 As long as the user holds a reference, the result structure is 2240 guaranteed to be valid and unmodified. 2241 2242 -- Function: void gpgme_result_unref (void *RESULT) 2243 SINCE: 1.2.0 2244 2245 The function ‘gpgme_result_unref’ releases a reference for the 2246 result RESULT. If this was the last reference, the result 2247 structure will be destroyed and all resources associated to it will 2248 be released. 2249 2250 Note that a context may hold its own references to result structures, 2251typically until the context is destroyed or the next operation is 2252started. In fact, these references are accessed through the 2253‘gpgme_op_*_result’ functions. 2254 2255 2256File: gpgme.info, Node: Context Attributes, Next: Key Management, Prev: Result Management, Up: Contexts 2257 22587.4 Context Attributes 2259====================== 2260 2261* Menu: 2262 2263* Protocol Selection:: Selecting the protocol used by a context. 2264* Crypto Engine:: Configuring the crypto engine. 2265* Setting the Sender:: How to tell the engine the sender. 2266* ASCII Armor:: Requesting ASCII armored output. 2267* Text Mode:: Choosing canonical text mode. 2268* Offline Mode:: Choosing offline mode. 2269* Pinentry Mode:: Choosing the pinentry mode. 2270* Included Certificates:: Including a number of certificates. 2271* Key Listing Mode:: Selecting key listing mode. 2272* Passphrase Callback:: Getting the passphrase from the user. 2273* Progress Meter Callback:: Being informed about the progress. 2274* Status Message Callback:: Status messages received from gpg. 2275* Context Flags:: Additional flags for a context. 2276* Locale:: Setting the locale of a context. 2277* Additional Logs:: Additional logs of a context. 2278 2279 2280File: gpgme.info, Node: Protocol Selection, Next: Crypto Engine, Up: Context Attributes 2281 22827.4.1 Protocol Selection 2283------------------------ 2284 2285 -- Function: gpgme_error_t gpgme_set_protocol (gpgme_ctx_t CTX, 2286 gpgme_protocol_t PROTO) 2287 The function ‘gpgme_set_protocol’ sets the protocol used within the 2288 context CTX to PROTO. All crypto operations will be performed by 2289 the crypto engine configured for that protocol. *Note Protocols 2290 and Engines::. 2291 2292 Setting the protocol with ‘gpgme_set_protocol’ does intentionally 2293 not check if the crypto engine for that protocol is available and 2294 installed correctly. *Note Engine Version Check::. 2295 2296 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the 2297 protocol could be set successfully, and ‘GPG_ERR_INV_VALUE’ if 2298 PROTOCOL is not a valid protocol. 2299 2300 -- Function: gpgme_protocol_t gpgme_get_protocol (gpgme_ctx_t CTX) 2301 The function ‘gpgme_get_protocol’ retrieves the protocol currently 2302 use with the context CTX. 2303 2304 2305File: gpgme.info, Node: Crypto Engine, Next: Setting the Sender, Prev: Protocol Selection, Up: Context Attributes 2306 23077.4.2 Crypto Engine 2308------------------- 2309 2310The following functions can be used to set and retrieve the 2311configuration of the crypto engines of a specific context. The default 2312can also be retrieved without any particular context. *Note Engine 2313Information::. The default can also be changed globally. *Note Engine 2314Configuration::. 2315 2316 -- Function: gpgme_engine_info_t gpgme_ctx_get_engine_info 2317 (gpgme_ctx_t CTX) 2318 SINCE: 1.1.0 2319 2320 The function ‘gpgme_ctx_get_engine_info’ returns a linked list of 2321 engine info structures. Each info structure describes the 2322 configuration of one configured backend, as used by the context 2323 CTX. 2324 2325 The result is valid until the next invocation of 2326 ‘gpgme_ctx_set_engine_info’ for this particular context. 2327 2328 This function can not fail. 2329 2330 -- Function: gpgme_error_t gpgme_ctx_set_engine_info (gpgme_ctx_t CTX, 2331 gpgme_protocol_t PROTO, const char *FILE_NAME, 2332 const char *HOME_DIR) 2333 SINCE: 1.1.0 2334 2335 The function ‘gpgme_ctx_set_engine_info’ changes the configuration 2336 of the crypto engine implementing the protocol PROTO for the 2337 context CTX. 2338 2339 FILE_NAME is the file name of the executable program implementing 2340 this protocol, and HOME_DIR is the directory name of the 2341 configuration directory for this crypto engine. If HOME_DIR is 2342 ‘NULL’, the engine’s default will be used. 2343 2344 Currently this function must be used before starting the first 2345 crypto operation. It is unspecified if and when the changes will 2346 take effect if the function is called after starting the first 2347 operation on the context CTX. 2348 2349 This function returns the error code ‘GPG_ERR_NO_ERROR’ if 2350 successful, or an error code on failure. 2351 2352 2353File: gpgme.info, Node: Setting the Sender, Next: ASCII Armor, Prev: Crypto Engine, Up: Context Attributes 2354 23557.4.3 How to tell the engine the sender. 2356---------------------------------------- 2357 2358Some engines can make use of the sender’s address, for example to figure 2359out the best user id in certain trust models. For verification and 2360signing of mails, it is thus suggested to let the engine know the sender 2361("From:") address. GPGME provides two functions to accomplish that. 2362Note that the esoteric use of multiple "From:" addresses is not 2363supported. 2364 2365 -- Function: gpgme_error_t gpgme_set_sender (gpgme_ctx_t CTX, 2366 int ADDRESS) 2367 2368 SINCE: 1.8.0 2369 2370 The function ‘gpgme_set_sender’ specifies the sender address for 2371 use in sign and verify operations. ADDRESS is expected to be the 2372 “addr-spec” part of an address but my also be a complete mailbox 2373 address, in which case this function extracts the “addr-spec” from 2374 it. Using ‘NULL’ for ADDRESS clears the sender address. 2375 2376 The function returns 0 on success or an error code on failure. The 2377 most likely failure is that no valid “addr-spec” was found in 2378 ADDRESS. 2379 2380 -- Function: const char * gpgme_get_sender (gpgme_ctx_t CTX) 2381 2382 SINCE: 1.8.0 2383 2384 The function ‘gpgme_get_sender’ returns the current sender address 2385 from the context, or NULL if none was set. The returned value is 2386 valid as long as the CTX is valid and ‘gpgme_set_sender’ has not 2387 been called again. 2388 2389 2390File: gpgme.info, Node: ASCII Armor, Next: Text Mode, Prev: Setting the Sender, Up: Context Attributes 2391 23927.4.4 ASCII Armor 2393----------------- 2394 2395 -- Function: void gpgme_set_armor (gpgme_ctx_t CTX, int YES) 2396 The function ‘gpgme_set_armor’ specifies if the output should be 2397 ASCII armored. By default, output is not ASCII armored. 2398 2399 ASCII armored output is disabled if YES is zero, and enabled 2400 otherwise. 2401 2402 -- Function: int gpgme_get_armor (gpgme_ctx_t CTX) 2403 The function ‘gpgme_get_armor’ returns 1 if the output is ASCII 2404 armored, and ‘0’ if it is not, or if CTX is not a valid pointer. 2405 2406 2407File: gpgme.info, Node: Text Mode, Next: Offline Mode, Prev: ASCII Armor, Up: Context Attributes 2408 24097.4.5 Text Mode 2410--------------- 2411 2412 -- Function: void gpgme_set_textmode (gpgme_ctx_t CTX, int YES) 2413 The function ‘gpgme_set_textmode’ specifies if canonical text mode 2414 should be used. By default, text mode is not used. 2415 2416 Text mode is for example used for the RFC2015 signatures; note that 2417 the updated RFC 3156 mandates that the mail user agent does some 2418 preparations so that text mode is not needed anymore. 2419 2420 This option is only relevant to the OpenPGP crypto engine, and 2421 ignored by all other engines. 2422 2423 Canonical text mode is disabled if YES is zero, and enabled 2424 otherwise. 2425 2426 -- Function: int gpgme_get_textmode (gpgme_ctx_t CTX) 2427 The function ‘gpgme_get_textmode’ returns 1 if canonical text mode 2428 is enabled, and ‘0’ if it is not, or if CTX is not a valid pointer. 2429 2430 2431File: gpgme.info, Node: Offline Mode, Next: Pinentry Mode, Prev: Text Mode, Up: Context Attributes 2432 24337.4.6 Offline Mode 2434------------------ 2435 2436 -- Function: void gpgme_set_offline (gpgme_ctx_t CTX, int YES) 2437 SINCE: 1.6.0 2438 2439 The function ‘gpgme_set_offline’ specifies if offline mode should 2440 be used. Offline mode is disabled if YES is zero, and enabled 2441 otherwise. By default, offline mode is disabled. 2442 2443 The details of the offline mode depend on the used protocol and its 2444 backend engine. It may eventually be extended to be more stricter 2445 and for example completely disable the use of Dirmngr for any 2446 engine. 2447 2448 For the CMS protocol the offline mode specifies whether Dirmngr 2449 shall be used to do additional validation that might require 2450 connecting external services (e.g. CRL / OCSP checks). Here the 2451 offline mode only affects the keylist mode 2452 ‘GPGME_KEYLIST_MODE_VALIDATE’. 2453 2454 For the OpenPGP protocol offline mode entirely disables the use of 2455 the Dirmngr and will thus guarantee that no network connections are 2456 done as part of an operation on this context. It has only an 2457 effect with GnuPG versions 2.1.23 or later. 2458 2459 For all other protocols the offline mode is currently ignored. 2460 2461 -- Function: int gpgme_get_offline (gpgme_ctx_t CTX) 2462 SINCE: 1.6.0 2463 2464 The function ‘gpgme_get_offline’ returns 1 if offline mode is 2465 enabled, and ‘0’ if it is not, or if CTX is not a valid pointer. 2466 2467 2468File: gpgme.info, Node: Pinentry Mode, Next: Included Certificates, Prev: Offline Mode, Up: Context Attributes 2469 24707.4.7 Pinentry Mode 2471------------------- 2472 2473 -- Function: gpgme_error_t gpgme_set_pinentry_mode (gpgme_ctx_t CTX, 2474 gpgme_pinentry_mode_t MODE) 2475 2476 SINCE: 1.4.0 2477 2478 The function ‘gpgme_set_pinentry_mode’ specifies the pinentry mode 2479 to be used. 2480 2481 For GnuPG >= 2.1 this option is required to be set to 2482 ‘GPGME_PINENTRY_MODE_LOOPBACK’ to enable the passphrase callback 2483 mechanism in GPGME through ‘gpgme_set_passphrase_cb’. 2484 2485 -- Function: gpgme_pinentry_mode_t gpgme_get_pinentry_mode 2486 (gpgme_ctx_t CTX) 2487 SINCE: 1.4.0 2488 2489 The function ‘gpgme_get_pinenty_mode’ returns the mode set for the 2490 context. 2491 2492 -- Data type: enum gpgme_pinentry_mode_t 2493 SINCE: 1.4.0 2494 2495 The ‘gpgme_minentry_mode_t’ type specifies the set of possible 2496 pinentry modes that are supported by GPGME if GnuPG >= 2.1 is used. 2497 The following modes are supported: 2498 2499 ‘GPGME_PINENTRY_MODE_DEFAULT’ 2500 SINCE: 1.4.0 2501 2502 Use the default of the agent, which is ask. 2503 2504 ‘GPGME_PINENTRY_MODE_ASK’ 2505 SINCE: 1.4.0 2506 2507 Force the use of the Pinentry. 2508 2509 ‘GPGME_PINENTRY_MODE_CANCEL’ 2510 SINCE: 1.4.0 2511 2512 Emulate use of Pinentry’s cancel button. 2513 2514 ‘GPGME_PINENTRY_MODE_ERROR’ 2515 SINCE: 1.4.0 2516 2517 Return a Pinentry error ‘No Pinentry’. 2518 2519 ‘GPGME_PINENTRY_MODE_LOOPBACK’ 2520 SINCE: 1.4.0 2521 2522 Redirect Pinentry queries to the caller. This enables the use 2523 of ‘gpgme_set_passphrase_cb’ because pinentry queries are 2524 redirected to gpgme. 2525 2526 Note: For 2.1.0 - 2.1.12 this mode requires 2527 ‘allow-loopback-pinentry’ to be enabled in the 2528 ‘gpg-agent.conf’ or an agent started with that option. 2529 2530 2531File: gpgme.info, Node: Included Certificates, Next: Key Listing Mode, Prev: Pinentry Mode, Up: Context Attributes 2532 25337.4.8 Included Certificates 2534--------------------------- 2535 2536 -- Function: void gpgme_set_include_certs (gpgme_ctx_t CTX, 2537 int NR_OF_CERTS) 2538 The function ‘gpgme_set_include_certs’ specifies how many 2539 certificates should be included in an S/MIME signed message. By 2540 default, only the sender’s certificate is included. The possible 2541 values of NR_OF_CERTS are: 2542 2543 ‘GPGME_INCLUDE_CERTS_DEFAULT’ 2544 SINCE: 1.0.3 2545 2546 Fall back to the default of the crypto backend. This is the 2547 default for GPGME. 2548 ‘-2’ 2549 Include all certificates except the root certificate. 2550 ‘-1’ 2551 Include all certificates. 2552 ‘0’ 2553 Include no certificates. 2554 ‘1’ 2555 Include the sender’s certificate only. 2556 ‘n’ 2557 Include the first n certificates of the certificates path, 2558 starting from the sender’s certificate. The number ‘n’ must 2559 be positive. 2560 2561 Values of NR_OF_CERTS smaller than -2 are undefined. 2562 2563 This option is only relevant to the CMS crypto engine, and ignored 2564 by all other engines. 2565 2566 -- Function: int gpgme_get_include_certs (gpgme_ctx_t CTX) 2567 The function ‘gpgme_get_include_certs’ returns the number of 2568 certificates to include into an S/MIME signed message. 2569 2570 2571File: gpgme.info, Node: Key Listing Mode, Next: Passphrase Callback, Prev: Included Certificates, Up: Context Attributes 2572 25737.4.9 Key Listing Mode 2574---------------------- 2575 2576 -- Function: gpgme_error_t gpgme_set_keylist_mode (gpgme_ctx_t CTX, 2577 gpgme_keylist_mode_t MODE) 2578 The function ‘gpgme_set_keylist_mode’ changes the default behaviour 2579 of the key listing functions. The value in MODE is a bitwise-or 2580 combination of one or multiple of the following bit values: 2581 2582 ‘GPGME_KEYLIST_MODE_LOCAL’ 2583 The ‘GPGME_KEYLIST_MODE_LOCAL’ symbol specifies that the local 2584 keyring should be searched for keys in the keylisting 2585 operation. This is the default. 2586 2587 Using only this option results in a ‘--list-keys’. 2588 2589 ‘GPGME_KEYLIST_MODE_EXTERN’ 2590 The ‘GPGME_KEYLIST_MODE_EXTERN’ symbol specifies that an 2591 external source should be searched for keys in the keylisting 2592 operation. The type of external source is dependent on the 2593 crypto engine used and whether it is combined with 2594 ‘GPGME_KEYLIST_MODE_LOCAL’. For example, it can be a remote 2595 keyserver or LDAP certificate server. 2596 2597 Using only this option results in a ‘--search-keys’ for 2598 ‘GPGME_PROTOCOL_OpenPGP’ and something similar to 2599 ‘--list-external-keys’ for ‘GPGME_PROTOCOL_CMS’. 2600 2601 ‘GPGME_KEYLIST_MODE_LOCATE’ 2602 This is a shortcut for the combination of 2603 ‘GPGME_KEYLIST_MODE_LOCAL’ and ‘GPGME_KEYLIST_MODE_EXTERN’, 2604 which results in a ‘--locate-keys’ for 2605 ‘GPGME_PROTOCOL_OpenPGP’. 2606 2607 ‘GPGME_KEYLIST_MODE_SIGS’ 2608 The ‘GPGME_KEYLIST_MODE_SIGS’ symbol specifies that the key 2609 signatures should be included in the listed keys. 2610 2611 ‘GPGME_KEYLIST_MODE_SIG_NOTATIONS’ 2612 SINCE: 1.1.1 2613 2614 The ‘GPGME_KEYLIST_MODE_SIG_NOTATIONS’ symbol specifies that 2615 the signature notations on key signatures should be included 2616 in the listed keys. This only works if 2617 ‘GPGME_KEYLIST_MODE_SIGS’ is also enabled. 2618 2619 ‘GPGME_KEYLIST_MODE_WITH_TOFU’ 2620 SINCE: 1.7.0 2621 2622 The ‘GPGME_KEYLIST_MODE_WITH_TOFU’ symbol specifies that 2623 information pertaining to the TOFU trust model should be 2624 included in the listed keys. 2625 2626 ‘GPGME_KEYLIST_MODE_WITH_KEYGRIP’ 2627 SINCE: 1.14.0 2628 2629 The ‘GPGME_KEYLIST_MODE_WITH_KEYRIP’ symbol specifies that the 2630 keygrip is always included in the listing. The default 2631 depends on the version of the backend and the used protocol. 2632 2633 ‘GPGME_KEYLIST_MODE_WITH_SECRET’ 2634 SINCE: 1.5.1 2635 2636 The ‘GPGME_KEYLIST_MODE_WITH_SECRET’ returns information about 2637 the presence of a corresponding secret key in a public key 2638 listing. A public key listing with this mode is slower than a 2639 standard listing but can be used instead of a second run to 2640 list the secret keys. This is only supported for GnuPG 2641 versions >= 2.1. Note that using this option also makes sure 2642 that the keygrip is available in the output. 2643 2644 ‘GPGME_KEYLIST_MODE_EPHEMERAL’ 2645 SINCE: 1.2.0 2646 2647 The ‘GPGME_KEYLIST_MODE_EPHEMERAL’ symbol specifies that keys 2648 flagged as ephemeral are included in the listing. 2649 2650 ‘GPGME_KEYLIST_MODE_VALIDATE’ 2651 SINCE: 0.4.5 2652 2653 The ‘GPGME_KEYLIST_MODE_VALIDATE’ symbol specifies that the 2654 backend should do key or certificate validation and not just 2655 get the validity information from an internal cache. This 2656 might be an expensive operation and is in general not useful. 2657 Currently only implemented for the S/MIME backend and ignored 2658 for other backends. 2659 2660 At least one of ‘GPGME_KEYLIST_MODE_LOCAL’ and 2661 ‘GPGME_KEYLIST_MODE_EXTERN’ must be specified. For future binary 2662 compatibility, you should get the current mode with 2663 ‘gpgme_get_keylist_mode’ and modify it by setting or clearing the 2664 appropriate bits, and then using that calculated value in the 2665 ‘gpgme_set_keylisting_mode’ operation. This will leave all other 2666 bits in the mode value intact (in particular those that are not 2667 used in the current version of the library). 2668 2669 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the mode 2670 could be set correctly, and ‘GPG_ERR_INV_VALUE’ if CTX is not a 2671 valid pointer or MODE is not a valid mode. 2672 2673 -- Function: gpgme_keylist_mode_t gpgme_get_keylist_mode 2674 (gpgme_ctx_t CTX) 2675 The function ‘gpgme_get_keylist_mode’ returns the current key 2676 listing mode of the context CTX. This value can then be modified 2677 and used in a subsequent ‘gpgme_set_keylist_mode’ operation to only 2678 affect the desired bits (and leave all others intact). 2679 2680 The function returns 0 if CTX is not a valid pointer, and the 2681 current mode otherwise. Note that 0 is not a valid mode value. 2682 2683 2684File: gpgme.info, Node: Passphrase Callback, Next: Progress Meter Callback, Prev: Key Listing Mode, Up: Context Attributes 2685 26867.4.10 Passphrase Callback 2687-------------------------- 2688 2689 -- Data type: gpgme_error_t (*gpgme_passphrase_cb_t)(void *HOOK, const 2690 char *UID_HINT, const char *PASSPHRASE_INFO, int PREV_WAS_BAD, 2691 int FD) 2692 The ‘gpgme_passphrase_cb_t’ type is the type of functions usable as 2693 passphrase callback function. 2694 2695 The argument UID_HINT might contain a string that gives an 2696 indication for which user ID the passphrase is required. If this 2697 is not available, or not applicable (in the case of symmetric 2698 encryption, for example), UID_HINT will be ‘NULL’. 2699 2700 The argument PASSPHRASE_INFO, if not ‘NULL’, will give further 2701 information about the context in which the passphrase is required. 2702 This information is engine and operation specific. 2703 2704 If this is the repeated attempt to get the passphrase, because 2705 previous attempts failed, then PREV_WAS_BAD is 1, otherwise it will 2706 be 0. 2707 2708 The user must write the passphrase, followed by a newline 2709 character, to the file descriptor FD. The function 2710 ‘gpgme_io_writen’ should be used for the write operation. Note 2711 that if the user returns 0 to indicate success, the user must at 2712 least write a newline character before returning from the callback. 2713 2714 If an error occurs, return the corresponding ‘gpgme_error_t’ value. 2715 You can use the error code ‘GPG_ERR_CANCELED’ to abort the 2716 operation. Otherwise, return ‘0’. 2717 2718 Note: The passphrase_cb only works with GnuPG 1.x and 2.1.x and not 2719 with the 2.0.x series. See ‘gpgme_set_pinentry_mode’ for more 2720 details on 2.1.x usage. 2721 2722 -- Function: void gpgme_set_passphrase_cb (gpgme_ctx_t CTX, 2723 gpgme_passphrase_cb_t PASSFUNC, void *HOOK_VALUE) 2724 The function ‘gpgme_set_passphrase_cb’ sets the function that is 2725 used when a passphrase needs to be provided by the user to 2726 PASSFUNC. The function PASSFUNC needs to implemented by the user, 2727 and whenever it is called, it is called with its first argument 2728 being HOOK_VALUE. By default, no passphrase callback function is 2729 set. 2730 2731 Not all crypto engines require this callback to retrieve the 2732 passphrase. It is better if the engine retrieves the passphrase 2733 from a trusted agent (a daemon process), rather than having each 2734 user to implement their own passphrase query. Some engines do not 2735 even support an external passphrase callback at all, in this case 2736 the error code ‘GPG_ERR_NOT_SUPPORTED’ is returned. 2737 2738 For GnuPG >= 2.1 the pinentry mode has to be set to 2739 ‘GPGME_PINENTRY_MODE_LOOPBACK’ to enable the passphrase callback. 2740 See ‘gpgme_set_pinentry_mode’. 2741 2742 The user can disable the use of a passphrase callback function by 2743 calling ‘gpgme_set_passphrase_cb’ with PASSFUNC being ‘NULL’. 2744 2745 -- Function: void gpgme_get_passphrase_cb (gpgme_ctx_t CTX, 2746 gpgme_passphrase_cb_t *PASSFUNC, void **HOOK_VALUE) 2747 The function ‘gpgme_get_passphrase_cb’ returns the function that is 2748 used when a passphrase needs to be provided by the user in 2749 *PASSFUNC, and the first argument for this function in *HOOK_VALUE. 2750 If no passphrase callback is set, or CTX is not a valid pointer, 2751 ‘NULL’ is returned in both variables. 2752 2753 PASSFUNC or HOOK_VALUE can be ‘NULL’. In this case, the 2754 corresponding value will not be returned. 2755 2756 2757File: gpgme.info, Node: Progress Meter Callback, Next: Status Message Callback, Prev: Passphrase Callback, Up: Context Attributes 2758 27597.4.11 Progress Meter Callback 2760------------------------------ 2761 2762 -- Data type: void (*gpgme_progress_cb_t)(void *HOOK, const char *WHAT, 2763 int TYPE, int CURRENT, int TOTAL) 2764 The ‘gpgme_progress_cb_t’ type is the type of functions usable as 2765 progress callback function. 2766 2767 The arguments are specific to the crypto engine. More information 2768 about the progress information returned from the GnuPG engine can 2769 be found in the GnuPG source code in the file ‘doc/DETAILS’ in the 2770 section PROGRESS. 2771 2772 -- Function: void gpgme_set_progress_cb (gpgme_ctx_t CTX, 2773 gpgme_progress_cb_t PROGFUNC, void *HOOK_VALUE) 2774 The function ‘gpgme_set_progress_cb’ sets the function that is used 2775 when progress information about a cryptographic operation is 2776 available. The function PROGFUNC needs to implemented by the user, 2777 and whenever it is called, it is called with its first argument 2778 being HOOK_VALUE. By default, no progress callback function is 2779 set. 2780 2781 Setting a callback function allows an interactive program to 2782 display progress information about a long operation to the user. 2783 2784 The user can disable the use of a progress callback function by 2785 calling ‘gpgme_set_progress_cb’ with PROGFUNC being ‘NULL’. 2786 2787 -- Function: void gpgme_get_progress_cb (gpgme_ctx_t CTX, 2788 gpgme_progress_cb_t *PROGFUNC, void **HOOK_VALUE) 2789 The function ‘gpgme_get_progress_cb’ returns the function that is 2790 used to inform the user about the progress made in *PROGFUNC, and 2791 the first argument for this function in *HOOK_VALUE. If no 2792 progress callback is set, or CTX is not a valid pointer, ‘NULL’ is 2793 returned in both variables. 2794 2795 PROGFUNC or HOOK_VALUE can be ‘NULL’. In this case, the 2796 corresponding value will not be returned. 2797 2798 2799File: gpgme.info, Node: Status Message Callback, Next: Context Flags, Prev: Progress Meter Callback, Up: Context Attributes 2800 28017.4.12 Status Message Callback 2802------------------------------ 2803 2804 -- Data type: gpgme_error_t (*gpgme_status_cb_t)(void *HOOK, const char 2805 *KEYWORD, const char *ARGS) 2806 The ‘gpgme_status_cb_t’ type is the type of function usable as a 2807 status message callback function. 2808 2809 The argument KEYWORD is the name of the status message while the 2810 ARGS argument contains any arguments for the status message. 2811 2812 If an error occurs, return the corresponding ‘gpgme_error_t’ value. 2813 Otherwise, return ‘0’. 2814 2815 -- Function: void gpgme_set_status_cb (gpgme_ctx_t CTX, 2816 gpgme_status_cb_t STATUSFUNC, void *HOOK_VALUE) 2817 SINCE: 1.6.0 2818 2819 The function ‘gpgme_set_status_cb’ sets the function that is used 2820 when a status message is received from gpg to STATUSFUNC. The 2821 function STATUSFUNC needs to be implemented by the user, and 2822 whenever it is called, it is called with its first argument being 2823 HOOK_VALUE. By default, no status message callback function is 2824 set. 2825 2826 The user can disable the use of a status message callback function 2827 by calling ‘gpgme_set_status_cb’ with STATUSFUNC being ‘NULL’. 2828 2829 -- Function: void gpgme_get_status_cb (gpgme_ctx_t CTX, 2830 gpgme_status_cb_t *STATUSFUNC, void **HOOK_VALUE) 2831 SINCE: 1.6.0 2832 2833 The function ‘gpgme_get_status_cb’ returns the function that is 2834 used to process status messages from gpg in *STATUSFUNC, and the 2835 first argument for this function in *HOOK_VALUE. If no status 2836 message callback is set, or CTX is not a valid pointer, ‘NULL’ is 2837 returned in both variables. 2838 2839 2840File: gpgme.info, Node: Context Flags, Next: Locale, Prev: Status Message Callback, Up: Context Attributes 2841 28427.4.13 Context Flags 2843-------------------- 2844 2845 -- Function: gpgme_error_t gpgme_set_ctx_flag (gpgme_ctx_t CTX, 2846 const char *NAME, const char *VALUE) 2847 2848 SINCE: 1.7.0 2849 2850 Some minor properties of the context can be controlled with flags 2851 set by this function. The properties are identified by the 2852 following values for NAME: 2853 2854 ‘"redraw"’ 2855 This flag is normally not changed by the caller because GPGME 2856 sets and clears it automatically: The flag is cleared before 2857 an operation and set if an operation noticed that the engine 2858 has launched a Pinentry. A Curses based application may use 2859 this information to redraw the screen; for example: 2860 2861 err = gpgme_op_keylist_start (ctx, "foo@example.org", 0); 2862 while (!err) 2863 { 2864 err = gpgme_op_keylist_next (ctx, &key); 2865 if (err) 2866 break; 2867 show_key (key); 2868 gpgme_key_release (key); 2869 } 2870 if ((s = gpgme_get_ctx_flag (ctx, "redraw")) && *s) 2871 redraw_screen (); 2872 gpgme_release (ctx); 2873 2874 ‘"full-status"’ 2875 Using a VALUE of "1" the status callback set by 2876 gpgme_set_status_cb returns all status lines with the 2877 exception of PROGRESS lines. With the default of "0" the 2878 status callback is only called in certain situations. 2879 2880 ‘"raw-description"’ 2881 Setting the VALUE to "1" returns human readable strings in a 2882 raw format. For example the non breaking space characters 2883 ("~") will not be removed from the ‘description’ field of the 2884 ‘gpgme_tofu_info_t’ object. 2885 2886 ‘"export-session-key"’ 2887 Using a VALUE of "1" specifies that the context should try to 2888 export the symmetric session key when decrypting data. By 2889 default, or when using an empty string or "0" for VALUE, 2890 session keys are not exported. 2891 2892 ‘"override-session-key"’ 2893 The string given in VALUE is passed to the GnuPG engine to 2894 override the session key for decryption. The format of that 2895 session key is specific to GnuPG and can be retrieved during a 2896 decrypt operation when the context flag "export-session-key" 2897 is enabled. Please be aware that using this feature with 2898 GnuPG < 2.1.16 will leak the session key on many platforms via 2899 ps(1). 2900 2901 ‘"auto-key-retrieve"’ 2902 Setting the VALUE to "1" asks the backend to automatically 2903 retrieve a key for signature verification if possible. Note 2904 that this option makes a "web bug" like behavior possible. 2905 Keyserver or Web Key Directory operators can see which keys 2906 you request, so by sending you a message signed by a brand new 2907 key (which you naturally will not have on your local keyring), 2908 the operator can tell both your IP address and the time when 2909 you verified the signature. 2910 2911 ‘"auto-key-import"’ 2912 Setting the VALUE to "1" forces the GPG backend to 2913 automatically import a missing key for signature verification 2914 from the signature. 2915 2916 ‘"include-key-block"’ 2917 Setting the VALUE to "1" forces the GPG backend to embed the 2918 signing key as well as an encryption subkey into the the 2919 signature. 2920 2921 ‘"request-origin"’ 2922 The string given in VALUE is passed to the GnuPG engines to 2923 request restrictions based on the origin of the request. 2924 Valid values are documented in the GnuPG manual and the gpg 2925 man page under the option ‘--request-origin’. Requires at 2926 least GnuPG 2.2.6 to have an effect. 2927 2928 ‘"no-symkey-cache"’ 2929 For OpenPGP disable the passphrase cache used for symmetrical 2930 en- and decryption. This cache is based on the message 2931 specific salt value. Requires at least GnuPG 2.2.7 to have an 2932 effect. 2933 2934 ‘"ignore-mdc-error"’ 2935 This flag passes the option ‘--ignore-mdc-error’ to gpg. This 2936 can be used to force decryption of a message which failed due 2937 to a missing integrity check. This flag must be used with 2938 great caution and only if it is a known non-corrupted old 2939 message and the decryption result of the former try had the 2940 decryption result flag ‘legacy_cipher_nomdc’ set. For 2941 failsafe reasons this flag is reset after each operation. 2942 2943 ‘"auto-key-locate"’ 2944 The string given in VALUE is passed to gpg. This can be used 2945 to change the behavior of a ‘GPGME_KEYLIST_MODE_LOCATE’ 2946 keylisting. Valid values are documented in the GnuPG manual 2947 and the gpg man page under the option ‘--auto-key-locate’. 2948 Requires at least GnuPG 2.1.18. 2949 2950 Note: Keys retrieved through ‘auto-key-locate’ are 2951 automatically imported in the keyring. 2952 2953 ‘trust-model’ 2954 SINCE: 1.11.2 2955 2956 Change the trust-model for all GnuPG engine operations. An 2957 empty string sets the trust-model back to the users default. 2958 If the trust-model is not supported by GnuPG the behavior is 2959 undefined and will likely cause all operations to fail. 2960 Example: "tofu+pgp". 2961 2962 This options should be used carefully with a strict version 2963 requirement. In some versions of GnuPG setting the 2964 trust-model changes the default trust-model for future 2965 operations. A change in the trust-model also can have 2966 unintended side effects, like rebuilding the trust-db. 2967 2968 ‘"extended-edit"’ 2969 This flag passes the option ‘--expert’ to gpg key edit. This 2970 can be used to get additional callbacks in ‘gpgme_op_edit’. 2971 2972 This function returns ‘0’ on success. 2973 2974 -- Function: const char * gpgme_get_ctx_flag (gpgme_ctx_t CTX, 2975 const char *NAME) 2976 2977 SINCE: 1.8.0 2978 2979 The value of flags settable by ‘gpgme_set_ctx_flag’ can be 2980 retrieved by this function. If NAME is unknown the function 2981 returns ‘NULL’. For boolean flags an empty string is returned for 2982 False and the string "1" is returned for True; either atoi(3) or a 2983 test for an empty string can be used to get the boolean value. 2984 2985 2986File: gpgme.info, Node: Locale, Next: Additional Logs, Prev: Context Flags, Up: Context Attributes 2987 29887.4.14 Locale 2989------------- 2990 2991A locale setting can be associated with a context. This locale is 2992passed to the crypto engine, and used for applications like the PIN 2993entry, which is displayed to the user when entering a passphrase is 2994required. 2995 2996 The default locale is used to initialize the locale setting of all 2997contexts created afterwards. 2998 2999 -- Function: gpgme_error_t gpgme_set_locale (gpgme_ctx_t CTX, 3000 int CATEGORY, const char *VALUE) 3001 SINCE: 0.4.3 3002 3003 The function ‘gpgme_set_locale’ sets the locale of the context CTX, 3004 or the default locale if CTX is a null pointer. 3005 3006 The locale settings that should be changed are specified by 3007 CATEGORY. Supported categories are ‘LC_CTYPE’, ‘LC_MESSAGES’, and 3008 ‘LC_ALL’, which is a wildcard you can use if you want to change all 3009 the categories at once. 3010 3011 The value to be used for the locale setting is VALUE, which will be 3012 copied to GPGME’s internal data structures. VALUE can be a null 3013 pointer, which disables setting the locale, and will make PIN entry 3014 and other applications use their default setting, which is usually 3015 not what you want. 3016 3017 Note that the settings are only used if the application runs on a 3018 text terminal, and that the settings should fit the configuration 3019 of the output terminal. Normally, it is sufficient to initialize 3020 the default value at startup. 3021 3022 The function returns an error if not enough memory is available. 3023 3024 3025File: gpgme.info, Node: Additional Logs, Prev: Locale, Up: Context Attributes 3026 30277.4.15 Additional Logs 3028---------------------- 3029 3030Additional logs can be associated with a context. These logs are engine 3031specific and can be be obtained with ‘gpgme_op_getauditlog’. 3032 3033 -- Function: gpgme_error_t gpgme_op_getauditlog (gpgme_ctx_t CTX, 3034 gpgme_data_t OUTPUT, unsigned int FLAGS) 3035 SINCE: 1.1.1 3036 3037 The function ‘gpgme_op_getauditlog’ is used to obtain additional 3038 logs as specified by FLAGS into the OUTPUT data. If 3039 3040 The function returns the error code ‘GPG_ERR_NO_ERROR’ if a log 3041 could be queried from the engine, and ‘GPG_ERR_NOT_IMPLEMENTED’ if 3042 the log specified in FLAGS is not available for this engine. If no 3043 log is available ‘GPG_ERR_NO_DATA’ is returned. 3044 3045 The value in FLAGS is a bitwise-or combination of one or multiple 3046 of the following bit values: 3047 3048 ‘GPGME_AUDITLOG_DIAG’ 3049 SINCE: 1.11.2 3050 3051 Obtain diagnostic output which would be written to ‘stderr’ in 3052 interactive use of the engine. This can be used to provide 3053 additional diagnostic information in case of errors in other 3054 operations. 3055 3056 Note: If log-file has been set in the configuration the log 3057 will be empty and ‘GPG_ERR_NO_DATA’ will be returned. 3058 3059 Implemented for: ‘GPGME_PROTOCOL_OpenPGP’ 3060 3061 ‘GPGME_AUDITLOG_DEFAULT’ 3062 SINCE: 1.11.2 3063 3064 This flag has the value 0 for compatibility reasons. Obtains 3065 additional information from the engine by issuing the 3066 ‘GETAUDITLOG’ command. For ‘GPGME_PROTOCOL_CMS’ this provides 3067 additional information about the X509 certificate chain. 3068 3069 Implemented for: ‘GPGME_PROTOCOL_CMS’ 3070 3071 ‘GPGME_AUDITLOG_HTML’ 3072 SINCE: 1.1.1 3073 3074 Same as ‘GPGME_AUDITLOG_DEFAULT’ but in HTML. 3075 3076 Implemented for: ‘GPGME_PROTOCOL_CMS’ 3077 3078 -- Function: gpgme_error_t gpgme_op_getauditlog_start (gpgme_ctx_t CTX, 3079 gpgme_data_t OUTPUT, unsigned int FLAGS) 3080 SINCE: 1.1.1 3081 3082 This is the asynchronous variant of ‘gpgme_op_getauditlog’. 3083 3084 3085File: gpgme.info, Node: Key Management, Next: Crypto Operations, Prev: Context Attributes, Up: Contexts 3086 30877.5 Key Management 3088================== 3089 3090Some of the cryptographic operations require that recipients or signers 3091are specified. This is always done by specifying the respective keys 3092that should be used for the operation. The following section describes 3093how such keys can be selected and manipulated. 3094 3095* Menu: 3096 3097* Key objects:: Description of the key structures. 3098* Listing Keys:: Browsing the list of available keys. 3099* Information About Keys:: Requesting detailed information about keys. 3100* Manipulating Keys:: Operations on keys. 3101* Generating Keys:: Creating new key pairs. 3102* Signing Keys:: Adding key signatures to public keys. 3103* Exporting Keys:: Retrieving key data from the key ring. 3104* Importing Keys:: Adding keys to the key ring. 3105* Deleting Keys:: Removing keys from the key ring. 3106* Changing Passphrases:: Change the passphrase of a key. 3107* Changing TOFU Data:: Changing data pertaining to TOFU. 3108* Advanced Key Editing:: Advanced key edit operation. 3109 3110 3111File: gpgme.info, Node: Key objects, Next: Listing Keys, Up: Key Management 3112 31137.5.1 Key objects 3114----------------- 3115 3116The keys are represented in GPGME by structures which may only be read 3117by the application but never be allocated or changed. They are valid as 3118long as the key object itself is valid. 3119 3120 -- Data type: gpgme_key_t 3121 3122 The ‘gpgme_key_t’ type is a pointer to a key object. It has the 3123 following members: 3124 3125 ‘gpgme_keylist_mode_t keylist_mode’ 3126 SINCE: 0.9.0 3127 3128 The keylist mode that was active when the key was retrieved. 3129 3130 ‘unsigned int revoked : 1’ 3131 This is true if the key is revoked. 3132 3133 ‘unsigned int expired : 1’ 3134 This is true if the key is expired. 3135 3136 ‘unsigned int disabled : 1’ 3137 This is true if the key is disabled. 3138 3139 ‘unsigned int invalid : 1’ 3140 This is true if the key is invalid. This might have several 3141 reasons, for a example for the S/MIME backend, it will be set 3142 during key listings if the key could not be validated due to 3143 missing certificates or unmatched policies. 3144 3145 ‘unsigned int can_encrypt : 1’ 3146 This is true if the key (ie one of its subkeys) can be used 3147 for encryption. 3148 3149 ‘unsigned int can_sign : 1’ 3150 This is true if the key (ie one of its subkeys) can be used to 3151 create data signatures. 3152 3153 ‘unsigned int can_certify : 1’ 3154 This is true if the key (ie one of its subkeys) can be used to 3155 create key certificates. 3156 3157 ‘unsigned int can_authenticate : 1’ 3158 SINCE: 0.4.5 3159 3160 This is true if the key (ie one of its subkeys) can be used 3161 for authentication. 3162 3163 ‘unsigned int is_qualified : 1’ 3164 SINCE: 1.1.0 3165 3166 This is true if the key can be used for qualified signatures 3167 according to local government regulations. 3168 3169 ‘unsigned int secret : 1’ 3170 This is true if the key is a secret key. Note, that this will 3171 always be true even if the corresponding subkey flag may be 3172 false (offline/stub keys). This is only set if a listing of 3173 secret keys has been requested or if 3174 ‘GPGME_KEYLIST_MODE_WITH_SECRET’ is active. 3175 3176 ‘unsigned int origin : 5’ 3177 SINCE: 1.8.0 3178 3179 Reserved for the origin of this key. 3180 3181 ‘gpgme_protocol_t protocol’ 3182 This is the protocol supported by this key. 3183 3184 ‘char *issuer_serial’ 3185 If ‘protocol’ is ‘GPGME_PROTOCOL_CMS’, then this is the issuer 3186 serial. 3187 3188 ‘char *issuer_name’ 3189 If ‘protocol’ is ‘GPGME_PROTOCOL_CMS’, then this is the issuer 3190 name. 3191 3192 ‘char *chain_id’ 3193 If ‘protocol’ is ‘GPGME_PROTOCOL_CMS’, then this is the chain 3194 ID, which can be used to built the certificate chain. 3195 3196 ‘gpgme_validity_t owner_trust’ 3197 If ‘protocol’ is ‘GPGME_PROTOCOL_OpenPGP’, then this is the 3198 owner trust. 3199 3200 ‘gpgme_subkey_t subkeys’ 3201 This is a linked list with the subkeys of the key. The first 3202 subkey in the list is the primary key and usually available. 3203 3204 ‘gpgme_user_id_t uids’ 3205 This is a linked list with the user IDs of the key. The first 3206 user ID in the list is the main (or primary) user ID. 3207 3208 ‘char *fpr’ 3209 SINCE: 1.7.0 3210 3211 This field gives the fingerprint of the primary key. Note 3212 that this is a copy of the fingerprint of the first subkey. 3213 For an incomplete key (for example from a verification result) 3214 a subkey may be missing but this field may be set 3215 nevertheless. 3216 3217 ‘unsigned long last_update’ 3218 SINCE: 1.8.0 3219 3220 Reserved for the time of the last update of this key. 3221 3222 -- Data type: gpgme_subkey_t 3223 SINCE: 1.5.0 3224 3225 The ‘gpgme_subkey_t’ type is a pointer to a subkey structure. 3226 Subkeys are one component of a ‘gpgme_key_t’ object. In fact, 3227 subkeys are those parts that contains the real information about 3228 the individual cryptographic keys that belong to the same key 3229 object. One ‘gpgme_key_t’ can contain several subkeys. The first 3230 subkey in the linked list is also called the primary key. 3231 3232 The subkey structure has the following members: 3233 3234 ‘gpgme_subkey_t next’ 3235 This is a pointer to the next subkey structure in the linked 3236 list, or ‘NULL’ if this is the last element. 3237 3238 ‘unsigned int revoked : 1’ 3239 This is true if the subkey is revoked. 3240 3241 ‘unsigned int expired : 1’ 3242 This is true if the subkey is expired. 3243 3244 ‘unsigned int disabled : 1’ 3245 This is true if the subkey is disabled. 3246 3247 ‘unsigned int invalid : 1’ 3248 This is true if the subkey is invalid. 3249 3250 ‘unsigned int can_encrypt : 1’ 3251 This is true if the subkey can be used for encryption. 3252 3253 ‘unsigned int can_sign : 1’ 3254 This is true if the subkey can be used to create data 3255 signatures. 3256 3257 ‘unsigned int can_certify : 1’ 3258 This is true if the subkey can be used to create key 3259 certificates. 3260 3261 ‘unsigned int can_authenticate : 1’ 3262 SINCE: 0.4.5 3263 3264 This is true if the subkey can be used for authentication. 3265 3266 ‘unsigned int is_qualified : 1’ 3267 SINCE: 1.1.0 3268 3269 This is true if the subkey can be used for qualified 3270 signatures according to local government regulations. 3271 3272 ‘unsigned int is_de_vs : 1’ 3273 SINCE: 1.8.0 3274 3275 This is true if the subkey complies with the rules for 3276 classified information in Germany at the restricted level 3277 (VS-NfD). This are currently RSA keys of at least 2048 bits or 3278 ECDH/ECDSA keys using a Brainpool curve. 3279 3280 ‘unsigned int secret : 1’ 3281 This is true if the subkey is a secret key. Note that it will 3282 be false if the key is actually a stub key; i.e. a secret key 3283 operation is currently not possible (offline-key). This is 3284 only set if a listing of secret keys has been requested or if 3285 ‘GPGME_KEYLIST_MODE_WITH_SECRET’ is active. 3286 3287 ‘gpgme_pubkey_algo_t pubkey_algo’ 3288 This is the public key algorithm supported by this subkey. 3289 3290 ‘unsigned int length’ 3291 This is the length of the subkey (in bits). 3292 3293 ‘char *keyid’ 3294 This is the key ID of the subkey in hexadecimal digits. 3295 3296 ‘char *fpr’ 3297 This is the fingerprint of the subkey in hexadecimal digits, 3298 if available. 3299 3300 ‘char *keygrip’ 3301 SINCE: 1.7.0 3302 3303 The keygrip of the subkey in hex digit form or ‘NULL’ if not 3304 available. 3305 3306 ‘long int timestamp’ 3307 This is the creation timestamp of the subkey. This is -1 if 3308 the timestamp is invalid, and 0 if it is not available. 3309 3310 ‘long int expires’ 3311 This is the expiration timestamp of the subkey, or 0 if the 3312 subkey does not expire. 3313 3314 ‘unsigned int is_cardkey : 1’ 3315 SINCE: 1.2.0 3316 3317 True if the secret key is stored on a smart card. 3318 3319 ‘char *card_number’ 3320 SINCE: 1.2.0 3321 3322 The serial number of a smart card holding this key or ‘NULL’. 3323 3324 ‘char *curve’ 3325 For ECC algorithms the name of the curve. 3326 3327 -- Data type: gpgme_user_id_t 3328 3329 A user ID is a component of a ‘gpgme_key_t’ object. One key can 3330 have many user IDs. The first one in the list is the main (or 3331 primary) user ID. 3332 3333 The user ID structure has the following members. 3334 3335 ‘gpgme_user_id_t next’ 3336 This is a pointer to the next user ID structure in the linked 3337 list, or ‘NULL’ if this is the last element. 3338 3339 ‘unsigned int revoked : 1’ 3340 This is true if the user ID is revoked. 3341 3342 ‘unsigned int invalid : 1’ 3343 This is true if the user ID is invalid. 3344 3345 ‘gpgme_validity_t validity’ 3346 This specifies the validity of the user ID. 3347 3348 ‘char *uid’ 3349 This is the user ID string. 3350 3351 ‘char *name’ 3352 This is the name component of ‘uid’, if available. 3353 3354 ‘char *comment’ 3355 This is the comment component of ‘uid’, if available. 3356 3357 ‘char *email’ 3358 This is the email component of ‘uid’, if available. 3359 3360 ‘char *address;’ 3361 The mail address (addr-spec from RFC-5322) of the user ID 3362 string. This is general the same as the ‘email’ part of this 3363 structure but might be slightly different. If no mail address 3364 is available ‘NULL’ is stored. 3365 3366 ‘gpgme_tofu_info_t tofu’ 3367 SINCE: 1.7.0 3368 3369 If not ‘NULL’ information from the TOFU database pertaining to 3370 this user id. 3371 3372 ‘gpgme_key_sig_t signatures’ 3373 This is a linked list with the signatures on this user ID. 3374 3375 ‘unsigned int origin : 5’ 3376 SINCE: 1.8.0 3377 3378 Reserved for the origin of this user ID. 3379 3380 ‘unsigned long last_update’ 3381 SINCE: 1.8.0 3382 3383 Reserved for the time of the last update of this user ID. 3384 3385 ‘char *uidhash;’ 3386 A string used by gpg to identify a user ID. This string can be 3387 used at certain prompts of ‘gpgme_op_edit’ to select a user 3388 ID. Users must be prepared to see a ‘NULL’ value here. The 3389 format of the value is not specified and may depend on the 3390 GPGME or GnuPG version. 3391 3392 -- Data type: gpgme_tofu_info_t 3393 3394 SINCE: 1.7.0 3395 3396 The ‘gpgme_tofu_info_t’ type is a pointer to a tofu info structure. 3397 Tofu info structures are one component of a ‘gpgme_user_id_t’ 3398 object, and provide information from the TOFU database pertaining 3399 to the user ID. 3400 3401 The tofu info structure has the following members: 3402 3403 ‘gpgme_key_sig_t next’ 3404 This is a pointer to the next tofu info structure in the 3405 linked list, or ‘NULL’ if this is the last element. 3406 3407 ‘unsigned int validity : 3’ 3408 This is the TOFU validity. It can have the following values: 3409 3410 ‘0’ 3411 The value ‘0’ indicates a conflict. 3412 3413 ‘1’ 3414 The value ‘1’ indicates a key without history. 3415 3416 ‘2’ 3417 The value ‘2’ indicates a key with too little history. 3418 3419 ‘3’ 3420 The value ‘3’ indicates a key with enough history for 3421 basic trust. 3422 3423 ‘4’ 3424 The value ‘4’ indicates a key with a lot of history. 3425 3426 ‘unsigned int policy : 4’ 3427 This is the TOFU policy, see ‘gpgme_tofu_policy_t’. 3428 3429 ‘unsigned short signcount’ 3430 This is the number of signatures seen for this binding (or 3431 ‘USHRT_MAX’ if there are more than that). 3432 3433 ‘unsigned short encrcount’ 3434 This is the number of encryptions done with this binding (or 3435 ‘USHRT_MAX’ if there are more than that). 3436 3437 ‘unsigned long signfirst’ 3438 Number of seconds since Epoch when the first signature was 3439 seen with this binding. 3440 3441 ‘unsigned long signlast’ 3442 Number of seconds since Epoch when the last signature was seen 3443 with this binding. 3444 3445 ‘unsigned long encrfirst’ 3446 Number of seconds since Epoch when the first encryption was 3447 done with this binding. 3448 3449 ‘unsigned long encrlast’ 3450 Number of seconds since Epoch when the last encryption was 3451 done with this binding. 3452 3453 ‘char *description’ 3454 A human-readable string summarizing the TOFU data (or NULL). 3455 3456 -- Data type: gpgme_key_sig_t 3457 3458 The ‘gpgme_key_sig_t’ type is a pointer to a key signature 3459 structure. Key signatures are one component of a ‘gpgme_key_t’ 3460 object, and validate user IDs on the key in the OpenPGP protocol. 3461 3462 The signatures on a key are only available if the key was retrieved 3463 via a listing operation with the ‘GPGME_KEYLIST_MODE_SIGS’ mode 3464 enabled, because it can be expensive to retrieve all signatures of 3465 a key. 3466 3467 The signature notations on a key signature are only available if 3468 the key was retrieved via a listing operation with the 3469 ‘GPGME_KEYLIST_MODE_SIG_NOTATIONS’ mode enabled, because it can be 3470 expensive to retrieve all signature notations. 3471 3472 The key signature structure has the following members: 3473 3474 ‘gpgme_key_sig_t next’ 3475 This is a pointer to the next key signature structure in the 3476 linked list, or ‘NULL’ if this is the last element. 3477 3478 ‘unsigned int revoked : 1’ 3479 This is true if the key signature is a revocation signature. 3480 3481 ‘unsigned int expired : 1’ 3482 This is true if the key signature is expired. 3483 3484 ‘unsigned int invalid : 1’ 3485 This is true if the key signature is invalid. 3486 3487 ‘unsigned int exportable : 1’ 3488 This is true if the key signature is exportable. 3489 3490 ‘gpgme_pubkey_algo_t pubkey_algo’ 3491 This is the public key algorithm used to create the signature. 3492 3493 ‘char *keyid’ 3494 This is the key ID of the key (in hexadecimal digits) used to 3495 create the signature. 3496 3497 ‘long int timestamp’ 3498 This is the creation timestamp of the key signature. This is 3499 -1 if the timestamp is invalid, and 0 if it is not available. 3500 3501 ‘long int expires’ 3502 This is the expiration timestamp of the key signature, or 0 if 3503 the key signature does not expire. 3504 3505 ‘gpgme_error_t status’ 3506 This is the status of the signature and has the same meaning 3507 as the member of the same name in a ‘gpgme_signature_t’ 3508 object. 3509 3510 ‘unsigned int sig_class’ 3511 This specifies the signature class of the key signature. The 3512 meaning is specific to the crypto engine. 3513 3514 ‘char *uid’ 3515 This is the main user ID of the key used to create the 3516 signature. 3517 3518 ‘char *name’ 3519 This is the name component of ‘uid’, if available. 3520 3521 ‘char *comment’ 3522 This is the comment component of ‘uid’, if available. 3523 3524 ‘char *email’ 3525 This is the email component of ‘uid’, if available. 3526 3527 ‘gpgme_sig_notation_t notations’ 3528 This is a linked list with the notation data and policy URLs. 3529 3530 3531File: gpgme.info, Node: Listing Keys, Next: Information About Keys, Prev: Key objects, Up: Key Management 3532 35337.5.2 Listing Keys 3534------------------ 3535 3536 -- Function: gpgme_error_t gpgme_op_keylist_start (gpgme_ctx_t CTX, 3537 const char *PATTERN, int SECRET_ONLY) 3538 3539 The function ‘gpgme_op_keylist_start’ initiates a key listing 3540 operation inside the context CTX. It sets everything up so that 3541 subsequent invocations of ‘gpgme_op_keylist_next’ return the keys 3542 in the list. 3543 3544 If PATTERN is ‘NULL’, all available keys are returned. Otherwise, 3545 PATTERN contains an engine specific expression that is used to 3546 limit the list to all keys matching the pattern. Note that the 3547 total length of the pattern is restricted to an engine-specific 3548 maximum (a couple of hundred characters are usually accepted). The 3549 pattern should be used to restrict the search to a certain common 3550 name or user, not to list many specific keys at once by listing 3551 their fingerprints or key IDs. 3552 3553 If SECRET_ONLY is not ‘0’, the list is restricted to secret keys 3554 only. 3555 3556 The context will be busy until either all keys are received (and 3557 ‘gpgme_op_keylist_next’ returns ‘GPG_ERR_EOF’), or 3558 ‘gpgme_op_keylist_end’ is called to finish the operation. 3559 3560 The function returns the error code ‘GPG_ERR_INV_VALUE’ if CTX is 3561 not a valid pointer, and passes through any errors that are 3562 reported by the crypto engine support routines. 3563 3564 -- Function: gpgme_error_t gpgme_op_keylist_ext_start (gpgme_ctx_t CTX, 3565 const char *PATTERN[], int SECRET_ONLY, int RESERVED) 3566 3567 The function ‘gpgme_op_keylist_ext_start’ initiates an extended key 3568 listing operation inside the context CTX. It sets everything up so 3569 that subsequent invocations of ‘gpgme_op_keylist_next’ return the 3570 keys in the list. 3571 3572 If PATTERN or *PATTERN is ‘NULL’, all available keys are returned. 3573 Otherwise, PATTERN is a ‘NULL’ terminated array of strings that are 3574 used to limit the list to all keys matching at least one of the 3575 patterns verbatim. Note that the total length of all patterns is 3576 restricted to an engine-specific maximum (the exact limit also 3577 depends on the number of patterns and amount of quoting required, 3578 but a couple of hundred characters are usually accepted). Patterns 3579 should be used to restrict the search to a certain common name or 3580 user, not to list many specific keys at once by listing their 3581 fingerprints or key IDs. 3582 3583 If SECRET_ONLY is not ‘0’, the list is restricted to secret keys 3584 only. 3585 3586 The value of RESERVED must be ‘0’. 3587 3588 The context will be busy until either all keys are received (and 3589 ‘gpgme_op_keylist_next’ returns ‘GPG_ERR_EOF’), or 3590 ‘gpgme_op_keylist_end’ is called to finish the operation. 3591 3592 The function returns the error code ‘GPG_ERR_INV_VALUE’ if CTX is 3593 not a valid pointer, and passes through any errors that are 3594 reported by the crypto engine support routines. 3595 3596 -- Function: gpgme_error_t gpgme_op_keylist_from_data_start 3597 (gpgme_ctx_t CTX, gpgme_data_t DATA, int RESERVED) 3598 3599 SINCE: 1.8.0 3600 3601 The function ‘gpgme_op_keylist_from_data_start’ initiates a key 3602 listing operation inside the context CTX. In contrast to the other 3603 key listing operation the keys are read from the supplied DATA and 3604 not from the local key database. The keys are also not imported 3605 into the local key database. The function sets everything up so 3606 that subsequent invocations of ‘gpgme_op_keylist_next’ return the 3607 keys from DATA. 3608 3609 The value of RESERVED must be ‘0’. 3610 3611 This function requires at least GnuPG version 2.1.14 and currently 3612 works only with OpenPGP keys. 3613 3614 The context will be busy until either all keys are received (and 3615 ‘gpgme_op_keylist_next’ returns ‘GPG_ERR_EOF’), or 3616 ‘gpgme_op_keylist_end’ is called to finish the operation. While 3617 the context is busy DATA may not be released. 3618 3619 The function returns the error code ‘GPG_ERR_INV_VALUE’ if CTX is 3620 not a valid pointer, and passes through any errors that are 3621 reported by the crypto engine support routines. 3622 3623 -- Function: gpgme_error_t gpgme_op_keylist_next (gpgme_ctx_t CTX, 3624 gpgme_key_t *R_KEY) 3625 3626 The function ‘gpgme_op_keylist_next’ returns the next key in the 3627 list created by a previous ‘gpgme_op_keylist_start’ operation in 3628 the context CTX. The key will have one reference for the user. 3629 *Note Manipulating Keys::. 3630 3631 This is the only way to get at ‘gpgme_key_t’ objects in GPGME. 3632 3633 If the last key in the list has already been returned, 3634 ‘gpgme_op_keylist_next’ returns ‘GPG_ERR_EOF’. 3635 3636 The function returns the error code ‘GPG_ERR_INV_VALUE’ if CTX or 3637 R_KEY is not a valid pointer, and ‘GPG_ERR_ENOMEM’ if there is not 3638 enough memory for the operation. 3639 3640 -- Function: gpgme_error_t gpgme_op_keylist_end (gpgme_ctx_t CTX) 3641 3642 The function ‘gpgme_op_keylist_end’ ends a pending key list 3643 operation in the context CTX. 3644 3645 After the operation completed successfully, the result of the key 3646 listing operation can be retrieved with ‘gpgme_op_keylist_result’. 3647 3648 The function returns the error code ‘GPG_ERR_INV_VALUE’ if CTX is 3649 not a valid pointer, and ‘GPG_ERR_ENOMEM’ if at some time during 3650 the operation there was not enough memory available. 3651 3652 The following example illustrates how all keys containing a certain 3653string (‘g10code’) can be listed with their key ID and the name and 3654email address of the main user ID: 3655 3656 gpgme_ctx_t ctx; 3657 gpgme_key_t key; 3658 gpgme_error_t err = gpgme_new (&ctx); 3659 3660 if (!err) 3661 { 3662 err = gpgme_op_keylist_start (ctx, "g10code", 0); 3663 while (!err) 3664 { 3665 err = gpgme_op_keylist_next (ctx, &key); 3666 if (err) 3667 break; 3668 printf ("%s:", key->subkeys->keyid); 3669 if (key->uids && key->uids->name) 3670 printf (" %s", key->uids->name); 3671 if (key->uids && key->uids->email) 3672 printf (" <%s>", key->uids->email); 3673 putchar ('\n'); 3674 gpgme_key_release (key); 3675 } 3676 gpgme_release (ctx); 3677 } 3678 if (gpg_err_code (err) != GPG_ERR_EOF) 3679 { 3680 fprintf (stderr, "can not list keys: %s\n", gpgme_strerror (err)); 3681 exit (1); 3682 } 3683 3684 -- Data type: gpgme_keylist_result_t 3685 This is a pointer to a structure used to store the result of a 3686 ‘gpgme_op_keylist_*’ operation. After successfully ending a key 3687 listing operation, you can retrieve the pointer to the result with 3688 ‘gpgme_op_keylist_result’. The structure contains the following 3689 member: 3690 3691 ‘unsigned int truncated : 1’ 3692 This is true if the crypto backend had to truncate the result, 3693 and less than the desired keys could be listed. 3694 3695 -- Function: gpgme_keylist_result_t gpgme_op_keylist_result 3696 (gpgme_ctx_t CTX) 3697 The function ‘gpgme_op_keylist_result’ returns a 3698 ‘gpgme_keylist_result_t’ pointer to a structure holding the result 3699 of a ‘gpgme_op_keylist_*’ operation. The pointer is only valid if 3700 the last operation on the context was a key listing operation, and 3701 if this operation finished successfully. The returned pointer is 3702 only valid until the next operation is started on the context. 3703 3704 In a simple program, for which a blocking operation is acceptable, 3705the following function can be used to retrieve a single key. 3706 3707 -- Function: gpgme_error_t gpgme_get_key (gpgme_ctx_t CTX, 3708 const char *FPR, gpgme_key_t *R_KEY, int SECRET) 3709 The function ‘gpgme_get_key’ gets the key with the fingerprint (or 3710 key ID) FPR from the crypto backend and return it in R_KEY. If 3711 SECRET is true, get the secret key. The currently active keylist 3712 mode is used to retrieve the key. The key will have one reference 3713 for the user. 3714 3715 If the key is not found in the keyring, ‘gpgme_get_key’ returns the 3716 error code ‘GPG_ERR_EOF’ and *R_KEY will be set to ‘NULL’. 3717 3718 The function returns the error code ‘GPG_ERR_INV_VALUE’ if CTX or 3719 R_KEY is not a valid pointer or FPR is not a fingerprint or key ID, 3720 ‘GPG_ERR_AMBIGUOUS_NAME’ if the key ID was not a unique specifier 3721 for a key, and ‘GPG_ERR_ENOMEM’ if at some time during the 3722 operation there was not enough memory available. 3723 3724 3725File: gpgme.info, Node: Information About Keys, Next: Manipulating Keys, Prev: Listing Keys, Up: Key Management 3726 37277.5.3 Information About Keys 3728---------------------------- 3729 3730Please see the beginning of this section for more information about 3731‘gpgme_key_t’ objects. 3732 3733 -- Data type: gpgme_validity_t 3734 The ‘gpgme_validity_t’ type is used to specify the validity of a 3735 user ID in a key. The following validities are defined: 3736 3737 ‘GPGME_VALIDITY_UNKNOWN’ 3738 The user ID is of unknown validity. The string representation 3739 of this validity is “?”. 3740 3741 ‘GPGME_VALIDITY_UNDEFINED’ 3742 The validity of the user ID is undefined. The string 3743 representation of this validity is “q”. 3744 3745 ‘GPGME_VALIDITY_NEVER’ 3746 The user ID is never valid. The string representation of this 3747 validity is “n”. 3748 3749 ‘GPGME_VALIDITY_MARGINAL’ 3750 The user ID is marginally valid. The string representation of 3751 this validity is “m”. 3752 3753 ‘GPGME_VALIDITY_FULL’ 3754 The user ID is fully valid. The string representation of this 3755 validity is “f”. 3756 3757 ‘GPGME_VALIDITY_ULTIMATE’ 3758 The user ID is ultimately valid. The string representation of 3759 this validity is “u”. 3760 3761 3762File: gpgme.info, Node: Manipulating Keys, Next: Generating Keys, Prev: Information About Keys, Up: Key Management 3763 37647.5.4 Manipulating Keys 3765----------------------- 3766 3767 -- Function: void gpgme_key_ref (gpgme_key_t KEY) 3768 The function ‘gpgme_key_ref’ acquires an additional reference for 3769 the key KEY. 3770 3771 -- Function: void gpgme_key_unref (gpgme_key_t KEY) 3772 The function ‘gpgme_key_unref’ releases a reference for the key 3773 KEY. If this was the last reference, the key will be destroyed and 3774 all resources associated to it will be released. 3775 3776 -- Function: gpgme_error_t gpgme_op_setexpire (gpgme_ctx_t CTX, 3777 gpgme_key_t KEY, unsigned long EXPIRES, const char *SUBFPRS, 3778 unsigned int RESERVED); 3779 3780 SINCE: 1.14.1 3781 3782 The function ‘gpgme_op_setexpire’ sets the expiration time of the 3783 key KEY or of the specified subkeys. This function requires at 3784 least version 2.1.22 of GnuPG. 3785 3786 KEY specifies the key to operate on. 3787 3788 EXPIRES specifies the expiration time in seconds from now. To be 3789 similar to other usages where expiration times are provided in 3790 unsigned long this is similar to the key creation date and so it is 3791 in seconds from NOW. 3792 3793 The common case is to use 0 to not set an expiration time. Note 3794 that this parameter takes an unsigned long value and not a ‘time_t’ 3795 to avoid problems on systems which use a signed 32 bit ‘time_t’. 3796 Note further that the OpenPGP protocol uses 32 bit values for 3797 timestamps and thus can only encode dates up to the year 2106. 3798 3799 SUBFPRS selects the subkey(s) for which the expiration time should 3800 be set. If SUBFPRS is set to ‘NULL’, then the expiration time of 3801 the primary key is set. If SUBFPRS is an asterisk (‘*’), then the 3802 expiration times of all non-revoked and not yet expired subkeys are 3803 set. To select more than one subkey put all subkey fingerprints 3804 into one string separated by linefeeds characters (‘\n’). 3805 3806 RESERVED is reserved for later use and must be ‘0’. 3807 3808 -- Function: gpgme_error_t gpgme_op_setexpire_start (gpgme_ctx_t CTX, 3809 gpgme_key_t KEY, unsigned long EXPIRES, const char *SUBFPRS, 3810 unsigned int FLAGS); 3811 3812 SINCE: 1.14.1 3813 3814 The function ‘gpgme_op_setexpire_start’ initiates a 3815 ‘gpgme_op_setexpire’ operation; see there for details. It must be 3816 completed by calling ‘gpgme_wait’ on the context. *Note Waiting 3817 For Completion::. 3818 3819 -- Function: gpgme_error_t gpgme_op_revuid_start (gpgme_ctx_t CTX, 3820 gpgme_key_t KEY, const char *USERID, unsigned int FLAGS); 3821 3822 SINCE: 1.14.1 3823 3824 The function ‘gpgme_op_setexpire_start’ initiates a 3825 ‘gpgme_op_setexpire’ operation; see there for details. It must be 3826 completed by calling ‘gpgme_wait’ on the context. *Note Waiting 3827 For Completion::. 3828 3829 3830File: gpgme.info, Node: Generating Keys, Next: Signing Keys, Prev: Manipulating Keys, Up: Key Management 3831 38327.5.5 Generating Keys 3833--------------------- 3834 3835GPGME provides a set of functions to create public key pairs. Most of 3836these functions require the use of GnuPG 2.1 and later; for older GnuPG 3837versions the ‘gpgme_op_genkey’ function can be used. Existing code 3838which wants to update to the new functions or new code which shall 3839supports older GnuPG versions may try the new functions first and 3840provide a fallback to the old function if the error code 3841‘GPG_ERR_NOT_SUPPORTED’ is received. 3842 3843 -- Function: gpgme_error_t gpgme_op_createkey (gpgme_ctx_t CTX, 3844 const char *USERID, const char *ALGO, unsigned long RESERVED, 3845 unsigned long EXPIRES, gpgme_key_t EXTRAKEY, 3846 unsigned int FLAGS); 3847 3848 SINCE: 1.7.0 3849 3850 The function ‘gpgme_op_createkey’ generates a new key for the 3851 procotol active in the context CTX. As of now this function does 3852 only work for OpenPGP and requires at least version 2.1.13 of 3853 GnuPG. 3854 3855 USERID is commonly the mail address associated with the key. GPGME 3856 does not require a specific syntax but if more than a mail address 3857 is given, RFC-822 style format is suggested. The value is expected 3858 to be in UTF-8 encoding (i.e. no IDN encoding for mail addresses). 3859 This is a required parameter. 3860 3861 ALGO specifies the algorithm for the new key (actually a keypair of 3862 public and private key). For a list of supported algorithms, see 3863 the GnuPG manual. If ALGO is ‘NULL’ or the string "default", the 3864 key is generated using the default algorithm of the engine. If the 3865 string "future-default" is used the engine may use an algorithm 3866 which is planned to be the default in a future release of the 3867 engine; however existing implementation of the protocol may not be 3868 able to already handle such future algorithms. For the OpenPGP 3869 protocol, the specification of a default algorithm, without 3870 requesting a non-default usage via FLAGS, triggers the creation of 3871 a primary key plus a secondary key (subkey). 3872 3873 RESERVED must be set to zero. 3874 3875 EXPIRES specifies the expiration time in seconds. If you supply 0, 3876 a reasonable expiration time is chosen. Use the flag 3877 ‘GPGME_CREATE_NOEXPIRE’ to create keys that do not expire. Note 3878 that this parameter takes an unsigned long value and not a ‘time_t’ 3879 to avoid problems on systems which use a signed 32 bit ‘time_t’. 3880 Note further that the OpenPGP protocol uses 32 bit values for 3881 timestamps and thus can only encode dates up to the year 2106. 3882 3883 EXTRAKEY is currently not used and must be set to ‘NULL’. A future 3884 version of GPGME may use this parameter to create X.509 keys. 3885 3886 FLAGS can be set to the bit-wise OR of the following flags: 3887 3888 ‘GPGME_CREATE_SIGN’ 3889 ‘GPGME_CREATE_ENCR’ 3890 ‘GPGME_CREATE_CERT’ 3891 ‘GPGME_CREATE_AUTH’ 3892 SINCE: 1.7.0 3893 3894 Do not create the key with the default capabilities (key 3895 usage) of the requested algorithm but use those explicitly 3896 given by these flags: “signing”, “encryption”, 3897 “certification”, or “authentication”. The allowed 3898 combinations depend on the algorithm. 3899 3900 If any of these flags are set and a default algorithm has been 3901 selected only one key is created in the case of the OpenPGP 3902 protocol. 3903 3904 ‘GPGME_CREATE_NOPASSWD’ 3905 SINCE: 1.7.0 3906 3907 Request generation of the key without password protection. 3908 3909 ‘GPGME_CREATE_SELFSIGNED’ 3910 SINCE: 1.7.0 3911 3912 For an X.509 key do not create a CSR but a self-signed 3913 certificate. This has not yet been implemented. 3914 3915 ‘GPGME_CREATE_NOSTORE’ 3916 SINCE: 1.7.0 3917 3918 Do not store the created key in the local key database. This 3919 has not yet been implemented. 3920 3921 ‘GPGME_CREATE_WANTPUB’ 3922 ‘GPGME_CREATE_WANTSEC’ 3923 SINCE: 1.7.0 3924 3925 Return the public or secret key as part of the result 3926 structure. This has not yet been implemented. 3927 3928 ‘GPGME_CREATE_FORCE’ 3929 SINCE: 1.7.0 3930 3931 The engine does not allow the creation of a key with a user ID 3932 already existing in the local key database. This flag can be 3933 used to override this check. 3934 3935 ‘GPGME_CREATE_NOEXPIRE’ 3936 SINCE: 1.9.0 3937 3938 Request generation of keys that do not expire. 3939 3940 After the operation completed successfully, information about the 3941 created key can be retrieved with ‘gpgme_op_genkey_result’. 3942 3943 The function returns zero on success, ‘GPG_ERR_NOT_SUPPORTED’ if 3944 the engine does not support the command, or a bunch of other error 3945 codes. 3946 3947 -- Function: gpgme_error_t gpgme_op_createkey_start (gpgme_ctx_t CTX, 3948 const char *USERID, const char *ALGO, unsigned long RESERVED, 3949 unsigned long EXPIRES, gpgme_key_t EXTRAKEY, 3950 unsigned int FLAGS); 3951 3952 SINCE: 1.7.0 3953 3954 The function ‘gpgme_op_createkey_start’ initiates a 3955 ‘gpgme_op_createkey’ operation; see there for details. It must be 3956 completed by calling ‘gpgme_wait’ on the context. *Note Waiting 3957 For Completion::. 3958 3959 -- Function: gpgme_error_t gpgme_op_createsubkey (gpgme_ctx_t CTX, 3960 gpgme_key_t KEY, const char *ALGO, unsigned long RESERVED, 3961 unsigned long EXPIRES, unsigned int FLAGS); 3962 3963 SINCE: 1.7.0 3964 3965 The function ‘gpgme_op_createsubkey’ creates and adds a new subkey 3966 to the primary OpenPGP key given by KEY. The only allowed protocol 3967 in CTX is ‘GPGME_PROTOCOL_OPENPGP’. Subkeys (aka secondary keys) 3968 are a concept in the OpenPGP protocol to bind several keys to a 3969 primary key. As of now this function requires at least version 3970 2.1.13 of GnuPG. 3971 3972 KEY specifies the key to operate on. 3973 3974 ALGO specifies the algorithm for the new subkey. For a list of 3975 supported algorithms, see the GnuPG manual. If ALGO is ‘NULL’ or 3976 the string "default", the subkey is generated using the default 3977 algorithm for an encryption subkey of the engine. If the string 3978 "future-default" is used the engine may use an encryption algorithm 3979 which is planned to be the default in a future release of the 3980 engine; however existing implementation of the protocol may not be 3981 able to already handle such future algorithms. 3982 3983 RESERVED must be set to zero. 3984 3985 EXPIRES specifies the expiration time in seconds. If you supply 0, 3986 a reasonable expiration time is chosen. Use the flag 3987 ‘GPGME_CREATE_NOEXPIRE’ to create keys that do not expire. Note 3988 that this parameter takes an unsigned long value and not a ‘time_t’ 3989 to avoid problems on systems which use a signed 32 bit ‘time_t’. 3990 Note further that the OpenPGP protocol uses 32 bit values for 3991 timestamps and thus can only encode dates up to the year 2106. 3992 3993 FLAGS takes the same values as described above for 3994 ‘gpgme_op_createkey’. 3995 3996 After the operation completed successfully, information about the 3997 created key can be retrieved with ‘gpgme_op_genkey_result’. 3998 3999 The function returns zero on success, ‘GPG_ERR_NOT_SUPPORTED’ if 4000 the engine does not support the command, or a bunch of other error 4001 codes. 4002 4003 -- Function: gpgme_error_t gpgme_op_createsubkey_start 4004 (gpgme_ctx_t CTX, gpgme_key_t KEY, const char *ALGO, 4005 unsigned long RESERVED, unsigned long EXPIRES, 4006 unsigned int FLAGS); 4007 4008 SINCE: 1.7.0 4009 4010 The function ‘gpgme_op_createsubkey_start’ initiates a 4011 ‘gpgme_op_createsubkey’ operation; see there for details. It must 4012 be completed by calling ‘gpgme_wait’ on the context. *Note Waiting 4013 For Completion::. 4014 4015 -- Function: gpgme_error_t gpgme_op_adduid (gpgme_ctx_t CTX, 4016 gpgme_key_t KEY, const char *USERID, unsigned int FLAGS); 4017 4018 SINCE: 1.7.0 4019 4020 The function ‘gpgme_op_adduid’ adds a new user ID to the OpenPGP 4021 key given by KEY. Adding additional user IDs after key creation is 4022 a feature of the OpenPGP protocol and thus the protocol for the 4023 context CTX must be set to OpenPGP. As of now this function 4024 requires at least version 2.1.13 of GnuPG. 4025 4026 KEY specifies the key to operate on. 4027 4028 USERID is the user ID to add to the key. A user ID is commonly the 4029 mail address to be associated with the key. GPGME does not require 4030 a specific syntax but if more than a mail address is given, RFC-822 4031 style format is suggested. The value is expected to be in UTF-8 4032 encoding (i.e. no IDN encoding for mail addresses). This is a 4033 required parameter. 4034 4035 FLAGS are currently not used and must be set to zero. 4036 4037 The function returns zero on success, ‘GPG_ERR_NOT_SUPPORTED’ if 4038 the engine does not support the command, or a bunch of other error 4039 codes. 4040 4041 -- Function: gpgme_error_t gpgme_op_adduid_start (gpgme_ctx_t CTX, 4042 gpgme_key_t KEY, const char *USERID, unsigned int FLAGS); 4043 4044 SINCE: 1.7.0 4045 4046 The function ‘gpgme_op_adduid_start’ initiates a ‘gpgme_op_adduid’ 4047 operation; see there for details. It must be completed by calling 4048 ‘gpgme_wait’ on the context. *Note Waiting For Completion::. 4049 4050 -- Function: gpgme_error_t gpgme_op_revuid (gpgme_ctx_t CTX, 4051 gpgme_key_t KEY, const char *USERID, unsigned int FLAGS); 4052 4053 SINCE: 1.7.0 4054 4055 The function ‘gpgme_op_revuid’ revokes a user ID from the OpenPGP 4056 key given by KEY. Revoking user IDs after key creation is a 4057 feature of the OpenPGP protocol and thus the protocol for the 4058 context CTX must be set to OpenPGP. As of now this function 4059 requires at least version 2.1.13 of GnuPG. 4060 4061 KEY specifies the key to operate on. 4062 4063 USERID is the user ID to be revoked from the key. The user ID must 4064 be given verbatim because the engine does an exact and case 4065 sensitive match. Thus the ‘uid’ field from the user ID object 4066 (‘gpgme_user_id_t’) is to be used. This is a required parameter. 4067 4068 FLAGS are currently not used and must be set to zero. 4069 4070 Note that the engine won’t allow to revoke the last valid user ID. 4071 To change a user ID is better to first add the new user ID, then 4072 revoke the old one, and finally publish the key. 4073 4074 The function returns zero on success, ‘GPG_ERR_NOT_SUPPORTED’ if 4075 the engine does not support the command, or a bunch of other error 4076 codes. 4077 4078 -- Function: gpgme_error_t gpgme_op_revuid_start (gpgme_ctx_t CTX, 4079 gpgme_key_t KEY, const char *USERID, unsigned int FLAGS); 4080 4081 SINCE: 1.7.0 4082 4083 The function ‘gpgme_op_revuid_start’ initiates a ‘gpgme_op_revuid’ 4084 operation; see there for details. It must be completed by calling 4085 ‘gpgme_wait’ on the context. *Note Waiting For Completion::. 4086 4087 -- Function: gpgme_error_t gpgme_op_set_ui_flag (gpgme_ctx_t CTX, 4088 gpgme_key_t KEY, const char *USERID, cons char * NAME, 4089 cons char * VALUE); 4090 4091 SINCE: 1.8.0 4092 4093 The function ‘gpgme_op_set_uid_flag’ is used to set flags on a user 4094 ID from the OpenPGP key given by KEY. Setting flags on user IDs 4095 after key creation is a feature of the OpenPGP protocol and thus 4096 the protocol for the context CTX must be set to OpenPGP. 4097 4098 KEY specifies the key to operate on. This parameters is required. 4099 4100 USERID is the user ID of the key to be manipulated. This user ID 4101 must be given verbatim because the engine does an exact and case 4102 sensitive match. Thus the ‘uid’ field from the user ID object 4103 (‘gpgme_user_id_t’) is to be used. This is a required parameter. 4104 4105 NAME names the flag which is to be changed. The only currently 4106 supported flag is: 4107 4108 ‘primary’ 4109 This sets the primary key flag on the given user ID. All other 4110 primary key flag on other user IDs are removed. VALUE must be 4111 given as NULL. For technical reasons this functions bumps the 4112 creation timestamp of all affected self-signatures up by one 4113 second. At least GnuPG version 2.1.20 is required. 4114 4115 The function returns zero on success, ‘GPG_ERR_NOT_SUPPORTED’ if 4116 the engine does not support the command, or a bunch of other error 4117 codes. 4118 4119 -- Function: gpgme_error_t gpgme_op_set_uid_flag_start 4120 (gpgme_ctx_t CTX, gpgme_key_t KEY, const char *USERID, 4121 cons char * NAME, cons char * VALUE); 4122 4123 SINCE: 1.8.0 4124 4125 The function ‘gpgme_op_set_uid_flag_start’ initiates a 4126 ‘gpgme_op_set_uid_flag’ operation; see there for details. It must 4127 be completed by calling ‘gpgme_wait’ on the context. *Note Waiting 4128 For Completion::. 4129 4130 -- Function: gpgme_error_t gpgme_op_genkey (gpgme_ctx_t CTX, 4131 const char *PARMS, gpgme_data_t PUBLIC, gpgme_data_t SECRET) 4132 4133 The function ‘gpgme_op_genkey’ generates a new key pair in the 4134 context CTX. The meaning of PUBLIC and SECRET depends on the 4135 crypto backend. 4136 4137 GPG does not support PUBLIC and SECRET, they should be ‘NULL’. 4138 GnuPG will generate a key pair and add it to the standard key ring. 4139 The fingerprint of the generated key is available with 4140 ‘gpgme_op_genkey_result’. 4141 4142 GpgSM requires PUBLIC to be a writable data object. GpgSM will 4143 generate a secret key (which will be stored by ‘gpg-agent’, and 4144 return a certificate request in PUBLIC, which then needs to be 4145 signed by the certification authority and imported before it can be 4146 used. GpgSM does not make the fingerprint available. 4147 4148 The argument PARMS specifies parameters for the key in an string 4149 that looks something like XML. The details about the format of 4150 PARMS are specific to the crypto engine used by CTX. The first 4151 line of the parameters must be ‘<GnupgKeyParams format="internal">’ 4152 and the last line must be ‘</GnupgKeyParams>’. Every line in 4153 between the first and last lines is treated as a Header: Value 4154 pair. In particular, no XML escaping is necessary if you need to 4155 include the characters ‘<’, ‘>’, or ‘&’. 4156 4157 Here is an example for GnuPG as the crypto engine (all parameters 4158 of OpenPGP key generation are documented in the GPG manual): 4159 4160 <GnupgKeyParms format="internal"> 4161 Key-Type: default 4162 Subkey-Type: default 4163 Name-Real: Joe Tester 4164 Name-Comment: with stupid passphrase 4165 Name-Email: joe@foo.bar 4166 Expire-Date: 0 4167 Passphrase: abc 4168 </GnupgKeyParms> 4169 4170 Here is an example for GpgSM as the crypto engine (all parameters 4171 of OpenPGP key generation are documented in the GPGSM manual): 4172 4173 <GnupgKeyParms format="internal"> 4174 Key-Type: RSA 4175 Key-Length: 1024 4176 Name-DN: C=de,O=g10 code,OU=Testlab,CN=Joe 2 Tester 4177 Name-Email: joe@foo.bar 4178 </GnupgKeyParms> 4179 4180 Strings should be given in UTF-8 encoding. The only format 4181 supported for now is “internal”. The content of the 4182 ‘GnupgKeyParms’ container is passed verbatim to the crypto backend. 4183 Control statements are not allowed. 4184 4185 After the operation completed successfully, the result can be 4186 retrieved with ‘gpgme_op_genkey_result’. 4187 4188 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the 4189 operation could be started successfully, ‘GPG_ERR_INV_VALUE’ if 4190 PARMS is not a well-formed string (e.g. does not have the expected 4191 tag-like headers and footers), ‘GPG_ERR_NOT_SUPPORTED’ if PUBLIC or 4192 SECRET is not valid, and ‘GPG_ERR_GENERAL’ if no key was created by 4193 the backend. 4194 4195 -- Function: gpgme_error_t gpgme_op_genkey_start (gpgme_ctx_t CTX, 4196 const char *PARMS, gpgme_data_t PUBLIC, gpgme_data_t SECRET) 4197 4198 The function ‘gpgme_op_genkey_start’ initiates a ‘gpgme_op_genkey’ 4199 operation. It can be completed by calling ‘gpgme_wait’ on the 4200 context. *Note Waiting For Completion::. 4201 4202 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the 4203 operation could be started successfully, ‘GPG_ERR_INV_VALUE’ if 4204 PARMS is not a valid XML string, and ‘GPG_ERR_NOT_SUPPORTED’ if 4205 PUBLIC or SECRET is not ‘NULL’. 4206 4207 -- Data type: gpgme_genkey_result_t 4208 4209 This is a pointer to a structure used to store the result of a 4210 ‘gpgme_op_genkey’ operation. After successfully generating a key, 4211 you can retrieve the pointer to the result with 4212 ‘gpgme_op_genkey_result’. The structure contains the following 4213 members: 4214 4215 ‘unsigned int primary : 1’ 4216 This flag is set to 1 if a primary key was created and to 0 if 4217 not. 4218 4219 ‘unsigned int sub : 1’ 4220 This flag is set to 1 if a subkey was created and to 0 if not. 4221 4222 ‘unsigned int uid : 1’ 4223 This flag is set to 1 if a user ID was created and to 0 if 4224 not. 4225 4226 ‘char *fpr’ 4227 This is the fingerprint of the key that was created. If both 4228 a primary and a subkey were generated, the fingerprint of the 4229 primary key will be returned. If the crypto engine does not 4230 provide the fingerprint, ‘fpr’ will be a null pointer. 4231 4232 ‘gpgme_data_t pubkey’ 4233 SINCE: 1.7.0 4234 4235 This will eventually be used to return the public key. It is 4236 currently not used. 4237 4238 ‘gpgme_data_t seckey’ 4239 SINCE: 1.7.0 4240 4241 This will eventually be used to return the secret key. It is 4242 currently not used. 4243 4244 -- Function: gpgme_genkey_result_t gpgme_op_genkey_result 4245 (gpgme_ctx_t CTX) 4246 4247 The function ‘gpgme_op_genkey_result’ returns a 4248 ‘gpgme_genkey_result_t’ pointer to a structure holding the result 4249 of a ‘gpgme_op_genkey’ operation. The pointer is only valid if the 4250 last operation on the context was a ‘gpgme_op_genkey’ or 4251 ‘gpgme_op_genkey_start’ operation, and if this operation finished 4252 successfully. The returned pointer is only valid until the next 4253 operation is started on the context. 4254 4255 4256File: gpgme.info, Node: Signing Keys, Next: Exporting Keys, Prev: Generating Keys, Up: Key Management 4257 42587.5.6 Signing Keys 4259------------------ 4260 4261Key signatures are a unique concept of the OpenPGP protocol. They can 4262be used to certify the validity of a key and are used to create the 4263Web-of-Trust (WoT). Instead of using the ‘gpgme_op_interact’ function 4264along with a finite state machine, GPGME provides a convenient function 4265to create key signatures when using modern GnuPG versions. 4266 4267 -- Function: gpgme_error_t gpgme_op_keysign (gpgme_ctx_t CTX, 4268 gpgme_key_t KEY, const char *USERID, unsigned long EXPIRES, 4269 unsigned int FLAGS); 4270 4271 SINCE: 1.7.0 4272 4273 The function ‘gpgme_op_keysign’ adds a new key signature to the 4274 public key KEY. This function requires at least version 2.1.12 of 4275 GnuPG. 4276 4277 CTX is the usual context which describes the protocol to use (which 4278 must be OpenPGP) and has also the list of signer keys to be used 4279 for the signature. The common case is to use the default key for 4280 signing other keys. If another key or more than one key shall be 4281 used for a key signature, ‘gpgme_signers_add’ can be used. *Note 4282 Selecting Signers::. 4283 4284 KEY specifies the key to operate on. 4285 4286 USERID selects the user ID or user IDs to be signed. If USERID is 4287 set to ‘NULL’ all valid user IDs are signed. The user ID must be 4288 given verbatim because the engine does an exact and case sensitive 4289 match. Thus the ‘uid’ field from the user ID object 4290 (‘gpgme_user_id_t’) is to be used. To select more than one user ID 4291 put them all into one string separated by linefeeds characters 4292 (‘\n’) and set the flag ‘GPGME_KEYSIGN_LFSEP’. 4293 4294 EXPIRES specifies the expiration time of the new signature in 4295 seconds. The common case is to use 0 to not set an expiration 4296 date. However, if the configuration of the engine defines a 4297 default expiration for key signatures, that is still used unless 4298 the flag ‘GPGME_KEYSIGN_NOEXPIRE’ is used. Note that this 4299 parameter takes an unsigned long value and not a ‘time_t’ to avoid 4300 problems on systems which use a signed 32 bit ‘time_t’. Note 4301 further that the OpenPGP protocol uses 32 bit values for timestamps 4302 and thus can only encode dates up to the year 2106. 4303 4304 FLAGS can be set to the bit-wise OR of the following flags: 4305 4306 ‘GPGME_KEYSIGN_LOCAL’ 4307 SINCE: 1.7.0 4308 4309 Instead of creating an exportable key signature, create a key 4310 signature which is is marked as non-exportable. 4311 4312 ‘GPGME_KEYSIGN_LFSEP’ 4313 SINCE: 1.7.0 4314 4315 Although linefeeds are uncommon in user IDs this flag is 4316 required to explicitly declare that USERID may contain several 4317 linefeed separated user IDs. 4318 4319 ‘GPGME_KEYSIGN_NOEXPIRE’ 4320 Force the creation of a key signature without an expiration 4321 date. This overrides EXPIRE and any local configuration of 4322 the engine. 4323 4324 The function returns zero on success, ‘GPG_ERR_NOT_SUPPORTED’ if 4325 the engine does not support the command, or a bunch of other error 4326 codes. 4327 4328 -- Function: gpgme_error_t gpgme_op_keysign_start (gpgme_ctx_t CTX, 4329 gpgme_key_t KEY, const char *USERID, unsigned long EXPIRES, 4330 unsigned int FLAGS); 4331 4332 SINCE: 1.7.0 4333 4334 The function ‘gpgme_op_keysign_start’ initiates a 4335 ‘gpgme_op_keysign’ operation; see there for details. It must be 4336 completed by calling ‘gpgme_wait’ on the context. *Note Waiting 4337 For Completion::. 4338 4339 -- Function: gpgme_error_t gpgme_op_revsig (gpgme_ctx_t CTX, 4340 gpgme_key_t KEY, gpgme_key_t SIGNING_KEY, const char *USERID, 4341 unsigned int FLAGS); 4342 4343 SINCE: 1.14.1 4344 4345 The function ‘gpgme_op_revsig’ revokes key signatures of the public 4346 key KEY made with the key SIGNING_KEY. This function requires at 4347 least version 2.2.24 of GnuPG. 4348 4349 KEY specifies the key to operate on. 4350 4351 SIGNING_KEY specifies the key whose signatures shall be revoked. 4352 4353 USERID selects the user ID or user IDs whose signatures shall be 4354 revoked. If USERID is set to ‘NULL’ the signatures on all user IDs 4355 are revoked. The user ID must be given verbatim because the engine 4356 does an exact and case sensitive match. Thus the ‘uid’ field from 4357 the user ID object (‘gpgme_user_id_t’) is to be used. To select 4358 more than one user ID put them all into one string separated by 4359 linefeeds characters (‘\n’) and set the flag ‘GPGME_REVSIG_LFSEP’. 4360 4361 FLAGS can be set to the bit-wise OR of the following flags: 4362 4363 ‘GPGME_REVSIG_LFSEP’ 4364 SINCE: 1.14.1 4365 4366 Although linefeeds are uncommon in user IDs this flag is 4367 required to explicitly declare that USERID may contain several 4368 linefeed separated user IDs. 4369 4370 The function returns zero on success, ‘GPG_ERR_NOT_SUPPORTED’ if 4371 the engine does not support the command, or a bunch of other error 4372 codes. 4373 4374 -- Function: gpgme_error_t gpgme_op_revsig_start (gpgme_ctx_t CTX, 4375 gpgme_key_t KEY, gpgme_key_t SIGNING_KEY, const char *USERID, 4376 unsigned int FLAGS); 4377 4378 SINCE: 1.14.1 4379 4380 The function ‘gpgme_op_revsig_start’ initiates a ‘gpgme_op_revsig’ 4381 operation; see there for details. It must be completed by calling 4382 ‘gpgme_wait’ on the context. *Note Waiting For Completion::. 4383 4384 4385File: gpgme.info, Node: Exporting Keys, Next: Importing Keys, Prev: Signing Keys, Up: Key Management 4386 43877.5.7 Exporting Keys 4388-------------------- 4389 4390Exporting keys means the same as running ‘gpg’ with the command 4391‘--export’. However, a mode flag can be used to change the way the 4392export works. The available mode flags are described below, they may be 4393or-ed together. 4394 4395‘GPGME_EXPORT_MODE_EXTERN’ 4396 If this bit is set, the output is send directly to the default 4397 keyserver. This is currently only allowed for OpenPGP keys. It is 4398 good practise to not send more than a few dozens key to a keyserver 4399 at one time. Using this flag requires that the KEYDATA argument of 4400 the export function is set to ‘NULL’. 4401 4402‘GPGME_EXPORT_MODE_MINIMAL’ 4403 SINCE: 1.3.1 4404 4405 If this bit is set, the smallest possible key is exported. For 4406 OpenPGP keys it removes all signatures except for the latest 4407 self-signatures. For X.509 keys it has no effect. 4408 4409‘GPGME_EXPORT_MODE_SSH’ 4410 SINCE: 1.4.0 4411 4412 If this bit is set, the latest authentication key of the requested 4413 OpenPGP key is exported in the OpenSSH public key format. This 4414 accepts just a single key; to force the export of a specific subkey 4415 a fingerprint pattern with an appended exclamation mark may be 4416 used. 4417 4418‘GPGME_EXPORT_MODE_SECRET’ 4419 SINCE: 1.6.0 4420 4421 Instead of exporting the public key, the secret key is exported. 4422 This may not be combined with ‘GPGME_EXPORT_MODE_EXTERN’. For 4423 X.509 the export format is PKCS#8. 4424 4425‘GPGME_EXPORT_MODE_RAW’ 4426 SINCE: 1.6.0 4427 4428 If this flag is used with ‘GPGME_EXPORT_MODE_SECRET’ for an X.509 4429 key the export format will be changed to PKCS#1. This flag may not 4430 be used with OpenPGP. 4431 4432‘GPGME_EXPORT_MODE_PKCS12’ 4433 SINCE: 1.6.0 4434 4435 If this flag is used with ‘GPGME_EXPORT_MODE_SECRET’ for an X.509 4436 key the export format will be changed to PKCS#12 which also 4437 includes the certificate. This flag may not be used with OpenPGP. 4438 4439‘GPGME_EXPORT_MODE_NOUID’ 4440 SINCE: 1.12.0 - experimental Do not export user ids. Works only 4441 with certain gpg version. 4442 4443 -- Function: gpgme_error_t gpgme_op_export (gpgme_ctx_t CTX, 4444 const char *PATTERN, gpgme_export_mode_t MODE, 4445 gpgme_data_t KEYDATA) 4446 The function ‘gpgme_op_export’ extracts public keys and returns 4447 them in the data buffer KEYDATA. The output format of the key data 4448 returned is determined by the ASCII armor attribute set for the 4449 context CTX, or, if that is not set, by the encoding specified for 4450 KEYDATA. 4451 4452 If PATTERN is ‘NULL’, all available keys are returned. Otherwise, 4453 PATTERN contains an engine specific expression that is used to 4454 limit the list to all keys matching the pattern. 4455 4456 MODE is usually 0; other values are described above. 4457 4458 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the 4459 operation completed successfully, ‘GPG_ERR_INV_VALUE’ if KEYDATA is 4460 not a valid empty data buffer, and passes through any errors that 4461 are reported by the crypto engine support routines. 4462 4463 -- Function: gpgme_error_t gpgme_op_export_start (gpgme_ctx_t CTX, 4464 const char *PATTERN, gpgme_export_mode_t MODE, 4465 gpgme_data_t KEYDATA) 4466 The function ‘gpgme_op_export_start’ initiates a ‘gpgme_op_export’ 4467 operation. It can be completed by calling ‘gpgme_wait’ on the 4468 context. *Note Waiting For Completion::. 4469 4470 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the 4471 operation could be started successfully, and ‘GPG_ERR_INV_VALUE’ if 4472 KEYDATA is not a valid empty data buffer. 4473 4474 -- Function: gpgme_error_t gpgme_op_export_ext (gpgme_ctx_t CTX, 4475 const char *PATTERN[], gpgme_export_mode_t MODE, 4476 gpgme_data_t KEYDATA) 4477 The function ‘gpgme_op_export’ extracts public keys and returns 4478 them in the data buffer KEYDATA. The output format of the key data 4479 returned is determined by the ASCII armor attribute set for the 4480 context CTX, or, if that is not set, by the encoding specified for 4481 KEYDATA. 4482 4483 If PATTERN or *PATTERN is ‘NULL’, all available keys are returned. 4484 Otherwise, PATTERN is a ‘NULL’ terminated array of strings that are 4485 used to limit the list to all keys matching at least one of the 4486 patterns verbatim. 4487 4488 MODE is usually 0; other values are described above. 4489 4490 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the 4491 operation completed successfully, ‘GPG_ERR_INV_VALUE’ if KEYDATA is 4492 not a valid empty data buffer, and passes through any errors that 4493 are reported by the crypto engine support routines. 4494 4495 -- Function: gpgme_error_t gpgme_op_export_ext_start (gpgme_ctx_t CTX, 4496 const char *PATTERN[], gpgme_export_mode_t MODE, 4497 gpgme_data_t KEYDATA) 4498 The function ‘gpgme_op_export_ext_start’ initiates a 4499 ‘gpgme_op_export_ext’ operation. It can be completed by calling 4500 ‘gpgme_wait’ on the context. *Note Waiting For Completion::. 4501 4502 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the 4503 operation could be started successfully, and ‘GPG_ERR_INV_VALUE’ if 4504 KEYDATA is not a valid empty data buffer. 4505 4506 -- Function: gpgme_error_t gpgme_op_export_keys (gpgme_ctx_t CTX, 4507 gpgme_key_t keys[], gpgme_export_mode_t MODE, 4508 gpgme_data_t KEYDATA) 4509 SINCE: 1.2.0 4510 4511 The function ‘gpgme_op_export_keys’ extracts public keys and 4512 returns them in the data buffer KEYDATA. The output format of the 4513 key data returned is determined by the ASCII armor attribute set 4514 for the context CTX, or, if that is not set, by the encoding 4515 specified for KEYDATA. 4516 4517 The keys to export are taken form the ‘NULL’ terminated array KEYS. 4518 Only keys of the currently selected protocol of CTX which do have a 4519 fingerprint set are considered for export. Other keys specified by 4520 the KEYS are ignored. In particular OpenPGP keys retrieved via an 4521 external key listing are not included. 4522 4523 MODE is usually 0; other values are described above. 4524 4525 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the 4526 operation completed successfully, ‘GPG_ERR_INV_VALUE’ if KEYDATA is 4527 not a valid empty data buffer, ‘GPG_ERR_NO_DATA’ if no useful keys 4528 are in KEYS and passes through any errors that are reported by the 4529 crypto engine support routines. 4530 4531 -- Function: gpgme_error_t gpgme_op_export_keys_start (gpgme_ctx_t CTX, 4532 gpgme_key_t KEYS[], gpgme_export_mode_t MODE, 4533 gpgme_data_t KEYDATA) 4534 SINCE: 1.2.0 4535 4536 The function ‘gpgme_op_export_keys_start’ initiates a 4537 ‘gpgme_op_export_ext’ operation. It can be completed by calling 4538 ‘gpgme_wait’ on the context. *Note Waiting For Completion::. 4539 4540 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the 4541 operation could be started successfully, and ‘GPG_ERR_INV_VALUE’ if 4542 KEYDATA is not a valid empty data buffer, ‘GPG_ERR_NO_DATA’ if no 4543 useful keys are in KEYS and passes through any errors that are 4544 reported by the crypto engine support routines. 4545 4546 4547File: gpgme.info, Node: Importing Keys, Next: Deleting Keys, Prev: Exporting Keys, Up: Key Management 4548 45497.5.8 Importing Keys 4550-------------------- 4551 4552Importing keys means the same as running ‘gpg’ with the command 4553‘--import’. 4554 4555 -- Function: gpgme_error_t gpgme_op_import (gpgme_ctx_t CTX, 4556 gpgme_data_t KEYDATA) 4557 The function ‘gpgme_op_import’ adds the keys in the data buffer 4558 KEYDATA to the key ring of the crypto engine used by CTX. The 4559 format of KEYDATA can be ASCII armored, for example, but the 4560 details are specific to the crypto engine. 4561 4562 After the operation completed successfully, the result can be 4563 retrieved with ‘gpgme_op_import_result’. 4564 4565 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the 4566 import was completed successfully, ‘GPG_ERR_INV_VALUE’ if KEYDATA 4567 if CTX or KEYDATA is not a valid pointer, and ‘GPG_ERR_NO_DATA’ if 4568 KEYDATA is an empty data buffer. 4569 4570 -- Function: gpgme_error_t gpgme_op_import_start (gpgme_ctx_t CTX, 4571 gpgme_data_t KEYDATA) 4572 The function ‘gpgme_op_import_start’ initiates a ‘gpgme_op_import’ 4573 operation. It can be completed by calling ‘gpgme_wait’ on the 4574 context. *Note Waiting For Completion::. 4575 4576 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the 4577 import could be started successfully, ‘GPG_ERR_INV_VALUE’ if CTX or 4578 KEYDATA is not a valid pointer, and ‘GPG_ERR_NO_DATA’ if KEYDATA is 4579 an empty data buffer. 4580 4581 -- Function: gpgme_error_t gpgme_op_import_keys (gpgme_ctx_t CTX, 4582 gpgme_key_t *KEYS) 4583 SINCE: 1.2.0 4584 4585 The function ‘gpgme_op_import_keys’ adds the keys described by the 4586 ‘NULL’ terminated array KEYS to the key ring of the crypto engine 4587 used by CTX. It is used to actually import and make keys permanent 4588 which have been retrieved from an external source (i.e. using 4589 ‘GPGME_KEYLIST_MODE_EXTERN’) earlier. The external keylisting must 4590 have been made with the same context configuration (in particular 4591 the same home directory). (1) Note that for OpenPGP this may 4592 require another access to the keyserver over the network. 4593 4594 Only keys of the currently selected protocol of CTX are considered 4595 for import. Other keys specified by the KEYS are ignored. As of 4596 now all considered keys must have been retrieved using the same 4597 method, i.e. the used key listing mode must be identical. 4598 4599 After the operation completed successfully, the result can be 4600 retrieved with ‘gpgme_op_import_result’. 4601 4602 To move keys from one home directory to another, export and import 4603 the keydata using ‘gpgme_op_export’ and ‘gpgme_op_import’. 4604 4605 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the 4606 import was completed successfully, ‘GPG_ERR_INV_VALUE’ if CTX is 4607 not a valid pointer, ‘GPG_ERR_CONFLICT’ if the key listing mode 4608 does not match, and ‘GPG_ERR_NO_DATA’ if no keys are considered for 4609 export. 4610 4611 -- Function: gpgme_error_t gpgme_op_import_keys_start (gpgme_ctx_t CTX, 4612 gpgme_key_t *KEYS) 4613 SINCE: 1.2.0 4614 4615 The function ‘gpgme_op_import_keys_start’ initiates a 4616 ‘gpgme_op_import_keys’ operation. It can be completed by calling 4617 ‘gpgme_wait’ on the context. *Note Waiting For Completion::. 4618 4619 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the 4620 import was completed successfully, ‘GPG_ERR_INV_VALUE’ if KEYDATA 4621 if CTX or KEYDATA is not a valid pointer, ‘GPG_ERR_CONFLICT’ if the 4622 key listing mode does not match, and ‘GPG_ERR_NO_DATA’ if no keys 4623 are considered for export. 4624 4625 -- Data type: gpgme_import_status_t 4626 This is a pointer to a structure used to store a part of the result 4627 of a ‘gpgme_op_import’ operation. For each considered key one 4628 status is added that contains information about the result of the 4629 import. The structure contains the following members: 4630 4631 ‘gpgme_import_status_t next’ 4632 This is a pointer to the next status structure in the linked 4633 list, or ‘NULL’ if this is the last element. 4634 4635 ‘char *fpr’ 4636 This is the fingerprint of the key that was considered. 4637 4638 ‘gpgme_error_t result’ 4639 If the import was not successful, this is the error value that 4640 caused the import to fail. Otherwise the error code is 4641 ‘GPG_ERR_NO_ERROR’. 4642 4643 ‘unsigned int status’ 4644 This is a bit-wise OR of the following flags that give more 4645 information about what part of the key was imported. If the 4646 key was already known, this might be 0. 4647 4648 ‘GPGME_IMPORT_NEW’ 4649 The key was new. 4650 4651 ‘GPGME_IMPORT_UID’ 4652 The key contained new user IDs. 4653 4654 ‘GPGME_IMPORT_SIG’ 4655 The key contained new signatures. 4656 4657 ‘GPGME_IMPORT_SUBKEY’ 4658 The key contained new sub keys. 4659 4660 ‘GPGME_IMPORT_SECRET’ 4661 The key contained a secret key. 4662 4663 -- Data type: gpgme_import_result_t 4664 This is a pointer to a structure used to store the result of a 4665 ‘gpgme_op_import’ operation. After a successful import operation, 4666 you can retrieve the pointer to the result with 4667 ‘gpgme_op_import_result’. The structure contains the following 4668 members: 4669 4670 ‘int considered’ 4671 The total number of considered keys. 4672 4673 ‘int no_user_id’ 4674 The number of keys without user ID. 4675 4676 ‘int imported’ 4677 The total number of imported keys. 4678 4679 ‘int imported_rsa’ 4680 The number of imported RSA keys. 4681 4682 ‘int unchanged’ 4683 The number of unchanged keys. 4684 4685 ‘int new_user_ids’ 4686 The number of new user IDs. 4687 4688 ‘int new_sub_keys’ 4689 The number of new sub keys. 4690 4691 ‘int new_signatures’ 4692 The number of new signatures. 4693 4694 ‘int new_revocations’ 4695 The number of new revocations. 4696 4697 ‘int secret_read’ 4698 The total number of secret keys read. 4699 4700 ‘int secret_imported’ 4701 The number of imported secret keys. 4702 4703 ‘int secret_unchanged’ 4704 The number of unchanged secret keys. 4705 4706 ‘int not_imported’ 4707 The number of keys not imported. 4708 4709 ‘gpgme_import_status_t imports’ 4710 A list of gpgme_import_status_t objects which contain more 4711 information about the keys for which an import was attempted. 4712 4713 ‘int skipped_v3_keys’ 4714 For security reasons modern versions of GnuPG do not anymore 4715 support v3 keys (created with PGP 2.x) and ignores them on 4716 import. This counter provides the number of such skipped v3 4717 keys. 4718 4719 -- Function: gpgme_import_result_t gpgme_op_import_result 4720 (gpgme_ctx_t CTX) 4721 The function ‘gpgme_op_import_result’ returns a 4722 ‘gpgme_import_result_t’ pointer to a structure holding the result 4723 of a ‘gpgme_op_import’ operation. The pointer is only valid if the 4724 last operation on the context was a ‘gpgme_op_import’ or 4725 ‘gpgme_op_import_start’ operation, and if this operation finished 4726 successfully. The returned pointer is only valid until the next 4727 operation is started on the context. 4728 4729 ---------- Footnotes ---------- 4730 4731 (1) Thus it is a replacement for the usual workaround of exporting 4732and then importing a key to make an X.509 key permanent. 4733 4734 4735File: gpgme.info, Node: Deleting Keys, Next: Changing Passphrases, Prev: Importing Keys, Up: Key Management 4736 47377.5.9 Deleting Keys 4738------------------- 4739 4740 -- Function: gpgme_error_t gpgme_op_delete_ext (gpgme_ctx_t CTX, 4741 const gpgme_key_t KEY, unsigned int FLAGS) 4742 SINCE: 1.9.1 4743 4744 The function ‘gpgme_op_delete_ext’ deletes the key KEY from the key 4745 ring of the crypto engine used by CTX. 4746 4747 FLAGS can be set to the bit-wise OR of the following flags: 4748 4749 ‘GPGME_DELETE_ALLOW_SECRET’ 4750 SINCE: 1.9.1 4751 4752 If not set, only public keys are deleted. If set, secret keys 4753 are deleted as well, if that is supported. 4754 4755 ‘GPGME_DELETE_FORCE’ 4756 SINCE: 1.9.1 4757 4758 If set, the user is not asked to confirm the deletion. 4759 4760 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the key 4761 was deleted successfully, ‘GPG_ERR_INV_VALUE’ if CTX or KEY is not 4762 a valid pointer, ‘GPG_ERR_NO_PUBKEY’ if KEY could not be found in 4763 the keyring, ‘GPG_ERR_AMBIGUOUS_NAME’ if the key was not specified 4764 unambiguously, and ‘GPG_ERR_CONFLICT’ if the secret key for KEY is 4765 available, but ALLOW_SECRET is zero. 4766 4767 -- Function: gpgme_error_t gpgme_op_delete_ext_start (gpgme_ctx_t CTX, 4768 const gpgme_key_t KEY, unsigned int FLAGS) 4769 SINCE: 1.9.1 4770 4771 The function ‘gpgme_op_delete_ext_start’ initiates a 4772 ‘gpgme_op_delete’ operation. It can be completed by calling 4773 ‘gpgme_wait’ on the context. *Note Waiting For Completion::. 4774 4775 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the 4776 operation was started successfully, and ‘GPG_ERR_INV_VALUE’ if CTX 4777 or KEY is not a valid pointer. 4778 4779 The following functions allow only to use one particular flag. 4780 4781 -- Function: gpgme_error_t gpgme_op_delete (gpgme_ctx_t CTX, 4782 const gpgme_key_t KEY, int ALLOW_SECRET) 4783 Similar to ‘gpgme_op_delete_ext’, but only the flag 4784 ‘GPGME_DELETE_ALLOW_SECRET’ can be provided. 4785 4786 -- Function: gpgme_error_t gpgme_op_delete_start (gpgme_ctx_t CTX, 4787 const gpgme_key_t KEY, int ALLOW_SECRET) 4788 Similar to ‘gpgme_op_delete_ext_start’, but only the flag 4789 ‘GPGME_DELETE_ALLOW_SECRET’ can be provided. 4790 4791 4792File: gpgme.info, Node: Changing Passphrases, Next: Changing TOFU Data, Prev: Deleting Keys, Up: Key Management 4793 47947.5.10 Changing Passphrases 4795--------------------------- 4796 4797 -- Function: gpgme_error_t gpgme_op_passwd (gpgme_ctx_t CTX, 4798 const gpgme_key_t KEY, unsigned int FLAGS) 4799 4800 SINCE: 1.3.0 4801 4802 The function ‘gpgme_op_passwd’ changes the passphrase of the 4803 private key associated with KEY. The only allowed value for FLAGS 4804 is ‘0’. The backend engine will usually popup a window to ask for 4805 the old and the new passphrase. Thus this function is not useful 4806 in a server application (where passphrases are not required 4807 anyway). 4808 4809 Note that old ‘gpg’ engines (before version 2.0.15) do not support 4810 this command and will silently ignore it. 4811 4812 -- Function: gpgme_error_t gpgme_op_passwd_start (gpgme_ctx_t CTX, 4813 const gpgme_key_t KEY, unsigned int FLAGS) 4814 4815 SINCE: 1.3.0 4816 4817 The function ‘gpgme_op_passwd_start’ initiates a ‘gpgme_op_passwd’ 4818 operation. It can be completed by calling ‘gpgme_wait’ on the 4819 context. *Note Waiting For Completion::. 4820 4821 The function returns ‘0’ if the operation was started successfully, 4822 and an error code if one of the arguments is not valid or the 4823 oepration could not be started. 4824 4825 4826File: gpgme.info, Node: Changing TOFU Data, Next: Advanced Key Editing, Prev: Changing Passphrases, Up: Key Management 4827 48287.5.11 Changing TOFU Data 4829------------------------- 4830 4831The OpenPGP engine features a Trust-On-First-Use (TOFU) key validation 4832model. For resolving conflicts it is necessary to declare the policy 4833for a key. See the GnuPG manual for details on the TOFU implementation. 4834 4835 -- Data type: enum gpgme_tofu_policy_t 4836 SINCE: 1.7.0 4837 4838 The ‘gpgme_tofu_policy_t’ type specifies the set of possible policy 4839 values that are supported by GPGME: 4840 4841 ‘GPGME_TOFU_POLICY_AUTO’ 4842 Set the policy to “auto”. 4843 ‘GPGME_TOFU_POLICY_GOOD’ 4844 Set the policy to “good”. 4845 ‘GPGME_TOFU_POLICY_BAD’ 4846 Set the policy to “bad”. 4847 ‘GPGME_TOFU_POLICY_ASK’ 4848 Set the policy to “ask”. 4849 ‘GPGME_TOFU_POLICY_UNKNOWN’ 4850 Set the policy to “unknown”. 4851 4852 To change the policy for a key the following functions can be used: 4853 4854 -- Function: gpgme_error_t gpgme_op_tofu_policy (gpgme_ctx_t CTX, 4855 const gpgme_key_t KEY, gpgme_tofu_policy_t POLICY) 4856 4857 SINCE: 1.7.0 4858 4859 The function ‘gpgme_op_tofu_policy’ changes the TOFU policy of KEY. 4860 The valid values for POLICY are listed above. As of now this 4861 function does only work for OpenPGP and requires at least version 4862 2.1.10 of GnuPG. 4863 4864 The function returns zero on success, ‘GPG_ERR_NOT_SUPPORTED’ if 4865 the engine does not support the command, or a bunch of other error 4866 codes. 4867 4868 -- Function: gpgme_error_t gpgme_op_tofu_policy_start (gpgme_ctx_t CTX, 4869 const gpgme_key_t KEY, gpgme_tofu_policy_t POLICY) 4870 4871 SINCE: 1.7.0 4872 4873 The function ‘gpgme_op_tofu_policy_start’ initiates a 4874 ‘gpgme_op_tofu_policy’ operation. It can be completed by calling 4875 ‘gpgme_wait’ on the context. *Note Waiting For Completion::. 4876 4877 The function returns ‘0’ if the operation was started successfully, 4878 and an error code if one of the arguments is not valid or the 4879 oepration could not be started. 4880 4881 4882File: gpgme.info, Node: Advanced Key Editing, Prev: Changing TOFU Data, Up: Key Management 4883 48847.5.12 Advanced Key Editing 4885--------------------------- 4886 4887 -- Data type: gpgme_error_t (*gpgme_interact_cb_t) (void *HANDLE, 4888 const char *STATUS, const char *ARGS, int FD) 4889 4890 SINCE: 1.7.0 4891 4892 The ‘gpgme_interact_cb_t’ type is the type of functions which GPGME 4893 calls if it a key interact operation is on-going. The status 4894 keyword STATUS and the argument line ARGS are passed through by 4895 GPGME from the crypto engine. An empty string represents EOF. The 4896 file descriptor FD is -1 for normal status messages. If STATUS 4897 indicates a command rather than a status message, the response to 4898 the command should be written to FD. The HANDLE is provided by the 4899 user at start of operation. 4900 4901 The function should return ‘GPG_ERR_FALSE’ if it did not handle the 4902 status code, ‘0’ for success, or any other error value. 4903 4904 -- Function: gpgme_error_t gpgme_op_interact (gpgme_ctx_t CTX, 4905 gpgme_key_t KEY, unsigned int FLAGS, gpgme_interact_cb_t FNC, 4906 void *HANDLE, gpgme_data_t OUT) 4907 4908 SINCE: 1.7.0 4909 4910 The function ‘gpgme_op_interact’ processes the key KEY 4911 interactively, using the interact callback function FNC with the 4912 handle HANDLE. The callback is invoked for every status and 4913 command request from the crypto engine. The output of the crypto 4914 engine is written to the data object OUT. 4915 4916 Note that the protocol between the callback function and the crypto 4917 engine is specific to the crypto engine and no further support in 4918 implementing this protocol correctly is provided by GPGME. 4919 4920 FLAGS modifies the behaviour of the function; the only defined bit 4921 value is: 4922 4923 ‘GPGME_INTERACT_CARD’ 4924 SINCE: 1.7.0 4925 4926 This is used for smartcard based keys and uses gpg’s 4927 ‘--card-edit’ command. 4928 4929 The function returns ‘0’ if the edit operation completes 4930 successfully, ‘GPG_ERR_INV_VALUE’ if CTX or KEY is not a valid 4931 pointer, and any error returned by the crypto engine or the edit 4932 callback handler. 4933 4934 -- Function: gpgme_error_t gpgme_op_interact_start (gpgme_ctx_t CTX, 4935 gpgme_key_t KEY, unsigned int FLAGS, gpgme_interact_cb_t FNC, 4936 void *HANDLE, gpgme_data_t OUT) 4937 4938 SINCE: 1.7.0 4939 4940 The function ‘gpgme_op_interact_start’ initiates a 4941 ‘gpgme_op_interact’ operation. It can be completed by calling 4942 ‘gpgme_wait’ on the context. *Note Waiting For Completion::. 4943 4944 The function returns ‘0’ if the operation was started successfully, 4945 and ‘GPG_ERR_INV_VALUE’ if CTX or KEY is not a valid pointer. 4946 4947 4948File: gpgme.info, Node: Crypto Operations, Next: Miscellaneous, Prev: Key Management, Up: Contexts 4949 49507.6 Crypto Operations 4951===================== 4952 4953Sometimes, the result of a crypto operation returns a list of invalid 4954keys encountered in processing the request. The following structure is 4955used to hold information about such a key. 4956 4957 -- Data type: gpgme_invalid_key_t 4958 This is a pointer to a structure used to store a part of the result 4959 of a crypto operation which takes user IDs as one input parameter. 4960 The structure contains the following members: 4961 4962 ‘gpgme_invalid_key_t next’ 4963 This is a pointer to the next invalid key structure in the 4964 linked list, or ‘NULL’ if this is the last element. 4965 4966 ‘char *fpr’ 4967 The fingerprint or key ID of the invalid key encountered. 4968 4969 ‘gpgme_error_t reason’ 4970 An error code describing the reason why the key was found 4971 invalid. 4972 4973* Menu: 4974 4975* Decrypt:: Decrypting a ciphertext. 4976* Verify:: Verifying a signature. 4977* Decrypt and Verify:: Decrypting a signed ciphertext. 4978* Sign:: Creating a signature. 4979* Encrypt:: Encrypting a plaintext. 4980 4981 4982File: gpgme.info, Node: Decrypt, Next: Verify, Up: Crypto Operations 4983 49847.6.1 Decrypt 4985------------- 4986 4987 -- Function: gpgme_error_t gpgme_op_decrypt (gpgme_ctx_t CTX, 4988 gpgme_data_t CIPHER, gpgme_data_t PLAIN) 4989 The function ‘gpgme_op_decrypt’ decrypts the ciphertext in the data 4990 object CIPHER and stores it into the data object PLAIN. 4991 4992 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the 4993 ciphertext could be decrypted successfully, ‘GPG_ERR_INV_VALUE’ if 4994 CTX, CIPHER or PLAIN is not a valid pointer, ‘GPG_ERR_NO_DATA’ if 4995 CIPHER does not contain any data to decrypt, 4996 ‘GPG_ERR_DECRYPT_FAILED’ if CIPHER is not a valid cipher text, 4997 ‘GPG_ERR_BAD_PASSPHRASE’ if the passphrase for the secret key could 4998 not be retrieved, and passes through some errors that are reported 4999 by the crypto engine support routines. 5000 5001 -- Function: gpgme_error_t gpgme_op_decrypt_start (gpgme_ctx_t CTX, 5002 gpgme_data_t CIPHER, gpgme_data_t PLAIN) 5003 The function ‘gpgme_op_decrypt_start’ initiates a 5004 ‘gpgme_op_decrypt’ operation. It can be completed by calling 5005 ‘gpgme_wait’ on the context. *Note Waiting For Completion::. 5006 5007 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the 5008 operation could be started successfully, and ‘GPG_ERR_INV_VALUE’ if 5009 CIPHER or PLAIN is not a valid pointer. 5010 5011 -- Function: gpgme_error_t gpgme_op_decrypt_ext ( gpgme_ctx_t CTX, 5012 gpgme_decrypt_flags_t FLAGS, gpgme_data_t CIPHER, 5013 gpgme_data_t PLAIN) 5014 5015 SINCE: 1.8.0 5016 5017 The function ‘gpgme_op_decrypt_ext’ is the same as 5018 ‘gpgme_op_decrypt’ but has an additional argument FLAGS. If FLAGS 5019 is 0 both function behave identically. 5020 5021 The value in FLAGS is a bitwise-or combination of one or multiple 5022 of the following bit values: 5023 5024 ‘GPGME_DECRYPT_VERIFY’ 5025 SINCE: 1.8.0 5026 5027 The ‘GPGME_DECRYPT_VERIFY’ symbol specifies that this function 5028 shall exactly act as ‘gpgme_op_decrypt_verify’. 5029 5030 ‘GPGME_DECRYPT_UNWRAP’ 5031 SINCE: 1.8.0 5032 5033 The ‘GPGME_DECRYPT_UNWRAP’ symbol specifies that the output 5034 shall be an OpenPGP message with only the encryption layer 5035 removed. This requires GnuPG 2.1.12 and works only for 5036 OpenPGP. This is the counterpart to ‘GPGME_ENCRYPT_WRAP’. 5037 5038 The function returns the error codes as described for 5039 ‘gpgme_op_decrypt’. 5040 5041 -- Function: gpgme_error_t gpgme_op_decrypt_ext_start ( 5042 gpgme_ctx_t CTX, gpgme_decrypt_flags_t FLAGS, 5043 gpgme_data_t CIPHER, gpgme_data_t PLAIN) 5044 5045 SINCE: 1.8.0 5046 5047 The function ‘gpgme_op_decrypt_ext_start’ initiates a 5048 ‘gpgme_op_decrypt_ext’ operation. It can be completed by calling 5049 ‘gpgme_wait’ on the context. *Note Waiting For Completion::. 5050 5051 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the 5052 operation could be started successfully, and ‘GPG_ERR_INV_VALUE’ if 5053 CIPHER or PLAIN is not a valid pointer. 5054 5055 -- Data type: gpgme_recipient_t 5056 SINCE: 1.1.0 5057 5058 This is a pointer to a structure used to store information about 5059 the recipient of an encrypted text which is decrypted in a 5060 ‘gpgme_op_decrypt’ operation. This information (except for the 5061 status field) is even available before the operation finished 5062 successfully, for example in a passphrase callback. The structure 5063 contains the following members: 5064 5065 ‘gpgme_recipient_t next’ 5066 This is a pointer to the next recipient structure in the 5067 linked list, or ‘NULL’ if this is the last element. 5068 5069 ‘gpgme_pubkey_algo_t’ 5070 The public key algorithm used in the encryption. 5071 5072 ‘char *keyid’ 5073 This is the key ID of the key (in hexadecimal digits) used as 5074 recipient. 5075 5076 ‘gpgme_error_t status’ 5077 This is an error number with the error code GPG_ERR_NO_SECKEY 5078 if the secret key for this recipient is not available, and 0 5079 otherwise. 5080 5081 -- Data type: gpgme_decrypt_result_t 5082 This is a pointer to a structure used to store the result of a 5083 ‘gpgme_op_decrypt’ operation. After successfully decrypting data, 5084 you can retrieve the pointer to the result with 5085 ‘gpgme_op_decrypt_result’. As with all result structures, it this 5086 structure shall be considered read-only and an application must not 5087 allocate such a strucure on its own. The structure contains the 5088 following members: 5089 5090 ‘char *unsupported_algorithm’ 5091 If an unsupported algorithm was encountered, this string 5092 describes the algorithm that is not supported. 5093 5094 ‘unsigned int wrong_key_usage : 1’ 5095 SINCE: 0.9.0 This is true if the key was not used according to 5096 its policy. 5097 5098 ‘unsigned int legacy_cipher_nomdc : 1’ 5099 SINCE: 1.11.2 The message was made by a legacy algorithm 5100 without any integrity protection. This might be an old but 5101 legitimate message. 5102 5103 ‘unsigned int is_mime : 1;’ 5104 SINCE: 1.11.0 The message claims that the content is a MIME 5105 object. 5106 5107 ‘unsigned int is_de_vs : 1;’ 5108 SINCE: 1.10.0 The message was encrypted in a VS-NfD compliant 5109 way. This is a specification in Germany for a restricted 5110 communication level. 5111 5112 ‘gpgme_recipient_t recipients’ 5113 SINCE: 1.1.0 5114 5115 This is a linked list of recipients to which this message was 5116 encrypted. 5117 5118 ‘char *file_name’ 5119 This is the filename of the original plaintext message file if 5120 it is known, otherwise this is a null pointer. 5121 5122 ‘char *session_key’ 5123 SINCE: 1.8.0 5124 5125 A textual representation (nul-terminated string) of the 5126 session key used in symmetric encryption of the message, if 5127 the context has been set to export session keys (see 5128 ‘gpgme_set_ctx_flag, "export-session-key"’), and a session key 5129 was available for the most recent decryption operation. 5130 Otherwise, this is a null pointer. 5131 5132 You must not try to access this member of the struct unless 5133 ‘gpgme_set_ctx_flag (ctx, "export-session-key")’ returns 5134 success or ‘gpgme_get_ctx_flag (ctx, "export-session-key")’ 5135 returns true (non-empty string). 5136 5137 ‘char *symkey_algo’ 5138 SINCE: 1.11.0 5139 5140 A string with the symmetric encryption algorithm and mode 5141 using the format "<algo>.<mode>". Note that the deprecated 5142 non-MDC encryption mode of OpenPGP is given as "PGPCFB". 5143 5144 -- Function: gpgme_decrypt_result_t gpgme_op_decrypt_result 5145 (gpgme_ctx_t CTX) 5146 The function ‘gpgme_op_decrypt_result’ returns a 5147 ‘gpgme_decrypt_result_t’ pointer to a structure holding the result 5148 of a ‘gpgme_op_decrypt’ operation. The pointer is only valid if 5149 the last operation on the context was a ‘gpgme_op_decrypt’ or 5150 ‘gpgme_op_decrypt_start’ operation. If the operation failed this 5151 might be a ‘NULL’ pointer. The returned pointer is only valid 5152 until the next operation is started on the context. 5153 5154 5155File: gpgme.info, Node: Verify, Next: Decrypt and Verify, Prev: Decrypt, Up: Crypto Operations 5156 51577.6.2 Verify 5158------------ 5159 5160 -- Function: gpgme_error_t gpgme_op_verify (gpgme_ctx_t CTX, 5161 gpgme_data_t SIG, gpgme_data_t SIGNED_TEXT, 5162 gpgme_data_t PLAIN) 5163 The function ‘gpgme_op_verify’ verifies that the signature in the 5164 data object SIG is a valid signature. If SIG is a detached 5165 signature, then the signed text should be provided in SIGNED_TEXT 5166 and PLAIN should be a null pointer. Otherwise, if SIG is a normal 5167 (or cleartext) signature, SIGNED_TEXT should be a null pointer and 5168 PLAIN should be a writable data object that will contain the 5169 plaintext after successful verification. 5170 5171 The results of the individual signature verifications can be 5172 retrieved with ‘gpgme_op_verify_result’. 5173 5174 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the 5175 operation could be completed successfully, ‘GPG_ERR_INV_VALUE’ if 5176 CTX, SIG or PLAIN is not a valid pointer, ‘GPG_ERR_NO_DATA’ if SIG 5177 does not contain any data to verify, and passes through any errors 5178 that are reported by the crypto engine support routines. 5179 5180 -- Function: gpgme_error_t gpgme_op_verify_start (gpgme_ctx_t CTX, 5181 gpgme_data_t SIG, gpgme_data_t SIGNED_TEXT, 5182 gpgme_data_t PLAIN) 5183 The function ‘gpgme_op_verify_start’ initiates a ‘gpgme_op_verify’ 5184 operation. It can be completed by calling ‘gpgme_wait’ on the 5185 context. *Note Waiting For Completion::. 5186 5187 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the 5188 operation could be started successfully, ‘GPG_ERR_INV_VALUE’ if 5189 CTX, SIG or PLAIN is not a valid pointer, and ‘GPG_ERR_NO_DATA’ if 5190 SIG or PLAIN does not contain any data to verify. 5191 5192 -- Data type: gpgme_sig_notation_t 5193 This is a pointer to a structure used to store a part of the result 5194 of a ‘gpgme_op_verify’ operation. The structure contains the 5195 following members: 5196 5197 ‘gpgme_sig_notation_t next’ 5198 This is a pointer to the next new signature notation structure 5199 in the linked list, or ‘NULL’ if this is the last element. 5200 5201 ‘char *name’ 5202 The name of the notation field. If this is ‘NULL’, then the 5203 member ‘value’ will contain a policy URL. 5204 5205 ‘int name_len’ 5206 The length of the ‘name’ field. For strings the length is 5207 counted without the trailing binary zero. 5208 5209 ‘char *value’ 5210 The value of the notation field. If ‘name’ is ‘NULL’, then 5211 this is a policy URL. 5212 5213 ‘int value_len’ 5214 The length of the ‘value’ field. For strings the length is 5215 counted without the trailing binary zero. 5216 5217 ‘gpgme_sig_notation_flags_t flags’ 5218 The accumulated flags field. This field contains the flags 5219 associated with the notation data in an accumulated form which 5220 can be used as an argument to the function 5221 ‘gpgme_sig_notation_add’. The value ‘flags’ is a bitwise-or 5222 combination of one or multiple of the following bit values: 5223 5224 ‘GPGME_SIG_NOTATION_HUMAN_READABLE’ 5225 SINCE: 1.1.0 5226 5227 The ‘GPGME_SIG_NOTATION_HUMAN_READABLE’ symbol specifies 5228 that the notation data is in human readable form 5229 5230 ‘GPGME_SIG_NOTATION_CRITICAL’ 5231 SINCE: 1.1.0 5232 5233 The ‘GPGME_SIG_NOTATION_CRITICAL’ symbol specifies that 5234 the notation data is critical. 5235 5236 ‘unsigned int human_readable : 1’ 5237 This is true if the ‘GPGME_SIG_NOTATION_HUMAN_READABLE’ flag 5238 is set and false otherwise. This flag is only valid for 5239 notation data, not for policy URLs. 5240 5241 ‘unsigned int critical : 1’ 5242 This is true if the ‘GPGME_SIG_NOTATION_CRITICAL’ flag is set 5243 and false otherwise. This flag is valid for notation data and 5244 policy URLs. 5245 5246 -- Data type: gpgme_signature_t 5247 This is a pointer to a structure used to store a part of the result 5248 of a ‘gpgme_op_verify’ operation. The structure contains the 5249 following members: 5250 5251 ‘gpgme_signature_t next’ 5252 This is a pointer to the next new signature structure in the 5253 linked list, or ‘NULL’ if this is the last element. 5254 5255 ‘gpgme_sigsum_t summary’ 5256 This is a bit vector giving a summary of the signature status. 5257 It provides an easy interface to a defined semantic of the 5258 signature status. Checking just one bit is sufficient to see 5259 whether a signature is valid without any restrictions. This 5260 means that you can check for GPGME_SIGSUM_VALID like this: 5261 5262 if ((sig.summary & GPGME_SIGSUM_VALID)) 5263 { 5264 ..do stuff if valid.. 5265 } 5266 else 5267 { 5268 ..do stuff if not fully valid.. 5269 } 5270 5271 The defined bits are: 5272 ‘GPGME_SIGSUM_VALID’ 5273 The signature is fully valid. 5274 5275 ‘GPGME_SIGSUM_GREEN’ 5276 The signature is good but one might want to display some 5277 extra information. Check the other bits. 5278 5279 ‘GPGME_SIGSUM_RED’ 5280 The signature is bad. It might be useful to check other 5281 bits and display more information, i.e. a revoked 5282 certificate might not render a signature invalid when the 5283 message was received prior to the cause for the 5284 revocation. 5285 5286 ‘GPGME_SIGSUM_KEY_REVOKED’ 5287 The key or at least one certificate has been revoked. 5288 5289 ‘GPGME_SIGSUM_KEY_EXPIRED’ 5290 The key or one of the certificates has expired. It is 5291 probably a good idea to display the date of the 5292 expiration. 5293 5294 ‘GPGME_SIGSUM_SIG_EXPIRED’ 5295 The signature has expired. 5296 5297 ‘GPGME_SIGSUM_KEY_MISSING’ 5298 Can’t verify due to a missing key or certificate. 5299 5300 ‘GPGME_SIGSUM_CRL_MISSING’ 5301 The CRL (or an equivalent mechanism) is not available. 5302 5303 ‘GPGME_SIGSUM_CRL_TOO_OLD’ 5304 Available CRL is too old. 5305 5306 ‘GPGME_SIGSUM_BAD_POLICY’ 5307 A policy requirement was not met. 5308 5309 ‘GPGME_SIGSUM_SYS_ERROR’ 5310 A system error occurred. 5311 5312 ‘GPGME_SIGSUM_TOFU_CONFLICT’ 5313 A TOFU conflict was detected. 5314 5315 ‘char *fpr’ 5316 This is the fingerprint or key ID of the signature. 5317 5318 ‘gpgme_error_t status’ 5319 This is the status of the signature. In particular, the 5320 following status codes are of interest: 5321 5322 ‘GPG_ERR_NO_ERROR’ 5323 This status indicates that the signature could be 5324 verified or that there is no signature. For the combined 5325 result this status means that all signatures could be 5326 verified. 5327 5328 Note: This does not mean that a valid signature could be 5329 found. Check the ‘summary’ field for that. 5330 5331 For example a ‘gpgme_op_decrypt_verify’ returns a 5332 verification result with GPG_ERR_NO_ERROR for encrypted 5333 but unsigned data. 5334 5335 ‘GPG_ERR_SIG_EXPIRED’ 5336 This status indicates that the signature is valid but 5337 expired. For the combined result this status means that 5338 all signatures are valid and expired. 5339 5340 ‘GPG_ERR_KEY_EXPIRED’ 5341 This status indicates that the signature is valid but the 5342 key used to verify the signature has expired. For the 5343 combined result this status means that all signatures are 5344 valid and all keys are expired. 5345 5346 ‘GPG_ERR_CERT_REVOKED’ 5347 This status indicates that the signature is valid but the 5348 key used to verify the signature has been revoked. For 5349 the combined result this status means that all signatures 5350 are valid and all keys are revoked. 5351 5352 ‘GPG_ERR_BAD_SIGNATURE’ 5353 This status indicates that the signature is invalid. For 5354 the combined result this status means that all signatures 5355 are invalid. 5356 5357 ‘GPG_ERR_NO_PUBKEY’ 5358 This status indicates that the signature could not be 5359 verified due to a missing key. For the combined result 5360 this status means that all signatures could not be 5361 checked due to missing keys. 5362 5363 ‘GPG_ERR_GENERAL’ 5364 This status indicates that there was some other error 5365 which prevented the signature verification. 5366 5367 ‘gpgme_sig_notation_t notations’ 5368 This is a linked list with the notation data and policy URLs. 5369 5370 ‘unsigned long timestamp’ 5371 The creation timestamp of this signature. 5372 5373 ‘unsigned long exp_timestamp’ 5374 The expiration timestamp of this signature, or 0 if the 5375 signature does not expire. 5376 5377 ‘unsigned int wrong_key_usage : 1’ 5378 This is true if the key was not used according to its policy. 5379 5380 ‘unsigned int pka_trust : 2’ 5381 This is set to the trust information gained by means of the 5382 PKA system. Values are: 5383 ‘0’ 5384 No PKA information available or verification not 5385 possible. 5386 ‘1’ 5387 PKA verification failed. 5388 ‘2’ 5389 PKA verification succeeded. 5390 ‘3’ 5391 Reserved for future use. 5392 Depending on the configuration of the engine, this metric may 5393 also be reflected by the validity of the signature. 5394 5395 ‘unsigned int chain_model : 1’ 5396 SINCE: 1.1.6 5397 5398 This is true if the validity of the signature has been checked 5399 using the chain model. In the chain model the time the 5400 signature has been created must be within the validity period 5401 of the certificate and the time the certificate itself has 5402 been created must be within the validity period of the issuing 5403 certificate. In contrast the default validation model checks 5404 the validity of signature as well at the entire certificate 5405 chain at the current time. 5406 5407 ‘gpgme_validity_t validity’ 5408 The validity of the signature. 5409 5410 ‘gpgme_error_t validity_reason’ 5411 If a signature is not valid, this provides a reason why. 5412 5413 ‘gpgme_pubkey_algo_t’ 5414 The public key algorithm used to create this signature. 5415 5416 ‘gpgme_hash_algo_t’ 5417 The hash algorithm used to create this signature. 5418 5419 ‘char *pka_address’ 5420 The mailbox from the PKA information or ‘NULL’. 5421 5422 ‘gpgme_key_t key’ 5423 SINCE: 1.7.0 5424 5425 An object describing the key used to create the signature. 5426 This key object may be incomplete in that it only conveys 5427 information availabale directly with a signature. It may also 5428 be ‘NULL’ if such information is not readily available. 5429 5430 -- Data type: gpgme_verify_result_t 5431 This is a pointer to a structure used to store the result of a 5432 ‘gpgme_op_verify’ operation. After verifying a signature, you can 5433 retrieve the pointer to the result with ‘gpgme_op_verify_result’. 5434 If the operation failed this might be a ‘NULL’ pointer. The 5435 structure contains the following member: 5436 5437 ‘gpgme_signature_t signatures’ 5438 A linked list with information about all signatures for which 5439 a verification was attempted. 5440 5441 ‘char *file_name’ 5442 This is the filename of the original plaintext message file if 5443 it is known, otherwise this is a null pointer. Warning: The 5444 filename is not covered by the signature. 5445 5446 ‘unsigned int is_mime : 1;’ 5447 SINCE: 1.11.0 5448 5449 The message claims that the content is a MIME object. 5450 Warning: This flag is not covered by the signature. 5451 5452 -- Function: gpgme_verify_result_t gpgme_op_verify_result 5453 (gpgme_ctx_t CTX) 5454 The function ‘gpgme_op_verify_result’ returns a 5455 ‘gpgme_verify_result_t’ pointer to a structure holding the result 5456 of a ‘gpgme_op_verify’ operation. The pointer is only valid if the 5457 last operation on the context was a ‘gpgme_op_verify’, 5458 ‘gpgme_op_verify_start’, ‘gpgme_op_decrypt_verify’ or 5459 ‘gpgme_op_decrypt_verify_start’ operation, and if this operation 5460 finished successfully (for ‘gpgme_op_decrypt_verify’ and 5461 ‘gpgme_op_decrypt_verify_start’, the error code ‘GPG_ERR_NO_DATA’ 5462 counts as successful in this context). The returned pointer is 5463 only valid until the next operation is started on the context. 5464 5465 5466File: gpgme.info, Node: Decrypt and Verify, Next: Sign, Prev: Verify, Up: Crypto Operations 5467 54687.6.3 Decrypt and Verify 5469------------------------ 5470 5471 -- Function: gpgme_error_t gpgme_op_decrypt_verify (gpgme_ctx_t CTX, 5472 gpgme_data_t CIPHER, gpgme_data_t PLAIN) 5473 The function ‘gpgme_op_decrypt_verify’ decrypts the ciphertext in 5474 the data object CIPHER and stores it into the data object PLAIN. 5475 If CIPHER contains signatures, they will be verified. 5476 5477 After the operation completed, ‘gpgme_op_decrypt_result’ and 5478 ‘gpgme_op_verify_result’ can be used to retrieve more information 5479 about the signatures. 5480 5481 If the error code ‘GPG_ERR_NO_DATA’ is returned, CIPHER does not 5482 contain any data to decrypt. However, it might still be signed. 5483 The information about detected signatures is available with 5484 ‘gpgme_op_verify_result’ in this case. 5485 5486 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the 5487 ciphertext could be decrypted successfully, ‘GPG_ERR_INV_VALUE’ if 5488 CTX, CIPHER or PLAIN is not a valid pointer, ‘GPG_ERR_NO_DATA’ if 5489 CIPHER does not contain any data to decrypt, 5490 ‘GPG_ERR_DECRYPT_FAILED’ if CIPHER is not a valid cipher text, 5491 ‘GPG_ERR_BAD_PASSPHRASE’ if the passphrase for the secret key could 5492 not be retrieved, and passes through any errors that are reported 5493 by the crypto engine support routines. 5494 5495 -- Function: gpgme_error_t gpgme_op_decrypt_verify_start 5496 (gpgme_ctx_t CTX, gpgme_data_t CIPHER, gpgme_data_t PLAIN) 5497 The function ‘gpgme_op_decrypt_verify_start’ initiates a 5498 ‘gpgme_op_decrypt_verify’ operation. It can be completed by 5499 calling ‘gpgme_wait’ on the context. *Note Waiting For 5500 Completion::. 5501 5502 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the 5503 operation could be started successfully, ‘GPG_ERR_INV_VALUE’ if 5504 CTX, CIPHER, PLAIN or R_STAT is not a valid pointer, and 5505 ‘GPG_ERR_NO_DATA’ if CIPHER does not contain any data to decrypt. 5506 5507 When processing mails it is sometimes useful to extract the actual 5508mail address (the “addr-spec”) from a string. GPGME provides this 5509helper function which uses the same semantics as the internal functions 5510in GPGME and GnuPG: 5511 5512 -- Function: char * gpgme_addrspec_from_uid (const char *UID) 5513 5514 SINCE: 1.7.1 5515 5516 Return the mail address (called “addr-spec” in RFC-5322) from the 5517 string UID which is assumed to be a user id (called “address” in 5518 RFC-5322). All plain ASCII characters (i.e. those with bit 7 5519 cleared) in the result are converted to lowercase. Caller must 5520 free the result using ‘gpgme_free’. Returns ‘NULL’ if no valid 5521 address was found (in which case ‘ERRNO’ is set to ‘EINVAL’) or for 5522 other errors. 5523 5524 5525File: gpgme.info, Node: Sign, Next: Encrypt, Prev: Decrypt and Verify, Up: Crypto Operations 5526 55277.6.4 Sign 5528---------- 5529 5530A signature can contain signatures by one or more keys. The set of keys 5531used to create a signatures is contained in a context, and is applied to 5532all following signing operations in this context (until the set is 5533changed). 5534 5535* Menu: 5536 5537* Selecting Signers:: How to choose the keys to sign with. 5538* Creating a Signature:: How to create a signature. 5539* Signature Notation Data:: How to add notation data to a signature. 5540 5541 5542File: gpgme.info, Node: Selecting Signers, Next: Creating a Signature, Up: Sign 5543 55447.6.4.1 Selecting Signers 5545......................... 5546 5547The key or the keys used to create a signature are stored in the 5548context. The following functions can be used to manipulate this list. 5549If no signer has been set into the context a default key is used for 5550signing. 5551 5552 -- Function: void gpgme_signers_clear (gpgme_ctx_t CTX) 5553 The function ‘gpgme_signers_clear’ releases a reference for each 5554 key on the signers list and removes the list of signers from the 5555 context CTX. 5556 5557 Every context starts with an empty list. 5558 5559 -- Function: gpgme_error_t gpgme_signers_add (gpgme_ctx_t CTX, 5560 const gpgme_key_t KEY) 5561 The function ‘gpgme_signers_add’ adds the key KEY to the list of 5562 signers in the context CTX. 5563 5564 Calling this function acquires an additional reference for the key. 5565 5566 -- Function: unsigned int gpgme_signers_count (const gpgme_ctx_t CTX) 5567 SINCE: 1.4.3 5568 5569 The function ‘gpgme_signers_count’ returns the number of signer 5570 keys in the context CTX. 5571 5572 -- Function: gpgme_key_t gpgme_signers_enum (const gpgme_ctx_t CTX, 5573 int SEQ) 5574 The function ‘gpgme_signers_enum’ returns the SEQth key in the list 5575 of signers in the context CTX. An additional reference is acquired 5576 for the user. 5577 5578 If SEQ is out of range, ‘NULL’ is returned. 5579 5580 5581File: gpgme.info, Node: Creating a Signature, Next: Signature Notation Data, Prev: Selecting Signers, Up: Sign 5582 55837.6.4.2 Creating a Signature 5584............................ 5585 5586 -- Data type: enum gpgme_sig_mode_t 5587 The ‘gpgme_sig_mode_t’ type is used to specify the desired type of 5588 a signature. The following modes are available: 5589 5590 ‘GPGME_SIG_MODE_NORMAL’ 5591 A normal signature is made, the output includes the plaintext 5592 and the signature. 5593 5594 ‘GPGME_SIG_MODE_DETACH’ 5595 A detached signature is made. 5596 5597 ‘GPGME_SIG_MODE_CLEAR’ 5598 A clear text signature is made. The ASCII armor and text mode 5599 settings of the context are ignored. 5600 5601 -- Function: gpgme_error_t gpgme_op_sign (gpgme_ctx_t CTX, 5602 gpgme_data_t PLAIN, gpgme_data_t SIG, gpgme_sig_mode_t MODE) 5603 The function ‘gpgme_op_sign’ creates a signature for the text in 5604 the data object PLAIN and returns it in the data object SIG. The 5605 type of the signature created is determined by the ASCII armor (or, 5606 if that is not set, by the encoding specified for SIG), the text 5607 mode attributes set for the context CTX and the requested signature 5608 mode MODE. 5609 5610 After the operation completed successfully, the result can be 5611 retrieved with ‘gpgme_op_sign_result’. 5612 5613 If an S/MIME signed message is created using the CMS crypto engine, 5614 the number of certificates to include in the message can be 5615 specified with ‘gpgme_set_include_certs’. *Note Included 5616 Certificates::. 5617 5618 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the 5619 signature could be created successfully, ‘GPG_ERR_INV_VALUE’ if 5620 CTX, PLAIN or SIG is not a valid pointer, ‘GPG_ERR_NO_DATA’ if the 5621 signature could not be created, ‘GPG_ERR_BAD_PASSPHRASE’ if the 5622 passphrase for the secret key could not be retrieved, 5623 ‘GPG_ERR_UNUSABLE_SECKEY’ if there are invalid signers, and passes 5624 through any errors that are reported by the crypto engine support 5625 routines. 5626 5627 -- Function: gpgme_error_t gpgme_op_sign_start (gpgme_ctx_t CTX, 5628 gpgme_data_t PLAIN, gpgme_data_t SIG, gpgme_sig_mode_t MODE) 5629 The function ‘gpgme_op_sign_start’ initiates a ‘gpgme_op_sign’ 5630 operation. It can be completed by calling ‘gpgme_wait’ on the 5631 context. *Note Waiting For Completion::. 5632 5633 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the 5634 operation could be started successfully, and ‘GPG_ERR_INV_VALUE’ if 5635 CTX, PLAIN or SIG is not a valid pointer. 5636 5637 -- Data type: gpgme_new_signature_t 5638 This is a pointer to a structure used to store a part of the result 5639 of a ‘gpgme_op_sign’ operation. The structure contains the 5640 following members: 5641 5642 ‘gpgme_new_signature_t next’ 5643 This is a pointer to the next new signature structure in the 5644 linked list, or ‘NULL’ if this is the last element. 5645 5646 ‘gpgme_sig_mode_t type’ 5647 The type of this signature. 5648 5649 ‘gpgme_pubkey_algo_t pubkey_algo’ 5650 The public key algorithm used to create this signature. 5651 5652 ‘gpgme_hash_algo_t hash_algo’ 5653 The hash algorithm used to create this signature. 5654 5655 ‘unsigned int sig_class’ 5656 The signature class of this signature. 5657 5658 ‘long int timestamp’ 5659 The creation timestamp of this signature. 5660 5661 ‘char *fpr’ 5662 The fingerprint of the key which was used to create this 5663 signature. 5664 5665 -- Data type: gpgme_sign_result_t 5666 This is a pointer to a structure used to store the result of a 5667 ‘gpgme_op_sign’ operation. After successfully generating a 5668 signature, you can retrieve the pointer to the result with 5669 ‘gpgme_op_sign_result’. The structure contains the following 5670 members: 5671 5672 ‘gpgme_invalid_key_t invalid_signers’ 5673 A linked list with information about all invalid keys for 5674 which a signature could not be created. 5675 5676 ‘gpgme_new_signature_t signatures’ 5677 A linked list with information about all signatures created. 5678 5679 -- Function: gpgme_sign_result_t gpgme_op_sign_result (gpgme_ctx_t CTX) 5680 The function ‘gpgme_op_sign_result’ returns a ‘gpgme_sign_result_t’ 5681 pointer to a structure holding the result of a ‘gpgme_op_sign’ 5682 operation. The pointer is only valid if the last operation on the 5683 context was a ‘gpgme_op_sign’, ‘gpgme_op_sign_start’, 5684 ‘gpgme_op_encrypt_sign’ or ‘gpgme_op_encrypt_sign_start’ operation. 5685 If that operation failed, the function might return a ‘NULL’ 5686 pointer. The returned pointer is only valid until the next 5687 operation is started on the context. 5688 5689 5690File: gpgme.info, Node: Signature Notation Data, Prev: Creating a Signature, Up: Sign 5691 56927.6.4.3 Signature Notation Data 5693............................... 5694 5695Using the following functions, you can attach arbitrary notation data to 5696a signature. This information is then available to the user when the 5697signature is verified. 5698 5699 -- Function: void gpgme_sig_notation_clear (gpgme_ctx_t CTX) 5700 SINCE: 1.1.0 5701 5702 The function ‘gpgme_sig_notation_clear’ removes the notation data 5703 from the context CTX. Subsequent signing operations from this 5704 context will not include any notation data. 5705 5706 Every context starts with an empty notation data list. 5707 5708 -- Function: gpgme_error_t gpgme_sig_notation_add (gpgme_ctx_t CTX, 5709 const char *NAME, const char *VALUE, 5710 gpgme_sig_notation_flags_t FLAGS) 5711 SINCE: 1.1.0 5712 5713 The function ‘gpgme_sig_notation_add’ adds the notation data with 5714 the name NAME and the value VALUE to the context CTX. 5715 5716 Subsequent signing operations will include this notation data, as 5717 well as any other notation data that was added since the creation 5718 of the context or the last ‘gpgme_sig_notation_clear’ operation. 5719 5720 The arguments NAME and VALUE must be ‘NUL’-terminated strings in 5721 human-readable form. The flag ‘GPGME_SIG_NOTATION_HUMAN_READABLE’ 5722 is implied (non-human-readable notation data is currently not 5723 supported). The strings must be in UTF-8 encoding. 5724 5725 If NAME is ‘NULL’, then VALUE should be a policy URL. 5726 5727 The function ‘gpgme_sig_notation_add’ returns the error code 5728 ‘GPG_ERR_NO_ERROR’ if the notation data could be added 5729 successfully, ‘GPG_ERR_INV_VALUE’ if CTX is not a valid pointer, or 5730 if NAME, VALUE and FLAGS are an invalid combination. The function 5731 also passes through any errors that are reported by the crypto 5732 engine support routines. 5733 5734 -- Function: gpgme_sig_notation_t gpgme_sig_notation_get 5735 (const gpgme_ctx_t CTX) 5736 SINCE: 1.1.0 5737 5738 The function ‘gpgme_sig_notation_get’ returns the linked list of 5739 notation data structures that are contained in the context CTX. 5740 5741 If CTX is not a valid pointer, or there is no notation data added 5742 for this context, ‘NULL’ is returned. 5743 5744 5745File: gpgme.info, Node: Encrypt, Prev: Sign, Up: Crypto Operations 5746 57477.6.5 Encrypt 5748------------- 5749 5750One plaintext can be encrypted for several recipients at the same time. 5751The list of recipients is created independently of any context, and then 5752passed to the encryption operation. 5753 5754* Menu: 5755 5756* Encrypting a Plaintext:: How to encrypt a plaintext. 5757 5758 5759File: gpgme.info, Node: Encrypting a Plaintext, Up: Encrypt 5760 57617.6.5.1 Encrypting a Plaintext 5762.............................. 5763 5764 -- Function: gpgme_error_t gpgme_op_encrypt (gpgme_ctx_t CTX, 5765 gpgme_key_t RECP[], gpgme_encrypt_flags_t FLAGS, 5766 gpgme_data_t PLAIN, gpgme_data_t CIPHER) 5767 The function ‘gpgme_op_encrypt’ encrypts the plaintext in the data 5768 object PLAIN for the recipients RECP and stores the ciphertext in 5769 the data object CIPHER. The type of the ciphertext created is 5770 determined by the ASCII armor (or, if that is not set, by the 5771 encoding specified for CIPHER) and the text mode attributes set for 5772 the context CTX. 5773 5774 RECP must be a ‘NULL’-terminated array of keys. The user must keep 5775 references for all keys during the whole duration of the call (but 5776 see ‘gpgme_op_encrypt_start’ for the requirements with the 5777 asynchronous variant). 5778 5779 The value in FLAGS is a bitwise-or combination of one or multiple 5780 of the following bit values: 5781 5782 ‘GPGME_ENCRYPT_ALWAYS_TRUST’ 5783 The ‘GPGME_ENCRYPT_ALWAYS_TRUST’ symbol specifies that all the 5784 recipients in RECP should be trusted, even if the keys do not 5785 have a high enough validity in the keyring. This flag should 5786 be used with care; in general it is not a good idea to use any 5787 untrusted keys. 5788 5789 ‘GPGME_ENCRYPT_NO_ENCRYPT_TO’ 5790 SINCE: 1.2.0 5791 5792 The ‘GPGME_ENCRYPT_NO_ENCRYPT_TO’ symbol specifies that no 5793 default or hidden default recipients as configured in the 5794 crypto backend should be included. This can be useful for 5795 managing different user profiles. 5796 5797 ‘GPGME_ENCRYPT_NO_COMPRESS’ 5798 SINCE: 1.5.0 5799 5800 The ‘GPGME_ENCRYPT_NO_COMPRESS’ symbol specifies that the 5801 plaintext shall not be compressed before it is encrypted. 5802 This is in some cases useful if the length of the encrypted 5803 message may reveal information about the plaintext. 5804 5805 ‘GPGME_ENCRYPT_PREPARE’ 5806 ‘GPGME_ENCRYPT_EXPECT_SIGN’ 5807 The ‘GPGME_ENCRYPT_PREPARE’ symbol is used with the UI Server 5808 protocol to prepare an encryption (i.e. sending the 5809 ‘PREP_ENCRYPT’ command). With the ‘GPGME_ENCRYPT_EXPECT_SIGN’ 5810 symbol the UI Server is advised to also expect a sign command. 5811 5812 ‘GPGME_ENCRYPT_SYMMETRIC’ 5813 SINCE: 1.7.0 5814 5815 The ‘GPGME_ENCRYPT_SYMMETRIC’ symbol specifies that the output 5816 should be additionally encrypted symmetrically even if 5817 recipients are provided. This feature is only supported for 5818 the OpenPGP crypto engine. 5819 5820 ‘GPGME_ENCRYPT_THROW_KEYIDS’ 5821 SINCE: 1.8.0 5822 5823 The ‘GPGME_ENCRYPT_THROW_KEYIDS’ symbols requests that the 5824 identifiers for the decrption keys are not included in the 5825 ciphertext. On the receiving side, the use of this flag may 5826 slow down the decryption process because all available secret 5827 keys must be tried. This flag is only honored for OpenPGP 5828 encryption. 5829 5830 ‘GPGME_ENCRYPT_WRAP’ 5831 SINCE: 1.8.0 5832 5833 The ‘GPGME_ENCRYPT_WRAP’ symbol specifies that the input is an 5834 OpenPGP message and not a plain data. This is the counterpart 5835 to ‘GPGME_DECRYPT_UNWRAP’. 5836 5837 ‘GPGME_ENCRYPT_WANT_ADDRESS’ 5838 SINCE: 1.11.0 5839 5840 The ‘GPGME_ENCRYPT_WANT_ADDRESS’ symbol requests that all 5841 supplied keys or key specifications include a syntactically 5842 valid mail address. If this is not the case the operation is 5843 not even tried and the error code ‘GPG_ERR_INV_USER_ID’ is 5844 returned. Only the address part of the key specification is 5845 conveyed to the backend. As of now the key must be specified 5846 using the RECPSTRING argument of the extended encrypt 5847 functions. This feature is currently only supported for the 5848 OpenPGP crypto engine. 5849 5850 If ‘GPG_ERR_UNUSABLE_PUBKEY’ is returned, some recipients in RECP 5851 are invalid, but not all. In this case the plaintext might be 5852 encrypted for all valid recipients and returned in CIPHER (if this 5853 happens depends on the crypto engine). More information about the 5854 invalid recipients is available with ‘gpgme_op_encrypt_result’. 5855 5856 If RECP is ‘NULL’, symmetric rather than public key encryption is 5857 performed. Symmetrically encrypted cipher text can be deciphered 5858 with ‘gpgme_op_decrypt’. Note that in this case the crypto backend 5859 needs to retrieve a passphrase from the user. Symmetric encryption 5860 is currently only supported for the OpenPGP crypto backend. 5861 5862 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the 5863 ciphertext could be created successfully, ‘GPG_ERR_INV_VALUE’ if 5864 CTX, RECP, PLAIN or CIPHER is not a valid pointer, 5865 ‘GPG_ERR_UNUSABLE_PUBKEY’ if RECP contains some invalid recipients, 5866 ‘GPG_ERR_BAD_PASSPHRASE’ if the passphrase for the symmetric key 5867 could not be retrieved, and passes through any errors that are 5868 reported by the crypto engine support routines. 5869 5870 -- Function: gpgme_error_t gpgme_op_encrypt_start (gpgme_ctx_t CTX, 5871 gpgme_key_t RECP[], gpgme_encrypt_flags_t FLAGS, 5872 gpgme_data_t PLAIN, gpgme_data_t CIPHER) 5873 The function ‘gpgme_op_encrypt_start’ initiates a 5874 ‘gpgme_op_encrypt’ operation. It can be completed by calling 5875 ‘gpgme_wait’ on the context. *Note Waiting For Completion::. 5876 5877 References to the keys only need to be held for the duration of 5878 this call. The user can release its references to the keys after 5879 this function returns, even if the operation is not yet finished. 5880 5881 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the 5882 operation could be started successfully, ‘GPG_ERR_INV_VALUE’ if 5883 CTX, RSET, PLAIN or CIPHER is not a valid pointer, and 5884 ‘GPG_ERR_UNUSABLE_PUBKEY’ if RSET does not contain any valid 5885 recipients. 5886 5887 -- Function: gpgme_error_t gpgme_op_encrypt_ext (gpgme_ctx_t CTX, 5888 gpgme_key_t RECP[], const char *RECPSTRING, 5889 gpgme_encrypt_flags_t FLAGS, gpgme_data_t PLAIN, 5890 gpgme_data_t CIPHER) 5891 5892 SINCE: 1.11.0 5893 5894 This is an extended version of ‘gpgme_op_encrypt’ with RECPSTRING 5895 as additional parameter. If RECP is NULL and RECPSTRING is not 5896 NULL, the latter is expected to be a linefeed delimited string with 5897 the set of key specifications. In contrast to RECP the keys are 5898 given directly as strings and there is no need to first create key 5899 objects. Leading and trailing white space is remove from each line 5900 in RECPSTRING. The keys are then passed verbatim to the backend 5901 engine. 5902 5903 For the OpenPGP backend several special keywords are supported to 5904 modify the operation. These keywords are given instead of a key 5905 specification. The currently supported keywords are: 5906 5907 ‘--hidden’ 5908 ‘--no-hidden’ 5909 These keywords toggle between normal and hidden recipients for 5910 all following key specifications. When a hidden recipient is 5911 requested the gpg option ‘-R’ (or ‘-F’ in file mode) is used 5912 instead of ‘-r’ (‘-f’ in file mode). 5913 5914 ‘--file’ 5915 ‘--no-file’ 5916 These keywords toggle between regular and file mode for all 5917 following key specification. In file mode the option ‘-f’ or 5918 ‘-F’ is passed to gpg. At least GnuPG version 2.1.14 is 5919 required to handle these options. The 5920 ‘GPGME_ENCRYPT_WANT_ADDRESS’ flag is ignored in file mode. 5921 5922 ‘--’ 5923 This keyword disables all keyword detection up to the end of 5924 the string. All keywords are treated as verbatim arguments. 5925 5926 To create a RECPSTRING it is often useful to employ a strconcat 5927 style function. For example this function creates a string to 5928 encrypt to two keys: 5929 5930 char * 5931 xbuild_recpstring (const char *key1, const char *key2) 5932 { 5933 char *result = gpgrt_strconcat ("--\n", key1, "\n", key2, NULL); 5934 if (!result) 5935 { perror ("strconcat failed"); exit (2); } 5936 return result; 5937 } 5938 5939 Note the use of the double dash here; unless you want to specify a 5940 keyword, it is a good idea to avoid any possible trouble with key 5941 specifications starting with a double dash. The used strconcat 5942 function is available in Libgpg-error 1.28 and later; Libgpg-error 5943 (aka Gpgrt) is a dependency of GPGME. The number of arguments to 5944 ‘gpgrt_strconcat’ is limited to 47 but that should always be 5945 sufficient. In case a larger and non-fixed number of keys are to 5946 be supplied the following code can be used: 5947 5948 char * 5949 xbuild_long_recpstring (void) 5950 { 5951 gpgrt_stream_t memfp; 5952 const char *s; 5953 void *result; 5954 5955 memfp = gpgrt_fopenmem (0, "w+b"); 5956 if (!memfp) 5957 { perror ("fopenmem failed"); exit (2); } 5958 gpgrt_fputs ("--", memfp); 5959 while ((s = get_next_keyspec ())) 5960 { 5961 gpgrt_fputc ('\n', memfp); 5962 gpgrt_fputs (s, memfp); 5963 } 5964 gpgrt_fputc (0, memfp); 5965 if (gpgrt_ferror (memfp)) 5966 { perror ("writing to memstream failed"); exit (2); } 5967 if (gpgrt_fclose_snatch (memfp, &result, NULL)) 5968 { perror ("fclose_snatch failed"); exit (2); } 5969 return result; 5970 } 5971 5972 In this example ‘get_next_keyspec’ is expected to return the next 5973 key to be added to the string. Please take care: Encrypting to a 5974 large number of recipients is often questionable due to security 5975 reasons and also for the technicality that all keys are currently 5976 passed on the command line to ‘gpg’ which has as a platform 5977 specific length limitation. 5978 5979 -- Function: gpgme_error_t gpgme_op_encrypt_ext_start (gpgme_ctx_t CTX, 5980 gpgme_key_t RECP[], const char *RECPSTRING, 5981 gpgme_encrypt_flags_t FLAGS, gpgme_data_t PLAIN, 5982 gpgme_data_t CIPHER) 5983 5984 SINCE: 1.11.0 5985 5986 This is an extended version of ‘gpgme_op_encrypt_start’ with 5987 RECPSTRING as additional parameter. If RECP is NULL and RECPSTRING 5988 is not NULL, the latter is expected to be a linefeed delimited 5989 string with the set of key specifications. In contrast to RECP the 5990 keys are given directly as strings and there is no need to first 5991 create key objects. The keys are passed verbatim to the backend 5992 engine. 5993 5994 -- Data type: gpgme_encrypt_result_t 5995 This is a pointer to a structure used to store the result of a 5996 ‘gpgme_op_encrypt’ operation. After successfully encrypting data, 5997 you can retrieve the pointer to the result with 5998 ‘gpgme_op_encrypt_result’. The structure contains the following 5999 members: 6000 6001 ‘gpgme_invalid_key_t invalid_recipients’ 6002 A linked list with information about all invalid keys for 6003 which the data could not be encrypted. 6004 6005 -- Function: gpgme_encrypt_result_t gpgme_op_encrypt_result 6006 (gpgme_ctx_t CTX) 6007 The function ‘gpgme_op_encrypt_result’ returns a 6008 ‘gpgme_encrypt_result_t’ pointer to a structure holding the result 6009 of a ‘gpgme_op_encrypt’ operation. The pointer is only valid if 6010 the last operation on the context was a ‘gpgme_op_encrypt’, 6011 ‘gpgme_op_encrypt_start’, ‘gpgme_op_sign’ or ‘gpgme_op_sign_start’ 6012 operation. If this operation failed, this might be a ‘NULL’ 6013 pointer. The returned pointer is only valid until the next 6014 operation is started on the context. 6015 6016 -- Function: gpgme_error_t gpgme_op_encrypt_sign (gpgme_ctx_t CTX, 6017 gpgme_key_t RECP[], gpgme_encrypt_flags_t FLAGS, 6018 gpgme_data_t PLAIN, gpgme_data_t CIPHER) 6019 The function ‘gpgme_op_encrypt_sign’ does a combined encrypt and 6020 sign operation. It is used like ‘gpgme_op_encrypt’, but the 6021 ciphertext also contains signatures for the signers listed in CTX. 6022 6023 The combined encrypt and sign operation is currently only available 6024 for the OpenPGP crypto engine. 6025 6026 -- Function: gpgme_error_t gpgme_op_encrypt_sign_start 6027 (gpgme_ctx_t CTX, gpgme_key_t RECP[], 6028 gpgme_encrypt_flags_t FLAGS, gpgme_data_t PLAIN, 6029 gpgme_data_t CIPHER) 6030 The function ‘gpgme_op_encrypt_sign_start’ initiates a 6031 ‘gpgme_op_encrypt_sign’ operation. It can be completed by calling 6032 ‘gpgme_wait’ on the context. *Note Waiting For Completion::. 6033 6034 The function returns the error code ‘GPG_ERR_NO_ERROR’ if the 6035 operation could be started successfully, and ‘GPG_ERR_INV_VALUE’ if 6036 CTX, RSET, PLAIN or CIPHER is not a valid pointer. 6037 6038 -- Function: gpgme_error_t gpgme_op_encrypt_sign_ext (gpgme_ctx_t CTX, 6039 gpgme_key_t RECP[], const char *RECPSTRING, 6040 gpgme_encrypt_flags_t FLAGS, gpgme_data_t PLAIN, 6041 gpgme_data_t CIPHER) 6042 6043 SINCE: 1.11.0 6044 6045 This is an extended version of ‘gpgme_op_encrypt_sign’ with 6046 RECPSTRING as additional parameter. If RECP is NULL and RECPSTRING 6047 is not NULL, the latter is expected to be a linefeed delimited 6048 string with the set of key specifications. In contrast to RECP the 6049 keys are given directly as strings and there is no need to first 6050 create the key objects. The keys are passed verbatim to the 6051 backend engine. 6052 6053 -- Function: gpgme_error_t gpgme_op_encrypt_sign_ext_start 6054 (gpgme_ctx_t CTX, gpgme_key_t RECP[], const char *RECPSTRING, 6055 gpgme_encrypt_flags_t FLAGS, gpgme_data_t PLAIN, 6056 gpgme_data_t CIPHER) 6057 6058 SINCE: 1.11.0 6059 6060 This is an extended version of ‘gpgme_op_encrypt_sign_start’ with 6061 RECPSTRING as additional parameter. If RECP is NULL and RECPSTRING 6062 is not NULL, the latter is expected to be a linefeed delimited 6063 string with the set of key specifications. In contrast to RECP the 6064 keys are given directly as strings and there is no need to first 6065 create the key objects. The keys are passed verbatim to the 6066 backend engine. 6067 6068 6069File: gpgme.info, Node: Miscellaneous, Next: Run Control, Prev: Crypto Operations, Up: Contexts 6070 60717.7 Miscellaneous operations 6072============================ 6073 6074Here are some support functions which are sometimes useful. 6075 6076* Menu: 6077 6078* Running other Programs:: Running other Programs 6079* Using the Assuan protocol:: Using the Assuan protocol 6080* Checking for updates:: How to check for software updates 6081 6082 6083File: gpgme.info, Node: Running other Programs, Next: Using the Assuan protocol, Up: Miscellaneous 6084 60857.7.1 Running other Programs 6086---------------------------- 6087 6088GPGME features an internal subsystem to run the actual backend engines. 6089Along with data abstraction object this subsystem can be used to run 6090arbitrary simple programs which even need not be related to 6091cryptographic features. It may for example be used to run tools which 6092are part of the GnuPG system but are not directly accessible with the 6093GPGME API. 6094 6095 -- Function: gpgme_error_t gpgme_op_spawn (gpgme_ctx_t CTX, 6096 const char *FILE, const char *ARGV[], gpgme_data_t DATAIN, 6097 gpgme_data_t DATAOUT, gpgme_data_t DATAERR, 6098 unsigned int FLAGS) 6099 6100 SINCE: 1.5.0 6101 6102 The function ‘gpgme_op_spawn’ runs the program FILE with the 6103 arguments taken from the NULL terminated array ARGV. If no 6104 arguments are required ARGV may be given as ‘NULL’. In the latter 6105 case or if ‘argv[0]’ is the empty string, GPGME uses the basename 6106 of FILE for ‘argv[0]’. The file descriptors ‘stdin’, ‘stdout’, and 6107 ‘stderr’ are connected to the data objects DATAIN, DATAOUT, and 6108 DATAERR. If NULL is passed for one of these data objects the 6109 corresponding file descriptor is connected to ‘/dev/null’. 6110 6111 The value in FLAGS is a bitwise-or combination of one or multiple 6112 of the following bit values: 6113 6114 ‘GPGME_SPAWN_DETACHED’ 6115 SINCE: 1.5.0 6116 6117 Under Windows this flag inhibits the allocation of a new 6118 console for the program. This is useful for a GUI application 6119 which needs to call a command line helper tool. 6120 6121 ‘GPGME_SPAWN_ALLOW_SET_FG’ 6122 SINCE: 1.5.0 6123 6124 Under Windows this flag allows the called program to put 6125 itself into the foreground. 6126 6127 -- Function: gpgme_error_t gpgme_op_spawn_start (gpgme_ctx_t CTX, 6128 const char *FILE, const char *ARGV[], gpgme_data_t DATAIN, 6129 gpgme_data_t DATAOUT, gpgme_data_t DATAERR, 6130 unsigned int FLAGS) 6131 6132 SINCE: 1.5.0 6133 6134 This is the asynchronous variant of ‘gpgme_op_spawn’. 6135 6136 6137File: gpgme.info, Node: Using the Assuan protocol, Next: Checking for updates, Prev: Running other Programs, Up: Miscellaneous 6138 61397.7.2 Using the Assuan protocol 6140------------------------------- 6141 6142The Assuan protocol can be used to talk to arbitrary Assuan servers. By 6143default it is connected to the GnuPG agent, but it may be connected to 6144arbitrary servers by using ‘gpgme_ctx_set_engine_info’, passing the 6145location of the servers socket as FILE_NAME argument, and an empty 6146string as HOME_DIR argument. 6147 6148 The Assuan protocol functions use three kinds of callbacks to 6149transfer data: 6150 6151 -- Data type: gpgme_error_t (*gpgme_assuan_data_cb_t) (void *OPAQUE, 6152 const void *DATA, size_t DATALEN) 6153 6154 SINCE: 1.2.0 6155 6156 This callback receives any data sent by the server. OPAQUE is the 6157 pointer passed to ‘gpgme_op_assuan_transact_start’, DATA of length 6158 DATALEN refers to the data sent. 6159 6160 -- Data type: gpgme_error_t (*gpgme_assuan_inquire_cb_t) (void *OPAQUE, 6161 const char *NAME, const char *ARGS, gpgme_data_t *R_DATA) 6162 6163 SINCE: 1.2.0 6164 6165 This callback is used to provide additional data to the Assuan 6166 server. OPAQUE is the pointer passed to 6167 ‘gpgme_op_assuan_transact_start’, NAME and ARGS specify what kind 6168 of data the server requested, and R_DATA is used to return the 6169 actual data. 6170 6171 Note: Returning data is currently not implemented in GPGME. 6172 6173 -- Data type: gpgme_error_t (*gpgme_assuan_status_cb_t) (void *OPAQUE, 6174 const char *STATUS, const char *ARGS) 6175 6176 SINCE: 1.2.0 6177 6178 This callback receives any status lines sent by the server. OPAQUE 6179 is the pointer passed to ‘gpgme_op_assuan_transact_start’, STATUS 6180 and ARGS denote the status update sent. 6181 6182 -- Function: gpgme_error_t gpgme_op_assuan_transact_start 6183 (gpgme_ctx_t CTX, const char *COMMAND, 6184 gpgme_assuan_data_cb_t DATA_CB, void * DATA_CB_VALUE, 6185 gpgme_assuan_inquire_cb_t INQUIRE_CB, void * INQUIRE_CB_VALUE, 6186 gpgme_assuan_status_cb_t STATUS_CB, void * STATUS_CB_VALUE) 6187 6188 SINCE: 1.2.0 6189 6190 Send the Assuan COMMAND and return results via the callbacks. Any 6191 callback may be ‘NULL’. The result of the operation may be 6192 retrieved using ‘gpgme_wait_ext’. 6193 6194 Asynchronous variant. 6195 6196 -- Function: gpgme_error_t gpgme_op_assuan_transact_ext 6197 (gpgme_ctx_t CTX, const char *COMMAND, 6198 gpgme_assuan_data_cb_t DATA_CB, void * DATA_CB_VALUE, 6199 gpgme_assuan_inquire_cb_t INQUIRE_CB, void * INQUIRE_CB_VALUE, 6200 gpgme_assuan_status_cb_t STATUS_CB, void * STATUS_CB_VALUE, 6201 gpgme_error_t *OP_ERR) 6202 6203 Send the Assuan COMMAND and return results via the callbacks. The 6204 result of the operation is returned in OP_ERR. 6205 6206 Synchronous variant. 6207 6208 6209File: gpgme.info, Node: Checking for updates, Prev: Using the Assuan protocol, Up: Miscellaneous 6210 62117.7.3 How to check for software updates 6212--------------------------------------- 6213 6214The GnuPG Project operates a server to query the current versions of 6215software packages related to GnuPG. GPGME can be used to access this 6216online database and check whether a new version of a software package is 6217available. 6218 6219 -- Data type: gpgme_query_swdb_result_t 6220 SINCE: 1.8.0 6221 6222 This is a pointer to a structure used to store the result of a 6223 ‘gpgme_op_query_swdb’ operation. After success full call to that 6224 function, you can retrieve the pointer to the result with 6225 ‘gpgme_op_query_swdb_result’. The structure contains the following 6226 member: 6227 6228 ‘name’ 6229 This is the name of the package. 6230 6231 ‘iversion’ 6232 The currently installed version or an empty string. This 6233 value is either a copy of the argument given to 6234 ‘gpgme_op_query_swdb’ or the version of the installed software 6235 as figured out by GPGME or GnuPG. 6236 6237 ‘created’ 6238 This gives the date the file with the list of version numbers 6239 has originally be created by the GnuPG project. 6240 6241 ‘retrieved’ 6242 This gives the date the file was downloaded. 6243 6244 ‘warning’ 6245 If this flag is set either an error has occurred or some of 6246 the information in this structure are not properly set. For 6247 example if the version number of the installed software could 6248 not be figured out, the ‘update’ flag may not reflect a 6249 required update status. 6250 6251 ‘update’ 6252 If this flag is set an update of the software is available. 6253 6254 ‘urgent’ 6255 If this flag is set an available update is important. 6256 6257 ‘noinfo’ 6258 If this flag is set, no valid information could be retrieved. 6259 6260 ‘unknown’ 6261 If this flag is set the given ‘name’ is not known. 6262 6263 ‘tooold’ 6264 If this flag is set the available information is not fresh 6265 enough. 6266 6267 ‘error’ 6268 If this flag is set some other error has occurred. 6269 6270 ‘version’ 6271 The version string of the latest released version. 6272 6273 ‘reldate’ 6274 The release date of the latest released version. 6275 6276 -- Function: gpgme_error_t gpgme_op_query_swdb (gpgme_ctx_t CTX, 6277 const char *NAME, const char *IVERSION, gpgme_data_t RESERVED) 6278 6279 SINCE: 1.8.0 6280 6281 Query the software version database for software package NAME and 6282 check against the installed version given by IVERSION. If IVERSION 6283 is given as ‘NULL’ a check is only done if GPGME can figure out the 6284 version by itself (for example when using "gpgme" or "gnupg"). If 6285 ‘NULL’ is used for NAME the current gpgme version is checked. 6286 RESERVED must be set to 0. 6287 6288 -- Function: gpgme_query_swdb_result_t gpgme_op_query_swdb_result 6289 (gpgme_ctx_t CTX) 6290 6291 SINCE: 1.8.0 6292 6293 The function ‘gpgme_op_query_swdb_result’ returns a 6294 ‘gpgme_query_swdb_result_t’ pointer to a structure holding the 6295 result of a ‘gpgme_op_query_swdb’ operation. The pointer is only 6296 valid if the last operation on the context was a successful call to 6297 ‘gpgme_op_query_swdb’. If that call failed, the result might be a 6298 ‘NULL’ pointer. The returned pointer is only valid until the next 6299 operation is started on the context CTX. 6300 6301Here is an example on how to check whether GnuPG is current: 6302 6303 #include <gpgme.h> 6304 6305 int 6306 main (void) 6307 { 6308 gpg_error_t err; 6309 gpgme_ctx_t ctx; 6310 gpgme_query_swdb_result_t result; 6311 6312 gpgme_check_version (NULL); 6313 err = gpgme_new (&ctx); 6314 if (err) 6315 fprintf (stderr, "error creating context: %s\n", gpg_strerror (err)); 6316 else 6317 { 6318 gpgme_set_protocol (ctx, GPGME_PROTOCOL_GPGCONF); 6319 6320 err = gpgme_op_query_swdb (ctx, "gnupg", NULL, 0); 6321 if (err) 6322 fprintf (stderr, "error querying swdb: %s\n", gpg_strerror (err)); 6323 else 6324 { 6325 result = gpgme_op_query_swdb_result (ctx); 6326 if (!result) 6327 fprintf (stderr, "error querying swdb\n"); 6328 if (!result->warning && !result->update) 6329 printf ("GnuPG version %s is current\n", 6330 result->iversion); 6331 else if (!result->warning && result->update) 6332 printf ("GnuPG version %s can be updated to %s\n", 6333 result->iversion, result->version); 6334 else 6335 fprintf (stderr, "error finding the update status\n"); 6336 } 6337 gpgme_release (ctx); 6338 } 6339 return 0; 6340 } 6341 6342 6343File: gpgme.info, Node: Run Control, Prev: Miscellaneous, Up: Contexts 6344 63457.8 Run Control 6346=============== 6347 6348GPGME supports running operations synchronously and asynchronously. You 6349can use asynchronous operation to set up a context up to initiating the 6350desired operation, but delay performing it to a later point. 6351 6352 Furthermore, you can use an external event loop to control exactly 6353when GPGME runs. This ensures that GPGME only runs when necessary and 6354also prevents it from blocking for a long time. 6355 6356* Menu: 6357 6358* Waiting For Completion:: Waiting until an operation is completed. 6359* Using External Event Loops:: Advanced control over what happens when. 6360* Cancellation:: How to end pending operations prematurely. 6361 6362 6363File: gpgme.info, Node: Waiting For Completion, Next: Using External Event Loops, Up: Run Control 6364 63657.8.1 Waiting For Completion 6366---------------------------- 6367 6368 -- Function: gpgme_ctx_t gpgme_wait (gpgme_ctx_t CTX, 6369 gpgme_error_t *STATUS, int HANG) 6370 The function ‘gpgme_wait’ continues the pending operation within 6371 the context CTX. In particular, it ensures the data exchange 6372 between GPGME and the crypto backend and watches over the run time 6373 status of the backend process. 6374 6375 If HANG is true, the function does not return until the operation 6376 is completed or cancelled. Otherwise the function will not block 6377 for a long time. 6378 6379 The error status of the finished operation is returned in STATUS if 6380 ‘gpgme_wait’ does not return ‘NULL’. 6381 6382 The CTX argument can be ‘NULL’. In that case, ‘gpgme_wait’ waits 6383 for any context to complete its operation. 6384 6385 ‘gpgme_wait’ can be used only in conjunction with any context that 6386 has a pending operation initiated with one of the 6387 ‘gpgme_op_*_start’ functions except ‘gpgme_op_keylist_start’ and 6388 ‘gpgme_op_trustlist_start’ (for which you should use the 6389 corresponding ‘gpgme_op_*_next’ functions). If CTX is ‘NULL’, all 6390 of such contexts are waited upon and possibly returned. 6391 Synchronous operations running in parallel, as well as key and 6392 trust item list operations, do not affect ‘gpgme_wait’. 6393 6394 In a multi-threaded environment, only one thread should ever call 6395 ‘gpgme_wait’ at any time, regardless of whether CTX is specified or 6396 not. This means that all calls to this function should be fully 6397 synchronized by locking primitives. It is safe to start 6398 asynchronous operations while a thread is running in ‘gpgme_wait’. 6399 6400 The function returns the CTX of the context which has finished the 6401 operation. If HANG is false, and the timeout expires, ‘NULL’ is 6402 returned and ‘*status’ will be set to 0. If an error occurs, 6403 ‘NULL’ is returned and the error is returned in ‘*status’. 6404 6405 6406File: gpgme.info, Node: Using External Event Loops, Next: Cancellation, Prev: Waiting For Completion, Up: Run Control 6407 64087.8.2 Using External Event Loops 6409-------------------------------- 6410 6411GPGME hides the complexity of the communication between the library and 6412the crypto engine. The price of this convenience is that the calling 6413thread can block arbitrary long waiting for the data returned by the 6414crypto engine. In single-threaded programs, in particular if they are 6415interactive, this is an unwanted side-effect. OTOH, if ‘gpgme_wait’ is 6416used without the HANG option being enabled, it might be called 6417unnecessarily often, wasting CPU time that could be used otherwise. 6418 6419 The I/O callback interface described in this section lets the user 6420take control over what happens when. GPGME will provide the user with 6421the file descriptors that should be monitored, and the callback 6422functions that should be invoked when a file descriptor is ready for 6423reading or writing. It is then the user’s responsibility to decide when 6424to check the file descriptors and when to invoke the callback functions. 6425Usually this is done in an event loop, that also checks for events in 6426other parts of the program. If the callback functions are only called 6427when the file descriptors are ready, GPGME will never block. This gives 6428the user more control over the program flow, and allows to perform other 6429tasks when GPGME would block otherwise. 6430 6431 By using this advanced mechanism, GPGME can be integrated smoothly 6432into GUI toolkits like GTK+ even for single-threaded programs. 6433 6434* Menu: 6435 6436* I/O Callback Interface:: How I/O callbacks are registered. 6437* Registering I/O Callbacks:: How to use I/O callbacks for a context. 6438* I/O Callback Example:: An example how to use I/O callbacks. 6439* I/O Callback Example GTK+:: How to use GPGME with GTK+. 6440* I/O Callback Example GDK:: How to use GPGME with GDK. 6441* I/O Callback Example Qt:: How to use GPGME with Qt. 6442 6443 6444File: gpgme.info, Node: I/O Callback Interface, Next: Registering I/O Callbacks, Up: Using External Event Loops 6445 64467.8.2.1 I/O Callback Interface 6447.............................. 6448 6449 -- Data type: gpgme_error_t (*gpgme_io_cb_t) (void *DATA, int FD) 6450 The ‘gpgme_io_cb_t’ type is the type of functions which GPGME wants 6451 to register as I/O callback handlers using the 6452 ‘gpgme_register_io_cb_t’ functions provided by the user. 6453 6454 DATA and FD are provided by GPGME when the I/O callback handler is 6455 registered, and should be passed through to the handler when it is 6456 invoked by the user because it noticed activity on the file 6457 descriptor FD. 6458 6459 The callback handler always returns ‘0’, but you should consider 6460 the return value to be reserved for later use. 6461 6462 -- Data type: gpgme_error_t (*gpgme_register_io_cb_t) (void *DATA, 6463 int FD, int DIR, gpgme_io_cb_t FNC, void *FNC_DATA, 6464 void **TAG) 6465 The ‘gpgme_register_io_cb_t’ type is the type of functions which 6466 can be called by GPGME to register an I/O callback function FNC for 6467 the file descriptor FD with the user. FNC_DATA should be passed as 6468 the first argument to FNC when the handler is invoked (the second 6469 argument should be FD). If DIR is 0, FNC should be called by the 6470 user when FD is ready for writing. If DIR is 1, FNC should be 6471 called when FD is ready for reading. 6472 6473 DATA was provided by the user when registering the 6474 ‘gpgme_register_io_cb_t’ function with GPGME and will always be 6475 passed as the first argument when registering a callback function. 6476 For example, the user can use this to determine the event loop to 6477 which the file descriptor should be added. 6478 6479 GPGME will call this function when a crypto operation is initiated 6480 in a context for which the user has registered I/O callback handler 6481 functions with ‘gpgme_set_io_cbs’. It can also call this function 6482 when it is in an I/O callback handler for a file descriptor 6483 associated to this context. 6484 6485 The user should return a unique handle in TAG identifying this I/O 6486 callback registration, which will be passed to the 6487 ‘gpgme_register_io_cb_t’ function without interpretation when the 6488 file descriptor should not be monitored anymore. 6489 6490 -- Data type: void (*gpgme_remove_io_cb_t) (void *TAG) 6491 The ‘gpgme_remove_io_cb_t’ type is the type of functions which can 6492 be called by GPGME to remove an I/O callback handler that was 6493 registered before. TAG is the handle that was returned by the 6494 ‘gpgme_register_io_cb_t’ for this I/O callback. 6495 6496 GPGME can call this function when a crypto operation is in an I/O 6497 callback. It will also call this function when the context is 6498 destroyed while an operation is pending. 6499 6500 -- Data type: enum gpgme_event_io_t 6501 The ‘gpgme_event_io_t’ type specifies the type of an event that is 6502 reported to the user by GPGME as a consequence of an I/O operation. 6503 The following events are defined: 6504 6505 ‘GPGME_EVENT_START’ 6506 The operation is fully initialized now, and you can start to 6507 run the registered I/O callback handlers now. Note that 6508 registered I/O callback handlers must not be run before this 6509 event is signalled. TYPE_DATA is ‘NULL’ and reserved for 6510 later use. 6511 6512 ‘GPGME_EVENT_DONE’ 6513 The operation is finished, the last I/O callback for this 6514 operation was removed. The accompanying TYPE_DATA points to a 6515 ‘struct gpgme_io_event_done_data’ variable that contains the 6516 status of the operation that finished. This event is 6517 signalled after the last I/O callback has been removed. 6518 6519 ‘GPGME_EVENT_NEXT_KEY’ 6520 In a ‘gpgme_op_keylist_start’ operation, the next key was 6521 received from the crypto engine. The accompanying TYPE_DATA 6522 is a ‘gpgme_key_t’ variable that contains the key with one 6523 reference for the user. 6524 6525 -- Data type: void (*gpgme_event_io_cb_t) (void *DATA, 6526 gpgme_event_io_t TYPE, void *TYPE_DATA) 6527 The ‘gpgme_event_io_cb_t’ type is the type of functions which can 6528 be called by GPGME to signal an event for an operation running in a 6529 context which has I/O callback functions registered by the user. 6530 6531 DATA was provided by the user when registering the 6532 ‘gpgme_event_io_cb_t’ function with GPGME and will always be passed 6533 as the first argument when registering a callback function. For 6534 example, the user can use this to determine the context in which 6535 this event has occurred. 6536 6537 TYPE will specify the type of event that has occurred. TYPE_DATA 6538 specifies the event further, as described in the above list of 6539 possible ‘gpgme_event_io_t’ types. 6540 6541 GPGME can call this function in an I/O callback handler. 6542 6543 6544File: gpgme.info, Node: Registering I/O Callbacks, Next: I/O Callback Example, Prev: I/O Callback Interface, Up: Using External Event Loops 6545 65467.8.2.2 Registering I/O Callbacks 6547................................. 6548 6549 -- Data type: struct gpgme_io_cbs 6550 This structure is used to store the I/O callback interface 6551 functions described in the previous section. It has the following 6552 members: 6553 6554 ‘gpgme_register_io_cb_t add’ 6555 This is the function called by GPGME to register an I/O 6556 callback handler. It must be specified. 6557 6558 ‘void *add_priv’ 6559 This is passed as the first argument to the ‘add’ function 6560 when it is called by GPGME. For example, it can be used to 6561 determine the event loop to which the file descriptor should 6562 be added. 6563 6564 ‘gpgme_remove_io_cb_t remove’ 6565 This is the function called by GPGME to remove an I/O callback 6566 handler. It must be specified. 6567 6568 ‘gpgme_event_io_cb_t event’ 6569 This is the function called by GPGME to signal an event for an 6570 operation. It must be specified, because at least the start 6571 event must be processed. 6572 6573 ‘void *event_priv’ 6574 This is passed as the first argument to the ‘event’ function 6575 when it is called by GPGME. For example, it can be used to 6576 determine the context in which the event has occurred. 6577 6578 -- Function: void gpgme_set_io_cbs (gpgme_ctx_t CTX, 6579 struct gpgme_io_cbs *IO_CBS) 6580 The function ‘gpgme_set_io_cbs’ enables the I/O callback interface 6581 for the context CTX. The I/O callback functions are specified by 6582 IO_CBS. 6583 6584 If IO_CBS->‘add’ is ‘NULL’, the I/O callback interface is disabled 6585 for the context, and normal operation is restored. 6586 6587 -- Function: void gpgme_get_io_cbs (gpgme_ctx_t CTX, 6588 struct gpgme_io_cbs *IO_CBS) 6589 The function ‘gpgme_get_io_cbs’ returns the I/O callback functions 6590 set with ‘gpgme_set_io_cbs’ in IO_CBS. 6591 6592 6593File: gpgme.info, Node: I/O Callback Example, Next: I/O Callback Example GTK+, Prev: Registering I/O Callbacks, Up: Using External Event Loops 6594 65957.8.2.3 I/O Callback Example 6596............................ 6597 6598To actually use an external event loop, you have to implement the I/O 6599callback functions that are used by GPGME to register and unregister 6600file descriptors. Furthermore, you have to actually monitor these file 6601descriptors for activity and call the appropriate I/O callbacks. 6602 6603 The following example illustrates how to do that. The example uses 6604locking to show in which way the callbacks and the event loop can run 6605concurrently. For the event loop, we use a fixed array. For a 6606real-world implementation, you should use a dynamically sized structure 6607because the number of file descriptors needed for a crypto operation in 6608GPGME is not predictable. 6609 6610 #include <assert.h> 6611 #include <errno.h> 6612 #include <stdlib.h> 6613 #include <pthread.h> 6614 #include <sys/types.h> 6615 #include <gpgme.h> 6616 6617 /* The following structure holds the result of a crypto operation. */ 6618 struct op_result 6619 { 6620 int done; 6621 gpgme_error_t err; 6622 }; 6623 6624 /* The following structure holds the data associated with one I/O 6625 callback. */ 6626 struct one_fd 6627 { 6628 int fd; 6629 int dir; 6630 gpgme_io_cb_t fnc; 6631 void *fnc_data; 6632 void *loop; 6633 }; 6634 6635 struct event_loop 6636 { 6637 pthread_mutex_t lock; 6638 #define MAX_FDS 32 6639 /* Unused slots are marked with FD being -1. */ 6640 struct one_fd fds[MAX_FDS]; 6641 }; 6642 6643 The following functions implement the I/O callback interface. 6644 6645 gpgme_error_t 6646 add_io_cb (void *data, int fd, int dir, gpgme_io_cb_t fnc, void *fnc_data, 6647 void **r_tag) 6648 { 6649 struct event_loop *loop = data; 6650 struct one_fd *fds = loop->fds; 6651 int i; 6652 6653 pthread_mutex_lock (&loop->lock); 6654 for (i = 0; i < MAX_FDS; i++) 6655 { 6656 if (fds[i].fd == -1) 6657 { 6658 fds[i].fd = fd; 6659 fds[i].dir = dir; 6660 fds[i].fnc = fnc; 6661 fds[i].fnc_data = fnc_data; 6662 fds[i].loop = loop; 6663 break; 6664 } 6665 } 6666 pthread_mutex_unlock (&loop->lock); 6667 if (i == MAX_FDS) 6668 return gpg_error (GPG_ERR_GENERAL); 6669 *r_tag = &fds[i]; 6670 return 0; 6671 } 6672 6673 void 6674 remove_io_cb (void *tag) 6675 { 6676 struct one_fd *fd = tag; 6677 struct event_loop *loop = fd->loop; 6678 6679 pthread_mutex_lock (&loop->lock); 6680 fd->fd = -1; 6681 pthread_mutex_unlock (&loop->lock); 6682 } 6683 6684 void 6685 event_io_cb (void *data, gpgme_event_io_t type, void *type_data) 6686 { 6687 struct op_result *result = data; 6688 6689 /* We don't support list operations here. */ 6690 if (type == GPGME_EVENT_DONE) 6691 { 6692 result->done = 1; 6693 result->err = *type_data; 6694 } 6695 } 6696 6697 The final missing piece is the event loop, which will be presented 6698next. We only support waiting for the success of a single operation. 6699 6700 int 6701 do_select (struct event_loop *loop) 6702 { 6703 fd_set rfds; 6704 fd_set wfds; 6705 int i, n; 6706 int any = 0; 6707 struct timeval tv; 6708 struct one_fd *fdlist = loop->fds; 6709 6710 pthread_mutex_lock (&loop->lock); 6711 FD_ZERO (&rfds); 6712 FD_ZERO (&wfds); 6713 for (i = 0; i < MAX_FDS; i++) 6714 if (fdlist[i].fd != -1) 6715 FD_SET (fdlist[i].fd, fdlist[i].dir ? &rfds : &wfds); 6716 pthread_mutex_unlock (&loop->lock); 6717 6718 tv.tv_sec = 0; 6719 tv.tv_usec = 1000; 6720 6721 do 6722 { 6723 n = select (FD_SETSIZE, &rfds, &wfds, NULL, &tv); 6724 } 6725 while (n < 0 && errno == EINTR); 6726 6727 if (n < 0) 6728 return n; /* Error or timeout. */ 6729 6730 pthread_mutex_lock (&loop->lock); 6731 for (i = 0; i < MAX_FDS && n; i++) 6732 { 6733 if (fdlist[i].fd != -1) 6734 { 6735 if (FD_ISSET (fdlist[i].fd, fdlist[i].dir ? &rfds : &wfds)) 6736 { 6737 assert (n); 6738 n--; 6739 any = 1; 6740 /* The I/O callback handler can register/remove callbacks, 6741 so we have to unlock the file descriptor list. */ 6742 pthread_mutex_unlock (&loop->lock); 6743 (*fdlist[i].fnc) (fdlist[i].fnc_data, fdlist[i].fd); 6744 pthread_mutex_lock (&loop->lock); 6745 } 6746 } 6747 } 6748 pthread_mutex_unlock (&loop->lock); 6749 return any; 6750 } 6751 6752 void 6753 wait_for_op (struct event_loop *loop, struct op_result *result) 6754 { 6755 int ret; 6756 6757 do 6758 { 6759 ret = do_select (loop); 6760 } 6761 while (ret >= 0 && !result->done); 6762 } 6763 6764 The main function shows how to put it all together. 6765 6766 int 6767 main (int argc, char *argv[]) 6768 { 6769 struct event_loop loop; 6770 struct op_result result; 6771 gpgme_ctx_t ctx; 6772 gpgme_error_t err; 6773 gpgme_data_t sig, text; 6774 int i; 6775 pthread_mutexattr_t attr; 6776 struct gpgme_io_cbs io_cbs = 6777 { 6778 add_io_cb, 6779 &loop, 6780 remove_io_cb, 6781 event_io_cb, 6782 &result 6783 }; 6784 6785 init_gpgme (); 6786 6787 /* Initialize the loop structure. */ 6788 6789 /* The mutex must be recursive, since remove_io_cb (which acquires a 6790 lock) can be called while holding a lock acquired in do_select. */ 6791 pthread_mutexattr_init (&attr); 6792 pthread_mutexattr_settype (&attr, PTHREAD_MUTEX_RECURSIVE); 6793 pthread_mutex_init (&loop.lock, &attr); 6794 pthread_mutexattr_destroy (&attr); 6795 6796 for (i = 0; i < MAX_FDS; i++) 6797 loop.fds[i].fd = -1; 6798 6799 /* Initialize the result structure. */ 6800 result.done = 0; 6801 6802 err = gpgme_data_new_from_file (&sig, "signature", 1); 6803 if (!err) 6804 err = gpgme_data_new_from_file (&text, "text", 1); 6805 if (!err) 6806 err = gpgme_new (&ctx); 6807 if (!err) 6808 { 6809 gpgme_set_io_cbs (ctx, &io_cbs); 6810 err = gpgme_op_verify_start (ctx, sig, text, NULL); 6811 } 6812 if (err) 6813 { 6814 fprintf (stderr, "gpgme error: %s: %s\n", 6815 gpgme_strsource (err), gpgme_strerror (err)); 6816 exit (1); 6817 } 6818 6819 wait_for_op (&loop, &result); 6820 if (!result.done) 6821 { 6822 fprintf (stderr, "select error\n"); 6823 exit (1); 6824 } 6825 if (!result.err) 6826 { 6827 fprintf (stderr, "verification failed: %s: %s\n", 6828 gpgme_strsource (result.err), gpgme_strerror (result.err)); 6829 exit (1); 6830 } 6831 /* Evaluate verify result. */ 6832 ... 6833 return 0; 6834 } 6835 6836 6837File: gpgme.info, Node: I/O Callback Example GTK+, Next: I/O Callback Example GDK, Prev: I/O Callback Example, Up: Using External Event Loops 6838 68397.8.2.4 I/O Callback Example GTK+ 6840................................. 6841 6842The I/O callback interface can be used to integrate GPGME with the GTK+ 6843event loop. The following code snippets shows how this can be done 6844using the appropriate register and remove I/O callback functions. In 6845this example, the private data of the register I/O callback function is 6846unused. The event notifications is missing because it does not require 6847any GTK+ specific setup. 6848 6849 #include <gtk/gtk.h> 6850 6851 struct my_gpgme_io_cb 6852 { 6853 gpgme_io_cb_t fnc; 6854 void *fnc_data; 6855 guint input_handler_id 6856 }; 6857 6858 void 6859 my_gpgme_io_cb (gpointer data, gint source, GdkInputCondition condition) 6860 { 6861 struct my_gpgme_io_cb *iocb = data; 6862 (*(iocb->fnc)) (iocb->data, source); 6863 } 6864 6865 void 6866 my_gpgme_remove_io_cb (void *data) 6867 { 6868 struct my_gpgme_io_cb *iocb = data; 6869 gtk_input_remove (data->input_handler_id); 6870 } 6871 6872 void 6873 my_gpgme_register_io_callback (void *data, int fd, int dir, gpgme_io_cb_t fnc, 6874 void *fnc_data, void **tag) 6875 { 6876 struct my_gpgme_io_cb *iocb = g_malloc (sizeof (struct my_gpgme_io_cb)); 6877 iocb->fnc = fnc; 6878 iocb->data = fnc_data; 6879 iocb->input_handler_id = gtk_input_add_full (fd, dir 6880 ? GDK_INPUT_READ 6881 : GDK_INPUT_WRITE, 6882 my_gpgme_io_callback, 6883 0, iocb, NULL); 6884 *tag = iocb; 6885 return 0; 6886 } 6887 6888 6889File: gpgme.info, Node: I/O Callback Example GDK, Next: I/O Callback Example Qt, Prev: I/O Callback Example GTK+, Up: Using External Event Loops 6890 68917.8.2.5 I/O Callback Example GDK 6892................................ 6893 6894The I/O callback interface can also be used to integrate GPGME with the 6895GDK event loop. The following code snippets shows how this can be done 6896using the appropriate register and remove I/O callback functions. In 6897this example, the private data of the register I/O callback function is 6898unused. The event notifications is missing because it does not require 6899any GDK specific setup. 6900 6901 It is very similar to the GTK+ example in the previous section. 6902 6903 #include <gdk/gdk.h> 6904 6905 struct my_gpgme_io_cb 6906 { 6907 gpgme_io_cb_t fnc; 6908 void *fnc_data; 6909 gint tag; 6910 }; 6911 6912 void 6913 my_gpgme_io_cb (gpointer data, gint source, GdkInputCondition condition) 6914 { 6915 struct my_gpgme_io_cb *iocb = data; 6916 (*(iocb->fnc)) (iocb->data, source); 6917 } 6918 6919 void 6920 my_gpgme_remove_io_cb (void *data) 6921 { 6922 struct my_gpgme_io_cb *iocb = data; 6923 gdk_input_remove (data->tag); 6924 } 6925 6926 void 6927 my_gpgme_register_io_callback (void *data, int fd, int dir, gpgme_io_cb_t fnc, 6928 void *fnc_data, void **tag) 6929 { 6930 struct my_gpgme_io_cb *iocb = g_malloc (sizeof (struct my_gpgme_io_cb)); 6931 iocb->fnc = fnc; 6932 iocb->data = fnc_data; 6933 iocb->tag = gtk_input_add_full (fd, dir ? GDK_INPUT_READ : GDK_INPUT_WRITE, 6934 my_gpgme_io_callback, iocb, NULL); 6935 *tag = iocb; 6936 return 0; 6937 } 6938 6939 6940File: gpgme.info, Node: I/O Callback Example Qt, Prev: I/O Callback Example GDK, Up: Using External Event Loops 6941 69427.8.2.6 I/O Callback Example Qt 6943............................... 6944 6945The I/O callback interface can also be used to integrate GPGME with the 6946Qt event loop. The following code snippets show how this can be done 6947using the appropriate register and remove I/O callback functions. In 6948this example, the private data of the register I/O callback function is 6949unused. The event notifications is missing because it does not require 6950any Qt specific setup. 6951 6952 #include <qsocketnotifier.h> 6953 #include <qapplication.h> 6954 6955 struct IOCB { 6956 IOCB( GpgmeIOCb f, void * d, QSocketNotifier * n ) 6957 : func( f ), data( d ), notifier( n ) {} 6958 GpgmeIOCb func; 6959 void * data; 6960 QSocketNotifier * notifier; 6961 } 6962 6963 class MyApp : public QApplication { 6964 6965 // ... 6966 6967 static void registerGpgmeIOCallback( void * data, int fd, int dir, 6968 GpgmeIOCb func, void * func_data, 6969 void ** tag ) { 6970 QSocketNotifier * n = 6971 new QSocketNotifier( fd, dir ? QSocketNotifier::Read 6972 : QSocketNotifier::Write ); 6973 connect( n, SIGNAL(activated(int)), 6974 qApp, SLOT(slotGpgmeIOCallback(int)) ); 6975 qApp->mIOCBs.push_back( IOCB( func, func_data, n ) ); 6976 *tag = (void*)n; 6977 } 6978 6979 static void removeGpgmeIOCallback( void * tag ) { 6980 if ( !tag ) return; 6981 QSocketNotifier * n = static_cast<QSocketNotifier*>( tag ); 6982 for ( QValueList<IOCB>::iterator it = qApp->mIOCBs.begin() ; 6983 it != qApp->mIOCBs.end() ; ++it ) 6984 if ( it->notifier == n ) { 6985 delete it->notifier; 6986 qApp->mIOCBs.erase( it ); 6987 return; 6988 } 6989 } 6990 6991 public slots: 6992 void slotGpgmeIOCallback( int fd ) { 6993 for ( QValueList<IOCB>::const_iterator it = mIOCBs.begin() ; 6994 it != mIOCBs.end() ; ++it ) 6995 if ( it->notifier && it->notifier->socket() == fd ) 6996 (*(it->func)) ( it->func_data, fd ); 6997 } 6998 6999 // ... 7000 7001 private: 7002 QValueList<IOCB> mIOCBs; 7003 // ... 7004 }; 7005 7006 7007File: gpgme.info, Node: Cancellation, Prev: Using External Event Loops, Up: Run Control 7008 70097.8.3 Cancellation 7010------------------ 7011 7012Sometimes you do not want to wait for an operation to finish. GPGME 7013provides two different functions to achieve that. The function 7014‘gpgme_cancel’ takes effect immediately. When it returns, the operation 7015is effectively canceled. However, it has some limitations and can not 7016be used with synchronous operations. In contrast, the function 7017‘gpgme_cancel_async’ can be used with any context and from any thread, 7018but it is not guaranteed to take effect immediately. Instead, 7019cancellation occurs at the next possible time (typically the next time 7020I/O occurs in the target context). 7021 7022 -- Function: gpgme_ctx_t gpgme_cancel (gpgme_ctx_t CTX) 7023 SINCE: 0.4.5 7024 7025 The function ‘gpgme_cancel’ attempts to cancel a pending operation 7026 in the context CTX. This only works if you use the global event 7027 loop or your own event loop. 7028 7029 If you use the global event loop, you must not call ‘gpgme_wait’ 7030 during cancellation. After successful cancellation, you can call 7031 ‘gpgme_wait’ (optionally waiting on CTX), and the context CTX will 7032 appear as if it had finished with the error code ‘GPG_ERR_CANCEL’. 7033 7034 If you use an external event loop, you must ensure that no I/O 7035 callbacks are invoked for this context (for example by halting the 7036 event loop). On successful cancellation, all registered I/O 7037 callbacks for this context will be unregistered, and a 7038 ‘GPGME_EVENT_DONE’ event with the error code ‘GPG_ERR_CANCEL’ will 7039 be signalled. 7040 7041 The function returns an error code if the cancellation failed (in 7042 this case the state of CTX is not modified). 7043 7044 -- Function: gpgme_ctx_t gpgme_cancel_async (gpgme_ctx_t CTX) 7045 SINCE: 1.1.7 7046 7047 The function ‘gpgme_cancel_async’ attempts to cancel a pending 7048 operation in the context CTX. This can be called by any thread at 7049 any time after starting an operation on the context, but will not 7050 take effect immediately. The actual cancellation happens at the 7051 next time GPGME processes I/O in that context. 7052 7053 The function returns an error code if the cancellation failed (in 7054 this case the state of CTX is not modified). 7055 7056 7057File: gpgme.info, Node: UI Server Protocol, Next: Debugging, Prev: Contexts, Up: Top 7058 7059Appendix A The GnuPG UI Server Protocol 7060*************************************** 7061 7062This section specifies the protocol used between clients and a User 7063Interface Server (UI server). This protocol helps to build a system 7064where all cryptographic operations are done by a server and the server 7065is responsible for all dialogs. Although GPGME has no direct support 7066for this protocol it is believed that servers will utilize the GPGME 7067library; thus having the specification included in this manual is an 7068appropriate choice. This protocol should be referenced as ‘The GnuPG UI 7069Server Protocol’. 7070 7071A server needs to implement these commands:(1) 7072 7073* Menu: 7074 7075* UI Server Encrypt:: Encrypt a message. 7076* UI Server Sign:: Sign a message. 7077* UI Server Decrypt:: Decrypt a message. 7078* UI Server Verify:: Verify a message. 7079* UI Server Set Input Files:: Specifying the input files to operate on. 7080* UI Server Sign/Encrypt Files:: Encrypting and signing files. 7081* UI Server Verify/Decrypt Files:: Decrypting and verifying files. 7082* UI Server Import/Export Keys:: Managing certificates. 7083* UI Server Checksum Files:: Create and verify checksums for files. 7084* Miscellaneous UI Server Commands:: Commands not related to a specific operation. 7085 7086 ---------- Footnotes ---------- 7087 7088 (1) In all examples we assume that the connection has already been 7089established; see the Assuan manual for details. 7090 7091 7092File: gpgme.info, Node: UI Server Encrypt, Next: UI Server Sign, Up: UI Server Protocol 7093 7094A.1 UI Server: Encrypt a Message 7095================================ 7096 7097Before encryption can be done the recipients must be set using the 7098command: 7099 7100 -- Command: RECIPIENT STRING 7101 7102 Set the recipient for the encryption. STRING is an RFC-2822 7103 recipient name ("mailbox" as per section 3.4). This command may or 7104 may not check the recipient for validity right away; if it does not 7105 all recipients are expected to be checked at the time of the 7106 ‘ENCRYPT’ command. All ‘RECIPIENT’ commands are cumulative until a 7107 successful ‘ENCRYPT’ command or until a ‘RESET’ command. Linefeeds 7108 are obviously not allowed in STRING and should be folded into 7109 spaces (which are equivalent). 7110 7111To tell the server the source and destination of the data, the next two 7112commands are to be used: 7113 7114 -- Command: INPUT FD=N 7115 Set the file descriptor for the message to be encrypted to N. The 7116 message send to the server is binary encoded. 7117 7118 GpgOL is a Windows only program, thus N is not a libc file 7119 descriptor but a regular system handle. Given that the Assuan 7120 connection works over a socket, it is not possible to use regular 7121 inheritance to make the file descriptor available to the server. 7122 Thus ‘DuplicateHandle’ needs to be used to duplicate a handle to 7123 the server process. This is the reason that the server needs to 7124 implement the ‘GETINFO pid’ command. Sending this command a second 7125 time replaces the file descriptor set by the last one. 7126 7127 -- Command: OUTPUT FD=N [--binary] 7128 Set the file descriptor to be used for the output (i.e. the 7129 encrypted message) to N. If the option ‘--binary’ is given the 7130 output shall be in binary format; if not given, the output for 7131 OpenPGP needs to be ASCII armored and for CMS Base-64 encoded. For 7132 details on the file descriptor, see the ‘INPUT’ command. 7133 7134The setting of the recipients, the data source and destination may 7135happen in any order, even intermixed. If this has been done the actual 7136encryption operation is called using: 7137 7138 -- Command: ENCRYPT --protocol=NAME 7139 7140 This command reads the plaintext from the file descriptor set by 7141 the ‘INPUT’ command, encrypts it and writes the ciphertext to the 7142 file descriptor set by the ‘OUTPUT’ command. The server may (and 7143 should) overlap reading and writing. The recipients used for the 7144 encryption are all the recipients set so far. If any recipient is 7145 not usable the server should take appropriate measures to notify 7146 the user about the problem and may cancel the operation by 7147 returning an error code. The used file descriptors are void after 7148 this command; the recipient list is only cleared if the server 7149 returns success. 7150 7151 Because GpgOL uses a streaming mode of operation the server is not 7152 allowed to auto select the protocol and must obey to the mandatory 7153 PROTOCOL parameter: 7154 7155 ‘OpenPGP’ 7156 Use the OpenPGP protocol (RFC-2440). 7157 ‘CMS’ 7158 Use the CMS (PKCS#7) protocol (RFC-3852). 7159 7160 To support automagically selection of the protocol depending on the 7161selected keys, the server MAY implement the command: 7162 7163 -- Command: PREP_ENCRYPT [--protocol=NAME] [--expect-sign] 7164 7165 This commands considers all recipients set so far and decides 7166 whether it is able to take input and start the actual encryption. 7167 This is kind of a dry-run ‘ENCRYPT’ without requiring or using the 7168 input and output file descriptors. The server shall cache the 7169 result of any user selection to avoid asking this again when the 7170 actual ‘ENCRYPT’ command is send. The ‘--protocol’ option is 7171 optional; if it is not given, the server should allow the user to 7172 select the protocol to be used based on the recipients given or by 7173 any other means. 7174 7175 If ‘--expect-sign’ is given the server should expect that the 7176 message will also be signed and use this hint to present a unified 7177 recipient and signer selection dialog if possible and desired. A 7178 selected signer should then be cached for the expected SIGN command 7179 (which is expected in the same session but possible on another 7180 connection). 7181 7182 If this command is given again before a successful ‘ENCRYPT’ 7183 command, the second one takes effect. 7184 7185 Before sending the OK response the server shall tell the client the 7186 protocol to be used (either the one given by the argument or the 7187 one selected by the user) by means of a status line: 7188 7189 -- Status line: PROTOCOL NAME 7190 Advise the client to use the protocol NAME for the ‘ENCRYPT’ 7191 command. The valid protocol names are listed under the description 7192 of the ‘ENCRYPT’ command. The server shall emit exactly one 7193 PROTOCOL status line. 7194 7195Here is an example of a complete encryption sequence; client lines are 7196indicated by a C:, server responses by C:: 7197 7198 C: RESET 7199 S: OK 7200 C: RECIPIENT foo@example.net 7201 S: OK 7202 C: RECIPIENT bar@example.com 7203 S: OK 7204 C: PREP_ENCRYPT 7205 S: S PROTOCOL OpenPGP 7206 S: OK 7207 C: INPUT FD=17 7208 S: OK 7209 C: OUTPUT FD=18 7210 S: OK 7211 C: ENCRYPT 7212 S: OK 7213 7214 7215File: gpgme.info, Node: UI Server Sign, Next: UI Server Decrypt, Prev: UI Server Encrypt, Up: UI Server Protocol 7216 7217A.2 UI Server: Sign a Message 7218============================= 7219 7220The server needs to implement opaque signing as well as detached 7221signing. Due to the nature of OpenPGP messages it is always required to 7222send the entire message to the server; sending just the hash is not 7223possible. The following two commands are required to set the input and 7224output file descriptors: 7225 7226 -- Command: INPUT FD=N 7227 Set the file descriptor for the message to be signed to N. The 7228 message send to the server is binary encoded. For details on the 7229 file descriptor, see the description of ‘INPUT’ in the ‘ENCRYPT’ 7230 section. 7231 7232 -- Command: OUTPUT FD=N [--binary] 7233 Set the file descriptor to be used for the output. The output is 7234 either the complete signed message or in case of a detached 7235 signature just that detached signature. If the option ‘--binary’ 7236 is given the output shall be in binary format; if not given, the 7237 output for OpenPGP needs to be ASCII armored and for CMS Base-64 7238 encoded. For details on the file descriptor, see the ‘INPUT’ 7239 command. 7240 7241To allow the server the selection of a non-default signing key the 7242client may optionally use the ‘SENDER’ command, see *note command 7243SENDER::. 7244 7245The signing operation is then initiated by: 7246 7247 -- Command: SIGN --protocol=NAME [--detached] 7248 Sign the data set with the ‘INPUT’ command and write it to the sink 7249 set by OUTPUT. NAME is the signing protocol used for the message. 7250 For a description of the allowed protocols see the ‘ENCRYPT’ 7251 command. With option ‘--detached’ given, a detached signature is 7252 created; this is actually the usual way the command is used. 7253 7254The client expects the server to send at least this status information 7255before the final OK response: 7256 7257 -- Status line: MICALG STRING 7258 The STRING represents the hash algorithm used to create the 7259 signature. It is used with RFC-1847 style signature messages and 7260 defined by PGP/MIME (RFC-3156) and S/MIME (RFC-3851). The GPGME 7261 library has a supporting function ‘gpgme_hash_algo_name’ to return 7262 the algorithm name as a string. This string needs to be lowercased 7263 and for OpenPGP prefixed with "‘pgp-’". 7264 7265