1 //! ACME Account management and creation. The [`Account`] type also contains most of the ACME API
2 //! entry point helpers.
4 use std
::collections
::HashMap
;
5 use std
::convert
::TryFrom
;
7 use openssl
::pkey
::{PKey, Private}
;
8 use serde
::{Deserialize, Serialize}
;
11 use crate::authorization
::{Authorization, GetAuthorization}
;
13 use crate::directory
::Directory
;
14 use crate::eab
::ExternalAccountBinding
;
16 use crate::key
::{Jwk, PublicKey}
;
17 use crate::order
::{NewOrder, Order, OrderData}
;
18 use crate::request
::Request
;
23 /// This contains the location URL, the account data and the private key for an account.
24 /// This can directly be serialized via serde to persist the account.
26 /// In order to register a new account with an ACME provider, see the [`Account::creator`] method.
27 #[derive(Deserialize, Serialize)]
28 #[serde(rename_all = "camelCase")]
30 /// Account location URL.
33 /// Acme account data.
34 pub data
: AccountData
,
36 /// base64url encoded PEM formatted private key.
37 pub private_key
: String
,
41 /// Rebuild an account from its components.
42 pub fn from_parts(location
: String
, private_key
: String
, data
: AccountData
) -> Self {
50 /// Builds an [`AccountCreator`]. This handles creation of the private key and account data as
51 /// well as handling the response sent by the server for the registration request.
52 pub fn creator() -> AccountCreator
{
53 AccountCreator
::default()
56 /// Place a new order. This will build a [`NewOrder`] representing an in flight order creation
59 /// The returned `NewOrder`'s `request` option is *guaranteed* to be `Some(Request)`.
63 directory
: &Directory
,
65 ) -> Result
<NewOrder
, Error
> {
66 let key
= PKey
::private_key_from_pem(self.private_key
.as_bytes())?
;
68 if order
.identifiers
.is_empty() {
69 return Err(Error
::EmptyOrder
);
72 let url
= directory
.new_order_url();
73 let body
= serde_json
::to_string(&Jws
::new(
75 Some(self.location
.clone()),
81 let request
= Request
{
84 content_type
: crate::request
::JSON_CONTENT_TYPE
,
86 expected
: crate::request
::CREATED
,
89 Ok(NewOrder
::new(request
))
92 /// Prepare a "POST-as-GET" request to fetch data. Low level helper.
93 pub fn get_request(&self, url
: &str, nonce
: &str) -> Result
<Request
, Error
> {
94 let key
= PKey
::private_key_from_pem(self.private_key
.as_bytes())?
;
95 let body
= serde_json
::to_string(&Jws
::new_full(
97 Some(self.location
.clone()),
106 content_type
: crate::request
::JSON_CONTENT_TYPE
,
112 /// Prepare a JSON POST request. Low level helper.
113 pub fn post_request
<T
: Serialize
>(
118 ) -> Result
<Request
, Error
> {
119 let key
= PKey
::private_key_from_pem(self.private_key
.as_bytes())?
;
120 let body
= serde_json
::to_string(&Jws
::new(
122 Some(self.location
.clone()),
131 content_type
: crate::request
::JSON_CONTENT_TYPE
,
137 /// Prepare a JSON POST request.
138 fn post_request_raw_payload(
143 ) -> Result
<Request
, Error
> {
144 let key
= PKey
::private_key_from_pem(self.private_key
.as_bytes())?
;
145 let body
= serde_json
::to_string(&Jws
::new_full(
147 Some(self.location
.clone()),
156 content_type
: crate::request
::JSON_CONTENT_TYPE
,
162 /// Get the "key authorization" for a token.
163 pub fn key_authorization(&self, token
: &str) -> Result
<String
, Error
> {
164 let key
= PKey
::private_key_from_pem(self.private_key
.as_bytes())?
;
165 let thumbprint
= PublicKey
::try_from(&*key
)?
.thumbprint()?
;
166 Ok(format
!("{}.{}", token
, thumbprint
))
169 /// Get the TXT field value for a dns-01 token. This is the base64url encoded sha256 digest of
170 /// the key authorization value.
171 pub fn dns_01_txt_value(&self, token
: &str) -> Result
<String
, Error
> {
172 let key_authorization
= self.key_authorization(token
)?
;
173 let digest
= openssl
::sha
::sha256(key_authorization
.as_bytes());
174 Ok(b64u
::encode(&digest
))
177 /// Prepare a request to update account data.
179 /// This is a rather low level interface. You should know what you're doing.
180 pub fn update_account_request
<T
: Serialize
>(
184 ) -> Result
<Request
, Error
> {
185 self.post_request(&self.location
, nonce
, data
)
188 /// Prepare a request to deactivate this account.
189 pub fn deactivate_account_request
<T
: Serialize
>(&self, nonce
: &str) -> Result
<Request
, Error
> {
190 self.post_request_raw_payload(
193 r
#"{"status":"deactivated"}"#.to_string(),
197 /// Prepare a request to query an Authorization for an Order.
199 /// Returns `Ok(None)` if `auth_index` is out of out of range. You can query the number of
200 /// authorizations from via [`Order::authorization_len`] or by manually inspecting its
201 /// `.data.authorization` vector.
202 pub fn get_authorization(
207 ) -> Result
<Option
<GetAuthorization
>, Error
> {
208 match order
.authorization(auth_index
) {
210 Some(url
) => Ok(Some(GetAuthorization
::new(self.get_request(url
, nonce
)?
))),
214 /// Prepare a request to validate a Challenge from an Authorization.
216 /// Returns `Ok(None)` if `challenge_index` is out of out of range. The challenge count is
217 /// available by inspecting the [`Authorization::challenges`] vector.
219 /// This returns a raw `Request` since validation takes some time and the `Authorization`
220 /// object has to be re-queried and its `status` inspected.
221 pub fn validate_challenge(
223 authorization
: &Authorization
,
224 challenge_index
: usize,
226 ) -> Result
<Option
<Request
>, Error
> {
227 match authorization
.challenges
.get(challenge_index
) {
229 Some(challenge
) => self
230 .post_request_raw_payload(&challenge
.url
, nonce
, "{}".to_string())
235 /// Prepare a request to revoke a certificate.
237 /// The certificate can be either PEM or DER formatted.
239 /// Note that this uses the account's key for authorization.
241 /// Revocation using a certificate's private key is not yet implemented.
242 pub fn revoke_certificate(
246 ) -> Result
<CertificateRevocation
, Error
> {
247 let cert
= if certificate
.starts_with(b
"-----BEGIN CERTIFICATE-----") {
248 b64u
::encode(&openssl
::x509
::X509
::from_pem(certificate
)?
.to_der()?
)
250 b64u
::encode(certificate
)
253 let data
= match reason
{
254 Some(reason
) => serde_json
::json
!({ "certificate": cert, "reason": reason }
),
255 None
=> serde_json
::json
!({ "certificate": cert }
),
258 Ok(CertificateRevocation
{
265 /// Certificate revocation involves converting the certificate to base64url encoded DER and then
266 /// embedding it in a json structure. Since we also need a nonce and possibly retry the request if
267 /// a `BadNonce` error happens, this caches the converted data for efficiency.
268 pub struct CertificateRevocation
<'a
> {
269 account
: &'a Account
,
273 impl CertificateRevocation
<'_
> {
274 /// Create the revocation request using the specified nonce for the given directory.
275 pub fn request(&self, directory
: &Directory
, nonce
: &str) -> Result
<Request
, Error
> {
277 .post_request(&directory
.data
.revoke_cert
, nonce
, &self.data
)
281 /// Status of an ACME account.
282 #[derive(Clone, Copy, Eq, PartialEq, Deserialize, Serialize)]
283 #[serde(rename_all = "camelCase")]
284 pub enum AccountStatus
{
285 /// This is not part of the ACME API, but a temporary marker for us until the ACME provider
286 /// tells us the account's real status.
287 #[serde(rename = "<invalid>")]
290 /// Means the account is valid and can be used.
293 /// The account has been deactivated by its user and cannot be used anymore.
296 /// The account has been revoked by the server and cannot be used anymore.
307 fn is_new(&self) -> bool
{
308 *self == AccountStatus
::New
312 /// ACME Account data. This is the part of the account returned from and possibly sent to the ACME
313 /// provider. Some fields may be uptdated by the user via a request to the account location, others
314 /// may not be changed.
315 #[derive(Clone, Deserialize, Serialize)]
316 #[serde(rename_all = "camelCase")]
317 pub struct AccountData
{
318 /// The current account status.
320 skip_serializing_if
= "AccountStatus::is_new",
321 default = "AccountStatus::new"
323 pub status
: AccountStatus
,
325 /// URLs to currently pending orders.
326 #[serde(skip_serializing_if = "Option::is_none")]
327 pub orders
: Option
<String
>,
329 /// The acccount's contact info.
331 /// This usually contains a `"mailto:<email address>"` entry but may also contain some other
332 /// data if the server accepts it.
333 #[serde(skip_serializing_if = "Vec::is_empty", default)]
334 pub contact
: Vec
<String
>,
336 /// Indicated whether the user agreed to the ACME provider's terms of service.
337 #[serde(skip_serializing_if = "Option::is_none")]
338 pub terms_of_service_agreed
: Option
<bool
>,
340 /// External account information.
341 #[serde(skip_serializing_if = "Option::is_none")]
342 pub external_account_binding
: Option
<ExternalAccountBinding
>,
344 /// This is only used by the client when querying an account.
345 #[serde(default = "default_true", skip_serializing_if = "is_false")]
346 pub only_return_existing
: bool
,
348 /// Stores unknown fields if there are any.
349 #[serde(flatten, default, skip_serializing_if = "HashMap::is_empty")]
350 pub extra
: HashMap
<String
, Value
>,
354 fn default_true() -> bool
{
359 fn is_false(b
: &bool
) -> bool
{
363 /// Helper to create an account.
365 /// This is used to generate a private key and set the contact info for the account. Afterwards the
366 /// creation request can be created via the [`request`](AccountCreator::request()) method, giving
367 /// it a nonce and a directory. This can be repeated, if necessary, like when the nonce fails.
369 /// When the server sends a succesful response, it should be passed to the
370 /// [`response`](AccountCreator::response()) method to finish the creation of an [`Account`] which
371 /// can then be persisted.
373 #[must_use = "when creating an account you must pass the response to AccountCreator::response()!"]
374 pub struct AccountCreator
{
375 contact
: Vec
<String
>,
376 terms_of_service_agreed
: bool
,
377 key
: Option
<PKey
<Private
>>,
378 eab_credentials
: Option
<(String
, PKey
<Private
>)>,
381 impl AccountCreator
{
382 /// Replace the contact infor with the provided ACME compatible data.
383 pub fn set_contacts(mut self, contact
: Vec
<String
>) -> Self {
384 self.contact
= contact
;
388 /// Append a contact string.
389 pub fn contact(mut self, contact
: String
) -> Self {
390 self.contact
.push(contact
);
394 /// Append an email address to the contact list.
395 pub fn email(self, email
: String
) -> Self {
396 self.contact(format
!("mailto:{}", email
))
399 /// Change whether the account agrees to the terms of service. Use the directory's or client's
400 /// `terms_of_service_url()` method to present the user with the Terms of Service.
401 pub fn agree_to_tos(mut self, agree
: bool
) -> Self {
402 self.terms_of_service_agreed
= agree
;
406 /// Set the EAB credentials for the account registration
407 pub fn set_eab_credentials(mut self, kid
: String
, hmac_key
: String
) -> Result
<Self, Error
> {
408 let hmac_key
= PKey
::hmac(&base64
::decode(hmac_key
)?
)?
;
409 self.eab_credentials
= Some((kid
, hmac_key
));
413 /// Generate a new RSA key of the specified key size.
414 pub fn generate_rsa_key(self, bits
: u32) -> Result
<Self, Error
> {
415 let key
= openssl
::rsa
::Rsa
::generate(bits
)?
;
416 Ok(self.with_key(PKey
::from_rsa(key
)?
))
419 /// Generate a new P-256 EC key.
420 pub fn generate_ec_key(self) -> Result
<Self, Error
> {
421 let key
= openssl
::ec
::EcKey
::generate(
422 openssl
::ec
::EcGroup
::from_curve_name(openssl
::nid
::Nid
::X9_62_PRIME256V1
)?
.as_ref(),
424 Ok(self.with_key(PKey
::from_ec_key(key
)?
))
427 /// Use an existing key. Note that only RSA and EC keys using the `P-256` curve are currently
428 /// supported, however, this will not be checked at this point.
429 pub fn with_key(mut self, key
: PKey
<Private
>) -> Self {
430 self.key
= Some(key
);
434 /// Prepare a HTTP request to create this account.
436 /// Changes to the user data made after this will have no effect on the account generated with
437 /// the resulting request.
438 /// Changing the private key between using the request and passing the response to
439 /// [`response`](AccountCreator::response()) will render the account unusable!
440 pub fn request(&self, directory
: &Directory
, nonce
: &str) -> Result
<Request
, Error
> {
441 let key
= self.key
.as_deref().ok_or(Error
::MissingKey
)?
;
442 let url
= directory
.new_account_url();
444 let external_account_binding
= self
448 ExternalAccountBinding
::new(&cred
.0, &cred
.1, Jwk
::try_from(key
)?
, url
.to_string())
452 let data
= AccountData
{
454 status
: AccountStatus
::New
,
455 contact
: self.contact
.clone(),
456 terms_of_service_agreed
: if self.terms_of_service_agreed
{
461 external_account_binding
,
462 only_return_existing
: false,
463 extra
: HashMap
::new(),
466 let body
= serde_json
::to_string(&Jws
::new(
477 content_type
: crate::request
::JSON_CONTENT_TYPE
,
479 expected
: crate::request
::CREATED
,
483 /// After issuing the request from [`request()`](AccountCreator::request()), the response's
484 /// `Location` header and body must be passed to this for verification and to create an account
485 /// which is to be persisted!
486 pub fn response(self, location_header
: String
, response_body
: &[u8]) -> Result
<Account
, Error
> {
487 let private_key
= self
489 .ok_or(Error
::MissingKey
)?
490 .private_key_to_pem_pkcs8()?
;
491 let private_key
= String
::from_utf8(private_key
).map_err(|_
| {
492 Error
::Custom("PEM key contained illegal non-utf-8 characters".to_string())
496 location
: location_header
,
497 data
: serde_json
::from_slice(response_body
)
498 .map_err(|err
| Error
::BadAccountData(err
.to_string()))?
,