revocation.rst (5164B)
1 2 .. index:: 3 double: subsystem; REVOCATION 4 5 .. _REVOCATION-Subsystem-Dev: 6 7 REVOCATION 8 ========== 9 10 The REVOCATION API consists of two parts, to query and to issue 11 revocations. 12 13 .. _Querying-for-revoked-keys: 14 15 Querying for revoked keys 16 ^^^^^^^^^^^^^^^^^^^^^^^^^ 17 18 ``GNUNET_REVOCATION_query`` is used to check if a given ECDSA public key 19 has been revoked. The given callback will be invoked with the result of 20 the check. The query can be canceled using 21 ``GNUNET_REVOCATION_query_cancel`` on the return value. 22 23 .. _Preparing-revocations: 24 25 Preparing revocations 26 ^^^^^^^^^^^^^^^^^^^^^ 27 28 It is often desirable to create a revocation record ahead-of-time and 29 store it in an off-line location to be used later in an emergency. This 30 is particularly true for GNUnet revocations, where performing the 31 revocation operation itself is computationally expensive and thus is 32 likely to take some time. Thus, if users want the ability to perform 33 revocations quickly in an emergency, they must pre-compute the 34 revocation message. The revocation API enables this with two functions 35 that are used to compute the revocation message, but not trigger the 36 actual revocation operation. 37 38 ``GNUNET_REVOCATION_check_pow`` should be used to calculate the 39 proof-of-work required in the revocation message. This function takes 40 the public key, the required number of bits for the proof of work (which 41 in GNUnet is a network-wide constant) and finally a proof-of-work number 42 as arguments. The function then checks if the given proof-of-work number 43 is a valid proof of work for the given public key. Clients preparing a 44 revocation are expected to call this function repeatedly (typically with 45 a monotonically increasing sequence of numbers of the proof-of-work 46 number) until a given number satisfies the check. That number should 47 then be saved for later use in the revocation operation. 48 49 ``GNUNET_REVOCATION_sign_revocation`` is used to generate the signature 50 that is required in a revocation message. It takes the private key that 51 (possibly in the future) is to be revoked and returns the signature. The 52 signature can again be saved to disk for later use, which will then 53 allow performing a revocation even without access to the private key. 54 55 .. _Issuing-revocations: 56 57 Issuing revocations 58 ^^^^^^^^^^^^^^^^^^^ 59 60 Given a ECDSA public key, the signature from ``GNUNET_REVOCATION_sign`` 61 and the proof-of-work, ``GNUNET_REVOCATION_revoke`` can be used to 62 perform the actual revocation. The given callback is called upon 63 completion of the operation. ``GNUNET_REVOCATION_revoke_cancel`` can be 64 used to stop the library from calling the continuation; however, in that 65 case it is undefined whether or not the revocation operation will be 66 executed. 67 68 .. _The-REVOCATION-Client_002dService-Protocol: 69 70 The REVOCATION Client-Service Protocol 71 -------------------------------------- 72 73 The REVOCATION protocol consists of four simple messages. 74 75 A ``QueryMessage`` containing a public ECDSA key is used to check if a 76 particular key has been revoked. The service responds with a 77 ``QueryResponseMessage`` which simply contains a bit that says if the 78 given public key is still valid, or if it has been revoked. 79 80 The second possible interaction is for a client to revoke a key by 81 passing a ``RevokeMessage`` to the service. The ``RevokeMessage`` 82 contains the ECDSA public key to be revoked, a signature by the 83 corresponding private key and the proof-of-work. The service responds 84 with a ``RevocationResponseMessage`` which can be used to indicate that 85 the ``RevokeMessage`` was invalid (e.g. the proof of work is incorrect), 86 or otherwise to indicate that the revocation has been processed 87 successfully. 88 89 .. _The-REVOCATION-Peer_002dto_002dPeer-Protocol: 90 91 The REVOCATION Peer-to-Peer Protocol 92 ------------------------------------ 93 94 Revocation uses two disjoint ways to spread revocation information among 95 peers. First of all, P2P gossip exchanged via CORE-level neighbours is 96 used to quickly spread revocations to all connected peers. Second, 97 whenever two peers (that both support revocations) connect, the SET 98 service is used to compute the union of the respective revocation sets. 99 100 In both cases, the exchanged messages are ``RevokeMessage``\ s which 101 contain the public key that is being revoked, a matching ECDSA 102 signature, and a proof-of-work. Whenever a peer learns about a new 103 revocation this way, it first validates the signature and the 104 proof-of-work, then stores it to disk (typically to a file 105 $GNUNET_DATA_HOME/revocation.dat) and finally spreads the information to 106 all directly connected neighbours. 107 108 For computing the union using the SET service, the peer with the smaller 109 hashed peer identity will connect (as a \"client\" in the two-party set 110 protocol) to the other peer after one second (to reduce traffic spikes 111 on connect) and initiate the computation of the set union. All 112 revocation services use a common hash to identify the SET operation over 113 revocation sets. 114 115 The current implementation accepts revocation set union operations from 116 all peers at any time; however, well-behaved peers should only initiate 117 this operation once after establishing a connection to a peer with a 118 larger hashed peer identity.