Merge branch 'TinCanTech-vars-hierarchy-v2'

Signed-off-by: Richard T Bonhomme <[email protected]>

ChangeLog

@@ -3,12 +3,18 @@ Easy-RSA 3 ChangeLog
 3.2.0 (TBD)
 
 3.1.7 (2023-10-13)
+   * Rewrite vars-auto-detect, adhere to EasyRSA-Advanced.md (#1029)
+     Under the hood, this is a considerable change but there are no user
+     noticable differences. With the exception of:
+     Caveat: The default '$PWD/pki/vars' file is forbidden to change either
+             EASYRSA or EASYRSA_PKI, which are both implied by default.
+   * EasyRSA-Advanced.md: Correct vars-auto-detect hierarchy (#1029)
+     Commit: ecd65065e3303da78811278a154ef7a969c2777b
+             EASYRSA/vars is moved to a higher priority than a default PKI.
+             vars-auto-detect no longer searches 'easyrsa' program directory.
    * gen-crl: preserve existing crl.pem ownership+mode (#1020)
    * New command: make-vars - Print vars.example (here-doc) to stdout (#1024)
    * show-expire: Calculate cert. expire seconds from DB date (#1023)
-   * Forbid "default vars in the default PKI" for all commands (#1021)
-     There can be only one default vars file, that is now './vars' ONLY.
-     Use of other 'vars' files can be done by using option --vars=<FILE>
    * Update OpenSSL to 3.1.2
 
 3.1.6 (2023-07-18)

doc/EasyRSA-Advanced.md

@@ -33,14 +33,27 @@ Configuration Reference
 
   1. The file referenced by the `--vars` CLI option
   2. The file referenced by the env-var named `EASYRSA_VARS_FILE`
-  3. The directory referenced by the `EASYRSA_PKI` env-var
-  4. The default PKI directory at `$PWD/pki`
-  4. The directory referenced by the `EASYRSA` env-var
-  5. The directory containing the easyrsa program
+  3. The directory referenced by the `--pki` CLI option (Recommended)
+  4. The directory referenced by the `EASYRSA_PKI` env-var
+  5. The directory referenced by the `EASYRSA` env-var
+  6. The default PKI directory at `$PWD/pki` (See note below)
+  7. The default working directory at `$PWD`
 
   Defining the env-var `EASYRSA_NO_VARS` will override the sourcing of the vars
   file in all cases, including defining it subsequently as a global option.
 
+  Note: If the vars file `$PWD/pki/vars` is sourced then it is forbidden from
+        setting/changing the current PKI, as defined by `EASYRSA_PKI` env-var.
+
+#### Use of `--pki` verses `--vars`
+
+  It is recommended to use option `--pki=DIR` to define your PKI at runtime.
+  This method will always auto-load the `vars` file found in defined PKI.
+
+  In a multi-PKI installation, use of `--vars` can potentially lead to
+  a vars file that is configured to set a PKI which cannot be verified
+  as the expected PKI. Use of `--vars` is not recommended.
+
 #### OpenSSL Config
 
   Easy-RSA is tightly coupled to the OpenSSL config file (.cnf) for the