doc/

2003-04-28  Marcus Brinkmann  <[email protected]>

	* gpgme.texi (Verify): Rewritten to take into account new and
	deprecated functions and data types.

gpgme/
2003-04-28  Marcus Brinkmann  <[email protected]>

	* gpgme.h (struct _gpgme_sig_notation): New structure.
	(GpgmeSigNotation): New type.
	(struct _gpgme_signature): New structure.
	(GpgmeSignature): New type.
	(struct _gpgme_op_verify_result): New structure.
	(GpgmeVerifyResult): New type.
	(gpgme_op_verify_result): New prototype.
	(gpgme_get_notation): Remove prototype.
	* ops.h (_gpgme_op_verify_init_result): New prototype.
	(_gpgme_verify_status_handler): Change first argument to void *.
	* util.h (_gpgme_decode_percent_string, _gpgme_map_gnupg_error):
	New prototypes.
	* conversion.c (_gpgme_decode_percent_string): New function.
	(gnupg_errors): New static global.
	(_gpgme_map_gnupg_error): New function.
	* gpgme.c (gpgme_release): Don't release CTX->notation.
	(gpgme_get_notation): Remove function.
	* decrypt-verify.c (_gpgme_op_decrypt_verify_start): Call
	_gpgme_op_verify_init_result.
	* verify.c: Do not include <stdio.h>, <assert.h> and "key.h", but
	do include "gpgme.h".
	(struct verify_result): Replace with ...
	(op_data_t): ... this type.
	(release_verify_result): Remove function.
	(release_op_data): New function.
	(is_token): Remove function.
	(skip_token): Remove function.
	(copy_token): Remove function.
	(gpgme_op_verify_result): New function.
	(calc_sig_summary): Rewritten.
	(finish_sig): Remove function.
	(parse_new_sig): New function.
	(parse_valid_sig): New function.
	(parse_notation): New function.
	(parse_trust): New function.
	(parse_error): New function.
	(_gpgme_verify_status_handler): Rewritten.  Change first argument
	to void *.
	(_gpgme_op_verify_start): Rework error handling.  Call
	_gpgme_op_verify_init_result.
	(gpgme_op_verify): Do not release or clear CTX->notation.
	(gpgme_get_sig_status): Rewritten.
	(gpgme_get_sig_string_attr): Likewise.
	(gpgme_get_sig_ulong_attr): Likewise.
	(gpgme_get_sig_key): Likewise.

2 files changed, 329 insertions, 139 deletions

diff --git a/doc/ChangeLog b/doc/ChangeLog
index 778625e4..653c216b 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,5 +1,8 @@
 2003-04-28  Marcus Brinkmann  <[email protected]>
 
+	* gpgme.texi (Verify): Rewritten to take into account new and
+	deprecated functions and data types.
+
 	* gpgme.texi (Decrypt): Descript gpgme_op_decrypt_result and
 	GpgmeDecryptResult.
 
diff --git a/doc/gpgme.texi b/doc/gpgme.texi
index 4e15fa07..a05a0e64 100644
--- a/doc/gpgme.texi
+++ b/doc/gpgme.texi
@@ -2805,56 +2805,6 @@ next operation is started on the context.
 @cindex signature, verification
 @cindex cryptographic operation, verification
 @cindex cryptographic operation, signature check
-@cindex signature, status
-
-@deftp {Data type} {enum GpgmeSigStat}
-@tindex GpgmeSigStat
-The @code{GpgmeSigStat} type holds the result of a signature check, or
-the combined result of all signatures.  The following results are
-possible:
-
-@table @code
-@item GPGME_SIG_STAT_NONE
-This status should not occur in normal operation.
-
-@item GPGME_SIG_STAT_GOOD
-This status indicates that the signature is valid.  For the combined
-result this status means that all signatures are valid.
-
-@item GPGME_SIG_STAT_GOOD_EXP
-This status indicates that the signature is valid but expired.  For
-the combined result this status means that all signatures are valid
-and expired.
-
-@item GPGME_SIG_STAT_GOOD_EXPKEY
-This status indicates that the signature is valid but the key used to
-verify the signature has expired.  For the combined result this status
-means that all signatures are valid and all keys are expired.
-
-@item GPGME_SIG_STAT_BAD
-This status indicates that the signature is invalid.  For the combined
-result this status means that all signatures are invalid.
-
-@item GPGME_SIG_STAT_NOKEY
-This status indicates that the signature could not be verified due to
-a missing key.  For the combined result this status means that all
-signatures could not be checked due to missing keys.
-
-@item GPGME_SIG_STAT_NOSIG
-This status indicates that the signature data provided was not a real
-signature.
-
-@item GPGME_SIG_STAT_ERROR
-This status indicates that there was some other error which prevented
-the signature verification.
-
-@item GPGME_SIG_STAT_DIFF
-For the combined result this status means that at least two signatures
-have a different status.  You can get each key's status with
-@code{gpgme_get_sig_status}.
-@end table
-@end deftp
-
 
 @deftypefun GpgmeError gpgme_op_verify (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{sig}}, @w{GpgmeData @var{signed_text}}, @w{GpgmeData @var{plain}})
 The function @code{gpgme_op_verify} verifies that the signature in the
@@ -2867,7 +2817,7 @@ writable data object that will contain the plaintext after successful
 verification.
 
 The results of the individual signature verifications can be retrieved
-with @code{gpgme_get_sig_status} and @code{gpgme_get_sig_key}.
+with @code{gpgme_op_verify_result}.
 
 The function returns @code{GPGME_No_Error} if the operation could be
 completed successfully, @code{GPGME_Invalid_Value} if @var{ctx},
@@ -2889,76 +2839,41 @@ started successfully, @code{GPGME_Invalid_Value} if @var{ctx},
 data to verify.
 @end deftypefun
 
-@deftypefun {const char *} gpgme_get_sig_status (@w{GpgmeCtx @var{ctx}}, @w{int @var{idx}}, @w{GpgmeSigStat *@var{r_stat}}, @w{time_t *@var{r_created}})
-The function @code{gpgme_get_sig_status} receives information about a
-signature after the @code{gpgme_op_verify} or
-@code{gpgme_op_verify_decrypt} operation.  A single detached signature
-can contain signatures by more than one key.  The @var{idx} specifies
-which signature's information should be retrieved, starting from
-@var{0}.
-
-The status of the signature will be returned in @var{r_stat} if it is
-not @code{NULL}.  The creation time stamp of the signature will be
-returned in @var{r_created} if it is not @var{NULL}.
-
-The function returns a statically allocated string that contains the
-fingerprint of the key which signed the plaintext, or @code{NULL} if
-@var{ctx} is not a valid pointer, the operation is still pending, or
-no verification could be performed.
-@end deftypefun
-
-@deftypefun {const char *} gpgme_get_sig_string_attr (@w{GpgmeCtx @var{ctx}}, @w{int @var{idx}}, @w{GpgmeAttr @var{what}}, @w{int @var{whatidx}})
-This function is similar to @code{gpgme_get_sig_status} but may be used
-to retrieve more detailed information.  @var{ctx} should be the context
-used for the last signature verification, @var{idx} is used to enumerate
-over all signatures starting with @code{0} and @var{whatidx} should be
-@code{0} unless otherwise stated.
+@deftp {Data type} {GpgmeSigNotation}
+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
+following members:
 
-The following values may be used for @var{what}:
 @table @code
-@item GPGME_ATTR_FPR
-Return the fingerprint of the key used to create the signature.
+@item GpgmeSigNotation next
+This is a pointer to the next new signature notation structure in the
+linked list, or @code{NULL} if this is the last element.
 
-@item GPGME_ATTR_ERRTOK
-Return a token with a more detailed error description.  A @var{whatidx}
-of @code{0} returns an error token associated with validity calculation,
-a value of @code{1} return an error token related to the certificate
-checking.
+@item char *name
+The name of the notation field.  If this is @code{NULL}, then the
+member @code{value} will contain a policy URL.
 
+@item char *value
+The value of the notation field.  If @code{name} is @code{NULL}, then
+this is a policy URL.
 @end table
-@end deftypefun
-
-@deftypefun {const char *} gpgme_get_sig_ulong_attr (@w{GpgmeCtx @var{ctx}}, @w{int @var{idx}}, @w{GpgmeAttr @var{waht}}, @w{int @var{whatidx}})
-This function is similar to @code{gpgme_get_sig_string_attr} but used
-for attributes which can be represented by an @code{unsigned long} data
-type.  @var{ctx} should be the context used for the last signature
-verification, @var{idx} is used to enumerate over all signatures
-starting with @code{0} and @var{whatidx} should be @code{0} unless
-otherwise stated.
-
-The following values may be used for @var{what}:
-@table @code
-@item GPGME_ATTR_CREATED
-Return the creation time of the signature in seconds since Epoch.  This
-is the same value as returned by @code{gpgme_get_sig_status}.
-
-@item GPGME_ATTR_EXPIRE
-Return the expiration time of the signature in seconds since Epoch. 
+@end deftp
 
-@item GPGME_ATTR_VALIDITY
-Returns the validity of the key used to create the signature.  This is a
-shortcut function which avoids an extra key lookup.  The value returned
-is one of @code{GPGME_VALIDITY_UNKNOWN}, @code{GPGME_VALIDITY_NEVER},
-@code{GPGME_VALIDITY_MARGINAL} or @code{GPGME_VALIDITY_FULL}.
+@deftp {Data type} {GpgmeSignature}
+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
+following members:
 
-@item GPGME_ATTR_SIG_STATUS
-This is the same value as returned by @code{gpgme_get_sig_status}.
+@table @code
+@item GpgmeSignature next
+This is a pointer to the next new signature structure in the linked
+list, or @code{NULL} if this is the last element.
 
-@item GPGME_ATTR_SIG_SUMMARY
-This returns a bit vector giving a summary of the signature status.
-Itprovides an easy interface to a defined semantic of the signature
-status.  Checking just one bit is sufficient to see whether a signature
-is valid without any restrictions.
+@item unsigned int summary;
+This is a bit vector giving a summary of the signature status.  It
+provides an easy interface to a defined semantic of the signature
+status.  Checking just one bit is sufficient to see whether a
+signature is valid without any restrictions.
 
 The defined bits are:
   @table @code
@@ -2999,44 +2914,316 @@ The defined bits are:
 
   @item GPGME_SIGSUM_SYS_ERROR
   A system error occured. 
+  @end table
+
+@item char *fpr
+This is the fingerprint or key ID of the signature.
 
+@item GpgmeError status
+This is the status of the signature.  In particular, the following
+status codes are of interest:
+
+  @table @code
+  @item GPGME_No_Error
+  This status indicates that the signature is valid.  For the combined
+  result this status means that all signatures are valid.
+
+  @item GPGME_Sig_Expired
+  This status indicates that the signature is valid but expired.  For
+  the combined result this status means that all signatures are valid
+  and expired.
+
+  @item GPGME_Key_Expired
+  This status indicates that the signature is valid but the key used to
+  verify the signature has expired.  For the combined result this status
+  means that all signatures are valid and all keys are expired.
+
+  @item GPGME_Bad_Signature
+  This status indicates that the signature is invalid.  For the combined
+  result this status means that all signatures are invalid.
+
+  @item GPGME_No_Public_Key
+  This status indicates that the signature could not be verified due to
+  a missing key.  For the combined result this status means that all
+  signatures could not be checked due to missing keys.
+
+  @item GPGME_General_Error
+  This status indicates that there was some other error which prevented
+  the signature verification.
   @end table
 
+@item GpgmeSigNotation notations
+This is a linked list with the notation data and policy URLs.
+
+@item unsigned long timestamp
+The creation timestamp of this signature.
+
+@item unsigned long exp_timestamp
+The expiration timestamp of this signature, or 0 if the signature does
+not expire.
+
+@item int wrong_key_usage : 1;
+
+@item GpgmeValidity validity
+
+@item GpgmeError validity_reason
 @end table
+@end deftp
+
+@deftp {Data type} {GpgmeVerifyResult}
+This is a pointer to a structure used to store the result of a
+@code{gpgme_op_verify} operation.  After successfully verifying a
+signature, you can retrieve the pointer to the result with
+@code{gpgme_op_verify_result}.  The structure contains the following
+member:
+
+@table @code
+@item GpgmeSignature signatures
+A linked list with information about all signatures for which a
+verification was attempted.
+@end table
+@end deftp
+
+@deftypefun GpgmeSignResult gpgme_op_verify_result (@w{GpgmeCtx @var{ctx}})
+The function @code{gpgme_op_verify_result} returns a
+@code{GpgmeVerifyResult} pointer to a structure holding the result of
+a @code{gpgme_op_verify} operation.  The pointer is only valid if the
+last operation on the context was a @code{gpgme_op_verify} or
+@code{gpgme_op_verify_start} operation, and if this operation finished
+successfully.  The returned pointer is only valid until the next
+operation is started on the context.
 @end deftypefun
 
 
-@deftypefun {const char *} gpgme_get_sig_key (@w{GpgmeCtx @var{ctx}}, @w{int @var{idx}}, @w{GpgmeKey *@var{r_key}})
-The function @code{gpgme_get_sig_status} receives a @code{GpgmeKey}
-object for the key which was used to verify the signature after the
-@code{gpgme_op_verify} or @code{gpgme_op_verify_decrypt} operation.  A
-single detached signature can contain signatures by more than one key.
-The @var{idx} specifies which signature's information should be
-retrieved, starting from @var{0}.  The key will have on reference for
-the user.
+The following interfaces are deprecated and only provided for backward
+compatibility.  Don't use them.  They will be removed in a future
+version of @acronym{GPGME}.
 
-The function is a convenient way to retrieve the keys belonging to the
-fingerprints returned by @code{gpgme_get_sig_status}.
+@deftp {Data type} {enum GpgmeSigStat}
+@tindex GpgmeSigStat
+The @code{GpgmeSigStat} type holds the result of a signature check, or
+the combined result of all signatures.  The following results are
+possible:
 
-The function returns @code{GPGME_No_Error} if the key could be
-returned, @code{GPGME_Invalid_Value} if @var{r_key} is not a valid
-pointer, @code{GPGME_Invalid_Key} if the fingerprint is not valid,
-@code{GPGME_EOF} if @var{idx} is too large, or some other error value
-if a problem occurred requesting the key.
+@table @code
+@item GPGME_SIG_STAT_NONE
+This status should not occur in normal operation.
+
+@item GPGME_SIG_STAT_GOOD
+This status indicates that the signature is valid.  For the combined
+result this status means that all signatures are valid.
+
+@item GPGME_SIG_STAT_GOOD_EXP
+This status indicates that the signature is valid but expired.  For
+the combined result this status means that all signatures are valid
+and expired.
+
+@item GPGME_SIG_STAT_GOOD_EXPKEY
+This status indicates that the signature is valid but the key used to
+verify the signature has expired.  For the combined result this status
+means that all signatures are valid and all keys are expired.
+
+@item GPGME_SIG_STAT_BAD
+This status indicates that the signature is invalid.  For the combined
+result this status means that all signatures are invalid.
+
+@item GPGME_SIG_STAT_NOKEY
+This status indicates that the signature could not be verified due to
+a missing key.  For the combined result this status means that all
+signatures could not be checked due to missing keys.
+
+@item GPGME_SIG_STAT_NOSIG
+This status indicates that the signature data provided was not a real
+signature.
+
+@item GPGME_SIG_STAT_ERROR
+This status indicates that there was some other error which prevented
+the signature verification.
+
+@item GPGME_SIG_STAT_DIFF
+For the combined result this status means that at least two signatures
+have a different status.  You can get each key's status with
+@code{gpgme_get_sig_status}.
+@end table
+@end deftp
+
+@deftypefun {const char *} gpgme_get_sig_status (@w{GpgmeCtx @var{ctx}}, @w{int @var{idx}}, @w{GpgmeSigStat *@var{r_stat}}, @w{time_t *@var{r_created}})
+The function @code{gpgme_get_sig_status} is equivalent to:
+ 
+@example
+  GpgmeVerifyResult result;
+  GpgmeSignature sig;
+
+  result = gpgme_op_verify_result (ctx);
+  sig = result->signatures;
+
+  while (sig && idx)
+    @{
+      sig = sig->next;
+      idx--;
+    @}
+  if (!sig || idx)
+    return NULL;
+
+  if (r_stat)
+    @{
+      switch (sig->status)
+	@{
+	case GPGME_No_Error:
+	  *r_stat = GPGME_SIG_STAT_GOOD;
+	  break;
+	  
+	case GPGME_Bad_Signature:
+	  *r_stat = GPGME_SIG_STAT_BAD;
+	  break;
+	  
+	case GPGME_No_Public_Key:
+	  *r_stat = GPGME_SIG_STAT_NOKEY;
+	  break;
+	  
+	case GPGME_No_Data:
+	  *r_stat = GPGME_SIG_STAT_NOSIG;
+	  break;
+	  
+	case GPGME_Sig_Expired:
+	  *r_stat = GPGME_SIG_STAT_GOOD_EXP;
+	  break;
+	  
+	case GPGME_Key_Expired:
+	  *r_stat = GPGME_SIG_STAT_GOOD_EXPKEY;
+	  break;
+	  
+	default:
+	  *r_stat = GPGME_SIG_STAT_ERROR;
+	  break;
+	@}
+    @}
+  if (r_created)
+    *r_created = sig->timestamp;
+  return sig->fpr;
+@end example
+@end deftypefun
+
+@deftypefun {const char *} gpgme_get_sig_string_attr (@w{GpgmeCtx @var{ctx}}, @w{int @var{idx}}, @w{GpgmeAttr @var{what}}, @w{int @var{whatidx}})
+The function @code{gpgme_get_sig_string_attr} is equivalent to:
+ 
+@example
+  GpgmeVerifyResult result;
+  GpgmeSignature sig;
+
+  result = gpgme_op_verify_result (ctx);
+  sig = result->signatures;
+
+  while (sig && idx)
+    @{
+      sig = sig->next;
+      idx--;
+    @}
+  if (!sig || idx)
+    return NULL;
+
+  switch (what)
+    @{
+    case GPGME_ATTR_FPR:
+      return sig->fpr;
+
+    case GPGME_ATTR_ERRTOK:
+      if (whatidx == 1)
+        return sig->wrong_key_usage ? "Wrong_Key_Usage" : "";
+      else
+	return "";
+    default:
+      break;
+    @}
+
+  return NULL;
+@end example
+@end deftypefun
+
+@deftypefun {const char *} gpgme_get_sig_ulong_attr (@w{GpgmeCtx @var{ctx}}, @w{int @var{idx}}, @w{GpgmeAttr @var{waht}}, @w{int @var{whatidx}})
+The function @code{gpgme_get_sig_ulong_attr} is equivalent to:
+ 
+@example
+  GpgmeVerifyResult result;
+  GpgmeSignature sig;
+
+  result = gpgme_op_verify_result (ctx);
+  sig = result->signatures;
+
+  while (sig && idx)
+    @{
+      sig = sig->next;
+      idx--;
+    @}
+  if (!sig || idx)
+    return 0;
+
+  switch (what)
+    @{
+    case GPGME_ATTR_CREATED:
+      return sig->timestamp;
+
+    case GPGME_ATTR_EXPIRE:
+      return sig->exp_timestamp;
+
+    case GPGME_ATTR_VALIDITY:
+      return (unsigned long) sig->validity;
+
+    case GPGME_ATTR_SIG_STATUS:
+      switch (sig->status)
+	@{
+	case GPGME_No_Error:
+	  return GPGME_SIG_STAT_GOOD;
+	  
+	case GPGME_Bad_Signature:
+	  return GPGME_SIG_STAT_BAD;
+	  
+	case GPGME_No_Public_Key:
+	  return GPGME_SIG_STAT_NOKEY;
+	  
+	case GPGME_No_Data:
+	  return GPGME_SIG_STAT_NOSIG;
+	  
+	case GPGME_Sig_Expired:
+	  return GPGME_SIG_STAT_GOOD_EXP;
+	  
+	case GPGME_Key_Expired:
+	  return GPGME_SIG_STAT_GOOD_EXPKEY;
+	  
+	default:
+	  return GPGME_SIG_STAT_ERROR;
+	@}
+
+    case GPGME_ATTR_SIG_SUMMARY:
+      return sig->summary;
+
+    default:
+      break;
+    @}
+  return 0;
+@end example
 @end deftypefun
 
-@deftypefun {char *} gpgme_get_notation (@w{GpgmeCtx @var{ctx}})
-The function @code{gpgme_get_notation} can be used to retrieve
-notation data from the last signature check in the context @var{ctx}.
+@deftypefun {const char *} gpgme_get_sig_key (@w{GpgmeCtx @var{ctx}}, @w{int @var{idx}}, @w{GpgmeKey *@var{r_key}})
+The function @code{gpgme_get_sig_key} is equivalent to:
+
+@example
+  GpgmeVerifyResult result;
+  GpgmeSignature sig;
+
+  result = gpgme_op_verify_result (ctx);
+  sig = result->signatures;
 
-If there is notation data available from the last signature check,
-this function may be used to return this notation data as a string.
-The string is an XML representation of that data embedded in a
-<notation> container.  The user has to release the string with
-@code{free}.
+  while (sig && idx)
+    @{
+      sig = sig->next;
+      idx--;
+    @}
+  if (!sig || idx)
+    return GPGME_EOF;
 
-The function returns a string if the notation data is available or
-@code{NULL} if there is no such data available.
+  return gpgme_get_key (ctx, sig->fpr, r_key, 0, 0);
+@end example
 @end deftypefun
 
 
@@ -3204,7 +3391,7 @@ The hash algorithm used to create this signature.
 @item unsigned long class
 The signature class of this signature.
 
-@item long int created
+@item long int timestamp
 The creation timestamp of this signature.
 
 @item char *fpr