From ab7146aa61f009f51a9bcf5b8855b128aadec55d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ingo=20Kl=C3=B6cker?= Date: Wed, 25 Jan 2023 12:17:05 +0100 Subject: [PATCH] doc: Update NEWS and API documentation -- GnuPG-bug-id: 6342 --- NEWS | 8 ++++-- doc/gpgme.texi | 66 +++++++++++++++++++++++++++++++++++++++++++++----- 2 files changed, 66 insertions(+), 8 deletions(-) diff --git a/NEWS b/NEWS index 824faeb7..365d4f95 100644 --- a/NEWS +++ b/NEWS @@ -11,8 +11,8 @@ Noteworthy changes in version 1.18.1 (unreleased) gpgme_op_sign* to allow creating an encrypted and/or signed archive. [T6342] - * Extended gpgme_op_decrypt* and gpgme_op_decrypt_verify* to allow - extracting an encrypted and/or signed archive. [T6342] + * Extended gpgme_op_decrypt*, gpgme_op_decrypt_verify*, and gpgme_op_verify* + to allow extracting an encrypted and/or signed archive. [T6342] * cpp: Handle error when trying to sign expired keys. [T6155] @@ -36,6 +36,10 @@ Noteworthy changes in version 1.18.1 (unreleased) GPGME_DECRYPT_ARCHIVE NEW. GPGME_ENCRYPT_ARCHIVE NEW. GPGME_SIG_MODE_ARCHIVE NEW. + GPGME_VERIFY_ARCHIVE NEW. + gpgme_verify_flags_t NEW. + gpgme_op_verify_ext_start NEW. + gpgme_op_verify_ext NEW. cpp: GpgGenCardKeyInteractor::Curve NEW. cpp: GpgGenCardKeyInteractor::setCurve NEW. qt: ListAllKeysJob::Option NEW. diff --git a/doc/gpgme.texi b/doc/gpgme.texi index 184b1afe..d7c38f82 100644 --- a/doc/gpgme.texi +++ b/doc/gpgme.texi @@ -5589,12 +5589,6 @@ The function @code{gpgme_op_decrypt} decrypts the ciphertext in the data object @var{cipher} and stores it into the data object @var{plain}. -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 function returns the error code @code{GPG_ERR_NO_ERROR} if the ciphertext could be decrypted successfully, @code{GPG_ERR_INV_VALUE} if @var{ctx}, @var{cipher} or @var{plain} is not a valid pointer, @@ -5628,6 +5622,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: @@ -5824,6 +5824,60 @@ 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. + +@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