crypto-stamp
v2.2.0
Published
Create web ready crypto signatures (stamps)
Downloads
26
Maintainers
Readme
Crypto Stamp
Web-ready format and library for signing and verifying asynchronous cryptography signatures. It can be used for authorization and document verification in web pages and web services. It designed to be replay and length expansion attacks resistant.
Installation
Install with npm:
npm i crypto-stamp
Usage
Example of creation, signing and verification stamp with ed25519
custom
stamp signer and verifier.
// Require CryptoStamp methods
const {createStamp, verifyStamp} = require('crypto-stamp');
// Require custom CryptoStamp encryption library for example ed25519
const {Signer, Verifier} = require('./crypto-stamp/ed25519');
// Signature generation item
const signer = new Signer({
secret: Buffer.alloc(32), // Provide secret key
});
// Signature verification item
const verifier = new Verifier();
// Stamp data
const stampData = {
type: 'auth',
date: new Date('1970-01-01T00:00:00.000+00:00'),
holders: ['cryptodoc.org'],
};
// Generate stamp
const stamp = await createStamp(stampData, signer);
// Verify stamp
if (await verifyStamp(stamp, verifier)) {
// Stamp is valid. Yaeee!
}
Stamp can be used like a WebToken with encodeToken
and decodeToken
methods.
Stamp
Each stamp authorize action with type
and custom params payload
at a time as date
to unlimited or several holders
.
{
// Stamp action type. Name or URI.
type: 'auth',
// Stamp data (optional)
payload: {},
// Date of creation
date: '1970-01-01T00:00:00.000+00:00',
// Stamp holders
holders: ['cryptodoc.org', '[email protected]'],
// Stamp verification data
stamp: {
// Signature algorithm name or URI.
alg: 'ed25519',
// Signature of length prefixed SHA3-256 hash
signature: '...signature...',
// Public key is optional and algorithm dependent property
publicKey: '...public key...',
},
}
API
createStamp()
(data:StampData, signer:StampSigner) -> Promise<Stamp,Error>
Method createsStamp converts StampData into deterministic length prefixed hash and sign with Signature interface instance.
const stamp = await verifyStamp(data, verifier)
verifyStamp()
(stamp:Stamp, verifier:StampVerifier) -> Promise<Boolean,Error>
Method verifyStamp converts StampData from stamp
into deterministic
length prefixed hash and verify it with StampVerifier interface instance.
const isValid = await verifyStamp(stamp, verifier)
StampData Type
{
type: String,
payload: Object,
date: Date|Number,
holders: String[],
}
Params for stamp creation.
StampSignature Type
{
alg: String,
signature: String|Object,
signer: String?,
}
Stamp Type
{
type: String,
payload: Object,
date: Date|Number,
holders: String[],
stamp: StampSignature
}
Stamp is StampData with StampSignature object.
StampSigner Interface
{
sign(hash:Uint8Array|Buffer) -> Promise<Stamp,Error>
}
See example of ed25519 signer implementation in example/ed25519.js
.
StampVerifier Interface
{
verify(hash:Uint8Array|Buffer, StampSignature) -> Promise<Boolean,Error>
}
See example of ed25519 verifier implementation in example/ed25519.js
.
encodeToken()
(stamp:Stamp) -> String
Convert base64 encoded web token string.
encodeToken(stamp) // -> String
decodeToken()
(token:String) -> Stamp
Convert base64 encoded WebToken to Stamp object.
decodeToken(token) // -> Stamp
getHash()
(value:Object, schema?:Object|Array|(() -> Object|Array)) -> Uint8Array
Return SHA3 hash from deterministic JSON string from JS value
. Use schema
to select exact object properties with normjson.
NOTE V8 doesn't sort object properties in lexicographical order so two familiar objects with different properties order will produce different JSON strings and thus different hashes.
Example
toHex(getHash({a: 1, b: 2})); // -> '7ed7e7ed5657f00683c745c9decb1b985bdd634f68f9f07c68e70b9593637da6'
toHex(getHash({b: 2, a: 1})); // -> '7ed7e7ed5657f00683c745c9decb1b985bdd634f68f9f07c68e70b9593637da6'
toHex()
(array:Uint8Array) -> String
Receive Uint8Array and convert it to hex string.
Spec
Data params.
| Param | Type | Description | |:------|:-----|:------------| | type | String | Required. Stamp type. For example "auth" or "accept". Could be complete URI | | payload | Object | Required. Stamp data. Could be any type. Differs for each action. Could be deleted when stamp created. By default it's an empty object | | date | String,Number | Optional. Date string in ISO 8601 format or unix timestamp | | holders | String[] | Optional. Holders is an array of signature receivers URIs |
Stamp params
| Param | Type | Description |
|:------|:-----|:------------|
| alg | String | Signature algorithm |
| signature | String|Object | Signature itself. Usually hex string but depends on algorithm |
| signer | String | Optional. Signature authentication value URI, name, etc |
| ... | * | Multiple algorithm based params, for example publicKey
. |
Hash
Hash is a SHA3-256 digest from 32 Uint Big Endian prefix length of stamp data and data converted to deterministic JSON string.
- type
- payload
- date
- holders
LICENSE
MIT