README

Installing
==========

The scripts do not need to be installed, but do prefer recent versions
of Bash (4.1.0 or later) and OpenSSL (1.0.1 or later). You will get
reduced functionality and/or unusable defaults on earlier versions.

Tested and working on Linux, FreeBSD, NetBSD, MacOSX and Windows.

To install on Windows you need MSYS2 or Cygwin. The portion of this used in
Git for Windows is sufficient. Other Unix/Linux emulators may work too.

whatssl bash script
===================

Gives a description of the contents of any OpenSSL related certificate,
key or parameter file. If the file contains multiple items they are
all described. If an item is encrypted a tiny dictionary attack will
be attempted.

Note: It will not print any private part of a file, instead it will
extract the related public key and describe the item as a "private key
for" the displayed public part.

mk-ovpn and mk-ovpn2 bash scripts
=================================

The mk-ovpn script calls mk-cert to make certificates and keys for
OpenVPN. The idea is to use the "singleuseca" mode to create a CA
certificate specifically for every instance of OpenVPN (client and server)
and only have the CA certificates that of the specific keys allowed to
connect listed in the configuration file. The mk-ovpn2 script collects
these CA certificates (and the user certificates and keys) does the
necessary selections for generating each ovpn config file.

At least one of the certificates must be marked as a server and a,
possibly empty, pattern file is needed to prefix the client setups.

mk-cert bash script
===================

Usage: mk-cert [Common Name] [arguments]

This script can create most styles of x509 certificate from the command
line.  All options can be configured from arguments and the standard
OpenSSL configuration file is not used. The default is to prompt for a
common name (plus OU and dnQualifier) and generate an ec:prime256r1 key
and certificate which is sent to the standard output.

Options:

    -cn=String
    -subj-cn=String
    -subj-ou=String
    -subj-dc=String
    -subj-o=String
    -subj-l=String
    -subj-st=String
    -subj-c=String
    -subj:oid=value

	Set a component of the certificate subject. Some items such as
	DC, OU and CN are allowed to be duplicated. OpenSSL will accept
	duplicates for any item.

	The OU is the most likely to be accepted as a place to store
	any unusual part of a name you may wish to include.

	The "-cn=" option is taken as both a common name, a SAN and the
	official common name for generic use. The "-subj-cn=" option
	string will only be used in the subject.

	Any arguments without a "-" to make them an option are assumed
	to be names too, the first one is a common name, like the "-cn"
	option.  The rest are san names if they look like domain names
	or IP addresses and OU items if they don't.

	If a argument begins with a "/" and contains an "=" it is
	treated as an OpenSSL subject string. This conflicts with the
	other options for building a subject.

	The bare "-subj:" version copies the string "oid=value" to the
	end of the section of the configuration. This allows any of the
	possible name parts (surname, info, favouriteDrink, CSPName, etc)
	to be added in any order. If OpenSSL doesn't know a particular
	oid the numeric value can be used.

	If no subject is specified one will be prompted for by OpenSSL
	unless a SAN is requested in which case an error is generated
	unless "-no-prompt" is used.

    -days=7304
	How many days should the certificate run for?

    -days=2038-01-18
	What day should the certificate expire on?

    -alldays
	Make the certificate run until 9999-12-31

    -out=FileName
	Put the certificate, and any other items in a file.

    -addcert=FileName
	Filename contains a certificate, put it in the same location as
	the created certificate. (Used for intermediate CA certificates)

    -keyout=FileName
	Put the private key in a specific file not "-out=" or stdout.

    -crl
	Generate an empty CRL using the certificate used to sign.

    -crlout=FileName
	Generate an empty CRL using the certificate used to sign.

    -caout=FileName
	Put the certificate used to sign in a specific file.

    -ser=0123456789abcdef
    -serial=0123456789abcdef
	Set the certificate serial number (in hexadecimal).
	Various noise characters will be removed.

    -dnq
	Generate and add a dnQualifier item to the subject.
	This is the original way of making sure that the subject of
	a certificate is unique. It was only needed within an org
	as the other DN components were sufficient for identifing
	organisations.

    -dnq=...
	Add a specific dnQualifier item to the subject.

    -nodnq
	Do not add a dnQualifier item to any subject; even if told to.

    -no-prompt
	Prevent OpenSSL prompting for any part of the subject.

    -ec:prime256v1
    -ec:256
    -ec:curve:encoding
    -ec:curve:encoding:no_seed
    -ec:ed25519
	Use OpenSSL ecparam to generate an EC key. This includes ed25519, ed448
	and their X25519 and X448 counterparts. The numbers 256,384 and 521 are
	shorthands for the curves prime256v1, secp384r1 and secp521r1.

    -ed25519
    -ed448
	Generate an ed25519 or ed448 private key.

    -list-curves
    -show-curves
	List the EC curves that OpenSSL supports.

    -rsa
    -rsa=2048
	Generate RSA private keys.

    -dsa
    -dsa=1024
	Generate DSA private keys.
	NB: This also makes the default digest SHA1.

    -keyfile=FileName
	Don't generate a key, use the one in FileName. If you're generating
	a "single use ca" the second throwaway key will be generated to be
	the same type as the key in this file if possible.

    -csrin=FileName
	Use the CSR from FileName instead of generating a new key.
	This cannot be used to create a self-signed certificate.

    -pubin=FileName
	Like -csrin this will use the public key from the item in FileName
	instead of generating a new key. The file can be any recognised
	file that contains a public key, not just a CSR. But if it's
	a CSR or a certificate it's common name will also be used if
	nothing else is specified.

    -csr
	Create a certificate signing request not a certificate
	Must use -keyout= option too.

    -showcsr
	Dump any CSR we use to the output too.

    -sign=FileName
	Use the key and certificate in FileName to sign the certificate,
	note if it's a PFX file it must have a ".pfx" extension.

    -singleuseca
    -suca
	Generate a new CA key for the CA certificate and to sign the standard
	certificate. Discard the CA key and send the CA certificate to the
	output.

    -v3singleuseca
    -v3suca
	Same but always make the CA a V3 certificate with the CA flag.

    -v1suca
	Same but always make the CA a V1 certificate.

    -casubj=...
    -caname=...
	Set the subject name for the single use CA, first is a CN or
	organisation, the rest are OU items.

    -pkcs12=FileName
    -pfx=FileName
	Create a "pfx" file with the certificate, private key and the
	CA certificate used to sign the certificate. The "-pkcs12" variant
	saves the file base64 encoded.

    -pass:password
    -pass=OpenSSL:pass
	Set a password on the key.

    -cipher=name
	Select the cipher used for encrypting the key with a password.

    -dgst=sha1
    -ripemd160, -sha, -sha1, -sha224, -sha256, -sha384, -sha512, -whirlpool
	Select the digest used for signing.

    -openssl=/path/to/executable/openssl
	Use the specified copy of openssl, not the one in the PATH.

    -showconf
	Debugging option, show the config files generated for OpenSSL

Version 3 certificate extensions.

    Note V3 extensions are used to limit the uses that a certificate
    can be put to. If you're not concerned with limiting use of the
    private key (ie the user is trusted) then these generally have
    no use. However, some validators insist on certain V3 extensions
    being present.

    The SAN extension is a minor exception to this as it allows multiple
    wildcard DNS names whereas browsers only accept one wildcard CN
    item in the subject. In addition some browsers are rejecting all
    certificates that don't have a SAN extension.

    -v3
	Make the certificate V3, don't add any extensions though.

    -v3san=SanName
    -san=SanName
	Add a SAN name.
	It may include the type prefix ie: DNS:www.example.com otherwise
	a dumb huristic is used to identify the type of the item. This
	option can be repeated as many times as needed.

	Note: the common name will normally be added automatically too.

    -v3san, -san
	Make a san from the common name even if there are no others.
	This is now required by Chrome in direct contravention of the
	requirements of RFC 2818 (HTTP over SSL).

    -v3ca, -ca
	Add normal V3 extensions for a CA certificate.

    -v3basicca
	Add only the basic extension for a CA certificate.

    -v3lastca, -lastca
	Make a V3 CA certificate with the 'pathlen:0' option to prevent
	certificates that this CA signs being CAs.

    -v3nokeyid, -nokeyid
	Disable the "Subject Key Identifier" and "Authority Key Identifier"
	additions.

    -v3usr, -v3user, -usr, -user
	Prevent this V3 certificate begin used as a CA.

    -v3server, -server
	Add V3 key usage extensions to prevent the certificate being used
	as anything except an SSL server.
	NB: Can be combined with -v3client or -v3email to allow those.

    -v3client, -client
	Add V3 key usage extensions to prevent the certificate being used
	as anything except an SSL client.
	NB: Can be combined with -v3server or -v3email to allow those.

    -v3email, -email
	Add V3 key usage extensions to prevent the certificate being used
	as anything except a MIME signing or encryption certificate.
	NB: Can be combined with -v3server or -v3client to allow those.

    -v3codesign, -codesign
	Add V3 key usage extensions to prevent the certificate being used
	as anything except a code signing certificate.

    -v3timestamp, -timestamp
	Add V3 key usage extensions for timestamp signing. This can NOT
	be combined with other key usages.

    -v3ns, -ns
	Add the netscape Client/server extensions too.

    -v3ns=...
    -ns=...
	Add a specific list of netscape usages.

    -v3crit, -v3critical, -critical
	Mark CA, key usage and extended key usage extensions as critical.
	Beware:
	    https://en.wikipedia.org/wiki/X.509#Implementation_issues

    -poltext=FileName
	Add an "all uses" policy extension and include the text from
	FileName as an "issuer statement".

    -policy=OID
	The first one of these sets the OID for the '-poltext' option if
	present. Additional '-policy' arguments add extra policy extensions.

    -tlsfeature=...
	Add the V3 extension that states a server will send a 'status_request'
	or 'status_request_v2' response when requested.

    -must-staple
	Alias for -tlsfeature=status_request
	Can also be entered as -v3=1.3.6.1.5.5.7.1.24=DER:30:03:02:01:05

    -v3permit=..., -permit=..., -v3exclude..., -exclude...
	Add the V3 extension for 'Name constraints', they consist of domain
	names or IP addresses with subnet masks in the form of tagged SAN
	names.

    -v3crluri=..., -crlurl=...
	Add a "CRL Distribution Point" item to the certificate extensions.

    -v3dv|-dv )
	Make the certificate policy "Domain validated" and set most
	of the other stuff that's supposed to be set.
	BUT would also need:
	    The certificate must be signed by a CA (not self-signed)
	    Add authorityInformationAccess extension
	    with OCSP over HTTP
	    and HTTP URL for issuing certificate

    -v3='OpenSSL extension config'
	Add any x509 v3 extension config to the OpenSSL config file used
	to create the certificate.

    -v3xt='OpenSSL extension config'
    -xt='OpenSSL extension config'
	Add any x509 v3 extension config to the OpenSSL config file used
	to create the certificate.

	This item is placed after the all "-v3=" items so can be used when
	the config file needs additional sections.