utils-crypto
Cryptographic primitives using sodium.Installation
yarn add @mainframe/utils-crypto
Types
KeyPair
Object containing the public and secret parts of the key:interface KeyPair {
publicKey: Buffer
secretKey: Buffer
}
EncryptedBox
interface EncryptedBox {
cipher: Buffer
nonce: Buffer
}
API
createBoxKeyPair()
Creates aKeyPair
for encryption, using the optionally provided seed
to generate it.Arguments
seed?: Buffer
Returns
KeyPair
createBoxPublicFromSign()
Converts a public signing key to an encryption one.Arguments
signKey: Buffer
Returns public encryption key
Buffer
createBoxKeyPairFromSign()
Converts a signingKeyPair
to an encryption one.Arguments
signPair: KeyPair
Returns encryption
KeyPair
encryptBox()
Creates anEncryptedBox
of the provided data
using the fromSecretKey
so it can be decrypted by the owner of the forPublicKey
.Arguments
data: Buffer
forPublicKey: Buffer
fromSecretKey: Buffer
Returns
EncryptedBox
decryptBox()
Decrypts the providedEncryptedBox
using the fromPublicKey
and forSecretKey
.Arguments
encrypted: EncryptedBox
fromPublicKey: Buffer
forSecretKey: Buffer
Returns
Buffer
if decryption is successfull, null
otherwisecreateSecretBoxKey()
Creates a random secret box encryption key.Returns
Buffer
with length SECRETBOX_KEYBYTES
(crypto_secretbox_KEYBYTES
)createSecretBoxKeyFromPassword()
Creates a secret box encryption key from the providedpassword
and other arguments. See hashPassword() for more details about the arguments values.Arguments
password: Buffer
salt: Buffer
opslimit?: number
, defaults toPASSWORDHASH_OPSLIMIT_SENSITIVE
memlimit?: number
, defaults toPASSWORDHASH_MEMLIMIT_SENSITIVE
algorithm?: number
Returns
Promise<Buffer>
encryptSecretBox()
Creates anEncryptedBox
of the provided data
using the key
.Arguments
data: Buffer
key: Buffer
Returns
EncryptedBox
decryptSecretBox()
Decrypts the providedEncryptedBox
using the key
.Arguments
data: Buffer
key: Buffer
Returns
Buffer
if decryption is successfull, null
otherwisehash()
Hashes the providedinput
to a buffer of the optional size
, using the key
if provided.Arguments
input: Buffer
size?: number
key?: Buffer
Returns
Buffer
hashStream()
Hashes the provided readablestream
to a buffer of the optional size
.Arguments
stream: Readable
size?: number
Returns
Promise<Buffer>
createPasswordHashSalt()
Creates a random salt for password hashing.Returns
Buffer
with length PASSWORDHASH_SALT_BYTES
(crypto_pwhash_SALTBYTES
)hashPassword()
Hashes the providedpassword
to the hash
buffer.Arguments
hash: Buffer
with length betweenPASSWORDHASH_BYTES_MIN
(crypto_pwhash_BYTES_MIN
) andPASSWORDHASH_BYTES_MAX
(crypto_pwhash_BYTES_MAX
)password: Buffer
salt: Buffer
with lengthPASSWORDHASH_SALT_BYTES
(crypto_pwhash_SALTBYTES
)opslimit?: number
betweenPASSWORDHASH_OPSLIMIT_MIN
(crypto_pwhash_OPSLIMIT_MIN
) andPASSWORDHASH_OPSLIMIT_MAX
(crypto_pwhash_OPSLIMIT_MAX
), defaults toPASSWORDHASH_OPSLIMIT_MODERATE
(crypto_pwhash_OPSLIMIT_MODERATE
)memlimit?: number
betweenPASSWORDHASH_MEMLIMIT_MIN
(crypto_pwhash_MEMLIMIT_MIN
) andPASSWORDHASH_MEMLIMIT_MAX
(crypto_pwhash_MEMLIMIT_MAX
), defaults toPASSWORDHASH_MEMLIMIT_MODERATE
(crypto_pwhash_MEMLIMIT_MODERATE
)algorithm?: number
, defaults toPASSWORDHASH_ALG_ARGON2ID13
(crypto_pwhash_ALG_ARGON2ID13
)
Returns
Promise<Buffer>
randomBytes()
Generates a buffer of random data having the providedsize
.Arguments
size: number
Returns
Buffer
secureRandomBytes()
Generates a secure buffer (protected memory) of random data having the providedsize
.Arguments
size: number
Returns
Buffer
createSecretStreamKey()
Creates a random secret stream encryption key.Returns
Buffer
with length SECRETSTREAM_KEYBYTES
(crypto_secretstream_xchacha20poly1305_KEYBYTES
)createEncryptStream()
Creates aTransform
stream encrypting contents using the provided key
.
This transform will add the encryption headers of length SECRETSTREAM_HEADERBYTES
(crypto_secretstream_xchacha20poly1305_HEADERBYTES
) to the output stream.Arguments
key: Buffer
of lengthSECRETSTREAM_KEYBYTES
Returns
Transform
streamcreateDecryptStream()
Creates aTransform
stream decrypting contents using the provided key
.
This transform expects the encryption headers to be present in the first SECRETSTREAM_HEADERBYTES
(crypto_secretstream_xchacha20poly1305_HEADERBYTES
) bytes of the input stream, as added by the createEncryptStream()
function.Arguments
key: Buffer
of lengthSECRETSTREAM_KEYBYTES
Returns
Transform
streamcreateSignKeyPair()
Creates aKeyPair
for signature, using the optionally provided seed
to generate it.Arguments
seed?: Buffer
Returns
KeyPair
getSignature()
Returns the signature for the provideddata
and secretKey
.Arguments
data: Buffer
secretKey: Buffer
Returns
Buffer
verifySignature()
Verifies the provideddata
has a valid signature
for the publicKey
.Arguments
data: Buffer
signature: Buffer
publicKey: Buffer
Returns
boolean
sign()
Signs the provideddata
with the secretKey
and returns the signed data.Arguments
data: Buffer
secretKey: Buffer
Returns
Buffer
openSigned()
Verifies the provideddata
has been signed for the publicKey
and returns the unsigned data. If the signature is incorrect, null
is returned.Arguments
data: Buffer
publicKey: Buffer
Returns
Buffer
if verification is successfull, null
otherwise