Purpose
|
Security Level
|
Examples
|
Worst Result if Compromised
|
Authentication
|
Master
|
Managing Dash Identity.
|
Loss of Identity.
|
Authentication
|
Critical
|
Exchange of assets (e.g., a property deed).
|
Loss of funds/assets.
|
Authentication
|
High
|
Publishing a message on a social network.
Sending a contact request in Dashpay.
|
Loss of reputation. Risk of inducing spam.
|
Authentication
|
Medium
|
Routine background transitions for application metadata.
|
Loss of credits. Loss of anonymity.
|
Encryption
|
Medium
|
Encryption of a DashPay encrypted extended public key.
|
Ability to decrypt private sent messages. Loss of privacy.
|
Decryption
|
Medium
|
Decryption of a DashPay encrypted extended public key.
|
Ability to decrypt private received messages. Loss of privacy.
|
The master authentication key is the sole key that can sign Identity updates or disable the Identity.
Clients should use different practices for allowing access to these keys. A key with a critical or master security level should always require a user to authenticate when signing a transition. A key with a high security level should be available as long as the user has authenticated at least once during a session, this can be at the beginning of the session. A key with a medium security level should not require user authentication but must require access to the device. Clients should make use of these different security levels to give an ideal experience to end users and only ask them to authenticate when appropriate.
Identities must be created with at least one authentication key in each security level. Keys can only be disabled if another valid key is enabled in the same security level. This can happen atomically in the same state transition. Contracts can define for each document type the minimal security level required for signing. Only keys of a higher security level can be used. If no such field is present then all keys except the medium security level keys can be used. Contracts are encouraged to use the security level the most appropriate for each document type.
## Encryption Keys
Encryption and decryption keys are not valid for document signing. A key's purpose can be both for encryption and decryption simultaneously. While Identities must be registered with at least one authentication key in each security level, this is not the case for encryption and decryption keys. However, it is required that an Identity be registered and maintain at least one encryption key at a high security level and one decryption at a medium security level. Contracts that use encrypted fields should identify for each of these fields the key exchange protocol used, the hash function used in the key exchange and the encryption mechanism. Key exchange protocols could be such as elliptic curve Diffie-Hellman (ECDH) and if no key exchange protocol is set ECDH should be used as the default.
When encrypting a field that is intended to be decrypted by a recipient, the owner of the document should use the private key of one of his encryption keys and a public decryption key valid on the recipient's Identity for the key exchange. On the recipient's side, the private key of the referenced decryption key and the referenced sender's encryption public key must be used.
At the last step of a Diffie-Hellman key exchange, in accordance with NIST specification, the x and y coordinates are hashed along with a nonce. This ensures non-reuse of keys. Non-reuse of shared encryption keys for Dash Platform is vital among various contracts with multiple applications and development teams. Data contracts should either have a field in the document type that provides this nonce or should use the contractId and the document type name for this nonce. If a Contract Document Type does not specify an encryption mechanism, the default should be :
`Shared_Key = SHA256_2(x || y || contractId || UTF8(document_type_name))`
It is important to use a hash function that is non-susceptible to key extension attacks. Double SHA256 and single SHA3 both are non-susceptible.
Using the contractId and the document type name will reuse keys but only in the selected relationship for a specific document type. This is fine if keys are properly used with a secure encryption mechanism as the number of document encryptions required for an attacker to break the shared encryption key is very high. While this number might decrease with more advanced research, it would still be orders of magnitude more than the number of documents that would be created in one document type.
It is recommended that encryption should use a secure variant of AES, either CBC, CTR or GCM mode, though specialized contracts might want to use other variants. AES-CBC on 256 bits should be the default if no encryption mode is provided in the contract.
Authentication keys can be queried in Dash Platform and doing so will return the Identity that owns the key. In order to achieve this feature and also to ensure non-repudiation among Identities, all authentication keys must be unique in Dash Platform. Having unique keys requires that all Identities registering keys must prove control over the key. This is to prevent an attack where an Identity would attempt to register a key while a second Identity would maliciously try to register the same key. The attacker would attempt to do this before the original user's transition would have been added to a Platform block. His purpose would be to get his state transition to be executed first, thus preventing the first Identity from successfully registering the key.
Encryption and decryption keys are not guaranteed to be unique in Dash Platform. This is because there could be situations where having the same decryption or encryption keys among multiple Identities could be useful. Dash Platform does not support querying of encryption or decryption keys to resolve owner Identity.
# Specification
This section defines the Identity data model, the steps for signing transitions and the four Identity state transitions. Complementing this are validation rules and execution logic that together represent version 1 of the Identity protocol which is a part of Dash Platform Protocol.
There are different ways to represent data depending on specific use cases. Thus all definitions of data structures are described independent of any particular representations. Structures defined below are maps of properties which are name-value pairs. Abstract data types are used to describe property values. The details on how structures and data types are implemented are described in the representations section below.
## Data Model
In Dash Platform Protocol, the Identity Data Model is defined by Identity and Identity Public Key structures.
### Identity
The Identity Data Model represents the decentralized identifier entity in Dash Platform Protocol.
#### Properties
**_protocolVersion_**
Identity protocol version.
* Required
* Must be an integer
* Must be set to the current valid protocol version
**_id_**
256-bit unique identifier.
* Required
* Must be a byte array
* Must have length of 32 bytes
**_publicKeys_**
A list of public keys associated with the Identity.
* Required
* Must be a list
* Must contain [Identity Public Keys](#identity-public-key)
* Must contain only unique items
* Must have minimum length of 5
* Must have maximum length of 4096
**_balance_**
Balance in Platform Credits.
* Required
* Must be an integer
* Must be greater than or equal to 0
**_revision_**
Identity update revision is used for optimistic concurrency control. Incremented by one with each new update so that the update will fail if the underlying data is modified between reading and writing.
* Required
* Must be an integer
* Must be greater than or equal to 0
**_isEnabled_**
A boolean flag that indicates if the Identity is enabled or disabled. A disabled Identity cannot be updated, used for state transition signing or any other operations.
* Required
* Must be a boolean
### Identity Public Key
The Identity Public Key represents the Identity public key entity in Dash Platform Protocol. This structure is used as a sub-model in the Identity and various state transitions described below.
#### Properties
**_id_**
Identifier of public key for Identity. Used together with Identity ID to point to the exact key that was used for signing and other operations.
* Required
* Must be an integer
* Must be greater than or equal to 0
* Must be unique for the Identity public keys
**_type_**
Public key type.
* Required
* Must be an integer
* Possible values
* 0 - EC Secp256k1
* 1 - BLS 12-381
**_purpose_**
Public key purpose.
* Required
* Must be an integer
* Possible values
* 0 - Authentication
* 1 - Encryption
* 2 - Decryption
* 3 - Encryption and Decryption
**_level_**
Public key associated security level.
* Required
* Must be an integer
* Possible values
* 0 - Master
* 1 - Critical
* 2 - High
* 3 - Medium
**_data_**
Raw public key.
_Note: For authentication using a public key hash can provide security benefits if the key is a single-use key, like in payment addresses, but provides no benefit when a key is used multiple times over its lifespan. Since the keys associated with an Identity are intended to be used repeatedly over an extended period of time, a raw public key is used instead of a public key hash._
* Required
* Must be a byte array
* Must have a length of
* 33 bytes for key type 0 (compressed format for EC Secp256k1 key)
* 48 bytes for key type 1 (BLS 12-381)
**_ownershipProof_**
The proof of ownership for this key. This proof of ownership must sign the owner's Identity unique id.
* Required
* Must be a byte array
* Must have a length of
* 65 bytes for key type 0 (compressed format for EC Secp256k1 key)
* 96 bytes for key type 1 (BLS 12-381)
**_disabledAt (optional)_**
Timestamp indicating that the key was disabled at a specified time. Although disabled keys cannot be updated, they can be used for signature verification and signing Identity Disable Transitions.
* Must be an integer
* Must be greater than or equal to 0
* Must not be more than 5 minutes before or 5 minutes after the current platform chain block time at the moment of disabling
## Signing of Transitions
There are two types of state transition signing. The first type is used when the transfer of funds is involved, i.e. for registering a new Identity or topping up the balance of an existing one.
To sign such a state transition, the following steps are performed:
1. Set the signature field to be equal to null
2. Serialize the state transition into its binary form using CBOR; Canonical CBOR must be used in order to be able to produce a deterministic (predictable and immutable) result
3. Hash the binary from step 2
4. Sign the hash using the private key corresponding to the public key in the funding transaction. Signing the state transition with this private key ensures that the person registering the Identity owns the funds from the funding transaction
5. Insert the resulting signature into the signature of the state transition
The second type is used for state transitions that perform an update to the state of the Identity, i.e. updating the state transition itself by adding/disabling keys of the Identity. This type is also used for signing state transitions that change the platform state - i.e. document state transitions and Data Contracts.
The mechanism for the second type is largely the same as for the first type, with some differences. Such state transitions also have a signaturePublicKeyId alongside the signature itself, which points to a key of the Identity that was used to sign a state transition.
To sign this type of state transition, the following steps are performed:
1. Set the signature and signature public key id fields to be equal to null
2. Serialize state transition into its binary form using CBOR; Canonical CBOR must be used in order to be able to produce a deterministic (predictable and immutable) result
3. Hash the binary from step 2
4. Sign the hash using the private key corresponding to the public key from the Identity
5. Insert the resulting signature into the signature of the state transition
6. Set the public key id field to be equal to the id of the key that was used to sign the transition
## State Transitions
### Identity Create Transition
Identity creation requires two actions:
1. Creating an Asset Lock transaction on the core chain to pay for the Identity Create Transition fees and populate the Identity balance with Platform Credits
2. Broadcasting an Identity Create Transition that references the Asset Lock transaction on the platform chain
The Asset Lock output must include a public key hash that can be used to verify that the submitter of the Identity Create Transition is authorized to spend the output of the Asset Lock. The key used to create this hash must be an ECDSA key and should only be used once.
The Identity Create Transition should be submitted to Dash Platform once the Asset Lock transaction it references is finalized. The Identity Create Transition must reference the Asset Lock transaction outpoint (tx hash + output index) to be spent. This transition must include a signature by the single-use key used to create the public key hash found in the Asset Lock transaction. A raw public key is not explicitly included as it can be derived from the signature.
Fees for the Identity Create Transition are deducted from the Asset Lock output amount. The initial Identity balance will therefore be:
`balance = (Asset Lock output amount) - (fees for the Identity Create Transition)`
The Asset Lock transaction will be described in more detail in an Asset Lock DIP.
#### Properties
**_protocolVersion_**
Identity protocol version.
* Required
* Must be an integer
* Must be set to the current valid Identity protocol version
**_type_**
Type of state transition. Identity Create Transition is type 2.
* Required
* Must be an integer
* Must have a value of 2
**_assetLockOutpoint_**
Asset Lock transaction [outpoint](https://btcinformation.org/en/glossary/outpoint).
* Required
* Must be a byte array
* Must have a length of 36 bytes
* The Asset Lock transaction must be finalized
* An`OP_ASSET_LOCK` output must be present in the transaction
* The output must be used only once
* The output amount must be > ST fee + credits dust
**_publicKeys_**
A list of public keys associated with the Identity.
* Required
* Must be a list
* Must contain [Identity Public Keys](#identity-public-key)
* Must contain only unique items
* Must have minimum length of 5
* Must have maximum length of 4096
**_signature_**
Cryptographic signature of the state transition.
* Required
* Must be a byte array
* Must have a length of 65 or 96 bytes
* Must be created by the key corresponding to the public key hash in the`OP_ASSET_LOCK` of the Asset Lock Transaction specified in assetLockOutpoint
#### Execution
This state transition creates an Identity as defined in the [Data Model section](#identity). Values for the Identity's properties are assigned as described in the table below: