2002-12-22 Marcus Brinkmann <marcus@g10code.de>
authorMarcus Brinkmann <mb@g10code.com>
Mon, 23 Dec 2002 17:12:48 +0000 (17:12 +0000)
committerMarcus Brinkmann <mb@g10code.com>
Mon, 23 Dec 2002 17:12:48 +0000 (17:12 +0000)
* gpgme.texi (Key Signatures): New section.
(Listing Keys): Add gpgme_get_key.

doc/ChangeLog
doc/gpgme.texi

index 827edd2..3622567 100644 (file)
@@ -1,3 +1,8 @@
+2002-12-22  Marcus Brinkmann  <marcus@g10code.de>
+
+       * gpgme.texi (Key Signatures): New section.
+       (Listing Keys): Add gpgme_get_key.
+
 2002-12-06  Marcus Brinkmann  <marcus@g10code.de>
 
        * gpgme.texi (Memory Based Data Buffers): New subsection.
@@ -5,7 +10,7 @@
        (Callback Based Data Buffers): Likewise.
        (Manipulating Data Buffers): Update interfaces.  Add
        gpgme_data_seek.
-       * gpgme.texi (Engine Version Check): Remove gpgme_chec_engine.
+       * gpgme.texi (Engine Version Check): Remove gpgme_check_engine.
        
 2002-11-21  Marcus Brinkmann  <marcus@g10code.de>
 
index 6576d61..43d842e 100644 (file)
@@ -155,6 +155,7 @@ Key Management
 
 * Listing Keys::                  Browsing the list of available keys.
 * Information About Keys::        Requesting detailed information about keys.
+* Key Signatures::                Listing the signatures on a key.
 * Manipulating Keys::             Operations on keys.
 * Generating Keys::               Creating new key pairs.
 * Exporting Keys::                Retrieving key data from the key ring.
@@ -1592,6 +1593,7 @@ A key can contain several user IDs and sub keys.
 @menu
 * Listing Keys::                  Browsing the list of available keys.
 * Information About Keys::        Requesting detailed information about keys.
+* Key Signatures::                Listing the signatures on a key.
 * Manipulating Keys::             Operations on keys.
 * Generating Keys::               Creating new key pairs.
 * Exporting Keys::                Retrieving key data from the key ring.
@@ -1712,6 +1714,26 @@ if (err)
   @}
 @end example
 
+In a simple program, for which a blocking operation is acceptable, the
+following function can be used to retrieve a single key.
+
+@deftypefun GpgmeError gpgme_get_key (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{fpr}}, @w{GpgmeKey *@var{r_key}}, @w{int @var{secret}}, @w{int @var{force_update}})
+The function @code{gpgme_get_key} gets the key with the fingerprint
+(or key ID) @var{fpr} from the key cache or from the crypto backend
+and return it in @var{r_key}.  If @var{force_update} is true, force a
+refresh of the key from the crypto backend and replace the key in the
+cache, if any.  If @var{secret} is true, get the secret key.
+
+If the @code{GPGME_KEYLIST_MODE_SIGS} mode is active, the key will be
+retrieved with the key signatures (and updated if necessary).
+
+The function returns @code{GPGME_Invalid_Value} if @var{ctx} or
+@var{r_key} is not a valid pointer, @code{GPGME_Busy} if there is a
+pending operation, @code{GPGME_Invalid_Key} if @var{fpr} is not a
+fingerprint or key ID, @code{GPGME_Out_Of_Core} if at some time during
+the operation there was not enough memory available.
+@end deftypefun
+
 
 @node Information About Keys
 @subsection Information About Keys
@@ -1921,6 +1943,109 @@ or @var{reserved} not @code{NULL}.
 @end deftypefun
 
 
+@node Key Signatures
+@subsection Key Signatures
+@cindex key, signatures
+@cindex signatures, on a key
+
+The signatures on a key are only available if the key was retrieved
+via a listing operation with the @code{GPGME_KEYLIST_MODE_SIGS} mode
+enabled, because it is expensive to retrieve all signatures of a key.
+
+So, before using the below interfaces to retrieve the signatures on a
+key, you have to make sure that the key was listed with signatures
+enabled.  One convenient, but blocking, way to do this is to use the
+function @code{gpgme_get_key}.
+
+@deftp {Data type} GpgmeAttr
+The @code{GpgmeAttr} type is used to specify a key signature
+attribute.  The following attributes are defined:
+
+@table @code
+@item GPGME_ATTR_KEYID
+This is the key ID of the key which was used for the signature.  It is
+representable as a string.
+
+@item GPGME_ATTR_ALGO
+This is the crypto algorithm used to create the signature.  It is
+representable as a string and as a number.  The numbers correspond to
+the @code{enum gcry_pk_algos} values in the gcrypt library.
+
+@item GPGME_ATTR_CREATED
+This is the timestamp at creation time of the signature.  It is
+representable as a number.
+
+@item GPGME_ATTR_EXPIRE
+This is the expiration time of the signature.  It is representable as
+a number.
+
+@item GPGME_ATTR_USERID
+This is the user ID associated with the signing key.  The user ID is
+representable as a number.
+
+@item GPGME_ATTR_NAME
+This is the name belonging to a user ID.  It is representable as a string.
+
+@item GPGME_ATTR_EMAIL
+This is the email address belonging to a user ID.  It is representable
+as a string.
+
+@item GPGME_ATTR_COMMENT
+This is the comment belonging to a user ID.  It is representable as a
+string.
+
+@item GPGME_ATTR_KEY_REVOKED
+This specifies if a key signature is a revocation signature.  It is
+representable as a number, and is @code{1} if the key is revoked, and
+@code{0} otherwise.
+
+@c @item GPGME_ATTR_KEY_EXPIRED
+@c This specifies if a key signature is expired.  It is representable as
+@c a number, and is @code{1} if the key is revoked, and @code{0}
+@c otherwise.
+@c
+@item GPGME_ATTR_SIG_CLASS
+This specifies the signature class of a key signature.  It is
+representable as a number.  The meaning is specific to the crypto
+engine.
+
+@item GPGME_ATTR_SIG_CLASS
+This specifies the signature class of a key signature.  It is
+representable as a number.  The meaning is specific to the crypto
+engine.
+
+@item GPGME_ATTR_SIG_STATUS
+This is the same value as returned by @code{gpgme_get_sig_status}.
+@end table
+@end deftp
+
+@deftypefun {const char *} gpgme_key_sig_get_string_attr (@w{GpgmeKey @var{key}}, @w{int @var{uid_idx}}, @w{GpgmeAttr @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
+The function @code{gpgme_key_sig_get_string_attr} returns the value of
+the string-representable attribute @var{what} of the signature
+@var{idx} on the user ID @var{uid_idx} in the key @var{key}.  The
+argument @var{reserved} is reserved for later use and should be
+@code{NULL}.
+
+The string returned is only valid as long as the key is valid.
+
+The function returns @code{0} if an attribute can't be returned as a
+string, @var{key} is not a valid pointer, @var{uid_idx} or @var{idx}
+out of range, or @var{reserved} not @code{NULL}.
+@end deftypefun
+
+@deftypefun {unsigned long} gpgme_key_sig_get_ulong_attr (@w{GpgmeKey @var{key}}, @w{int @var{uid_idx}}, @w{GpgmeAttr @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
+The function @code{gpgme_key_sig_get_ulong_attr} returns the value of
+the number-representable attribute @var{what} of the signature
+@var{idx} on the user ID @var{uid_idx} in the key @var{key}.  The
+argument @var{reserved} is reserved for later use and should be
+@code{NULL}.
+
+The function returns @code{0} if an attribute can't be returned as a
+string, @var{key} is not a valid pointer, @var{uid_idx} or @var{idx}
+out of range, or @var{reserved} not @code{NULL}.
+@end deftypefun
+
+
 @node Manipulating Keys
 @subsection Manipulating Keys
 @cindex key, manipulation