# supersphincs

> SPHINCS+ and Ed25519 paired together as a single signing scheme

Latest version **8.0.6** (published 2023-07-17) · MIT license · 0 weekly downloads

## Install

```sh
npm install supersphincs
pnpm add supersphincs
yarn add supersphincs
bun add supersphincs
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 8.0.6 |
| Published | 2023-07-17 |
| First published | 2016-05-16 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 4 |
| Unpacked size | 1.7 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Cyph, Inc. |
| Maintainers | cyphinc |
| Keywords | cryptography, post-quantum, sphincs, ecc, asm.js, webassembly |

## Links

- npm: https://www.npmjs.com/package/supersphincs
- Repository: https://github.com/cyph/pqcrypto.js
- Homepage: https://github.com/cyph/pqcrypto.js#readme
- Issues: https://github.com/cyph/pqcrypto.js/issues
- npm.io page: https://npm.io/package/supersphincs

## Dependencies (4)

- [sphincs](https://npm.io/package/sphincs.md) *
- [sodiumutil](https://npm.io/package/sodiumutil.md) *
- [fast-sha512](https://npm.io/package/fast-sha512.md) *
- [libsodium-wrappers-sumo](https://npm.io/package/libsodium-wrappers-sumo.md) *

## Alternatives

- [@gemini-wallet/core](https://npm.io/package/@gemini-wallet/core.md) — 515.6K weekly downloads
- [utility](https://npm.io/package/utility.md) — 416.6K weekly downloads
- [@primno/dpapi](https://npm.io/package/@primno/dpapi.md) — 7.2K weekly downloads
- [pi-readseek](https://npm.io/package/pi-readseek.md) — 3.7K weekly downloads
- [@emilia-protocol/verify](https://npm.io/package/@emilia-protocol/verify.md) — 1.1K weekly downloads

## Recent versions

- 8.0.6 (latest) — 2023-07-17
- 5.4.2 (old) — 2020-08-01
- 6.2.3-next (next) — 2019-09-09
- 6.0.8-debug (debug) — 2018-06-18
- 8.0.5 — 2023-05-21
- 8.0.4 — 2023-03-27
- 8.0.3 — 2023-01-26
- 8.0.2 — 2022-08-06
- 8.0.1 — 2022-07-26
- 8.0.0 — 2022-07-17
- 7.0.2 — 2022-07-15
- 7.0.1 — 2022-07-13
- 7.0.0 — 2022-07-13
- 6.3.5 — 2022-07-12
- 6.3.4 — 2022-07-11
- … 60 more at https://npm.io/package/supersphincs/versions

## README

# supersphincs

## Overview

SuperSPHINCS combines the post-quantum [SPHINCS+](https://sphincs.org) with the more conventional
elliptic-curve (ECC) [Ed25519](https://ed25519.cr.yp.to) as a single signing scheme. SPHINCS+ is
provided by [sphincs](https://github.com/cyph/pqcrypto.js/tree/master/packages/sphincs) and
Ed25519 signing is performed using [libsodium.js](https://github.com/jedisct1/libsodium.js).

Before signing, a SHA-512 hash is performed, using the current platform's native implementation
where available or an efficient JavaScript implementation from
[TweetNaCl.js](https://github.com/dchest/tweetnacl-js) otherwise.

## Example Usage

	import {superSphincs} from 'supersphincs';

	const keyPair /*: {privateKey: Uint8Array; publicKey: Uint8Array} */ =
		await superSphincs.keyPair()
	;

	const message /*: Uint8Array */ =
		new Uint8Array([104, 101, 108, 108, 111]) // "hello"
	;

	// Optional additional data argument, similar conceptually to what AEAD cyphers support.
	// If specified, must be the same when signing and verifying. For more information and
	// usage advice, see: https://download.libsodium.org/doc/secret-key_cryptography/aead.html
	const additionalData /*: Uint8Array */ =
		new Uint8Array([119, 111, 114, 108, 100]) // "world"
	;

	/* Combined signatures */

	const signed /*: Uint8Array */ =
		await superSphincs.sign(message, keyPair.privateKey, additionalData)
	;

	const verified /*: Uint8Array */ =
		await superSphincs.open(signed, keyPair.publicKey, additionalData) // same as message
	;

	/* Detached signatures */

	const signature /*: Uint8Array */ =
		await superSphincs.signDetached(message, keyPair.privateKey, additionalData)
	;

	const isValid /*: boolean */ =
		await superSphincs.verifyDetached(
			signature,
			message,
			keyPair.publicKey,
			additionalData
		) // true
	;

	/* Export and optionally encrypt keys */

	const keyData /*: {
		private: {
			classical: string;
			combined: string;
			postQuantum: string;
		};
		public: {
			classical: string;
			combined: string;
			postQuantum: string;
		};
	} */ =
		await superSphincs.exportKeys(keyPair, 'secret passphrase')
	;

	if (typeof localStorage === 'undefined') {
		localStorage	= {};
	}

	// May now save exported keys to disk (or whatever)
	localStorage.superSphincsPrivateKey = keyData.private.combined;
	localStorage.sphincsPrivateKey      = keyData.private.postQuantum;
	localStorage.eccPrivateKey          = keyData.private.classical;
	localStorage.superSphincsPublicKey  = keyData.public.combined;
	localStorage.sphincsPublicKey       = keyData.public.postQuantum;
	localStorage.eccPublicKey           = keyData.public.classical;


	/* Reconstruct an exported key using either the superSphincs
		value or any pair of valid sphincs and ecc values */

	const keyPair1 = await superSphincs.importKeys({
		public: {
			classical: localStorage.eccPublicKey,
			postQuantum: localStorage.sphincsPublicKey
		}
	});

	// May now use keyPair1.publicKey as in the above examples
	console.log('Import #1:');
	console.log(keyPair1);

	const keyPair2 = await superSphincs.importKeys(
		{
			private: {
				combined: localStorage.superSphincsPrivateKey
			}
		},
		'secret passphrase'
	);

	// May now use keyPair2 as in the above examples
	console.log('Import #2:');
	console.log(keyPair2);

	// Constructing an entirely new SuperSPHINCS key pair from
	// the original SPHINCS+ key pair and a new ECC key pair
	const keyPair3 = await superSphincs.importKeys(
		{
			private: {
				classical: (
					await superSphincs.exportKeys(
						await superSphincs.keyPair(),
						'hunter2'
					)
				).private.classical,
				postQuantum: localStorage.sphincsPrivateKey
			}
		},
		{
			classical: 'hunter2',
			postQuantum: 'secret passphrase'
		}
	);

	// May now use keyPair3 as in the above examples
	console.log('Import #3:');
	console.log(keyPair3);

## Changelog

Breaking changes in major versions:

8.0.0:

* Standardized method signatures across packages.

7.0.0:

* Upgraded from SPHINCS and RSA to SPHINCS+ and ECC. For backwards compatibility with
previous versions of this package, use
[supersphincs-legacy](https://github.com/cyph/pqcrypto.js/tree/master/packages/supersphincs-legacy).

6.0.0:

* Additional data optional with default value of `new Uint8Array(0)`.

5.0.0:

* Additional data format change.

4.0.0:

* As part of upgrading from asm.js to WebAssembly (with asm.js included as a fallback),
the API is fully asynchronous.

3.0.0:

* General API cleanup.

2.0.0:

* Split into module (supersphincs.js) and standalone pre-bundled version (dist/supersphincs.js).

---
_Source: https://npm.io/package/supersphincs · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._