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 #[cfg_attr(feature="api-types", proxmox_schema::api())]
283 #[derive(Clone, Copy, Eq, PartialEq, Deserialize, Serialize)]
284 #[serde(rename_all = "camelCase")]
285 pub enum AccountStatus
{
286 /// This is not part of the ACME API, but a temporary marker for us until the ACME provider
287 /// tells us the account's real status.
288 #[serde(rename = "<invalid>")]
291 /// Means the account is valid and can be used.
294 /// The account has been deactivated by its user and cannot be used anymore.
297 /// The account has been revoked by the server and cannot be used anymore.
308 fn is_new(&self) -> bool
{
309 *self == AccountStatus
::New
313 #[cfg_attr(feature="api-types", proxmox_schema::api(
315 extra
: { type: Object, properties: {}
, additional_properties
: true },
316 contact
: { type: Array, items: { type: String, description: "Contact Info." }
}
319 /// ACME Account data. This is the part of the account returned from and possibly sent to the ACME
320 /// provider. Some fields may be uptdated by the user via a request to the account location, others
321 /// may not be changed.
322 #[derive(Clone, PartialEq, Deserialize, Serialize)]
323 #[serde(rename_all = "camelCase")]
324 pub struct AccountData
{
325 /// The current account status.
327 skip_serializing_if
= "AccountStatus::is_new",
328 default = "AccountStatus::new"
330 pub status
: AccountStatus
,
332 /// URLs to currently pending orders.
333 #[serde(skip_serializing_if = "Option::is_none")]
334 pub orders
: Option
<String
>,
336 /// The acccount's contact info.
338 /// This usually contains a `"mailto:<email address>"` entry but may also contain some other
339 /// data if the server accepts it.
340 #[serde(skip_serializing_if = "Vec::is_empty", default)]
341 pub contact
: Vec
<String
>,
343 /// Indicated whether the user agreed to the ACME provider's terms of service.
344 #[serde(skip_serializing_if = "Option::is_none")]
345 pub terms_of_service_agreed
: Option
<bool
>,
347 /// External account information.
348 #[serde(skip_serializing_if = "Option::is_none")]
349 pub external_account_binding
: Option
<ExternalAccountBinding
>,
351 /// This is only used by the client when querying an account.
352 #[serde(default = "default_true", skip_serializing_if = "is_false")]
353 pub only_return_existing
: bool
,
355 /// Stores unknown fields if there are any.
356 #[serde(flatten, default, skip_serializing_if = "HashMap::is_empty")]
357 pub extra
: HashMap
<String
, Value
>,
361 fn default_true() -> bool
{
366 fn is_false(b
: &bool
) -> bool
{
370 /// Helper to create an account.
372 /// This is used to generate a private key and set the contact info for the account. Afterwards the
373 /// creation request can be created via the [`request`](AccountCreator::request()) method, giving
374 /// it a nonce and a directory. This can be repeated, if necessary, like when the nonce fails.
376 /// When the server sends a succesful response, it should be passed to the
377 /// [`response`](AccountCreator::response()) method to finish the creation of an [`Account`] which
378 /// can then be persisted.
380 #[must_use = "when creating an account you must pass the response to AccountCreator::response()!"]
381 pub struct AccountCreator
{
382 contact
: Vec
<String
>,
383 terms_of_service_agreed
: bool
,
384 key
: Option
<PKey
<Private
>>,
385 eab_credentials
: Option
<(String
, PKey
<Private
>)>,
388 impl AccountCreator
{
389 /// Replace the contact infor with the provided ACME compatible data.
390 pub fn set_contacts(mut self, contact
: Vec
<String
>) -> Self {
391 self.contact
= contact
;
395 /// Append a contact string.
396 pub fn contact(mut self, contact
: String
) -> Self {
397 self.contact
.push(contact
);
401 /// Append an email address to the contact list.
402 pub fn email(self, email
: String
) -> Self {
403 self.contact(format
!("mailto:{}", email
))
406 /// Change whether the account agrees to the terms of service. Use the directory's or client's
407 /// `terms_of_service_url()` method to present the user with the Terms of Service.
408 pub fn agree_to_tos(mut self, agree
: bool
) -> Self {
409 self.terms_of_service_agreed
= agree
;
413 /// Set the EAB credentials for the account registration
414 pub fn set_eab_credentials(mut self, kid
: String
, hmac_key
: String
) -> Result
<Self, Error
> {
415 let hmac_key
= PKey
::hmac(&base64
::decode(hmac_key
)?
)?
;
416 self.eab_credentials
= Some((kid
, hmac_key
));
420 /// Generate a new RSA key of the specified key size.
421 pub fn generate_rsa_key(self, bits
: u32) -> Result
<Self, Error
> {
422 let key
= openssl
::rsa
::Rsa
::generate(bits
)?
;
423 Ok(self.with_key(PKey
::from_rsa(key
)?
))
426 /// Generate a new P-256 EC key.
427 pub fn generate_ec_key(self) -> Result
<Self, Error
> {
428 let key
= openssl
::ec
::EcKey
::generate(
429 openssl
::ec
::EcGroup
::from_curve_name(openssl
::nid
::Nid
::X9_62_PRIME256V1
)?
.as_ref(),
431 Ok(self.with_key(PKey
::from_ec_key(key
)?
))
434 /// Use an existing key. Note that only RSA and EC keys using the `P-256` curve are currently
435 /// supported, however, this will not be checked at this point.
436 pub fn with_key(mut self, key
: PKey
<Private
>) -> Self {
437 self.key
= Some(key
);
441 /// Prepare a HTTP request to create this account.
443 /// Changes to the user data made after this will have no effect on the account generated with
444 /// the resulting request.
445 /// Changing the private key between using the request and passing the response to
446 /// [`response`](AccountCreator::response()) will render the account unusable!
447 pub fn request(&self, directory
: &Directory
, nonce
: &str) -> Result
<Request
, Error
> {
448 let key
= self.key
.as_deref().ok_or(Error
::MissingKey
)?
;
449 let url
= directory
.new_account_url();
451 let external_account_binding
= self
455 ExternalAccountBinding
::new(&cred
.0, &cred
.1, Jwk
::try_from(key
)?
, url
.to_string())
459 let data
= AccountData
{
461 status
: AccountStatus
::New
,
462 contact
: self.contact
.clone(),
463 terms_of_service_agreed
: if self.terms_of_service_agreed
{
468 external_account_binding
,
469 only_return_existing
: false,
470 extra
: HashMap
::new(),
473 let body
= serde_json
::to_string(&Jws
::new(
484 content_type
: crate::request
::JSON_CONTENT_TYPE
,
486 expected
: crate::request
::CREATED
,
490 /// After issuing the request from [`request()`](AccountCreator::request()), the response's
491 /// `Location` header and body must be passed to this for verification and to create an account
492 /// which is to be persisted!
493 pub fn response(self, location_header
: String
, response_body
: &[u8]) -> Result
<Account
, Error
> {
494 let private_key
= self
496 .ok_or(Error
::MissingKey
)?
497 .private_key_to_pem_pkcs8()?
;
498 let private_key
= String
::from_utf8(private_key
).map_err(|_
| {
499 Error
::Custom("PEM key contained illegal non-utf-8 characters".to_string())
503 location
: location_header
,
504 data
: serde_json
::from_slice(response_body
)
505 .map_err(|err
| Error
::BadAccountData(err
.to_string()))?
,