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