Claims

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

DiME uses claims to communicate information to receiving parties. These claims are like other data formats as JSON Web Tokens (JWT), although availability and usages may differ.

The first component after the header in a DiME item contains a Base64 encoded JSON string containing claims. Envelopes are an exception to this, where the use of claims is optional.

There are several standardized claims in DiME, all with a specific purpose. Most claims may be used for all types of DiME items, however, there are few exceptions to this.

Even if the data format allows for the use of proprietary or application-specific claims, there is yet no standardized naming convention. At the time being non-standard claims are not officially supported, although this may change over time.

Each standardized claim uses a three-letter abbreviation, referred to as the claim key. The claim key is used in the JSON string as the field name when adding claims. The following table outlines all standard claims, their usage, and any exceptions:

Claim	Key	Description	Applies to
Ambit	amb	Describes the region, location or boundaries where the item is intended or valid	All
Audience ID	aud	The identifier of the indented receiver, or audience, of the item	All
Capability	cap	Describes the capabilities, or usages/constrains, of an item	Identity, Identity Issuing Request, Key
Common Name	cmn	A common name, or alias, for the item, may be used to simplify manual identification of items	All
Context	ctx	The context for in which the item is to be used or valid	All
Expires at	exp	The date and time when the item should be considered invalid and should no longer be used	All
Issued at	iat	The date and time when the item should be considered valid and only used after (until expires at, if specified)	All
Issuer ID	iss	The identifier of the issuer of the item	All
Issuer URL	isu	A URL or other form of resource locator where the issuer identity or public key may be fetched	All
Key ID	kid	The identifier of a key that is related to the item	All
Item links	lnk	Item links to other items that has been securely linked to the item	All
MIME type	mim	The MIME type of any payload that is attached to the item	Data, Message
Methods	mtd	Intended for use with external systems and data formats. Will be specified further in the future	All
Public key	pub	A public key in raw format	Identity, Identity Issuing Request, Key, Message
Principle information	pri	A key-value object with further information related to the principle related to the item	Identity, Identity Issuing Request
Secret key	key	A secret key in raw format, may be a private key or a shared key	Key
Subject ID	sub	The identifier of the subject related to the item	All
System name	sys	The name of the system where the item originated from or belongs to	All
Unique ID	uid	A unique identifier for the item	All

Ambit

Claim key	Format
amb	String array (UTF8)

The ambit of an item describes the reach or within what region it may be used. A valid item may be refused if it is being used outside its ambit. The defined ambit and its enforcement is system-specific.

"amb": [ 
    "global", 
    "administration" 
]

If ambit is omitted, then it is assumed that the item has no restrictions on where it may be used inside the deployed infrastructure.

Audience ID

Claim key	Format
aud	String (UUIDv4)

The audience ID claim specifies the identifier of the receiver, the intended audience, of the a DiME item.

"aud": "34e7081b-8871-467a-a963-7f0eedb42c80"

If an item has no direct intended receiver (audience), then this claim may be omitted.

Capability

Claim key	Format
cap	String array (UTF8)

Capabilities describe the allowed usage of an identity or key. For more information about possible values refer to either Identity or Key.

Common Name

Claim key	Format
cmn	String (UTF8)

May be used to simplify manual identification of items where Common Name refers to a particular entity name or alias.

"cmn": "Data Integrity Message Envelope"

The maximum length of a common name is 84 characters.

Context

Claim key	Format
ctx	String (UTF8)

This claim is used to provide additional information about the context of the DiME item. This could be used to indicate intention of a message as “request” or “response”, or the use of a particular key.

"ctx": "keep-alive"

The maximum length of a context is 84 characters.

Expires at

Claim key	Format
exp	String (RFC 3339)

This claim specifies the date when an item expires. The format of the date follows the standard RFC 3339 and UTC must always be used. RFC 3339 is used for its ease of parsing and also since it is human-readable. Items with an expiration date in the past must be discarded, the same applies if the expiration date is before the issued date.

"exp": "2025-11-18T18:06:02.974395Z"

Issued at

Claim key	Format
iat	String (RFC 3339)

The issued at claim specifies the date when an item was created or issued. The format of the date follows the standard RFC 3339 and UTC must always be used. RFC 3339 is used for its ease of parsing and also since it is human-readable. Items that do include this claim that specifies a date in the future should be discarded, the same applies if the expires at date ("exp") is before the issued date.

Issuer ID

Claim key	Format
iss	String (UUIDv4)

This is the unique subject ID of the entity that created or issued an item.

"iss": "647589bf-7f7e-4d4c-8174-e3eb366d5a91"

Issuer URL

Claim key	Format
isu	String (UTF8)

A URL, or part of, that may be used to locate and fetch the issuer identity if needed.

"isu": "https://dime.example.com?id=647589bf-7f7e-4d4c-8174-e3eb366d5a91"
"isu": "?q=647589bf-7f7e-4d4c-8174-e3eb366d5a91"

The maximum length of Issuer URL (isu) is 512 characters, although it is recommended to keep this short and use it to build a full URL using other known components.

Key ID

Claim key	Format
kid	String (UUIDv4)

The Key ID refers to a unique identifier of a DiME key item. This claim may be used to indicate which key is needed to verify the signature of the item, or which key is needed to decrypt any attached payload.

"kid": "0cef1d8f-54be-4ce0-a669-cd2897ac64e0"

Key ID is equal to the value of the unique ID (‘uid’) of a key item.

Item links

Claim key	Format
lnk	String (UTF8)

This claim is used to store links to other DiME items in an item. For detailed information refer to Item links.

"lnk": "KEY.c0eb7bed-591e-4021-970d-e881147fa48d.7df0f3f6122413e83beb5347408d909151d5f956fe973a08357ceaf1c0b83b19"

Methods

Claim key	Format
mtd	String array (UTF8)

This claim will be further specificed in the future. The intention for it is to hold information on how to convert, or adapt a DiME item for the use in external systems using other types of data formats.

An example of this are emerging decentalized solutions for distributing and using public-key pairs.

"mtd":
[
    "furture-specification:and:use"
]

MIME type

Claim key	Format
mim	String (UTF8)

DiME items that carry arbitrary payloads may use this claim to specify the MIME type of the payload data. This must use the standard format of MIME (Multipurpose Internet Mail Extensions) types.

"mim": "text/plain"

The MIME type claim is used by Data and Message.

Public key

Claim key	Format
pub	String (UTF8)

This claim holds a public key, which can be used to verify signatures or complete Diffie-Hellman key agreement for shared keys. For that actual format refer to Key encoding.

"pub": "STN.Lo8cQbUU9wiDY1rgDbxYDAzsm8gis7RrDFsnH3BcvbY8wpBNC"

The Public key claim is used by Identity, Identity Issuing Request, Key and Message.

Principle information

Claim key	Format
pri	JSON object

A simple JSON object with information associated with the subject or holder of an identity. This may be the name of the entity name and organization. Not standard fields have been specified for the DiME data format and this claim is considered to be applicaiton-specific. This may be changed in the future.

The below example should be see as an example of usage as field names and structure is up to the application.

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

The Principle information claim is used by Identity and Identity Issuing Request.

Secret key

Claim key	Format
key	String (UTF8)

The raw data of the secret key, asymmetric or symmetric. For encoding information refer to Key encoding.

"key": "STN.aBjkzKX2B5ZwG1nrbmNFmugZp6o3i6Fk8oVmjtfopvgTPJcPcEMottZji2ejUmMWgEDukLDyFBchTw5KBoKjFF55wCTWk"

This claim is used by Key.

Subject ID

Claim key	Format
sub	String (UUIDv4)

This is a unique identifier for the entity (subject) that owns, or is associated with, the DiME item. Unlike Unique ID, this may be reused over time for the same subject or entity. For example, if an entity requests a re-issue of an Identity item, then the Subject ID may remain the same, whereas the Unique ID would change.

"sub": "a6902184-2ba0-4ba0-ab91-ca77da7d05d3"

System name

Claim key	Format
sys	String (UTF8)

The system claim specifies the network, application scope or system where a DiME item is deployed. It may be used to specify sub-sections within a larger infrastructure.

The usage is application-specific. However, when issuing Identity items from a Identity item the system name will carry over, unless anything else is specified.

"sys": "dimeformat.io"
"sys": "beaa26e7-34b2-4fa2-bdf6-17fec0840a01"
"sys": "NETWORK_DOMAIN:SUBNETWORK_DOMAIN"

Unique ID

Claim key	Format
uid	String (UUIDv4)

This is unique identifier for a DiME item. It must not be reused, not even for items of other DiME item type. A new unique id must be generated at creation, this is also required when reissuing Identity items.

"uid": "c48e4b68-91ac-4c93-ba96-1c35c50761d4"

JSON

DiME holds item claims in a simple JSON structure, as demonstrated previous. To enable simple cross-platform use DiME also uses JSON canonicalization to ensure a consistent order of the claims inside the JSON structure. The JSON Canonicalization Scheme (JCS) is described in RFC 8785.

JSON schema

Coming soon...