liz/veilid
1
0
Fork 0
Code Pull Requests Packages Releases Activity

Add Test CA and simple certs for testing

Browse Source
This commit is contained in:
John Smith
2021-11-22 09:02:41 -05:00
parent 190f0ed36b
commit c4cd54e020
41 changed files with 5081 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

124
files/test-ca/doc/EasyRSA-Advanced.md Normal file
View File

@@ -0,0 +1,124 @@
Easy-RSA Advanced Reference
=============================
This is a technical reference for advanced users familiar with PKI processes. If
you need a more detailed description, see the `EasyRSA-Readme` or `Intro-To-PKI`
docs instead.
Configuration Reference
-----------------------
#### Configuration Sources
There are 3 possible ways to perform external configuration of Easy-RSA,
selected in the following order where the first defined result wins:
1. Command-line option
2. Environmental variable
3. 'vars' file, if one is present (see `vars Autodetection` below)
4. Built-in default
Note that not every possible config option can be set everywhere, although any
env-var can be added to the 'vars' file even if it's not shown by default.
#### vars Autodetection
A 'vars' file is a file named simply `vars` (without an extension) that
Easy-RSA will source for configuration. This file is specifically designed
*not* to replace variables that have been set with a higher-priority method
such as CLI opts or env-vars.
The following locations are checked, in this order, for a vars file. Only the
first one found is used:
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
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.
#### OpenSSL Config
Easy-RSA is tightly coupled to the OpenSSL config file (.cnf) for the
flexibility the script provides. It is required that this file be available,
yet it is possible to use a different OpenSSL config file for a particular
PKI, or even change it for a particular invocation.
The OpenSSL config file is searched for in the following order:
1. The env-var `EASYRSA_SSL_CONF`
2. The 'vars' file (see `vars Autodetection` above)
3. The `EASYRSA_PKI` directory with a filename of `openssl-easyrsa.cnf`
4. The `EASYRSA` directory with a filename of `openssl-easyrsa.cnf`
Advanced extension handling
---------------------------
Normally the cert extensions are selected by the cert type given on the CLI
during signing; this causes the matching file in the x509-types subdirectory to
be processed for OpenSSL extensions to add. This can be overridden in a
particular PKI by placing another x509-types dir inside the `EASYRSA_PKI` dir
which will be used instead.
The file named `COMMON` in the x509-types dir is appended to every cert type;
this is designed for CDP usage, but can be used for any extension that should
apply to every signed cert.
Additionally, the contents of the env-var `EASYRSA_EXTRA_EXTS` is appended with
its raw text added to the OpenSSL extensions. The contents are appended as-is to
the cert extensions; invalid OpenSSL configs will usually result in failure.
Environmental Variables Reference
---------------------------------
A list of env-vars, any matching global option (CLI) to set/override it, and a
possible terse description is shown below:
* `EASYRSA` - should point to the Easy-RSA top-level dir, where the easyrsa
script is located.
* `EASYRSA_OPENSSL` - command to invoke openssl
* `EASYRSA_SSL_CONF` - the openssl config file to use
* `EASYRSA_PKI` (CLI: `--pki-dir`) - dir to use to hold all PKI-specific
files, defaults to `$PWD/pki`.
* `EASYRSA_DN` (CLI: `--dn-mode`) - set to the string `cn_only` or `org` to
alter the fields to include in the req DN
* `EASYRSA_REQ_COUNTRY` (CLI: `--req-c`) - set the DN country with org mode
* `EASYRSA_REQ_PROVINCE` (CLI: `--req-st`) - set the DN state/province with
org mode
* `EASYRSA_REQ_CITY` (CLI: `--req-city`) - set the DN city/locality with org
mode
* `EASYRSA_REQ_ORG` (CLI: `--req-org`) - set the DN organization with org mode
* `EASYRSA_REQ_EMAIL` (CLI: `--req-email`) - set the DN email with org mode
* `EASYRSA_REQ_OU` (CLI: `--req-ou`) - set the DN organizational unit with org
mode
* `EASYRSA_KEY_SIZE` (CLI: `--key-size`) - set the key size in bits to
generate
* `EASYRSA_ALGO` (CLI: `--use-algo`) - set the crypto alg to use: rsa or ec
* `EASYRSA_CURVE` (CLI: `--curve`) - define the named EC curve to use
* `EASYRSA_EC_DIR` - dir to store generated ecparams
* `EASYRSA_CA_EXPIRE` (CLI: `--days`) - set the CA expiration time in days
* `EASYRSA_CERT_EXPIRE` (CLI: `--days`) - set the issued cert expiration time
in days
* `EASYRSA_CRL_DAYS` (CLI: `--days`) - set the CRL 'next publish' time in days
* `EASYRSA_NS_SUPPORT` (CLI: `--ns-cert`) - string 'yes' or 'no' fields to
include the deprecated Netscape extensions
* `EASYRSA_NS_COMMENT` (CLI: `--ns-comment`) - string comment to include when
using the deprecated Netscape extensions
* `EASYRSA_TEMP_FILE` - a temp file to use when dynamically creating req/cert
extensions
* `EASYRSA_REQ_CN` (CLI: `--req-cn`) - default CN, necessary to set in BATCH
mode
* `EASYRSA_DIGEST` (CLI: `--digest`) - set a hash digest to use for req/cert
signing
* `EASYRSA_BATCH` (CLI: `--batch`) - enable batch (no-prompt) mode; set
env-var to non-zero string to enable (CLI takes no options)
* `EASYRSA_PASSIN` (CLI: `--passin`) - allows to specify a source for
password using any openssl password options like pass:1234 or env:var
* `EASYRSA_PASSOUT` (CLI: `--passout`) - allows to specify a source for
password using any openssl password options like pass:1234 or env:var
**NOTE:** the global options need to be provided before the actual commands.

236
files/test-ca/doc/EasyRSA-Readme.md Normal file
View File

@@ -0,0 +1,236 @@
Easy-RSA 3 Documentation Readme
===============================
This document explains how Easy-RSA 3 and each of its assorted features work.
If you are looking for a quickstart with less background or detail, an
implementation-specific How-to or Readme may be available in this (the `doc/`)
directory.
Easy-RSA Overview
-----------------
Easy-RSA is a utility for managing X.509 PKI, or Public Key Infrastructure. A
PKI is based on the notion of trusting a particular authority to authenticate a
remote peer; for more background on how PKI works, see the `Intro-To-PKI`
document.
The code is written in platform-neutral POSIX shell, allowing use on a wide
range of host systems. The official Windows release also comes bundled with the
programs necessary to use Easy-RSA. The shell code attempts to limit the number
of external programs it depends on. Crypto-related tasks use openssl as the
functional backend.
Feature Highlights
------------------
Here's a non-exhaustive list of the more notable Easy-RSA features:
* Easy-RSA is able to manage multiple PKIs, each with their own independent
configuration, storage directory, and X.509 extension handling.
* Multiple Subject Name (X.509 DN field) formatting options are supported. For
VPNs, this means a cleaner commonName only setup can be used.
* A single backend is used across all supported platforms, ensuring that no
platform is 'left out' of the rich features. Unix-alikes (BSD, Linux, etc)
and Windows are all supported.
* Easy-RSA's X.509 support includes CRL, CDP, keyUsage/eKu attributes, and
additional features. The included support can be changed or extended as an
advanced feature.
* Interactive and automated (batch) modes of operation
* Flexible configuration: features can be enabled through command-line
options, environment variables, a config file, or a combination of these.
* Built-in defaults allow Easy-RSA to be used without first editing a config
file.
Obtaining and Using Easy-RSA
----------------------------
#### Download and extraction (installation)
Easy-RSA's main program is a script, supported by a couple of config files. As
such, there is no formal "installation" required. Preparing to use Easy-RSA is
as simple as downloading the compressed package (.tar.gz for Linux/Unix or
.zip for Windows) and extract it to a location of your choosing. There is no
compiling or OS-dependent setup required.
You should install and run Easy-RSA as a non-root (non-Administrator) account
as root access is not required.
#### Running Easy-RSA
Invoking Easy-RSA is done through your preferred shell. Under Windows, you
will use the `EasyRSA Start.bat` program to provide a POSIX-shell environment
suitable for using Easy-RSA.
The basic format for running commands is:
./easyrsa command [ cmd-opts ]
where `command` is the name of a command to run, and `cmd-opts` are any
options to supply to the command. Some commands have mandatory or optional
cmd-opts. Note the leading `./` component of the command: this is required in
Unix-like environments and may be a new concept to some Windows users.
General usage and command help can be shown with:
./easyrsa help [ command ]
When run without any command, general usage and a list of available commands
are shown; when a command is supplied, detailed help output for that command
is shown.
Configuring Easy-RSA
--------------------
Easy-RSA 3 no longer needs any configuration file prior to operation, unlike
earlier versions. However, the `vars.example` file contains many commented
options that can be used to control non-default behavior as required. Reading
this file will provide an idea of the basic configuration available. Note that
a vars file must be named just `vars` (without an extension) to actively use it.
Additionally, some options can be defined at runtime with options on the
command-line. A full list can be shown with:
./easyrsa help options
Any of these options can appear before the command as required as shown below:
./easyrsa [options] command [ cmd-opts ]
For experts, additional configuration with env-vars and custom X.509 extensions
is possible. Consult the `EasyRSA-Advanced` documentation for details.
Getting Started: The Basics
---------------------------
Some of the terms used here will be common to those familiar with how PKI works.
Instead of describing PKI basics, please consult the document `Intro-To-PKI` if
you need a more basic description of how a PKI works.
#### Creating an Easy-RSA PKI
In order to do something useful, Easy-RSA needs to first initialize a
directory for the PKI. Multiple PKIs can be managed with a single installation
of Easy-RSA, but the default directory is called simply "pki" unless otherwise
specified.
To create or clear out (re-initialize) a new PKI, use the command:
./easyrsa init-pki
which will create a new, blank PKI structure ready to be used. Once created,
this PKI can be used to make a new CA or generate keypairs.
#### The PKI Directory Structure
An Easy-RSA PKI contains the following directory structure:
* private/ - dir with private keys generated on this host
* reqs/ - dir with locally generated certificate requests (for a CA imported
requests are stored here)
In a clean PKI no files exist yet, just the bare directories. Commands called
later will create the necessary files depending on the operation.
When building a CA, a number of new files are created by a combination of
Easy-RSA and (indirectly) openssl. The important CA files are:
* `ca.crt` - This is the CA certificate
* `index.txt` - This is the "master database" of all issued certs
* `serial` - Stores the next serial number (serial numbers increment)
* `private/ca.key` - This is the CA private key (security-critical)
* `certs_by_serial/` - dir with all CA-signed certs by serial number
* `issued/` - dir with issued certs by commonName
#### After Creating a PKI
Once you have created a PKI, the next useful step will be to either create a
CA, or generate keypairs for a system that needs them. Continue with the
relevant section below.
Using Easy-RSA as a CA
----------------------
#### Building the CA
In order to sign requests to produce certificates, you need a CA. To create a
new CA in a PKI you have created, run:
./easyrsa build-ca
Be sure to use a strong passphrase to protect the CA private key. Note that
you must supply this passphrase in the future when performing signing
operations with your CA, so be sure to remember it.
During the creation process, you will also select a name for the CA called the
Common Name (CN.) This name is purely for display purposes and can be set as
you like.
#### Importing requests to the CA
Once a CA is built, the PKI is intended to be used to import requests from
external systems that are requesting a signed certificate from this CA. In
order to sign the request, it must first be imported so Easy-RSA knows about
it. This request file must be a standard CSR in PKCS#10 format.
Regardless of the file name to import, Easy-RSA uses a "short name" defined
during import to refer to this request. Importing works like this:
./easyrsa import-req /path/to/request.req nameOfRequest
The nameOfRequest should normally refer to the system or person making the
request.
#### Signing a request
Once Easy-RSA has imported a request, it can be reviewed and signed. Every
certificate needs a "type" which controls what extensions the certificate gets
Easy-RSA ships with 3 possible types: `client`, `server`, and `ca`, described
below:
* client - A TLS client, suitable for a VPN user or web browser (web client)
* server - A TLS server, suitable for a VPN or web server
* ca - A intermediate CA, used when chaining multiple CAs together
./easyrsa sign-req <type> nameOfRequest
Additional types of certs may be defined by local sites as needed; see the
advanced documentation for details.
#### Revoking and publishing CRLs
If an issue certificate needs to be revoked, this can be done as follows:
./easyrsa revoke nameOfRequest
To generate a CRL suitable for publishing to systems that use it, run:
./easyrsa gen-crl
Note that this will need to be published or sent to systems that rely on an
up-to-date CRL as the certificate is still valid otherwise.
Using Easy-RSA to generate keypairs & requests
----------------------------------------------
Easy-RSA can generate a keypair and certificate request in PKCS#10 format. This
request is what a CA needs in order to generate and return a signed certificate.
Ideally you should never generate entity keypairs for a client or server in a
PKI you are using for your CA. It is best to separate this process and generate
keypairs only on the systems you plan to use them.
Easy-RSA can generate a keypair and request with the following command:
./easyrsa gen-req nameOfRequest
You will then be given a chance to modify the Subject details of your request.
Easy-RSA uses the short name supplied on the command-line by default, though you
are free to change it if necessary. After providing a passphrase and Subject
details, the keypair and request files will be shown.
In order to obtain a signed certificate, the request file must be sent to the
CA for signing; this step is obviously not required if a single PKI is used as
both the CA and keypair/request generation as the generated request is already
"imported."

58
files/test-ca/doc/EasyRSA-Upgrade-Notes.md Normal file
View File

@@ -0,0 +1,58 @@
Upgrading to Easy-RSA 3 from earlier versions
=========
People upgrading to Easy-RSA 3 from a 2.x version should note some important
changes starting with version 3. For a better overview of version 3 in general,
see the Readme in the doc/ directory.
List of important changes
----
* nsCertType extensions are no longer included by default. Use of such
"Netscape" attributes have been deprecated upstream and their use is
discouraged. Configure `EASYRSA_NS_SUPPORT` in vars if you want to enable
this legacy behavior.
Notably, this is important for OpenVPN deployments relying on the
`--ns-cert-type` directive. Either have OpenVPN use the preferred
`--remote-cert-tls` option, or enable legacy NS extensions.
* The default request Subject (or DN, Distinguished Name) includes just the
commonName. This is more suitable for VPNs and environments that don't wish
to include info about the Country/State/City/Org/OU in certs. Configure
`EASYRSA_DN` in vars if you want to enable the legacy behavior.
* The 3.0 release lacks PKCS#11 (smartcard/token) support. This is anticipated
to be supported in a future point-release to target each platform's need.
* The -utf8 option has been added for all supported commands. This should be
backwards compatible with ASCII strings.
* The default private key encryption has been changed from 3des to aes256.
Some new concepts
----
Easy-RSA 3 has some new concepts compared to the prior v2 series.
### Request-Import-Sign workflow
v3 is now designed to support keypairs generated on the target system where
they will be used, thus improving security as no keys need to be transferred
between hosts. The old workflow of generating everything in a single PKI is
still supported as well.
The recommended workflow when using Easy-RSA as a CA is to import requests,
sign them, and return the issued & CA certs. Each requesting system can use
Easy-RSA without a CA to generate keypairs & requests.
### "Org"-style DN flexibility
When using Easy-RSA in the "org" DN mode, it is no longer required to match
some of the field values. This improves flexibility, and enables easier remote
generation as the requester doesn't need to know the CA's values in advance.
Previously in v2, the Country, State, and Org values all had to match or a
request couldn't be signed. If you want the old behavior you can change the
OpenSSL config to require it or simply look over the DN at signing time.

142
files/test-ca/doc/Hacking.md Normal file
View File

@@ -0,0 +1,142 @@
Easy-RSA 3 Hacking Guide
===
This document is aimed at programmers looking to improve on the existing
codebase.
Compatibility
---
The `easyrsa` code is written in POSIX shell (and any cases where it is not is
considered a bug to be fixed.) The only exceptions are the `local` keyword and
the construct `export FOO=baz`, both well-supported.
As such, modifications to the code should also be POSIX; platform-specific code
should be placed under the `distro/` dir and listed by target platform.
Coding conventions
---
While there aren't strict syntax standards associated with the project, please
follow the existing format and flow when possible; however, specific exceptions
can be made if there is a significant reason or benefit.
Do try to:
* Keep variables locally-scoped when possible
* Comment sections of code for readability
* Use the conventions for prefixes on global variables
* Set editors for tab stops of 8 spaces
* Use tabs for code indents; use aligned spaces for console text
Keeping code, docs, and examples in sync
---
Changes that adjust, add, or remove features should have relevant docs, help
output, and examples updated at the same time.
Release versioning
---
A point-release bump (eg: 3.0 to 3.1) is required when the frontend interface
changes in a non-backwards compatible way. Always assume someone has an
automated process that relies on the current functionality for official
(non-beta, non-rc) releases. A possible exception exists for bugfixes that do
break backwards-compatibility; caution is to be used in such cases.
The addition of a new command may or may not require a point-release depending
on the significance of the feature; the same holds true for additional optional
arguments to commands.
Project layout
---
The project's files are structured as follows:
* `easyrsa3/` is the primary project code. On Linux/Unix-alikes, all the core
code and supporting files are stored here.
* `Licensing/` is for license docs.
* `build/` is for build information and scripts.
* `contrib/` is for externally-contributed files, such as useful external
scripts or interfaces for other systems/languages.
* `distro/` is for distro-specific supporting files, such as the Windows
frontend wrappers. Code components that are not platform-neutral should go
here.
* `doc/` is for documentation. Much of this is in Markdown format which can be
easily converted to HTML for easy viewing under Windows.
* `release-keys/` list current and former KeyIDs used to sign release packages
(not necessarily git tags) available for download.
* The top-level dir includes files for basic project info and reference
appropriate locations for more detail.
As a brief note, it is actually possible to take just the easyrsa3/ dir and end
up with a functional project; the remaining structure includes docs, build prep,
distro-specific wrappers, and contributed files.
Git conventions
---
As of Easy-RSA 3, the following git conventions should be used. These are mostly
useful for people with repo access in order to keep a standard meaning to commit
messages and merge actions.
### Signed-off-by: and related commit message lines
Committers with push access should ensure a `Signed-off-by:` line exists at
the end of the commit message with their name on it. This indicates that the
committer has reviewed the changes to the commit in question and approve of
the feature and code in question. It also helps verify the code came from an
acceptable source that won't cause issues with the license.
This can be automatically added by git using `git commit -s`.
Additional references can be included as well. If multiple people reviewed the
change, the committer may add their names in additional `Signed-off-by:`
lines; do get permission from that person before using their name, however ;)
The following references may be useful as well:
* `Signed-off-by:` -- discussed above, indicates review of the commit
* `Author:` -- references an author of a particular feature, in full or
significant part
* `Changes-by:` -- indicates the listed party contributed changes or
modifications to a feature
* `Acked-by:` -- indicates review of the feature, code, and/or functional
correctness
### Merging from external sources (forks, patches, etc)
Contributions can come in many forms: GitHub "pull requests" from cloned
repos, references to external repos, patches to the ML, or others. Those won't
necessary have `Signed-off-by:` lines or may contain less info in the commit
message than is desirable to explain the changes.
The committing author to this project should make a merge-commit in this case
with the appropriate details provided there. If additional code changes are
necessary, this can be done on a local branch prior to merging back into the
mainline branch.
This merge-commit should list involved contributors with `Author:` or similar
lines as required. The individual commits involved in a merge also retain the
original committer; regardless, the merge-commit message should give a clear
indication of what the entire set of commits does as a whole.
### Tagging
Tags should follow the convention:
vM.m.p
where `M` is the major version, `m` is the minor "point-release" version, and
`p` is the patch-level. Suffixes of `-rc#`, `-beta#`, etc can be added for
pre-release versions as required.
Currently tags are taken from the mainline development branch in question. The
ChangeLog should thus be updated prior to tagging. Tags should also be
annotated with an appropriate commit message and signed-off. This can be done
as shown below (don't use `-s` unless you intend to use GPG with git.)
git tag -a v1.2.3
Corresponding release downloads can be uploaded to release distribution points
as required.

97
files/test-ca/doc/Intro-To-PKI.md Normal file
View File

@@ -0,0 +1,97 @@
Introduction to PKI
===================
This document is designed to give you a brief introduction into how a PKI, or
Public Key Infrastructure, works.
Terminology Used
----------------
To avoid confusion, the following terms will be used throughout the Easy-RSA
documentation. Short forms may be substituted for longer forms as convenient.
* **PKI**: Public Key Infrastructure. This describes the collection of files
and associations between the CA, keypairs, requests, and certificates.
* **CA**: Certificate Authority. This is the "master cert" at the root of a
PKI.
* **cert**: Certificate. A certificate is a request that has been signed by a
CA. The certificate contains the public key, some details describing the
cert itself, and a digital signature from the CA.
* **request**: Certificate Request (optionally 'req'.) This is a request for a
certificate that is then send to a CA for signing. A request contains the
desired cert information along with a digital signature from the private
key.
* **keypair**: A keypair is an asymmetric cryptographic pair of keys. These
keys are split into two parts: the public and private keys. The public key
is included in a request and certificate.
The CA
------
The heart of a PKI is the CA, or Certificate Authority, and this is also the
most security-sensitive. The CA private key is used to sign all issued
certificates, so its security is critical in keeping the entire PKI safe. For
this reason, it is highly recommended that the CA PKI structure be kept on a
system dedicated for such secure usage; it is not a great idea to keep the CA
PKI mixed in with one used to generate end-entity certificates, such as clients
or servers (VPN or web servers.)
To start a new PKI, the CA is first created on the secure environment.
Depending on security needs, this could be managed under a locked down account,
dedicated system, or even a completely offline system or using removable media
to improve security (after all, you can't suffer an online break-in if your
system or PKI is not online.) The exact steps to create a CA are described in a
separate section. When creating a new CA, the CA keypair (private and public
keys) are created, as well as the file structure necessary to support signing
issued certificates.
Once a CA has been created, it can receive certificate requests from
end-entities. These entity certificates are issued to consumers of X509
certificates, such as a client or server of a VPN, web, or email system. The
certificate requests and certificates are not security-sensitive, and can be
transferred in whatever means convenient, such as email, flash drive, etc. For
better security, it is a good idea to verify the received request matches the
sender's copy, such as by verifying the expected checksum against the sender's
original.
Keypairs and requests
---------------------
Individual end-entities do not need a full CA set up and will only need to
create a keypair and associated certificate request. The private key is not used
anywhere except on this entity, and should never leave that system. It is wise
to secure this private key with a strong passphrase, because if lost or stolen
the holder of the private key can make connections appearing as the certificate
holder.
Once a keypair is generated, the certificate request is created and digitally
signed using the private key. This request will be sent to a CA for signing, and
a signed certificate will be returned.
How requests become certificates
--------------------------------
After a CA signs the certificate request, a signed certificate is produced. In
this step, the CA's private key is used to digitally sign the entity's public
key so that any system trusting the CA certificate can implicitly trust the
newly issued certificate. This signed certificate is then sent back to the
requesting entity. The issued certificate is not security-sensitive and can be
sent over plaintext transmission methods.
Verifying an issued certificate
-------------------------------
After 2 entities have created keypairs, sent their requests to the CA, and
received a copy of their signed certificates and the CA's own certificate, they
can mutually authenticate with one-another. This process does not require the 2
entities to have previously exchanged any kind of security information directly.
During a TLS handshake each side of the connection presents their own cert chain
to the remote end. Each side checks the validity of the cert received against
their own copy of the CA cert. By trusting the CA root cert, the peer they are
talking to can be authenticated.
The remote end proves it "really is" the entity identified by the cert by
signing a bit of data using its own private key. Only the holder of the private
key is able to do this, allowing the remote end to verify the authenticity of
the system being connected to.