nstcert

Name

nstcert — NST script to generate SSL certificates.

Synopsis

nstcert [ -m ENTRY | --mode ENTRY ] [ --name TEXT ] [ --country TEXT ] [ --state TEXT ] [ --locality TEXT ] [ --organization TEXT ] [ --unit TEXT ] [ --common TEXT ] [ --san TEXT ] [ --email TEXT ] [ --days-valid INTEGER ] [ --ssl-host HOSTNAME|IPv4ADDR ] [ --ssl-port PORT ] [ --document-root DIRECTORY ] [ --certfile FILENAME ] [ --keep [true]|false ] [ -c FILENAME | --config FILENAME ] [ -h [true]|false | --help [true]|false ] [ -H [true]|false | --help-long [true]|false ] [ -v [true]|false | --verbose [true]|false ] [ --version [true]|false ]

Description

The process of generating SSL key and certificate files and then making use of them in a Apache™ configuration file can be a time consuming process. This script attempts to automate part of the process by generating template files for use within the Apache™ httpd daemon. A convenient PEM (Privacy-enhanced Electronic Mail) file is also generated.

Because there are so many settings associated with a certificate file, it often makes sense to create a template configuration file, edit the contents of the template configuration file, then use the configuration file to produce the final results. This will reduce the number of items which must be entered on the command line.

Here is a example of using nstcert:

[root@probe ~]# nstcert -m cfg -c show >| redali.crt.conf
[root@probe ~]# vi redali.crt.conf
[root@probe ~]# nstcert -m cfg -c redali.crt.conf -v
+ NOTE    + Generating key file: ca.key
+ SUCCESS + Created key: ca.key
+ NOTE    + Generating certificate file: redali.crt
+ SUCCESS + Created the CA private key file: ca.key
+ SUCCESS + Created the self-signed CA certificate file: ca.crt
+ SUCCESS + Created the private key file: redali.key
+ SUCCESS + Created the certificate signing request file: server.csr
+ SUCCESS + Created the serial number file: server.srl
+ SUCCESS + Created the x509 self-signed certificate file: redali.crt
+ NOTE    + Generating pem file: redali.pem
+ SUCCESS + Created pem file: redali.pem
+ NOTE    + Generating Apache config file: redali-apache.conf
+ SUCCESS + Created Apache config file: redali-apache.conf

Congratulations, we have successfully generated the following:

  redali.key          install under: /etc/nst/httpd/conf/ssl.key/
  redali.crt          install under: /etc/nst/httpd/conf/ssl.crt/
  redali.pem          install under: /etc/nst/
  redali-apache.conf  install under: /etc/nst/httpd/conf.d

After installing the above files in the directories shown, you will
want to edit "/etc/nst/httpd/conf.d/redali-apache.conf" and then issue
the following command to restart the nstwui service:

  systemctl reload nstwui.service

The current mapping is:

  https://55.55.55.55:24365/ -> /opt/pub/redali/public_html

[root@probe ~]#

Notes:

In the above example, one would want to review and/or edit the "redali-apache.conf" configuration file.
While the files generated by this script have only been tested on the NST system, we suspect that they will be usable in other environments as well.

Options

The following command line options are available:

[-m ENTRY] | [--mode ENTRY]: This option controls what the nstcert script will do. The following modes are available: ("cfg"), "pem" or "view". If you specify "cfg" (the default), this script will be in Generate SSL Certificate mode and operation will depend on the value of the "[-c | --config FILENAME]" option. Specify "pem" to generate the NST PEM (Privacy-enhanced Electronic Mail) file: "/etc/nst/nst.pem". This file can only be created if the Apache Server Certificate file: "/etc/nst/httpd/conf/ssl.crt/server.crt" and the Server Private Key file: "/etc/nst/httpd/conf/ssl.key/server.key" have been previously generated. Specify "view" to use the openssl command to view an X.509 certificate in text format specified by the "--certfile FILENAME" parameter.
[--name TEXT]: This option allows one to specify the name to be used when generating files related to the certificate. For example, if you specify: "--name bogus", we will generate "bogus.key", "bogus.crt" and "bogus-apache.conf". This value can be set via NAME in the config file.
[--country TEXT]: This is used to identify the country associated with your certificate. It should be a two character (upper case) ISO identifier. For example: "US". This value can be set via COUNTRY in the config file.
[--state TEXT]: This option allows one to specify the province (or state name) to associate with the certificate. It should be the full name (mixed case is acceptable). For example: "New York". This value can be set via STATE in the config file.
[--locality TEXT]: This option allows one to specify the location (typically the city name) to associate with the certificate. It should be the full name (mixed case is acceptable). For example: "Albany". This value can be set via LOCALITY in the config file.
[--organization TEXT]: This option allows one to specify the organization (typically the company name) to associate with the certificate. It should be the full name (mixed case is acceptable). For example: "My New Company". This value can be set via ORGANIZATION in the config file.
[--unit TEXT]: This option allows one to specify the unit within the organization to associate with the certificate. It should be the full name (mixed case is acceptable). For example: "My New Department". It is acceptable to leave this field blank. This value can be set via UNIT in the config file.
[--common TEXT]: This option allows one to associate a common name with the certificate. Most people will use either a person's name, or the name of the host system. For example: "www.mynewcompany.bogus". It is acceptable to leave this field blank. This value can be set via COMMON in the config file.
[--san TEXT]: This option allows one to specify one or more subject alternate names (subjectAltName) with the certificate. The default value used will be the Fully Qualified Domain Name (FQDN) for the system. The format used for specifying these alternative names is a quoted, comma separated string with a "DNS:" prefix for each name added: "subjectAltName=DNS:name1,DNS:name2". For example: "subjectAltName=DNS:redstore.com,DNS:www.redstore.com".
[--email TEXT]: This option allows one to associate a particular email address with the certificate. For example: "jane.doe@mynewcompany.bogus". It is acceptable to leave this field blank. This value can be set via EMAIL in the config file.
[--days-valid INTEGER]: This option controls how many days the certificate will remain valid. It defaults to 730 (2 years) if omitted (roughly 10 years). This value can be set via DAYS_VALID in the config file. As of Fall 2019 values greater than 825 days may cause certificate issues. The minimum value permitted is 1. The maximum value permitted is 365000.
[--ssl-host HOSTNAME|IPv4ADDR]: The host name or IP address of the SSL server as it will appear to client connections (where the httpd daemon is running). You will typically want to change it from the default value of "127.0.0.1". This value can be set via SSL_HOST in the config file.
[--ssl-port PORT]: The port number which the httpd daemon should listen for SSL connections. You may want to change it from the default value of "443" if you are hosting multiple sites. This value can be set via SSL_PORT in the config file.
[--document-root DIRECTORY]: This parameter is used to specify the location of the directory where the httpd daemon will find the files to serve. This value can be set via DOCUMENT_ROOT in the config file.
[--certfile FILENAME]: Use this option with mode: "view" to display the X.509 content in text format for the certificate file.
[--keep [true]|false]: Normally, the intermediate (temporary) files that are created in the process of generating your final certificate files are removed. If you would like these temporary files to remain for inspection, use the "--keep" option. This is typically only used for debugging purposes. Most users will not need to specify this option.
[-c FILENAME] | [--config FILENAME]: By default, the nstcert will attempt to load configuration information from both /etc/nst/nstcert.conf and ${HOME}/.nstcert.conf (where the values in the latter file take precedence). If the files are not found, then all required parameters must be specified on the command line. You can specify --config FILE to load a configuration file other than ${HOME}/.nstcert.conf. You may specify --config no to disable the loading of any configuration. You may specify --config load if you want the script to exit in error if ${HOME}/.nstcert.conf is not found. You may specify --config save to save the options specified as ${HOME}/.nstcert.conf. You may specify --config show to see what the current command line arguments (or default values) would look like if saved in a configuration file.
[-h [true]|false] | [--help [true]|false]: When this option is specified, nstcert will display a short one line description of nstcert, followed by a short description of each of the supported command line options. After displaying this information nstcert will terminate.
[-H [true]|false] | [--help-long [true]|false]: This option will attempt to pull up additional nstcert documentation within a text based web browser. You can force which browser we use setting the environment variable TEXTBROWSER, otherwise, we will search for some common ones.
[-v [true]|false] | [--verbose [true]|false]: When you set this option to true, nstcert will produce additional output. This is typically used for diagnostic purposes to help track down when things go wrong.
[--version [true]|false]: If this option is specified, the version number of the script is displayed.

Environment