tezos-crypto

Tezos: library with all the cryptographic primitives used by Tezos
package tezos-crypto
Legend:
Library
Module
Module type
Parameter
Class
Class type
Library tezos-crypto
Module Tezos_crypto . Timelock

!!! WARNING !!!

WE USE 2048 RSA KEYS WHICH DO NOT PROVIDE THE CLASSICAL 128 BITS OF SECURITY. WE ALLOW OURSELVES TO DO THAT SINCE WE DO NOT EXPOSE KEYS FOR A LONG TIME. YOU ARE RESPONSIBLE FOR NOT REUSING OLD KEYS

type symmetric_key

We will time-lock symmetric keys to then handle arbitrary bytes

type rsa_public

RSA public key to define a group in which we will work. The key is an integer n = p*q with p,q primes number. The group we work in is the set of inversible mod n.

type rsa_secret

RSA secret key of the from p,q. Indicates the cardinal of the group.

type time_lock_proof

Proof that the opening of a value is the claimed value. Is concretely a member of the RSA group.

type locked_value

Locked value that can be quickly access with a secret or slowly-access with a number of sequential operations. Is concretely a member of the RSA group.

type unlocked_value

Member of the RSA group that we will lock. In our case it represents a symmetric key.

type ciphertext

A symmetric ciphertext and message authentication code, containing the bytes we want to protect

val gen_rsa_keys : unit -> rsa_public * rsa_secret

Generates random RSA keys of 2046 bits. The size works only if we use them for a small amount of time. !!! NEW KEYS SHOULD BE GENERATED FOR EACH LOCKING !!!

  • raises [Failure]

    if there is not enough entropy available.

val gen_locked_value : rsa_public -> locked_value

Generates almost uniformly an integer mod n. It is in the RSA group with overwhelming probability. We use this since we want to lock symmetric keys, not pre-determined messages.

  • raises [Failure]

    if there is not enough entropy available.

val unlocked_value_to_symmetric_key : unlocked_value -> symmetric_key

Hashes a number mod n to a symmetric key for authenticated encryption.

val locked_value_to_symmetric_key_with_secret : rsa_secret -> time:Z.t -> locked_value -> symmetric_key

Unlock a value using RSA secret and hash the result to derive a symmetric key using unlocked_value_to_symmetric_key

val unlock_with_secret : rsa_secret -> time:Z.t -> locked_value -> unlocked_value

Unlock a value using the RSA secret.

val unlock_and_prove_with_secret : rsa_secret -> time:Z.t -> locked_value -> unlocked_value * time_lock_proof

Unlock a value using the RSA secret. Also produces a proof certifying that the result is indeed what had been locked.

val unlock_and_prove_without_secret : rsa_public -> time:Z.t -> locked_value -> unlocked_value * time_lock_proof

Unlock a value the slow way, without the RSA secret. Also produces a proof certifying that the result is indeed what had been locked.

val prove_without_secret : rsa_public -> time:Z.t -> locked_value -> unlocked_value -> time_lock_proof
val prove_with_secret : rsa_secret -> time:Z.t -> locked_value -> unlocked_value -> time_lock_proof
val verify_time_lock : rsa_public -> time:Z.t -> locked_value -> unlocked_value -> time_lock_proof -> bool

Verifies that locked_value indeed contains unlocked_value with parameters rsa_public and time:Z.t.

val locked_value_to_symmetric_key_with_proof : rsa_public -> time:Z.t -> unlocked_value -> locked_value -> time_lock_proof -> symmetric_key option

Receives a claim opening with a proof. If the proof is valid hashes the opening using unlocked_value_to_symmetric_key, returns None otherwise.

val encrypt : symmetric_key -> bytes -> ciphertext

encrypt using authenticated encryption, i.e. ciphertext contains a ciphertext and a message authentication code.

val decrypt : symmetric_key -> ciphertext -> bytes option

Checks the message authentication code. If correct decrypt the ciphertext, otherwise returns None.

type chest = {
locked_value : locked_value;
time : Z.t;
rsa_public : rsa_public;
ciphertext : ciphertext;
}

Contains a value (the decryption of the ciphertext) that can be provably recovered in time sequential operation or with the rsa secret.

val chest_encoding : chest Data_encoding.t
type chest_key = {
unlocked_value : unlocked_value;
proof : time_lock_proof;
}

Provably opens a chest in a short time.

val chest_key_encoding : chest_key Data_encoding.t

Result of the opening of a chest. The opening can fail in two way which we distinguish to blame the right party. One can provide a false unlocked_value or unlocked_proof, in which case we return Bogus_opening and the provider of the chest key is at fault. Othewise, one can lock the wrong key or put garbage in the ciphertext in which case we return Bogus_cipher and the provider of the chest is at fault. Otherwise we return Correct payload where payload is the content that had originally been put in the chest.

type opening_result =
| Correct of Bytes.t
| Bogus_cipher
| Bogus_opening
val open_chest : chest -> chest_key -> opening_result
val create_chest_and_chest_key : payload:Bytes.t -> time:Z.t -> chest * chest_key

High level function which takes care of generating the locked value, the RSA parameters, and encrypt the payload. Also returns the chest key

val create_chest_key : chest -> chest_key

High level function which unlock the value and create the time-lock proof.