serval-dna/doc/REST-API-Keyring.md

Keyring REST API

Serval Project, November 2017

Introduction

The Serval Mesh network is based on cryptographic identities that can easily be created by any node at any time. Each Serval DNA daemon that runs on a node in the network stores its own identities in the Keyring, an encrypted store protected by passwords, and gives applications access to the Keyring via the Keyring REST API described in this document. Using this API, client applications can add, remove, unlock, lock, query, and modify identities in the keyring.

Basic concepts

Serval ID

Every identity in the Serval mesh network is represented by its Serval ID, (usually abbreviated to SID, and formerly known as “Subscriber ID”), which is a unique 256-bit public key in the Curve25519 crypto-box key space. The SID is used:

• as the network address in the Serval Mesh network
• to encrypt MDP messages
• to identify the senders, recipients and authors of Rhizome bundles
• to identify the parties in a MeshMS conversation

The Serval ID public key is derived from the Serval ID secret key, which is generated when the identity is first created, and stored in the keyring. The original implementation of Serval DNA generated the Serval ID secret key at random, but since the introduction of combined IDs, the secret key is derived from the Serval Signing ID secret key.

Serval Signing ID

Every identity in the Serval mesh network has a Serval Signing ID, which is a unique 256-bit public key in the Curve25519 crypto-sign key space that is generated by choosing a secret signing key at random when the the identity is first created. The Signing ID is used:

• to prevent forgery of Serval Mesh network routing messages
• to authenticate non-encrypted MDP messages

The large size of the key space means that, as long as the secret key choice is truly random, the probability of two identities having the same ID is negligible, even if billions of identities are generated.

Combined IDs

Since July 2016, Serval DNA generates Serval IDs by deriving them from the Serval Signing ID, so when creating a new identity, only a single secret key is generated at random instead of two. This change was made possible by replacing the NaCl cryptographic library with libsodium, which provides a primitive to map keys from the crypto-sign key space to the crypto-box key space (but not vice versa, which is mathematically impossible).

These related keys are called combined IDs.

Eventually, the Serval ID will be replaced by the Serval Signing ID throughout the Serval software and protocols, but will still be called “Serval ID”. The encryption key (in the crypto-box key space) will be derived from the signing key on the fly whenever needed, so there will only be one kind of Serval ID, which will be a great simplification.

DID

The DID (Dialled Identity) is a telephone number, represented as a string of five or more digits from the set 123456789#0*. It is used by the DNA protocol to allow Serval mesh network users to discover each other by telephone number; the first step in establishing a mesh voice call.

Name

The Name is a short, non-blank, non-empty, unstructured string assigned by a human user to an identity. It is used to represent the identity to human users, as it is more recognisable than a hexadecimal SID or a DID (telephone number).

The name is encoded using UTF-8. Since it is intended for human consumption, it may be constrained to contain only printable characters and no carriage-motion characters (eg, TAB U+0009 or LF U+0010), and to not start or end with white space.

Rhizome Secret

The Rhizome Secret is a secret key, separate from the SID secret, that is generated randomly for each new identity, and stored in the keyring as part of the identity. The Rhizome Secret is used to securely encode the Bundle Secret of a bundle into its manifest, in the form of the Bundle Key, thus relieving Rhizome applications of the burden of having to store and protect Bundle Secrets themselves.

PIN

When an identity is created, it can optionally be given a PIN (passphrase). If the PIN is empty then the identity is permanently unlocked (visible).

Identities with a non-empty PIN are stored encrypted in the keyring file. Inspection of the keyring file will not reveal their presence unless the correct PIN is supplied, because all unused entries in the keyring file are filled with pseudo-random content that is indistinguishable from encrypted identities.

If a PIN is lost and forgotten, then the identity (identities) it unlocks will remain locked and unusable forever. There is no “master PIN” or back-door.

Identity unlocking

All Keyring requests can supply a passphrase using the optional pin parameter, which unlocks all keyring identities protected by that password, prior to performing the request. Serval DNA caches every PIN it receives until the PIN is revoked using the lock request, so once an identity is unlocked, it remains visible until explicitly locked.

Keyring REST API common features

Keyring JSON result

All Keyring requests relating to a single identity that do not produce a special response content for the outcome, return the following augmented JSON result object as the HTTP response content:

{
    "http_status_code": ...,
    "http_status_message": "...",
    "identity": {
        "sid": "<hex64>",
        "identity": "<hex64>",
        "did": "...",
        "name": "..."
    }
}

• the sid field is the SID; a string containing 64 uppercase hexadecimal digits
• the identity field is the Signing Id; a string containing 64 uppercase hexadecimal digits
• the did field is the string DID; omitted if the identity has no DID
• the name field is the string Name; omitted if the identity has no name

Keyring REST API operations

GET /restful/keyring/identities.json

Returns a list of all currently unlocked identities, in JSON table format. The table columns are:

• sid: the SID of the identity, a string of 64 uppercase hex digits
• identity: the Signing ID of the identity, a string of 64 uppercase hex digits
• did: the optional DID (telephone number) of the identity; null if none is assigned
• name: the optional string Name of the identity; null if none is assigned

GET /restful/keyring/add

Creates a new identity with a random SID. If the pin parameter is supplied, then the new identity will be protected by that password, and the password will be cached by Serval DNA so that the new identity is unlocked.

Returns 201 Created if an identity is created; the JSON result describes the identity that was created.

GET /restful/keyring/SID/remove

Removes an existing identity with a given SID.

If there is no unlocked identity with the given SID, this request returns 404 Not Found. Otherwise it returns 200 OK and the JSON result describes the identity that was removed.

GET /restful/keyring/SID/set

Sets the DID and/or name of the unlocked identity that has the given SID. The following parameters are recognised:

• did: sets the DID (phone number); must be a string of five or more digits from the set 123456789#0*
• name: sets the name; must be non-empty

If there is no unlocked identity with the given SID, this request returns 404 Not Found.

GET /restful/keyring/SID/lock

Locks an existing identity with a given SID.

If there is no unlocked identity with the given SID, this request returns 404 Not Found. Otherwise it returns 200 OK and the JSON result describes the identity that was locked.

---

Copyright 2015 Serval Project Inc.
Copyright 2016-2017 Flinders University
Available under the Creative Commons Attribution 4.0 International licence.