ACME: module configuration.

Author: bavshin-f5

Cargo.lock

@@ -10,6 +10,12 @@ rust-version = "1.81.0"
 crate-type = ["cdylib"]
 
 [dependencies]
+http = "1.3.1"
+openssl = { version = "0.10.73", features = ["bindgen"] }
+openssl-foreign-types = { package = "foreign-types", version = "0.3" }
+openssl-sys = { version = "0.9.109", features = ["bindgen"] }
+siphasher = { version = "1.0.1", default-features = false }
+thiserror = { version = "2.0.12", default-features = false }
 
 [dependencies.nginx-sys]
 git = "https://github.com/nginx/ngx-rust"

Cargo.toml

@@ -10,9 +10,9 @@ certificate management ([ACME]) protocol.
 
 ### Requirements
 
-* Regular nginx build dependencies
-* System-wide installation of OpenSSL 1.1.1 or later 
-* Rust toolchain (1.81.0 or later)
+- Regular nginx build dependencies
+- System-wide installation of OpenSSL 1.1.1 or later
+- Rust toolchain (1.81.0 or later)
 
 ### Commands
 
@@ -25,24 +25,181 @@ cd nginx-acme
 export NGINX_BUILD_DIR=$(realpath ../nginx/objs)
 cargo build --release
 ```
+
 The result will be located at `target/release/libnginx_acme.so`.
 
 Another way is to use the provided config script:
+
 ```sh
 # in the nginx source directory
 auto/configure \
     --with-compat \
     --with-http_ssl_module \
     --add-[dynamic-]module=/path/to/nginx-acme
 ```
+
 The result will be located at `$NGX_OBJS/ngx_http_acme_module.so`.
 
 Currently this method produces a slightly larger library, as we don't instruct
-the linker to perform dead code elimination.
+the linker to perform LTO and dead code elimination.
 
 ## How to Use
 
-To be added later.
+Add the module to the nginx configuration,
+
+```nginx
+load_module modules/ngx_http_acme_module.so;
+```
+
+and configure with the directives described below
+
+## Configuration directives
+
+### `acme_issuer`
+
+Syntax: `acme_issuer _name_ { ... }`\
+Context: `http`
+
+Defines a new certificate issuer object.
+
+#### `uri`
+
+Syntax: `uri http_uri;`\
+Context: `acme_issuer`
+
+The [directory URL] of the ACME server. This is the only mandatory parameter
+in the `acme_issuer` block.
+
+[directory URL]: https://www.rfc-editor.org/rfc/rfc8555#section-7.1.1
+
+#### `account_key`
+
+Syntax: `account_key alg[:size]|file;`\
+Context: `acme_issuer`
+
+The account's private key used for request authentication.
+Accepted values:
+
+- `ecdsa:256/384/521` for `ES256`/`ES384`/`ES512` JSON Web Signature algorithms
+- `rsa:2048..4096` for `RS256`
+- File path for an existing key, using one of the algorithms above.
+
+The generated account keys are preserved across reloads, but will be lost on
+restart unless `state_path` is configured.
+
+#### `contact`
+
+Syntax: `contact _url_;`\
+Context: `acme_issuer`
+
+An array of URLs that the ACME server can use to contact the client for issues
+related to this account.
+
+Can be specified multiple times.
+
+#### `resolver`
+
+Syntax: `resolver address ... [valid=time] [ipv4=on|off] [ipv6=on|off] [status_zone=zone];`\
+Default: `---`\
+Context: `acme_issuer`
+
+Configures name servers used to resolve names of upstream servers into
+addresses.
+
+Required, but can be inherited from the `http` block.
+
+#### `resolver_timeout`
+
+Syntax: `resolver_timeout time;`\
+Default: `30s`\
+Context: `acme_issuer`
+
+Sets a timeout for name resolution.
+
+#### `ssl_trusted_certificate`
+
+Syntax: `ssl_trusted_certificate file;`\
+Default: `system CA bundle`\
+Context: `acme_issuer`
+
+Specifies a file with trusted CA certificates in the PEM format used to verify
+the certificate of the ACME server.
+
+#### `ssl_verify`
+
+Syntax: `ssl_verify on|off;`\
+Default: `on`\
+Context: `acme_issuer`
+
+Enables or disables verification of the ACME server certificate.
+
+#### `state_path`
+
+Syntax: `state_path _path_;`\
+Default: `---`\
+Context: `acme_issuer`
+
+Defines a directory for storing the module data that can be persisted across
+restarts. This could greatly improve the time until the server is ready and
+help with rate-limiting ACME servers.
+
+The directory, if configured, will contain sensitive content:
+the account key, the issued certificates and private keys.
+
+### `acme_shared_zone`
+
+Syntax: `acme_shared_zone size;`\
+Context: `http`\
+Default: `262k`
+
+An optional directive that allows increasing the size of in-memory storage of
+the module.
+The shared memory zone will be used to store the issued certificates, keys and
+challenge data for all the configured certificate issuers.
+
+### `acme_certificate`
+
+Syntax: `acme_certificate issuer=_issuer_name_ [key=alg[:size]|file] [identifiers...];`\
+Context: `server`
+
+Defines a certificate with the list of _identifiers_ requested from issuer
+_issuer_name_.
+
+The `key` parameter sets the type of generated private key or a path to an
+existing file. Supported key algorithms and sizes:
+`ecdsa:256` (default), `ecdsa:384`, `ecdsa:521`, `rsa:2048`..`rsa:4096`.
+
+Since 1.27.2, the `key` parameter supports the additional schemes implemented
+in the [`ssl_certificate_key`] directive: `data:`, `engine:` and more recently
+`store:`, with a caveat that password-protected keys are not supported.
+
+[`ssl_certificate_key`]: https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_certificate_key
+
+## Example configuration:
+
+```nginx
+resolver 127.0.0.1;
+
+acme_issuer example {
+    uri         https://acme.example.com/directory;
+    contact     mailto:[email protected];
+    state_path  /var/lib/nginx/acme-example;
+}
+
+acme_shared_zone 1M;
+
+server {
+    server_name  .example.test;
+
+    acme_certificate .example.test
+                     issuer=example
+                     key=ecdsa:256;
+
+    ssl_certificate     $acme_certificate;
+    ssl_certificate_key $acme_certificate_key;
+}
+
+```
 
 ## License
 

README.md

@@ -44,4 +44,16 @@ fn detect_nginx_features() {
     if let Ok(os) = env::var("DEP_NGINX_OS") {
         println!("cargo::rustc-cfg=ngx_os=\"{os}\"");
     }
+
+    // Generate cfg values for version checks
+
+    println!("cargo::rustc-check-cfg=cfg(ngx_ssl_cache)");
+    println!("cargo::rerun-if-env-changed=DEP_NGINX_VERSION_NUMBER");
+    if let Ok(version) = env::var("DEP_NGINX_VERSION_NUMBER") {
+        let version: u64 = version.parse().unwrap();
+
+        if version >= 1_027_002 {
+            println!("cargo::rustc-cfg=ngx_ssl_cache");
+        }
+    }
 }