Method Specification for Ontology
did:ont
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.
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.
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.
A part of the SHA-2 cryptographic hash family designed by the United States National Security Agency. First published in 2001.
A popular encoding scheme commonly used in blockchain technology. Maintains readability while allowing for data compression and encoded verification.
An abbreviation for augmented Backus–Naur form. An ABNF specification is a set of derivation rules.
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
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 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.
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": [{...}]
}
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"
},
]
}
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"
}
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" isdid: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"
}
]
}
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.
Below is an example:
{
...
"authentication": [
"did:ont:AderzAExYf7yiuHicVLKmooY51i2Cdzg72#keys-1",
{
"id": "did:ont:AderzAExYf7yiuHicVLKmooY51i2Cdzg72#keys-2",
"type": "EEcdsaSecp256r1VerificationKey2019",
"controller": "did:ont:AderzAExYf7yiuHicVLKmooY51i2Cdzg72",
"publicKeyBaseHex": "03a835599850544b4c0a222d594be5d59cf298f5a3fd90bff1c8caa064523745f3"
}
],
}
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.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"]
}
],
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.
Below is a specific example:
{
...
"service": [
{
"id": "did:ont:AderzAExYf7yiuHicVLKmooY51i2Cdzg72#some-service",
"type": "SomeServiceType",
"serviceEndpint": "Some URL"
}
]
}
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
},
]
}
ONT ID Documents SHOULD include a
created
property to specify the time of creation.Below is a specific example:
{
"created": "2018-06-30T12:00:00Z"
}
ONT ID Documents SHOULD include an
updated
property to specify a timestamp of the most recent change.Below is a specific example:
{
"updated": "2019-06-30T12:00:00Z"
}
ONT ID Documents MAY include a
proof
property to prove the integrity of that ONT ID Document.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.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"
]
}
[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
Please follow the link below for the contract API reference.
Last modified 3yr ago