Title:	Tool for Secure Shipment of Content
Version:	0.9.0
Maintainer:	Are Edvardsen <biorakel@gmail.com>
Description:	Convenient tools for exchanging files securely from within R. By encrypting the content safe passage of files (shipment) can be provided by common but insecure carriers such as ftp and email. Based on asymmetric cryptography no management of shared secrets is needed to make a secure shipment as long as authentic public keys are available. Public keys used for secure shipments may also be obtained from external providers as part of the overall process. Transportation of files will require that relevant services such as ftp and email servers are available.
License:	GPL-3
Encoding:	UTF-8
Imports:	httr, jsonlite, openssl, RCurl, yaml
Suggests:	httptest, httpuv, rmarkdown, testthat (≥ 2.1.0), withr
RoxygenNote:	7.2.1
URL:	https://github.com/Rapporteket/sship
BugReports:	https://github.com/Rapporteket/sship/issues
NeedsCompilation:	no
Packaged:	2022-12-12 11:51:40 UTC; rstudio
Author:	Are Edvardsen [aut, cre]
Repository:	CRAN
Date/Publication:	2022-12-12 12:20:02 UTC

Functions handling sship R package config

Description

Functions handling sship R package config

Usage

create_config(dir = ".")

write_config(config, dir = ".", filename = "_sship.yml")

get_config(dir = ".")

check_config(config)

Arguments

Value

A status message or list of config

Examples

# Create a new config file from package default
create_config(dir = tempdir())

# Get config
config <- get_config(system.file("sship.yml", package = "sship"))

# Check if config is valid
check_config(config)

# Write config to file
write_config(config, dir = tempdir())

Unpack shipment and decrypt content

Description

This function tries to reverse the process of enc and hence depend on the conventions used there.

Usage

dec(tarfile, keyfile = "~/.ssh/id_rsa", target_dir = ".")

Arguments

Details

Some of the functions used here might be vulnerable to differences between systems running R. Possible caveats may be the availability of the (un)tar-function and how binary streams/files are treated.

Value

Invisibly a character string providing the file path of the decrypted file.

See Also

enc

Examples

# Please note that these examples will write files to a local temporary
# directory.

## Make temporary workspace
wd <- tempdir()

## Make a private-public key pair named "id_rsa" and "id_rsa.pub"
keygen(directory = wd, type = "rsa", overwrite_existing = TRUE)

## Make a secured (encrypted) file
saveRDS(iris, file = file.path(wd, "secret.rds"), ascii = TRUE)
pubkey <- readLines(file.path(wd, "id_rsa.pub"))
secure_secret_file <-
  enc(filename = file.path(wd, "secret.rds"),
      pubkey_holder = NULL,
      pubkey = pubkey)

## Decrypt secured file using the private key
secret_file <-
  dec(tarfile = secure_secret_file,
      keyfile = file.path(wd, "id_rsa"),
      target_dir = wd)

Encryption of shipment content

Description

Various functions and helper functions to establish encrypted files. To secure the content (any file) the Advanced Encryption Standard (AES) is applied with an ephemeral key consisting of 256 random bits. This key is only used once for encryption (and then one more time during decryption at a later stage). A random 128 bit initialization vector (iv) is also applied during encryption. There is no extra security gain in this since the key will never be re-used for encryption/decryption. So, just for good measures then :-) After the content has been encrypted the key itself is encrypted by applying a public key offered by the recipient. This key is obtained from a public provider. Currently, GitHub is the only option. The three files: encrypted content, the encrypted key and the (cleartext) iv is then bundled into a tarball ready for shipment.

Usage

enc_filename(filename)

make_pubkey_url(pubkey_holder = "github", pid)

get_pubkey(pubkey_holder, pid)

enc(filename, pubkey_holder, pid, pubkey = NULL)

Arguments

Details

Encrypted files can be decrypted outside R using the OpenSSL library. Both the key and the initialization vector (iv) are binary and this method uses the key directly (and not a [hashed] passphrase). OpenSSL decryption need to be fed the key (and iv) as a string of hex digits. Methods for conversion from binary to hex may vary between systems. Below, a bash shell (unix) example is given

Step 1: decrypt symmetric key (open envelope) using a private key

openssl rsautl -decrypt -inkey ~/.ssh/id_rsa -in key.enc -out key

Step 2: decrypt content by key obtained in step 1, also converting key and iv to strings of hexadecimal digits

openssl aes-256-cbc -d -in data.csv.enc -out data.csv \
-K $(hexdump -e '32/1 "%02x"' key) -iv $(hexdump -e '16/1 "%02x"' iv)

Value

Character string providing a filename or a key

See Also

dec

Examples

# Please note that these examples will write files to a local temporary
# directory.

## Define temporary working directory and a secret file name
wd <- tempdir()
secret_file_name <- "secret.rds"

## Add content to the secret file
saveRDS(iris, file = file.path(wd, secret_file_name), ascii = TRUE)

## Make a private-public key pair named "id_rsa" and "id_rsa.pub"
keygen(directory = wd, type = "rsa", overwrite_existing = TRUE)

## Load public key
pubkey <- readLines(file.path(wd, "id_rsa.pub"))

## Make a secured file (ready for shipment)
secure_secret_file <- enc(filename = file.path(wd, "secret.rds"),
                          pubkey_holder = NULL, pubkey = pubkey)

Make calls to the github API

Description

Provides a structured list of the specified resource from the the github API.

Usage

gh(path, proxy_url = NULL, token = NULL)

github_api(path, proxy_url = NULL, token = NULL)

rate_limit(proxy_url = NULL, token = NULL)

Arguments

Details

For most use cases only gh() will be relevant. The helper function github_api() do the actual lifting while rate_limit() handles API rate limits.

Value

A list of class github_api containing the parsed content, API resource path and the response object. For rate_limit() the path is always "/rate_limit" and can hence be used to detect if the limit is exceeded (without being counted as a request itself). If the allowed API rate is exceeded gh() will return a message stating the fact and simple suggestions on how to remedy the problem.

Examples

## Get all branches of a repository. If the api rate limit is exceeded this
## function will return NULL and an informative message
gh("repos/Rapporteket/sship/branches")

## helper functions that will normally not be used
github_api("/rate_limit")
rate_limit()

Make private-public key pair

Description

Just for the convenience of it, make a key pair that may be used alongside sship. Please note that by default the private key will not be protected by a password.

Usage

keygen(
  directory = "~/.ssh",
  type = "rsa",
  password = NULL,
  overwrite_existing = FALSE
)

Arguments

Value

Nothing will be returned from this function, but a message containing the directory where the keys were written is provided

Examples

keygen(directory = tempdir(), overwrite_existing = TRUE)

Filter ssh public keys by type

Description

From a vector of ssh public keys, return those that are of a given type.

Usage

pubkey_filter(keys, type)

Arguments

Value

A vector of strings representing (filtered) public keys.

Examples

## make ssh public key strings
rsa_pubkey <- openssl::write_ssh(openssl::rsa_keygen()$pubkey)
dsa_pubkey <- openssl::write_ssh(openssl::dsa_keygen()$pubkey)

## filter keys by type
pubkey <- pubkey_filter(c(rsa_pubkey, dsa_pubkey), "rsa")
identical(pubkey, rsa_pubkey)

Secure cargo and make shipment (secure shipment)

Description

First, the content (a file) is encrypted and packed and then shipped to the recipient using the specified vessel (transportation method). If the given vessel is not available the function return an error. Optionally, a declaration can also be associated with the shipment and dispatched immediately after the actual cargo.

Usage

sship(content, recipient, pubkey_holder, vessel, declaration = "")

dispatch(recipient, vessel, cargo)

dispatchable(recipient, vessel)

make_url(recipient, vessel)

make_opts(recipient, vessel)

Arguments

Details

Most likely access control will be enforced before docking of the shipment can commence. For each recipient a list of available vessels (transport methods) is defined and must include relevant credentials. Functions used here rely on local configuration (sship.yml) to access such credentials.

Value

TRUE if successful

See Also

enc

Standard sship symmetric decryption

Description

Standard sship symmetric decryption

Usage

sym_dec(data, key, iv = attr(data, "iv"))

Arguments

Value

A raw vector of decrypted data.

Standard sship symmetric encryption

Description

Standard sship symmetric encryption

Usage

sym_enc(data, key, iv = openssl::rand_bytes(16))

Arguments

Value

A raw vector of encrypted data.