diff options
Diffstat (limited to 'doc/gpgme.texi')
| -rw-r--r-- | doc/gpgme.texi | 150 |
1 files changed, 142 insertions, 8 deletions
diff --git a/doc/gpgme.texi b/doc/gpgme.texi index c4a29d5..d99e9bb 100644 --- a/doc/gpgme.texi +++ b/doc/gpgme.texi @@ -14,7 +14,7 @@ @syncodeindex pg fn @copying -Copyright @copyright{} 2002--2008, 2010, 2012--2017 g10 Code GmbH. +Copyright @copyright{} 2002--2008, 2010, 2012--2018 g10 Code GmbH. @quotation Permission is granted to copy, distribute and/or modify this document @@ -1909,6 +1909,25 @@ data object was successfully created, and @code{GPG_ERR_ENOMEM} if not enough memory is available. @end deftypefun +@deftypefun gpgme_error_t gpgme_data_new_from_estream (@w{gpgme_data_t *@var{dh}}, @w{gpgrt_stream_t @var{stream}}) +The function @code{gpgme_data_new_from_estream} creates a new +@code{gpgme_data_t} object and uses the gpgrt stream @var{stream} to read +from (if used as an input data object) and write to (if used as an +output data object). + +When using the data object as an input buffer, the function might read +a bit more from the stream than is actually needed by the crypto +engine in the desired operation because of internal buffering. + +Note that GPGME assumes that the stream is in blocking mode. Errors +during I/O operations, except for EINTR, are usually fatal for crypto +operations. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +data object was successfully created, and @code{GPG_ERR_ENOMEM} if not +enough memory is available. +@end deftypefun + @node Callback Based Data Buffers @subsection Callback Based Data Buffers @@ -2426,6 +2445,7 @@ started. In fact, these references are accessed through the * Progress Meter Callback:: Being informed about the progress. * Status Message Callback:: Status messages received from gpg. * Locale:: Setting the locale of a context. +* Additional Logs:: Additional logs of a context. @end menu @@ -2762,6 +2782,8 @@ The @code{GPGME_KEYLIST_MODE_LOCAL} symbol specifies that the local keyring should be searched for keys in the keylisting operation. This is the default. +Using only this option results in a @code{--list-keys}. + @item GPGME_KEYLIST_MODE_EXTERN The @code{GPGME_KEYLIST_MODE_EXTERN} symbol specifies that an external source should be searched for keys in the keylisting operation. The @@ -2769,10 +2791,14 @@ type of external source is dependent on the crypto engine used and whether it is combined with @code{GPGME_KEYLIST_MODE_LOCAL}. For example, it can be a remote keyserver or LDAP certificate server. +Using only this option results in a @code{--search-keys} for +@code{GPGME_PROTOCOL_OpenPGP} and something similar to +@code{--list-external-keys} for @code{GPGME_PROTOCOL_CMS}. + @item GPGME_KEYLIST_MODE_LOCATE This is a shortcut for the combination of -@code{GPGME_KEYLIST_MODE_LOCAL} and @code{GPGME_KEYLIST_MODE_EXTERN} -and convenient when the --locate-key feature of OpenPGP is desired. +@code{GPGME_KEYLIST_MODE_LOCAL} and @code{GPGME_KEYLIST_MODE_EXTERN}, which +results in a @code{--locate-keys} for @code{GPGME_PROTOCOL_OpenPGP}. @item GPGME_KEYLIST_MODE_SIGS The @code{GPGME_KEYLIST_MODE_SIGS} symbol specifies that the key @@ -3078,7 +3104,7 @@ the time when you verified the signature. The string given in @var{value} is passed to the GnuPG engines to request restrictions based on the origin of the request. Valid values are documented in the GnuPG manual and the gpg man page under the -option ``--request-origin''. Requires at least GnuPG 2.2.6 to have an +option @option{--request-origin}. Requires at least GnuPG 2.2.6 to have an effect. @item "no-symkey-cache" @@ -3086,6 +3112,25 @@ For OpenPGP disable the passphrase cache used for symmetrical en- and decryption. This cache is based on the message specific salt value. Requires at least GnuPG 2.2.7 to have an effect. +@item "ignore-mdc-error" +This flag passes the option @option{--ignore-mdc-error} to gpg. This +can be used to force decryption of a message which failed due to a +missing integrity check. This flag must be used with great caution +and only if it is a known non-corrupted old message and the decryption +result of the former try had the decryption result flag +@code{legacy_cipher_nomdc} set. For failsafe reasons this flag is +reset after each operation. + +@item "auto-key-locate" +The string given in @var{value} is passed to gpg. This can be used +to change the behavior of a @code{GPGME_KEYLIST_MODE_LOCATE} keylisting. +Valid values are documented in the GnuPG manual and the gpg man page under +the option @option{--auto-key-locate}. +Requires at least GnuPG 2.1.18. + +Note: Keys retrieved through @code{auto-key-locate} are automatically +imported in the keyring. + @end table This function returns @code{0} on success. @@ -3146,6 +3191,70 @@ The function returns an error if not enough memory is available. @end deftypefun +@node Additional Logs +@subsection Additional Logs +@cindex auditlog, of the engine +@cindex auditlog + +Additional logs can be associated with a context. These logs are +engine specific and can be be obtained with @code{gpgme_op_getauditlog}. + +@deftypefun gpgme_error_t gpgme_op_getauditlog @ + (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{output}}, @ + @w{unsigned int @var{flags}}) +@since{1.1.1} + +The function @code{gpgme_op_getauditlog} is used to obtain additional +logs as specified by @var{flags} into the @var{output} data. If + +The function returns the error code @code{GPG_ERR_NO_ERROR} if a +log could be queried from the engine, and @code{GPG_ERR_NOT_IMPLEMENTED} +if the log specified in @var{flags} is not available for this engine. +If no log is available @code{GPG_ERR_NO_DATA} is returned. + +The value in @var{flags} is a bitwise-or combination of one or +multiple of the following bit values: + +@table @code +@item GPGME_AUDITLOG_DIAG +@since{1.11.2} + +Obtain diagnostic output which would be written to @code{stderr} in +interactive use of the engine. This can be used to provide additional +diagnostic information in case of errors in other operations. + +Note: If log-file has been set in the configuration the log will +be empty and @code{GPG_ERR_NO_DATA} will be returned. + +Implemented for: @code{GPGME_PROTOCOL_OpenPGP} + +@item GPGME_AUDITLOG_DEFAULT +@since{1.11.2} + +This flag has the value 0 for compatibility reasons. Obtains additional +information from the engine by issuing the @code{GETAUDITLOG} command. +For @code{GPGME_PROTOCOL_CMS} this provides additional information about +the X509 certificate chain. + +Implemented for: @code{GPGME_PROTOCOL_CMS} + +@item GPGME_AUDITLOG_HTML +@since{1.1.1} + +Same as @code{GPGME_AUDITLOG_DEFAULT} but in HTML. + +Implemented for: @code{GPGME_PROTOCOL_CMS} +@end table +@end deftypefun + +@deftypefun gpgme_error_t gpgme_op_getauditlog_start @ + (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{output}}, @ + @w{unsigned int @var{flags}}) +@since{1.1.1} + +This is the asynchronous variant of @code{gpgme_op_getauditlog}. +@end deftypefun + @node Key Management @section Key Management @cindex key management @@ -4554,6 +4663,10 @@ If this flag is used with @code{GPGME_EXPORT_MODE_SECRET} for an X.509 key the export format will be changed to PKCS#12 which also includes the certificate. This flag may not be used with OpenPGP. +@item GPGME_EXPORT_MODE_NOUID +@since{1.12.0 - experimental} +Do not export user ids. Works only with certain gpg version. + @end table @@ -5368,7 +5481,7 @@ This is a pointer to a structure used to store the result of a data, you can retrieve the pointer to the result with @code{gpgme_op_decrypt_result}. As with all result structures, it this structure shall be considered read-only and an application must -not allocated such a strucure on its own. The structure contains the +not allocate such a strucure on its own. The structure contains the following members: @table @code @@ -5378,9 +5491,22 @@ algorithm that is not supported. @item unsigned int wrong_key_usage : 1 @since{0.9.0} - This is true if the key was not used according to its policy. +@item unsigned int legacy_cipher_nomdc : 1 +@since{1.11.2} +The message was made by a legacy algorithm without any integrity +protection. This might be an old but legitimate message. + +@item unsigned int is_mime : 1; +@since{1.11.0} +The message claims that the content is a MIME object. + +@item unsigned int is_de_vs : 1; +@since{1.10.0} +The message was encrypted in a VS-NfD compliant way. This is a +specification in Germany for a restricted communication level. + @item gpgme_recipient_t recipients @since{1.1.0} @@ -5408,7 +5534,7 @@ or @code{gpgme_get_ctx_flag (ctx, "export-session-key")} returns true @since{1.11.0} A string with the symmetric encryption algorithm and mode using the -format "<algo>.<mode>". Note that old non-MDC encryption mode of +format "<algo>.<mode>". Note that the deprecated non-MDC encryption mode of OpenPGP is given as "PGPCFB". @end table @@ -5723,7 +5849,15 @@ verification was attempted. @item char *file_name This is the filename of the original plaintext message file if it is -known, otherwise this is a null pointer. +known, otherwise this is a null pointer. Warning: The filename is +not covered by the signature. + +@item unsigned int is_mime : 1; +@since{1.11.0} + +The message claims that the content is a MIME object. Warning: This +flag is not covered by the signature. + @end table @end deftp |