Module Js_of_ocaml.Crypto

Web Crypto API.

A code example:

  let hash data =
    Promise.map
      (fun buf -> buf)
      ((Crypto.subtle ())##digest
         (Crypto.algorithm (Js.string "SHA-256"))
         (Crypto.buffer_source_of_array_buffer_view data))

Most of SubtleCrypto is exposed as object methods, mirroring the JavaScript surface: obtain the subtle object with subtle and call its methods with ##.

Common types

type algorithm

An AlgorithmIdentifier: either a bare name (e.g. "SHA-256") or a parameter object (e.g. {name: "AES-GCM"; iv: ...}). Build one with algorithm or algorithm_obj.

val algorithm : Js.js_string Js.t -> algorithm

algorithm name is the bare-name form of an algorithm identifier, such as algorithm (Js.string "SHA-256").

val algorithm_obj : < .. > Js.t -> algorithm

algorithm_obj o uses an arbitrary parameter object as an algorithm identifier. Build o with Js.Unsafe.obj or the object%js syntax.

type bufferSource

A BufferSource: an ArrayBuffer or any ArrayBufferView (typed array or DataView). Build one with buffer_source_of_array_buffer or buffer_source_of_array_buffer_view.

val buffer_source_of_array_buffer : Typed_array.arrayBuffer Js.t -> bufferSource
val buffer_source_of_array_buffer_view : Typed_array.arrayBufferView Js.t -> bufferSource

Key types, usages and formats

module Key_type : sig ... end

The KeyType of a cryptoKey.

module Key_usage : sig ... end

A KeyUsage: an operation a cryptoKey may be used for.

module Key_format : sig ... end

A KeyFormat for importing and exporting keys.

Keys

class type cryptoKey = object ... end
class type cryptoKeyPair = object ... end
type jsonWebKey = Js.Unsafe.any

A key in JsonWebKey form (RFC 7517): a plain JSON object whose members carry the key material (e.g. kty, n, e for RSA; crv, x, y for EC). Exposed as Js.Unsafe.any: read its members with Js.Unsafe.get, build one with Js.Unsafe.obj, and serialise/parse with the JSON global.

Typed algorithm parameters

type params =
  1. | RSASSA_PKCS1_v1_5
    (*

    Sign/verify; parameters are just the name.

    *)
  2. | RSA_PSS of {
    1. salt_length : int;
    }
  3. | RSA_OAEP of {
    1. label : bufferSource option;
    }
  4. | ECDSA of {
    1. hash : algorithm;
    }
  5. | ECDH of {
    1. public : cryptoKey Js.t;
    }
  6. | AES_CTR of {
    1. counter : bufferSource;
    2. length : int;
    }
  7. | AES_CBC of {
    1. iv : bufferSource;
    }
  8. | AES_GCM of {
    1. iv : bufferSource;
    2. additional_data : bufferSource option;
    3. tag_length : int option;
    }
  9. | AES_KW
    (*

    Key-wrapping; parameters are just the name.

    *)
  10. | HMAC
    (*

    Sign/verify; parameters are just the name.

    *)
  11. | HKDF of {
    1. hash : algorithm;
    2. salt : bufferSource;
    3. info : bufferSource;
    }
  12. | PBKDF2 of {
    1. hash : algorithm;
    2. salt : bufferSource;
    3. iterations : int;
    }
  13. | RSA_keygen of {
    1. name : Js.js_string Js.t;
      (*

      "RSASSA-PKCS1-v1_5", "RSA-PSS" or "RSA-OAEP".

      *)
    2. modulus_length : int;
    3. public_exponent : Typed_array.uint8Array Js.t;
    4. hash : algorithm;
    }
    (*

    RsaHashedKeyGenParams for subtleCrypto.generateKey.

    *)
  14. | RSA_import of {
    1. name : Js.js_string Js.t;
      (*

      "RSASSA-PKCS1-v1_5", "RSA-PSS" or "RSA-OAEP".

      *)
    2. hash : algorithm;
    }
    (*

    RsaHashedImportParams for subtleCrypto.importKey.

    *)
  15. | EC_keygen of {
    1. name : Js.js_string Js.t;
      (*

      "ECDSA" or "ECDH".

      *)
    2. named_curve : Js.js_string Js.t;
    }
    (*

    EcKeyGenParams.

    *)
  16. | AES_keygen of {
    1. name : Js.js_string Js.t;
      (*

      "AES-CTR", "AES-CBC", "AES-GCM" or "AES-KW".

      *)
    2. length : int;
    }
    (*

    AesKeyGenParams.

    *)
  17. | HMAC_keygen of {
    1. hash : algorithm;
    2. length : int option;
    }
    (*

    HmacKeyGenParams.

    *)
  18. | SHA_1
  19. | SHA_256
  20. | SHA_384
  21. | SHA_512
  22. | Other of Js.js_string Js.t
    (*

    An algorithm whose name is not recognised.

    *)

A typed view of an algorithm identifier, with one constructor per WebCrypto algorithm-parameter dictionary. The nullary constructors map to a bare name string; the others map to a parameter object. hash fields are themselves algorithm values (usually a digest name such as to_algorithm of SHA_256).

val to_algorithm : params -> algorithm

Build a JS AlgorithmIdentifier from typed params.

val of_algorithm : algorithm -> params

Recover typed params from a JS AlgorithmIdentifier by dispatching on its name. Key-generation and import parameter objects are told apart from same-named operation parameters by which fields are present (e.g. modulusLength vs hash for RSA, namedCurve for EC, iv/counter vs length for AES). An unrecognised name maps to Other.

SubtleCrypto

class type subtleCrypto = object ... end

Crypto

class type crypto = object ... end
val crypto : unit -> crypto Js.t

The crypto global (globalThis.crypto).

val subtle : unit -> subtleCrypto Js.t

(crypto ())##.subtle. Only available in a secure context.

val is_supported : unit -> bool

Whether the crypto global is available in the current environment.