Cribl - Docs

Getting started with Cribl LogStream

Questions? We'd love to help you! Meet us in #cribl (sign up)

Changelog    Guides

Encryption

Encryption of data in motion

With Cribl you can encrypt fields or patterns within events in real-time using C.Crypto.encrypt() in a Mask function. The Mask function accepts multiple replacement rules and multiple fields to apply them to. A Match Regex defines the pattern that describes the content to be replaced. The Replace Expression is a JS expression or literal to replace matched content. C.Crypto.encrypt() method can be used here to generate an encrypted string from a value passed to it.

C.Crypto.encrypt() Syntax

(method) Crypto.encrypt(value: any, keyclass: number, keyId?: string, defaultVal?: string): string
Encrypt the given value with the keyId or a keyId picked up automatically based on keyclass
@param {string | Buffer} value - what to encrypt
@param - keyclass - if keyId isn't specified, pick one at the given key class
@param - keyId - encryption keyId, takes precedence over keyclass
@param - defaultVal - what to return if encryptions fails for any reason, if unspecified the original value is returned
@returns - - if encryption succeeds the encrypted value, otherwise defaultVal if specified, otherwise value.

Encryption Keys

Symmetric key encryption keys can be configured through the CLI or UI. Users are free to define as many keys as required. Each key is characterized by the following:
keyId: ID of the key.
algorithm: Algorithm used with the key
keyclass: Cribl Key Class (below) that the key belongs to.
kms: Key management system for the key. Defaults to local.
created: Time (epoch) when key was generated.
expires: Time (epoch) after which the key is invalid. Useful for key rotation.
useIV: Flag that indicates whether or not an initialization vector was used.

Key Classes

Key Classes in Cribl are collection of keys that can be used to implement multiple levels of access control. Users or groups of users with access to data with encrypted patterns can be associated with key classes for even more granular, pattern-level compartmentalized access.

Example
Users U0, U1 have been given access to keyclass 0 which contains key id 0 and 1. These keys are used to encrypt certain patterns in datasetA. Even though users U0, U1, U2 have access to read this dataset, only U0 and U1 can decrypt its encrypted patterns.

Key Class
Dataset

keyclass: 0
Keys: keyId: 0, keyId: 1
Users: U0, U1

datasetA
Users: U0, U1, U2

User U1 has been given access to an additional keyclass, 1 which contains key id 11 and 22. These keys are used to encrypt certain other patterns in datasetA. Even though users U0, U1, U2 have access to read this dataset - same to above - only U1 can decrypt the additional encrypted patterns.

Key Class
Dataset

keyclass: 1
Keys: keyId: 11, keyId: 22
Users: U1

datasetA
Users: U0, U1, U2

Configuring Keys with CLI

When using the local key management system, encryption keys in Cribl are encrypted with $CRIBL_HOME/local/cribl/auth/cribl.secret and stored in $CRIBL_HOME/local/cribl/auth/keys.json. Keys are added and listed using the keys command.

Note 1: If you're running Cribl as an app in a Splunk Heavy Forwarder and you don't have Nodejs installed in your system, you can use the one that Splunk ships with. If that's the case, instead of using node ..., start the commands below with: $SPLUNK_HOME/bin/splunk cmd node --harmony ...

Note 2: When installed as a Splunk app, $CRIBL_HOME is $SPLUNK_HOME/etc/apps/cribl

Cribl monitors keys.json file for changes every 60 seconds.

Listing keys
node $CRIBL_HOME/bin/cribl.bundle.js keys list

keyId  algorithm    keyclass  kms    created         expires     useIV
-----------------------------------------------------------------------
1      aes-256-cbc  0         local  1544906269.316  0           false
2      aes-256-cbc  1         local  1544906272.452  0           false
3      aes-256-cbc  2         local  1544906275.948  1545906275  true
4      aes-256-cbc  3         local  1544906278.026  0           false

Adding keys:

Displaying --help
node $CRIBL_HOME/bin/cribl.bundle.js keys add --help

Add encryption keys
Usage: [options] [args]

Options:
-c <keyclass> - key class to set for the key
-k <kms>      - KMS to use, must be configured, see cribl.yml
-e <expires>  - expiration time, epoch time
-i            - use an initialization vector

Adding a key to keyclass 1 with no expiration date.
node $CRIBL_HOME/bin/cribl.bundle.js keys add -c 1 -i

Adding key: success. Key count=1

Listing keys to verify key generation
node $CRIBL_HOME/bin/cribl.bundle.js keys list

keyId  algorithm    keyclass  kms    created         expires     useIV
-----------------------------------------------------------------------
1      aes-256-cbc  1         local  1545243364.342  0           true

Configuring Keys with UI

The key management interface can be accessed through Data Security | Encryption Keys . Here you can list and add new keys. To protect against accidental changes, once saved a key's parameters can only be edit through configuration files.

Sync auth/(cribl.secret|keys.json)

To successfully decrypt data, the decrypt command will need access to the same keys that were used to encrypt. cribl.secret and keys.json in $CRIBL_HOME/local/cribl/auth in the Cribl instance where encryption happened should be synced/copied over to the one on the Search Head/decrypting side. When using the UI, these files can be downloaded through the Get Key Bundle button.

Encryption


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.