Identity

DiME, the open and trust-based data format building secure Application-based Public-Key Infrastructures (APKIs) in a breeze.

The identity item is used to identify entities within an Application-based Public-Key Infrastructure (APKI). In many ways it is equivalent to a X.509 certificates.

An Identity item carries information about the owner or holder, refereed to as a subject. A subject may be a device, node or actual individual.

The following is an example of a DiME identity item:

Di:ID.eyJjYXAiOlsiZ2VuZXJpYyIsImlkZW50aWZ5Il0sImV4cCI6IjIwMjMtMTAtMDNUMTQ6NDE6NTMuMTU2NzY0WiIsImlhdCI6IjIwMjItMTAtMDNUMTQ6NDE6NTMuMTU2NzY0WiIsImlzcyI6ImNlNTc4YjM2LWJhMmMtNGNmMS1hZTVjLTM3YzU2NWFmNmUxMSIsInB1YiI6IlNUTi41c3JlS1hGRE1iYUVUekJkVVVwSzVEYm5vSnJhMUZlN2RlWkRNRmlyeFVnZDZCN3JzIiwic3ViIjoiY2MzMDVmNzQtNjFkYy00ZWNlLWJkNTAtY2E4ODVkMGMzNjlmIiwic3lzIjoiaW8uZGltZWZvcm1hdC5yZWYiLCJ1aWQiOiJlYmE3YzcxOC0wNjBjLTQ4MDgtYjM1MS00Nzc5MzAyNjUwMmQifQ.SUQuZXlKallYQWlPbHNpWjJWdVpYSnBZeUlzSW1sa1pXNTBhV1o1SWl3aWFYTnpkV1VpWFN3aVpYaHdJam9pTWpBeU55MHhNQzB3TWxReE5EbzBNVG8xTXk0eE5EUXpOamhhSWl3aWFXRjBJam9pTWpBeU1pMHhNQzB3TTFReE5EbzBNVG8xTXk0eE5EUXpOamhhSWl3aWFYTnpJam9pWWpRell6UTRNamd0TURrMk1TMDBZbVEyTFdJM1lXTXRaVGMyWWprNE9HSmhabVl3SWl3aWNIVmlJam9pVTFST0xtMXJWVTF2WjJWdmFGVTVRM1YxY0RsVlYzWnhNVEo2VTI5Vk5qUmxURlZYVlZoeE1UbG1PWEJaU2pOaFNsWkdVRU1pTENKemRXSWlPaUpqWlRVM09HSXpOaTFpWVRKakxUUmpaakV0WVdVMVl5MHpOMk0xTmpWaFpqWmxNVEVpTENKemVYTWlPaUpwYnk1a2FXMWxabTl5YldGMExuSmxaaUlzSW5WcFpDSTZJalV5T1RNMlptUTBMV1ZtTldNdE5EbGxOUzA1T1RreUxUSmxaVEJsWkRBeFpETXdNaUo5Lk1qWTNNRFUzWm1RNU4yVXlNRE5tTmk1all6TTNNbU5rWTJFek1EQmtaRFU1TkRZMk5HWmhNMkUxWXpaa00yUTFNakpqTmpSbE9EbG1NalE1TmpjME9EVXdNamN3TlRReFkyVXlOalZrTUdOalpUVmhaVFJsTmpFMk1tUTNNREpqTURFNE1tWTJZalUyTkRKa09ERTVOREUxTW1Oa056ZzNZMlkxTlRFd056Qm1abVV4Tm1aaU0yRXpOemcxTXpFd05B.MDFiODQxNmIzMjk0NmJmYi5jZWQ2ZThkYWMyYWMyOTMzODI5ZDhmZGY3NWE0Y2IwMzE5N2FmNDY3MjVmMDQ2NjE3NDBmZDE5ODJiM2FjZjJmOGNiZmIwNDVlZTk3YWEwYWU0NzZlZDEzMTA5MmU1MTAyNDg1NzU2M2VhYmNhOTc0ZDEwYTIwOGI0YTgxNDgwMg

The header of a DiME identity item is always 'ID' as seen in the above example following the colon (':') after the envelope header ('Di').

Components

A DiME identity item consists of several components. Each component is separated by a dot (‘.’), which is referred to as a component separator.

The following components make up an identity item:

• Header - always 'ID'

• Claims - required

• Trust chain - optional

• Signature - required

Claims

Claims are information or data related to the identity. These could be unique identifiers, expiration dates, associated public keys, and principle information (additional information about a subject).

Any claims inside an identity item are protected from modification by an encapsulating signature. This signature is generated when the identity is issued, normally by using the private key of the issuing entity.

Example of a decoded claims component:

{
  "amb": 
  [
    "global",
    "adminstration"
  ],
  "cap":
  [
    "generic",
    "identify"
  ],
  "exp": "2023-10-03T14:41:53.156764Z",
  "iat": "2022-10-03T14:41:53.156764Z",
  "iss": "ce578b36-ba2c-4cf1-ae5c-37c565af6e11",
  "pri": 
  {
    "entity": "Example subject",
    "location": "Planet Earth",
    "organization": "DiME",
    "domain": [ "dimeformat.io" ],
    "contact": [ "[email protected]" ]
  },
  "pub": "DSC.X4W/UvSL1GqTY+fAh3LFcDGK92zsP2oIYxAlXLmtjPk",
  "sub": "cc305f74-61dc-4ece-bd50-ca885d0c369f",
  "sys": "io.dimeformat.ref",
  "uid": "eba7c718-060c-4808-b351-47793026502d"
}

As any other DiME items, Identity may use many different claims. This page include those claims that has specific usage for identities. For general information about claims refer to Claims.

Capabilities

An important part of a DiME identity is the capability ('cap') claim. This array of strings specifies what an identity may be used for. The Di:ME specification defines a small number of capabilities that are considered standards.

The following capabilities are currently defined:

• generic

• identify

• issue

• prove

• seal

• self

• timestamp

"cap": 
[ 
    "generic", 
    "identify", 
    "issue",
    "prove"
    "seal",
    "self",
    "timestamp" 
]

Capabilities are generally requested by a subject through an Identity Issuing Request (IIR). The issuing subject will validate the requested capabilities, and if acceptable, issue a Dime identity with the same capabilities.

During issuing of an identity, it is recommended to verify the requested capabilities to ensure that only allowed capabilities are being asked for. Also, it is recommended to make sure that required capabilities are included.

Some requested capabilities may be removed during issuing and others, that may not have been requested, can be added.

Generic

The generic capability is normally always present, particularly when no other capability has been requested. Although, when other capabilities are set, the inclusion of generic is not required.

This is given to subjects that have been allowed to connect to a system, but where no or limited authentication have been conducted.

An example may be in an IoT-network which uses Trust-On-First-Use (TOFU) when registering devices automatically. In these cases, full authentication may not be possible. Once a DiME identity with the generic capability has been issued to a device, it may be used for authentication of that device.

Identify

The identify capability should be given to entities that have been properly authenticated before issuing an identity. The identity issued may after this point replace the authentication method.

Several DiME identities may be issued to the same subject. First one with a generic capability for the initial connection, then once the subject performed the required authentication, a new identity, containing the identify capability, may be issued. This allows for a system where subjects with different capabilities co-exist and can increase or decrease capabilities over time.

Issue

The issue capability is used when a DiME identity should be able to issue other identities from received IIRs. Normally this capability is given to either a root identity or additional issuing identities that are used to register entities within a system.

It is recommended to use this capability only for a limited number of identities within a system. These identities are used to build up the network of registered identities and therefore also the trust within.

Additional issuing identities, issued by one root identity, may be used to create sections within an infrastructure, where the trust chains are different depending on which part a subject belongs to.

Prove

The prove capability is used when a entity needs to prove ownership of something, or prove the including to some part of a system.

Prove is considered to be more limited to the identify capability, but more authenticated then the generic capability.

Seal

The seal capability is intended to use for packaging and integrity protecting artifacts, builds, binary files, documents, or code. Here the signature will be used to verify authenticity of the package and also associate the release or file with the author or supplier.

Self

The self capability must only be used with identities that are their own issuer. This happens when an IIR is created with a public-key pair, which is then used to issue a new identity by the same entity (without the use of another identity item).

This capability should only reserved to root identities and a limited amount of other identities responsible for issuing identities.

Identities with the capability self are considered self-issued.

Timestamp

The timestamp capability is to be used when locking some noteworthy moment in time, much a notary stamp. This will help to freeze digital assets in time proving that they were valid at the time of signing.

Principle information

A DiME identity may use the claim for Principle information ('pri'). This allows for application-specific information to be include in the identity item.

The principle information claim is a simple JSON object and may be filled with any type of valid information. No standard fields have been specified for the use of this claim, and is considered to be applicaiton-specific. This may be changed in the future.

"pri": 
{
  "entity": "Example subject",
  "location": "Planet Earth",
  "organization": "DiME",
  "domain": [ "dimeformat.io" ],
  "contact": [ "[email protected]" ]
}

Trust chain

This component is optional and its usage depends on the system or infrastructure where DiME identities are used.

A normal trust chain consists of two or three identities, a root identity, an optional intermediate identity, and at least one leaf identity. In this chain the root identity is self-signed, the intermediate identity is signed by the root and any leaf identities are signed by the intermediate.

Any number of identities may be added recursively in this component and used appropriately to verify the full trust chain. In the above example using three identities (root, intermediate and leaf) the trust chain component would include the intermediate identity. Here it is assumed that the root identity is distributed separately and most likely beforehand.

Signature

The final component in an identity item is always the signature. Any identity item that is missing a signature component must always be discarded. The identity item must also be discarded if the signature verification fails.

For additional details around the format of signature see Signature encoding.