# package octez-libs

`Timelock`

is a set of functions to handle time-locking a value and opening time-locked values.

A time-locked value can either be opened quickly by the locker itself (i.e., the one possessing the RSA secret), or slowly by anyone doing a fixed number of sequential operations.

In the interface of this module, this fixed number is consistently named `time`

and is represented by an integer.

Once opened via the slow method a proof of opening can be produced to avoid having to do so again. This proof is verifiable in logarithmic time.

In order to time-lock an arbitrary sequence of bytes, we 1. encrypt the bytes with a symmetric key, and then 2. we time-lock the symmetric key itself.

This module implements a scheme inspired by: Time-lock puzzles and timed release - Rivest, Shamir, Wagner https://people.csail.mit.edu/rivest/pubs/RSW96.pdf

!!! 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

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.

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

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

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

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 2048 bits. The size works only if we use them for a small amount of time. !!! NEW KEYS SHOULD BE GENERATED FOR EACH LOCKING !!!

`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.

`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:int ->
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:int ->
locked_value ->
unlocked_value
```

Unlock a value using the RSA secret.

```
val unlock_and_prove_with_secret :
rsa_secret ->
time:int ->
locked_value ->
unlocked_value * timelock_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:int ->
locked_value ->
unlocked_value * timelock_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:int ->
locked_value ->
unlocked_value ->
timelock_proof
```

```
val prove_with_secret :
rsa_secret ->
time:int ->
locked_value ->
unlocked_value ->
timelock_proof
```

```
val verify_timelock :
rsa_public ->
time:int ->
locked_value ->
unlocked_value ->
timelock_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:int ->
unlocked_value ->
locked_value ->
timelock_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.

`val ciphertext_encoding : ciphertext Data_encoding.t`

`val proof_encoding : timelock_proof Data_encoding.t`

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`

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 ways 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.

`val open_chest : chest -> chest_key -> time:int -> opening_result`

Takes a chest, chest key and time and tries to recover the underlying plaintext. See the documentation of opening_result.

`val get_plaintext_size : chest -> int`

Gives the size of the underlying plaintext in a chest in bytes. Used for gas accounting

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

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

```
val chest_sampler :
rng_state:Random.State.t ->
plaintext_size:int ->
time:int ->
chest * chest_key
```

----- !!!!! Do not use for wallets: the RNG is not safe !!!!---- Sampler for the gasbenchmarks. Takes an Ocaml RNG state as arg for reproducibility.