@iota/signing

@iota/signing

IOTA Signing Scheme

Installation

Install using npm:

npm install @iota/signing

or using yarn:

yarn add @iota/signing

API Reference

• signing

  • .subseed(seed, index)

  • .key(subseedTrits, numberOfFragments)

  • .digests(key)

  • .address(digests)

  • .validateSignatures(expectedAddress, signatureFragments, bundle)

  • .normalizedBundle(bundle)

signing.subseed(seed, index)

Summary: Generates a subseed.
Throws:

• errors.ILLEGAL_SUBSEED_INDEX : Make sure that the index argument is a number greater than 0.

Param	Type	Description
seed	Int8Array	A 243-trit seed to use to derive the subseed
index	number	The private key index to use to derive the subseed

This method derives a subseed from a seed and a private key index.

You can use the subseed to derive private keys and their addresses.

Note: If the given seed is less then 243 trits, 0 trits are appended to it until it is 243 trits long.

Related methods

To convert a seed from trytes to trits, use the trytesToTrits() method.

To derive a private key from the subseed, use the key() method.

Returns: Int8Array - subseed - A subseed in trits
Example

const seed = 'MYSUPERSECRETSEED...';
const subseed = Sign.subseed(Converter.trytesToTrits(seed), 0);

signing.key(subseedTrits, numberOfFragments)

Summary: Generates a private key.
Throws:

• errors.ILLEGAL_SUBSEED_LENGTH : Make sure that the subseedTrits argument contains 243 trits.
• errors.ILLEGAL_NUMBER_OF_FRAGMENTS : Make sure that the numberOfFragments argument is a valid security level (between 1 and 3).

Param	Type	Description
subseedTrits	Int8Array	A subseed in trits
numberOfFragments	number	The security level that you want the private key to have

This method derives a private key from a subseed.

You can use the private key to derive an address and to sign bundles that withdraw from that address.

Related methods

To generate a subseed, use the subseed() method.

Returns: Int8Array - privateKey - A private key in trits.
Example

const seed = 'MYSUPERSECRETSEED...';
const subseed = Signing.subseed(Converter.trytesToTrits(seed), 0);

const privateKey = Signing.key(subseed, 2);

signing.digests(key)

Summary: Generates key digests for a given private key.
Throws:

• errors.ILLEGAL_KEY_LENGTH : Make sure that the key argument contains 2,187, 4,374, or 6,561 trits.

Param	Type	Description
key	Int8Array	Private key in trits

This method derives key digests from a private key.

You can use the key digests to generate an address.

Related methods

To generate a private key, use the key() method.

Returns: Int8Array - digests - Key digests in trits
Example

const seed = 'MYSUPERSECRETSEED...';
const subseed = Signing.subseed(Converter.trytesToTrits(seed), 0);

const privateKey = Signing.key(subseed, 2);

const digests = Signing.digests(privateKey);

signing.address(digests)

Summary: Derives an address from the given key digests.
Throws:

• errors.ILLEGAL_DIGESTS_LENGTH : Make sure that the digests argument contains a multiple of 243 trits.

Param	Type	Description
digests	Int8Array	Key digests in trits

This method derives a 243-trit address from the given key digests.

Related methods

To generate a private key, use the key() method.

Returns: Int8Array - address - Address in trits
Example

const seed = 'MYSUPERSECRETSEED...';
const subseed = Signing.subseed(Converter.trytesToTrits(seed), 0);

const privateKey = Signing.key(subseed, 2);

const digests = Signing.digests(privateKey);

const address = Signing.address(digests);

signing.validateSignatures(expectedAddress, signatureFragments, bundle)

Summary: Validates the given signature, using the given bundle and address.
Throws:

• errors.ILLEGAL_BUNDLE_HASH_LENGTH : Make sure that the bundle argument contains a 243-trit bundle hash.

Param	Type	Description
expectedAddress	Int8Array	Input address in trits
signatureFragments	Array.<Int8Array>	Signature fragments in trits
bundle	Int8Array	Bundle hash in trits

This method validates a signature by doing the following:

• Normalizing the bundle hash
• Deriving the key digests of the address, using the normalized bundle hash and the signature -.Deriving an address from the key digests
• Comparing the derived address to the expectedAddress argument to find out if they match

If the addresses match, the signature is valid.

For more information about signatures see the documentation portal.

Related methods

To convert trytes such as bundle hashes and addresses to trits, use the trytesToTrits() method.

Returns: boolean - valid - Whether the signatures are valid.
Example

let valid = Signing.validateSignatures(expectedAddress, signatureFragments, bundle);

signing.normalizedBundle(bundle)

Summary: Normalizes the bundle hash.
Throws:

• errors.ILLEGAL_BUNDLE_HASH_LENGTH : Make sure that the bundle argument contains a 243-trit bundle hash.

Param	Type	Description
bundle	Int8Array	Bundle hash in trits

This method normalizes the given bundle hash to make sure that only around half of the private key is revealed when the bundle hash is signed.

For more information about signatures see the documentation portal.

To find out more about why the bundle hash is normalized, see this answer on StackExchange.

Related methods

To convert a bundle hash from trytes to trits, use the trytesToTrits() method.

Returns: Int8Array - Normalized bundle hash in trits
Example

let normalizedBundleHash = Signing.normalizedBundle(bundle);