cipherlib/README.md

AEAD Cryptographic Library

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		<Bytes>		AEAD Associated data - Variable length (0 up to 2^32 bytes)
	
					{ aad: 'text is authenticated and stored unencrypted in Payload' }
	
AuthTag			<Bytes>		16 bytes - generated by the cipher algorithm
	
Ciphertext		<Bytes>		Variable lengthnciphered plaintext data (1 up to 2*32 bytes)
	
Nonce			<Bytes>		16 bytes padded per PKCS#7 
	
Options			<Object>	aka method options: { optionName: 'optionParameter' }
							     { keyfilepath: '~/mymasterkeyfile' }
	
Payload			<Object>		Structure for storing AEAD data including: Nonce,
						Ciphertext, AAD, AuthTag