ZCap-LD (Authorization)

The Storage Kit uses the concept of ZCap-LD to build a capability-based authorization, but with a modified specification.

This framework provides functionality such as sharing and managing confidential data by using capabilities. In this document any ZCap-LD capability data model is using the JSON format. A ZCap-LD capability represents several attributes:

• a context definition

• an associated id

• an invoker, which represents a nonce

• a parentCapability, which contains the whole parent ZCap-LD capability and not only a reference to the capability.

• a proof field, which signs the capability with a Linked Data Proof to verify the capability. It also contains a proofPurpose to indicate if it is a capability delegation or invocation.

The field proof contains the following attributes:

• "created" represents the exact date and time when the capability delegation was created

• "creator" shows the key, a nonce, of the creator

• "jws" is a claim signed with a signature. The server can verify the claim with a secret signing key. So the JSON Web Signature (jws) claim signature can be seen as a private key and the server’s secret signing key as the public key. With this the server is able to verify the proof.

• "purpose" a string to show if it is a delegation or invocation.

• "type" is used to indicate which digital signature the proof includes.

• "verificationMethod" represents a key to verify the delegation

The root ZCap-LD capability contains another attribute called "rootCapability". It represents the associated EDV. An EDV is an encrypted data vault. This EDV can be seen as a root of trust. The EDV grants permission to the root capability and the root capability is able to grant permission to a child and so on.

Delegation

Any capability instead of the target capability needs to have a "parentCapability" property. It points on another capability or at the target. Several capabilities together form a capability chain.

In ZCap-LD delegation is handled via the capability chain.

Example:

The example represents attributes which are needed to create a ZCap-LD capability delegation. Any capability needs an unique id. This id is a simple uuid (Universally unique identifier). In this example the edv delegates permission to the root capability. So the edv serves as the invoker. The attribute invoker is represented as a did:key, nonce, starting with "z6Mk...". To verify this delegation there is a proof attribute. It contains important details: the capability was created on the 19th of december 2021 at 10:42 and 14 seconds, the key of the creator starting with "z6Mkp...", the jws starting with "eyJi...", the proof purpose shows that this capability is a delegation, it includes a digital signature produced by an ed25519 cryptographic key and the key to verify the delegation starting with "z6Mkk...".

At first the proof itself needs to be verified. This can be done by checking the jws attribute. After that the delegation can be verified by comparing the verification method and the invoker. In this example the delegation verification is successful because the key of the "invoker" property and the key of the "verificationMethod" property are equal. At the end there is an attribute called "rootCapability". It is a reference to the associated edv. The root capability can be compared to a root of trust component. It ensures that this delegation can be trusted.

Invocation

In ZCap-LD an invocation is used to authorize a further capability delegation. It contains a property called "action". This property represents the behavior of an invocation. The "action" property consists of 3 parts. What should be performed, the document id to identify the right document and the content encrypted as a SHA256 of the content.

Example:

This is an example of an invocation to create a new document in JSON format.

At first the initial capability needs to be created and verified. This is done by the attribute "parentCapability". It is a capability delegation. This delegation example is described in the delegation part of this document. Then the invocation will be created. The action attribute tells what the invocation is about. In this case the system will create a new document with the name "testDocument" and the content encrypted as a SHA256ofContent. Like the delegation an invocation includes an unique id, an invoker and a proof field. This capability invocation was created on the 19th of December 2021 at 10:44 and 1 seconds, the key of the creator starts with "z6Mkk...", the jws starts with "eyJi...", the proof purpose shows that this capability is an invocation, it includes a digital signature produced by an ed25519 cryptographic key and the key to verify the invocation starts with "z6Mkk...".

To verify that the invocation has the permission to take place its proof needs to be verified. After that the attribute "verficationMethod" of the initial capability needs to be the same as the "creator" attribute of the invocation capability. In this example both keys are equal, so the initial capability grants authority to the invocation and the document will be created.

Caveats

A caveat can be used to restrict a capability. In many cases it is useful to define restrictions how the capability may be used. For child capabilities caveats don’t need to be redefined, because every capability inherit all the caveats from their parents. Caveats are identified by their types and other properties. The following code example shows how a caveat has to be declared in JSON format.

Example:

For example Bob wants to buy a new car. He searched on the internet and found a guy called Jimmy who sells his dream car. He wants to take a test drive. So he asks Jimmy if he can get the key for the car. Before Jimmy gives the key to Bob he wants to make sure that Bob comes back with the car. He decides there is no need to take the risk that Bob just wants to steal his car. That’s why Jimmy creates a new more restricted capability and delegates the new car key to Bob. The car’s gauge currently says 149980 kilometers driven. So as we can see in the code example above Jimmy restricts Bob to drive up to 20 kilometers, but no more.