src/account.rs

   1 //! ACME Account management and creation. The [`Account`] type also contains most of the ACME API
   2 //! entry point helpers.
   3
   4 use std::collections::HashMap;
   5 use std::convert::TryFrom;
   6
   7 use openssl::pkey::{PKey, Private};
   8 use serde::{Deserialize, Serialize};
   9 use serde_json::Value;
  10
  11 use crate::authorization::{Authorization, GetAuthorization};
  12 use crate::b64u;
  13 use crate::directory::Directory;
  14 use crate::jws::Jws;
  15 use crate::key::PublicKey;
  16 use crate::order::{NewOrder, Order, OrderData};
  17 use crate::request::Request;
  18 use crate::Error;
  19
  20 /// An ACME Account.
  21 ///
  22 /// This contains the location URL, the account data and the private key for an account.
  23 /// This can directly be serialized via serde to persist the account.
  24 ///
  25 /// In order to register a new account with an ACME provider, see the [`Account::creator`] method.
  26 #[derive(Deserialize, Serialize)]
  27 #[serde(rename_all = "camelCase")]
  28 pub struct Account {
  29     /// Account location URL.
  30     pub location: String,
  31
  32     /// Acme account data.
  33     pub data: AccountData,
  34
  35     /// base64url encoded PEM formatted private key.
  36     pub private_key: String,
  37 }
  38
  39 impl Account {
  40     /// Rebuild an account from its components.
  41     pub fn from_parts(location: String, private_key: String, data: AccountData) -> Self {
  42         Self {
  43             location,
  44             data,
  45             private_key,
  46         }
  47     }
  48
  49     /// Builds an [`AccountCreator`]. This handles creation of the private key and account data as
  50     /// well as handling the response sent by the server for the registration request.
  51     pub fn creator() -> AccountCreator {
  52         AccountCreator::default()
  53     }
  54
  55     /// Place a new order. This will build a [`NewOrder`] representing an in flight order creation
  56     /// request.
  57     ///
  58     /// The returned `NewOrder`'s `request` option is *guaranteed* to be `Some(Request)`.
  59     pub fn new_order(
  60         &self,
  61         order: &OrderData,
  62         directory: &Directory,
  63         nonce: &str,
  64     ) -> Result<NewOrder, Error> {
  65         let key = PKey::private_key_from_pem(self.private_key.as_bytes())?;
  66
  67         if order.identifiers.is_empty() {
  68             return Err(Error::EmptyOrder);
  69         }
  70
  71         let url = directory.new_order_url();
  72         let body = serde_json::to_string(&Jws::new(
  73             &key,
  74             Some(self.location.clone()),
  75             url.to_owned(),
  76             nonce.to_owned(),
  77             order,
  78         )?)?;
  79
  80         let request = Request {
  81             url: url.to_owned(),
  82             method: "POST",
  83             content_type: crate::request::JSON_CONTENT_TYPE,
  84             body,
  85             expected: crate::request::CREATED,
  86         };
  87
  88         Ok(NewOrder::new(request))
  89     }
  90
  91     /// Prepare a "POST-as-GET" request to fetch data. Low level helper.
  92     pub fn get_request(&self, url: &str, nonce: &str) -> Result<Request, Error> {
  93         let key = PKey::private_key_from_pem(self.private_key.as_bytes())?;
  94         let body = serde_json::to_string(&Jws::new_full(
  95             &key,
  96             Some(self.location.clone()),
  97             url.to_owned(),
  98             nonce.to_owned(),
  99             String::new(),
 100         )?)?;
 101
 102         Ok(Request {
 103             url: url.to_owned(),
 104             method: "POST",
 105             content_type: crate::request::JSON_CONTENT_TYPE,
 106             body,
 107             expected: 200,
 108         })
 109     }
 110
 111     /// Prepare a JSON POST request. Low level helper.
 112     pub fn post_request<T: Serialize>(
 113         &self,
 114         url: &str,
 115         nonce: &str,
 116         data: &T,
 117     ) -> Result<Request, Error> {
 118         let key = PKey::private_key_from_pem(self.private_key.as_bytes())?;
 119         let body = serde_json::to_string(&Jws::new(
 120             &key,
 121             Some(self.location.clone()),
 122             url.to_owned(),
 123             nonce.to_owned(),
 124             data,
 125         )?)?;
 126
 127         Ok(Request {
 128             url: url.to_owned(),
 129             method: "POST",
 130             content_type: crate::request::JSON_CONTENT_TYPE,
 131             body,
 132             expected: 200,
 133         })
 134     }
 135
 136     /// Prepare a JSON POST request.
 137     fn post_request_raw_payload(
 138         &self,
 139         url: &str,
 140         nonce: &str,
 141         payload: String,
 142     ) -> Result<Request, Error> {
 143         let key = PKey::private_key_from_pem(self.private_key.as_bytes())?;
 144         let body = serde_json::to_string(&Jws::new_full(
 145             &key,
 146             Some(self.location.clone()),
 147             url.to_owned(),
 148             nonce.to_owned(),
 149             payload,
 150         )?)?;
 151
 152         Ok(Request {
 153             url: url.to_owned(),
 154             method: "POST",
 155             content_type: crate::request::JSON_CONTENT_TYPE,
 156             body,
 157             expected: 200,
 158         })
 159     }
 160
 161     /// Get the "key authorization" for a token.
 162     pub fn key_authorization(&self, token: &str) -> Result<String, Error> {
 163         let key = PKey::private_key_from_pem(self.private_key.as_bytes())?;
 164         let thumbprint = PublicKey::try_from(&*key)?.thumbprint()?;
 165         Ok(format!("{}.{}", token, thumbprint))
 166     }
 167
 168     /// Get the TXT field value for a dns-01 token. This is the base64url encoded sha256 digest of
 169     /// the key authorization value.
 170     pub fn dns_01_txt_value(&self, token: &str) -> Result<String, Error> {
 171         let key_authorization = self.key_authorization(token)?;
 172         let digest = openssl::sha::sha256(key_authorization.as_bytes());
 173         Ok(b64u::encode(&digest))
 174     }
 175
 176     /// Prepare a request to update account data.
 177     ///
 178     /// This is a rather low level interface. You should know what you're doing.
 179     pub fn update_account_request<T: Serialize>(
 180         &self,
 181         nonce: &str,
 182         data: &T,
 183     ) -> Result<Request, Error> {
 184         self.post_request(&self.location, nonce, data)
 185     }
 186
 187     /// Prepare a request to deactivate this account.
 188     pub fn deactivate_account_request<T: Serialize>(&self, nonce: &str) -> Result<Request, Error> {
 189         self.post_request_raw_payload(
 190             &self.location,
 191             nonce,
 192             r#"{"status":"deactivated"}"#.to_string(),
 193         )
 194     }
 195
 196     /// Prepare a request to query an Authorization for an Order.
 197     ///
 198     /// Returns `Ok(None)` if `auth_index` is out of out of range. You can query the number of
 199     /// authorizations from via [`Order::authorization_len`] or by manually inspecting its
 200     /// `.data.authorization` vector.
 201     pub fn get_authorization(
 202         &self,
 203         order: &Order,
 204         auth_index: usize,
 205         nonce: &str,
 206     ) -> Result<Option<GetAuthorization>, Error> {
 207         match order.authorization(auth_index) {
 208             None => Ok(None),
 209             Some(url) => Ok(Some(GetAuthorization::new(self.get_request(url, nonce)?))),
 210         }
 211     }
 212
 213     /// Prepare a request to validate a Challenge from an Authorization.
 214     ///
 215     /// Returns `Ok(None)` if `challenge_index` is out of out of range. The challenge count is
 216     /// available by inspecting the [`Authorization::challenges`] vector.
 217     ///
 218     /// This returns a raw `Request` since validation takes some time and the `Authorization`
 219     /// object has to be re-queried and its `status` inspected.
 220     pub fn validate_challenge(
 221         &self,
 222         authorization: &Authorization,
 223         challenge_index: usize,
 224         nonce: &str,
 225     ) -> Result<Option<Request>, Error> {
 226         match authorization.challenges.get(challenge_index) {
 227             None => Ok(None),
 228             Some(challenge) => self
 229                 .post_request_raw_payload(&challenge.url, nonce, "{}".to_string())
 230                 .map(Some),
 231         }
 232     }
 233
 234     /// Prepare a request to revoke a certificate.
 235     ///
 236     /// The certificate can be either PEM or DER formatted.
 237     ///
 238     /// Note that this uses the account's key for authorization.
 239     ///
 240     /// Revocation using a certificate's private key is not yet implemented.
 241     pub fn revoke_certificate(
 242         &self,
 243         certificate: &[u8],
 244         reason: Option<u32>,
 245     ) -> Result<CertificateRevocation, Error> {
 246         let cert = if certificate.starts_with(b"-----BEGIN CERTIFICATE-----") {
 247             b64u::encode(&openssl::x509::X509::from_pem(certificate)?.to_der()?)
 248         } else {
 249             b64u::encode(certificate)
 250         };
 251
 252         let data = match reason {
 253             Some(reason) => serde_json::json!({ "certificate": cert, "reason": reason }),
 254             None => serde_json::json!({ "certificate": cert }),
 255         };
 256
 257         Ok(CertificateRevocation {
 258             account: self,
 259             data,
 260         })
 261     }
 262 }
 263
 264 /// Certificate revocation involves converting the certificate to base64url encoded DER and then
 265 /// embedding it in a json structure. Since we also need a nonce and possibly retry the request if
 266 /// a `BadNonce` error happens, this caches the converted data for efficiency.
 267 pub struct CertificateRevocation<'a> {
 268     account: &'a Account,
 269     data: Value,
 270 }
 271
 272 impl CertificateRevocation<'_> {
 273     /// Create the revocation request using the specified nonce for the given directory.
 274     pub fn request(&self, directory: &Directory, nonce: &str) -> Result<Request, Error> {
 275         self.account
 276             .post_request(&directory.data.revoke_cert, nonce, &self.data)
 277     }
 278 }
 279
 280 /// Status of an ACME account.
 281 #[derive(Clone, Copy, Eq, PartialEq, Deserialize, Serialize)]
 282 #[serde(rename_all = "camelCase")]
 283 pub enum AccountStatus {
 284     /// This is not part of the ACME API, but a temporary marker for us until the ACME provider
 285     /// tells us the account's real status.
 286     #[serde(rename = "<invalid>")]
 287     New,
 288
 289     /// Means the account is valid and can be used.
 290     Valid,
 291
 292     /// The account has been deactivated by its user and cannot be used anymore.
 293     Deactivated,
 294
 295     /// The account has been revoked by the server and cannot be used anymore.
 296     Revoked,
 297 }
 298
 299 impl AccountStatus {
 300     #[inline]
 301     fn new() -> Self {
 302         AccountStatus::New
 303     }
 304
 305     #[inline]
 306     fn is_new(&self) -> bool {
 307         *self == AccountStatus::New
 308     }
 309 }
 310
 311 /// ACME Account data. This is the part of the account returned from and possibly sent to the ACME
 312 /// provider. Some fields may be uptdated by the user via a request to the account location, others
 313 /// may not be changed.
 314 #[derive(Clone, Deserialize, Serialize)]
 315 #[serde(rename_all = "camelCase")]
 316 pub struct AccountData {
 317     /// The current account status.
 318     #[serde(
 319         skip_serializing_if = "AccountStatus::is_new",
 320         default = "AccountStatus::new"
 321     )]
 322     pub status: AccountStatus,
 323
 324     /// URLs to currently pending orders.
 325     #[serde(skip_serializing_if = "Option::is_none")]
 326     pub orders: Option<String>,
 327
 328     /// The acccount's contact info.
 329     ///
 330     /// This usually contains a `"mailto:<email address>"` entry but may also contain some other
 331     /// data if the server accepts it.
 332     #[serde(skip_serializing_if = "Vec::is_empty", default)]
 333     pub contact: Vec<String>,
 334
 335     /// Indicated whether the user agreed to the ACME provider's terms of service.
 336     #[serde(skip_serializing_if = "Option::is_none")]
 337     pub terms_of_service_agreed: Option<bool>,
 338
 339     /// External account information. This is currently not directly supported in any way and only
 340     /// stored to completeness.
 341     #[serde(skip_serializing_if = "Option::is_none")]
 342     pub external_account_binding: Option<Value>,
 343
 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,
 347
 348     /// Stores unknown fields if there are any.
 349     #[serde(flatten, default, skip_serializing_if = "HashMap::is_empty")]
 350     pub extra: HashMap<String, Value>,
 351 }
 352
 353 #[inline]
 354 fn default_true() -> bool {
 355     true
 356 }
 357
 358 #[inline]
 359 fn is_false(b: &bool) -> bool {
 360     !*b
 361 }
 362
 363 /// Helper to create an account.
 364 ///
 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.
 368 ///
 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.
 372 #[derive(Default)]
 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 }
 379
 380 impl AccountCreator {
 381     /// Replace the contact infor with the provided ACME compatible data.
 382     pub fn set_contacts(mut self, contact: Vec<String>) -> Self {
 383         self.contact = contact;
 384         self
 385     }
 386
 387     /// Append a contact string.
 388     pub fn contact(mut self, contact: String) -> Self {
 389         self.contact.push(contact);
 390         self
 391     }
 392
 393     /// Append an email address to the contact list.
 394     pub fn email(self, email: String) -> Self {
 395         self.contact(format!("mailto:{}", email))
 396     }
 397
 398     /// Change whether the account agrees to the terms of service. Use the directory's or client's
 399     /// `terms_of_service_url()` method to present the user with the Terms of Service.
 400     pub fn agree_to_tos(mut self, agree: bool) -> Self {
 401         self.terms_of_service_agreed = agree;
 402         self
 403     }
 404
 405     /// Generate a new RSA key of the specified key size.
 406     pub fn generate_rsa_key(self, bits: u32) -> Result<Self, Error> {
 407         let key = openssl::rsa::Rsa::generate(bits)?;
 408         Ok(self.with_key(PKey::from_rsa(key)?))
 409     }
 410
 411     /// Generate a new P-256 EC key.
 412     pub fn generate_ec_key(self) -> Result<Self, Error> {
 413         let key = openssl::ec::EcKey::generate(
 414             openssl::ec::EcGroup::from_curve_name(openssl::nid::Nid::X9_62_PRIME256V1)?.as_ref(),
 415         )?;
 416         Ok(self.with_key(PKey::from_ec_key(key)?))
 417     }
 418
 419     /// Use an existing key. Note that only RSA and EC keys using the `P-256` curve are currently
 420     /// supported, however, this will not be checked at this point.
 421     pub fn with_key(mut self, key: PKey<Private>) -> Self {
 422         self.key = Some(key);
 423         self
 424     }
 425
 426     /// Prepare a HTTP request to create this account.
 427     ///
 428     /// Changes to the user data made after this will have no effect on the account generated with
 429     /// the resulting request.
 430     /// Changing the private key between using the request and passing the response to
 431     /// [`response`](AccountCreator::response()) will render the account unusable!
 432     pub fn request(&self, directory: &Directory, nonce: &str) -> Result<Request, Error> {
 433         let key = self.key.as_deref().ok_or(Error::MissingKey)?;
 434
 435         let data = AccountData {
 436             orders: None,
 437             status: AccountStatus::New,
 438             contact: self.contact.clone(),
 439             terms_of_service_agreed: if self.terms_of_service_agreed {
 440                 Some(true)
 441             } else {
 442                 None
 443             },
 444             external_account_binding: None,
 445             only_return_existing: false,
 446             extra: HashMap::new(),
 447         };
 448
 449         let url = directory.new_account_url();
 450         let body = serde_json::to_string(&Jws::new(
 451             key,
 452             None,
 453             url.to_owned(),
 454             nonce.to_owned(),
 455             &data,
 456         )?)?;
 457
 458         Ok(Request {
 459             url: url.to_owned(),
 460             method: "POST",
 461             content_type: crate::request::JSON_CONTENT_TYPE,
 462             body,
 463             expected: crate::request::CREATED,
 464         })
 465     }
 466
 467     /// After issuing the request from [`request()`](AccountCreator::request()), the response's
 468     /// `Location` header and body must be passed to this for verification and to create an account
 469     /// which is to be persisted!
 470     pub fn response(self, location_header: String, response_body: &[u8]) -> Result<Account, Error> {
 471         let private_key = self
 472             .key
 473             .ok_or(Error::MissingKey)?
 474             .private_key_to_pem_pkcs8()?;
 475         let private_key = String::from_utf8(private_key).map_err(|_| {
 476             Error::Custom("PEM key contained illegal non-utf-8 characters".to_string())
 477         })?;
 478
 479         Ok(Account {
 480             location: location_header,
 481             data: serde_json::from_slice(response_body)
 482                 .map_err(|err| Error::BadAccountData(err.to_string()))?,
 483             private_key,
 484         })
 485     }
 486 }