Skip to content

SDK: Getting Started

The Grizzly SDK provides a JavaScript/TypeScript library for encrypting and decrypting data in your Node.js applications. The SDK manages key caching, handles encryption operations using Node.js streams, and abstracts away the complexity of working with the Grizzly platform.

Installation

Requirements

  • Node.js 20 or higher
  • Access to a Grizzly platform instance
  • An API Key with appropriate permissions

Install via npm

npm install @grizzlycbg/grizzly-sdk

Quick Start

The SDK revolves around the KeyClient, which connects to your Grizzly instance and manages all encryption operations.

Basic Example 
import { KeyClient } from '@grizzlycbg/grizzly-sdk'

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

// Create a KeyRing
const ring = await client.ring.create('Finance')

// Encrypt data
const encrypted = await ring.encrypt('Secret Message')

// Decrypt data
const decrypted = await ring.decrypt(encrypted)

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

Connection Options

The KeyClient.create() method accepts several configuration options:

Option Type Required Description
host string Yes* Base URL of your Grizzly instance
asymHost string No URL for the Asymmetric Key Service (defaults to {host}/asym)
apikey string Yes* API Key for authentication
keycache.max number No Maximum number of cached keys (default: unlimited)

Required when using REST connections

Advanced Configuration **Key Caching** 
const client = await KeyClient.create({
   host: 'https://your-tenant.grizzlycbg.io',
   apikey: 'apikey-123456-1234567890',
   keycache: {
      max: 100  // Cache up to 100 keys in memory
   }
})

Working with KeyRings

KeyRings organize encryption keys into logical groups. Each KeyRing has a unique name and manages its own set of keys.

Creating a KeyRing 
// Create with default settings (Grizzly-managed keys)
const ring = await client.ring.create('TeamA')

// Create with custom configuration
const ring = await client.ring.create('TeamB', {
   config: {
      algos: {
         aes256: {
            maxEncryptCount: 10000  // Rotate after 10k encryptions
         }
      }
   }
})
Accessing Existing KeyRings 
// Get by name
const ring = await client.ring.get('TeamA')

// Get by ID
const ring = await client.ring.getById('ring-123456')

// List all KeyRing names
const rings = await client.ring.getAll()
console.log(rings)  // ['TeamA', 'TeamB', 'Finance']
Deleting a KeyRing 
await client.ring.delete('TeamA')

Encrypting & Decrypting Data

The SDK supports encrypting strings, Buffers, and Node.js Readable streams.

String Encryption 
const ring = await client.ring.get('Finance')

// Encrypt
const encrypted = await ring.encrypt('Sensitive data')

// Decrypt
const decrypted = await ring.decrypt(encrypted)
Buffer Encryption 
const data = Buffer.from('Binary data', 'utf-8')

const encrypted = await ring.encrypt(data)
const decrypted = await ring.decrypt(encrypted)
Stream Encryption (Large Files) 
import fs from 'fs'

const ring = await client.ring.get('Documents')

// Encrypt a file stream
const readStream = fs.createReadStream('/path/to/large-file.pdf')
const encryptedStream = await ring.encrypt(readStream)

// Write encrypted stream to file
encryptedStream.pipe(fs.createWriteStream('/path/to/encrypted.bin'))

// Decrypt a file stream
const encryptedRead = fs.createReadStream('/path/to/encrypted.bin')
const decryptedStream = await ring.decrypt(encryptedRead)

decryptedStream.pipe(fs.createWriteStream('/path/to/decrypted.pdf'))

Decrypting Without KeyRing Reference

The SDK can decrypt data without knowing which KeyRing was used. The platform determines the correct KeyRing from the encrypted data's header.

Client-Level Decryption 
// Encrypt with a KeyRing
const ring = await client.ring.get('Finance')
const encrypted = await ring.encrypt('Secret message')

// Decrypt at client level (no KeyRing needed)
const decrypted = await client.decrypt(encrypted)

console.log(decrypted)  // 'Secret message'

Key Rotation

Keys are automatically rotated based on KeyRing configuration. You can also manually rotate keys when needed.

Manual Key Rotation 
const ring = await client.ring.get('Finance')

// Rotate to a new key
await ring.rotate()

// New encryptions use the new key
const encrypted = await ring.encrypt('New data')

// Old encrypted data still decrypts correctly
const oldDecrypted = await ring.decrypt(oldEncryptedData)

Customer-Managed Keys

You can provide your own RSA key pair instead of using Grizzly-managed keys. This gives you complete control over key lifecycle.

Providing Your Own Key Pair

Generate RSA Key Pair (4096-bit)

# Using OpenSSL
openssl genrsa -out private.pem 4096
openssl rsa -in private.pem -pubout -out public.pem

Create KeyRing with Custom Keys

import fs from 'fs'

const publicKey = fs.readFileSync('./public.pem', 'utf-8')
const privateKey = fs.readFileSync('./private.pem', 'utf-8')

const ring = await client.ring.create('SecureTeam', {
   publicKey,
   privateKey
})

Next Steps