signun
signun provides N-API bindings to the following crypto libraries:
Installation
npm i @nlv8/signun
Features
- Digital Signature
- Sync and async secp256k1 ECDSA.
- Tunable performance characteristics in bindings.gyp. Please see the documentation of secp256k1 for the available settings.
- Uses GMP if available.
- Sync and async secp256k1 ECDSA.
- Cryptographic Hash
- Async BLAKE2b.
Runs on
- Windows x86 (will not use GMP),
- Linux x86/ARM (will use GMP if available),
- Mac x86/ARM (will use GMP if available).
Examples
secp256k1 ECDSA
Sync
const { randomBytes } = require('crypto');
const { secp256k1 } = require('@nlv8/signun');
let privateKey;
do {
privateKey = randomBytes(32)
} while (!secp256k1.privateKeyVerifySync(privateKey));
const publicKey = secp256k1.publicKeyCreateSync(privateKey);
const message = randomBytes(32);
const signOptions = {
// 32 bytes of custom data.
data: null,
// Custom nonce function.
noncefn: null
}
const signResult = secp256k1.signSync(message, privateKey, signOptions);
const verifyResult = secp256k1.verifySync(message, signResult.signature, publicKey);
console.log(verifyResult);
Async
const { randomBytes } = require('crypto');
const { secp256k1 } = require('@nlv8/signun');
(async function main() {
let privateKey;
do {
privateKey = randomBytes(32)
} while (!(await secp256k1.privateKeyVerify(privateKey)));
const publicKey = await secp256k1.publicKeyCreate(privateKey);
const message = randomBytes(32);
// Custom nonce function is not supported yet for async.
const signOptions = {
// 32 bytes of custom data.
data: null
}
const signResult = await secp256k1.sign(message, privateKey, signOptions);
const verifyResult = await secp256k1.verify(message, signResult.signature, publicKey);
console.log(verifyResult);
})();
BLAKE2
hash
const { randomBytes } = require('crypto');
const { blake2b } = require('@nlv8/signun');
(async function main() {
const data = randomBytes(64);
const hashLength = 64;
const result = await blake2b.hash(data, hashLength);
})();
keyedHash
const { randomBytes } = require('crypto');
const { blake2b } = require('@nlv8/signun');
(async function main() {
const data = randomBytes(64);
const key = randomBytes(64);
const hashLength = 64;
const result = await blake2b.keyedHash(data, key, hashLength);
})();
API
signun exports the following two objects.
secp256k1
Asynchronous and synchronous bindings for secdp256k1-based ECDSA. By default, all functions are async, returning a Promise. However, by appending Sync
at the end of the function name, one can invoke them synchronously.
privateKeyVerify(privateKey)
Verifies whether a Buffer is a valid private key.
-
privateKey: Buffer
: A Buffer containing the candidate private key.
Returns true
if the specified Buffer is a valid private key and false
otherwise.
publicKeyCreate(privateKey, isCompressed = true)
Constructs a new public key corresponding to the specified private key.
-
privateKey: Buffer
: A Buffer containing a valid private key. -
isCompressed: boolean = true
: Whether a compressed representation should be produced.
Returns a Buffer with the public key upon success.
Will throw/reject if the public key cannot be created from the specified data.
sign(message, privateKey, options)
Signs the message with the specified private key.
-
message: Buffer
: The message to sign. -
privateKey: Buffer
: The private key with which the signature will be created. -
options: object
: Optional options object. Can only be used for synchronous invocations.-
data: Buffer
: Arbitrary data to be passed to the nonce function. -
noncefn: function
: A custom nonce function, with the following signature:noncefn(message: Buffer, key: Buffer, algo: Buffer, data: Buffer, attempt: number): Buffer
.
-
Returns an object with the following properties upon success:
-
signature: Buffer
: The actual signature. -
recovery: number
: The recovery id.
Will throw/reject if the signature cannot be created.
verify(message, signature, publicKey)
Verifies a signature against the specified message and public key.
-
message: Buffer
: The message we think was signed. -
signature: Buffer
: The signature to be verified. -
publicKey
: The public key pair of the signing private key.
Returns true
if the signature is valid and false
otherwise.
blake2b
Asynchronous BLAKE2b hashing.
hash(data, hashLength)
Hashes the specified data.
-
data: Buffer
: The data to be hashed. Can be empty but must be a valid Buffer. -
hashLength: number
: The length of the hash. Must be between 1 and 64 (inclusive).
Returns the hash in a Buffer.
keyedHash(data, key, hashLength)
Produces the keyed hash of the specified data.
-
data: Buffer
: The data to be hashed. Can be empty but must be a valid Buffer. -
key: Buffer
: The key to be used. -
hashLength: number
: The length of the hash. Must be between 1 and 64 (inclusive).
Returns the hash in a Buffer.
Acknowledgements
This is an open source project maintained by NLV8.
Original authors include Viktor Simkó, Tibor Balla and Attila Bagossy
Licence
signun is licensed under Apache-2.0.
Licences of dependencies:
- secp256k1: MIT
- BLAKE2: Triple-licensed, using Apache 2.0