Po.et Documentation
Technical documentation for the Po.et Network

About Po.et
Use Po.et
Reference
Process
RDD

Issuers and Signatures

Each claim in the Po.et Network MUST be signed by its issuer so that the system can later validate ownership of any given claim.

An issuer MUST be an existing identity claim in the Po.et Network.

Signature Goals

Non Goals/Out-of-Scope

Linked Data Signatures

Po.et uses the Linked Data Signature specification to sign claims. There are some very specific elements to be noted in this specification:

  1. Instead of directly injecting the public key, the signature block provides a creator URI that SHOULD dereference to the appropriate public key. In order to implement that here, the Po.et protocol uses the link to the issuer’s identity claim to dereference the public key, which ensures a permanent retrieval of this specific public key.
  2. There are a variety of protocols used to generate the signature: canonization, hashing, and finally cryptographically signing the document. These are all grouped together into a Signature Suite. Identifying the signature suite used provides the libraries with the means to verify the signature. (See Constructing the Signature)

The Signature Block

The signature block (or proof) is a Linked Data Signature object that includes the following fields:

creator: Identity Claims vs Other Claims

All claims in the Po.et Network must be signed with an existing Identity Claim. The only claims that can be self-signed are Identity Claims meant to represent an Identity Provider. This provider can then generate other identity claims.

To self-sign an Identity Claim, use the URI data schema:

data:,02db393ae2d566ceddd95a97fd88bc2897a0818528158261cec45087a58786f09d

IMPORTANT For a user to export an identity claim, they must also be able to retrieve the private key associated with the Identity Claim. This is true for wallets providing key custody.

Constructing the Signature

Note that the first 4 steps involve creating the document to be signed from the raw document. A signature for a claim should be constructed as follows:

  1. Create a copy of the claim without the id or signature.
  2. Generate a canonicalized version of the claim.
  3. Add nonce and domain to the canonical version of the claim, if either are to be used.
  4. Use a prescribed hashing algorithm to generate a hash of the canonical claim (more information below).
  5. Digitally sign the hash using the private key and a prescribed signing algorithm.
  6. Add a signature node (proof) to the claim with all of the information detailed below.

Canonical Documents

Refer to JSON-LD 1.1: Serializing/Deserializing RDF.

Canonical Form, or normalized form, is the formal method of expressing a document to yield isomorphic results, regardless of serialization.

The algorithm for serializing/deserializing JSON-LD documents to RDF is described here.

The reference node library for JavaScript is: https://github.com/digitalbazaar/jsonld.js

The current results of the test suite against the standard is here.

Constructing the Hash

Many of the signature suites contain both the signing and hashing algorithms as part of the suite. Selecting such a suite may handle hashing the canonical document during the signing process.

Verifying the Signature

Steps 1-5 involve recreating the actual document that was signed. Step 6 is the standard verification of a signed document given the recreated signed document, the signing algorithm, and the public key.

  1. Get the public key by dereferencing its URL identifier in the signature node of the signed claim. Confirm that the Linked Data document that describes the public key specifies its owner and that its owner’s URL identifier can be dereferenced to reveal a bi-directional link back to the key. Ensure that the key’s owner is a trusted entity before proceeding to the next step.
  2. Extract the signature (proof) portion of the signed claim.
  3. Extract the data portion of the signed claim, remove the id. Add the nonce and domain if they are included in the signature block.
  4. Generate a canonicalized version of the claim.
  5. Use the prescribed hashing algorithm to generate a hash of the canonical claim (See above).
  6. Use the prescribed signing algorithm with the public key, hashed canonical claim, and signing value (proof) to verify the signature.

References

  1. W3C Linked Data Signatures 1.0 - Draft: Linked Data SIgnature Overview
  2. W3C Linked Data Signatures 1.0 - Draft: Multiple Signatures
  3. W3C RDF Dataset Normalization
  4. JSON-LD 1.1: Serializing/Deserializing RDF