Key

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

Key items are used to store or distribute keys within an Application-based Public-Key Infrastructure (APKI). Keys may be signed or unsigned.

Example:

Di:KEY.eyJjYXAiOlsic2lnbiJdLCJpYXQiOiIyMDIyLTEwLTIzVDEyOjEyOjQwLjM3MDQwM1oiLCJrZXkiOiJTVE4uTFNONk01MTlSNDczd1VINUROcXl6a1FlQ1k0NExzd0w5aXVGUFlvMThqd3hoV3p6NUNWc3NOeVdManhvMWFGZkhSY2dueVA3NVBXTlBxenZZRWVMa3Y2bk1CN1JHIiwicHViIjoiU1ROLjJhdFpRWlc5Z1BSa29MamZwYXhhR29LSHJQYUg3Sksyc1F2QXB6cjlleENZNUhTeVQyIiwidWlkIjoiYzk3YzViYTctNjQ0NC00NzZkLWJlMTMtOTA4NGI5ZGQ1ZmNhIn0

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

Key may contain types with different capabilities and usages. For any public versions, keys intended for distribution, it is vital to remove the 'key' claim, as this hold the sensitive key material for a private or secret key. Apart for removing the 'key' claim, a public version may exactly the same as the original key item.

Components

A DiME key 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 a key item:

• Header - always 'KEY'

• Claims - required

• Signature - optional

Claims

Claims are information or data related to the key, including the actual public and/or secret key.

Claims inside the key item may be optionally protected by signing the key item.

Example of a decoded claims component:

{
    "cap":
    [
        "sign"
    ],
    "iat": "2022-10-03T17:37:02.630038Z",
    "key": "DSC.7VN2b6f0nxqubSU955PuMenLtV6u9ltQr0ovUG0CL0Rfhb9S9IvUapNj58CHcsVwMYr3bOw/aghjECVcua2M+Q",
    "pub": "DSC.X4W/UvSL1GqTY+fAh3LFcDGK92zsP2oIYxAlXLmtjPk",
    "uid": "c8f26b1f-3406-4c29-a47e-b8482780ab64"
}

As any other DiME items, Key may use many different claims. This section will detail those claims that are specific for keys. For general information about claims refer to Claims.

Capability

The capability ('cap') claim describes the usages that are intended for a key. This will determine what a key may be used for. Capabilities, and combinations thereof, may be limited by the cryptographic suite used, refer to Suites for more information.

The following key capabilities are defined in the DiME data format specification:

• authenticate

• encrypt

• exchange

• sign

"cap":
[
    "sign"
]

Authenticate

Given to keys that may be used to generate authentication codes. This may be one-time passwords or message authentication codes.

Encrypt

Given to keys that are used for symmetric encryption, where the same key is used to encrypt and decrypt a set of data.

Exchange

Given to keys that are used for Diffie-Hellman key agreements, where multiple entities need to securely exchange a symmetric a shared key for encryption, or other purposes.

Sign

Given to keys that are used to generate digital signatures. Digital signatures may be used to protect the integrity of a set of data, which may be other DiME items.

Public key

The public key ('pub') claim holds the public key of a public-key pair. For format and encoding information refer to Key encoding.

This claim is only used with keys that have the capability 'sign' or 'exchange'.

Secret key

The secret key ('key') claim holds either the private key of a public-key pair or a shared encryption key (symmetric).

If a public version of a key item is generated, then this claim must be omitted.

Signature

A DiME key item may be signed to protect its integrity. For additional information about signatures refer to Signature encoding.