glitch in the license text detected by hyazinthe, thank you!

[oweals/gnunet.git] / src / include / gnunet_revocation_service.h

diff --git a/src/include/gnunet_revocation_service.h b/src/include/gnunet_revocation_service.h
index 772dbbe75148e69ac55dfc3c11b3cc5897087c8e..4a29b3239da88fb23e17818974f1277e2f93143a 100644 (file)
--- a/src/include/gnunet_revocation_service.h
+++ b/src/include/gnunet_revocation_service.h
@@ -1,30 +1,32 @@
 /*
       This file is part of GNUnet
-      (C) 2013 Christian Grothoff (and other contributing authors)
+      Copyright (C) 2013 GNUnet e.V.
 
-      GNUnet is free software; you can redistribute it and/or modify
-      it under the terms of the GNU General Public Licerevocation as published
-      by the Free Software Foundation; either version 3, or (at your
-      option) any later version.
+      GNUnet is free software: you can redistribute it and/or modify it
+      under the terms of the GNU Affero General Public License as published
+      by the Free Software Foundation, either version 3 of the License,
+      or (at your option) any later version.
 
       GNUnet is distributed in the hope that it will be useful, but
       WITHOUT ANY WARRANTY; without even the implied warranty of
       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-      General Public Licerevocation for more details.
-
-      You should have received a copy of the GNU General Public Licerevocation
-      along with GNUnet; see the file COPYING.  If not, write to the
-      Free Software Foundation, Inc., 59 Temple Place - Suite 330,
-      Boston, MA 02111-1307, USA.
+      Affero General Public License for more details.
  */
 
 #ifndef GNUNET_REVOCATION_SERVICE_H_
 #define GNUNET_REVOCATION_SERVICE_H_
 
 /**
- * @file include/gnunet_revocation_service.h
- * @brief API to perform and access key revocations
- * @defgroup revocation key revocation service
+ * @author Christian Grothoff
+ *
+ * @file
+ * API to perform and access key revocations
+ *
+ * @defgroup revocation  Revocation service
+ * Perform and access key revocations.
+ *
+ * @see [Documentation](https://gnunet.org/revocation-subsystem)
+ *
  * @{
  */
 
@@ -52,8 +54,9 @@ struct GNUNET_REVOCATION_Query;
  * Callback to call with the result of a key revocation query.
  *
  * @param cls closure
- * @param is_valid #GNUNET_NO of the key is/was revoked, 
- *                 #GNUNET_YES if the key is still valid
+ * @param is_valid #GNUNET_NO of the key is/was revoked,
+ *                 #GNUNET_YES if the key is still valid,
+ *                 #GNUNET_SYSERR if we had trouble querying the service
  *
  */
 typedef void (*GNUNET_REVOCATION_Callback) (void *cls,
@@ -71,7 +74,7 @@ typedef void (*GNUNET_REVOCATION_Callback) (void *cls,
  */
 struct GNUNET_REVOCATION_Query *
 GNUNET_REVOCATION_query (const struct GNUNET_CONFIGURATION_Handle *cfg,
-                        const struct GNUNET_CRYPTO_EccPublicSignKey *key,
+                        const struct GNUNET_CRYPTO_EcdsaPublicKey *key,
                         GNUNET_REVOCATION_Callback func, void *func_cls);
 
 
@@ -94,17 +97,21 @@ struct GNUNET_REVOCATION_Handle;
  * Perform key revocation.
  *
  * @param cfg the configuration to use
- * @param key key to revoke
- * @param pow proof of work to use
+ * @param key public key of the key to revoke
+ * @param sig signature to use on the revocation (should have been
+ *            created using #GNUNET_REVOCATION_sign_revocation).
+ * @param pow proof of work to use (should have been created by
+ *            iteratively calling #GNUNET_REVOCATION_check_pow)
  * @param func funtion to call with the result of the check
  *             (called with `is_valid` being #GNUNET_NO if
  *              the revocation worked).
  * @param func_cls closure to pass to @a func
- * @return handle to use in #GNUNET_REVOCATION_cancel to stop REVOCATION from invoking the callback
+ * @return handle to use in #GNUNET_REVOCATION_revoke_cancel to stop REVOCATION from invoking the callback
  */
 struct GNUNET_REVOCATION_Handle *
 GNUNET_REVOCATION_revoke (const struct GNUNET_CONFIGURATION_Handle *cfg,
-                         const struct GNUNET_CRYPTO_EccPrivateKey *key,
+                         const struct GNUNET_CRYPTO_EcdsaPublicKey *key,
+                         const struct GNUNET_CRYPTO_EcdsaSignature *sig,
                          uint64_t pow,
                          GNUNET_REVOCATION_Callback func, void *func_cls);
 
@@ -124,11 +131,24 @@ GNUNET_REVOCATION_revoke_cancel (struct GNUNET_REVOCATION_Handle *h);
  *
  * @param key key to check for
  * @param pow proof of work value
+ * @param matching_bits how many bits must match (configuration)
  * @return #GNUNET_YES if the @a pow is acceptable, #GNUNET_NO if not
  */
 int
-GNUNET_REVOCATION_check_pow (const struct GNUNET_CRYPTO_EccPublicSignKey *key,
-                            uint64_t pow);
+GNUNET_REVOCATION_check_pow (const struct GNUNET_CRYPTO_EcdsaPublicKey *key,
+                            uint64_t pow,
+                            unsigned int matching_bits);
+
+
+/**
+ * Create a revocation signature.
+ *
+ * @param key private key of the key to revoke
+ * @param sig where to write the revocation signature
+ */
+void
+GNUNET_REVOCATION_sign_revocation (const struct GNUNET_CRYPTO_EcdsaPrivateKey *key,
+                                  struct GNUNET_CRYPTO_EcdsaSignature *sig);
 
 
 #if 0                           /* keep Emacsens' auto-indent happy */
@@ -138,6 +158,6 @@ GNUNET_REVOCATION_check_pow (const struct GNUNET_CRYPTO_EccPublicSignKey *key,
 }
 #endif
 
-/** @} */ /* end of group revocation */
-
 #endif /* GNUNET_REVOCATION_SERVICE_H_ */
+
+/** @} */ /* end of group revocation */