---
title: "Technical Notes"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Technical Notes}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```


# General Technical Notes

* Objects are encrypted in memory prior to writing to file
* `encrypt()`/`decrypt()` can process any R object understood by `serialize()`

The encryption technique in this package is [XChaCha20-Poly1305](https://en.wikipedia.org/wiki/ChaCha20-Poly1305)
which is the [extended nonce](https://en.wikipedia.org/wiki/ChaCha20-Poly1305#XChaCha20-Poly1305_%E2%80%93_extended_nonce_variant) variant of the ChaCha20-Poly1305 technique used in 
[IPsec](https://en.wikipedia.org/wiki/IPsec), 
[SSH](https://en.wikipedia.org/wiki/Secure_Shell) and 
[Wireguard](https://en.wikipedia.org/wiki/WireGuard).

The encryption method follows RFC 8439 ['Authenticated Encryption with Additional Data (AEAD)'](https://en.wikipedia.org/wiki/Authenticated_encryption#Authenticated_encryption_with_associated_data_(AEAD)) 

* The nonce used within 'monocypher' is 24-bytes (192 bits).  This is large enough that 
  counter/ratcheting mechanisms do not need to be used, and random bytes are 
  unlikely to generate the same nonce twice in any reasonable timeframe.
* The nonce is created internally using random bytes from the cryptographic random number
  generator from the system this is running on.
* In general when encrypting data using Authenticated Encryption:
    * Keep the following items **secret**:
        * the original data (obviously!)
        * the encryption key.
    * These items are **not secret**:
        * Nonce
        * MAC - message authentication code
        * Number of bytes of data


### File structure

The data structure is a concatenation of the nonce, mac and encrypted data

* `[nonce] [mac] [encrypted data]`
    * `[nonce]` = 24 bytes
    * `[mac]` = 16 bytes
    * `[encrypted data]` = remaining bytes

### Included Cryptographic Libraries 

The package relies on the cryptographic algorithms supplied by [`monocypher`](https://monocypher.org/)