removed all the .cvsignre files - they should be local
[gpgme.git] / doc / gpgme.texi
index e473127..573742f 100644 (file)
@@ -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.
@@ -614,7 +615,11 @@ This value means that there are too many active backend processes.
 This value means that the creation of a pipe failed.
 
 @item GPGME_No_Recipients 
-This value means that no recipients for a message have been set.
+This value means that no valid recipients for a message have been set.
+
+@item GPGME_Invalid_Recipients 
+This value means that some, but not all, recipients for a message have
+been invalid.
 
 @item GPGME_No_Data
 This value means that a @code{GpgmeData} object which was expected to
@@ -681,6 +686,19 @@ The function @code{gpgme_strerror} returns a pointer to a statically
 allocated string containing a description of the error with the error
 value @var{err}.  This string can be used to output a diagnostic
 message to the user.
+
+The following example illustrates the use of @code{gpgme_strerror}:
+
+@example
+GpgmeCtx ctx;
+GpgmeError err = gpgme_new (&ctx);
+if (err)
+  @{
+    fprintf (stderr, "%s: creating GpgME context failed: %s\n",
+             argv[0], gpgme_strerror (err));
+    exit (1);
+  @}
+@end example
 @end deftypefun
 
 
@@ -774,7 +792,6 @@ exactly one of @var{filename} and @var{fp} is not a valid pointer,
 @code{GPGME_Out_Of_Core} if not enough memory is available.
 @end deftypefun
 
-
 @deftypefun GpgmeError gpgme_data_new_with_read_cb (@w{GpgmeData *@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}})
 The function @code{gpgme_data_new_with_read_cb} creates a new
 @code{GpgmeData} object and uses the callback function @var{readfunc}
@@ -961,6 +978,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 +1042,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 +1056,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
@@ -1042,15 +1099,47 @@ valid pointer.
 
 @deftypefun void gpgme_set_keylist_mode (@w{GpgmeCtx @var{ctx}}, @w{int @var{mode}})
 The function @code{gpgme_set_keylist_mode} changes the default
-behaviour of the key listing functions.  Defined values for @var{mode}
-are:
+behaviour of the key listing functions.  The value in @var{mode} is a
+bitwise-or combination of one or multiple of the following bit values:
 
 @table @code
-@item 0
-Normal listing.
-@item 1
-Fast listing without information about the key validity.
+@item GPGME_KEYLIST_MODE_LOCAL
+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.
+
+@item GPGME_KEYLIST_MODE_EXTERN
+The @code{GPGME_KEYLIST_MODE_EXTERN} symbol specifies that an external
+source should be should be searched for keys in the keylisting
+operation.  The type of external source is dependant on the crypto
+engine used.  For example, it can be a remote keyserver or LDAP
+certificate server.
 @end table
+
+At least one of @code{GPGME_KEYLIST_MODE_LOCAL} and
+@code{GPGME_KEYLIST_MODE_EXTERN} must be specified.  For future binary
+compatibility, you should get the current mode with
+@code{gpgme_get_keylist_mode} and modify it by setting or clearing the
+appropriate bits, and then using that calulcated value in the
+@code{gpgme_set_keylisting_mode} operation.  This will leave all other
+bits in the mode value intact (in particular those that are not used
+in the current version of the library).
+
+The function returns @code{GPGME_No_Error} if the mode could be set
+correctly, and @code{GPGME_Invalid_Value} if @var{ctx} is not a valid
+pointer or @var{mode} is not a valid mode.
+@end deftypefun
+
+
+@deftypefun int gpgme_get_keylist_mode (@w{GpgmeCtx @var{ctx}})
+The function @code{gpgme_get_keylist_mode} returns the current key
+listing mode of the context @var{ctx}.  This value can then be
+modified and used in a subsequent @code{gpgme_set_keylist_mode}
+operation to only affect the desired bits (and leave all others
+intact).
+
+The function returns 0 if @var{ctx} is not a valid pointer, and the
+current mode otherwise.  Note that 0 is not a valid mode value.
 @end deftypefun
 
 
@@ -1184,6 +1273,31 @@ valid pointer, and passes through any errors that are reported by the
 crypto engine support routines.
 @end deftypefun
 
+@deftypefun GpgmeError gpgme_op_keylist_ext_start (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{pattern}[]}, @w{int @var{secret_only}}, @w{int @var{reserved}})
+The function @code{gpgme_op_keylist_ext_start} initiates an extended
+key listing operation inside the context @var{ctx}.  It sets
+everything up so that subsequent invocations of
+@code{gpgme_op_keylist_next} return the keys in the list.
+
+If @var{pattern} or @var{*pattern} is @code{NULL}, all available keys
+are returned.  Otherwise, @var{pattern} is a @code{NULL} terminated
+array of strings that are used to limit the list to all keys matching
+at least one of the patterns verbatim.
+
+If @var{secret_only} is not @code{0}, the list is restricted to secret
+keys only.
+
+The value of @var{reserved} must be @code{0}.
+
+The context will be busy until either all keys are received (and
+@code{gpgme_op_keylist_next} returns @code{GPGME_EOF}), or
+@code{gpgme_op_keylist_end} is called to finish the operation.
+
+The function returns @code{GPGME_Invalid_Value} if @var{ctx} is not a
+valid pointer, and passes through any errors that are reported by the
+crypto engine support routines.
+@end deftypefun
+
 @deftypefun GpgmeError gpgme_op_keylist_next (@w{GpgmeCtx @var{ctx}}, @w{GpgmeKey *@var{r_key}})
 The function @code{gpgme_op_keylist_next} returns the next key in the
 list created by a previous @code{gpgme_op_keylist_start} operation in
@@ -1212,6 +1326,35 @@ operation, @code{GPGME_Out_Of_Core} if at some time during the
 operation there was not enough memory available.
 @end deftypefun
 
+The following example illustrates how all keys containing a certain
+string (@code{g10code}) can be listed with their key ID and the name
+and e-mail address of the main user ID:
+
+@example
+GpgmeCtx ctx;
+GpgmeError err = gpgme_new (&ctx);
+
+if (!err)
+  @{
+    err = gpgme_op_keylist_start (ctx, "g10code", 0);
+    while (!err && (err = gpgme_op_keylist_next (ctx, &key)) != GPGME_EOF)
+      @{
+        printf ("%s: %s <%s>\n",
+                gpgme_key_get_string_attr (key, GPGME_ATTR_KEYID, 0, 0),
+               gpgme_key_get_string_attr (key, GPGME_ATTR_NAME, 0, 0),
+               gpgme_key_get_string_attr (key, GPGME_ATTR_EMAIL, 0, 0));
+        gpgme_key_release (key);
+      @}
+    gpgme_release (ctx);
+  @}
+if (err)
+  @{
+    fprintf (stderr, "%s: can not list keys: %s\n",
+             argv[0], gpgme_strerror (err));
+    exit (1);
+  @}
+@end example
+
 
 @node Information About Keys
 @subsection Information About Keys
@@ -1256,7 +1399,8 @@ This is the timestamp at creation time of a sub key.  It is
 representable as a number.
 
 @item GPGME_ATTR_EXPIRE
-XXX FIXME
+This is the expiration time of a sub key.  It is representable as a
+number.
 
 @item GPGME_ATTR_OTRUST
 XXX FIXME  (also for trust items)
@@ -1305,7 +1449,7 @@ This is the type of a trust item.
 @item GPGME_ATTR_IS_SECRET
 This specifies if the key is a secret key.  It is representable as a
 string or a number.  If the key is a secret key, the representation is
-``1'' or @code{1}, otherwise it is NULL or @code{0}.
+``1'' or @code{1}, otherwise it is @code{NULL} or @code{0}.
 
 @item GPGME_ATTR_KEY_REVOKED
 This specifies if a sub key is revoked.  It is representable as a
@@ -1436,11 +1580,19 @@ The function @code{gpgme_op_genkey} generates a new key pair in the
 context @var{ctx} and puts it into the standard key ring if both
 @var{pubkey} and @var{seckey} are @code{NULL}.  In this case the
 function returns immediately after starting the operation, and does
-not wait for it to complete.  @var{pubkey} and @var{seckey} are
-reserved for later use and should be @code{NULL}.  (The function
-should return the public key in the data buffer @var{pubkey} and the
-secret key in the data buffer @var{seckey}, but this is not
-implemented yet).
+not wait for it to complete.  If @var{pubkey} is not @code{NULL} it
+should be the handle for an empty (newly created) data object, and
+upon successful completion the data object will contain the public
+key.  If @var{seckey} is not @code{NULL} it should be the handle for
+an empty (newly created) data object, and upon successful completion
+the data object will contain the secret key.
+
+Note that not all crypto engines support this interface equally.
+GnuPG does not support @var{pubkey} and @var{subkey}, they should be
+both @code{NULL}, and the key pair will be added to the standard key
+ring.  GpgSM does only support @var{pubkey}, the secret key will be
+stored by @command{gpg-agent}.  GpgSM expects @var{pubkey} being not
+@code{NULL}.
 
 The argument @var{parms} specifies parameters for the key in an XML
 string.  The details about the format of @var{parms} are specific to
@@ -1448,8 +1600,6 @@ the crypto engine used by @var{ctx}.  Here is an example for GnuPG as
 the crypto engine:
 
 @example
-<literal>
-<![CDATA[
 <GnupgKeyParms format="internal">
 Key-Type: DSA
 Key-Length: 1024
@@ -1461,8 +1611,16 @@ Name-Email: joe@@foo.bar
 Expire-Date: 0
 Passphrase: abc
 </GnupgKeyParms>
-]]>
-</literal>
+@end example
+
+Here is an example for GpgSM as the crypto engine:
+@example
+<GnupgKeyParms format="internal">
+Key-Type: RSA
+Key-Length: 1024
+Name-DN: C=de,O=g10 code,OU=Testlab,CN=Joe 2 Tester
+Name-Email: joe@@foo.bar
+</GnupgKeyParms>
 @end example
 
 Strings should be given in UTF-8 encoding.  The only format supported
@@ -1472,8 +1630,9 @@ allowed.
 
 The function returns @code{GPGME_No_Error} if the operation could be
 started successfully, @code{GPGME_Invalid_Value} if @var{parms} is not
-a valid XML string, and @code{GPGME_Not_Supported} if @var{pubkey} or
-@var{seckey} is not @code{NULL}.
+a valid XML string, @code{GPGME_Not_Supported} if @var{pubkey} or
+@var{seckey} is not valid, and @code{GPGME_General_Error} if no key
+was created by the backend.
 @end deftypefun
 
 @deftypefun GpgmeError gpgme_op_genkey_start (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{parms}}, @w{GpgmeData @var{pubkey}}, @w{GpgmeData @var{seckey}})
@@ -1529,6 +1688,9 @@ The function @code{gpgme_op_import} adds the keys in the data buffer
 The format of @var{keydata} can be @var{ASCII} armored, for example,
 but the details are specific to the crypto engine.
 
+More information about the import is available with
+@code{gpgme_get_op_info}.  @xref{Detailed Results}.
+
 The function returns @code{GPGME_No_Error} if the import was completed
 successfully, @code{GPGME_Invalid_Value} if @var{keydata} if @var{ctx}
 or @var{keydata} is not a valid pointer, and @code{GPGME_No_Data} if
@@ -1559,8 +1721,10 @@ key ring of the crypto engine used by @var{ctx}.  If
 otherwise secret keys are deleted as well.
 
 The function returns @code{GPGME_No_Error} if the key was deleted
-successfully, and @code{GPGME_Invalid_Value} if @var{ctx} or @var{key}
-is not a valid pointer.
+successfully, @code{GPGME_Invalid_Value} if @var{ctx} or @var{key} is
+not a valid pointer, @code{GPGME_Invalid_Key} if @var{key} could not
+be found in the keyring, and @code{GPGME_Conflict} if the secret key
+for @var{key} is available, but @var{allow_secret} is zero.
 @end deftypefun
 
 @deftypefun GpgmeError gpgme_op_delete_start (@w{GpgmeCtx @var{ctx}}, @w{const GpgmeKey @var{key}}, @w{int @var{allow_secret}})
@@ -1785,9 +1949,14 @@ have a different status.  You can get each key's status with
 @end deftp
 
 @deftypefun GpgmeError gpgme_op_verify (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{sig}}, @w{GpgmeData @var{plain}}, @w{GpgmeSigStat *@var{r_stat}})
-The function @code{gpgme_op_verify} verifies that the detached
-signature in the data object @var{sig} is a valid signature for the
-plaintext in the data object @var{plain}.
+The function @code{gpgme_op_verify} verifies that the signature in the
+data object @var{sig} is a valid signature.  If @var{plain} is
+initialized with plaintext data, it is assumed that @var{sig} is a
+detached signature, and its validity for the plaintext given in
+@var{plain} is verified.  If @var{plain} is an uninitialized data
+object, it is assumed that @var{sig} is a normal (or cleartext)
+signature, and the plaintext is available in @var{plain} after
+successful verification.
 
 The combined status of all signatures is returned in @var{r_stat}.
 The results of the individual signature verifications can be retrieved
@@ -1796,9 +1965,9 @@ with @code{gpgme_get_sig_status} and @code{gpgme_get_sig_key}.
 The function returns @code{GPGME_No_Error} if the operation could be
 completed successfully, @code{GPGME_Invalid_Value} if @var{ctx},
 @var{sig}, @var{plain} or @var{r_stat} is not a valid pointer,
-@code{GPGME_No_Data} if @var{sig} or @var{plain} does not contain any
-data to verify, and passes through any errors that are reported by the
-crypto engine support routines.
+@code{GPGME_No_Data} if @var{sig} does not contain any data to verify,
+and passes through any errors that are reported by the crypto engine
+support routines.
 @end deftypefun
 
 @deftypefun GpgmeError gpgme_op_verify_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{sig}}, @w{GpgmeData @var{plain}})
@@ -1984,6 +2153,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}
@@ -2104,22 +2277,33 @@ The function @code{gpgme_recipients_enum_close} releases the iterator
 @subsubsection Encrypting a Plaintext
 
 @deftypefun GpgmeError gpgme_op_encrypt (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{rset}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{cipher}})
-The function @code{gpgme_op_crypt} encrypts the plaintext in the data
+The function @code{gpgme_op_encrypt} encrypts the plaintext in the data
 object @var{plain} for the recipients @var{rset} and stores the
 ciphertext in the data object @var{cipher}.  The type of the
 ciphertext created is determined by the @acronym{ASCII} armor and text
 mode attributes set for the context @var{ctx}.
 
-More information about the encrypted text is available with
+If @code{GPGME_Invalid_Recipients} is returned, some recipients in
+@var{rset} are invalid, but not all.  In this case the plaintext is
+encrypted for all valid recipients and returned in @var{cipher}.  More
+information about the invalid recipients is available with
 @code{gpgme_get_op_info}.  @xref{Detailed Results}.
 
+If @var{recp} is @code{NULL}, symmetric rather than public key
+encryption is performed.  Symmetrically encrypted cipher text can be
+deciphered with @code{gpgme_op_decrypt}.  Note that in this case the
+crypto backend needs to retrieve a passphrase from the user.
+Symmetric encryption is currently only supported for the OpenPGP
+crypto backend.
+
 The function returns @code{GPGME_No_Error} if the ciphertext could be
 created successfully, @code{GPGME_Invalid_Value} if @var{ctx},
 @var{rset}, @var{plain} or @var{cipher} is not a valid pointer,
-@code{GPGME_No_Recipient} if @var{rset} does not contain any
-valid recipients, @code{GPGME_No_Passphrase} if the passphrase for the
-secret key could not be retrieved, and passes through any errors that
-are reported by the crypto engine support routines.
+@code{GPGME_No_Recipients} if @var{rset} does not contain any valid
+recipients, @code{GPGME_Invalid_Recipients} if @var{rset} contains
+some invalid recipients, @code{GPGME_No_Passphrase} if the passphrase
+for the secret key could not be retrieved, and passes through any
+errors that are reported by the crypto engine support routines.
 @end deftypefun
 
 @deftypefun GpgmeError gpgme_op_encrypt_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{rset}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{cipher}})
@@ -2130,7 +2314,31 @@ The function @code{gpgme_op_encrypt_start} initiates a
 The function returns @code{GPGME_No_Error} if the operation could be
 started successfully, @code{GPGME_Invalid_Value} if @var{ctx},
 @var{rset}, @var{plain} or @var{cipher} is not a valid pointer, and
-@code{GPGME_No_Recipient} if @var{rset} does not contain any valid
+@code{GPGME_No_Recipients} if @var{rset} does not contain any valid
+recipients.
+@end deftypefun
+
+
+@deftypefun GpgmeError gpgme_op_encrypt_sign (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{rset}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{cipher}})
+The function @code{gpgme_op_encrypt_sign} does a combined encrypt and
+sign operation.  It is used like @code{gpgme_op_encrypt}, but the
+ciphertext also contains signatures for the signers listed in
+@var{ctx}.
+
+The combined encrypt and sign operation is currently only available
+for the OpenPGP crypto engine.
+@end deftypefun
+
+@deftypefun GpgmeError gpgme_op_encrypt_sign_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{rset}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{cipher}})
+The function @code{gpgme_op_encrypt_sign_start} initiates a
+@code{gpgme_op_encrypt_sign} operation.  It can be completed by
+calling @code{gpgme_wait} on the context.  @xref{Waiting For
+Completion}.
+
+The function returns @code{GPGME_No_Error} if the operation could be
+started successfully, @code{GPGME_Invalid_Value} if @var{ctx},
+@var{rset}, @var{plain} or @var{cipher} is not a valid pointer, and
+@code{GPGME_No_Recipients} if @var{rset} does not contain any valid
 recipients.
 @end deftypefun
 
@@ -2148,8 +2356,6 @@ release the string with @code{free}.
 
 Here is a sample of the information that might be returned:
 @example
-<literal>
-<![CDATA[
 <GnupgOperationInfo>
   <signature>
     <detached/> <!-- or cleartext or standard -->
@@ -2161,12 +2367,10 @@ Here is a sample of the information that might be returned:
     <fpr>121212121212121212</fpr>
   </signature>
 </GnupgOperationInfo>
-]]>
-</literal>
 @end example
 
 Currently, the only operations that return additional information are
-encrypt and sign.  @xref{Encrypt}, @xref{Sign}.
+encrypt, sign and import.  @xref{Encrypt}, @xref{Sign}, @xref(Importing Keys}.
 
 The function returns a string or @code{NULL} if no such data is
 available.
@@ -2195,7 +2399,7 @@ later point.
 @cindex cryptographic operation, wait for
 @cindex wait for completion
 
-@deftypefun GpgmeCtx gpgme_wait (@w{GpgmeCtx @var{ctx}}, @w{int @var{hang}})
+@deftypefun GpgmeCtx gpgme_wait (@w{GpgmeCtx @var{ctx}}, @w{GpgmeError *@var{status}}, @w{int @var{hang}})
 The function @code{gpgme_wait} does continue the pending operation
 within the context @var{ctx}.  In particular, it ensures the data
 exchange between @acronym{GPGME} and the crypto backend and watches
@@ -2205,7 +2409,14 @@ If @var{hang} is true, the function does not return until the
 operation is completed or cancelled.  Otherwise the function will not
 block for a long time.
 
-The function returns @var{ctx}.
+The error status of the finished operation is returned in
+@var{status}.
+
+The @var{ctx} argument can be @code{NULL}.  In that case,
+@code{gpgme_wait} waits for any context to complete its operation.
+
+The function returns the @var{ctx} of the context which has finished
+the operation.
 @end deftypefun
 
 
@@ -2268,5 +2479,3 @@ registered yet.
 @summarycontents
 @contents
 @bye
-
-@c  LocalWords:  GPGME gpgme