Cipherlib User Reference (Javascript/nodejs)

April 28, 2025

rev 0.2.0

Introduction

Cipherlib is an Application Programming Interface (API) for nodejs and python3. The API provides cryptographic functions (Methods and Objects) that encrypt plaintext (non-ciphered data) and decrypt ciphertext (encrypted AEAD data) generated by the API.

The API supports AEAD (Authenticated Encryption with Associated Data) based on RFC 5116.

AEAD provides authenticated encryption and the ability to check the integrity and authentication of additional authenticated data (AAD) that is sent without encryption (text sent in the clear).

For background, early work on AEAD was initiated in 2007 with NIST's guidance in their publication 800-38D, "Recommendation for Block Cipher Modes of Operation: Galois/Counter Mode (GCM) and GMAC."

CipherLib supports both CCM (Cipher Counter block chaining mode) and GCM algorithms as defined in RFC 5084 and RFC 7714 with support for AES-128 and AES-256. The default is GCM AES-128 though via an option parameter can be set to preferred. (See Class Method Options below.)

Audience

This document is intended for software designers, architects, and programmers using Javascript programming language via nodejs.

A companion version of this document is available for Python developers.

API Dependencies

node_module dependencies via npm

	use-strict module
	
	

Class Library Example

const CipherLib = require( 'cipherlib' );

async function main() {

	const cipherlib = new CipherLib.CipherLib( );
	
	try { var Payload = await cipherlib.textEncrypt( "Hello World", { "encode":"hex" } ) }
		catch( err ) {
			console.log( err.message );
			process.exit(1);
		};
		
	console.log( Payload );

}

main()

CipherLib Class Methods

Method Promise

textEncrypt( plaintext, { Options: Parameter, ...} ): ( Error, Payload )

payloadDecrypt( Payload, { Options: Parameter, ...} ): ( Error, plaintext )

getAAD ( Payload, { Options: Parameter, ...} ): ( Error, AADtext )

getAuthTag ( Payload, { Options: Parameter, ...} ): ( Error, AuthTag )

authPayload( Payload, AuthTag [, AAD] ): ( Error, Boolean )

resetDefaults( { Options: Parameter, ...} ): ( Error, Boolean )

Events

No generated events. 

Constructors/Prototypes

The constructor allows setting/overriding default options.  

Example, sets the default masterkey file:  

	const CipherLib = require( '../cipherlib' ); 
	
	const cipherlib = new CipherLib.CipherLib( { keyfilepath: '~/mymasterkeyfile' } );
	
		

Class Objects and descriptions

Object Type Description/Details

aad or AAD AEAD Associated data - Variable length (0 up to 2^32 bytes)

				{ aad: 'text is authenticated and stored unencrypted in Payload' }

AuthTag 16 bytes - generated by the cipher algorithm

Ciphertext Variable lengthnciphered plaintext data (1 up to 2*32 bytes)

Nonce 16 bytes padded per PKCS#7

Options aka method options: { optionName: 'optionParameter' } { keyfilepath: '~/mymasterkeyfile' }

Payload Structure for storing AEAD data including: Nonce, Ciphertext, AAD, AuthTag