dk.simongray.webcrypto — dk.simongray/webcrypto-clj 0.1.0

The Web Cryptography API of the W3C, the same on the JVM, in Node and in browsers. It uses the JCA on the JVM and WebCrypto in JavaScript.

The methods of SubtleCrypto are here under their names in kebab case, e.g. import-key, and take their arguments in the same order. Each returns its result on the JVM (and a promise of it in ClojureScript). To chain them the same way on both platforms, use then.

• An algorithm is a keyword, its WebCrypto name in lower case (e.g. :sha-256), or a map of its :name and its parameters, named as the members of its dictionary in kebab case (e.g. :tag-length).
• A usage of a key is a keyword, e.g. :encrypt or :derive-bits, and a format is :raw, :spki, :pkcs8 or :jwk.
• Bytes are a byte array on the JVM and a Uint8Array in JavaScript.
• A JWK is a map of its JSON members as keywords, e.g. :kty and :key_ops.
• A key is WebCrypto's CryptoKey in ClojureScript and a type of the library's own on the JVM. Use key-info for its attributes. A key pair is a map of its :public-key and its :private-key.

The algorithms are these:

• SHA-1 and SHA-2 for digest
• HMAC, ECDSA, RSASSA-PKCS1-v1_5, RSA-PSS and Ed25519 for sign and verify
• AES-GCM for encrypt and decrypt
• HKDF, PBKDF2 and ECDH for derive-bits and derive-key

ECDSA and ECDH take the curves P-256, P-384 and P-521. Ed25519 needs Java 15 or later on the JVM. For hashes, HMACs and HKDF without promises, see the hash namespace, and for keys in PEM, the pem namespace.

An error is an ex-info whose :type is one of these keywords, named after the exceptions of WebCrypto, section 14.4:

• ::not-supported-error, for an algorithm, a format or a parameter that the library doesn't support
• ::syntax-error, for usages that a key can't have, or none
• ::invalid-access-error, for a key of another algorithm or type, without the usage, or one that can't be exported
• ::data-error, for key data that isn't what the algorithm takes
• ::operation-error, for an operation that fails, e.g. a decryption of a changed ciphertext, or a parameter out of its range
• ::type-error, for an argument of the wrong type or a missing parameter

decrypt clj/s

(decrypt algorithm key data)

The plaintext of the bytes data that the key encrypted by the algorithm, e.g. {:name :aes-gcm :iv iv}. A ciphertext that was changed, or that another key or IV encrypted, throws operation-error.

derive-bits clj/s

(derive-bits algorithm key length)

The length bits, as bytes, that the algorithm derives from the base key key, e.g. {:name :hkdf :hash :sha-256 :salt salt :info info}. The length is a whole number of bytes, in bits, except for ECDH, which takes any length and also nil, for all its bits:

(derive-bits {:name :ecdh :public their-public-key} my-private-key nil)

derive-key clj/s

(derive-key algorithm key derived-key-type extractable usages)

A new key of the derived-key-type, e.g. {:name :aes-gcm :length 256}, that the algorithm derives from the base key key, which is extractable (or not) and has the usages.

(derive-key {:name :pbkdf2 :hash :sha-256 :salt salt :iterations 600000}
            password
            {:name :aes-gcm :length 256}
            false
            [:encrypt :decrypt])

digest clj/s

(digest algorithm data)

The digest of the bytes data by the algorithm: :sha-1, :sha-256, :sha-384 or :sha-512. In JavaScript this is WebCrypto's own digest, which is faster on large data than hash/digest.

encrypt clj/s

(encrypt algorithm key data)

The bytes data encrypted with the key by the algorithm, e.g. {:name :aes-gcm :iv iv}. With AES-GCM the tag follows the ciphertext.

export-key clj/s

(export-key format key)

The key in the format: bytes for :raw, :spki and :pkcs8, and a map for :jwk. Only a key that was made extractable exports, a public key as :spki (or :raw for ECDSA, ECDH and Ed25519) and a private key as :pkcs8.

generate-key clj/s

(generate-key algorithm extractable usages)

A new key of the algorithm, e.g. {:name :aes-gcm :length 256}, which is extractable (or not) and has the usages, e.g. [:encrypt :decrypt]. For an asymmetric algorithm it's a key pair, whose public key is always extractable:

(generate-key {:name :ecdsa :named-curve :p-256} false [:sign :verify])
;; => {:public-key … :private-key …}

import-key clj/s

(import-key format data algorithm extractable usages)

The key of the key data in the format, for the algorithm, which is extractable (or not) and has the usages.

The data is bytes for :raw, :spki and :pkcs8, and a map for :jwk, e.g. a password for PBKDF2:

(import-key :raw (bytes/encode "hunter2") :pbkdf2 false [:derive-key])

To import a key in PEM, read it with the pem namespace first.

key-info clj/s

(key-info key)

The attributes of the key as a map:

• :type, :secret, :public or :private
• :extractable?, whether export-key can export it
• :algorithm, its algorithm, e.g. {:name :hmac :hash :sha-256 :length 512} or {:name :ecdsa :named-curve :p-256}
• :usages, the set of its usages

key? clj/s

(key? x)

Whether x is a key.

random-bytes clj/s

(random-bytes n)

An array of n random bytes from the platform's secure source of randomness, as getRandomValues fills one, but with a limit of 2,147,483,647 bytes rather than its 65,536, as a Java array has.

sign clj/s

(sign algorithm key data)

The signature of the bytes data with the key by the algorithm, e.g. :hmac, :ed25519 or {:name :ecdsa :hash :sha-256}. An ECDSA signature is r and s side by side, as in JOSE.

then clj/s

(then x f)

The result of calling f on x: at once on the JVM, and in ClojureScript a promise of it, once x resolves if it's a promise. It chains the results of the other functions here the same way on both platforms.

(-> (import-key :raw (bytes/encode "hunter2") :pbkdf2 false [:derive-key])
    (then #(derive-key params % {:name :aes-gcm :length 256} false [:encrypt])))

verify clj/s

(verify algorithm key signature data)

Whether signature is the signature of the bytes data with the key by the algorithm, e.g. :hmac.