Revocation Service API Documentation
The Brickchain Revocation protocol allows a client that wishes to revoke a signature from a document to create a Revocation Request and send it to a Revocation Service. The Revocation Service is expected to publish a validated Revocation Request on a blockchain.
The Revocation Service is also responsible to answer queries to a client that looks up a revocation (with a hash) and send it a matching Revocation document.
All URLs referenced in the documentation have the following base:
The Revocation Server API must be served over HTTPS. To ensure data privacy, unencrypted HTTP should not be supported.
The Revocation Server instance has its own hostname, and issues signed responses with its own key.
The multihash in a revocation lookup is generated from the original payload field (JWS) of the request. The multihash contains the hash of the payload and the signature to be revoked. A client that wished to perform a revocation lookup must generate the multihash with the current set of hashing algorithms used on the Integrity Platform (currently only SHA-256). The multihash is sent as part of the path in the URL. See Pseudocode at the end of this document.
The response is either a HTTP status 404 if the multihash does not match a revocation currently published, or HTTP status 200 with a JWS containing a Revocation document signed by a Revocation Service.
The signature on the Revocation document must match a Revocation Service you trust (there will be a mechanism for distributing valid Revocation Service keys), and the content of the Revocation document must be checked against the original payload.
POST https://revocation-service/revocation/add/ <revocation request in body>
The create a new Revocation Request document you must have access to the original document with the signature and the key that created that signature. The payload field and the signature is combined to one document that is hashed into a multihash with the current valid hashing algorithm (currently only SHA-256). If there are more than one current hashing algorithm, only the newest algorithm should be used. The hash is embedded in a JWS called Revocation Checksum and signed by the same key as the original JWS. Both the original JWS and the Revocation Checksum JWS are embedded in the Revocation Request, and the Revocation Request is signed by yet the same key. See Pseudocode at the end of this document.
The Revocation Request is posted to the /add API endpoint. If the Revocation Service can validate the content of the Revocation Request, it generates a Revocation document containing the Revocation Checksum JWS, and signed with the Revocation Service key. The Revocation is sent back in the body of the response with HTTP status 200. The Revocation document is also published on a blockchain, and the multihash from the original Revocation Checksum document is used as the key to retrieve the Revocation document from any Revocation Service using the GET /get/<multihash> method.
If the Revocation Service cannot validate the Revocation Request document, it sends back the HTTP status 403 Forbidden.
Pseudocode for the JWS content
Generating a Revocation Request
First generate a Revocation Checksum from the original JWS document, and the signature to revoke:
Payload = OriginalJWS.Payload // Get the original payload Signature = OriginalJWS.Signature // The signature to revoke Hash = Hash(Payload+Signature) // Current hash algorithm is SHA-256 Multihash = Multihash(Hash) // Translate the hex-encoded hash into a Multihash string Checksum = new Checksumdocument(Multihash) SignedChecksum = Sign(Checksum) // Sign with same key as OriginalJWS
Then generate the Revocation Request document containing the original JWS and the Checksum:
RevocationRequest = new revocationrequest(OriginalJWS, Checksum) RevocationRequestSigned = Sign(RevocationRequest) // Sign with the same key as OriginalJWS
Querying for a Revocation
To query for a Revocation you must calculate the multihash for the original JWS. A JWS coming from a client to a service can contain multiple signatures. You need to calculate the multihash for each signature that needs a revocation check.
for each signature(JWS): Payload = JWS.Payload Signature = JWS.Signature OriginalKey = JWS.Key Hash = Hash(Payload+Signature) Multihash = Multihash(Hash) Revocation = GET https://revocation-service/get/<Multihash> if HTTP == 404 iterate over next signature end // check the content with a revocation service key Revocation.Payload = Verify(Revocation) // Check payload from Revocation if Revocation.Payload.Checksum.Key != JWS.Key print "Revocation is not valid for this JWS" exit end // Compare checksums Checksum = Verify(Revocation.Payload.Checksum, Revocation.Payload.Checksum.Key) if Revocation.Payload.Checksum == Multihash print "The signature has been revoked" end end if no signatures has a match print "JWS is ok" perform action end