diff --git a/README.md b/README.md index a3f8910..9d06e45 100644 --- a/README.md +++ b/README.md @@ -1,210 +1,244 @@ # ACME Email S/MIME Client -ACME Email Client for **EmailReply-00 Challenge** to obtain S/MIME certificate. +ACME Email Client for **EmailReply-00 Challenge** to obtain S/MIME certificates. -ACME Email S/MIME client aims at performing the ACME Email Challenge for S/MIME certification. It is based on RFC 8823 *[Extensions to Automatic Certificate Management Environment for End-User S/MIME Certificates](https://datatracker.ietf.org/doc/html/rfc8823 "Extensions to Automatic Certificate Management Environment for End-User S/MIME Certificates")*, which is an extension to the ACME protocol [[RFC 8555](https://tools.ietf.org/html/rfc8555 "RFC 8555")]. +The ACME Email S/MIME client is designed to facilitate the ACME Email Challenge for S/MIME certification. It operates in accordance with RFC 8823 *[Extensions to Automatic Certificate Management Environment for End-User S/MIME Certificates](https://datatracker.ietf.org/doc/html/rfc8823 "Extensions to Automatic Certificate Management Environment for End-User S/MIME Certificates")*, an extension to the ACME protocol [[RFC 8555](https://tools.ietf.org/html/rfc8555 "RFC 8555")]. -With [CASTLE Platform® ACME Server](https://acme.castle.cloud/ "CASTLE Platform® ACME Server"), ACME Email S/MIME Client can obtain S/MIME certificates by using Certbot. With S/MIME certificates, e-mails, pdf, docx, etc. can be signed to proof the integrity of the source and authorship. Despite other platforms that require to pay for obtaining these certificates, [CASTLE Platform® ACME Server](https://acme.castle.cloud/ "CASTLE Platform® ACME Server") offers it **by free**. +Utilizing the [CASTLE Platform® ACME Server](https://acme.castle.cloud/ "CASTLE Platform® ACME Server"), the ACME Email S/MIME Client can acquire S/MIME certificates through Certbot. These certificates enable the signing of emails, PDFs, DOCX files, etc., ensuring the integrity of the source and authorship. Unlike other platforms that require payment for these certificates, [CASTLE Platform® ACME Server](https://acme.castle.cloud/ "CASTLE Platform® ACME Server") offers them **for free**. -## Why -Let's Encrypt ACME system is robust and represents a major step for securing the web. However, there is no possibility to extend it to e-mail and document signing. I do not know which is their roadmap, but I think that S/MIME certificates are the next natural step. +## Motivation +The Let's Encrypt ACME system represents a significant advancement in web security. However, it lacks provisions for extending security measures to email and document signing. While the roadmap of Let's Encrypt remains unclear in this regard, S/MIME certificates seem to be a logical progression. -RFC 8823 describes the procedure to validate the authenticity of an e-mail. It does not validates the identify of the subject behind the e-mail address, only the recipient. As with the ACME HTTPS specification, which does not validate the identify of the company behind a domain, ACME e-mail S/MIME specification describes the validity of a particular e-mail address. +RFC 8823 outlines the procedure for validating the authenticity of an email, albeit without verifying the identity of the subject behind the email address, only the recipient. Similar to the ACME HTTPS specification, which does not validate the identity of the company behind a domain, the ACME Email S/MIME specification validates the authenticity of a specific email address. -We implemented the ACME server at [CASTLE Platform®](https://www.castle.cloud/ "CASTLE Platform®") and it fits and follows the specifications for obtaining S/MIME certificates. Obviously, [CASTLE Platform® Certification Authority](https://ca.castle.cloud/ "CASTLE Platform® CA") is not the same as Let's Encrypt, it uses its own. Fortunately, [CASTLE Platform® CA](https://ca.castle.cloud/ "CASTLE Platform® CA") follows the same standards as other common CA, with the same compatibilities and extensions. If [CASTLE Platform® CA](https://ca.castle.cloud/ "CASTLE Platform® CA") is trusted, the obtained S/MIME certificate is likely similar to the ones obtained through paying CA. +We have implemented the ACME server at [CASTLE Platform®](https://www.castle.cloud/ "CASTLE Platform®"), adhering to and aligning with the specifications for obtaining S/MIME certificates. It's worth noting that [CASTLE Platform® Certification Authority](https://ca.castle.cloud/ "CASTLE Platform® CA") differs from Let's Encrypt, utilizing its own certification authority. Nevertheless, [CASTLE Platform® CA](https://ca.castle.cloud/ "CASTLE Platform® CA") upholds the same standards as other common CAs, ensuring compatibility and extensions. If [CASTLE Platform® CA](https://ca.castle.cloud/ "CASTLE Platform® CA") is trusted, the resulting S/MIME certificate is likely comparable to those obtained through paid CAs. ## Installation -It is preferably to create a Virtual Environment and install the package as follows: - - python3 -m venv venv - source venv/bin/activate - pip3 install . - -It will install all dependencies and required packages. With the virtual environment activated, you can continue using the client `cli.py`. - -## How to use it -ACME E-mail S/MIME client uses the Certbot framework for managing ACME protocols. However, the official software does not provide support for S/MIME certification. To circumvent this issue, we bypass some procedures (CSR -- Certificate Signature Request mainly) to acomplish standard specifications. `cli.py` performs all this stuff by generating CSR with the correct extension and executes Certbot with the correct parameters. +Preferably, set up a Virtual Environment and install the package using the following commands: -To use it: +```bash +python3 -m venv venv +source venv/bin/activate +pip3 install . +``` - usage: cli.py [-h] -e EMAIL [-t] [--dry-run] [-n] [-c CONFIG_DIR] [-w WORK_DIR] [-l LOGS_DIR] [--agree-tos AGREE_TOS] [--contact CONTACT] [--imap] [--login LOGIN] [--password PASSWORD] [--host HOST] [--port PORT] [--ssl] - [--smtp-method {STARTTLS,SSL,plain}] [--smtp-login SMTP_LOGIN] [--smtp-password SMTP_PASSWORD] [--smtp-host SMTP_HOST] [--smtp-port SMTP_PORT] [--no-passphrase] [--passphrase PASSPHRASE] - [--usage {digitalSignature,contentCommitment,keyEncipherment,keyAgreement}] - {cert,revoke,renew} +These commands will install all necessary dependencies and required packages. Once the virtual environment is activated, you can proceed to use the client `cli.py`. - - Requests a S/MIME certificate - - positional arguments: - {cert,revoke,renew} - - optional arguments: - -h, --help show this help message and exit - -e EMAIL, --email EMAIL - E-mail of the issued certificate - -t, --test Tests the certification from a staging server - --dry-run Do not store any file. For testing - -n, --non-interactive - Runs the certification without any user interaction - -c CONFIG_DIR, --config-dir CONFIG_DIR - Configuration directory - -w WORK_DIR, --work-dir WORK_DIR - Working directory - -l LOGS_DIR, --logs-dir LOGS_DIR - Logs directory - --agree-tos AGREE_TOS - Logs directory - --contact CONTACT Contact e-mail for important account notifications - --imap Uses IMAP Authenticator for automatic reply - --login LOGIN IMAP login - --password PASSWORD IMAP password - --host HOST IMAP server host - --port PORT IMAP server port. If empty, it will be auto-detected - --ssl IMAP SSL connection - --smtp-method {STARTTLS,SSL,plain} - SMTP method {STARTTLS,SSL,plain} - --smtp-login SMTP_LOGIN - SMTP login. If empty, IMAP login will be used - --smtp-password SMTP_PASSWORD - SMTP password. If empty, IMAP password will be used - --smtp-host SMTP_HOST - SMTP server host - --smtp-port SMTP_PORT - SMTP server port. If empty, it will be auto-detected - --no-passphrase PKCS12 is stored without passphrase. Use with CAUTION: the PKCS12 contains the private key - --passphrase PASSPHRASE - Passphrase to use for the PKCS12 generation. This passpharse will be used for private key encryption - --usage {digitalSignature,contentCommitment,keyEncipherment,keyAgreement} - Key usage for certificate. Multiple usages can be specified - - --cert-path CERT_PATH - Path where certificate is located - --reason {unspecified,keycompromise,affiliationchanged,superseded,cessationofoperation} - Reason of revocation - --key-path KEY_PATH Path of private key location - --outlook Uses MAPI (Outlook) Authenticator for automatic reply - --outlook-account OUTLOOK_ACCOUNT - Outlook account where the challenge is processed - -Some of the parameters are shared by Certbot software, since it manages the protocol stack and data flow between the client and the ACME server. Sooner more parameters will be added. - -Multiple email addresses can be specified. All these addresses will be added to `subjectAltNames` extension with the identifier `email` into a single certificate. **No wildcards are allowed**. This is useful when you use multiple alias under the same email account. Keep in mind that there are some rate limits on the number of addresses that can be included in a single certificate. Consult them at [Rate Limits](https://acme.castle.cloud/documentation/rate-limits "Rate Limits"). To specify multiple email addresses use `--email` flag so many times as needed. +## How to use it +The ACME Email S/MIME client, implemented in `cli.py`, utilizes the Certbot framework for managing ACME protocols. Although the official software lacks support for S/MIME certification, we've devised a workaround by bypassing certain procedures, primarily the Certificate Signature Request (CSR), to adhere to standard specifications. + +Here's how to use the client: + +```plaintext +usage: cli.py [-h] [-e EMAIL] [-t] [--dry-run] [-n] [-c CONFIG_DIR] [-w WORK_DIR] [-l LOGS_DIR] [--agree-tos] + [--contact CONTACT] [--imap] [--login LOGIN] [--password PASSWORD] [--host HOST] [--port PORT] [--ssl] + [--smtp-method {STARTTLS,SSL,plain}] [--smtp-login SMTP_LOGIN] [--smtp-password SMTP_PASSWORD] + [--smtp-host SMTP_HOST] [--smtp-port SMTP_PORT] [--no-passphrase] [--passphrase PASSPHRASE] + [--usage {digitalSignature,contentCommitment,keyEncipherment,keyAgreement}] [--cert-path CERT_PATH] + [--reason {unspecified,keycompromise,affiliationchanged,superseded,cessationofoperation}] + [--key-path KEY_PATH] [--outlook] [--outlook-account OUTLOOK_ACCOUNT] [--tb] [--tb-unsafe] + [--tb-profile TB_PROFILE] [--tb-bin TB_BIN] + {cert,revoke,renew} +Requests a S/MIME certificate + +positional arguments: + {cert,revoke,renew} + +optional arguments: + -h, --help show this help message and exit + -e EMAIL, --email EMAIL + E-mail address to certify. Multiple e-mail addresses are allowed + -t, --test Tests the certification from a staging server + --dry-run Do not store any file. For testing + -n, --non-interactive + Runs the certification without any user interaction + -c CONFIG_DIR, --config-dir CONFIG_DIR + Configuration directory + -w WORK_DIR, --work-dir WORK_DIR + Working directory + -l LOGS_DIR, --logs-dir LOGS_DIR + Logs directory + --agree-tos Accepts Terms of Service + --contact CONTACT Contact e-mail for important account notifications + --imap Uses IMAP Authenticator for automatic reply + --login LOGIN IMAP login + --password PASSWORD IMAP password + --host HOST IMAP server host + --port PORT IMAP server port. If empty, it will be auto-detected + --ssl IMAP SSL connection + --smtp-method {STARTTLS,SSL,plain} + SMTP method {STARTTLS,SSL,plain} + --smtp-login SMTP_LOGIN + SMTP login. If empty, IMAP login will be used + --smtp-password SMTP_PASSWORD + SMTP password. If empty, IMAP password will be used + --smtp-host SMTP_HOST + SMTP server host + --smtp-port SMTP_PORT + SMTP server port. If empty, it will be auto-detected + --no-passphrase PKCS12 is stored without passphrase. Use with CAUTION: the PKCS12 contains the private key + --passphrase PASSPHRASE + Passphrase to use for the PKCS12 generation. This passpharse will be used for private key + encryption + --usage {digitalSignature,contentCommitment,keyEncipherment,keyAgreement} + Key usage for certificate. Multiple usages can be specified + --cert-path CERT_PATH + Path where certificate is located + --reason {unspecified,keycompromise,affiliationchanged,superseded,cessationofoperation} + Reason of revocation + --key-path KEY_PATH Path of private key location + --outlook Uses MAPI (Outlook) Authenticator for automatic reply + --outlook-account OUTLOOK_ACCOUNT + Outlook account where the challenge is processed + --tb Uses Thunderbird Authenticator for automatic reply + --tb-unsafe Run authenticator disabling security checks. USE WITH CAUTION. + --tb-profile TB_PROFILE + Thunderbird profile where it runs + --tb-bin TB_BIN Thunderbird binary/executable path +``` + +The parameters are a blend of Certbot software and custom ones required for managing the S/MIME certification process. Multiple email addresses can be specified using the `--email` flag, useful for including multiple aliases under the same email account. Note that wildcard entries are not permitted. Additionally, please refer to the rate limits for the number of addresses allowed in a single certificate [here](https://acme.castle.cloud/documentation/rate-limits "Rate Limits"). ### Key Usage -The ACME Email protocol defines the possibility to specify the key usage of the issued certificate. Currently, four (4) usages are allowed: -* For signing only: - * `digitalSignature`: this usage is highly recommended, as it enables the digital signature in S/MIME certificates for signing. - * `contentCommitment` (formerly `nonRepudation`): it enables non-repudiation services to guarantee the authenticity of signed data. -* For encryption only: - * `keyEncipherment`: the public key can be used to encrypt a symmetric key, which is transferred to the target. - * `keyAgreement`: the certificate may use a key agreement protocol to establish a symmetric key. +The ACME Email protocol allows specifying the key usage of the issued certificate. Currently, four (4) usages are permitted: + +- For signing only: + - `digitalSignature`: This usage is highly recommended as it enables digital signatures in S/MIME certificates for signing. + - `contentCommitment` (formerly `nonRepudation`): It enables non-repudiation services to guarantee the authenticity of signed data. + +- For encryption only: + - `keyEncipherment`: The public key can be used to encrypt a symmetric key, which is then transferred to the target. + - `keyAgreement`: The certificate may utilize a key agreement protocol to establish a symmetric key. -The client can specify multiple usages in a single certificate vía `--usage` flag. Use multiple `--usage` to specify multiple usages (for example, `--usage digitalSignature --usage keyEncipherment`). +The client can specify multiple usages in a single certificate via the `--usage` flag. Use multiple `--usage` flags to indicate multiple usages (e.g., `--usage digitalSignature --usage keyEncipherment`). -If no `--usage` flag is specified, the ACME server will issue a certificate with `digitalSignature`, `contentCommitment` and `keyEncipherment` by default. +If no `--usage` flag is specified, the ACME server will issue a certificate with `digitalSignature`, `contentCommitment`, and `keyEncipherment` by default. -No other extension are allowed in the CSR. Any CSR with extensions different from `keyUsage` and `subjectAltNames` will be rejected. +No other extensions are allowed in the CSR. Any CSR with extensions different from `keyUsage` and `subjectAltNames` will be rejected. -If `--key-path` is used for `cert` command, the new certificate will contain the same public key corresponding to the specified private key. This is useful for renewals with the same public key. +If `--key-path` is used for the `cert` command, the new certificate will contain the same public key corresponding to the specified private key. This is useful for renewals with the same public key. ### Example #### Using IMAP authenticator -For obtaining an S/MIME certificate with IMAP authenticator. With this authenticator, all the procedure is performed automatically. IMAP and SMTP clients are created dynamically and the ACME challenge is answered without user intervention. +To obtain an S/MIME certificate with the IMAP authenticator, the process is automated, requiring minimal user intervention. Here's an example command: -For example: - -`python3 cli.py cert --config-dir . --work-dir . --logs-dir . -e address@domain.com --contact contact@anotherdomain.com --imap --login imap_user --password imap_password --host imap.domain.com --ssl --smtp-method STARTTLS --smtp-port smtp_port --smtp-host smtp.domain.com` +```bash +python3 cli.py cert --config-dir . --work-dir . --logs-dir . -e address@domain.com --contact contact@anotherdomain.com --imap --login imap_user --password imap_password --host imap.domain.com --ssl --smtp-method STARTTLS --smtp-port smtp_port --smtp-host smtp.domain.com +``` -where `address@domain.com` is the e-mail address to certify and `contact@anotherdomain.com` is just the contact address for receiving notifications related with the account. Contact address is only used the first time. It can be ommitted in subsequent calls. +Explanation of parameters: +- `-e address@domain.com`: The email address to certify. +- `--contact contact@anotherdomain.com`: Contact address for receiving notifications related to the account. +- `--imap --login imap_user --password imap_password --host imap.domain.com --ssl`: IMAP settings for authentication. Replace `imap_user`, `imap_password`, and `imap.domain.com` with your IMAP login credentials and server information. SSL is enabled for secure communication. +- `--smtp-method STARTTLS --smtp-port smtp_port --smtp-host smtp.domain.com`: SMTP settings for authentication. Replace `smtp_port` and `smtp.domain.com` with your SMTP port and server information. STARTTLS method is used for secure communication. -This authenticator creates dynamic IMAP and SMTP clients for getting the token from the ACME e-mail, generate the authentication and reply to the ACME server with the ACME response. All the process is transparent and smooth to the user. Notes: -1. If no SMTP credentials are provided, IMAP credentials for SMTP client will be used. -2. This authenticator works for "normal" e-mail accounts. It does not work with e-mail providers that have OAuth login (i.e., no GMail). -3. The ACME message are catched from INBOX. It will not work if you have a misconfigured spam filtering or have pre-filtering rules. -4. In case it does not work, use interactive authenticator. - -If everything goes well, the ACME server will grant your request and will issue a certificate. This certificate will be downloaded automatically and the client will put in a PKCS12 container. The client also will put the private key in the PKCS12 container. The PKCS12 container is a standard object, used for importing public and private keys to the Keychain. Often is used by e-mail clients for selecting the S/MIME certificate, used for signature and encryption. +1. If SMTP credentials are not provided, the IMAP credentials for the SMTP client will be used. +2. This authenticator works with "normal" email accounts and does not support OAuth login (e.g., Gmail). +3. The ACME messages are retrieved from the INBOX. Ensure correct spam filtering or pre-filtering rules are in place. +4. If issues arise, consider using the interactive authenticator. -You can optionally protect the PKCS12 container with a passphrase. Since it contains your private key, **it is highly recommended** to protect the PKCS12 container with a strong passphrase. The client will prompt you for a passphrase before generating the PKCS12, if no `--pasphrase` is specified. If you aim at authomatizing the whole process, use the flag `--passphrase ` to specify the secret passphrase. +If the process is successful, the ACME server will grant the request and issue a certificate. The certificate will be downloaded automatically and stored in a PKCS12 container, which includes the private key. It's highly recommended to protect the PKCS12 container with a passphrase. You can specify the passphrase using `--passphrase ` to automate the process. #### Using MAPI/Outlook authenticator -MAPI authenticator allows to reply automatically the ACME Email Challenge without user interaction. The authenticator is able to manage the Outlook email client, previously configured, to receive, process and reply the challenge. +With this authenticator, no login and password are provided in the CLI since it uses Outlook client to manage the account. This authenticator works with OAuth email providers. -How to use: -1. Open your Outlook client **with Administrator privileges** (right click on the Outlook client --> Execute with Administrator privileges) -2. Select the Inbox of the account to challenge with. Ensure that the connection with you IMAP provider is properly configured. -3. Execute the client `cli.py` with `--outlook` and `--outlook-account ACCOUNT` parameters, where `ACCOUNT` is the name of your Outlook account. +To utilize the MAPI authenticator for automatically replying to the ACME Email Challenge without user interaction, follow these steps: + +1. Open your Outlook client **with Administrator privileges** (right-click on the Outlook client --> Run as Administrator). +2. Select the Inbox of the account to be challenged. Ensure that the connection with your IMAP provider is properly configured. +3. Execute the client `cli.py` with the `--outlook` and `--outlook-account ACCOUNT` parameters, where `ACCOUNT` is the name of your Outlook account. For example: -`python cli.py cert -e address@domain.com --outlook --outlook-account MyPersonalAccount` -* Due to Certbot limitations, Outlook must run with Administrator rights. +```bash +python cli.py cert -e address@domain.com --outlook --outlook-account MyPersonalAccount +``` -#### Using interactive authenticator -**IMPORTANT: This method is not recommended, as it does not performs any authentication check (such as DKIM or S/MIME). These checks MUST be carried out by the user manually.** +Note: Due to limitations in Certbot, Outlook must run with Administrator rights. -For obtaining an S/MIME certificate with interactive authenticator. +#### Using Thunderbird authenticator +With this authenticator, no login and password are provided in the CLI since it uses Thudnerbird client to manage the account. This authenticator works with OAuth email providers. -`python3 cli.py cert --config-dir . --work-dir . --logs-dir . -e address@domain.com --contact contact@anotherdomain.com --usage digitalSignature --usage keyEncipherment` +To utilize the Thunderbird authenticator for automatically replying to the ACME Email Challenge without user interaction, follow these steps: +1. Open your Thunderbird client. +2. Execute the client `cli.py` with the `--tb` parameter. +3. In case of security error, pass the `--tb-unsafe` parameter to bypass these checks. +4. After receiving the ACME challenge, a pop-up will appear with the response in the body. Just click on Send and **do not modify any value**. -where `address@domain.com` is the e-mail address to certify and `contact@anotherdomain.com` is just the contact address for receiving notifications related with the account. Contact address is only used the first time. It can be ommitted in subsequent calls. +For example: -After this, the client will negotiate with [CASTLE Platform® ACME Server](https://acme.castle.cloud/ "CASTLE Platform® ACME Server") for obtaining an S/MIME certificate. -1. An e-mail will be send to `address@domain.com` with a challenge subject. The client will wait for the token you will receive in the `address@domain.com`. -2. The subject has the form of `ACME: `. The `` part is needed for passing the challenge. -3. Copy the **entire** subject (with the `ACME: `part included) and paste it to the client terminal. -4. With the ``you provided, the client will generate the **challenge response**, which has the form `-----BEGIN ACME RESPONSE-----...-----END ACME RESPONSE-----`. -5. Copy the response and reply the ACME e-mail you received. Paste the challenge response in the **top of the message's body** and send it back to the ACME server. -**IMPORTANT: Remind that your private key is not transmitted to ACME server, nor flows through internet at any time. The CSR contains your public key linked to your private key and the ACME server generates the public certificate based on it, without the need of the private key.** +```bash +python cli.py cert -e address@domain.com --tb --tb-unsafe +``` -_(Reminder: private and public keys are generated automatically, you do not have to worry about that.)_ +#### Using interactive authenticator +**IMPORTANT: This method is not recommended, as it does not performs any authentication check (such as DKIM or S/MIME). These checks MUST be carried out by the user manually.** -### Current Features -* The private key is generated locally on your system. -* S/MIME challenge, defined at RFC 8823. -* PKCS12 certificate storaging, with embedded private key. -* Can revoke certificates. -* Adjustable RSA key bit-length (2048 (default), 4096, ...). -* Customizable key usage for the certificate: digitalSignature, keyEncipherment, contentCommitment and/or keyAgreement can be specified. -* Fully automated or interactive. -* IMAP and SMTP support for automated ACME replies. -* MAPI/Outlook support for automated ACME replies. -* DKIM and S/MIME checks for message authentication. -* Multiple email addresses in a single certificate. -* Reusable private key (and public) for multiple certificates. -* Staging ACME server for test environments. -* Supports an interactive text UI, or can be driven entirely from the command line. -* Free and Open Source Software, made with Python. +For obtaining an S/MIME certificate with the interactive authenticator, follow these steps: -## TL;DR (some technical aspects) -Certbot is a magnific software. It manages the ACME procedure and gives a support for customized plugins. However, it only supports "dns" Identifier Types in the CSR and here is where the problem arises. S/MIME certificates (and also specifications) require that Identifier Types **must be** "email". The ACME server could replace "dns" for "email" in the CSR but this is not possible, as the CSR is signed with the private key and it is unalterable. +```bash +python3 cli.py cert --config-dir . --work-dir . --logs-dir . -e address@domain.com --contact contact@anotherdomain.com --usage digitalSignature --usage keyEncipherment +``` -Fortunately, Certbot supports the `--csr` parameter, which allows to provide an external CSR instead of auto-generated CSR. +Explanation of parameters: +- `-e address@domain.com`: The email address to certify. +- `--contact contact@anotherdomain.com`: Contact address for receiving notifications related to the account. +- `--usage digitalSignature --usage keyEncipherment`: Specifies the key usages for the certificate. -The rest of the client is composed by three modules: +After executing this command, the client will negotiate with [CASTLE Platform® ACME Server](https://acme.castle.cloud/ "CASTLE Platform® ACME Server") to obtain an S/MIME certificate. Here's what you need to do next: -1. Authenticator plugin: it performs the authentication task, generating the ACME response by using the `` provided in the subject. Two authenticators are provided: - 1. IMAP: it creates dynamic IMAP and SMTP clients for ACME message interception, token catching and automatic response to ACME server. No user intervention is needed. - 2. Interactive: it requires user intervention by pasting the token, copying the ACME response and replying to the ACME server via e-mail. **This method is not recommended, as it does not performs any authentication check (such as DKIM or S/MIME). These checks MUST be carried out by the user manually.** -2. Installation plugin: it generates the PKCS12 container with the private key and certificate. -3. Challenges: it defines the EmailReply-00 challenge, described at RFC 8823. +1. An email will be sent to `address@domain.com` with a challenge subject. +2. The subject will have the form of `ACME: `. You need to wait for the token to be received in the email inbox. +3. Copy the **entire** subject (including the `ACME: ` part) and paste it into the client terminal. +4. The client will generate the **challenge response** using the provided token. This response will have the form `-----BEGIN ACME RESPONSE-----...-----END ACME RESPONSE-----`. +5. Copy the response and reply to the ACME email you received. Paste the challenge response in the **top of the message's body** and send it back to the ACME server. -Besides the `email` identifier, Certbot also does not allow missing `DNSName` in the Subject Alternative Names in the CSR. Due to this, we must add `RFC822Name` and `DNSName` in the CSR, both with the email to certify. +It's crucial to note that your private key is not transmitted to the ACME server or over the internet at any point. The CSR contains your public key, linked to your private key, and the ACME server generates the public certificate based on it, without requiring the private key. + +Also, remember that private and public keys are generated automatically, so you don't need to worry about that part of the process. + +### Current Features +It sounds like the ACME Email S/MIME client is quite versatile and feature-rich. Here's a summary of its capabilities: + +- **Local Private Key Generation**: The client generates the private key locally on the user's system. +- **S/MIME Challenge Support**: Implements the S/MIME challenge as defined in RFC 8823. +- **PKCS12 Certificate Storing**: Stores certificates in PKCS12 format, including the embedded private key. +- **Certificate Revocation**: Supports revocation of certificates. +- **Adjustable RSA Key Bit-length**: Allows customization of the RSA key bit-length, including options like 2048 (default), 4096, etc. +- **Customizable Key Usage**: Users can specify key usages for the certificate, including digitalSignature, keyEncipherment, contentCommitment, and/or keyAgreement. +- **Automation Options**: Supports both fully automated and interactive modes. +- **IMAP and SMTP Support**: Offers support for automated ACME replies via IMAP and SMTP. +- **MAPI/Outlook Support**: Provides support for automated ACME replies using MAPI/Outlook. +- **Thunderbird Support**: Provides support for automated ACME replies using Thunderbird. +- **DKIM and S/MIME Checks**: Performs DKIM and S/MIME checks for message authentication. +- **Multiple Email Addresses**: Can include multiple email addresses in a single certificate. +- **Reusable Private Key**: Allows reuse of private (and public) keys for multiple certificates. +- **Staging ACME Server**: Supports a staging ACME server for testing environments. +- **User Interface Options**: Supports an interactive text UI or can be driven entirely from the command line. +- **Open Source**: Free and open-source software, developed with Python. + +Overall, these features make the ACME Email S/MIME client a comprehensive tool for managing S/MIME certificates with various customization and automation options. + +## TL;DR (some technical aspects) +# Summary: -Thanks to this, we are able to write on our own code and leave the Certbot code unmodified. Of course, if in a future Certbot supports "email" Identifier Type and ACME S/MIME challenges, all this repository will be useless. In the meantime, you can use it. +Certbot is a powerful software for managing the ACME procedure, but it only supports "dns" Identifier Types in the CSR, which is incompatible with S/MIME certificates requiring "email" Identifier Types. To address this, the client provides a workaround using the `--csr` parameter to accept external CSRs. The client comprises three main modules: -## License -All the code in this repository is under GPLv3 license. +1. **Authenticator Plugin**: + - **IMAP**: Automatically handles ACME challenge responses by creating dynamic IMAP and SMTP clients. + - **Interactive**: Requires user intervention for ACME challenge responses, but lacks authentication checks. +2. **Installation Plugin**: Generates PKCS12 containers with private keys and certificates. +3. **Challenges**: Defines the EmailReply-00 challenge specified in RFC 8823. -## About -ACME E-mail S/MIME Client and ACME E-mail S/MIME Server are part of the [CASTLE Platform®](https://www.castle.cloud/ "CASTLE Platform®"), a platform of the [Centre Tecnològic de Telecomunicacions de Catalunya (CTTC)](https://www.cttc.es "CTTC"). +Additionally, due to Certbot's requirements, the CSR must include both `RFC822Name` and `DNSName` in the Subject Alternative Names. The client's flexibility allows users to customize their code while leveraging Certbot's functionality. If Certbot were to support "email" Identifier Types and ACME S/MIME challenges in the future, this workaround may become unnecessary. -Maintainer: -* Pol Henarejos (pol.henarejos@cttc.es). +## License: +The code in this repository is licensed under GPLv3. -The Centre Tecnològic de Telecomunicacions de Catalunya (CTTC) is a non-profit research institution based in Castelldefels (Barcelona), resulting from a public initiative of the Regional Government of Catalonia (Generalitat de Catalunya). +## About: +The ACME E-mail S/MIME Client and ACME E-mail S/MIME Server are components of the CASTLE Platform®, developed by the Centre Tecnològic de Telecomunicacions de Catalunya (CTTC), a non-profit research institution based in Castelldefels, Spain. CTTC focuses on communication system technologies and geomatics research. -Research activities at the CTTC, both fundamental and applied, mainly focus on technologies related to the physical, data-link and network layers of communication systems, and to the Geomatics. +**Maintainer:** Pol Henarejos (pol.henarejos@cttc.es) \ No newline at end of file