diff --git a/NAMESPACE b/NAMESPACE index 3af5c927..00885ee1 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -10,6 +10,7 @@ export(crew_class_controller_group) export(crew_class_launcher) export(crew_class_launcher_local) export(crew_class_schedule) +export(crew_class_tls) export(crew_clean) export(crew_client) export(crew_controller) @@ -22,6 +23,7 @@ export(crew_launcher_local) export(crew_random_name) export(crew_retry) export(crew_schedule) +export(crew_tls) export(crew_worker) export(ends_with) export(everything) diff --git a/R/crew_client.R b/R/crew_client.R index 25e261ef..be364d3f 100644 --- a/R/crew_client.R +++ b/R/crew_client.R @@ -9,31 +9,12 @@ #' If `NULL`, the host defaults to the local IP address. #' @param port TCP port to listen for the workers. If `NULL`, #' then an available ephemeral port is automatically chosen. -#' @param tls_enable Logical of length 1, whether to use transport layer -#' security (TLS) to secure connections between the client and workers. -#' Only supported for `mirai` version 0.9.0.9020 and above and -#' `nanonext` version 0.9.0.9034 and above. -#' Uses an automatically generated one-time self-signed certificate by -#' default. To guard against man-in-the-middle attacks, consider -#' generating a one-time certificate yourself, requesting a trusted -#' certificate authority (CA) to sign it, and then supplying the -#' keys to the `tls_config` argument. Enabling TLS requires `mirai` -#' version 0.9.0.9027 or above, and a `NULL` value for `tls_enable` -#' will enable TLS if and only if the `mirai` version is sufficient. -#' @param tls_config Optional and only relevant if TLS is enabled -#' (see the `tls_config` argument). The `tls_config` argument -#' controls how transport layer security (TLS) is configured, -#' and it is directly forwarded to the `tls` argument of -#' `mirai::daemons()`. If `tls_config` is `NULL`, -#' then `mirai` will generate a one-time -#' self-signed certificate. This default approach is protects against -#' the simplest attempts at packet sniffing, but it is still vulnerable -#' to man-in-the-middle attacks. When greater security is required, -#' consider generating a PEM-encoded certificate and associated -#' private key yourself and using a trusted certificate authority (CA) -#' to sign the former. The documentation of `mirai`, including the -#' `tls` arguments of the `mirai::daemons()` and `mirai::daemon()` -#' functions, has more details. +#' @param tls Either `NULL` to disable transport layer security (TLS) +#' or a TLS configuration object from [crew_tls()]. +#' @param tls_enable Deprecated on 2023-09-15 in version 0.4.1. +#' Use argument `tls` instead. +#' @param tls_config Deprecated on 2023-09-15 in version 0.4.1. +#' Use argument `tls` instead. #' @param seconds_interval Number of seconds between #' polling intervals waiting for certain internal #' synchronous operations to complete. If `space_poll` is `TRUE`, then diff --git a/R/crew_tls.R b/R/crew_tls.R new file mode 100644 index 00000000..743907fd --- /dev/null +++ b/R/crew_tls.R @@ -0,0 +1,246 @@ +#' @title Configure TLS. +#' @export +#' @family user +#' @description Create an `R6` object with transport layer security (TLS) +#' configuration for `crew`. +#' @details See for +#' details. +#' @return An `R6` object with TLS configuration settings and methods. +#' @param mode Character of length 1. Must be one of the following: +#' * `"none"`: disable TLS configuration. +#' * `"automatic"`: let `mirai` create a one-time key pair with a +#' self-signed certificate. +#' * `"custom"`: manually supply a private key pair, an optional +#' password for the private key, a certificate, +#' an optional revocation list. +#' @param key If `mode` is `"none"` or `"automatic"`, then `key` is `NULL`. +#' If `mode` is `"custom"`, then `key` is a character of length 1 +#' with the file path to the private key file. +#' @param password If `mode` is `"none"` or `"automatic"`, +#' then `password` is `NULL`. +#' If `mode` is `"custom"` and the private key is not encrypted, then +#' `password` is still `NULL`. +#' If `mode` is `"custom"` and the private key is encrypted, +#' then `password` is a character of length 1 the the password of the private +#' key. In this case, DO NOT SAVE THE PASSWORD IN YOUR R CODE FILES. +#' See the `keyring` R package for solutions. +#' @param certificates If `mode` is `"none"` or `"automatic"`, +#' then `certificates` is `NULL`. +#' If `mode` is `"custom"`, then `certificates` is a character vector +#' of file paths to certificate files (signed public keys). +#' If the certificate is self-signed or if it is +#' directly signed by a certificate authority (CA), +#' then only the certificate of the CA is needed. But if you have a whole +#' certificate chain which begins at your own certificate and ends with the +#' CA, then you can supply the whole certificate chain as a character vector +#' which begins at your own certificate and ends with +#' the certificate of the CA. +#' @examples +#' crew_tls(mode = "automatic") +crew_tls <- function( + mode = "none", + key = NULL, + password = NULL, + certificates = NULL +) { + tls <- crew_class_tls$new( + name = crew::crew_random_name(), + mode = mode, + key = key, + password = password, + certificates = certificates + ) + tls$validate() + tls +} + +#' @title `R6` TLS class. +#' @export +#' @family class +#' @description `R6` class for TLS configuration. +#' @details See [crew_tls()]. +#' @examples +#' crew_tls(mode = "automatic") +crew_class_tls <- R6::R6Class( + classname = "crew_class_tls", + cloneable = FALSE, + public = list( + #' @field name Name of the [crew_client()] object paired with this TLS + #' object. Automatically set in [crew_client()]. + name = NULL, + #' @field mode See [crew_tls()]. + mode = NULL, + #' @field key See [crew_tls()]. + key = NULL, + #' @field password See [crew_tls()]. + password = NULL, + #' @field certificates See [crew_tls()]. + certificates = NULL, + #' @description TLS configuration constructor. + #' @return An `R6` object with TLS configuration. + #' @param name Name of the [crew_tls()] object paired with this TLS + #' object. Automatically set in [crew_tls()]. + #' @param mode Argument passed from [crew_tls()]. + #' @param key Argument passed from [crew_tls()]. + #' @param password Argument passed from [crew_tls()]. + #' @param certificates Argument passed from [crew_tls()]. + #' @examples + #' crew_tls(mode = "automatic") + initialize = function( + name = NULL, + mode = NULL, + key = NULL, + password = NULL, + certificates = NULL + ) { + self$name <- name + self$mode <- mode + self$key <- key + self$password <- password + self$certificates <- certificates + }, + #' @description Validate the object. + #' @return `NULL` (invisibly). + validate = function() { + for (field in c("name", "mode")) { + crew_assert( + self[[field]], + is.character(.), + length(.) == 1L, + nzchar(.), + !anyNA(.), + message = paste( + "crew_tls() argument", + field, + "must be a character of length 1" + ) + ) + } + crew_assert( + crew_assert( + self$mode %in% c("none", "automatic", "custom"), + message = "TLS mode must be \"none\", \"automatic\", or \"custom\"." + ) + ) + if_any( + self$mode %in% c("none", "automatic"), + self$validate_mode_automatic(), + self$validate_mode_custom() + ) + invisible() + }, + #' @description Validation for non-custom modes. + #' @return `NULL` (invisibly). + validate_mode_automatic = function() { + for (field in c("key", "password", "certificates")) { + crew_assert( + is.null(self[[field]]), + message = paste( + "If mode is not \"custom\" in crew_tls(), then", + field, + "must be NULL." + ) + ) + } + invisible() + }, + #' @description Validation for custom mode. + #' @return `NULL` (invisibly). + validate_mode_custom = function() { + for (field in c("key", "password", "certificates")) { + crew_assert( + self[[field]], + is.character(.), + length(.) >= 1L, + nzchar(.), + !anyNA(.), + message = paste( + "If mode is \"custom\", then crew_tls() argument", + field, + "must be of type character and be non-missing and nonempty." + ) + ) + } + for (field in c("key", "password")) { + crew_assert( + length(self[[field]]) == 1L, + message = paste( + "If mode is \"custom\", then crew_tls() argument", + field, + "must have length 1." + ) + ) + } + files <- c(self$key, self$certificates) + for (file in files) { + crew_assert( + file.exists(file), + message = paste("file not found:", file) + ) + } + crew_tls_assert_key(self$key) + for (certificate in self$certificates) { + crew_tls_assert_certificate(certificate) + } + invisible() + } + ) +) + +crew_tls_assert_key <- function(key) { + crew_assert( + file.exists(key), + message = "private key file not found" + ) + lines <- readLines(key) + crew_assert( + length(lines) > 0L, + message = "private key file is empty" + ) + crew_assert( + lines[1L] == "-----BEGIN PRIVATE KEY-----" || + lines[1L] == "-----BEGIN ENCRYPTED PRIVATE KEY-----", + message = paste( + "private key file must begin with the line", + "-----BEGIN PRIVATE KEY----- or -----BEGIN ENCRYPTED PRIVATE KEY-----.", + "please make sure you have a valid private key in PEM format." + ) + ) + crew_assert( + lines[length(lines)] == "-----END PRIVATE KEY-----" || + lines[length(lines)] == "-----END ENCRYPTED PRIVATE KEY-----", + message = paste( + "private key file must end with the line", + "-----END PRIVATE KEY----- or -----END ENCRYPTED PRIVATE KEY-----.", + "please make sure you have a valid private key in PEM format." + ) + ) +} + +crew_tls_assert_certificate <- function(certificate) { + crew_assert( + file.exists(certificate), + message = paste("certificate file not found:", certificate) + ) + lines <- readLines(certificate) + crew_assert( + length(lines) > 0L, + message = paste("certificate file is empty:", certificate) + ) + crew_assert( + lines[1L] == "-----BEGIN CERTIFICATE-----", + message = paste( + "certificate file must begin with the line", + "-----BEGIN CERTIFICATE-----.", + "please make sure you have a valid certificate in PEM format." + ) + ) + crew_assert( + lines[length(lines)] == "-----BEGIN CERTIFICATE-----", + message = paste( + "certificate file must end with the line", + "-----BEGIN CERTIFICATE-----.", + "please make sure you have a valid certificate in PEM format." + ) + ) +} diff --git a/_pkgdown.yml b/_pkgdown.yml index d062bd88..044ca840 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -16,6 +16,7 @@ reference: - '`crew_controller_local`' - '`crew_controller_group`' - '`crew-package`' + - '`crew_tls`' - title: Launcher plugin development contents: - '`crew_client`' diff --git a/man/crew-package.Rd b/man/crew-package.Rd index 3b62ace9..0db50f38 100644 --- a/man/crew-package.Rd +++ b/man/crew-package.Rd @@ -27,6 +27,7 @@ and \href{https://mllg.github.io/batchtools/}{\code{batchtools}}. Other user: \code{\link{crew_clean}()}, \code{\link{crew_controller_group}()}, -\code{\link{crew_controller_local}()} +\code{\link{crew_controller_local}()}, +\code{\link{crew_tls}()} } \concept{user} diff --git a/man/crew_class_client.Rd b/man/crew_class_client.Rd index dba63a86..6cd1fc60 100644 --- a/man/crew_class_client.Rd +++ b/man/crew_class_client.Rd @@ -33,7 +33,8 @@ Other class: \code{\link{crew_class_controller_group}}, \code{\link{crew_class_controller}}, \code{\link{crew_class_launcher}}, -\code{\link{crew_class_schedule}} +\code{\link{crew_class_schedule}}, +\code{\link{crew_class_tls}} } \concept{class} \section{Public fields}{ diff --git a/man/crew_class_controller.Rd b/man/crew_class_controller.Rd index 95bad265..847585c1 100644 --- a/man/crew_class_controller.Rd +++ b/man/crew_class_controller.Rd @@ -41,7 +41,8 @@ Other class: \code{\link{crew_class_client}}, \code{\link{crew_class_controller_group}}, \code{\link{crew_class_launcher}}, -\code{\link{crew_class_schedule}} +\code{\link{crew_class_schedule}}, +\code{\link{crew_class_tls}} } \concept{class} \section{Public fields}{ diff --git a/man/crew_class_controller_group.Rd b/man/crew_class_controller_group.Rd index 3de6e66a..68c4cbc1 100644 --- a/man/crew_class_controller_group.Rd +++ b/man/crew_class_controller_group.Rd @@ -47,7 +47,8 @@ Other class: \code{\link{crew_class_client}}, \code{\link{crew_class_controller}}, \code{\link{crew_class_launcher}}, -\code{\link{crew_class_schedule}} +\code{\link{crew_class_schedule}}, +\code{\link{crew_class_tls}} } \concept{class} \section{Public fields}{ diff --git a/man/crew_class_launcher.Rd b/man/crew_class_launcher.Rd index 2dd2e9bd..8339573d 100644 --- a/man/crew_class_launcher.Rd +++ b/man/crew_class_launcher.Rd @@ -53,7 +53,8 @@ Other class: \code{\link{crew_class_client}}, \code{\link{crew_class_controller_group}}, \code{\link{crew_class_controller}}, -\code{\link{crew_class_schedule}} +\code{\link{crew_class_schedule}}, +\code{\link{crew_class_tls}} } \concept{class} \section{Public fields}{ diff --git a/man/crew_class_schedule.Rd b/man/crew_class_schedule.Rd index ee681757..8f923aa9 100644 --- a/man/crew_class_schedule.Rd +++ b/man/crew_class_schedule.Rd @@ -15,7 +15,8 @@ Other class: \code{\link{crew_class_client}}, \code{\link{crew_class_controller_group}}, \code{\link{crew_class_controller}}, -\code{\link{crew_class_launcher}} +\code{\link{crew_class_launcher}}, +\code{\link{crew_class_tls}} } \concept{class} \section{Public fields}{ diff --git a/man/crew_class_tls.Rd b/man/crew_class_tls.Rd new file mode 100644 index 00000000..33947680 --- /dev/null +++ b/man/crew_class_tls.Rd @@ -0,0 +1,137 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/crew_tls.R +\name{crew_class_tls} +\alias{crew_class_tls} +\title{\code{R6} TLS class.} +\description{ +\code{R6} class for TLS configuration. +} +\details{ +See \code{\link[=crew_tls]{crew_tls()}}. +} +\examples{ +crew_tls(mode = "automatic") + +## ------------------------------------------------ +## Method `crew_class_tls$new` +## ------------------------------------------------ + +crew_tls(mode = "automatic") +} +\seealso{ +Other class: +\code{\link{crew_class_client}}, +\code{\link{crew_class_controller_group}}, +\code{\link{crew_class_controller}}, +\code{\link{crew_class_launcher}}, +\code{\link{crew_class_schedule}} +} +\concept{class} +\section{Public fields}{ +\if{html}{\out{
}} +\describe{ +\item{\code{name}}{Name of the \code{\link[=crew_client]{crew_client()}} object paired with this TLS +object. Automatically set in \code{\link[=crew_client]{crew_client()}}.} + +\item{\code{mode}}{See \code{\link[=crew_tls]{crew_tls()}}.} + +\item{\code{key}}{See \code{\link[=crew_tls]{crew_tls()}}.} + +\item{\code{password}}{See \code{\link[=crew_tls]{crew_tls()}}.} + +\item{\code{certificates}}{See \code{\link[=crew_tls]{crew_tls()}}.} +} +\if{html}{\out{
}} +} +\section{Methods}{ +\subsection{Public methods}{ +\itemize{ +\item \href{#method-crew_class_tls-new}{\code{crew_class_tls$new()}} +\item \href{#method-crew_class_tls-validate}{\code{crew_class_tls$validate()}} +\item \href{#method-crew_class_tls-validate_mode_automatic}{\code{crew_class_tls$validate_mode_automatic()}} +\item \href{#method-crew_class_tls-validate_mode_custom}{\code{crew_class_tls$validate_mode_custom()}} +} +} +\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-crew_class_tls-new}{}}} +\subsection{Method \code{new()}}{ +TLS configuration constructor. +\subsection{Usage}{ +\if{html}{\out{
}}\preformatted{crew_class_tls$new( + name = NULL, + mode = NULL, + key = NULL, + password = NULL, + certificates = NULL +)}\if{html}{\out{
}} +} + +\subsection{Arguments}{ +\if{html}{\out{
}} +\describe{ +\item{\code{name}}{Name of the \code{\link[=crew_tls]{crew_tls()}} object paired with this TLS +object. Automatically set in \code{\link[=crew_tls]{crew_tls()}}.} + +\item{\code{mode}}{Argument passed from \code{\link[=crew_tls]{crew_tls()}}.} + +\item{\code{key}}{Argument passed from \code{\link[=crew_tls]{crew_tls()}}.} + +\item{\code{password}}{Argument passed from \code{\link[=crew_tls]{crew_tls()}}.} + +\item{\code{certificates}}{Argument passed from \code{\link[=crew_tls]{crew_tls()}}.} +} +\if{html}{\out{
}} +} +\subsection{Returns}{ +An \code{R6} object with TLS configuration. +} +\subsection{Examples}{ +\if{html}{\out{
}} +\preformatted{crew_tls(mode = "automatic") +} +\if{html}{\out{
}} + +} + +} +\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-crew_class_tls-validate}{}}} +\subsection{Method \code{validate()}}{ +Validate the object. +\subsection{Usage}{ +\if{html}{\out{
}}\preformatted{crew_class_tls$validate()}\if{html}{\out{
}} +} + +\subsection{Returns}{ +\code{NULL} (invisibly). +} +} +\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-crew_class_tls-validate_mode_automatic}{}}} +\subsection{Method \code{validate_mode_automatic()}}{ +Validation for non-custom modes. +\subsection{Usage}{ +\if{html}{\out{
}}\preformatted{crew_class_tls$validate_mode_automatic()}\if{html}{\out{
}} +} + +\subsection{Returns}{ +\code{NULL} (invisibly). +} +} +\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-crew_class_tls-validate_mode_custom}{}}} +\subsection{Method \code{validate_mode_custom()}}{ +Validation for custom mode. +\subsection{Usage}{ +\if{html}{\out{
}}\preformatted{crew_class_tls$validate_mode_custom()}\if{html}{\out{
}} +} + +\subsection{Returns}{ +\code{NULL} (invisibly). +} +} +} diff --git a/man/crew_clean.Rd b/man/crew_clean.Rd index 25f700f6..29cb6483 100644 --- a/man/crew_clean.Rd +++ b/man/crew_clean.Rd @@ -61,6 +61,7 @@ crew_clean() Other user: \code{\link{crew-package}}, \code{\link{crew_controller_group}()}, -\code{\link{crew_controller_local}()} +\code{\link{crew_controller_local}()}, +\code{\link{crew_tls}()} } \concept{user} diff --git a/man/crew_client.Rd b/man/crew_client.Rd index a33af7cb..8c431e6c 100644 --- a/man/crew_client.Rd +++ b/man/crew_client.Rd @@ -27,32 +27,11 @@ If \code{NULL}, the host defaults to the local IP address.} \item{port}{TCP port to listen for the workers. If \code{NULL}, then an available ephemeral port is automatically chosen.} -\item{tls_enable}{Logical of length 1, whether to use transport layer -security (TLS) to secure connections between the client and workers. -Only supported for \code{mirai} version 0.9.0.9020 and above and -\code{nanonext} version 0.9.0.9034 and above. -Uses an automatically generated one-time self-signed certificate by -default. To guard against man-in-the-middle attacks, consider -generating a one-time certificate yourself, requesting a trusted -certificate authority (CA) to sign it, and then supplying the -keys to the \code{tls_config} argument. Enabling TLS requires \code{mirai} -version 0.9.0.9027 or above, and a \code{NULL} value for \code{tls_enable} -will enable TLS if and only if the \code{mirai} version is sufficient.} +\item{tls_enable}{Deprecated on 2023-09-15 in version 0.4.1. +Use argument \code{tls} instead.} -\item{tls_config}{Optional and only relevant if TLS is enabled -(see the \code{tls_config} argument). The \code{tls_config} argument -controls how transport layer security (TLS) is configured, -and it is directly forwarded to the \code{tls} argument of -\code{mirai::daemons()}. If \code{tls_config} is \code{NULL}, -then \code{mirai} will generate a one-time -self-signed certificate. This default approach is protects against -the simplest attempts at packet sniffing, but it is still vulnerable -to man-in-the-middle attacks. When greater security is required, -consider generating a PEM-encoded certificate and associated -private key yourself and using a trusted certificate authority (CA) -to sign the former. The documentation of \code{mirai}, including the -\code{tls} arguments of the \code{mirai::daemons()} and \code{mirai::daemon()} -functions, has more details.} +\item{tls_config}{Deprecated on 2023-09-15 in version 0.4.1. +Use argument \code{tls} instead.} \item{seconds_interval}{Number of seconds between polling intervals waiting for certain internal @@ -62,6 +41,9 @@ this is also the minimum number of seconds between calls to \item{seconds_timeout}{Number of seconds until timing out while waiting for certain synchronous operations to complete.} + +\item{tls}{Either \code{NULL} to disable transport layer security (TLS) +or a TLS configuration object from \code{\link[=crew_tls]{crew_tls()}}.} } \description{ Create an \code{R6} wrapper object to manage the \code{mirai} client. diff --git a/man/crew_controller_group.Rd b/man/crew_controller_group.Rd index 79e615f5..595f5acd 100644 --- a/man/crew_controller_group.Rd +++ b/man/crew_controller_group.Rd @@ -34,6 +34,7 @@ group$terminate() Other user: \code{\link{crew-package}}, \code{\link{crew_clean}()}, -\code{\link{crew_controller_local}()} +\code{\link{crew_controller_local}()}, +\code{\link{crew_tls}()} } \concept{user} diff --git a/man/crew_controller_local.Rd b/man/crew_controller_local.Rd index dd3fbefd..585a05a4 100644 --- a/man/crew_controller_local.Rd +++ b/man/crew_controller_local.Rd @@ -38,32 +38,11 @@ If \code{NULL}, the host defaults to the local IP address.} \item{port}{TCP port to listen for the workers. If \code{NULL}, then an available ephemeral port is automatically chosen.} -\item{tls_enable}{Logical of length 1, whether to use transport layer -security (TLS) to secure connections between the client and workers. -Only supported for \code{mirai} version 0.9.0.9020 and above and -\code{nanonext} version 0.9.0.9034 and above. -Uses an automatically generated one-time self-signed certificate by -default. To guard against man-in-the-middle attacks, consider -generating a one-time certificate yourself, requesting a trusted -certificate authority (CA) to sign it, and then supplying the -keys to the \code{tls_config} argument. Enabling TLS requires \code{mirai} -version 0.9.0.9027 or above, and a \code{NULL} value for \code{tls_enable} -will enable TLS if and only if the \code{mirai} version is sufficient.} - -\item{tls_config}{Optional and only relevant if TLS is enabled -(see the \code{tls_config} argument). The \code{tls_config} argument -controls how transport layer security (TLS) is configured, -and it is directly forwarded to the \code{tls} argument of -\code{mirai::daemons()}. If \code{tls_config} is \code{NULL}, -then \code{mirai} will generate a one-time -self-signed certificate. This default approach is protects against -the simplest attempts at packet sniffing, but it is still vulnerable -to man-in-the-middle attacks. When greater security is required, -consider generating a PEM-encoded certificate and associated -private key yourself and using a trusted certificate authority (CA) -to sign the former. The documentation of \code{mirai}, including the -\code{tls} arguments of the \code{mirai::daemons()} and \code{mirai::daemon()} -functions, has more details.} +\item{tls_enable}{Deprecated on 2023-09-15 in version 0.4.1. +Use argument \code{tls} instead.} + +\item{tls_config}{Deprecated on 2023-09-15 in version 0.4.1. +Use argument \code{tls} instead.} \item{seconds_interval}{Number of seconds between polling intervals waiting for certain internal @@ -152,6 +131,7 @@ controller$terminate() Other user: \code{\link{crew-package}}, \code{\link{crew_clean}()}, -\code{\link{crew_controller_group}()} +\code{\link{crew_controller_group}()}, +\code{\link{crew_tls}()} } \concept{user} diff --git a/man/crew_tls.Rd b/man/crew_tls.Rd new file mode 100644 index 00000000..4644c2be --- /dev/null +++ b/man/crew_tls.Rd @@ -0,0 +1,66 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/crew_tls.R +\name{crew_tls} +\alias{crew_tls} +\title{Configure TLS.} +\usage{ +crew_tls(mode = "none", key = NULL, password = NULL, certificates = NULL) +} +\arguments{ +\item{mode}{Character of length 1. Must be one of the following: +\itemize{ +\item \code{"none"}: disable TLS configuration. +\item \code{"automatic"}: let \code{mirai} create a one-time key pair with a +self-signed certificate. +\item \code{"custom"}: manually supply a private key pair, an optional +password for the private key, a certificate, +an optional revocation list. +}} + +\item{key}{If \code{mode} is \code{"none"} or \code{"automatic"}, then \code{key} is \code{NULL}. +If \code{mode} is \code{"custom"}, then \code{key} is a character of length 1 +with the file path to the private key file.} + +\item{password}{If \code{mode} is \code{"none"} or \code{"automatic"}, +then \code{password} is \code{NULL}. +If \code{mode} is \code{"custom"} and the private key is not encrypted, then +\code{password} is still \code{NULL}. +If \code{mode} is \code{"custom"} and the private key is encrypted, +then \code{password} is a character of length 1 the the password of the private +key. In this case, DO NOT SAVE THE PASSWORD IN YOUR R CODE FILES. +See the \code{keyring} R package for solutions.} + +\item{certificates}{If \code{mode} is \code{"none"} or \code{"automatic"}, +then \code{certificates} is \code{NULL}. +If \code{mode} is \code{"custom"}, then \code{certificates} is a character vector +of file paths to certificate files (signed public keys). +If the certificate is self-signed or if it is +directly signed by a certificate authority (CA), +then only the certificate of the CA is needed. But if you have a whole +certificate chain which begins at your own certificate and ends with the +CA, then you can supply the whole certificate chain as a character vector +which begins at your own certificate and ends with +the certificate of the CA.} +} +\value{ +An \code{R6} object with TLS configuration settings and methods. +} +\description{ +Create an \code{R6} object with transport layer security (TLS) +configuration for \code{crew}. +} +\details{ +See \url{https://wlandau.github.io/crew/articles/risks.html} for +details. +} +\examples{ +crew_tls(mode = "automatic") +} +\seealso{ +Other user: +\code{\link{crew-package}}, +\code{\link{crew_clean}()}, +\code{\link{crew_controller_group}()}, +\code{\link{crew_controller_local}()} +} +\concept{user}