Claims
DiME, the open and trust-based data format building secure Application-based Public-Key Infrastructures (APKIs) in a breeze.
Last updated
DiME, the open and trust-based data format building secure Application-based Public-Key Infrastructures (APKIs) in a breeze.
Last updated
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 |
---|---|---|---|
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.
If ambit is omitted, then it is assumed that the item has no restrictions on where it may be used inside the deployed infrastructure.
The audience ID claim specifies the identifier of the receiver, the intended audience, of the a DiME item.
If an item has no direct intended receiver (audience), then this claim may be omitted.
Capabilities describe the allowed usage of an identity or key. For more information about possible values refer to either Identity or Key.
May be used to simplify manual identification of items where Common Name refers to a particular entity name or alias.
The maximum length of a common name is 84 characters.
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.
The maximum length of a context is 84 characters.
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.
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.
This is the unique subject ID of the entity that created or issued an item.
A URL, or part of, that may be used to locate and fetch the issuer identity if needed.
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.
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.
Key ID is equal to the value of the unique ID (‘uid’) of a key item.
This claim is used to store links to other DiME items in an item. For detailed information refer to Item links.
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.
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.
The MIME type claim is used by Data and Message.
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.
The Public key claim is used by Identity, Identity Issuing Request, Key and Message.
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.
The Principle information claim is used by Identity and Identity Issuing Request.
The raw data of the secret key, asymmetric or symmetric. For encoding information refer to Key encoding.
This claim is used by Key.
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.
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.
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.
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.
Coming soon...
Claim key | Format |
---|---|
Claim key | Format |
---|---|
Claim key | Format |
---|---|
Claim key | Format |
---|---|
Claim key | Format |
---|---|
Claim key | Format |
---|---|
Claim key | Format |
---|---|
Claim key | Format |
---|---|
Claim key | Format |
---|---|
Claim key | Format |
---|---|
Claim key | Format |
---|---|
Claim key | Format |
---|---|
Claim key | Format |
---|---|
Claim key | Format |
---|---|
Claim key | Format |
---|---|
Claim key | Format |
---|---|
Claim key | Format |
---|---|
Claim key | Format |
---|---|
Claim key | Format |
---|---|
amb
Describes the region, location or boundaries where the item is intended or valid
All
aud
The identifier of the indented receiver, or audience, of the item
All
cap
Describes the capabilities, or usages/constrains, of an item
Identity, Identity Issuing Request, Key
cmn
A common name, or alias, for the item, may be used to simplify manual identification of items
All
ctx
The context for in which the item is to be used or valid
All
exp
The date and time when the item should be considered invalid and should no longer be used
All
iat
The date and time when the item should be considered valid and only used after (until expires at, if specified)
All
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
kid
The identifier of a key that is related to the item
All
lnk
Item links to other items that has been securely linked to the item
All
mim
The MIME type of any payload that is attached to the item
Data, Message
mtd
Intended for use with external systems and data formats. Will be specified further in the future
All
pub
A public key in raw format
Identity, Identity Issuing Request, Key, Message
pri
A key-value object with further information related to the principle related to the item
Identity, Identity Issuing Request
key
A secret key in raw format, may be a private key or a shared key
Key
sub
The identifier of the subject related to the item
All
sys
The name of the system where the item originated from or belongs to
All
uid
A unique identifier for the item
All
amb
String array (UTF8)
aud
String (UUIDv4)
cap
String array (UTF8)
cmn
String (UTF8)
ctx
String (UTF8)
exp
String (RFC 3339)
iat
String (RFC 3339)
iss
String (UUIDv4)
isu
String (UTF8)
kid
String (UUIDv4)
lnk
String (UTF8)
mtd
String array (UTF8)
mim
String (UTF8)
pub
String (UTF8)
pri
JSON object
key
String (UTF8)
sub
String (UUIDv4)
sys
String (UTF8)
uid
String (UUIDv4)