Additional data

Note: This is an advanced topic, and not essential for regular use of the encryption tools in this package.

This package uses ‘Authenticated Encryption with Additional Data (AEAD)’ to encrypt messages.

Additional data (or ‘associated data’) may be included in the encryption process. This additional data is part of the message authentication, but not part of the encrypted message.

A common way additional data is used is for encrypted data which has an unencrypted header containing meta-information. This header must be readable before the message is decrypted, but also must not allow tampering.

Worked example

An example of the use of additional data is addressing an encrypted message to a particular recipient.

The address on the envelope must be readable to allow delivery, but the message inside needs to remain confidential.

In this case, the address is the additional data - it is sent with the data, but not encrypted. Because the address forms part of the message authentication, any modification of the address will prevent the authentication of the encrypted payload.

In the following example, a message for Judy is encrypted, and the address on the envelope is used as the additional data.

library(rmonocypher)

# Using additional data to encrypt a message
file     <- tempfile()
key      <- argon2("my secret key2")
message  <- 'Meet me in St Louis' 
address  <- 'To: Judy'
enc      <- encrypt(message, file, key, additional_data = address)

# Package the additional data and deliver to recipient
letter <- list(address = address, message = file)
letter

#> $address
#> [1] "To: Judy"
#> 
#> $message
#> [1] "/tmp/RtmpYtPkkj/file8e45e26b005"

# Recipient decodes message, and the 'address' forms part of the decryption.
decrypt(letter$message, key = key, additional_data = letter$address)

#> [1] "Meet me in St Louis"

If a malicious third-party tampers with the address, then the message cannot be authenticated. E.g. if the letter is altered as if it were being sent to “Sandra”, then decryption will fail:

letter$address <- "To: Sandra"
decrypt(letter$message, key = key, additional_data = letter$address)

#> Error in decrypt(letter$message, key = key, additional_data = letter$address): decrypt_(): Decryption failed