Package Exports

@grizzlycbg/grizzly-sdk
@grizzlycbg/grizzly-sdk/index
@grizzlycbg/grizzly-sdk/index.js

Readme

Typescript SDK (Beta)

This SDK allows developers to encrypt/decrypt data using Grizzly's platform.

Install

Requirements:

NodeJS 20+

npm install @grizzlycbg/grizzly-sdk

Usage

To get started, you'll create a KeyClient. This client will connect to your tenant, and manage the resources there. The SDK manages Key caching and encrypting/decrypting data using NodeJS Streams.

To get started:

// Create a client
let client = await KeyClient.create({
   host: `https://your-tenant.grizzlycbg.io`,
   asymHost: `https://your-tenant.grizzlycbg.io/asym`,
   apikey: "apikey-123456-1234567890"
})

// Create a KeyRing. KeyRings are referenced by name.
let ring = await client.ring.create('Finance')

// Encrypt and decrypt data
let encrypted = await ring.encrypt("Secret Message")
let decrypted = await ring.decrypt(encrypted)

console.log(`Encrypted: ${encrypted}`)
console.log(`Decrypted: ${decrypted}`)

// You can manually rotate the keys if needed.
await ring.rotate()

// This is encrypted with the new set of keys
let world = await ring.encrypt("World!")

await ring.rotate()

let fish = await ring.encrypt("Fish were here!!")

await ring.rotate()

let dworld = await ring.decrypt(world)
let dfish = await ring.decrypt(fish)

// The client can also decrypt data without pulling the KeyRing (if using an Asym server)
await client.decrypt(encrypted)

Generating RSA Key Pairs

The Grizzly platform encrypts every KeyRing Key with the Public Key of an RSA Key Pair. You can supply your own Key Pair, or Grizzly can manage that for you. If you want provide your own Key Pair, this is something that you'll need to manage. We have some options for you if you want to go with a solution that is already built.

The Key Pair is expected to have the format:

Private Key: PKCS8 Type, PEM formatted
Public Key: PKCS1, PEM formatted

To generate the Key Pair using openssl:

# Generating a private key
ssh-keygen -t rsa -b 4096 -m PEM

# Generating both public and private keys
openssl genrsa -out pem 4096
openssl rsa -in pem -pubout -out pem.pub

KeyClient API

Properties

ring: IKeyRingWarden

Access to the KeyRingWarden. The KeyRingWarden manages the KeyRings.

Methods

encrypt(data: string | Buffer | Readable, keyring: string, options?: EncryptOptions): Promise<string | Buffer | Readable>

Encrypts data. Data can be a string, Buffer, or a Readable Stream.

data: The data to encrypt
keyring: The KeyRing name
options:
- asset: If using Asset Tagging, provide the tag here
- outFormat EncodingFormat enum. One of: string, buffer, or readale-stream
- inEncoding: Encoding enum. Specifies the incoming encoding. Setting this ensures that the SDK can properly work with the data that's being passed in.
- outEncoding: Encoding enum. Specifies the return value encoding.

decrypt(data: string | Buffer | Readable, privateKey?: string, options?: EncodingOptions): Promise<string | Buffer | Readable>

Decrypts data. There is no need to know which KeyRing was used to encrypt the data. The platform will manage that for you.

privateKey: The KeyRing's Private Key.
options:
- asset: If using Asset Tagging, provide the tag here
- outFormat EncodingFormat enum. One of: string, buffer, or readale-stream
- inEncoding: Encoding enum. Specifies the incoming encoding. Setting this ensures that the SDK can properly work with the data that's being passed in.
- outEncoding: Encoding enum. Specifies the return value encoding.

KeyRingWarden

create(name: string, options?: KeyRingCreateOptions): Promise<IKeyRing>

Creates a new KeyRing. All names must be unique.

name: (required; string) The KeyRing name.
options: (optional; KeyRingCreateOptions) KeyRing creation options.
- algo: The Algorithm to use. AES-256 is the only Algorithm currently supported.
- config: The KeyRing config (see below)
- publicKey: The RSA Public Key
- privateKey:

The user has an the option of providing their own private/public key pair. If a public key is provided, the associated private key must also be provided. If neither are provided, a pair will be generated for you, using the options passed in the "privateKey" property. These keys will be used to encrypt/decrypt the Keys when stored.

export type KeyRingCreateOptions = {
   algo?: Algorithm        // The cryptographic Algorithm to use. Defaults to AES-256.
   publicKey?: string      // pem formatted public key
   config: {
      props?: GenericObject      // Additional properties added when a KeyRing is created
      key?: {                    // Key options
         props?: GenericObject;  // Additional properties added when Keys are created
      };
      algos: {                   // Algo specific configs
         aes256?: {           
               maxEncryptCount: number // Number of times to encrypt before rotating the Key
         };
      },
   },
   privateKey?: {          // Options for generating the private key. Passed to Node crypto.
      type: string         // Must be pkcs1 or pkcs8
      format: string       // Must be pem, der, or jwk
      cipher: string       // If provided, the private key will be encrypted with the cipher and passphrase
      passphrase: string   // Must be included with the "cipher" option
   } | string  // PEM formatted Key
}

delete(name: string): Promise<void>

Deletes a KeyRing by name.

name: {required; string} The KeyRing name.

**get(name: string): Promise<IKeyRing | undefined>**

Gets a KeyRing by name.

name: {required; string} The KeyRing name.

**getAll(): Promise<string[]>**

Gets all KeyRings.

getById(id: string): Promise<IKeyRing | undefined>

Gets a KeyRing by ID.

id: {required; string} The KeyRing ID.

KeyRing

Properties

readonly id: string: The KeyRing ID.

readonly name: string: The KeyRing name, lower cased.

readonly displayName: string: The KeyRing name with casing preserved.

readonly activeKey: Key: The active key.

Methods

decrypt(data: string | Buffer | Readable, options?: EncodingOptions): Promise<string | Buffer | Readable>

Decrypts the data.

data: (required; string | Buffer | Readable) The data can be provided in several ways. And if not specified, the return value Type will be the same as this data parameter.
options: (optional; EncodingOptions) Specify the return type.

encrypt(data: string | Buffer | Readable, options?: EncodingOptions): Promise<string | Buffer | Readable>

Encrypts the data based on the current active key.

data: (required; string | Buffer | Readable) The data can be provided in several ways. And if not specified, the return value Type will be the same as this data parameter.
options: (optional; EncodingOptions) Specify the return type.

getConfig(): Promise<KeyRingConfig>

Gets the KeyRing config for the KeyRing.

rotate(algo?: Algorithm): Promise<Key>

Rotates the underlying key. Most developers will never need to do this, but it is necessary to have when you want to partition keys based on a system event (ie like a user leaving a channel for a chat application).

algo: (optional; Algorithm) Can change the underlying algorithm. If not specified, retains the algorithm in use.

updateConfig(handler: KeyRingConfigUpdateHandler): Promise<void>

Updates the KeyRing's configuration.

handler: (required) The handler for changing the config.