doc/

2002-02-25  Marcus Brinkmann  <[email protected]>

	* gpgme.texi (Creating a Signature): Add a note about
	certifications to include.
	(Included Certifications): New section.

gpgme/
2002-02-25  Marcus Brinkmann  <[email protected]>

	* context.h (struct gpgme_context_s): New member include_certs.
	* gpgme.h (gpgme_set_include_certs): Add prototype.
	(gpgme_get_include_certs): Likewise.
	* gpgme.c (gpgme_set_include_certs): New function.
	(gpgme_get_include_certs): Likewise.
	(gpgme_new): Set include_certs to 1 (the default).
	* engine.c (_gpgme_engine_op_sign): Accept new argument include_certs,
	and pass it to _gpgme_gpgsm_op_sign.
	* engine.h (_gpgme_engine_op_sign): Likewise for prototype.
	* engine-gpgsm.c (_gpgme_gpgsm_op_sign): Accept new argument
	include_certs and handle it.
	* engine-gpgsm.h (_gpgme_gpgsm_start): Add new argument include_certs.
	* sign.c (gpgme_op_sign_start): Add new argument to
	_gpgme_engine_op_sign call.

1 files changed, 45 insertions, 0 deletions

diff --git a/doc/gpgme.texi b/doc/gpgme.texi
index 777ba223..708110c3 100644
--- a/doc/gpgme.texi
+++ b/doc/gpgme.texi
@@ -138,6 +138,7 @@ Context Attributes
 * Protocol Selection::            Selecting the protocol used by a context.
 * @acronym{ASCII} Armor::                   Requesting @acronym{ASCII} armored output.
 * Text Mode::                     Choosing canonical text mode.
+* Included Certificates::         Including a number of certificates.
 * Key Listing Mode::              Selecting key listing mode.
 * Passphrase Callback::           Getting the passphrase from the user.
 * Progress Meter Callback::       Being informed about the progress.
@@ -961,6 +962,7 @@ The function @code{gpgme_release} destroys the context with the handle
 * Protocol Selection::            Selecting the protocol used by a context.
 * @acronym{ASCII} Armor::                   Requesting @acronym{ASCII} armored output.
 * Text Mode::                     Choosing canonical text mode.
+* Included Certificates::       Including a number of certificates.
 * Key Listing Mode::              Selecting key listing mode.
 * Passphrase Callback::           Getting the passphrase from the user.
 * Progress Meter Callback::       Being informed about the progress.
@@ -1024,6 +1026,9 @@ Text mode is for example used for the RFC2015 signatures; note that
 the updated RFC 3156 mandates that the mail user agent does some
 preparations so that text mode is not needed anymore.
 
+This option is only relevant to the OpenPGP crypto engine, and ignored
+by all other engines.
+
 Canonical text mode is disabled if @var{yes} is zero, and enabled
 otherwise.
 @end deftypefun
@@ -1035,6 +1040,42 @@ valid pointer.
 @end deftypefun
 
 
+@node Included Certificates
+@subsection Included Certificates
+@cindex certificates, included
+
+@deftypefun void gpgme_set_include_certs (@w{GpgmeCtx @var{ctx}}, @w{int @var{nr_of_certs}})
+The function @code{gpgme_set_include_certs} specifies how many
+certificates should be included in an S/MIME signed message.  By
+default, only the sender's certificate is included.  The possible
+values of @var{nr_of_certs} are:
+
+@table @code
+@item -2
+Include all certificates except the root certificate.
+@item -1
+Include all certificates.
+@item 0
+Include no certificates.
+@item 1
+Include the sender's certificate only.
+@item n
+Include the first n certificates of the certificates path, starting
+from the sender's certificate.  The number @code{n} must be positive.
+@end table
+
+Values of @var{nr_of_certs} smaller than -2 are undefined.
+
+This option is only relevant to the CMS crypto engine, and ignored
+by all other engines.
+@end deftypefun
+
+@deftypefun int gpgme_get_include_certs (@w{GpgmeCtx @var{ctx}})
+The function @code{gpgme_get_include_certs} returns the number of
+certificates to include into an S/MIME signed message.
+@end deftypefun
+
+
 @node Key Listing Mode
 @subsection Key Listing Mode
 @cindex key listing mode
@@ -2036,6 +2077,10 @@ the data object @var{plain} and returns it in the data object
 More information about the signatures is available with
 @code{gpgme_get_op_info}.  @xref{Detailed Results}.
 
+If an S/MIME signed message is created using the CMS crypto engine,
+the number of certificates to include in the message can be specified
+with @code{gpgme_set_include_certs}.  @xref{Included Certificates}.
+
 The function returns @code{GPGME_No_Error} if the signature could be
 created successfully, @code{GPGME_Invalid_Value} if @var{ctx},
 @var{plain} or @var{sig} is not a valid pointer, @code{GPGME_No_Data}