From f71374dd1f5637e7b25afaa8b1b04816c8f4a771 Mon Sep 17 00:00:00 2001 From: Richard T Bonhomme Date: Mon, 26 Aug 2024 20:18:46 +0100 Subject: [PATCH 1/2] doc: Revoke and Renew, update for Easy-RSA v3.2.1 Add available abbreviations for 'reason' codes. Add 'renew' and 'expire/sign' details. Add place holder for "CA renewal" Signed-off-by: Richard T Bonhomme --- doc/EasyRSA-Renew-and-Revoke.md | 102 ++++++++++++++++++++++---------- 1 file changed, 70 insertions(+), 32 deletions(-) diff --git a/doc/EasyRSA-Renew-and-Revoke.md b/doc/EasyRSA-Renew-and-Revoke.md index fa2140f9d..c4a0b0256 100644 --- a/doc/EasyRSA-Renew-and-Revoke.md +++ b/doc/EasyRSA-Renew-and-Revoke.md @@ -2,33 +2,77 @@ Easy-RSA 3 Certificate Renewal and Revocation Documentation =========================================================== This document explains how the **differing versions** of Easy-RSA 3 work -with Renewal and Revocation of Certificates and Private keys. +with regard to Renewal and Revocation of Certificates. + +## In summary: + + **Easy-RSA Version 3.1.7** provides the most flexible support of renewal. +This includes command `rewind-renew`, which is required to recover certificates +renewed by `renew` command version 1. However, this does **not** include renewing +any supported certificate attributes. + +**Easy-RSA Version 3.2.1** is preferred for future support. + +---- + +Reason codes available for revoke commands +------------------------------------------ + +The follow is an exhaustive list of available `reason` codes, with abbreviations: + +- `us | uns* | unspecified` +- `kc | key* | keyCompromise` +- `cc | ca* | CACompromise` +- `ac | aff* | affiliationChanged` +- `ss | sup* | superseded` +- `co | ces* | cessationOfOperation` +- `ch | cer* | certificateHold` + + `reason` must be one of these abbreviations/codes, otherwise not be used. + +---- Easy-RSA version 3.2.x ---------------------- -v3.2 no longer supports the `renew` command. +For **Easy-RSA Version 3.2.0**, command `renew` is NOT supported. + +Please upgrade to Easy-RSA Version 3.2.1 + +For **Easy-RSA Version 3.2.1+**, command `renew` is supported. -Instead, the process is as follows: -1. Command `expire ` - This will move an existing certificate - from `pki/issued` to `pki/expired`, so that a new certificate - can be signed, using the original request. +The command `renew` has been rewritten and now supports the renewal of +supported attributes. During renewal, the certificate is inspected and all +supported attributes are applied to the renewed certificate, as they were +in the original. - Generally, renewing is required ONLY when a certificate is due to - expire. This means that certificates moved to `pki/expired` are - expected to be expired or to expire in the near future. +User added attributes from `$EASYRSA_EXTRA_EXTS`, that are not supported, +are dropped. -2. Command `sign-req ` - Sign a new certificate. +If the renewed certificate requires unsupported attibutes or changing the +`commonName` then the following process, that of expiry and then signing a +new certificate from the original request file, is required. - This allows ALL command line customisations to be used. eg: SAN. - (These customisations do not work correctly with the old `renew`) +The expiry and signing process is as follows: +1. Command `expire ` -3. If required, Command `revoke-expired` can be used to revoke an + This will move an existing certificate from `pki/issued` to `pki/expired`, + so that a new certificate can be signed, using the original request. + + Generally, renewing is required ONLY when a certificate is due to expire. + This means that certificates moved to `pki/expired` are expected to be expired + or to expire in the near future, however, this is not a requirement. + +2. Command `sign-req ` + + Sign a new certificate. This allows ALL command line customisations to be used. + +3. If required, command `revoke-expired` can be used to revoke an expired certificate in the `pki/expired` directory. -This approach also allows certificates which have been edited during -`sign-req` to be edited the same way, without the need for excessive -and non-standard code. (Note: OpenSSL allows only one way for edits) +This approach allows original certificates, which have been edited during `sign-req`, +to be edited the same way. +---- Easy-RSA version 3.1.x ---------------------- @@ -76,7 +120,7 @@ using command: easyrsa rewind-renew serialNumber -Command `rewind-renew` is available since Easy-RSA version `3.1.1` +Command `rewind-renew` is only available in Easy-RSA version `3.1.1` to `3.1.7`. Once `rewind-renew` has recovered the files, the certificate can be revoked: @@ -111,6 +155,7 @@ private key is still valid. `renew` version 3 is **only** available since Easy-RSA version `3.1.1+`. +---- Easy-RSA Reporting tools for certificate status ----------------------------------------------- @@ -131,21 +176,7 @@ certificate status: `show-revoke` shows all certificates which have been revoked. - -Reason codes available for revoke commands ------------------------------------------- - -The follow is an exhaustive list of available `reason` codes: -- `unspecified` -- `keyCompromise` -- `CACompromise` -- `affiliationChanged` -- `superseded` -- `cessationOfOperation` -- `certificateHold` - - `reason` must be one of these codes, otherwise not be used. - +---- About command `rebuild` ----------------------- @@ -153,3 +184,10 @@ About command `rebuild` If `rebuild` is used then the output directory of old certificate, key and request is also the `renewed` directory. Use **`revoke-renewed`** to revoke an old certificate/key pair, which has been _rebuilt_ by command `rebuild`. + +---- + +Renew CA Certificate +==================== + +TBD From df099d7f4711948714764ff5efcdcf5ebf036f13 Mon Sep 17 00:00:00 2001 From: Richard T Bonhomme Date: Fri, 30 Aug 2024 19:22:56 +0100 Subject: [PATCH 2/2] doc: Revoke and Renew, update for Easy-RSA v3.2.1 - Partial renew CA Signed-off-by: Richard T Bonhomme --- doc/EasyRSA-Renew-and-Revoke.md | 73 +++++++++++++++++++++++++++++---- 1 file changed, 65 insertions(+), 8 deletions(-) diff --git a/doc/EasyRSA-Renew-and-Revoke.md b/doc/EasyRSA-Renew-and-Revoke.md index c4a0b0256..baee5f9cc 100644 --- a/doc/EasyRSA-Renew-and-Revoke.md +++ b/doc/EasyRSA-Renew-and-Revoke.md @@ -6,7 +6,7 @@ with regard to Renewal and Revocation of Certificates. ## In summary: - **Easy-RSA Version 3.1.7** provides the most flexible support of renewal. +**Easy-RSA Version 3.1.7** provides the most flexible support of renewal. This includes command `rewind-renew`, which is required to recover certificates renewed by `renew` command version 1. However, this does **not** include renewing any supported certificate attributes. @@ -33,7 +33,7 @@ The follow is an exhaustive list of available `reason` codes, with abbreviations ---- Easy-RSA version 3.2.x ----------------------- +====================== For **Easy-RSA Version 3.2.0**, command `renew` is NOT supported. Please upgrade to Easy-RSA Version 3.2.1 @@ -75,11 +75,7 @@ to be edited the same way. ---- Easy-RSA version 3.1.x ----------------------- - -**UPDATE**: -The changes noted for Easy-RSA version 3.1.2 have all been included with -Easy-RSA version 3.1.1 - See https://github.com/OpenVPN/easy-rsa/pull/688 +====================== Command Details: `renew` ------------------------ @@ -190,4 +186,65 @@ an old certificate/key pair, which has been _rebuilt_ by command `rebuild`. Renew CA Certificate ==================== -TBD +Easy-RSA Version 3.2.1+ supports a simple way to effectively renew a CA Certificate. + +**Preamble** - Specifically for use with OpenVPN: + +When a CA certificate expires it must be replaced, this is unavoidable. +No matter what method is used to create a new or renewed CA certificate, +that CA certificate must be distributed to all of your servers and clients. + +Please consider the method outlined here, which requires very little work: + +1. **Before you do anything else -- Make a BACKUP of your current PKI.** + +2. Use command `init-pki soft` + + This will reset your current PKI but will keep your `vars` setting file + and your current Request files [CSR], in the `pki/reqs` directory. + + If you have an Easy-RSA generated TLS key for OpenVPN, that will also be + preserved. However, it will NOT be used for new `inline` files. The file + `pki/private/easyrsa-tls.key` will be moved to `pki/easyrsa-keepsafe-tls.key`, + for safe keeping. Easy-RSA will display a warning that this key is still + valid and possibly in use, before allowing another TLS key to be generated. + +3. Use command `build-ca` + + (With or without password and other preferences) + + This will build a completely new CA Certificate and private key. + + Use option `--days` to extend the lifetime of your new CA. + +4. Use command `sign-req ` + + (With or without other preferences, password is not relavent) + + This will use an existing Request to sign a new Certificate. + + This will NOT generate a new Private Key for each new Certificate. + + This will generate new `inline` files that can be distributed publicly. + These `inline` files will not contain any security sensitive data. + + This means that you will have a new CA certificate and private key. + And signed certificates for all of your users, including servers. + +5. Distribute the new `inline` files to all members of your PKI/VPN. + + These new `inline` files will not contain the user private key or the + OpenVPN Pre-shared TLS key. + + These new `inline` files can be used by OpenVPN, examples below: + + * specify: `--config ` in the OpenVPN user config file. + * Use copy/paste to add the new details to the OpenVPN user config file. + * Use `cat` to append the `inline` file to the OpenVPN user config file. + + Note: + `inline` files in the `pki/inline/private` directory include security keys, + which MUST only be transmitted over a secure connection, such as `https`. + + As of Easy-RSA Version 3.2.1, this is the only supported way to renew an + expired CA certificate.