Documentation

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.

Base URL

All URLs referenced in the documentation have the following base:

https://<revocation-service>/revocation/

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.

Endpoints:

GET https://revocation-service/revocation/get/<multihash>

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.

Example:

GET https://revocation-service/revocation/get/122023d8d088e212...

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