WFJSL Cryptographic Functions

Overview

The Whiteflag JavaScript Library (WFJSL) is an implementation of the Whiteflag Protocol written in TypeScript, and compiled to JavaScript, to support the development of Whiteflag-enabled applications in JavaScript.

The @whiteflagprotocol/crypto package provides cryptographic functions for other Whiteflag packages. Therefore, it should normally not be necessary to add this package as a dependency.

The WFJSL uses the Web Crypto API for the basic implementation of Whiteflag cryptographic functions, such as secret negotiation, encryption, and authentication. Putting these critical security functions in a separate package makes them better inspectable, testable and maintainable.

Most cryptography functions are asynchronous and return a Promise.

This description provides a generic overview of the WFJSL cryptography package. Please see the WFJSL TypeDoc documentation for a detailed description of all classes and functions.

Hashing

The Whiteflag cryptography package provides three hashing functions with the hash module:

| Function | Purpose | |----------|---------------------------------------------------------------------------| | hkdf | Hash-based Key Derivation Function using SHA-256 i.a.w. RFC 5869 | | hash | Basic hashing function, using SHA-256 as default | | hmac | Hash-Based Message Authentication Code function, using SHA-256 as default |

The hkdf function is used by Whiteflag to derive encryption keys and authentication tokens and bind them to the blockchain address of a specific originator. The hash and hmac functions are wrappers easy common access to the underlying algorithms through the Web Crypto API; they are used by the hkdf function, but may also be used for other functionality as required.

Encryption

The Whiteflag cryptography package provides the following functions for message encryption with the cipher module:

| Function | Purpose | |-------------|---------------------------------------------------------------------------------------| | encrypt | Encrypts a binary encoded Whiteflag message, based on the Whiteflag encryption method | | decrypt | Decrypts a binary encoded Whiteflag message, based on the Whiteflag encryption method | | deriveKey | Derives the encryption key based on the Whiteflag encryption method |

The encrypt and decrypt functions take a binary encoded Whiteflag message, along with a number of encryption parameters such as the encryption key, to perform the encryption and decryption of messages.

The deriveKey function uses the hkdf function with the input key material, information parameter, salt, and key length for the encryption method, to generate the Web Crypto API encryption key to be used with the encrypt and decrypt functions i.a.w. the Whiteflag standard.

The Whiteflag encryption methods are defined by the WfCryptoMethod enum.

Cryptographic Keys

The Whiteflag cryptography package provides the following functions for key generation with the keys module:

| Function | Purpose | |-----------------|----------------------------------------------| | createAesKey | Creates an AES encryption and decryption key | | createHmacKey | Creates an HMAC signing key |

All key generation functions create a Web Crypto API CryptoKey object, typically from a raw key generated or provided elsewhere. These keys are primarily intended to provide the correct Web Crypto API keys to other functions of the cryptography package.