EVOLUTION-MANAGER
Edit File: ssl_ctx.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>R: Hooks to manipulate the SSL context for curl requests</title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <link rel="stylesheet" type="text/css" href="R.css" /> </head><body> <table width="100%" summary="page for ssl_ctx {openssl}"><tr><td>ssl_ctx {openssl}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2>Hooks to manipulate the SSL context for curl requests</h2> <h3>Description</h3> <p>These functions allow for manipulating the SSL context from inside the <a href="https://curl.se/libcurl/c/CURLOPT_SSL_CTX_FUNCTION.html">CURLOPT_SSL_CTX_FUNCTION</a> callback using the curl R package. Note that this is not fully portable and will only work on installations that use matching versions of libssl (see details). It is recommended to only use this locally and if what you need cannot be accomplished using standard libcurl TLS options, e.g. those listed in <code>curl::curl_options('ssl')</code> or <code>curl::curl_options('tls')</code>. </p> <h3>Usage</h3> <pre> ssl_ctx_add_cert_to_store(ssl_ctx, cert) ssl_ctx_set_verify_callback(ssl_ctx, cb) ssl_ctx_curl_version_match() </pre> <h3>Arguments</h3> <table summary="R argblock"> <tr valign="top"><td><code>ssl_ctx</code></td> <td> <p>pointer object to the SSL context provided in the ssl_ctx_function callback.</p> </td></tr> <tr valign="top"><td><code>cert</code></td> <td> <p>certificate object, e.g from <a href="read_key.html">read_cert</a> or <a href="certificates.html">download_ssl_cert</a>.</p> </td></tr> <tr valign="top"><td><code>cb</code></td> <td> <p>callback function with 1 parameter (the server certificate) and which returns TRUE (for proceed) or FALSE (for abort).</p> </td></tr> </table> <h3>Details</h3> <p>Curl allows for setting an <a href="../../curl/html/curl_options.html">option</a> called <code>ssl_ctx_function</code>: this is a callback function that is triggered during the TLS initiation, before any https connection has been made. This serves as a hook to let you manipulate the TLS configuration (called <code>SSL_CTX</code> for historical reasons), in order to control how to curl will validate the authenticity of server certificates for upcoming TLS connections. </p> <p>Currently we provide 2 such functions: <a href="ssl_ctx.html">ssl_ctx_add_cert_to_store</a> injects a custom certificate into the trust-store of the current TLS connection. But most flexibility is provided via <a href="ssl_ctx.html">ssl_ctx_set_verify_callback</a> which allows you to override the function that is used by validate if a server certificate should be trusted. The callback will receive one argument <code>cert</code> and has to return <code>TRUE</code> or <code>FALSE</code> to decide if the cert should be trusted. </p> <p>By default libcurl re-uses connections, hence the cert validation is only performed in the first request to a given host. Subsequent requests use the already established TLS connection. For testing, it can be useful to set <code>forbid_reuse</code> in order to make a new connection for each request, as done in the examples below. </p> <h3>System compatibility</h3> <p>Passing the SSL_CTX between the curl and openssl R packages only works if they are linked to the same version of libssl. Use <a href="ssl_ctx.html">ssl_ctx_curl_version_match</a> to test if this is the case. On Debian / Ubuntu you need to build the R curl package against <code>libcurl4-openssl-dev</code>, which is usually the case. On Windows you would need to set <code>CURL_SSL_BACKEND=openssl</code> in your <code style="white-space: pre;">~/.Renviron</code> file. On MacOS things are complicated because it uses LibreSSL instead of OpenSSL by default. You can make it work by compiling the curl R package from source against the homebrew version of curl and then then set <code>CURL_SSL_BACKEND=openssl</code> in your <code style="white-space: pre;">~/.Renviron</code> file. If your curl and openssl R packages use different versions of libssl, the examples may segfault due to ABI incompatibility of the SSL_CTX structure. </p> <h3>Examples</h3> <pre> ## Not run: # Example 1: accept your local snakeoil https cert mycert <- openssl::download_ssl_cert('localhost')[[1]] # Setup the callback h <- curl::new_handle(ssl_ctx_function = function(ssl_ctx){ ssl_ctx_add_cert_to_store(ssl_ctx, mycert) }, verbose = TRUE, forbid_reuse = TRUE) # Perform the request req <- curl::curl_fetch_memory('https://localhost', handle = h) # Example 2 using a custom verify function verify_cb <- function(cert){ id <- cert$pubkey$fingerprint cat("Server cert from:", as.character(id), "\n") TRUE # always accept cert } h <- curl::new_handle(ssl_ctx_function = function(ssl_ctx){ ssl_ctx_set_verify_callback(ssl_ctx, verify_cb) }, verbose = TRUE, forbid_reuse = TRUE) # Perform the request req <- curl::curl_fetch_memory('https://localhost', handle = h) ## End(Not run) </pre> <hr /><div style="text-align: center;">[Package <em>openssl</em> version 2.0.4 <a href="00Index.html">Index</a>]</div> </body></html>