Method Specification for Ontology

did:ont

Abstract

ONT ID is Ontology's decentralized identity framework based on W3C Decentralized Identifiers (DIDs) specification using blockchain and cryptography technology, which can instantly identify and connect people, assets, things, and events. ONT ID offers the features of decentralization, self-management, privacy protection and ease of use. With ONT ID, the privacy and security of users' identity and data are fully protected and users can have complete control over their own identity and data.

The ONT ID specification conforms to W3C DIDs specification and extends the definition and features on its basis.

Conformance and Terminology

This specification assumes a fair degree of understanding of W3C DIDs specification.

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in IETF RFC 2119.

ONT ID

Used to denote Ontology's blockchain technology and cryptography based decentralized identity framework. Also denotes the decentralized identifier allocated to entities that part of the decentralized Ontology network.

SHA256

A part of the SHA-2 cryptographic hash family designed by the United States National Security Agency. First published in 2001.

Base58

A popular encoding scheme commonly used in blockchain technology. Maintains readability while allowing for data compression and encoded verification.

ABNF

An abbreviation for augmented Backus–Naur form. An ABNF specification is a set of derivation rules.

ONT ID Format

ONT ID Syntax

ONT ID is a URI conforming to IETF RFC 3986 and SHOULD be generated by each entity itself.

ONT ID is generated in conformity with W3C DIDs specification。

ONT ID is generated as described in ABNF as follows:

ontid        = "did:ont:" ontid-string
ontid-string = 1* idchar
idchar       = 1-9 / A-H / J-N / P-Z / a-k / m

"did:ont:" denotes that ONT ID is the decentralized identifier conforming to W3C DIDs specification that is registered on the Ontology blockchain; idchar includes all the characters of the Base58 encoded character set.

ontid-string MUST be generated using the following method:

1. Generate a 20-byte random number.

2. Append 1-byte tag bits. Append 1-byte tag bits to the generated random number, i.e. data = VER || h;

3. Calculate 4-byte parity bits. Calculate the SHA256 hash of the data twice and take the first 4 bytes as parity bits, i.e. checksum = SHA256(SHA256(data))[0:4];

4. Encode. Encode the above result to a Base58 encoded value, i.e. ontid-string = Base58(data || checksum).

In the above stated process, || represents the connector that connects the two adjoining byte strings. The recommended value of VER is 23.

Below is an example of an ONT ID:

did:ont:AderzAExYf7yiuHicVLKmooY51i2Cdzg72

ONT ID URL Syntax

The ONT ID URL syntax follows the DID URL rules defined in W3C DIDs specification.

The ONT ID URL syntax is as follows.

ontid-url = "did:ont:"ontid-specific-id
          [ ";" param ] [ "/" path ]
          [ "?" query ] [ "#" fragment ]

For more information, see the rules about param，path，query and fragment as defined in W3C DIDs specification.

ONT ID Registration and Deactivation

ONT ID MUST be registered on the Ontology blockchain to be activated, and the same ONT ID MUST NOT be registered more than once.

Only the owner or delegate of the ONT ID can deactivate it.

When an ONT ID is deactivated, all the related data, including private keys, delegates, properties, and recovery person, will be deleted and only the identifier of the ONT ID will remain on the Ontology blockchain.

Deactivated ONT ID can no longer be used and cannot be reactivated for use.

ONT ID Document

Each ONT ID will have a corresponding ONT ID Document.

ONT ID Document is a method of serializing ONT ID information expressed using JSON-LD as defined in DID Documents of the W3C DIDs specification.

Below is the structure of the ONT ID Document:

{
  "@context": ["https://www.w3.org/ns/did/v1", "https://ontid.ont.io/did/v2"],
  "id": "did:ont:AderzAExYf7yiuHicVLKmooY51i2Cdzg72",
  "publicKey": [{...}],
  "authentication": [{...}],
  "controller": [{...}],
  "recovery": [{...}],
  "service": [{...}],
  "attribute": [{...}],
  "created": [{...}],
  "updated": [{...}],
  "proof": [{...}]
}

Context

ONT ID Documents MUST include a @context property.

The value of the @context property MUST be one or more URIs, where the value of the first URI MUST be https://www.w3.org/ns/did/v1 and the value of the second URI MUST be https://ontid.ont.io/did/v2. For more information, see W3C DIDs specification.

Below is an example:

{
  "@context": ["https://www.w3.org/ns/did/v1","https://ontid.ont.io/did/v2"]
}

In practice, the terms in the context provided by W3C and Ontology may not be able to meet users' demand. In this case, users need to define the context themselves and can use embedded context for extensions.

For example, users need to append a property to an ONT ID, create the corresponding context for the type value of the property and publish the context to an URI accessible to all users. This is represented in the ONT ID Document as follows:

{
  "attribute": [
    {
      "@context": {
        "some-type": "uri-of-the-context",
      },
      "id": "did:ont:some-ont-id#some-attribute",
      "type": "some-type",
      "value": "some-value"
    },
  ]
}

Identifiers

ONT ID Documents MUST include an id property to specify the ONT ID identifier linked to the Document.

The value of id MUST be a valid ONT ID.

{
  "id": "did:ont:AderzAExYf7yiuHicVLKmooY51i2Cdzg72"
}

Public Keys

An ONT ID Document MUST include a publicKey property to specify a set of public keys linked to that ONT ID.

Public and private key pairs can be used for the self-management, authorization, and verification of ONT ID. An ONT ID can be linked to multiple public and private key pairs and one pair of public and private keys can also be used to manage multiple ONT IDs.

When an ONT ID is registered on the Ontology blockchain, it SHOULD be bound to the public key of the ONT ID owner. The owner should keep the matching private key safely.

Every public key object linked to the publicKey property SHOULD include the fields id, type, controller and encoding.

Each linked public key has its own identifier specified using the field id. Each bound public key is numbered starting from 1 according to the linking order. The format of "id" is

did:ont:some-ont-id#keys-{index}

{index} is the serial number of the public key.

Bound public keys can be revoked. Revoked public keys cannot be reactivated, but still possess the original serial numbers.

The value of the type field represents the corresponding cryptographic algorithm of the public key. Ontology supports an array of international standard cryptographic algorithms, such as ECDSA, EdDSA and SM2 signature.

The value of the controller field, which identifies the controller of the corresponding private key, MUST be a valid ONT ID, denoting that the public key is controlled by this ONT ID.

The encoding key is the corresponding encoding format of the public key and the value is the result value of the public key using that encoding format. The encoding formats that Ontology supports include publicKeyPem, publicKeyHex and publicKeybase58.

Below is a specific example of the PublicKey property:

{
  "publicKey": [
    {
      "id": "did:ont:AderzAExYf7yiuHicVLKmooY51i2Cdzg72#keys-1",
      "type": "EcdsaSecp256r1VerificationKey2019",
      "controller": "did:ont:AderzAExYf7yiuHicVLKmooY51i2Cdzg72",
      "publicKeyHex": "02a545599850544b4c0a222d594be5d59cf298f5a3fd90bff1c8caa095205901f2"
    }
  ]
}

Authentication

ONT ID Documents use an OPTIONAL authentication property to specify verification methods.

ONT ID allows users to add the authentication property to denote that the holder of that ONT ID has authorized a set of verification methods for identification.

This part is derived from W3C DIDs specification.

Below is an example:

{
  ...
  "authentication": [
    "did:ont:AderzAExYf7yiuHicVLKmooY51i2Cdzg72#keys-1",
    {
      "id": "did:ont:AderzAExYf7yiuHicVLKmooY51i2Cdzg72#keys-2",
      "type": "EEcdsaSecp256r1VerificationKey2019",
      "controller": "did:ont:AderzAExYf7yiuHicVLKmooY51i2Cdzg72",
      "publicKeyBaseHex": "03a835599850544b4c0a222d594be5d59cf298f5a3fd90bff1c8caa064523745f3"
    }
  ],
}

Delegation

In an ONT ID Document, an OPTIONAL controller property is used to designate a delegate.

An ONT ID can be delegated to and controlled by other ONT IDs. A designated delegate MUST be specified when registering the ONT ID on the Ontology blockchain.

The ONT ID of the delegate has the authorization of registration and deactivation of the delegated ONT ID, and can modify properties publicKey and authentication of the delegated ONT ID.

It is worth noting that an ONT ID Document can assign controller without designating authentication.

The ONT ID of the delegate MUST be self-managed.

The delegate can be an ONT ID or a management group consisted of multiple ONT IDs. The management group can set complex threshold control logic to meet different security requirements. For example, set a management group of n ONT IDs and specify that the group can only perform an operation with the signature of at least m(<=n) ONT IDs. The setting is expressed as follows:

{
  "threshold": "m",
  "members": ["ID1", "ID2", ... , "IDn"]
}

Then, define the control logic of the recursive combination, meaning that group members can either be ONT ID, or a nested management group, as shown below:

{
  "threshold": "m1",
  "members": [
    "ID1",
    {
      "threshold": "m2",
      "members": ["ID2", ...]
    },
    ...
  ]
}

Below is a specific example representing that either did:ont:AderzAExYf7yiuHicVLKmooY51i2Cdzg72, or did:ont:AXjJnU1TJViks4KUGQruiXwkKznwVpz7Z9 and did:ont:AKwf6DvKFSBxhsmhjGCvJgaxHvCEQmpZZv together can act as a delegate.

"controller:" [
  {
    "threshold": 1,
    "members": [
      "did:ont:AderzAExYf7yiuHicVLKmooY51i2Cdzg72",
      {
        "threshold": 2,
        "members": ["did:ont:AXjJnU1TJViks4KUGQruiXwkKznwVpz7Z9", "did:ont:AKwf6DvKFSBxhsmhjGCvJgaxHvCEQmpZZv"]
      },
      ...
    ]
  }
]，

When performing operations on the delegated ONT ID, the ONT ID of the delegate(s) need to provide valid digital signatures conforming to the control logic.

The delegate can link public keys for the delegated ONT ID by setting publicKey property, and can also set authentication property, thus turning it into self-management mode. A self-managed ONT ID cannot be switched to delegated mode.

Recovery Mechanism

ONT ID Documents use an OPTIONAL recovery property to designate the recovery party.

In the event that the owner of the ONT ID lost the private key, the recovery person can help the owner to reset the private key. The recovery person can add and delete public keys from authentication of that ONT ID and update the settings for the recovery person.

Only a self-managed ONT ID can designate other ONT IDs as the recovery party.

The recovery person can use the method of group management, the rules of which are the same as the management group of delegate. The recovery person needs to provide valid digital signatures in conformity with the control logic to perform any operation.

Below is a specific example, representing that either one of ont:AXjJnU1TJViks4KUGQruiXwkKznwVpz7Z9 and did:ont:AKwf6DvKFSBxhsmhjGCvJgaxHvCEQmpZZv can perform the recovery operation.

"recovery": [
  {
    "threshold": 1,
    "members": ["did:ont:AXjJnU1TJViks4KUGQruiXwkKznwVpz7Z9", "did:ont:AKwf6DvKFSBxhsmhjGCvJgaxHvCEQmpZZv"]
  }
]，

Service Information

ONT ID Documents use an optional service to specify the service property.

ONT ID allows entities to add services to specify the information of a service related to that ONT ID, including types of service and service endpoints.

This part is derived from W3C DIDs specification.

Below is a specific example:

{
  ...
  "service": [
    {
      "id": "did:ont:AderzAExYf7yiuHicVLKmooY51i2Cdzg72#some-service",
      "type": "SomeServiceType",
      "serviceEndpint": "Some URL"
    }
  ]
}

Additional Properties

ONT ID Documents include an OPTIONAL attribute to link a set of ONT ID-related properties.

The owner or delegate of the ONT ID can add, modify or delete additional properties.

Each property MUST include the fields of key, value, and type.

• key as the identifier of the property,

• type denotes the type of the property,

• value is the content of the property.

attribute can include 100 properties at most.

There is a limit on the length of the property's field. The maximum lengths of the key, value, and type fields are 80 bytes, 64 bytes, and 512K bytes respectively.

For example, did:ont:AderzAExYf7yiuHicVLKmooY51i2Cdzg72 contains a property:

key: "some-attribute"
type: "some-type"
value: "some-value"

The property is then expressed in the ONT ID Document as follows:

{
  "id": "did:ont:AderzAExYf7yiuHicVLKmooY51i2Cdzg72",
  "attribute" : [
    {
      "key": "some-attribute",
      "type": "some-type",
      "value": "some-value"
    },
  ]
}

The types and the specific content of the additional properties are not covered in this specification and should be defined by the application layer.

Below is a specific example:

{
  "attribute": [
    {
      "key": "age",
      "type": "number",
      "value": 18
    },
  ]
}

Created

ONT ID Documents SHOULD include a created property to specify the time of creation.

This part is derived from W3C DIDs specification.

Below is a specific example:

{
  "created": "2018-06-30T12:00:00Z"
}

Updated

ONT ID Documents SHOULD include an updated property to specify a timestamp of the most recent change.

This part is derived from W3C DIDs specification.

Below is a specific example:

{
  "updated": "2019-06-30T12:00:00Z"
}

Proof of Integrity

ONT ID Documents MAY include a proof property to prove the integrity of that ONT ID Document.

This part is derived from W3C DIDs specification.

Below is a specific example:

{
  "proof": {
    "type": "LinkedDataSignature2015",
    "created": "2020-02-02T02:02:02Z",
    "creator": "did:ont:AderzAExYf7yiuHicVLKmooY51i2Cdzg72#keys-1",
    "signatureValue": "QNB13Y7Q9...1tzjn4w=="
  }
}

As of now, the proof property has not been fully implemented yet.

Appendix

Below is a simple example of an ONT ID Document:

{
  "@context": ["https://www.w3.org/ns/did/v1", "https://ontid.ont.io/did/v2"],
  "id": "did:ont:AderzAExYf7yiuHicVLKmooY51i2Cdzg72",
  "publicKey": [
    {
      "id": "did:ont:AderzAExYf7yiuHicVLKmooY51i2Cdzg72#keys-1",
      "type": "EcdsaSecp256r1VerificationKey2019",
      "controller": "did:ont:AderzAExYf7yiuHicVLKmooY51i2Cdzg72",
      "publicKeyHex": "02a545599850544b4c0a222d594be5d59cf298f5a3fd90bff1c8caa095205901f2"
    }
  ],
    "authentication": [
    "did:ont:AderzAExYf7yiuHicVLKmooY51i2Cdzg72#keys-1"
  ]
}

References

[W3C-DID] Decentralized Identifiers (DIDs) v1.0. W3C. Mar 2020. Working Draft. URL: https://www.w3.org/TR/did-core/

[RFC2119] Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119

[RFC3986] Uniform Resource Identifier (URI): Generic Syntax. T. Berners-Lee; R. Fielding; L. Masinter. IETF. JANUARY 2005. Standards Track. URL: https://tools.ietf.org/html/rfc3986

[BASE58] The Base58 Encoding Scheme. Manu Sporny. IETF. December 2019. Internet-Draft. URL: https://tools.ietf.org/html/draft-msporny-base58

ONT ID Contract API

Please follow the link below for the contract API reference.

pageONT ID Contract API