# More About WASD OpenSSL

### OpenSSL v1.0.2j, 26th September 2016

https://openssl.org/news/changelog.html

Copyright © 1998-2016 Mark G. Daniel
This program, comes with ABSOLUTELY NO WARRANTY.
This is free software, and you are welcome to redistribute it under the
conditions of the GNU GENERAL PUBLIC LICENSE, version 3, or any later version.
http://www.gnu.org/licenses/gpl.txt

OpenSSL
Copyright © 1998-2016 The OpenSSL Project
Copyright © 1995-1998 Eric Young
OpenSSL License

## Contents

- Local Copy
- Default Configuration
- Certificate Authority
- Server Certificates
- Key Size
- Finger Pokin'
- Ephemeral DH Param
- Wipeout

This directory contains a number of procedures providing an elementary certificate management environment for WASD without needing to be too concerned with the intricacies of OpenSSL. It should be emphasized that this facility does not pretend to be any more than a casual source of server certificates and does not exploit anywhere-near the full capabilities of OpenSSL certificate management. Nor does it claim to be robust or fool-proof (a casual inspection of the procedures will reveal the phrase "quick and dirty" used more than once). The contents may be used as-are or cloned to create a site-specific instance. This document assumes a site copy is desired.

WASD documentation on SSL/TLS features is 4 - Secure Sockets Layer / Transport Layer Security from WASD VMS Web Services - Features and Facilities document (from local site).

OpenSSL.org documentation wiki at https://wiki.openssl.org/

## Local Copy

This directory structure, procedures and default configuration file are designed for simple copying into something site-specific. The site copy does not need to be part of the OpenSSL or WASD trees.

    $ CREATE /DIRECTORY device:[directory]
    $ COPY WASD_ROOT:[SRC.OPENSSL-1_0_2.WASD]*.COM,*.CNF,*.HTML device:[directory]

When first used the procedures will create the following directory structure.

    device:[directory]
                     .CERT]
                     .CERT.WORK]

The top-level directory contains the procedures, etc., `[.CERT]` the generated certificates, and `[.CERT.WORK]` the certificate database, serial number index and random number seed. This directory is also used as scratch space during procedure use.

## Default Configuration

The configuration file DEFAULT.CNF may be edited to provide _default responses more in line with local requirements. The following section entries can generally be modified from the WASD-specifics, others only with more detailed knowlege of OpenSSL.

    [ req_distinguished_name ]
    countryName			= Country Name (2 letter code)
    countryName_default		= AU

    stateOrProvinceName		= State or Province Name (full name)
    stateOrProvinceName_default	= SA

    localityName			= Locality Name (eg, city)
    localityName_default		= Adelaide

    0.organizationName		= Organization Name (eg, company)
    0.organizationName_default	= WASD HTTPd Server Cert

    organizationalUnitName		= Organizational Unit Name (eg, section)
    organizationalUnitName_default	= Testing Only

    commonName			= Common Name (eg, YOUR name)
    commonName_default		= WASD VMS Web Services

    emailAddress			= Email Address
    emailAddress_default		= Mark.Daniel@wasd.vsm.com.au

To specify a different configuration file name (in the same directory) assign the symbol `CONFIGFILENAME` before executing any WASD procedures.

    $ CONFIGFILENAME = "LOCAL.CNF"
    $ @CREATE_CA_CERT.COM
    $ @CREATE_SERVER_CERT.COM name

## Certificate Authority

A Certificate Authority (or CA) certificate may then be generated. This forms the "authority" for any server certificates subsequently issued using it. It requires a "PEM pass phrase" (password) to be supplied. The password is case-sensitive. This password must be provided when generating server certificates ... don't forget it!

    $ @CREATE_CA_CERT

## Server Certificates

These certificates are used for authentication and encryption purposes by Secure Sockets Layer services provided by a server. When creating such a certificate the CA password will be required (and remember, the password is case-sensitive). When creating a server certificate details of the server and it's organisation need to be provided.

    $ @CREATE_SERVER_CERT name

## Key Size

The RSA private key size specified by these procedures is a recommended 2048 bits. Some older browsers (e.g. VMS Netscape Navigator Gold 3.03) will not have an encryption algorithm supporting this key size and will report messages to that effect. New certificates using a 512 bit key size (determined empirically) for both CA and server will need to be generated to support such an environment. Assign the symbol `RSAKEYSIZE` before executing any WASD procedures.

    $ RSAKEYSIZE = 1024
    $ @CREATE_CA_CERT.COM
    $ @CREATE_SERVER_CERT.COM name

## Finger-Pokin'

It is possible to manually "fiddle" the certificate management database if an inadvertant certificate is created, a problem aborts certificate processing, etc. It involves the modification of two files.

- `[.CERT.WORK]SERIAL.TXT`
  This file contains the serial number of the next certificate. This can be "stepped back" (or anywhere for that matter) by simple editing. The file `SERIAL.TXT-OLD` is the previous version and could be copied over the current to undo the last certificate generation.
- `[.CERT.WORK]INDEX.TXT`
  This file contains a list of issued certificate details (it is to this the message "Data Base Updated" refers), one certificate per line. This too can be manually modified - with care (each line is generally longer than eighty characters). The file `INDEX.TXT-OLD` is the previous version and could be copied over the current to undo the last certificate generation.

Make quite sure whatever you modify represents exactly what you intend to undo!

## Ephemeral DH Param

Forward secrecy, sometimes known as perfect forward secrecy (PFS), is a property of key-agreement protocols ensuring that a session key derived from a set of long-term keys cannot be compromised if one of the long-term keys is compromised in the future.

> https://en.wikipedia.org/wiki/Forward_secrecy

OpenSSL supports forward secrecy using Diffie-Hellman key exchange with elliptic curve cryptography and this relies on generating emphemeral keys based on unique, safe prime numbers. These are expensive to generate and so this is done infrequently, often during software build or installation. In the case of WASD, to maximise flexibility, these numbers are stored in external PEM-format files, by default located in the `WASD_ROOT:[LOCAL]` directory. These files are only briefly accessed during server startup SSL initialisation and the content later used during network connection SSL negotiation to generate the required ephemeral keys. Each file contains one prime for a given key size, 512, 1024, etc., generated using the OpenSSL dhparam utility.

Executing the procedure

    $ @CREATE_EPHEMERAL_DH_PARAM

will generate files containing 512, 1024 and 2048 bit primes (this can take considerable time), and optionally copy those files to the `WASD_ROOT:[LOCAL]` directory. The `[.CERT]` directory contains files that could be used but unique, locally generated primes are preferable.

NOTE: Ephemeral keys form part of PFS, the others being selection and ordering of server ciphers, and ensuring the server determines the cipher used (`+OP_CIPHER_SERVER_PREFERENCE`). Ephemeral key generation is supported beginning with WASD v10.4.1.

## Wipeout!

It is possible to "clean out" all server certificates, or even more drastically delete the CA certificate and all the database files (effectively returning the environment to an empty condition). Use with caution!

    $ @CREATE_CLEAN