Identity management ​

After importing and instantiating the SDK, it will need to have an "identity" to perform other operations.

A user is represented by several "identities", usually one per device. These identities are created through the SDK. They can either be kept only in volatile memory, or in a persistent local database. They can also be saved onto our servers in a secure way to be able to reuse them later.

To save an identity on our servers securely, there are two ways to protect it:

• using a password with the plugin @seald-io/sdk-plugin-ssks-password;
• using two-man rule with the plugin @seald-io/sdk-plugin-ssks-2mr.

For a manual management of the protection of an identity that would not be covered by these plugins, do not hesitate to contact us or use the manual export.

Creating identities ​

A Seald user is represented by several "identities". These are actually private keys generated locally on the user's device with the SDK.

They are all linked together by a signature chain. For more details about our technology, please visit the dedicated page.

We distinguish two cases:

• a first identity ;
• the next identities that are attached to it, called "sub-identities".

First identity ​

To create an identity for a new user, use the sdk.initiateIdentity function.

This function requires a JSON Web Token. A dedicated guide will explain how to generate these license JWTs.

const seald = SealdSDK({ appId, apiURL, plugins: [SealdSDKPluginSSKSPassword(keyStorageURL)] })
await seald.initialize()
// Create their Seald identity
await seald.initiateIdentity({ signupJWT: 'signup-jwt-value' })

const seald = SealdSDK({ appId, apiURL, plugins: [SealdSDKPluginSSKSPassword(keyStorageURL)] })
await seald.initialize()
// Create their Seald identity
await seald.initiateIdentity({ signupJWT: 'signup-jwt-value' })

Personalized identifier ​

It is possible to add a custom identifier, called connector, in string format, via the use of a JWT. This can be done when creating an identity, or later using the sdk.pushJwt function.

The connector must be in the format ${IDENTIFIER}@${APP_ID}. The connector type must always be 'AP'.

An identity can have multiple identifiers. Adding a custom ID is done via the connector_add key defined in this documentation.

Sub-identities ​

From an existing identity of a user you can create a "sub-identity" using the function sdk.createSubIdentity on an SDK instance which has already been initialized.

This sub-identity will then be able to decrypt everything that the initial identity can decrypt: when another user encrypts something for that user, both the identity and the subidentity will be able to decrypt it.

This is typically used to have a separate sub-identity per device. For example, when the user logs in to a new device, we can retrieve a "main" identity protected by password or with 2-man rule, then create a new sub-identity linked to it for this device. It is then possible to store this sub-identity in localStorage, and to retrieve it when opening a new page, in order to have persistent sessions accross tabs.

const seald = SealdSDK({ appId, apiURL, plugins: [SealdSDKPluginSSKSPassword(keyStorageURL)] })
await seald.initialize()
// Create its Seald identity
await seald.initiateIdentity({ signupJWT: 'signup-jwt-value' })

// Create a sub-identity
const { subIdentity } = await seald.createSubIdentity()

const seald = SealdSDK({ appId, apiURL, plugins: [SealdSDKPluginSSKSPassword(keyStorageURL)] })
await seald.initialize()
// Create its Seald identity
await seald.initiateIdentity({ signupJWT: 'signup-jwt-value' })

// Create a sub-identity
const { subIdentity } = await seald.createSubIdentity()

This function returns a Buffer similar to the one to the one created by sdk.exportIdentity and described in the manual export paragraph.

// Pre-generate 1 key
sdk.preGenerateIdentityKeys(1)

/*
Do other stuff, to let time for the pre-generation to finish as background task
*/

// Create a sub-identity faster
const { identity } = await seald.createSubIdentity()

// Pre-generate 1 key
sdk.preGenerateIdentityKeys(1)

/*
Do other stuff, to let time for the pre-generation to finish as background task
*/

// Create a sub-identity faster
const { identity } = await seald.createSubIdentity()

You can then import this Buffer into another instance of the SDK with the function sdk.importIdentity, or save it directly on SSKS with the functions sdk.ssks2MR.saveIdentity or sdk.ssksPassword.saveIdentity.

Persistent local database ​

How it works ​

By default, the Seald SDK only saves its database in volatile memory: if you create an identity, then close and re-open your browser tab, the created identity will not be accessible anymore and will be lost, except if you have protected it onto SSKS with a password or with two-man-rule. It this case, even if the user has an authenticated session, they will have to re-type their password, or re-authenticate with their email, in order to retrieve their Seald identity.

In order to have a better user experience, we can use a persistent local database, automatically stored securely in the browser by the Seald SDK, encrypted with a key stored on your backend called databaseKey.

When the user re-opens the application, the databaseKey is retrieved from the backend through an authenticated session, and this key will be used to decrypt the encryptedDB.

Using a persistent local database ​

To use a persistent local database, you just need to add a databasePath argument to save the database, and a databaseKey argument to encrypt it, when initializing the SDK.

The server can either use a single databaseKey per user for all their devices, or it can use a different databaseKey per session. Using a different databaseKey per session is a bit more secure, but implies a more complicated data model. We will assume in the following a different databaseKey per session.

const seald = SealdSDK({
  appId,
  apiURL,
  databaseKey,
  databasePath: `seald-guide-session-${sessionID}`
})

const seald = SealdSDK({
  appId,
  apiURL,
  databaseKey,
  databasePath: `seald-guide-session-${sessionID}`
})

Here, databaseKey and sessionID must be generated and returned by the server.

We add sessionID in the databasePath in order for it to be unique for each session.

Indeed, if the same user logs-out, then logs back in, the server will have generated a new databaseKey. We therefore cannot use the same database: the database must be unique for each session, so we make databasePath change depending on the sessionID.

// front-end
const seald = SealdSDK({
  appId,
  apiURL,
  databaseRawKey: 'uz0BqYCF6IzefVHd8VzvbOZVp12GTMFD2L+UwCGYiRbKhGymgwG5HMSGfNiDt37h5FaTMKHYaqCcGTtH2ZVCzw=='
  databasePath: `seald-guide-session-${sessionID}`
})

// front-end
const seald = SealdSDK({
  appId,
  apiURL,
  databaseRawKey: 'uz0BqYCF6IzefVHd8VzvbOZVp12GTMFD2L+UwCGYiRbKhGymgwG5HMSGfNiDt37h5FaTMKHYaqCcGTtH2ZVCzw=='
  databasePath: `seald-guide-session-${sessionID}`
})

// back-end
const crypto = require('crypto')
const util = require('util')
const randomBytes = util.promisify(crypto.randomBytes)

const rawKeyBuffer = await randomBytes(64)
// This format is strict : it must be exactly 64 bytes, encoded as Base64
// and must be from a cryptographically-safe random source
const rawKey = rawKeyBuffer.toString('base64')

// back-end
const crypto = require('crypto')
const util = require('util')
const randomBytes = util.promisify(crypto.randomBytes)

const rawKeyBuffer = await randomBytes(64)
// This format is strict : it must be exactly 64 bytes, encoded as Base64
// and must be from a cryptographically-safe random source
const rawKey = rawKeyBuffer.toString('base64')

Unlike the protection of a user's identity on SSKS, here the usage is the same whether you want to create a new identity and store it in a persistent database, or retrieve an existing identity from it.

You will find more details, especially on what you will have to implement on the backend side, on the example project's page about the persistent database.

Password protection ​

Password protection of an identity is based on a derivation of a password known by the user into a symmetric key that is used to encrypt and decrypt the identity.

How it works ​

This encrypted identity is then stored on a dedicated service named Seald SDK Key Storage or SSKS.

The password protection of an identity works as follows:

The retrieval of a password protected identity works as follows:

The @seald-io/sdk-plugin-ssks-password plugin allows to do this automatically.

Save the identity ​

To use this storage method, you need to add the @seald-io/sdk-plugin-ssks-password plugin when instantiating the SDK, then after creating the identity, store it on SSKS using the sdk.ssksPassword.saveIdentity function.

const seald = SealdSDK({ appId, apiURL, plugins: [SealdSDKPluginSSKSPassword(keyStorageURL)] })
await seald.initialize()
// Create the Seald identity
await seald.initiateIdentity({ signupJWT: 'signup-jwt-value' })
// Save the password-encrypted Seald identity on the SSKS server
await seald.ssksPassword.saveIdentity({
  userId: 'myUserId',
  password: 'user-known-secret-password'
})

const seald = SealdSDK({ appId, apiURL, plugins: [SealdSDKPluginSSKSPassword(keyStorageURL)] })
await seald.initialize()
// Create the Seald identity
await seald.initiateIdentity({ signupJWT: 'signup-jwt-value' })
// Save the password-encrypted Seald identity on the SSKS server
await seald.ssksPassword.saveIdentity({
  userId: 'myUserId',
  password: 'user-known-secret-password'
})

The identity is now saved.

// Create a sub-identity
const { identity: mySubIdentity } = await seald.createSubIdentity()
// Save the new Seald identity, encrypted by the password, on the SSKS server
await seald.ssksPassword.saveIdentity({
  userId: 'myUserId',
  password: 'user-known-secret-password',
  identity: mySubIdentity
})

// Create a sub-identity
const { identity: mySubIdentity } = await seald.createSubIdentity()
// Save the new Seald identity, encrypted by the password, on the SSKS server
await seald.ssksPassword.saveIdentity({
  userId: 'myUserId',
  password: 'user-known-secret-password',
  identity: mySubIdentity
})

Retrieve the identity ​

To retrieve the identity at login, call the sdk.ssksPassword.retrieveIdentity function, with the same userId and password arguments as used in the save-identity.

const seald = SealdSDK({ appId, apiURL, plugins: [SealdSDKPluginSSKSPassword(keyStorageURL)] })
await seald.initialize()
// Retrieve the password-encrypted Seald identity from the SSKS server
await seald.ssksPassword.retrieveIdentity({
  userId: 'myUserId',
  password: 'user-known-secret-password'
})

const seald = SealdSDK({ appId, apiURL, plugins: [SealdSDKPluginSSKSPassword(keyStorageURL)] })
await seald.initialize()
// Retrieve the password-encrypted Seald identity from the SSKS server
await seald.ssksPassword.retrieveIdentity({
  userId: 'myUserId',
  password: 'user-known-secret-password'
})

The SDK instance is now ready to be used!

Change the password ​

When the user changes the password, you can use the sdk.ssksPassword.changeIdentityPassword function to have the identity stored with the new password and delete the one stored with the old one.

const seald = SealdSDK({ appId, apiURL, plugins: [SealdSDKPluginSSKSPassword(keyStorageURL)] })
await seald.initialize()
// Retrieve the Seald identity, encrypted with the old password, from the SSKS server
await seald.ssksPassword.retrieveIdentity({
  userId: 'myUserId',
  password: 'user-known-secret-password' // old password
})
// change the password
await seald.ssksPassword.changeIdentityPassword({
  userId: 'myUserId',
  currentPassword: 'user-known-secret-password', // old password
  newPassword: 'new-user-known-secret-password' // new password
})

const seald = SealdSDK({ appId, apiURL, plugins: [SealdSDKPluginSSKSPassword(keyStorageURL)] })
await seald.initialize()
// Retrieve the Seald identity, encrypted with the old password, from the SSKS server
await seald.ssksPassword.retrieveIdentity({
  userId: 'myUserId',
  password: 'user-known-secret-password' // old password
})
// change the password
await seald.ssksPassword.changeIdentityPassword({
  userId: 'myUserId',
  currentPassword: 'user-known-secret-password', // old password
  newPassword: 'new-user-known-secret-password' // new password
})

The password is now changed and only the new one can be used.

Password also used for authentication ​

In case you want to use the same password for identity protection as for authentication, it cannot be transmitted to the server as is, otherwise the server could then reconstruct the user's key, thus breaking the end-to-end encryption.

In this case, the login and account creation steps must be modified to introduce password pre-derivation using secure derivation functions so that your server never has access to the raw password, but only to a derived version.

You can find an example implementation here.

Customize the password derivation ​

As explained previously, the password provided by the user is derived into a "storage key", and an "encryption key". This derivation is done with scrypt.

For advanced use however, you can bypass this mechanism, and directly pass raw "storage key" and "encryption key" as arguments.

The storage key does not have to be secret from your server. It must however be unique, and secret from any other user, as it would allow the saved identity to be deleted. It must be a string, maximum 256 characters long, and composed of the following allowed characters: /A-Za-z0-9+\/=\-_@./.

For this, several strategies are possible:

• you can use a random string generated by the server, and simply pass it to the front-end
• you can also derive it from the password, potentially with another salt stored on the server

The encryption key, however, can only be known by the user in their frontend and must absolutely remain secret from any other actor, including your server. It must be the Base64 string encoding of a 64 bytes buffer. The usual way is to derive it from the password, if possible with a unique random salt generated and stored by your server.

Example of custom derivation of rawEncryptionKey with PBKDF2:

const PBKDF2 = require('pbkdf2')
const util = require('util')
const pbkdf2 = util.promisify(PBKDF2.pbkdf2)

const derivedKeyBuffer = await pbkdf2(userPassword, serverStoredSalt, 1, 64, 'sha512')
const derivedKey = derivedKeyBuffer.toString('base64')

await sdk.ssksPassword.saveIdentity({
  userId,
  // `rawEncryptionKey` format is strict :
  // it must be exactly 64 bytes, encoded as Base64
  rawEncryptionKey: derivedKey,

  // `rawStorageKey` is more lenient : it must be unique and secret,
  // but can be anything up to 256 characters long
  // Allowed characters : /A-Za-z0-9+\/=\-_@./
  rawStorageKey: serverStoredRawStorageKey
})

const PBKDF2 = require('pbkdf2')
const util = require('util')
const pbkdf2 = util.promisify(PBKDF2.pbkdf2)

const derivedKeyBuffer = await pbkdf2(userPassword, serverStoredSalt, 1, 64, 'sha512')
const derivedKey = derivedKeyBuffer.toString('base64')

await sdk.ssksPassword.saveIdentity({
  userId,
  // `rawEncryptionKey` format is strict :
  // it must be exactly 64 bytes, encoded as Base64
  rawEncryptionKey: derivedKey,

  // `rawStorageKey` is more lenient : it must be unique and secret,
  // but can be anything up to 256 characters long
  // Allowed characters : /A-Za-z0-9+\/=\-_@./
  rawStorageKey: serverStoredRawStorageKey
})

Protection with 2-man-rule ​

The 2-man-rule protection mode consists of "splitting" the identity to be protected in two and placing one half on the application's back-end subject to authentication, and the other half on Seald SDK Key Storage (SSKS) subject to independent authentication.

The goal is that a user has "the right" to lose all their passwords and all their devices without losing any data. The trade-off is that this mode is not strictly "end-to-end".

It is necessary to implement on the server side the storage of a secret stored and delivered against authentication, as well as an interaction with SSKS.

How it works ​

More specifically, to protect an identity, the protocol is as follows (in the normal case):

To retrieve an identity, the protocol is as follows:

Thus, if the backend is breached, the encryptedIdentity stored on SSKS will not be breached, and the backend cannot simulate an authentication to SSKS.

Conversely, if SSKS is breached, the twoManRuleKey will not be breached and SSKS cannot simulate authentication to the backend.

Protection of an identity ​

To use this method of protection, you must install, import & add when instantiating the SDK the @seald-io/sdk-plugin-ssks-2mr plugin.

Your application server must then :

• create a new user on SSKS by giving its email address ;
• generate an SSKS session for this user;
• generate a secret twoManRuleKey for this user (a sufficiently robust random string of characters, for example a UUID would be a good choice)
• transmit the sessionId and the secret twoManRuleKey to the front-end which we will symbolize by API.getSSKSSession() in the example.

The user can then store their identity using the sdk.ssks2MR.saveIdentity function.

You can find the SSKS API documentation for your application server here.

// Instantiate the SDK
const seald = SealdSDK({ appId, apiURL, plugins: [SealdSDKPluginSSKS2MR(keyStorageURL)] })
await seald.initialize()
// We create a Seald identity as seen in the first part
await seald.initiateIdentity({ signupJWT: 'signup-jwt-value' })

// We make an API call to the application server to get the `sessionId` and the `twoManRuleKey`.
const { sessionId, twoManRuleKey } = APIClient.getSSKSSession() // API endpoint to develop on your end

await seald.ssks2MR.saveIdentity({
  userId: 'myUserId',
  sessionId,
  // the user's email address must be repeated to avoid a MITM by your application server
  authFactor: {
    type: 'EM',
    value: 'user@domain.com'
  },
  twoManRuleKey // `twoManRuleKey` is the key stored by your application server to secure this user's identity
})

// Instantiate the SDK
const seald = SealdSDK({ appId, apiURL, plugins: [SealdSDKPluginSSKS2MR(keyStorageURL)] })
await seald.initialize()
// We create a Seald identity as seen in the first part
await seald.initiateIdentity({ signupJWT: 'signup-jwt-value' })

// We make an API call to the application server to get the `sessionId` and the `twoManRuleKey`.
const { sessionId, twoManRuleKey } = APIClient.getSSKSSession() // API endpoint to develop on your end

await seald.ssks2MR.saveIdentity({
  userId: 'myUserId',
  sessionId,
  // the user's email address must be repeated to avoid a MITM by your application server
  authFactor: {
    type: 'EM',
    value: 'user@domain.com'
  },
  twoManRuleKey // `twoManRuleKey` is the key stored by your application server to secure this user's identity
})

The identity is now saved.

// Create a sub-identity
const { identity: mySubIdentity } = await seald.createSubIdentity()
// Save the new Seald identity, encrypted by `twoManRuleKey`, on the SSKS server
await seald.ssks2MR.saveIdentity({
  userId: 'myUserId',
  sessionId,
  authFactor: {
    type: 'EM',
    value: 'user@domain.com'
  },
  twoManRuleKey,
  identity: mySubIdentity
})

// Create a sub-identity
const { identity: mySubIdentity } = await seald.createSubIdentity()
// Save the new Seald identity, encrypted by `twoManRuleKey`, on the SSKS server
await seald.ssks2MR.saveIdentity({
  userId: 'myUserId',
  sessionId,
  authFactor: {
    type: 'EM',
    value: 'user@domain.com'
  },
  twoManRuleKey,
  identity: mySubIdentity
})

Retrieving an identity ​

Then, upon a new instantiation of the SDK, your backend must generate in the same way a session for the user, and pass the sessionId and the twoManRuleKey to the front-end. The SSKS server then sends an email containing a challenge (valid for 6h) to the user's email address.

Then you need to call the function sdk.ssks2MR.retrieveIdentity with the arguments userId, sessionId, email, challenge and twoManRuleKey.

// We instantiate the SDK
const seald = SealdSDK({ appId, apiURL, plugins: [SealdSDKPluginSSKS2MR(keyStorageURL)] })
await seald.initialize()

// We make an API call to the application server to get the `sessionId` and the `twoManRuleKey`.
const { sessionId, twoManRuleKey } = APIClient.getSSKSSession() // API endpoint to develop on your end

/* an email is sent to the user containing a `challenge` valid for 6h */
/* ... */
/* the `challenge` is retrieved by the user and given in the page context */

await seald.ssks2MR.retrieveIdentity({
  userId: 'myUserId',
  sessionId,
  // the user's email address must be repeated to avoid a MITM by your application server
  authFactor: {
    type: 'EM',
    value: 'user@domain.com'
  },
  challenge: 'challenge sent by email',
  twoManRuleKey // `twoManRuleKey` is the key stored by your application server to secure this user's identity
})

// We instantiate the SDK
const seald = SealdSDK({ appId, apiURL, plugins: [SealdSDKPluginSSKS2MR(keyStorageURL)] })
await seald.initialize()

// We make an API call to the application server to get the `sessionId` and the `twoManRuleKey`.
const { sessionId, twoManRuleKey } = APIClient.getSSKSSession() // API endpoint to develop on your end

/* an email is sent to the user containing a `challenge` valid for 6h */
/* ... */
/* the `challenge` is retrieved by the user and given in the page context */

await seald.ssks2MR.retrieveIdentity({
  userId: 'myUserId',
  sessionId,
  // the user's email address must be repeated to avoid a MITM by your application server
  authFactor: {
    type: 'EM',
    value: 'user@domain.com'
  },
  challenge: 'challenge sent by email',
  twoManRuleKey // `twoManRuleKey` is the key stored by your application server to secure this user's identity
})

Your SDK instance is now ready to be used!

Changing a user's authFactor ​

In the user's lifecycle in your application, they may sometimes need to change their email address or phone number.

If this authentication factor is used to store their Seald identity onto SSKS, you will also need to re-register their identity on this new email address or phone number.

To do this, there is no specific API point in the SSKS server API or specific function in the SSKS plugin of the SDK. Simply store the user's identity on the new factor (if the identity is not present locally, you will need to retrieve it on the old authentication factor first), and then use the server API to delete the identity stored on the old factor.

Using a raw TwoManRule Key ​

When calling ssks2MR.saveIdentity or ssks2MR.retrieveIdentity, you can also replace twoManRuleKey with rawTwoManRuleKey.

Note that rawTwoManRuleKey must be the Base64 string encoding of a cryptographically random buffer of 64 bytes.

Technically, this avoids deriving the twoManRuleKey with scrypt, which improves the speed of execution.

If in doubt, use twoManRuleKey instead.

Using a rawTwoManRuleKey:

const seald = SealdSDK({ appId, apiURL, plugins: [SealdSDKPluginSSKS2MR(keyStorageURL)] })
await seald.initialize()

// Using a `rawTwoManRuleKey` with `ssks2MR.saveIdentity`
await sdk.ssks2MR.saveIdentity({
  userId,
  sessionId,
  authFactor,
  rawTwoManRuleKey: rawKey
})

// Using a `rawTwoManRuleKey` with `ssks2MR.retrieveIdentity`
await sdk.ssks2MR.retrieveIdentity({
  userId,
  sessionId,
  authFactor,
  challenge,
  rawTwoManRuleKey: rawKey
})

const seald = SealdSDK({ appId, apiURL, plugins: [SealdSDKPluginSSKS2MR(keyStorageURL)] })
await seald.initialize()

// Using a `rawTwoManRuleKey` with `ssks2MR.saveIdentity`
await sdk.ssks2MR.saveIdentity({
  userId,
  sessionId,
  authFactor,
  rawTwoManRuleKey: rawKey
})

// Using a `rawTwoManRuleKey` with `ssks2MR.retrieveIdentity`
await sdk.ssks2MR.retrieveIdentity({
  userId,
  sessionId,
  authFactor,
  challenge,
  rawTwoManRuleKey: rawKey
})

Generating a suitable rawTwoManRuleKey:

const crypto = require('crypto')
const util = require('util')
const randomBytes = util.promisify(crypto.randomBytes)

const rawKeyBuffer = await randomBytes(64)
// This format is strict : it must be exactly 64 bytes, encoded as Base64
// and must be from a cryptographically-safe random source
const rawKey = rawKeyBuffer.toString('base64')

const crypto = require('crypto')
const util = require('util')
const randomBytes = util.promisify(crypto.randomBytes)

const rawKeyBuffer = await randomBytes(64)
// This format is strict : it must be exactly 64 bytes, encoded as Base64
// and must be from a cryptographically-safe random source
const rawKey = rawKeyBuffer.toString('base64')

Manual export ​

It is also possible to manage the storage of an identity manually.

For this, you can use the sdk.exportIdentity and sdk.importIdentity functions.

sdk.exportIdentity allows you to export a Buffer containing the current identity of the SDK instance.

Conversely, sdk.importIdentity imports an identity Buffer in the SDK instance in order to make it functional.