@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);