2. Getting Started¶
Warning
Please be aware that the Jolocom library is still undergoing active development. All identities are currently anchored on the Rinkeby testnet. Please do not transfer any real ether to your Jolocom identity.
2.1. How to install the Jolocom library¶
To begin using the Jolocom protocol, first install the Jolocom library as a dependency in your project. You can use npm
or yarn
to do so:
# using npm
npm install jolocom-lib --save
# using yarn
yarn add jolocom-lib
2.2. Browser and React Native Environments¶
To use the library in a browser or react native environment, you also need some polyfills as some of the dependencies assume running in a node environment
# using npm
npm install --save vm-browserify crypto-browserify assert stream-browserify events
# using yarn
yarn add vm-browserify crypto-browserify assert stream-browserify events
Also, you will need to configure your bundler (webpack, parcel, metro, etc) with aliases for the modules named *-browserify
For React Native’s metro.config.js:
module.exports = {
resolver: {
extraNodeModules: {
// Polyfills for node libraries
"crypto": require.resolve("crypto-browserify"),
"stream": require.resolve("stream-browserify"),
"vm": require.resolve("vm-browserify")
}
},
}
Also process.version
must be defined, so you might need to just set it in your index file:
process.version = 'v11.13.0'
2.3. How to create a self-sovereign identity¶
In broad strokes, the creation of a self-sovereign identity comprises the following steps:
- Instantiate a
SoftwareKeyProvider
- Use the instantiated
keyProvider
to derive two keys, one to control your Jolocom identity, and another one to sign Ethereum transactions (e.g. for anchoring the identity, rotating keys, etc.) - Fuel the second derived key with enough Ether to pay for the transaction anchoring the identity
- Instantiate and use the
JolocomRegistry
to create and anchor the DID document on the Ethereum network
The following sections elaborate on these steps.
Instantiate the Key Provider class
The SoftwareKeyProvider
class abstracts all functionality related to deriving key pairs and creating / validating cryptographic signatures.
Currently two ways of instantiating the class are supported, namely using the constructor or using the static fromSeed
method:
import { JolocomLib } from 'jolocom-lib'
import { crypto } from 'crypto'
// Feel free to use a better rng module
const seed = crypto.randomBytes(32)
const password = 'secret'
const vaultedKeyProvider = JolocomLib.KeyProvider.fromSeed(seed, password)
In the snippet above the fromSeed
method is used. It takes the seed in cleartext, and a password that will be used as a key to encrypt the provided seed on the instance.
Note
The password must be 32 bytes long (the expected encoding is UTF-8). In case a password of a different length is provided (e.g. the example above), it will be hashed using sha256
internally before usage. An appropriate warning will be printed to the console.
The encrypted seed can be retrieved from the class instance using:
const encryptedSeed = vaultedKeyProvider.encryptedSeed
Note
The returned value is a 64 byte Buffer
, containing the initialization vector (IV) (16 bytes) concatenated with the ciphertext (48 bytes). aes-256-cbc
is used for encryption.
The alternative way to instantiate the class by using it’s constructor:
import { JolocomLib } from 'jolocom-lib'
const vaultedKeyProvider = new JolocomLib.KeyProvider(encryptedSeed)
Note
The expected value for encryptedSeed
is a 64 byte Buffer
, containing the initialization vector (IV) (16 bytes) concatenated with the ciphertext (48 bytes). aes-256-cbc
will be used for decryption.
Derive a key to sign the Ethereum transaction
The vaultedKeyProvider
just instantiated can be used to derive further key pairs necessary to complete the registration.
We need to derive a key for signing the Ethereum transaction, which anchors the newly created identity.
const publicEthKey = vaultedKeyProvider.getPublicKey({
encryptionPass: secret
derivationPath: JolocomLib.KeyTypes.ethereumKey // "m/44'/60'/0'/0/0"
})
See also
In the event that one of your keys becomes compromised, you only lose that one key. All other derived keys (including the most important master key) remain secure. Go to BIP-32 if you want to find out more about this derivation scheme. We are currently looking at key recovery solutions in case the master key itself is compromised.
The only arguments that need to be passed to getPublicKey
are the derivationPath
, in the format defined in BIP-32, and the encryptionPass
that was used to create the encryption cipher.
The Jolocom library comes equipped with a few predefined paths for generating specific key pairs. The list will expand as new use cases are explored. You can view the available paths as follows:
console.log(JolocomLib.KeyTypes)
The next step involves transferring a small amount of ether to the Rinkeby address corresponding to the created key pair.
Transferring ether to the key
In order to anchor the identity on the Ethereum network, a transaction must be assembled and broadcasted. In order to pay for the assembly and broadcasting, a small amount of ether needs to be present on the signing key. There are a few ways to receive ether on the Rinkeby test network, and the library also expose a helper function to assist:
await JolocomLib.util.fuelKeyWithEther(publicEthKey)
This will send a request to a fueling service Jolocom is currently hosting.
Anchoring the identity
The final step to creating a self-sovereign identity is anchoring the identity on Ethereum and storing the newly created DID document on IPFS.
For these purposes, the JolocomRegistry
can be used; it is essentially an implementation of a DID resolver.
The creation would look as follows:
const registry = JolocomLib.registries.jolocom.create()
await registry.create(vaultedKeyProvider, secret)
Behind the scenes, two key pairs are derived from the seed. The first key is used to derive the DID and create a corresponding DID document. The second key is used to sign the Ethereum transaction, adding the new DID to the registry smart contract.
Note
We intend to add support for executable signed messages in the next major release, thereby eliminating the need to derive two key pairs.
2.4. Using the identity¶
The create
function presented in the previous section eventually returns an instance of the IdentityWallet
class, which can be used
to authenticate against services, issue credentials, and request data from other identities.
Later sections will explore the exposed interface in more detail.
In case you have already created your identity, and would like to instantiate an IdentityWallet
, you can
simply run:
/**
* You will need to instantiate a Key Provider using the seed used for identity creation
* We are currently working on simplifying, and optimising this part of the api
*/
const registry = JolocomLib.registries.jolocom.create()
const IdentityWallet = await registry.authenticate(vaultedKeyProvider, {
derivationPath: JolocomLib.KeyTypes.jolocomIdentityKey,
encryptionPass: secret
})
2.5. What can I do now?¶
So far, you have successfully created and anchored a digital self-sovereign identity. The subsequent sections cover how to:
- create a public profile and make it available through your DID document;
- issue statements about yourself and others in form of signed verifiable credentials;
- authenticate against other identities, share and receive signed verifiable credentials, and create various interaction tokens;
- use custom connectors for IPFS and Ethereum communication.