The Xecret.io SDK contains functions for protecting sensitive end user secrets including passwords and cryptocurrency wallet passphrases. The SDK is made available to integration partners by permission, and usually consists of a Node.js compatible module to be imported and invoked by partners’ applications.
There are two symmetrical uses of the Xecret.io SDK: to generate cryptographic slices of a user’s secret in the form of printable pages, and to scan those pages later and recover the user’s secret.
Creation of the printable slice pages involves invoking Xecret.io functions to create an SVG or optionally a bitmap image of the pages. Following best practices, the user should be prompted to print these out as hard copy, although it is also possible to share the images on preferably separate and secure communication channels.
Recovery of the secret from the slices involves use of a device’s camera to scan QR codes. The Xecret.io SDK provides a sample implementation to retrieve the encrypted data as would be taken from a scanned QR code, and feed it to the recovery algorithm. Once the threshold for recovery has been met, the plaintext secret is returned from the recovery function and can be displayed to the user, or employed immediately to unlock access to a wallet.
By using the Xecret.io SDK, your application can enable your user’s protection of sensitive secrets and passwords or phrases to go to the next level, including powerful new options for dispersing the secret to more than one location – not merely for backup but also to apply the innovative concept of decentralization of trust.
A Secure QR Slice or Share is a page generated by your application using the Xecret.io SDK, that encodes cryptographic ciphertext in the form of a scannable QR code. The code is not human readable, and even if a person scanned the code with another app, the result would not be readable. In fact, due to Xecret.io’s cryptographic approach, a single share contributes nothing useful to an attacker attempting to retrieve a secret.
A Secret is the text being protected by the Xecret.io SDK. It consists of text typed by an end user or generated by a wallet app as a new wallet protection passphrase.
A Share Threshold and Count refers to the number of different shares required to recover a secret, and the total number of shares generated. For example, if the threshold is two and the count is three, then three distinct share pages will be generated, of which any two can be used to recover the secret. By definition, if fewer shares than the threshold are in hand, the secret cannot be recovered. Even with a brute force approach, Xecret.io’s cryptographic algorithm is not subject to hacking.
Going Offline means disconnecting from the internet while performing sensitive operations. Xecret.io documents rigorous measures for users of our consumer protect to go offline when either generating secure slices, or recovering them. Because we never send the user’s secret over the wire, users can take the extra step for assurance of disconnecting from the internet to ensure absolute protection of their valuable secrets. This approach of not relying on a remote API enables Xecret.io to be a great fit with non-custodial wallets.
Secret Recovery is a multi step process of scanning QR codes from successive pages. As long as the threshold number of shares are scanned, the original secret can be cryptographically recovered. If fewer shares are scanned, or if shares from different Xecret sets are scanned by accident, the SDK’s functions will return an error; it is the responsibility of the integrating app to display feedback to the user.
| Approximate number of hours to implement creation of secure QR slices from a Secret text with threshold recovery | 18 |
| Approximate number of hours to implement crypto payment portal (UI not included) | 3 |
To make use of the Xecret.io SDK, perform the following steps:
Extract the SDK javascript module into your application’s Node.js javascript source. There is a single javascript file required to integrate the SDK, named xecret.js. You will import it to your program and invoke its functions in the same way as the example application.
Add an import of the Xecret.io module to your code.
Add invocation of the function to generate slices, along with code to handle dispatching of the generated slice pages either to the printer, or on secure channel(s).
Add invocation of the functions for recovery of slices, using the slice text retrieved by QR Code scanning. Any common Node.js QR code camera integration will work for this, as will standard native libraries for iOS and Android app frameworks.
a. Pass the secure slice text to the Xecret.io SDK recovery function, and evaluate the result. If the secret is not recovered, then display the resultant message to the end user.
b. If more slices must be scanned, use the returned slices element to replace your slices, as it will be “cleaned up” from irrelevant or erroneous slices passed in. You should also provide an option to the user to reset and restart the scan from scratch.
c. When the secret is returned from the recovery function, handle it securely to unlock the wallet or display to the user, as appropriate.
Ensure user secrets are handled securely. If possible, especially in a non-custodial wallet, allow the user to perform these functions offline or in airplane mode. Be sure to clear variables or other memory or cache when done performing secure functions on behalf of the user.
An example is included with the Xecret SDK, tailored for React Native. This example is under the XecretDemo folder. This minimalist React Native app allows a user to type a text secret, such as a seed phrase, then generate QR code slices.
The app shows how to take the slice text from the SDK and use common javascript libraries to render the slice as a graphical QR image. This image can be printed (see react-native-print npm module) or copied to the clipboard for pasting in a secure channel (see react-native-copy-image on Github).
The app also shows how slices can be fed back into the SDK's functions to recover the original secret for a full round trip.
All materials in this SDK are confidential and protected by copyright. This SDK is not open source or public domain. These materials are provided to approved parties to integrate into specific approved apps, subject to all terms of the license agreement. Integration in your app requires compliance with all terms of the license agreement, including facilitation of payment by end users prior to making use of Xecret features. Consult your license agreement, which is provided separately, for details.
| Name | Number of Slices | Price | Recovery Attempts | Redundancy | Variable Threshold |
|---|---|---|---|---|---|
| Free | 2-Slices | Free | Unlimited | ||
| Basic | 3-Slices | $9.99 | Unlimited | ||
| Professional | 5-Slices | $99 | Unlimited | ||
| Corporate | 7-Slices | $499 | Unlimited | ||
| Whale | 11-Slices | $2,499 | Unlimited |
Represents a single encrypted slice or share
new RecoveryShare()
ShareIdx :number
- The index counting from 0 of this share, as originally generated. It is important to recover a secret using the original indexes of any used shares.
ShareIdx :number
The XecretAlgo class provides access to the Xecret algorithm for splitting and joining secure, distributed shares of a protected secret.
new XecretAlgo(k, n, minLengthResolution)
Constructs a XecretAlgo instance with defined parameters.
| Name | Type | Description |
|---|---|---|
| k | number | The threshold of shares required to recover a secret, e.g. 2 for 2 of 3. |
| n | number | The total number of shares generated, e.g. 3 for 2 of 3. |
| minLengthResolution | number | always set to 128. |
RecoverSecret(shares)
Recovers a secret from a threshold of available shares.
Parameters:
| Name | Type | Description |
|---|---|---|
| Shares | Array. < Recovery Share> | The ciphertext shares or slices from which the secret is to be recovered. |
Returns:
- A byte array
SplitSecret(secret, crypto) → {Array.<RecoveryShare>}
Generates separate shares as byte arrays, based on a byte array input.
Parameters:
| Name | Type | Description |
|---|---|---|
| Secret | string | The secret or plaintext to be protected, given as a byte array. |
| crypto | object | The crypto module to be used by the algorithm. This module or object must expose a function getRandomValues(arr) that populates the provided array with strongly random values. |
Returns:
- an array of share objects.
Type
Array.<RecoveryShare>
b45decode(str, a) → {uint8array}
Transforms the base45 encoded string provided into a byte array.
Parameters:
| Name | Type | Description |
|---|---|---|
| str | string | The base 45 string. |
| a | Object | Buffer module with a from(bytes) method that can transform a byte array into a string. |
Returns:
- a list of bytes self-describing a share, as used by serializeShare and deserializeShare.
Type
uint8array
b45encode(buffer) → {String}
Transforms bytes provided into a base 45 string suitable for use in a QR code.
Parameters:
| Name | Type | Description |
|---|---|---|
| buffer | unit8array | a list of bytes self-describing a share, as output by serializeShare. |
- a base 45 encoded string of the bytes passed in.
Type
string
deserializeShare(buffer) → {Array}
Accepts an .
Parameters:
| Name | Type | Description |
|---|---|---|
| buffer | unit8array | a list of bytes self-describing a share, as output by serializeShare. |
- an array containing [magicNumber, n, k, shareId, UUID, payload] as described in serializeShare().
Type
Array
serializeShare(magicNumber, n, k, shareId, UUID, payload) → {Array}
Prepares a ciphertext slice or share for the QR code format by flattening it into a consistent byte array structure.
Parameters:
| Name | Type | Description |
|---|---|---|
| magicNumber | number | A constant number used to recognize QR codes created by us (should always be 123456789). |
| n | number | The number of shares in this set, e.g. 3 for 2 of 3. |
| k | number | The recovery threshold of shares in this set, e.g. 2 for 2 of 3. |
| shareId | number | The zero based index of this share. |
| UUID | unit8array | A random set ID for this entire set. Send the same value for all shares of a set, and generate a new random UUID for any new set. |
| payload | unit8array | The byte list containing the encrypted slice or share. |
Returns:
- A byte array containing the flattened or serialized array of bytes self-describing this share.
Type
uint8array