async_acme/acme/
mod.rs

1/*! Automatic Certificate Management Environment (ACME) acording to [rfc8555](https://datatracker.ietf.org/doc/html/rfc8555)
2
3*/
4use generic_async_http_client::{Error as HTTPError, Request, Response};
5use serde::{Deserialize, Serialize};
6use std::convert::TryInto;
7use thiserror::Error;
8
9mod account;
10pub use account::Account;
11
12use crate::cache::CacheError;
13
14/// URI of <https://letsencrypt.org/> staging Directory. Use this for tests. See <https://letsencrypt.org/docs/staging-environment/>
15pub const LETS_ENCRYPT_STAGING_DIRECTORY: &str =
16    "https://acme-staging-v02.api.letsencrypt.org/directory";
17/// URI of <https://letsencrypt.org/> prod Directory. Certificates aquired from this are trusted by most Browsers.
18pub const LETS_ENCRYPT_PRODUCTION_DIRECTORY: &str =
19    "https://acme-v02.api.letsencrypt.org/directory";
20/// ALPN string used by ACME-TLS challanges
21pub const ACME_TLS_ALPN_NAME: &[u8] = b"acme-tls/1";
22
23/// An ACME directory. Containing the REST endpoints of an ACME provider
24#[derive(Debug, Clone, Deserialize)]
25#[serde(rename_all = "camelCase")]
26pub struct Directory {
27    pub new_nonce: String,
28    pub new_account: String,
29    pub new_order: String,
30}
31
32impl Directory {
33    ///query the endpoints from a discovery url
34    pub async fn discover(url: &str) -> Result<Self, AcmeError> {
35        Ok(Request::get(url).exec().await?.json().await?)
36    }
37    pub async fn nonce(&self) -> Result<String, AcmeError> {
38        let response = Request::get(self.new_nonce.as_str()).exec().await?;
39        get_header(&response, "replay-nonce")
40    }
41}
42
43/// Challange used to prove ownership over a domain
44#[derive(Debug, Deserialize, Eq, PartialEq)]
45pub enum ChallengeType {
46    #[serde(rename = "http-01")]
47    Http01,
48    #[serde(rename = "dns-01")]
49    Dns01,
50    #[serde(rename = "tls-alpn-01")]
51    TlsAlpn01,
52}
53
54/// State of an ACME request
55#[derive(Debug, Deserialize)]
56#[serde(tag = "status", rename_all = "camelCase")]
57pub enum Order {
58    /// [`Auth`] for authorizations must be completed
59    Pending {
60        /// URLs for ([`Account::check_auth`](./struct.Account.html#method.check_auth))
61        authorizations: Vec<String>,
62        /// URL to send CSR to
63        finalize: String,
64    },
65    /// [`Auth`] is done. CSR can be sent ([`Account::send_csr`](./struct.Account.html#method.send_csr))
66    Ready {
67        /// URL to send CSR to
68        finalize: String,
69    },
70    /// CSR is done. Certificate can be downloaded ([`Account::obtain_certificate`](./struct.Account.html#method.obtain_certificate))
71    Valid {
72        /// URL to fetch the final Certificate
73        certificate: String,
74    },
75    Invalid,
76}
77
78///Authentication status for a particular challange
79///
80/// Can be obtained by [`Account::check_auth`](./struct.Account.html#method.check_auth)
81/// and is driven by triggering and completing challanges
82#[derive(Debug, Deserialize)]
83#[serde(tag = "status", rename_all = "camelCase")]
84pub enum Auth {
85    /// challange must be triggered
86    Pending {
87        /// host to authenticate
88        identifier: Identifier,
89        /// challenges to complete in order to authenticate
90        challenges: Vec<Challenge>,
91    },
92    /// ownership is proven
93    Valid,
94    Invalid,
95    Revoked,
96    Expired,
97}
98
99#[derive(Clone, Debug, Serialize, Deserialize)]
100#[serde(tag = "type", content = "value", rename_all = "camelCase")]
101pub enum Identifier {
102    Dns(String),
103}
104
105#[derive(Debug, Deserialize)]
106pub struct Challenge {
107    #[serde(rename = "type")]
108    pub typ: ChallengeType,
109    pub url: String,
110    pub token: String,
111}
112
113#[derive(Error, Debug)]
114pub enum AcmeError {
115    #[error("io error: {0}")]
116    Io(#[from] std::io::Error),
117    #[error("JSON error: {0}")]
118    Json(#[from] serde_json::Error),
119    #[error("http request error: {0}")]
120    HttpRequest(#[from] HTTPError),
121    #[error("acme service response is missing {0} header")]
122    MissingHeader(&'static str),
123    #[error("no tls-alpn-01 challenge found")]
124    NoTlsAlpn01Challenge,
125    #[error("HTTP Status {0} indicates error")]
126    HttpStatus(u16),
127    #[cfg(any(feature = "rustls_ring", feature = "rustls_aws_lc_rs"))]
128    #[error("Could not create Certificate: {0}")]
129    RcgenError(#[from] rcgen::Error),
130    #[error("error from cache: {0}")]
131    Cache(Box<dyn CacheError>),
132}
133
134impl AcmeError {
135    pub fn cache<E: CacheError>(err: E) -> Self {
136        Self::Cache(Box::new(err))
137    }
138}
139
140/// parse a HTTP header as String or fail
141fn get_header(response: &Response, header: &'static str) -> Result<String, AcmeError> {
142    response
143        .header(header)
144        .and_then(|hv| hv.try_into().ok())
145        .ok_or(AcmeError::MissingHeader(header))
146}
147
148#[cfg(test)]
149#[cfg(any(feature = "use_async_std", feature = "use_tokio"))]
150mod test {
151    use super::*;
152    use crate::test::*;
153    #[test]
154    fn discover() {
155        async fn server(listener: TcpListener) -> std::io::Result<bool> {
156            let (mut stream, _) = listener.accept().await?;
157            assert_stream(&mut stream, b"GET /directory HTTP").await?;
158
159            let body = format!(
160                r##"{{
161                "keyChange": "host/key-change",
162                "meta": {{
163                  "caaIdentities": [
164                    "letsencrypt.org"
165                  ],
166                  "termsOfService": "https://letsencrypt.org/documents/LE-SA-v1.3-September-21-2022.pdf",
167                  "website": "https://letsencrypt.org/docs/staging-environment/"
168                }},
169                "newAccount": "host/new-acct",
170                "newNonce": "host/new-nonce",
171                "newOrder": "host/new-order",
172                "q3Eo-_fidjY": "https://community.letsencrypt.org/t/adding-random-entries-to-the-directory/33417",
173                "renewalInfo": "https://acme-staging-v02.api.letsencrypt.org/draft-ietf-acme-ari-02/renewalInfo/",
174                "revokeCert": "host/revoke-cert"
175              }}"##
176            );
177
178            stream
179                .write_all(format!("HTTP/1.1 200 OK\r\nContent-Length: {}\r\nContent-Type:  application/json\r\n\r\n{}", body.len(),body).as_bytes())
180                .await?;
181
182            Ok(true)
183        }
184        block_on(async {
185            let (listener, port, host) = listen_somewhere().await?;
186            let t = spawn(server(listener));
187
188            let d = Directory::discover(&format!("http://{}:{}/directory", host, port)).await?;
189            assert_eq!(d.new_account, "host/new-acct");
190            assert_eq!(d.new_nonce, "host/new-nonce");
191            assert_eq!(d.new_order, "host/new-order");
192
193            assert!(t.await?, "not cool");
194            Ok(())
195        });
196    }
197    pub async fn return_nounce(listener: &TcpListener) -> std::io::Result<bool> {
198        let (mut stream, _) = listener.accept().await?;
199        assert_stream(&mut stream, b"GET /acme/new-nonce HTTP").await?;
200        stream
201            .write_all(b"HTTP/1.1 204 No Content\r\nContent-Length: 0\r\nreplay-nonce: abc\r\n\r\n")
202            .await?;
203        close(stream).await?;
204        Ok(true)
205    }
206    pub fn new_dir(host: &str, port: u16) -> Directory {
207        let new_nonce = format!("http://{}:{}/acme/new-nonce", host, port);
208        let new_account = format!("http://{}:{}/acme/new-acct", host, port);
209        let new_order = format!("http://{}:{}/acme/new-order", host, port);
210        Directory {
211            new_nonce,
212            new_account,
213            new_order,
214        }
215    }
216    #[test]
217    fn nonce() {
218        async fn server(listener: TcpListener) -> std::io::Result<bool> {
219            return_nounce(&listener).await
220        }
221        block_on(async {
222            let (listener, port, host) = listen_somewhere().await?;
223            let t = spawn(server(listener));
224
225            let d = new_dir(&host, port);
226            assert_eq!(d.nonce().await?, "abc");
227
228            assert!(t.await?, "not cool");
229            Ok(())
230        });
231    }
232    #[test]
233    fn lets_encrypt_staging() {
234        block_on(async {
235            let d = Directory::discover(LETS_ENCRYPT_STAGING_DIRECTORY).await?;
236            assert!(!d.new_account.is_empty());
237            assert!(!d.new_order.is_empty());
238            assert!(!d.nonce().await.unwrap().is_empty());
239            Ok(())
240        });
241    }
242}
async_acme/acme/mod.rs

async_acme/acme/
mod.rs
