@fluree/crypto

Cryptography Library for Fluree

A collection of Javascript cryptography functions for Fluree.

Utility Functions

$3

- Arguments: string
- Returns: string

Normalizes string using the NKFC standard to ensure consistent hashing.

const normalApple = crypto.normalizeString("\u0041\u030apple")

For example, we can see that:

crypto.sha2_256("\u0041\u030apple") results in 6e9288599c1ff90127459f82285327c83fa0541d8b7cd215d0cd9e587150c15f.

While using the normalized version of the string

crypto.sha2_256_normalize(normalApple) results in 58acf888b520fe51ecc0e4e5eef46c3bea3ca7df4c11f6719a1c2471bbe478bf.

$3

- Arguments: string or byte-array
- Returns: byte-array

This functions normalizes a string and returns a byte-array. If it is already a byte-array, it returns itself.

For example:

crypto.stringToByteArray("hi there") results in [104, 105, 32, 116, 104, 101, 114, 101].

$3

- Arguments: byte-array
- Returns: byte-array

This functions takes a byte-array and returns a string.

crypto.byteArrayToString([104, 105, 32, 116, 104, 101, 114, 101]) results in hi there.

Public-key Cryptography

$3

- Arguments: none or private-key-as-hex-string
- Returns: { private: "private-key-as-hex-string", public: "public-key-as-hex-string" }

This function will return a map with a public and private key:

crypto.generateKeyPair(); will return a valid public-private key pair.

For example, this might return:

{ private: "6a5f415f49986006815ae7887016275aac8ffb239f9a2fa7172300578582b6c2",
public: "02991719b37817f6108fc8b0e824d3a9daa3d39bc97ecfd4f8bc7ef3b71d4c6391"}.

You can also call this function with a private key already provided.

crypto.generateKeyPair("6a5f415f49986006815ae7887016275aac8ffb239f9a2fa7172300578582b6c2");

This will return:

{ private: "6a5f415f49986006815ae7887016275aac8ffb239f9a2fa7172300578582b6c2",
public: "02991719b37817f6108fc8b0e824d3a9daa3d39bc97ecfd4f8bc7ef3b71d4c6391"}.

$3

- Arguments: private-key-as-hex-string
- Returns: public-key-as-hex-string

Given a private key, this returns a public key:

crypto.pubKeyFromPrivate("6a5f415f49986006815ae7887016275aac8ffb239f9a2fa7172300578582b6c2");

This will return: 02991719b37817f6108fc8b0e824d3a9daa3d39bc97ecfd4f8bc7ef3b71d4c6391;

$3

- Arguments: private-key-as-hex-string
- Returns: account-id

Given a private key, this will return an account id:

crypto.accountIdFromPrivate("6a5f415f49986006815ae7887016275aac8ffb239f9a2fa7172300578582b6c2");

This will return TfGvAdKH2nRdV4zP4yBz4kJ2R9WzYHDe2EV.

$3

- Arguments: public-key-as-hex-string
- Returns: account-id

Given a public key, this will return an account id:

crypto.accountIdFromPublic("02991719b37817f6108fc8b0e824d3a9daa3d39bc97ecfd4f8bc7ef3b71d4c6391");

This will return TfGvAdKH2nRdV4zP4yBz4kJ2R9WzYHDe2EV.

$3

- Arguments: message, private-key-as-hex-string
- Returns: signature

Given a message and a private key, this will return a signature.

``
const message = "hi there";
const privateKey = "6a5f415f49986006815ae7887016275aac8ffb239f9a2fa7172300578582b6c2";

crypto.signMessage(message, privateKey);
`

This returns:

`
1b3046022100cbd32e463567fefc2f120425b0224d9d263008911653f50e83953f47cfbef3bc022100fcf81206277aa1b86d2667b4003f44643759b8f4684097efd92d56129cd89ea8
`


$3

- Arguments: public-key-as-hex-string, message, signature
- Returns: true or false

Given a public key, message, and a signature, this function will return true or false.

`
const message = "hi there";
const privateKey = "6a5f415f49986006815ae7887016275aac8ffb239f9a2fa7172300578582b6c2";
const publicKey = "02991719b37817f6108fc8b0e824d3a9daa3d39bc97ecfd4f8bc7ef3b71d4c6391";
const signature = crypto.signMessage(message, privateKey);

crypto.verifySignature(publicKey, message, signature);

`

This returns true.

$3

- Arguments: message, signature
- Returns: true or false

`
const message = "hi there";
const signature = crypto.signMessage(message, "6a5f415f49986006815ae7887016275aac8ffb239f9a2fa7172300578582b6c2");

crypto.pubKeyFromMessage(message, signature);
`

This returns 02991719b37817f6108fc8b0e824d3a9daa3d39bc97ecfd4f8bc7ef3b71d4c6391.

$3

- Arguments: message, signature
- Returns: true or false

`
const message = "hi there";
const signature = crypto.signMessage(message, "6a5f415f49986006815ae7887016275aac8ffb239f9a2fa7172300578582b6c2");

crypto.accountIdFromMessage(message, signature);
`

This returns TfGvAdKH2nRdV4zP4yBz4kJ2R9WzYHDe2EV.

Hashing

$3

- Arguments: string or byte-array or string or byte-array, output-format or input in input format, output-format, input-format
- Returns: By default hex-string.

Valid input and output formats: hex, bytes, base64, base58, string.

This function: crypto.sha2_256("hi"); returns:

8f434346648f6b96df89dda901c5176b10a6d83961dd3c1ac88b59b2dc327aa4.

$3

- Arguments: string or string, output-format
- Returns: By default hex-string.

Valid output formats: hex, bytes, base64, base58, string.

This function: crypto.sha2_256_normalize("hi") returns:

8f434346648f6b96df89dda901c5176b10a6d83961dd3c1ac88b59b2dc327aa4.

$3

- Arguments: string or byte-array or string or byte-array, output-format or input in input format, output-format, input-format
- Returns: By default hex-string.

Valid input and output formats: hex, bytes, base64, base58, string.

This function: crypto.sha2_512("hi"); returns:

150a14ed5bea6cc731cf86c41566ac427a8db48ef1b9fd626664b3bfbb99071fa4c922f33dde38719b8c8354e2b7ab9d77e0e67fc12843920a712e73d558e197.

$3

- Arguments: string or string, output-format
- Returns: By default hex-string.

Valid output formats: hex, bytes, base64, base58, string.

This function: crypto.sha2_512_normalize("hi"); returns:

150a14ed5bea6cc731cf86c41566ac427a8db48ef1b9fd626664b3bfbb99071fa4c922f33dde38719b8c8354e2b7ab9d77e0e67fc12843920a712e73d558e197.

$3

- Arguments: string or byte-array or string or byte-array, output-format
- Returns: By default hex-string.

Valid output formats: hex, bytes, base64, base58, string.

This function: crypto.sha3_256("hi"); returns:
crypto
b39c14c8da3b23811f6415b7e0b33526d7e07a46f2cf0484179435767e4a8804.

$3

- Arguments: string or string, output-format
- Returns: By default hex-string.

Valid output formats: hex, bytes, base64, base58, string.

This function: crypto.sha3_256_normalize("hi"); returns:

b39c14c8da3b23811f6415b7e0b33526d7e07a46f2cf0484179435767e4a8804.

$3

- Arguments: string or byte-array or string or byte-array, output-format
- Returns: By default hex-string.

Valid output formats: hex, bytes, base64, base58, string.

This function: crypto.sha3_512("hi"); returns:

154013cb8140c753f0ac358da6110fe237481b26c75c3ddc1b59eaf9dd7b46a0a3aeb2cef164b3c82d65b38a4e26ea9930b7b2cb3c01da4ba331c95e62ccb9c3.

$3

- Arguments: string or string, output-format
- Returns: By default hex string.

Valid output formats: hex, bytes, base64, base58, string.

This function: crypto.sha3_512_normalize("hi"); returns:

154013cb8140c753f0ac358da6110fe237481b26c75c3ddc1b59eaf9dd7b46a0a3aeb2cef164b3c82d65b38a4e26ea9930b7b2cb3c01da4ba331c95e62ccb9c3.

$3

- Arguments: string or string, output-format or string, output-format, input-format
- Returns: By default hex-string.

Valid input or output formats: hex, bytes, base64, base58, string.

This function: crypto.ripemd_160("hi"); returns 242485ab6bfd3502bcb3442ea2e211687b8e4d89.

Encryption

$3

- Arguments: message, iv, key or message, iv, key, output-format
- Returns: By default hex-string.

Valid output formats: hex, base64.

`
const initialization_vector = [6, 224, 71, 170, 241, 204, 115, 21, 30, 8, 46, 223, 106, 207, 55, 42];
const message = "hi";
const key = "there";

crypto.aesEncrypt(message, initialization_vector, key);
`

This returns: 668cd07d1a17cc7a8a0390cf017ac7ef.

$3

- Arguments: x, iv, key or x, iv, key, output-format or x, iv, key, output-format, input-format
- Returns: By default hex-string.

`
const initialization_vector = [6, 224, 71, 170, 241, 204, 115, 21, 30, 8, 46, 223, 106, 207, 55, 42];
const message = "hi";
const key = "there";
const encrypted = crypto.aesEncrypt(message, initialization_vector, key);

crypto.aesDecrypt(encrypted, initialization_vector, key);
`

This returns: hi.

$3

- Arguments: message or message, salt or message, salt, n or message, salt, n, r, p or message, salt, n, r, p, dk-len
- Returns: hex-string.

The arguments by default:

- salt: 16 random bytes
- n: 32,768
- r: 8
- p: 1
- dk-len: 32


`
const salt = [172, 28, 242, 108, 175, 130, 214, 6, 249, 61, 244, 178, 34, 8, 13, 178];

crypto.scryptEncrypt("hi", salt)
`

This results in 57f93bcf926c31a9e2d2129da84bfca51eb9447dfe1749b62598feacaad657d4.

$3

- Arguments: message, encrypted, salt or message, encrypted, salt, n, r, p
- Returns: true or false

The arguments by default:

- n: 32,768
- r: 8
- p: 1

`
const salt = [172, 28, 242, 108, 175, 130, 214, 6, 249, 61, 244, 178, 34, 8, 13, 178];

crypto.scryptEncrypt("hi", salt, 32768, 8, 1)

crypto.scryptCheck("hi", "57f93bcf926c31a9e2d2129da84bfca51eb9447dfe1749b62598feacaad657d4", salt, 32768, 8, 1)
`

Contributing

Clone this repo to your local machine and create a new branch for your work.

You'll need the Clojure CLI tools installed for development and testing of this library.

- macOS
- brew install clojure/tools/clojure

You will also need the NodeJS and NPM tools installed.

- macOS
- brew install node
- brew install npm

$3

You can run the CLJ and CLJS test suites like this: make test.

If you want to run one or the other you can do make cljtest or make cljstest.

$3

#### ClojureScript

Run make to build the CLJS library JAR. It will create or update
target/fluree-crypto.jar.

To test this in another CLJS project, just point that project's deps.edn
:deps entry at :local/root "../path/to/fluree.crypto".

#### Node

Run make node to build the NodeJS library in out/nodejs/fluree-crypto.js.

To test this in another Node project, run npm install --save
../path/to/fluree.crypto. That will point @fluree/crypto at this working
directory.

#### Browser

Run make browser to build the browser library in out/browser/fluree-crypto.js.

To test this you can run npx shadow-cljs watch browser and then open
http://localhost:8000/ in a web browser. You should see a byte array output
on the web page.

$3

You can install the JAR locally with:

make install

$3

You can deploy to Clojars with the following:

env CLOJARS_USERNAME=your-user CLOJARS_PASSWORD=your-deploy-token make deploy

You can deploy to npmjs.com with the following:

npm publish

$3

The CI/CD pipeline is run inside a Docker container. You can run this locally if you have
Docker installed via:

script/run-in-docker.sh make test`