imicros-keys

Moleculer service for the imicros key store

Installation

$ npm install imicros-keys --save

Dependencies

Requires a running Redis Instance.

Usage Keys Service

Set the master token as environment variable

process.env.MASTER_TOKEN = "MCN`1T-:,P41!QQ"

const { ServiceBroker } = require("moleculer");
const { Master } = require("imicros-keys");
 
broker = new ServiceBroker({
    logger: console
});
broker.createService(Master, Object.assign({ 
    settings: {
        redis: {
            port: process.env.REDIS_PORT || 6379,
            host: process.env.REDIS_HOST || "127.0.0.1",
            password: process.env.REDIS_AUTH || "",
            db: process.env.REDIS_DB || 0,
        },
        expirationDays: 30  // rotate key after 30 days
    }
}));
broker.start();
 

The keys service is not started directly - the master service will create it after unsealing. After the first start call master.init to generate a new master key and retrieve the secret shares and the verifcation hash.

Keep the shares as well as the verification hash very save as the master key cannot be changed!

The following steps must be done after each restart:

• set the verfication hash for each sealed node with master.setVerifyHash. Alternatively you can set the environment variable process.env.MASTER_HASH, as you know it after the first init call.
• call master.unseal with the different shares until the required number of shares is reached When the required number of shares is reached the node is unsealed and the keys service is started automatically.

Services can now retrieve their secret keys with calling keys.getOek.

Actions master service

init { token } => { shares, verifyHash } 
setVerifyHash { nodeID, token, verifyHash } => { verifyHash } 
unseal { nodeID, token, share } => { received }
isSealed => true|false
getSealed { token } => { sealed:Array<String> }
getMasterKey { token } => masterKey  - only local calls!

Actions key service

getOek { service, id } => { id, key }
owners => [ owner id's ]

init

Called only once for all key services to retrieve shares and the verification hash. It generates a new master key and split it into the secret shares. These shares and the verification hash must be used for unsealing all running key services. Never change them in a running system with existing keys in the database!

let param = {
    token: "my secret master token"
}
broker.call("master.init", param).then(res => {
    // res.shares -> array of secret shares
    // res.verifyHash -> combined hash/salt
})

getSealed

Returns an array of node ID's of sealed nodes. If all nodes are unsealed, the array is empty.

let param = {
    token: "my secret master token"
}
broker.call("master.getSealed", param).then(res => {
    // res.sealed -> array of node ID's
})

setVerifyHash

Set the verification hash for sealed nodes. Must be called for each sealed node with the related node ID.

let param = {
    nodeID: "...",          // as retrieved by master.getSealed
    token: "my secret master token",
    verifyHash: "..."       // as retrived by master.init
}
broker.call("master.setVerifyHash", param).then(res => {
    // res.verifyHash -> in case of success: same value as transferred
})

unseal

Set a share for reconstruction of the master key and unsealing the node. Must be called for each sealed node ID with different shares until the required number of shares is reached. When the required number is reached the node is automatically unsealed and the key service is started.

let param = {
    nodeID: "...",          // as retrieved by master.getSealed
    token: "my secret master token",
    share: "..."            // as retrived by master.init
}
broker.call("master.unseal", param).then(res => {
    // res.retrieved -> number of retrieved (different) shares
})

getOek

This method is called by other services to obtain their private key for encryption. It is called without ID to get the default key for encryption. After reaching the expiration date (according to the expiration days in the settings) a new default private key is generated. The retrieved ID has to be stored with the encrypted object and has to be given with the new retrieval to get the correct key for decryption.

let params = {
    service: "my service",                      // name of my service
    id: "35e53e27-3d91-4524-8c40-80566546f536"  // optional: getting the right key for decryption
},
broker.call("keys.getOek", param).then(res => {
    // res.id -> uuid of the key
    // res.key -> key
})