Item verification

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

Before a DiME item should be trusted and then used, it must be verified. Verification is an important step and plays a part in the saying "Trust, but verify", or perhaps the more modern version "Never trust, always verify".

There are four steps in the verification of a DiME item, these are:

1. (if available/applicable) verify the issuer of the DiME item

   1. verify that "iss" claim in verified item is equal to "sub" claim identity used to verify

   2. verify the validity (dates) in the issuer identity, see point 2 for required steps

2. (if available) verify any dates in the DiME item

   1. verify that issued at date is passed (if "iat" claim is set)

   2. verify that issued at date is not after expiration date (if "iat" and "exp" claim are set)

   3. verify that expiration date is not passed (if "exp" claim is set)

3. (if available) verify that linked items are valid

4. (if available) verify that the digital signature is correct

   1. if verifying with a trust chain, then each identity in the trust chain to the root must also have their signatures verified

This order is used to ensure that the more expensive verification operations are done later in the verification process, this includes verification of item links and digital signatures. If any steps fail, then the verification must exit with an appropriate error code.

Each verification may be done separately if this is more appropriate. However, it is generally recommended to verify everything in one operation.

Verify issuer claim

If an DiME item is verified directly using a DiME identity, and thus using the public key inside the identity, then the claim "iss" must contain the same value in both items.

Verify dates

If any date-based claims are set in an item, then those need to be verified. This following order should be used when verifying:

1. The issued at date must be earlier than the current system date

2. The issued at date must not be later than the expiration date

3. The expiration date must be later than the current system date

Note that it is only necessary to validate those dates that are set in an item. If a date claim is excluded, then the item should be considered to never expire (missing "exp" claim) or have no start date (missing "iat" claim).

Date verification should be done using milliseconds. This may, however, introduce a time synchronization issue when sending instant or short-lived items between entities. For thoughts and solutions to this problem, refer to Time synchronization.

All dates processed must always be in Coordinated Universal Time (UTC).

Verify linked items

Linked items need to be verified before an item may be considered complete from an integrity perspective.

Multiple items may be linked to one DiME item and it should be possible to verify one or more items at the same time. If not all items linked are verified, then the integrity should be considered partly intact, only if all provided items are verified successfully. Intact integrity is only when all linked items are verified successfully against a complete and matching set of provided items.

If any item in a provided list is verified unsuccessfully, then integrity must be considered broken.

Linked items may be omitted when verifying for trust, which may be the case when the verifying entity do not have access to the original items that are linked.

Verify signature

Verification of a digital signature is normally the most expensive operation, thus it may be done last, and only if all other previous verification operations have completed successfully.

A provided public key, or locally stored trusted public keys, should be used to verify the integrity of the DiME item towards the signature. The item header together with any base 64 encoded content must be used when generating the signature, and thus, also when verifying the signature.

For additional details of signatures and how they are encoded, refer to Signature encoding.

Integrity state results

The following table outlines the integrity state result value for DiME item verification. These state must be used to indicate the result of a verification.

State name	Success/failed	Description
Complete	Success	All parts of the DiME item was successfully verified and the item may be trusted.
Partially complete	Success	All parts of the DiME item was successfully verified. However, not all linked items where verified, although, those that where was successful.
Intact	Success	All verified parts of the DiME item was successful. However, some parts where skipped, like linked items as no list of items where provided.
Valid signature	Success	The signature of the DiME item was verified successfully. No other parts where verified.
Valid dates	Success	The dates (issued at and/or expires at) in the DiME item were verified successfully. No other parts where verified.
Valid item links	Success	Any linked items where verified successfully against a provided item list. No items where skipped or missing. No other parts where verified.
Partially valid item links	Success	All linked items where verified successfully against a provided item list. Any list, linked items or provided items, may contain items not in the other list. No other parts where verified.
No signature	Failed	Unable to verify the digital signature, as the DiME item did not contain a signature.
Not trusted	Failed	The digital signature could not be successfully verified, and, thus the DiME item must not be trusted.
Key mismatch	Failed	The public key used to verify the DiME item does not match the key pair used to generate the digital signature.
Issuer mismatch	Failed	The issuer ID ("iss") in the DiME identity used when verifying does not match issuer ID ("iss") set in the item verified.
Used after expired	Failed	The expiration date ("exp") set in the DiME item verified has passed, and the item should no longer be used.
Used before issued	Failed	The issued at date ("iat") set in the DiME item has not yet passed, and the item should not be used yet.
Date mismatch	Failed	The dates set in the DiME item verified are incorrect, where the issued at date ("iat") is after the expiration date ("exp").
Linked item fault	Failed	One, or several, linked items could not be verified successfully.
Linked item mismatch	Failed	Provided item list to verify linked items contains additional, non-linked, items.
Linked item missing	Failed	No linked items found when verifying with a provided item list.