Module Bytesrw_crypto.Psa

Thin bindings to PSA Crypto API.

The binding is low-level and mostly one-to-one with C. It does not try to embelish the API for OCaml idioms. However given a memory-safe implementation of PSA Crypto, this binding allows no unsafe usage.

Key material. When key material is manipulated explicitly (Psa.import_key, Psa.export_key, etc.) we use Psa.bigbytes to store the bytes. Since a bigbytes value wraps a C malloced pointer, it prevents the garbage collector from copying the key material and Bytesrw_crypto.Clearing it destroys it. Of course if you use Bigbytes.of_string or Bigbytes.of_bytes to create the bigbytes value that defeats the purpose. Note that OCaml 5.2 added functions to directly read and write bigbytes values with channels and file descriptors.

Naming convention. Any C identifier of the form psa_xxx_yyy_zzz or PSA_XXX_YYY_ZZZ is mapped in OCaml to on one of Psa.xxx_yyy_zzz, Psa.Xxx.yyy_zzz. There may be a few exception to the rule (e.g. Psa.Cipher.block_length).

Return value convention. When C functions return by setting a value passed by reference (e.g. a key identifier or number of bytes written) if and only the call is a success we return that value in an OCaml Ok value and otherwise Error value with the error status code. See for example Psa.generate_key, Psa.export_key, etc.

Supported version and references. For now we bind the version 1.2 of the API with what is available in the TF-PSA-Crypto implementation of the specification (a few entry points are missing).

Preliminaries

Note. These are OCaml artefacts, not part of the PSA Crypto API.

type uint8 = int

The type for unsigned 8-bit integers.

type uint16 = int

The type for unsigned 16-bit integers.

type uint32 = int32

The type for unsigned 32-bit integers.

type uint64 = int64

The type for unsigned 64-bit integers.

type bigbytes = (int, Stdlib.Bigarray.int8_unsigned_elt, Stdlib.Bigarray.c_layout) Stdlib.Bigarray.Array1.t

The type for bigarrays of bytes. See also Bytesrw_crypto.Bigbytes.

Status codes

module Status : sig ... end

Status codes.

val success : Status.t

PSA_SUCCESS

val operation_incomplete : Status.t

PSA_OPERATION_INCOMPLETE

module Error : sig ... end

Error statuses.

Library management

val crypto_api_version : unit -> int * int

crypto_api_version () is the version of this implementation of the PSA Crypto API.

val crypto_init : unit -> Status.t

psa_crypto_init

Note. A call to this function is made in the initialisation of the Bytesrw_crypto module.

Algorithms

module Alg : sig ... end

Algorithms.

Key management

Key identifiers

module Key_id : sig ... end

Key identifiers.

Key attributes

module Key_attributes : sig ... end

Key attributes.

val get_key_attributes : Key_id.t -> Key_attributes.t -> Status.t

psa_get_key_attributes

val reset_key_attributes : Key_attributes.t -> unit

psa_reset_key_attributes

val get_key_id : Key_attributes.t -> Key_id.t

psa_get_key_id

val set_key_id : Key_attributes.t -> Key_id.t -> unit

psa_set_key_id

Key lifetimes

module Key_location : sig ... end

Key locations.

module Key_persistence : sig ... end

Key persistence.

module Key_lifetime : sig ... end

Key lifetimes.

val get_key_lifetime : Key_attributes.t -> Key_lifetime.t

psa_get_key_lifetime

val set_key_lifetime : Key_attributes.t -> Key_lifetime.t -> unit

psa_set_key_lifetime

Key usages

module Key_usage : sig ... end

Key usages.

val get_key_algorithm : Key_attributes.t -> Alg.t

psa_get_key_algorithm

val set_key_algorithm : Key_attributes.t -> Alg.t -> unit

psa_set_key_algorithm

val get_key_usage_flags : Key_attributes.t -> Key_usage.t

psa_get_key_usage_flags

val set_key_usage_flags : Key_attributes.t -> Key_usage.t -> unit

psa_set_key_usage_flags

Key types

module Ecc_family : sig ... end

Elliptic curve keys.

module Dh_family : sig ... end

Diffie-Hellman keys.

module Key_type : sig ... end

Key types.

val get_key_type : Key_attributes.t -> Key_type.t

psa_get_key_type

val set_key_type : Key_attributes.t -> Key_type.t -> unit

psa_set_key_type

val get_key_bits : Key_attributes.t -> int

psa_get_key_bits

val set_key_bits : Key_attributes.t -> int -> unit

psa_set_key_bits

Creation

val import_key : ?length:int -> Key_attributes.t -> bigbytes -> (Key_id.t, Status.t) Stdlib.result

psa_import_key is Ok kid if the key was imported by reading length bytes of the bigbytes (defaults to the size of the bigbytes).

val generate_key : Key_attributes.t -> (Key_id.t, Status.t) Stdlib.result

psa_generate_key is Ok kid if the was generated.

val copy_key : Key_id.t -> Key_attributes.t -> (Key_id.t, Status.t) Stdlib.result

psa_copy_key is Ok kid if the key was copied.

Destruction

val destroy_key : Key_id.t -> Status.t

psa_destroy_key

val purge_key : Key_id.t -> Status.t

psa_purge_key

Export

val export_key : Key_id.t -> bigbytes -> (int, Status.t) Stdlib.result

psa_export_key is Ok n iff n bytes were written.

val export_public_key : Key_id.t -> bigbytes -> (int, Status.t) Stdlib.result

psa_export_public_key is Ok n iff n bytes were written.

val export_key_output_size : Key_type.t -> bits:int -> int

PSA_EXPORT_KEY_OUTPUT_SIZE

val export_public_key_output_size : Key_type.t -> bits:int -> int

PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE

val export_key_pair_max_size : unit -> int

PSA_EXPORT_KEY_PAIR_MAX_SIZE

val export_public_key_max_size : unit -> int

PSA_EXPORT_PUBLIC_KEY_MAX_SIZE

Cryptographic operations

Message digests (Hashes)

module Hash : sig ... end

Message digests.

Message authentication codes (MAC)

module Mac : sig ... end

Message authentication codes (MAC).

Unauthenticated ciphers

module Cipher : sig ... end

Unauthenticated ciphers.

Authenticated encryption with associated data (AEAD)

module Aead : sig ... end

Authenticated encryption with associated data (AEAD).

Key derivation

module Key_derivation : sig ... end

Key derivation.

Asymmetric signature

module Sign : sig ... end

Asymmetric signatures.

Asymmetric encryption

module Asymmetric : sig ... end

Asymmetric encryption.

Key agreement

module Key_agreement : sig ... end

Key agreement.

Random number generation

val generate_random : Bytesrw.Bytes.Slice.t -> Status.t

generate_random s writes the bytes in the slice range with psa_generate_random.

val generate_random_bigbytes : bigbytes -> Status.t

generate_random_bigbytes s writes the bigbytes bytes with psa_generate_random.