§ Self-Certifying Identifier (SCID) Specification

Specification Status: DRAFT

Latest Draft: https://github.com/bcgov/scid-spec

Editors:
Stephen Curran
John Jordan, BC Gov
Andrew Whitehead
Brian Richter
Dmitri Zagidulin
Participate:
GitHub repo
File a bug
Commit history

§ Abstract

A self-certifying identifier (SCID) as defined in this specification is an identifier for, and embedded in. a JSON object that is created on initial use of that object. The SCID remains consistent as the object evolves, and is verifiable from the initial JSON object.

SCIDs are using the Trust DID Web (did:tdw) DID Method.

§ Definitions

self-certifying identifier
An object identifier derived from initial data such that an attacker could not create a new object with the same identifier. The input for a did:tdw SCID is the initial DIDDoc with the placeholder {SCID} wherever the SCID is to be placed.
base32_lower
Applies [RFC4648] to convert data to a base32 encoding, and then lower cases the result. Data encoded as base32 consists of a string of characters containing only the letters A-Z and digits 2-7.
JSON Canonicalization Scheme
The [RFC8785] canonicalizes a JSON structure such that is suitable for verifiable hashing or signing.

§ Overview

TODO

To be added.

§ Selef-Certifying Identifier (SCID) Specification

The SCID, a globally unique identifier, is generated as part of the creation of an object and used as or placed into an identifier for the object.

§ Create (Register) SCID

Creating a SCID is done by carrying out the following steps.

  1. Define the identifier string, including where the SCID will be placed. Identify (using the placeholder {SCID}) where the required SCID will be placed in the identifier string (ie. did:tdw:example.com:{SCID}).
  2. Create the initial JSON object (e.g., did.json) object to which the SCID applies, with whatever content is required. Wherever there is self-reference to the SCID in the content, use the {SCID} placeholder for the SCID (ie. did:tdw:example.com:{SCID}#key-1).
  3. Calculate the SCID for the identified object as defined in the SCID Generation and Validation section of this specification.
  4. Replace in the content the placeholder for the SCID {SCID} with the calculated SCID.

§ Read (Resolve)

For the initial version of the content, verify that the SCID that is or is embedded in the identifier verifies according to the SCID Generation and Verification section of this specification.

§ SCID Generation and Validation

The Self-certifying identifier or scid is derived from the initial content of the identified object, and forms some or all of the object identifier.

§ Generate SCID

To generate the required SCID for an identifier a Controller MUST execute the following function:

left(base32_lower(hash(JCS(initial object content with placeholders))), <length>)

Where:

  1. The initial object content with placeholders is the initial content defined by the Controller for the object, with the placeholder {SCID} put everywhere the SCID will be used in the resolved version 1 of the content. At minimum, the {SCID} MUST appear in the top level id item of the content. It MAY occur elsewhere in the content.
  2. JCS is an implementation of the JSON Canonicalization Scheme [RFC8785]. It outputs a canonicalized representation of its input.
  3. hash is either sha256 or an alternative hash algorithm defined in the hash item in the parameters. Its output is the hash of its input.
  4. base32_lower as defined by the base32_lower function. Its output is the lower case of the Base32 encoded string of its input.
  5. left extracts the <length> number of characters from the string input.
    1. <length> MUST be at least 28 characters.

§ Verify SCID

To verify the SCID of a SCID-based identifier being resolved, the resolver MUST execute the following process:

  1. Extract the SCID from the identifier.
  2. Verify that the length of the scid is at least 28 characters.
    1. If less than 28 characters, terminate the resolution process with an error.
  3. Extract or retrieve the first version of the object content.
  4. Treat the content as a string and do a text replacement of the scid value from the first step with the string {SCID}. This should result in the initial content object with placeholders data needed for the next step.
  5. Execute the hashing process defined in the generation defined above to generate the value calculatedSCID.
    1. For the <length> value, use the length of the scid extracted in step 1.
  6. Verify that the scid matches the calculatedSCID.

§ Security and Privacy Considerations

TODO

To be added.

§ Implementors Guide

§ Implementations

Proof of concept implementations of the SCID generation code are in the did:tdw software for DID Controllers and resolvers that can be found here:

§ did:tdw Example

The following shows an example of a SCID being created. This example uses the creation of a Decentralized Identifier (DID) that has an associated SCID. The SCID is generated from the DID’s associated DIDDoc.

§ DIDDoc with SCID Placeholders

This is the version of the DIDDoc that is the input to the SCID Generation Process. Note the {SCID} placeholders where the SCID will later be placed in the next step of the process.

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/multikey/v1"
  ],
  "id": "did:tdw:example.com:{SCID}",
  "controller": "did:tdw:example.com:{SCID}",
  "authentication": [
    "did:tdw:example.com:{SCID}#y4SDXopT"
  ],
  "assertionMethod": [
    "did:tdw:example.com:{SCID}#5b48Zj6B"
  ],
  "verificationMethod": [
    {
      "id": "did:tdw:example.com:{SCID}#y4SDXopT",
      "controller": "did:tdw:example.com:{SCID}",
      "type": "Multikey",
      "publicKeyMultibase": "z6Mksta2t7db1WSx2JBorfYFcJnaJMBKUyupD2qPy4SDXopT"
    },
    {
      "id": "did:tdw:example.com:{SCID}#5b48Zj6B",
      "controller": "did:tdw:example.com:{SCID}",
      "type": "Multikey",
      "publicKeyMultibase": "z6Mkw1KSvGWNAwSwWbcpwPgFARX4vKPa1xvcDMsJ5b48Zj6B"
    }
  ]
}

§ DIDDoc with SCID In Place

After the SCID is generated, the {SCID} placeholders are replaced by the generated SCID value. In this case, the SCID is 4c99uuenu8gk6n3bgf09fuf350gx

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/multikey/v1"
  ],
  "id": "did:tdw:example.com:4c99uuenu8gk6n3bgf09fuf350gx",
  "controller": "did:tdw:example.com:4c99uuenu8gk6n3bgf09fuf350gx",
  "authentication": [
    "did:tdw:example.com:4c99uuenu8gk6n3bgf09fuf350gx#y4SDXopT"
  ],
  "assertionMethod": [
    "did:tdw:example.com:4c99uuenu8gk6n3bgf09fuf350gx#5b48Zj6B"
  ],
  "verificationMethod": [
    {
      "id": "did:tdw:example.com:4c99uuenu8gk6n3bgf09fuf350gx#y4SDXopT",
      "controller": "did:tdw:example.com:4c99uuenu8gk6n3bgf09fuf350gx",
      "type": "Multikey",
      "publicKeyMultibase": "z6Mksta2t7db1WSx2JBorfYFcJnaJMBKUyupD2qPy4SDXopT"
    },
    {
      "id": "did:tdw:example.com:4c99uuenu8gk6n3bgf09fuf350gx#5b48Zj6B",
      "controller": "did:tdw:example.com:4c99uuenu8gk6n3bgf09fuf350gx",
      "type": "Multikey",
      "publicKeyMultibase": "z6Mkw1KSvGWNAwSwWbcpwPgFARX4vKPa1xvcDMsJ5b48Zj6B"
    }
  ]
}

The SCID is a stable identifier that can be embedded (in this case) in the DID string. As the DIDDoc evolves over time, the SCID can be used to demonstrate that future versions of the DID/DIDDoc evolved from the initial version of the DIDDoc.

§ References

RFC4648
The Base16, Base32, and Base64 Data Encodings. S. Josefsson; 2006-10. Status: Proposed Standard.
RFC8785
JSON Canonicalization Scheme (JCS). A. Rundgren; B. Jordan; S. Erdtman; 2020-06. Status: Informational.

✕
Table of Contents ✕
undefined