Add initial TLS support to dropshot (#224)

This adds a new (optional) configuration table for making Dropshot listen for HTTP-over-TLS connections instead of plain HTTP:

  [http_api_server]
  bind_address = "127.0.0.1:0"
  request_body_max_bytes = 1024
  [http_api_server.tls]
  cert_file = "/path/to/certs.pem"
  key_file = "/path/to/key.pem"

When TLS is enabled, only TLS connections will be accepted.

Author: teisenbe

Cargo.lock

@@ -11,6 +11,7 @@ keywords = ["rest", "openapi", "async"]
 categories = ["network-programming", "web-programming::http-server"]
 
 [dependencies]
+async-stream = "0.3.2"
 async-trait = "0.1.52"
 base64 = "0.13.0"
 bytes = "1"
@@ -22,13 +23,16 @@ openapiv3 = "=1.0.0"
 paste = "1.0.6"
 percent-encoding = "2.1.0"
 proc-macro2 = "1.0.36"
+rustls = "0.20.2"
+rustls-pemfile = "0.2.1"
 serde_json = "1.0.74"
 serde_urlencoded = "0.7.0"
 slog-async = "2.4.0"
 slog-bunyan = "2.2.0"
 slog-json = "2.4.0"
 slog-term = "2.5.0"
 syn = "1.0.85"
+tokio-rustls = "0.23.2"
 toml = "0.5.6"
 
 [dependencies.chrono]
@@ -69,13 +73,23 @@ features = [ "uuid" ]
 
 [dev-dependencies]
 expectorate = "1.0.4"
+hyper-rustls = "0.23.0"
 hyper-staticfile = "0.8"
 lazy_static = "1.4.0"
 libc = "0.2.112"
 mime_guess = "2.0.3"
 subprocess = "0.2.8"
 tempfile = "3.3"
 trybuild = "1.0.53"
+# Used by the https examples and tests
+pem = "1.0"
+rcgen = "0.8.14"
+
+[dev-dependencies.rustls]
+version = "0.20.2"
+# This is needed to use with_custom_certificate_verifier in tests
+# https://docs.rs/rustls/0.20.2/src/rustls/client/builder.rs.html#34-49
+features = [ "dangerous_configuration" ]
 
 [dev-dependencies.schemars]
 version = "0.8.8"

dropshot/Cargo.toml

@@ -0,0 +1,194 @@
+// Copyright 2020 Oxide Computer Company
+
+/*!
+ * Example use of Dropshot with TLS enabled
+ */
+
+use dropshot::endpoint;
+use dropshot::ApiDescription;
+use dropshot::ConfigDropshot;
+use dropshot::ConfigLogging;
+use dropshot::ConfigLoggingLevel;
+use dropshot::ConfigTls;
+use dropshot::HttpError;
+use dropshot::HttpResponseOk;
+use dropshot::HttpResponseUpdatedNoContent;
+use dropshot::HttpServerStarter;
+use dropshot::RequestContext;
+use dropshot::TypedBody;
+use schemars::JsonSchema;
+use serde::Deserialize;
+use serde::Serialize;
+use std::io::Write;
+use std::sync::atomic::AtomicU64;
+use std::sync::atomic::Ordering;
+use std::sync::Arc;
+use tempfile::NamedTempFile;
+
+/*
+ * This function would not be used in a normal application. It is used to
+ * generate temporary keys and certificates for the purpose of this demo.
+ */
+fn generate_keys() -> Result<(NamedTempFile, NamedTempFile), String> {
+    let keypair =
+        rcgen::generate_simple_self_signed(vec!["localhost".to_string()])
+            .map_err(|e| e.to_string())?;
+    let cert = keypair.serialize_pem().map_err(|e| e.to_string())?;
+    let priv_key = keypair.serialize_private_key_pem();
+
+    let make_temp = || {
+        tempfile::Builder::new()
+            .prefix("dropshot-https-example-")
+            .rand_bytes(5)
+            .tempfile()
+    };
+
+    let mut cert_file =
+        make_temp().map_err(|_| "failed to create cert_file")?;
+    cert_file
+        .write(cert.as_bytes())
+        .map_err(|_| "failed to write cert_file")?;
+    let mut key_file = make_temp().map_err(|_| "failed to create key_file")?;
+    key_file
+        .write(priv_key.as_bytes())
+        .map_err(|_| "failed to write key_file")?;
+    Ok((cert_file, key_file))
+}
+
+#[tokio::main]
+async fn main() -> Result<(), String> {
+    /*
+     * Begin by generating TLS certificates and keys. A normal application would
+     * just pass the paths to these via ConfigDropshot.
+     */
+    let (cert_file, key_file) = generate_keys()?;
+
+    /*
+     * We must specify a configuration with a bind address.  We'll use 127.0.0.1
+     * since it's available and won't expose this server outside the host.  We
+     * request port 0, which allows the operating system to pick any available
+     * port.
+     *
+     * In addition, we'll make this an HTTPS server.
+     */
+    let config_dropshot = ConfigDropshot {
+        tls: Some(ConfigTls {
+            cert_file: cert_file.path().to_path_buf(),
+            key_file: key_file.path().to_path_buf(),
+        }),
+        ..Default::default()
+    };
+
+    /*
+     * For simplicity, we'll configure an "info"-level logger that writes to
+     * stderr assuming that it's a terminal.
+     */
+    let config_logging = ConfigLogging::StderrTerminal {
+        level: ConfigLoggingLevel::Info,
+    };
+    let log = config_logging
+        .to_logger("example-basic")
+        .map_err(|error| format!("failed to create logger: {}", error))?;
+
+    /*
+     * Build a description of the API.
+     */
+    let mut api = ApiDescription::new();
+    api.register(example_api_get_counter).unwrap();
+    api.register(example_api_put_counter).unwrap();
+
+    /*
+     * The functions that implement our API endpoints will share this context.
+     */
+    let api_context = ExampleContext::new();
+
+    /*
+     * Set up the server.
+     */
+    let server =
+        HttpServerStarter::new(&config_dropshot, api, api_context, &log)
+            .map_err(|error| format!("failed to create server: {}", error))?
+            .start();
+
+    /*
+     * Wait for the server to stop.  Note that there's not any code to shut down
+     * this server, so we should never get past this point.
+     */
+    server.await
+}
+
+/**
+ * Application-specific example context (state shared by handler functions)
+ */
+struct ExampleContext {
+    /** counter that can be manipulated by requests to the HTTP API */
+    counter: AtomicU64,
+}
+
+impl ExampleContext {
+    /**
+     * Return a new ExampleContext.
+     */
+    pub fn new() -> ExampleContext {
+        ExampleContext {
+            counter: AtomicU64::new(0),
+        }
+    }
+}
+
+/*
+ * HTTP API interface
+ */
+
+/**
+ * `CounterValue` represents the value of the API's counter, either as the
+ * response to a GET request to fetch the counter or as the body of a PUT
+ * request to update the counter.
+ */
+#[derive(Deserialize, Serialize, JsonSchema)]
+struct CounterValue {
+    counter: u64,
+}
+
+/**
+ * Fetch the current value of the counter.
+ */
+#[endpoint {
+    method = GET,
+    path = "/counter",
+}]
+async fn example_api_get_counter(
+    rqctx: Arc<RequestContext<ExampleContext>>,
+) -> Result<HttpResponseOk<CounterValue>, HttpError> {
+    let api_context = rqctx.context();
+
+    Ok(HttpResponseOk(CounterValue {
+        counter: api_context.counter.load(Ordering::SeqCst),
+    }))
+}
+
+/**
+ * Update the current value of the counter.  Note that the special value of 10
+ * is not allowed (just to demonstrate how to generate an error).
+ */
+#[endpoint {
+    method = PUT,
+    path = "/counter",
+}]
+async fn example_api_put_counter(
+    rqctx: Arc<RequestContext<ExampleContext>>,
+    update: TypedBody<CounterValue>,
+) -> Result<HttpResponseUpdatedNoContent, HttpError> {
+    let api_context = rqctx.context();
+    let updated_value = update.into_inner();
+
+    if updated_value.counter == 10 {
+        Err(HttpError::for_bad_request(
+            Some(String::from("BadInput")),
+            format!("do not like the number {}", updated_value.counter),
+        ))
+    } else {
+        api_context.counter.store(updated_value.counter, Ordering::SeqCst);
+        Ok(HttpResponseUpdatedNoContent())
+    }
+}

dropshot/examples/https.rs

@@ -138,7 +138,7 @@ async fn main() -> Result<(), String> {
     let ctx = tree;
     let config_dropshot = ConfigDropshot {
         bind_address: SocketAddr::from((Ipv4Addr::LOCALHOST, port)),
-        request_body_max_bytes: 1024,
+        ..Default::default()
     };
     let config_logging = ConfigLogging::StderrTerminal {
         level: ConfigLoggingLevel::Debug,

dropshot/examples/pagination-basic.rs

@@ -295,7 +295,7 @@ async fn main() -> Result<(), String> {
     let ctx = DataCollection::new();
     let config_dropshot = ConfigDropshot {
         bind_address: SocketAddr::from((Ipv4Addr::LOCALHOST, port)),
-        request_body_max_bytes: 1024,
+        ..Default::default()
     };
     let config_logging = ConfigLogging::StderrTerminal {
         level: ConfigLoggingLevel::Debug,

dropshot/examples/pagination-multiple-resources.rs

@@ -311,7 +311,7 @@ async fn main() -> Result<(), String> {
     let ctx = ProjectCollection::new();
     let config_dropshot = ConfigDropshot {
         bind_address: SocketAddr::from((Ipv4Addr::LOCALHOST, port)),
-        request_body_max_bytes: 1024,
+        ..Default::default()
     };
     let config_logging = ConfigLogging::StderrTerminal {
         level: ConfigLoggingLevel::Debug,

dropshot/examples/pagination-multiple-sorts.rs

@@ -6,6 +6,7 @@
 use serde::Deserialize;
 use serde::Serialize;
 use std::net::SocketAddr;
+use std::path::PathBuf;
 
 /**
  * Configuration for a Dropshot server.
@@ -31,6 +32,11 @@ use std::net::SocketAddr;
  *             [http_api_server]
  *             bind_address = "127.0.0.1:12345"
  *             request_body_max_bytes = 1024
+ *             ## Optional, to enable TLS
+ *             [http_api_server.tls]
+ *             cert_file = "/path/to/certs.pem"
+ *             key_file = "/path/to/key.pem"
+ *
  *
  *             ## ... (other app-specific config)
  *         "##
@@ -49,13 +55,31 @@ pub struct ConfigDropshot {
     pub bind_address: SocketAddr,
     /** maximum allowed size of a request body, defaults to 1024 */
     pub request_body_max_bytes: usize,
+
+    /** If present, enables TLS with the given configuration */
+    pub tls: Option<ConfigTls>,
+}
+
+#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
+pub struct ConfigTls {
+    /** Path to a PEM file containing a certificate chain for the
+     *  server to identify itself with. The first certificate is the
+     *  end-entity certificate, and the remaining are intermediate
+     *  certificates on the way to a trusted CA.
+     */
+    pub cert_file: PathBuf,
+    /** Path to a PEM-encoded PKCS #8 file containing the private key the
+     *  server will use.
+     */
+    pub key_file: PathBuf,
 }
 
 impl Default for ConfigDropshot {
     fn default() -> Self {
         ConfigDropshot {
             bind_address: "127.0.0.1:0".parse().unwrap(),
             request_body_max_bytes: 1024,
+            tls: None,
         }
     }
 }

dropshot/src/config.rs

@@ -70,6 +70,7 @@
  *             &ConfigDropshot {
  *                 bind_address: "127.0.0.1:0".parse().unwrap(),
  *                 request_body_max_bytes: 1024,
+ *                 tls: None,
  *             },
  *             api,
  *             Arc::new(()),
@@ -615,6 +616,7 @@ pub use api_description::ApiEndpointParameterLocation;
 pub use api_description::ApiEndpointResponse;
 pub use api_description::OpenApiDefinition;
 pub use config::ConfigDropshot;
+pub use config::ConfigTls;
 pub use error::HttpError;
 pub use error::HttpErrorResponseBody;
 pub use handler::Extractor;