diff options
Diffstat (limited to 'doc/gpgme.texi')
| -rw-r--r-- | doc/gpgme.texi | 345 |
1 files changed, 272 insertions, 73 deletions
diff --git a/doc/gpgme.texi b/doc/gpgme.texi index 7f17815..260c057 100644 --- a/doc/gpgme.texi +++ b/doc/gpgme.texi @@ -421,18 +421,28 @@ directory in which the header file is located to the compilers include file search path (via the @option{-I} option). However, the path to the include file is determined at the time the -source is configured. To solve this problem, gpgme ships with a small -helper program @command{gpgme-config} that knows about the path to the -include file and other configuration options. The options that need -to be added to the compiler invocation at compile time are output by -the @option{--cflags} option to @command{gpgme-config}. The following -example shows how it can be used at the command line: +source is configured. To solve this problem, gpgme ships with +@code{gpgme.pc} file, that knows about the path to the include file +and other configuration options. The command, @command{pkg-config}, +can be used to handle information with @code{gpgme.pc} file. In an +environment which doesn't have @command{pkg-config} (like the one in +early stage of OS bootstrap), for Automake, you can use +@code{gpgme.m4} which invokes @command{gpgrt-config} with +@code{gpgme.pc}. (In the past, gpgme used to ship with a small helper +program @command{gpgme-config}. This functionality of +@command{gpgme-config} is replaced by @command{pkg-config} with +@code{gpgme.pc} file.) + +The options that need to be added to the compiler invocation at +compile time are output by the @option{--cflags} option to +@command{pkg-config gpgme}. The following example shows how it can be +used at the command line: @example -gcc -c foo.c `gpgme-config --cflags` +gcc -c foo.c `pkg-config --cflags gpgme` @end example -Adding the output of @samp{gpgme-config --cflags} to the compiler +Adding the output of @samp{pkg-config --cflags gpgme} to the compiler command line will ensure that the compiler can find the @acronym{GPGME} header file. @@ -440,36 +450,39 @@ A similar problem occurs when linking the program with the library. Again, the compiler has to find the library files. For this to work, the path to the library files has to be added to the library search path (via the @option{-L} option). For this, the option -@option{--libs} to @command{gpgme-config} can be used. For +@option{--libs} to @command{pkg-config gpgme} can be used. For convenience, this option also outputs all other options that are required to link the program with @acronym{GPGME} (in particular, the @samp{-lgpgme} option). The example shows how to link @file{foo.o} with the @acronym{GPGME} library to a program @command{foo}. @example -gcc -o foo foo.o `gpgme-config --libs` +gcc -o foo foo.o `pkg-config --libs gpgme` @end example Of course you can also combine both examples to a single command by -specifying both options to @command{gpgme-config}: +specifying both options to @command{pkg-config gpgme}: @example -gcc -o foo foo.c `gpgme-config --cflags --libs` -@end example - -If you need to detect the installed language bindings you can use list -them using: - -@example -gpgme-config --print-lang -@end example - -or test for the availability using - -@example -gpgme-config --have-lang=python && echo 'Bindings for Pythons available' +gcc -o foo foo.c `pkg-config --cflags --libs gpgme` @end example +@c +@c Feature not available by pkg-config/gpgrt-config +@c +@c If you need to detect the installed language bindings you can use list +@c them using: +@c +@c @example +@c gpgme-config --print-lang +@c @end example +@c +@c or test for the availability using +@c +@c @example +@c gpgme-config --have-lang=python && echo 'Bindings for Pythons available' +@c @end example +@c @node Largefile Support (LFS) @section Largefile Support (LFS) @@ -578,7 +591,7 @@ mode (@code{_LARGEFILE64_SOURCE}). It is much easier if you use GNU Automake instead of writing your own Makefiles. If you do that you do not have to worry about finding and -invoking the @command{gpgme-config} script at all. @acronym{GPGME} +invoking the @command{pkg-config} script at all. @acronym{GPGME} provides an extension to Automake that does all the work for you. @c A simple macro for optional variables. @@ -586,35 +599,36 @@ provides an extension to Automake that does all the work for you. @r{[}@var{\varname\}@r{]} @end macro @defmac AM_PATH_GPGME (@ovar{minimum-version}, @ovar{action-if-found}, @ovar{action-if-not-found}) -@defmacx AM_PATH_GPGME_PTH (@ovar{minimum-version}, @ovar{action-if-found}, @ovar{action-if-not-found}) -@defmacx AM_PATH_GPGME_PTHREAD (@ovar{minimum-version}, @ovar{action-if-found}, @ovar{action-if-not-found}) Check whether @acronym{GPGME} (at least version @var{minimum-version}, if given) exists on the host system. If it is found, execute @var{action-if-found}, otherwise do @var{action-if-not-found}, if given. +This macro locates for @code{gpgme.pc}, with cross-compile support. + Additionally, the function defines @code{GPGME_CFLAGS} to the flags needed for compilation of the program to find the @file{gpgme.h} header file, and @code{GPGME_LIBS} to the linker flags needed to link -the program to the @acronym{GPGME} library. If the used helper script -does not match the target type you are building for a warning is -printed and the string @code{libgcrypt} is appended to the variable -@code{gpg_config_script_warn}. - -@code{AM_PATH_GPGME_PTHREAD} checks for the version of @acronym{GPGME} -that can be used with the native pthread implementation, and defines -@code{GPGME_PTHREAD_CFLAGS} and @code{GPGME_PTHREAD_LIBS}. Since -version 1.8.0 this is no longer required to GPGME_PTHREAD as -@acronym{GPGME} itself is thread safe. - -This macro searches for @command{gpgme-config} along the PATH. If -you are cross-compiling, it is useful to set the environment variable -@code{SYSROOT} to the top directory of your target. The macro will -then first look for the helper program in the @file{bin} directory -below that top directory. An absolute directory name must be used for -@code{SYSROOT}. Finally, if the configure command line option -@code{--with-gpgme-prefix} is used, only its value is used for the top -directory below which the helper script is expected. +the program to the @acronym{GPGME} library. +@c +@c If the used helper script does not match the target type you are +@c building for a warning is printed and the string @code{gpgme} is +@c appended to the variable @code{gpg_config_script_warn}. +@c@c@c@c@c@c@c@c +@c ^-- About this statement. +@c In the past, this might happens, when it was configured by +@c --with-*-prefix options, and it located the helper script for +@c other target. Cross-build by gpgrt-config has been improved +@c (in different way), so it's not relevant now. +@c + + +@code{AM_PATH_GPGME_PTHREAD} was provided to check for the version of +@acronym{GPGME} with the native pthread implementation, and it defined +@code{GPGME_PTHREAD_CFLAGS} and @code{GPGME_PTHREAD_LIBS}. Since +version 1.8.0 this is no longer necessary, as @acronym{GPGME} itself +is thread safe. Please use plain @code{AM_PATH_GPGME} instead, with +@code{GPGME_CFLAGS} and @code{GPGME_LDFLAGS}. @end defmac @@ -632,9 +646,8 @@ LDADD = $(GPGME_LIBS) @cindex libtool The easiest way is to just use GNU Libtool. If you use libtool, and -link to @code{libgpgme.la}, @code{libgpgme-pth.la} or -@code{libgpgme-pthread.la} respectively, everything will be done -automatically by Libtool. +link to @code{libgpgme.la}, everything will be done automatically by +Libtool. @node Library Version Check @@ -727,6 +740,13 @@ is not met, GPGME fails early instead of trying to use the existent version. The given version must be a string with major, minor, and micro number. Example: "2.1.0". +@item inst-type +The installation type is used to prefer a certain GnuPG installation. +The value is interpreted as an integer: A value of 0 is ignored, a +value of 1 indicates an installation scheme as used by Gpg4win, a +value of 2 indicates an installation scheme as used by GnuPG Desktop +on Windows. All other values are reserved. + @item w32-inst-dir On Windows GPGME needs to know its installation directory to find its spawn helper. This is in general no problem because a DLL has this @@ -961,6 +981,9 @@ Return the name of the directory with GnuPG shared data. @item localedir Return the name of the directory with GnuPG locale data. +@item socketdir +Return the name of the directory with the following sockets. + @item agent-socket Return the name of the socket to connect to the gpg-agent. @@ -1004,6 +1027,9 @@ Return the name of the pinentry program. @item gpg-wks-client-name Return the name of the Web Key Service tool. +@item gpgtar-name +Return the name of the gpgtar program. + @end table @end deftypefun @@ -1623,6 +1649,11 @@ when requested. @item GPG_ERR_CANCELED This value means that the operation was canceled. +@item GPG_ERR_FULLY_CANCELED +This value means that the operation was canceled. It is sometimes returned +instead of @code{GPG_ERR_CANCELED} for internal reasons in GnuPG. You should +treat both values identically. + @item GPG_ERR_INV_ENGINE This value means that the engine that implements the desired protocol is currently not available. This can either be because the sources @@ -2173,6 +2204,11 @@ associated with the data object. The file name will be stored in the output when encrypting or signing the data and will be returned to the user when decrypting or verifying the output data. +If a signed or encrypted archive is created, then the file name will be +interpreted as the base directory for the relative paths of the files and +directories to put into the archive. This corresponds to the --directory +option of gpgtar. + The function returns the error code @code{GPG_ERR_INV_VALUE} if @var{dh} is not a valid pointer and @code{GPG_ERR_ENOMEM} if not enough memory is available. @@ -2336,7 +2372,7 @@ The data is a PKCS#12 message. This is commonly used to exchange private keys for X.509. @end table -@deftypefun gpgme_data_type_t gpgme_data_identify (@w{gpgme_data_t @var{dh}}) +@deftypefun gpgme_data_type_t gpgme_data_identify (@w{gpgme_data_t @var{dh}, int @var{reserved}}) @since{1.4.3} The function @code{gpgme_data_identify} returns the type of the data @@ -2346,6 +2382,7 @@ identification, the function returns zero object has been created the identification may not be possible or the data object may change its internal state (file pointer moved). For file or memory based data object, the state should not change. +@var{reserved} should be zero. @end deftypefun @@ -2657,8 +2694,9 @@ for example completely disable the use of Dirmngr for any engine. For the CMS protocol the offline mode specifies whether Dirmngr shall be used to do additional validation that might require connecting -external services (e.g. CRL / OCSP checks). Here the offline mode -only affects the keylist mode @code{GPGME_KEYLIST_MODE_VALIDATE}. +external services (e.g. CRL / OCSP checks). The offline mode is used +for all operations on this context. It has only an effect with +GnuPG versions 2.1.6 or later. For the OpenPGP protocol offline mode entirely disables the use of the Dirmngr and will thus guarantee that no network connections are done @@ -2863,6 +2901,12 @@ option also makes sure that the keygrip is available in the output. The @code{GPGME_KEYLIST_MODE_EPHEMERAL} symbol specifies that keys flagged as ephemeral are included in the listing. +@item GPGME_KEYLIST_MODE_WITH_V5FPR +@since{1.23.0} + +The @code{GPGME_KEYLIST_MODE_WITH_V5FPR} symbol specifies that key +listings shall also provide v5 style fingerprints for v4 OpenPGp keys. + @item GPGME_KEYLIST_MODE_VALIDATE @since{0.4.5} @@ -3141,8 +3185,8 @@ The string given in @var{value} is passed to the GnuPG engine to override the session key for decryption. The format of that session key is specific to GnuPG and can be retrieved during a decrypt operation when the context flag "export-session-key" is enabled. Please be aware that -using this feature with GnuPG < 2.1.16 will leak the session key on -many platforms via ps(1). +using this feature with GnuPG < 2.1.16 or when decrypting an archive +will leak the session key on many platforms via ps(1). @item "auto-key-retrieve" Setting the @var{value} to "1" asks the backend to automatically @@ -3229,6 +3273,11 @@ The string given in @var{value} is passed to the GnuPG engine to use as filter when importing keys. Valid values are documented in the GnuPG manual and the gpg man page under the option @option{--import-filter}. +@item "no-auto-check-trustdb" +@since{1.19.0} +Setting the @var{value} to "1" forces the GPG backend to disable the +automatic check of the trust database. + @end table This function returns @code{0} on success. @@ -3412,22 +3461,47 @@ listings if the key could not be validated due to missing certificates or unmatched policies. @item unsigned int can_encrypt : 1 -This is true if the key (ie one of its subkeys) can be used for -encryption. +This is true if the key or one of its subkeys can be used for +encryption and the encryption will likely succeed. @item unsigned int can_sign : 1 -This is true if the key (ie one of its subkeys) can be used to create -data signatures. +This is true if the key or one of its subkeys can be used to create +data signatures and the signing will likely succeed. @item unsigned int can_certify : 1 -This is true if the key (ie one of its subkeys) can be used to create +This is true if the key or one of its subkeys can be used to create key certificates. @item unsigned int can_authenticate : 1 @since{0.4.5} This is true if the key (ie one of its subkeys) can be used for -authentication. +authentication and the authentication will likely succeed. + +@item unsigned int has_encrypt : 1 +@since{1.23.0} + +This is true if the key or one of its subkeys is capable of encryption. +Note that this flag is set even if the key is expired. + +@item unsigned int has_sign : 1 +@since{1.23.0} + +This is true if the key or one of its subkeys is capable of signing. +Note that this flag is set even if the key is expired. + +@item unsigned int has_certify : 1 +@since{1.23.0} + +This is true if the key or one of its subkeys is capable of +certification. Note that this flag is set even if the key is expired. + +@item unsigned int has_authenticate : 1 +@since{1.23.0} + +This is true if the key or one of its subkeys is capable of +authentication. Note that this flag is set even if the key is +expired. @item unsigned int is_qualified : 1 @since{1.1.0} @@ -3567,6 +3641,10 @@ This is the key ID of the subkey in hexadecimal digits. This is the fingerprint of the subkey in hexadecimal digits, if available. +@item char *v5fpr +For a v4 OpenPGP key this is its v5 style fingerprint of the subkey in +hexadecimal digits, if available. + @item char *keygrip @since{1.7.0} @@ -5550,8 +5628,9 @@ An error code describing the reason why the key was found invalid. @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}}) The function @code{gpgme_op_decrypt} decrypts the ciphertext in the -data object @var{cipher} and stores it into the data object -@var{plain}. +data object @var{cipher} or, if a file name is set on the data object, +the ciphertext stored in the corresponding file. The decrypted +ciphertext is stored into the data object @var{plain}. The function returns the error code @code{GPG_ERR_NO_ERROR} if the ciphertext could be decrypted successfully, @code{GPG_ERR_INV_VALUE} @@ -5586,6 +5665,12 @@ The function @code{gpgme_op_decrypt_ext} is the same as @code{gpgme_op_decrypt} but has an additional argument @var{flags}. If @var{flags} is 0 both function behave identically. +If the flag @code{GPGME_DECRYPT_ARCHIVE} is set, then an encrypted +archive in the data object @var{cipher} is decrypted and extracted. +The content of the archive is extracted into a directory named +@code{GPGARCH_n_} (where @code{n} is a number) or into the directory +set with @code{gpgme_data_set_file_name} for the data object @var{plain}. + The value in @var{flags} is a bitwise-or combination of one or multiple of the following bit values: @@ -5596,6 +5681,14 @@ multiple of the following bit values: The @code{GPGME_DECRYPT_VERIFY} symbol specifies that this function shall exactly act as @code{gpgme_op_decrypt_verify}. +@item GPGME_DECRYPT_ARCHIVE +@since{1.19.0} + +The @code{GPGME_DECRYPT_ARCHIVE} symbol specifies that the input is an +encrypted archive that shall be decrypted and extracted. This feature +is currently only supported for the OpenPGP crypto engine and requires +GnuPG 2.4.1. + @item GPGME_DECRYPT_UNWRAP @since{1.8.0} @@ -5750,7 +5843,10 @@ detached signature, then the signed text should be provided in Otherwise, if @var{sig} is a normal (or cleartext) signature, @var{signed_text} should be a null pointer and @var{plain} should be a writable data object that will contain the plaintext after successful -verification. +verification. If a file name is set on the data object @var{sig} (or +on the data object @var{signed_text}), then the data of the signature +(resp. the data of the signed text) is not read from the data object +but from the file with the given file name. The results of the individual signature verifications can be retrieved with @code{gpgme_op_verify_result}. @@ -5775,6 +5871,61 @@ operation could be started successfully, @code{GPG_ERR_INV_VALUE} if any data to verify. @end deftypefun + +@deftypefun gpgme_error_t gpgme_op_verify_ext ( @ + @w{gpgme_ctx_t @var{ctx}}, @ + @w{gpgme_verify_flags_t @var{flags}}, @ + @w{gpgme_data_t @var{sig}}, @ + @w{gpgme_data_t @var{signed_text}}, @ + @w{gpgme_data_t @var{plain}}) + +The function @code{gpgme_op_verify_ext} is the same as +@code{gpgme_op_verify} but has an additional argument +@var{flags}. If @var{flags} is 0 both function behave identically. + +If the flag @code{GPGME_VERIFY_ARCHIVE} is set, then a signed archive +in the data object @var{sig} is verified and extracted. The content of +the archive is extracted into a directory named @code{GPGARCH_n_} +(where @code{n} is a number) or into the directory set with +@code{gpgme_data_set_file_name} for the data object @var{plain}. + +The value in @var{flags} is a bitwise-or combination of one or +multiple of the following bit values: + +@table @code +@item GPGME_VERIFY_ARCHIVE +@since{1.19.0} + +The @code{GPGME_VERIFY_ARCHIVE} symbol specifies that the input is a +signed archive that shall be verified and extracted. This feature +is currently only supported for the OpenPGP crypto engine and requires +GnuPG 2.4.1. + +@end table + +The function returns the error codes as descriped for +@code{gpgme_op_decrypt} respective @code{gpgme_op_encrypt}. +@end deftypefun + +@deftypefun gpgme_error_t gpgme_op_verify_ext_start ( @ + @w{gpgme_ctx_t @var{ctx}}, @ + @w{gpgme_verify_flags_t @var{flags}}, @ + @w{gpgme_data_t @var{sig}}, @ + @w{gpgme_data_t @var{signed_text}}, @ + @w{gpgme_data_t @var{plain}}) + +The function @code{gpgme_op_verify_ext_start} initiates a +@code{gpgme_op_verify_ext} operation. It can be completed by calling +@code{gpgme_wait} on the context. @xref{Waiting For Completion}. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +operation could be started successfully, @code{GPG_ERR_INV_VALUE} if +@var{ctx}, @var{sig} or @var{plain} is not a valid pointer, and +@code{GPG_ERR_NO_DATA} if @var{sig} or @var{plain} does not contain +any data to verify. +@end deftypefun + + @deftp {Data type} {gpgme_sig_notation_t} This is a pointer to a structure used to store a part of the result of a @code{gpgme_op_verify} operation. The structure contains the @@ -6207,16 +6358,33 @@ A detached signature is made. @item GPGME_SIG_MODE_CLEAR A clear text signature is made. The @acronym{ASCII} armor and text mode settings of the context are ignored. + +@item GPGME_SIG_MODE_ARCHIVE +@since{1.19.0} + +A signed archive is created from the given files and directories. This +feature is currently only supported for the OpenPGP crypto engine and requires +GnuPG 2.4.1. + @end table @end deftp @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}}) The function @code{gpgme_op_sign} creates a signature for the text in the data object @var{plain} and returns it in the data object -@var{sig}. The type of the signature created is determined by the -@acronym{ASCII} armor (or, if that is not set, by the encoding -specified for @var{sig}), the text mode attributes set for the context -@var{ctx} and the requested signature mode @var{mode}. +@var{sig} or writes it directly to the file set with +@code{gpgme_data_set_file_name} for the data object @var{sig}. The type +of the signature created is determined by the @acronym{ASCII} armor (or, +if that is not set, by the encoding specified for @var{sig}), the text +mode attributes set for the context @var{ctx} and the requested signature +mode @var{mode}. + +If signature mode @code{GPGME_SIG_MODE_ARCHIVE} is requested, then a +signed archive is created from the files and directories given as +NUL-separated list in the data object @var{plain} and returned in the +data object @var{sig}. The paths of the files and directories have to +be given as paths relative to the current working directory or relative +to the base directory set with @code{gpgme_data_set_file_name}. After the operation completed successfully, the result can be retrieved with @code{gpgme_op_sign_result}. @@ -6265,7 +6433,8 @@ The public key algorithm used to create this signature. The hash algorithm used to create this signature. @item unsigned int sig_class -The signature class of this signature. +The signature class of this signature. Note that only the values 0, +1, and 2 are well-defined. @item long int timestamp The creation timestamp of this signature. @@ -6383,10 +6552,19 @@ and then passed to the encryption operation. @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}}) The function @code{gpgme_op_encrypt} encrypts the plaintext in the data object @var{plain} for the recipients @var{recp} and stores the -ciphertext in the data object @var{cipher}. The type of the -ciphertext created is determined by the @acronym{ASCII} armor (or, if -that is not set, by the encoding specified for @var{cipher}) and the -text mode attributes set for the context @var{ctx}. +ciphertext in the data object @var{cipher} or writes it directly to the +file set with @code{gpgme_data_set_file_name} for the data object +@var{cipher}. The type of the ciphertext created is determined by the +@acronym{ASCII} armor (or, if that is not set, by the encoding specified +for @var{cipher}) and the text mode attributes set for the context +@var{ctx}. + +If the flag @code{GPGME_ENCRYPT_ARCHIVE} is set, then an encrypted +archive is created from the files and directories given as NUL-separated +list in the data object @var{plain} and returned in the data object +@var{cipher}. The paths of the files and directories have to +be given as paths relative to the current working directory or relative +to the base directory set with @code{gpgme_data_set_file_name}. @var{recp} must be a @code{NULL}-terminated array of keys. The user must keep references for all keys during the whole duration of the @@ -6403,6 +6581,10 @@ recipients in @var{recp} should be trusted, even if the keys do not have a high enough validity in the keyring. This flag should be used with care; in general it is not a good idea to use any untrusted keys. +For the S/MIME (CMS) protocol this flag allows to encrypt to a +certificate without running any checks on the validity of the +certificate. + @item GPGME_ENCRYPT_NO_ENCRYPT_TO @since{1.2.0} @@ -6463,6 +6645,14 @@ of now the key must be specified using the @var{recpstring} argument of the extended encrypt functions. This feature is currently only supported for the OpenPGP crypto engine. +@item GPGME_ENCRYPT_ARCHIVE +@since{1.19.0} + +The @code{GPGME_ENCRYPT_ARCHIVE} symbol specifies that the input is a +NUL-separated list of file paths and directory paths that shall be +encrypted into an archive. This feature is currently only supported +for the OpenPGP crypto engine and requires GnuPG 2.4.1. + @end table If @code{GPG_ERR_UNUSABLE_PUBKEY} is returned, some recipients in @@ -7798,6 +7988,15 @@ reveal sensitive details like passphrases or other data you use in your application. If you are asked to send a log file, make sure that you run your tests only with play data. +The trace function makes use of gpgrt's logging function and thus the +special @file{socket://} and @file{tcp://} files may be used. Because +this conflicts with the use of colons to separate fields, the following +hack is used: If the file name contains the string @code{^//} all +carets are replaced by colons. For example to log to TCP port 42042 +this can be used: +@smallexample +GPGME_DEBUG=5:tcp^//127.0.0.1^42042 +@end smallexample @node Deprecated Functions @appendix Deprecated Functions |