gnablib

gnablib

A lean, zero dependency library to provide a useful base for your project. Checksums, cryptography, codecs, date-times, error-checking-codes, logging, pseudorandom number generation. The tools you need for any project. Secure build pipeline, provenance signed and typed.

Installation

This module is available through NPM. There are no install scripts, decrease your risk by explicitly preventing (--ignore-scripts)

(pnpm|npm) install gnablib --ignore-scripts

To verify provenance:

npm audit signatures

Details

Augmented Backus-Naur Form /rfc5234

• Operators
• Definition of core rules

Algorithms

• Weighted Random Sampling
• Next power of 2 32bit
• Bits set 32bit
• Count leading zeros (CLZ) 32bit
• Thomson NFA (1968) solver

Checksum/Hash

A checksum; can be used to prevent/identify accidental changes. A hash; maps some data to another, often used for hash tables, or to speed up comparison.

Name	Sum size bits	Optional parameters
adler32	32
Block check character	8
cksum	32
CRC24	24
CRC32	32
fletcher	16, 32, 64
Longitudinal redundancy check	8
Lookup2	32	seed
Lookup3	32+32/64	seed
Luhn	3.5
MD5Sum	128
Murmur3	32	seed
SHA1Sum	160
Spooky v2	128	seed
xxHash	32, 64	seed

Command Line Interface (cli)

• Argument and option parsing
• Foreground, background color (8 color, 213 color, 16M colors)
• Underline, bold, faint, italic, blink, invert, hide, strike-through, overline text styles
• Terminal controls & style (cursor move, screen/line clear)

Codec

• ASCII85
• Base32, zBase32, Base32Hex, Crockford32
• Base64, Base64url, B64
• bfloat16
• Densely Packed Decimal
• Hex
• IEEE754 Binary
• Proquint
• QuotedPrintable
• ROT13, ROT13.5, ROT47
• URI
• UTF8
• uuencode
• UUID
• YEnc

Crypto

Block

• Cipher Block Chaining (CBC)
• Cipher FeedBack (CFB)
• Counter (CTR)
• Electronic CodeBook (ECB)
• Output FeedBack (OFB)

CBC or CTR are recommended by Niels Ferguson and Bruce Schneier. ECB should not be used.

Padding

• ANSI X9.23 / ISO 10126 padding
• ISO 7816-4 padding
• ISO 9797-1 padding 2
• PKCS#7 / PKCS#5 padding
• Zero / Null padding

Symmetric

Name	Block size	Key size	Nonce size	Features
Advanced Encryption Standard (AES)	16	16, 24, 32	0
Ascon-128	8	16	16	AEAD
Ascon-128a	16	16	16	AEAD
Ascon-80pq	8	20	16	AEAD, Resistance to quantum adversary
Blowfish	8	4-56	0
ChaCha20	64	16, 32	12
ChaCha20-Poly1305	64	32	12	AEAD
Rabbit	16	16	0, 8
Salsa20	64	16, 32	8
Salsa20-Poly1305	64	32	12	AEAD
Twofish	16	16, 24, 32	0
XChaCha20	64	32	24
XChaCha20-Poly1305	64	32	24	AEAD
XSalsa20	64	16, 32	24
XSalsa20-Poly1305	64	32	24	AEAD

Secure Hash

Cryptography hash functions that have the properties:

• Finding an input string that matches a hash value (pre-image) is hard
• Finding a pair of messages that generate the same hash value (collision) is hard

Name	Digest sizes	Optional parameters
Ascon-Hash, Ascon-HashA	256	-
Blake	256, 512	salt
Blake2b	8-512, 256, 384, 512	key, salt, personalization
Blake2s	8-256, 224, 256	key, salt, personalization
Keccak	8-512, 224, 256, 384, 512	capacity
MD4†	128†	-
MD5†	128†	-
ParallelHash (128,256)	8-512	block size, customization
RipeMD†	128†, 160†, 256, 320	-
SHA-1†	160†	-
SHA-2	224, 256, 384, 512, 512/224, 512/256	-
SHA-3	224, 256, 384, 512	-
TupleHash (128, 256)	8-512	customization
Whirlpool	512	-

† No longer considered cryptographically safe

Key Derivation Function (KDF)

A cryptographic algorithm that derives one or more secret keys from a secret value. Can be used to stretch keys (make them longer), or obtain a key in a particular format (eg making a key a fixed length)

• HKDF
• PBKDF2 pbkdf2_hmac_sha1, pbkdf2_hmac_sha256, pbkdf2_hmac_sha512

Message Authentication Code (MAC)

Also known as an authentication tag, a short piece of information to authenticate a message. Protect integrity, and authenticity.

Name	Tag Size
CMAC	16 (AES)
HMAC	Depends on hash (Blake, Blake2, cShake, Keccak, MD4, MD5, RipeMD, Sha1, Sha2, Sha3, Shake, Whirlpool)
HopMAC	16 (Kangaroo Twelve)
KMAC	16, 32 (Keccak)
Poly1305	16

EXtendable-Output Function (XOF)

A secure hash that can produce output of any desired length.

Name	Capacities	Optional parameters
Ascon-Xof, Ascon-XofA	256	digest size
cShake	128, 256	digest size, function name, customization
KangarooTwelve	128	digest size, customization
KmacXof	128, 256	digest size, key, customization
ParallelHashXof	128, 256	block size, digest size, customization
Shake	128, 256	digest size
TupleHashXof	128, 256	digest size, customization
TurboSHAKE	128, 256	digest size, customization

DateTime

• Year, Month, Day
• Hour, Minute, Second, Millisecond, Microsecond
• DateTimeLocal, DateTimeUtc, DateOnly, TimeOnly
• Duration, DurationExact
• DateTime*.lt|lte|eq|gt|gte|neq - Compare two date-times
• DateTime*.add|sub - Add or subtract Duration|DurationExact from a date-time
• DateTime*.diff|diffExact - Get the difference between two dates in y/m/d/h/* or d/h/*

Error Correction Codes

• Reed Solomon

Endian

• Big
• Little

Net

• CIDR
• IPv4
• IpTree

Primitive

• Fixed TypedArray
• Int64
• Lazy
• Readonly TypedArray
• Scaling TypedArray
• StringBuilder
• UInt16, UInt32, UInt64, UInt128, UInt256, UInt512
• U32MutArra, U64MutArray
• UInt, UIntMut
• WindowStr

Extensions:

• Bit
• Int
• String
• Uint8Array

PseudoRandom number generators (PRNG)

Good PRNGs

Use one of these if you can, alphabetically sorted. gjrand32b is only somewhat official and doesn't have a lot of testing.

Name	Year	Variant	State (bytes)	‡	Range
GJRand	2005	~gjrand32b	16		U32
		gjrand64	32	‡	U64
Permuted Congruential Generator (PCG)	2014	pcg32	8	‡	U32
		pcgG64	16	‡	U64
Small Fast Counting (SFC)	2010	sfc16	8		U16
		sfc32	16		U32
		sfc64	32	‡	U64
SplitMix	2014	splitmix32	4		U32
		splitmix64	8	‡	U64
Tychei	2011	tychei	16		U32
Well equidistributed long-period linear (WELL)	2006	well512	64		U32
XoRoShiRo	2018	xoroshiro64*	8		U32
		xoroshiro64**	8		U32
		xoroshiro128+	16	‡	U64
		xoroshiro128++	16	‡	U64
		xoroshiro128**	16	‡	U64
XorShift+	2003	xorShift128+	16	‡	U64
XoShiRo	2018	xoshiro128+	16		U32
		xoshiro128++	16		U32
		xoshiro128**	16		U32
		xoshiro256+	32	‡	U64
		xoshiro256++	32	‡	U64
		xoshiro256**	32	‡	U64

‡: Uses U64 library to exceed JS 32bit integer constraint (may be slower)

U16 : [0 - 32767 | 0xFFFF]
U31 : [0 - 2147483647 | 0x7FFFFFFF]
U32 : [0 - 4294967295 | 0xFFFFFFFF]
U64 : [0 - 18446744073709551615 | 0xFFFFFFFFFFFFFFFF]

Poor PRNGs

Best not to use these, there are some dragons in these waters (so if you're choosing, be aware of the limitations). However, you might have a compatibility constraint (or love the name Mersenne Twister).

Name	Year	Variant	State (bytes)	Range
ARC4/RC4/Arcfour/Arc4random	1997	arc4	32	U8
Mersenne Twister	1998	mt19937	2496	U32
MulBerry32	2017	mulberry32	4	U32
XorShift	2003	xorShift128	16	U32

Bad PRNGs

If you're curious about the lineage, or need for compatibility with an old decision, but don't chose one of these. If you're already using one of these, consider migrating.

Name	Variant	State (bytes)	Range
Lehmer/LCG/MCG 1988	all	4	U31
Marsaglia	-	1	[0 - 9]
Middle-Square	-	4	n digits
MSVC (LGC)	-	4	U16
RANDU (LCG)	-	4	U31
XorShift 2003	xorshift32	4	U32
	xorshift64	8	U64

RegExp

• RegExp escape string

RunTime

• Configuration (including collecting from environment variables)
• Structured logging
• Normalize stack entries, and stack traces across engines, with colors

License

MPL-1.1