Protocol

A domain name system for personal information

1. Introduction

Digital ID is a protocol that constitutes an open identity layer for the Internet and a lookup layer for personal information. It allows you to prove your identity towards others and to look up attributes of others in a decentralized manner. Being freely extensible with services, Digital ID aims to supersede proprietary platforms by establishing a framework of open standards.

The Digital ID protocol is an internet identity protocol that enables decentralized hosting of user attributes. It implements a permission system to allow attribute provisioning for authorized services and users.

Digital ID aims to solve the following problems:

  • Many-accounts: The technology behind the web was designed to allow easy access to openly available documents, which did not require any accounts at all. However, today the web consists mainly of (semi-)private services, such as social media and online banking, which require identification, authentication and authorization of users. As a result, today’s users have to deal with more than 90 accounts, on average. Identity federation is one possible solution for tackling the many-accounts problem.

  • Weak passwords: The password problem goes along with the accounts problem. Users are still using weak passwords and repeated passwords. More secure technologies, such as client-certificate authentication, exist, but are not widely used and not very user friendly in Browsers, yet. In Digital ID, there is no need for passwords, because just like client-certificates, we’re making use of cryptographic algorithms and protocols to authenticate an identity. At the same time, we focus on usability, to avoid the mistakes made with client-certificate authentication.

  • Untrusted Identity Hosts: Looking at today’s offers on identity federations on the web, Facebook and Google are at the top of the list. However, if users use their convenient identity federation services, it comes at a price: The corporations that operate the identity provider, learn about what services a user uses whenever the user logs in. This is usually not desirable and sometimes a concern for privacy. Furthermore, since Digital ID has a decentralized design, user data can be hosted on any server in any country. Even self-hosting is possible.

This specification gives an overview of how the internals of Digital ID work. Different profiles have been designed to cover common identity use cases, some of them are based on the existing protocols OpenID Connect and SAML 2.0.

1.1. Requirements Notation and Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119].

2. Features

For an easier understanding on whether the Digital ID protocol fits your needs, we cover a couple of features in this chapter.

2.1. Password-less Login

The major design problem on the web is that we often use passwords to authenticate ourselves. Here is an incomplete list of what is wrong about password authentication:

  • Doesn’t scale well: With 90 accounts on average per user, we need 90 different, difficult-to-guess passwords. However, most users are not willing to choose a different password for each account. It would simply be too difficult to remember all of them. Therefore, clever users use password managers, but the average user either uses a simple password or re-uses an existing password (or both).

  • Trusting the server: This leads to another major problem: We need to trust the service provider, where we created the account at, to store our passwords in a reliable and secure way, and not try to log in at our online banking platform with the same credentials.

  • Social engineering and phishing: Even if the server we are talking to is reliable, attackers have a simple game: If they do not guess or brute-force the password of a user account, they can try to trick the user into typing it into a fake website. The world wide economic impact of phishing is as much as US$5 billion, according to the 2013 Microsoft Computing Safety Index.

With today’s knowledge in cryptography, we do, however, have a more-secure alternative to passwords. The Digital ID protocol is therefore abstaining from the use of passwords, and instead uses digital signatures to securely identify a client, and thereby the user who operates the client. How a user authenticates against a client is not specified, because it largely depends on the type of client, e.g., a mobile phone with a fingerprint sensor can support unlocking of a client using fingerprint authentication.

2.2. Decentralized Hosting of Identities

When using a centralized identity provider, a group of users has to agree upon the identity provider. This is the case for logins on the web, where the network-effect usually decides who the identity provider is (see Facebook and Google Login). In a company environment, or in an environment where using Facebook or Google accounts is simply not appropriate (i.e. eHealth, eGovernment, online banking, etc.), choosing a single identity provider is often a question of politics.

With the Digital ID protocol, this decision is left to the users. Similar to the email protocol, a user may decide in which country and with which provider he or she wants to store his or her data. Yet, as long as the service provider supports the Digital ID protocol, data can be fetched in a secure manner from the Digital ID identity provider and transferred to a Digital ID client.

2.3. Identity Federation

One potential solution for the password problem is to use existing accounts and federate them to another account. When using a pure Digital ID solution, federation is not necessary, because the identity is already part of the protocol.

Fetching identity attributes is another feature which is usually part of identity federation. We cover this in the next paragraph.

In essence, instead of federating identity attributes to service providers, users can give permission to service providers to synchronize identity attributes from their Digital ID hosts. This also allows offline access and automatic updates, because once user consent is given, no more user interaction is necessary.

In comparison to typical identity federation protocols such as SAML and OpenID Connect, Digital ID also allows users to give access to any identities, not just platform operators. This means that data can be exchanged between different users directly.

Access to identity attributes can either be made public to everyone, or permission can be granted to a context. A context can consist of a single identifier, multiple identifiers or a hierarchy of other contexts.

2.5. Attribute-Based Access Control

Taking one step further, with the Digital ID protocol, permission to identity attributes can be restricted to identities with specific attributes. This means that people or services who should have access to identity attributes do not have to be listed explicitly. In combination with verified attributes, rules such as "only accessible for people who work at company X" are a great method for ensuring that only authorized users are able to access data, while reducing the identity management overhead.

2.6. Account Synchronization

Users have, on average, 90 accounts, which need to be managed and updated whenever attributes change. This is a cumbersome, manual process, and it likely leads to outdated account data.

The same problem also exists for service providers, who once federated identity attributes of a user into their system. For example, for service providers to target their market segment well, they need to know if a potential customer moved to a new address.

To mitigate this problem, the Digital ID protocol supports automated account synchronization.

2.7. Anonymous Authentication

Digital ID was build according to the privacy by design principle. This means that neither the identity provider needs to know with which Digital ID host the user communicates, nor that the Digital ID host needs to know who the identity is, but only if it has certain attributes.

To achieve this, the Digital ID protocol makes use of an anonymous credential system to proof correctness of attributes towards another Digital ID host. With anonymous credentials, the user may transmits a credential, signed by the identity provider, to convince the verifying Digital ID host that her attributes satisfy certain properties. This has the obvious advantage that the verifier can no longer reuse the credential to impersonate Alice. Another advantage is that anonymous credentials allow the user to reveal a selected subset of her attributes.

2.8. Verification and Validation of Attributes

Credentials can be signed not just by the identity provider itself, but by any other Digital ID host as well. Digital ID is therefore predestined to, not just host attributes in a decentralized manner, but also to have multiple decentralized verification providers who are capable of verifying user attributes and issuing credentials to the Digital ID client.

3. Hosting

The Digital ID protocol is designed as a client-server model with a decentralized server architecture that allows users to choose their Digital ID host, e.g., for their location or trust towards the host. The architecture resembels the E-Mail protocol, in which users MAY choose their own provider and can communicate with users that choose other providers.

user choses server

A service (that is, the process running the Digital ID software) MAY accommodate several Digital ID hosts with each being denoted by a different domain name.

3.1. Identifiers

Digital ID identifiers MUST BE unique identifiers of the form <user>@<host>. A identity’s location is therefore determined using the host part of a Digital ID identifier. A client interested in identity attributes of a certain Digital ID identity, requests the Digital ID host that is referenced in its identifier.

3.2. Connection

The Digital ID protocol is an application layer protocol on top of TCP. Following the client-server model, the recipient of a request MUST always be a host, which returns a response to the requester and closes the TCP connection.

When creating a Digital ID host, a subdomain "id.<domain>.<tld>" MUST be registered and point to the IP address of the server that runs the Digital ID server. The socket port MUST be set to 1494.

Hosts MUST sign responses with 2048-bit RSA and encrypt with 192-bit AES. Since requests are always initiated by clients, the client MUST choose an AES symmetric key, which is encrypted with the 2048-RSA public key of the host and send along with the request.

3.3. Identity Creation

The creation of a Digital ID identity is performed by creating an initial client that claims a unique identifier. The initial client is fully authorized at the Digital ID host and can subsequently accredit other clients.

Since the purpose of identifiers is to identify Digital ID identities, it is not allowed to ever reassign them, even if the domain changes hands. In this sense, deleting a Digital ID identity is not possible, you can only stop using it.

3.4. Trusting a Digital ID Host

3.4.1. Public Key Infrastructure

Every host MUST create a public key that MUST be certified as part of the public key infrastructure. To reduce the risk of having false certificates issued, we do not want to specify too many root certificates. Therefore, the only accepted root certificate authority, at the moment, is digitalid.net.

3.4.2. Auditing and Liability

To reduce the trust required from users, hosts need to log all actions of clients which have an effect on the state of a Digital ID identity. They are liable for all actions that they cannot trace to one of the clients accredited by the user. Due to the credentials' limited validity period of one hour (see Section X), such evidence MUST be stored for only one year. The liability of hosts themselves is limited to two years after the time of signing, due to the maximum attributes caching period of one year (see Section X).

3.5. Host Architecture

A Digital ID host has a layered architecture that consists of a connection, authorization, controller, model and persistence layer. The layers are described in the following:

Digital ID Host Layers
  • Connection Layer: Receives encrypted requests, decrypts them and verifies their signature to retrieve the identity of the requester. Replies are signed by the host and encrypted with the symmetric key that was received in the request. Signing a request is optional, which means that anonymous requests are possible.

  • Authorization Layer: Checks whether a change or retrieval of a state is permitted. The actions and queries in the controller layer specify which permissions they require and which restrictions they have.

  • Controller Layer: Defines what should be done with the request. The controller layer consists of actions and queries that can change or retrieve a state of an identity for the requesting agent.

  • Audit Service: Is responsible of auditing every change and retrieval executed in the controller layer.

  • Model Layer: Consists of subjects that are associated with an identity and have properties that are synchronized across (authorized) clients, e.g., attributes, settings, agents, certificates and contacts.

  • Persistence Layer: Stores and retrieves subjects of the model layer from and into a relational database.

4. Clients

Digital ID clients are the agents that send requests to Digital ID hosts. In comparison to a browser, a Digital ID client is a so called thick client, which provides rich functionality independent of a server. This means that, in contrast to web browsers, Digital ID clients never run untrusted code downloaded from a server and therefore are not vulnerable to security issues such as cross-site scripting and cross-site request forgery.

thin vs thick client

4.1. Accreditation

Before being able to act on your behalf, Digital ID clients need to be accredited at your Digital ID host. This is done by registering their public key together with their preferred authorization at the Digital ID host. Only the first client is authorized automatically. Further clients of the same identity MUST be authorize by a previously created, sufficiently authorized client.

user registers new client

4.2. Client Architecture

Digital ID allows to execute actions and queries locally and to synchronize them to the host at a later time, which enables offline usage. Therefore, the architecture of a Digital ID client looks like the host architecture and can (and probably should) be combined into the same code base.

5. Authentication & Authorization

In contrast to other identity federation protocol, the Digital ID protocol specifies how clients must be authenticated. This ensures that the authentication has a proper level of security, which is considered important to prevent identity and data theft.

5.1. Client Authentication towards own Digital ID Identity

The identity provider must authenticate and authorize its clients before allowing to manage the identity attributes or issuing credentials.

In Digital ID, the client authenticates itself using the Schnorr signature scheme, which is based on the discrete logarithm problem. Mathematically speaking, a client has to convince the host that it knows the discrete logarithm of some value f to base a, denoted as u (i.e. f = au), without transmitting u. f denotes the public key of the client.

To create a key pair, a base a must be chosen by the server, which can be the same for all clients of a host. This number is published and therefore part of the public key.

To create a public/private key pair, a random value r is chosen and t = ar is calculated and fixed. This value is concatenated to the message M and hashed: e = H(M, t). The client calculates y = (r - ue) and thereby forms the signature with e and y. It sends e and y to the server.

The server calculates t' = ay * fe. It checks whether e' = H(M, t') equals e. One can easily see that the client must indeed be the holder of the secret u (and thereby the only one who can commit to f), if we insert the values for y and f: t' = a(r-ue) * (au)e = a (r-ue+ue) = a r = t.

In conclusion, by having a specific client committing to a value f upon initialization, it can be identified by the Digital ID host without requiring a user name and password and therefore without many security problems that come along.

5.2. Permission System

Assume that a client wants to fetch data from another Digital ID identity. The data owner must first give permission to the identity of the requesting client. Permission can be granted to

  • everybody, or

  • a contact, which references a person using an identifier,

  • a context, which is a hierarchy of other contexts that has contacts as leaf nodes, or

  • an expressions, which is a set operation on everybody or one or more contexts and allows to further restrict access by specifying attributes that must or must not be associated with the individuals of the group.

5.3. Client Authentication towards other Digital ID Identities

When a client requests information of a Digital ID identity (other than its own), it must first request a credential from its own Digital ID host, which it then can present to the Digital ID host of the requested identity.

For this, the client requests that a hash s of a certain statement is signed, e.g. an attribute, a range of an attribute, a negation of an attribute, etc. It sends s along with y * hr, y being the public key of the client (see Schnorr signature in Section 5.1 h being part of the public key of the Digital ID host of the requesting identity, and r being a randomly chosen blinding value.

The Digital ID host then signs the statement by calculating b = (f-sgxhr)-1/e mod n (n being the modulus of the RSA group of the host). b is returned to the client.

The values f, g, h and n constitute the public key of the Digital ID host. Due to the fact that only the Digital ID host knows the group order, no one else can compute the eth root to find b.

Instead of forwarding b directly to the Digital ID host that hosts the requested identity, the client adds an additional blinding value r', which makes the credential re-usable so that it can not be tracked back to a single identity. Therefore, b' = b * hr' is calculated and b' and s are forwarded to the Digital ID host of the requested identity. The receiving Digital ID host validates the credential b' by proving that fs = b'egxhr-e*r'.

6. Protocol Specifics

Digital ID is a semantic alternative to the hyper-text transfer protocol (HTTP). In comparison to HTTP, the identity is part of the protocol, which makes accounts and account management on the server-side superfluous.

Digital ID consists of two layers: an open identity layer for the Internet, and a lookup layer for personal information.

The following diagram visualizes where we position the identity layer. We see Digital ID as the base for applications, who can now focus on their service instead of managing accounts and security.

Digital ID identity layer

The lookup layer allows for decentralized hosting of user data and platform independence. If user A would like to use a different service for hosting files as user B, they are still able to exchange files by requesting the referenced service. Authentication and identification at the service can also be done via the identity layer, or though other authentication methods.

Digital ID lookup layer

6.1. Connection Details

The Digital ID protocol follows a decentralized client-server model and runs on top of TCP. A subdomain id.<domain>.<tld> must be registered and point to the IP address of the server that runs the Digital ID host. The socket port is currently specified as 1494. All communication is encrypted with RSA-2048 and AES 192 with CBC and PKCS5 padding.

6.2. eXtensible Data Format

To describe the intention of a request, e.g., which actions or queries should be performed, the eXtensible Data Format (XDF) is used. It is a binary format that describes what kind of information is sent from a client to a server and vice versa. Instead of being human readable, as XML or HTTP, XDF focuses on being efficient, small and easy for machines to understand.

XDF knows two types: Syntactic and semantic types. As the names suggest, syntactic types define what data is transmitted, whereas semantic types define the meaning of the information.

XDF is extensible with new syntactic or semantic types. If is, however, required that types are unique. Instead of namespaces, as typically used in XML, a type in XDF is specified with an identifier of the format <typename>@<host>.

6.2.1. Syntactic Types

The basic idea of syntactic types is to encode the hierarchy of types. Final types, such as integers, characters, booleans, etc., are the leaf nodes of the hierarchy and describe the type of a single value. Structural types such as tuples, maps and lists can group multiple values or key-value pairs of either the same or different (syntactic or semantic) types.

Another type that falls under the category of syntactic types are the so called transformational types. In Digital ID, we defined three types of transformational types: encryption, signatures and compression. They define the process of validating or retrieving the content of a message. They can be seen as syntactic sugar that describes how a packet in Digital ID must look like.

Final types, structural types and transformational types all fall under the category of syntactic types. They can be used to describe how information is encoded. The table below gives an overview of the syntactic types that are currently supported by XDF.

Table 1. Syntactic Types
Category Type Identifier Description

Final Types

Boolean

boolean@core.digitalid.net

Either true or false.

Integer08

integer08@core.digitalid.net

An integer number of 8 bit (byte).

Integer16

integer16@core.digitalid.net

An integer number of 16 bit (short).

Integer32

integer32@core.digitalid.net

An integer number of 32 bit (int).

Integer64

integer64@core.digitalid.net

An integer number of 64 bit (long).

Integer

integer@core.digitalid.net

A big integer number, between -22*(31-1) and +22*(31-1).

Decimal32

decimal32@core.digitalid.net

A floating point number of 32 bit (float).

Decimal64

decimal64@core.digitalid.net

A floating point number of 64 bit (double).

String1

string1@core.digitalid.net

A character.

String64

string64@core.digitalid.net

A string of at most 64 characters.

String128

string128@core.digitalid.net

A string of at most 128 characters.

String

string@core.digitalid.net

A string of arbitrary length.

Binary128

binary128@core.digitalid.net

A byte array of 128 bytes.

Binary256

binary256@core.digitalid.net

A byte array of 256 bytes.

Binary

binary@core.digitalid.net

A byte array of arbitrary length.

Structural Types

List

list@core.digitalid.net

A list of other types. Every item in the list must have the same type.

Tuple

tuple@core.digitalid.net

A collection of multiple syntactic types. The types may be different.

Transformational Types

Compression

compression@core.digitalid.net

The content is compressed with the ZIP file format as described in the RFC1951.

Signature

client.signature@core.digitalid.net, host.signature@core.digitalid.net

The content is signed by the client (request) or by the host (response).

Encryption

request.encryption@core.digitalid.net, response.encryption@core.digitalid.net

The content is encrypted by the client (request) or by the host (response).

6.2.2. Semantic Types

While syntactic types focus on the how, semantic types deal with the what: What information is encoded in a package or in an XDF file. A semantic type describes the meaning of a type. It may be based on other semantic types and eventually resolves to a collection of syntactic types.

Digital ID specifies its action using semantic types. It thereby achieves extensibility, because not every Digital ID host must necessarily understand every semantic type.

Semantic types may restrict syntactic types. For example, month@core.digitalid.net is a semantic type based on an Integer08 and must be positive and smaller than 12. Likewise, birthday@core.digitalid.net is a semantic type that is based on a tuple of day@core.digitalid.net, month@core.digitalid.net, year@core.digitalid.net and restricts that the date must be in the past.

7. Core Methods

The Digital ID core protocol specifies core methods that are available on every Digital ID host. These are necessary to create and manage an identity. Additional methods can be specified by Digital ID extensions and may be very specific for the use case.

Digital ID extensions

7.1. Action, Queries and Replies

In Digital ID, methods are either actions or queries. Actions change a state on the host or client, whereas queries return a state. The actions and queries available on the Digital ID core protocol are listed below.

Replies are messages that inform the request issuer about the state of the action or query. A successfully executed action SHOULD have an empty reply. Clients are informed about errors via error replies.

7.1.1. Error Replies

In case of an error, a code is returned to the client. The core is based on the integer08@core.digitalid.net type. The following request error codes are available to indicate which error happened:

  • 0: INTERNAL: Indicates a condition that should never occur in a correct program. The error is an internal server error.

  • 1: EXTERNAL: Indicates an abnormal condition that is caused by an external component.

  • 2: REQUEST: Indicates that the request is invalid.

  • 3: PACKET: Indicates that the packet is corrupt.

  • 4: REPLAY: Indicates that the packet is replayed.

  • 5: ENCRYPTION: Indicates that the encryption is invalid.

  • 6: KEYS: Indicates that the keys are invalid.

  • 7: AUDIT: Indicates that the audit file was corrupt.

  • 8: SIGNATURE: Indicates that the signature was invalid.

  • 9: KEYROTATION: Indicates that a key rotation is required.

  • 10: COMPRESSION: Indicates that the compression is invalid.

  • 11: CONTENT: Indicates that the content has the wrong format.

  • 12: METHOD: Indicates that the method does not exist.

  • 13: RECIPIENT: Indicates that the recipient is unknown.

  • 14: IDENTITY: Indicates that the identifier is unknown.

  • 15: RELOCATION: Indicates that the identity relocated to another host.

  • 16: SERVICE: Indicates that the referenced service does not exist or does not know the identity anymore.

  • 17: AUTHORIZATION: Indicates an insufficient authorization.

The error reply is encoded as error@core.digitalid.net and is a tuple of an error code (based on the syntactic type integer08@core.digitalid.net) and a message (based on the syntactic type string64@core.digitalid.net).

7.2. Permissions and Restrictions

Before an action or query is executed on a host, the host checks whether the identity has the required permissions to execute the method. Therefore, every method must define which permissions it needs.

Further, internal actions can also define required restrictions. These define whether the client must have specific roles.

7.3. Identity Creation

When a new Digital ID is created, the host checks whether the chosen identifier already exists. If this is not the case, it creates the new Digital ID and marks the client as fully authorized. Only the client that is used for identity creation is authorized automatically. Other clients need to be marked as authorized through an existing client. See Client Accreditation for further details.

identity creation

Action name: action.open.account@core.digitalid.net

Content:

  • subject@core.digitalid.net: The identifier for which an account should be opened. Based on string64@core.digitalid.net.

  • category@core.digitalid.net: The category for which an account should be opened. Based on integer08@core.digitalid.net. Values are either 3 (natural person) or 4 (artificial person, which is a legal, but not natural person such as an organization).

  • client.agent.key@core.digitalid.net: Together with the subject, the client agent key uniquely identifies a client. The client chooses a client agent key and informs the host about its choice.

  • client.name@core.digitalid.net: The human-readable name of the client.

7.4. Client Accreditation

Only the first client, with which the Digital ID has been created, is automatically authorized. Other clients need to be explicitly marked as authorized by the user through an already authorized client. The new client polls the host to check whether it has already been authorized.

client accreditation

Action name: action.accredit.client.agent@core.digitalid.net

Content:

  • client.agent.key@core.digitalid.net: The client agent that should be accredited.

  • client.name@core.digitalid.net: The name of the client.

  • client.commitment@digitalid.net: The commitment of the client, which is semantically equivalent to its public key.

An already authorized client can activate a client by calling the following action:

Action name: action.client.agent.active@core.digitalid.net

Content:

  • boolean@core.digitalid.net: The flag that marks the client as active. To activate, true must be transferred. Likewise, to disable a client, false must be transferred.

7.5. Attribute Creation and Modification

An identity can create and manage attributes by changing their value or their visibility.

To change the value of an attribute, the following action can be called:

Action name: action.attribute.value@core.digitalid.net

Content:

  • signature@core.digitalid.net: Contains the type-agnostic, signed attribute.

The visibility of an attribute is defined by its owner, not by the action itself. This means that the permission to access an attribute is public, but is restricted by the visibility property. To change the visibility of an attribute, the following action can be called:

Action name: action.attribute.visibility@core.digitalid.net

Content:

  • passiveexpression@core.digitalid.net: The passive expression that defines the visibility.

7.6. Credential Query

When requesting data from another identity, the request must be signed with the user’s identity. Therefore, the client must first request a credential from the user’s host. The credential is valid for one hour and can be used to retrieve data from any hosts that accepts the credential.

attributes request

Query name: query.credential@core.digitalid.net

Content:

  • credential.claim@core.digitalid.net: A claim which states that the identity has certain attributes. The credential is issued such that the receiver of the credential can prove that the claim is correct.

Returns:

  • credential@core.digitalid.net: Returns the credential, which is valid for one hour.

7.7. Public Key Retrieval and Trust Validation

When a client communicates with a host for the first time, the host’s public key has to be retrieved, so that the following requests can be encrypted. The attribute request to retrieve the public key of a host is still unencrypted and unsigned. It is the only available request in Digital ID which may be unencrypted.

Every client is shipped with the certificate of the root certificate authority (RCA). If a public key is retrieved from a host, its validity and trust is checked by validating the certificate chain. Every successfully validated public key is cached at the client. The attribute request for a server’s public key is recursive, until an already cached and therefore trusted public key is found. The last intermediate CA certificate must be signed with the shipped certificate of the root CA, otherwise the public key is not considered valid.

public key retrieval

Query name: query.host.publickey@core.digitalid.net

Returns:

  • host.publickey@core.digitalid.net: The public key of the queried host.

7.8. Attribute Request

If the attribute’s visibility allows an identity to access the attribute of another identity, When requesting attributes from a contact, the visibility expression is evaluated to identify whether the requesting identity is allowed to read the attribute’s value.

Query name: query.attribute.value@core.digitalid.net

Content:

  • signature@core.digital.id.net: The requested, type-agnostic attribute.

Returns:

  • signature@core.digitalid.net: Returns the attribute and its value, which is type-agnostic.

8. Identity Attributes

Each host can define its own semantic types and, thereby, extend the set of attributes available in the Digital ID protocol.

The attributes defined in the Digital ID core host are listed below.

8.1. Core Attribute

  • name@core.digitalid.net: A name. It is based on a string64@core.digitalid.net.

8.2. Address Attributes

  • firstname@core.digitalid.net: The first name of the person. It is based on a string64@core.digitalid.net.

  • surname@core.digitalid.net: The last name of the person. It is based on a string64@core.digitalid.net.

  • email@core.digitalid.net: Specifies an email address. It is based on a string64@core.digitalid.net and matches a certain regular expression.

  • phone@core.digitalid.net: Specifies a phone number. It is based on a string64@core.digitalid.net.

  • streetname@core.digitalid.net: Specifies the name of a street. It is based string64@core.digitalid.net.

  • streetnumber@core.digitalid.net: Specifies the street number. It is based integer08@core.digitalid.net.

  • street@core.digitalid.net: Specifies a street. It is based on a tuple of streetname@core.digitalid.net and streetnumber@core.digitalid.net.

  • zipcode@core.digitalid.net: Specifies a zipcode. It is based on string64@core.digitalid.net.

  • cityname@core.digitalid.net: Specifies the name of a city. It is based on string64@core.digitalid.net.

  • city@core.digitalid.net: Specifies a city. It is based on a tuple of zipcode@core.digitalid.net and cityname@core.digitalid.net.

  • address@core.digitalid.net: Specifies an address. It is based on a tuple of the semantic type name@core.digitalid.net, street@core.digitalid.net, city@core.digitalid.net and country@core.digitalid.net.

  • country@core.digitalid.net: Specifies the name of a country. It is based on string64@core.digitalid.net. The list of currently valid country names currently contains 196 valid entries.

  • website@core.digitalid.net: The website of the person. It is based on the syntactic type string64@core.digitalid.net.

  • day@core.digitalid.net: Specified a day. It is based on the syntactic type integer08@core.digitalid.net. The value must be positive and lower or equal to 31.

  • month@core.digitalid.net: Specified a month. It is based on the syntactic type integer08@core.digitalid.net. The value must be positive and lower or equal to 12.

  • year@core.digitalid.net: Specified a year. It is based on the syntactic type integer08@core.digitalid.net. The value must be positive.

  • birthday@core.digitalid.net: The birthday of the person. It is based on the tuple of day@core.digitalid.net, month@core.digitalid.net and year@core.digitalid.net and must be in the past.

9. Web Extensions

To make the Digital ID protocol available for HTTP services, the transaction gateway is introduced. It is a component which provides a REST interface that allows to use Digital ID services in a limited manner on the web. This section focuses on the REST API of the transaction gateway. The format of the available requests is introduced below.

9.1. General Architecture

The overall architecture can be seen below. The green blocks represent components build upon the Digital ID protocol, the yellow blocks represent components in the HTTP context. On the left side we see the service provider, on the right side the user.

web extension
Note
When using the web extension, the service provider must be a web application, that is capable of providing the transaction request via a HTTP REST API as Json.

Digital ID allows users to choose their desired Digital ID server. Users use one or more Digital ID clients (in this example, a mobile app) to manage their data and grant permission to access attributes. Service providers publish their login, registration, signing or other identity-centered requests via an endpoint as so called transaction requests. They have a trusted relationship with a transaction gateway to receive transaction responses. This means that, for the service providers, the authentication of the user towards his/her identity server is out of scope. Once a user confirms a transaction (i.e. by giving consent to federate attributes or by signing a document), the Digital ID client forwards a transaction response to the transaction gateway of the service provider.

9.2. Transaction Request

Transaction requests are used to initiate transactions from a service provider directed towards a specific person. These transactions are centered around a user and include identity and attribute federation, digital transaction such as online shopping checkouts, signing of digital documents and more.

9.2.1. Request Envelope

9.2.2. Example

{
  "version": "v1",
  "sessionId" : "1234",
  "title": "Registration at https://example.com",
  "description": "Please provide the following attributes in order to register at https://example.com:",
  "sender": {
    "senderName": "Example",
    "senderIdentifier": "ex1",
    "senderIconUrl": "https://example.com/icon"
  },
  "confirmationLevel": "STRONG",
  "confirmationRequestMessage": "Please confirm the transaction",
  "buttonName": "register",
  "recipient": null,
  "serviceEndpoint": "https://example.com/rest/transaction",
  "primaryColor": "#2C3E50",
  "secondaryColor": "#0AD2F4",
  "messages": [
    {
      "responseRequired": true,
      "title": "Requested Attributes",
      "description": "The following attributes are required for the registration:",
      "id": "attrreq1",
      "collapsed": false,
      "visible": true,
      "requestedAttributes": [
        {
         "optional": false,
        "attributeType": "FIRST_NAME"
        },
        {
         "optional": false,
        "attributeType": "LAST_NAME"
        },
        {
         "optional": false,
        "attributeType": "BIRTHDATE"
        }
      ]
      "requestContext": "REGISTRATION"
    }
  ]
}

9.2.3. Properties

  • version - required
    The version indicates which version of transaction request is used. Currently valid is "v1".

  • sessionId - required
    The session id with which the transaction is associated with. The transaction response will contain the same session ID so that the service can map it to the request. The session ID can be an arbitrary string, chosen by the service and must not exceed 64 characters.

  • title - required
    The title which appears in the transaction message. It should inform the user about the content of the transaction.

  • description - required
    The description, which appears in the transaction message. It should inform the user in detail about the content of the transaction.

  • sender - required
    An object which consists of the senderName, senderIdentifier and senderIconUrl.

  • senderName - required
    The name of the sender, which is the service provider. The service provider must register itself with the same name. The transaction gateway must verify that the sender is authorized.

  • senderIdentifier - required
    The unique identifier of the sender, which is the service provider. The service provider must register itself with the same identifier. The transaction gateway must verify that the sender is authorized.

  • senderIconUrl - optional
    A URL to a icon in png or jpeg format that is shown in the transaction message. Max. size is 100x100 pixels.

  • confirmationLevel - optional, default: NONE
    Depending on the confirmation level, a different type of transaction is required. Valid values: NONE: no confirmation is required. WEAK: confirmation with a PIN is required. STRONG: confirmation with a biometric factor (e.g. fingerprint) is required.

  • confirmationRequestMessage - optional, default: "Please confirm the transaction"
    The message shown on the confirmation dialog.

  • buttonName - optional, default: "continue"
    The name of the button which is pressed to continue the transaction.

  • recipient - optional
    The recipient, which is the Digital ID identifier of the person that receives the transaction request.

  • serviceEndpoint - optional
    If specified, the transaction gateway responds directly with the transaction respond. If no value is specified, the service provider must poll at the transaction gateway to receive the transaction response.

  • primaryColor - optional
    The primary color of the transaction request, shown in the app. Can be used to brand the transaction request for the service provider.

  • secondaryColor - optional
    The secondary color of the transaction request, shown in the app. messages. Can be used to brand the transaction request for the service provider.

  • messages - required
    A list of messages which are the content of the transaction request. The list may be empty. If the confirmationLevel is set to WEAK or STRONG, the request is a login request. If the messages list is empty and confirmationLevel is NONE, the transaction request is invalid.

9.3. Messages

There are 3 types of messages that can be send via transaction request:

9.3.1. Message Types

Request

A request is a message for which a response is required. This is the most common transaction request message. Examples for requests are the attribute request, signing request, shopping cart request and select option request.

Notification

A message that does not expect a response is called a notification. Notifications are used to inform the user about anything that might be relative to him or her. It is possible that notifications also update the state of his or her data. In comparison to an update, a notification is visible.

Update

Updates are messages that are not visible to the user, but change the state of his or her data. An example is changing the validation status of an attribute.

9.3.2. Message Body

The general message body has the following properties:

General Properties
  • id - required
    The id of the message. The id is a string that is used to reference the message.

  • title - required
    The title of the message, which is shown as the title of the section in the request.

  • description - optional
    The description of the message, which describes the purpose of the request in detail.

  • responseRequired - required
    A boolean flag that indicates whether a response is required, e.g. as a reply to an attributes request.

  • collapsed - optional, defaults to false
    The flag indicates whether the whole message should be shown or if only a summary should be displayed. Used for example in the shopping cart request to give an overview of the products in the cart.

  • visible - required
    The flag indicates whether the message should be visible at all, or if it is an invisible update.

9.3.3. Requests

Properties

The following property values are specific for messages of type request.

  • responseRequired: True for all requests.

  • visible: True for all requests.

AttributesRequest

This request type is used to request user attributes.

Example
{
    "responseRequired": true,
    "title": "Requested Attributes",
    "description": "The following attributes are required for the registration:",
    "id": "attrreq1",
    "collapsed": false,
    "visible": true,
    "requestedAttributes": [
        {
            "optional": false,
            "attributeType": "FIRST_NAME"
        },
        {
            "optional": false,
            "attributeType": "LAST_NAME"
        },
        {
            "optional": false,
            "attributeType": "BIRTHDATE"
        }
    ],
    "requestContext": "REGISTRATION"
}
Properties
  • requestedAttributes - required
    A list of requested attributes.

    • optional - required
      Indicates whether the attribute is optional or mandatory. If optional, the user can choose not to return it and the request should still succeed.

    • attributeType - required
      The type of the attribute that is requested. Must be one of:

FIRST_NAME

The first name of the user.

LAST_NAME

The last name of the user.

NAME

The first and last name of the user or another identifying name of the identity.

GENDER

THe gender f the user. Valid values are "female" and "male".

BIRTHDATE

The birthdate of the user.

NATIONALITY

The nationality of the identity.

PICTURE

The picture of the identity in the form of a URL that links to a png or jpeg image.

STREET

The street of the identity.

ZIPCODE

The zipcode of the identity.

CITYNAME

The name of the city.

CITY

The zipcode and the name of the city.

STATE

The state of the identity.

COUNTRY

The country of the identity.

ADDRESS

The address of the identity, which is a combination of STREET, CITY and STATE.

PHONE_NUMBER

The phone number of the identity.

EMAIL

The email address of the identity.

PASSPORT_AUTHORITY

The authority that issued the passport.

PASSPORT_NUMBER

The passport number.

PASSPORT_DATE_OF_ISSUE

The date on which the passport was issued.

PASSPORT_DATE_OF_EXPIRY

The date on which the passport will expire.

  • requestContext - optional
    The context under which the request was initiated. Depending on the context, the presentation on the app might differ. Currently valid values are: REGISTRATION, LOGIN.

SigningRequest

This request type is used to sign a document.

Example
{
    "responseRequired": true,
    "title": "Signing Request",
    "description": "Please sign the following document:",
    "id": "signreq1",
    "visible": true,
    "documentURL": "https://example.com/files/document.pdf"
}
Properties
  • documentURL - required
    The URL of the document that should be signed.

9.3.4. Notification

Properties

The following property values are specific for messages of type notification.

  • responseRequired: False for all requests.

  • visible: True for all requests.

Note
Currently there are no specified notification messages.

9.3.5. Update

Properties

The following property values are specific for messages of type notification.

  • responseRequired: False for all requests.

  • visible: False for all requests.

Validation Update

Informs the client about currently valid attribute values.

Example
{
    "id": "signreq1",
    "title": "Validation Update",
    "visible": false,
    "responseRequired": false,
    "validatedAttributes": [
        "FIRST_NAME": "Stephanie",
        "LAST_NAME": "Stroka",
        "BIRTHDATE": "06.09.1987"
    ]
}
Properties
  • validatedAttributes - required
    The attributes and attribute values that have been successfully validated.

9.4. Transaction Response

Transaction responses are replies to transaction requests. The following section documents the properties of transaction responses.

9.4.1. Response Envelope

Example
{
    "version": "v1",
    "sessionId" : "1234",
    "digitalID": "stephanie.stroka@digitalid.net",
    "transactionConfirmed": true,
    "userCancelled": false,
    "responses": [
        {
            "attributes": [
                "FIRST_NAME": "Stephanie",
                "LAST_NAME": "Stroka",
                "BIRTHDATE": "06.09.1987"
            ]
        }
      ]
}
Properties
  • version - required
    The version indicates which version of transaction response is used. Currently valid is "v1".

  • sessionId - required
    The session id with which the transaction is associated with. The transaction response will contain the same session ID as the transaction request so that the service can map it to the request. The session ID can be an arbitrary string, chosen by the service and must not exceed 64 characters.

  • digitalID - required
    The digital ID identifier with which the transaction was executed. transactionConfirmed - required The flag indicates if the transaction was successfully confirmed.

  • userCancelled - required
    The flag indicates if the user cancelled the request.

  • responses - required
    A list of responses that map to the request messages in the transaction request. The list can be empty if there were no request messages.

9.4.2. Responses

Responses are replies to messages of type request. The following responses can be expected when sending requests.

AttributesResponse

Response to the AttributeRequest.

Example
{
  "attributes": [
    "FIRST_NAME": "Stephanie",
    "LAST_NAME": "Stroka",
    "BIRTHDATE": "06.09.1987"
  ]
}
Properties
  • attributes - required
    A list of attribute types and their values. Must contain all non-optional requested attributes.

SigningResponse

Response to the SigningRequest.

Example
{
  "isSigned": true,
  "signedDocumentURL": "https://idp.org/files/signed_document.pdf"
}
Properties
  • isSigned - required
    Indicates whether the document was signed.

  • signedDocumentURL - required
    The location of the signed document.