Command Line Interface

Using the command line

The SimpleAuthority sauth command line interface can be used to automate common tasks, including:

  • generating new certificates
  • creating new users
  • updating user details
  • deleting users
  • processing CSR files, and
  • generating CRLs.

The command line interface requires an Enterprise license.

The installer automatically updates your PATH environment variable on Windows platforms so that the sauth.bat script can be found. On Mac and Linux platforms, this needs to be done manually.

On Mac platforms with default install settings, you can do this by created a .bash_profile file in your home directory (or appending your existing file) with the following line:

export PATH="/Applications/SimpleAuthority.app/Contents/MacOS":$PATH

Command line interface

The following commands are supported. See below for more information on arguments.

cert

sauth cert -subj arg [-passin arg] [-passout arg] [-verbose] [-stdout]

sauth cert -name arg [-passin arg] [-passout arg] [-verbose] [-stdout]


Generates a new certificate for an existing user. The user can be identified using their subject distinguished name, or just their name.

Options/Preferences settings are used to control the output directory for the new identity file, whether or not a separate certificate file is also created, if a backup of the identity file is retained, file formats and names, directory publishing and iCalendar publishing behaviour.

If -passout is not specified, a randomly generated password will be used for the new identity file.

Examples:

sauth cert -subj "C=AU,O=Acme Inc,CN=John Doe" -passin "pass:caPassword"

sauth cert -name "John Doe" -passin "pass:caPassword" -passout "pass:JohnsPassword"

batchcert

sauth batchcert [-passin arg] [-passout arg] [-verbose] [-stdout]


Generates new certificates for all active users that are currently marked as having "warning" (orange) status.

Options/Preferences settings are used to control the time period for when users are marked with "warning" status prior to certificate expiry, as well as other settings (see cert command for details).

Examples:

sauth batchcert

sauth batchcert -passin "pass:caPassword" -passout "pass:userPasswords"

create

sauth create -subj arg [-san arg] [-type arg] [-days arg] [-verbose]

sauth create -name arg [-san arg] [-type arg] [-days arg] [-verbose]


Creates a new user.

Default settings are used for the user's Organisational Unit, Organisation and Country settings when the -name version of this command is used. Default settings are also used for the certificate type and validity period if these are not specified.

Examples:

sauth create -subj "C=AU,O=Acme Inc,CN=John Doe" -san "john@nowhere.com"

sauth create -name "John Doe" -type "General Purpose" -days 365

update

sauth update -subj arg [-newsubj arg] [-san arg] [-type arg] [-days arg] [-active yes|no] [-verbose]

sauth update -name arg [-newsubj arg] [-san arg] [-type arg] [-days arg] [-active yes|no] [-verbose]


Updates an existing user entry with new details.

The user is identified using their subject distinguished name or name. The other arguments are used to specify new user settings.

Examples:

sauth update -subj "C=AU,O=Acme Inc,CN=John" -newsubj "C=AU,O=New Acme Inc,CN=John Doe" -san "john@newacme.com"

sauth update -name "John Doe" -active no

delete

sauth delete -subj arg [-verbose]

sauth delete -name arg [-verbose]


Deletes the specified user, including all certificate records and backup identity files.

Examples:

sauth delete -subj "C=AU,O=Acme Inc,CN=John"

sauth delete -name "John Doe"

list

sauth list [-active yes|no] [-verbose]


Prints the subject distinguished names of users to stdout.

Each user is listed on a separate line. These values can each be used as a -subj argument parameter to identify the user for other commands.

By default, all users are listed. The list can be restricted to active or inactive users by specifying -active yes|no.

Additional fields are shown if the -verbose argument is used.

Examples:

sauth user list

sauth user list -active yes

crl

sauth crl [-passin arg] [-verbose] [-stdout]


Generates a new CRL.

The output directory and other settings are retrieved from Options/Preferences. If the CRL file already exists, it will be overwritten.

Example:

sauth crl -passin "env:CA_PASSWORD"

csr

sauth csr -in file [-type arg] [-days arg] [-passin arg] [-verbose] [-stdout]


Processes a certificate signing request file to generate a new certificate.

A new user is generated if required to hold the new certificate record. All subject distinguished name parameters are included in the new certificate. Extension requests are included if -type is not specified.

Examples:

sauth csr -in csr.txt

sauth csr -in csr.txt -type "General Purpose" -days 365 -passin "env:CA_PASSWORD"

file

sauth file -in file [-passin arg] [-verbose] [-stdout]


Processes multiple commands that are contained in a text file. Each line in the file is processed as a separate command. This is more efficient than calling the application multiple times because it avoids JVM startup and shutdown times.

Comments can be included in the file using the # character. Any -passin or -verbose command arguments that might exist in the file are ignored, since they are overwritten by the respective file command arguments.

Example:

sauth file -in commands.txt -passin "env:CA_PASSWORD" -verbose

where commands.txt contains:

# create new user
create -subj "C=AU,O=Acme Inc,CN=John Doe" -san "john@nowhere.com"
# generate certificate for new user
cert -name "John Doe"
# issue an updated CRL
crl

help

sauth help


Displays this help information.

Example:

sauth help

version

sauth version [-verbose]


Displays version information.

Example:

sauth version -verbose

Command line arguments

-name arg The user's name. This is the CN component of the subject distinguished name.
-subj arg The user's subject distinguished name. The argument must be formatted using the X.500 standard, with zero or one values for C, O, OU and CN (in that order) elements only, e.g. -subj "C=AU,O=Acme Inc,CN=John Doe"
-newsubj arg The new subject distinguished name. Used to update user details. The same rules apply for a valid argument as for -subj.
-san arg   The user's subject alternative name. This is usually their email address, but may also be used to hold a DNS name or other value.
-type arg The name of the certificate type to use.
-days arg The certificate validity period in days.
-active yes|no Whether or not a user is marked as active.
-in file The input file. The file may be specified using an absolute or relative path, however relative paths are relative to the location of the sauth script.
-passin arg Used to specify the CA password. A number of formats are supported for arg:
pass:password The actual password is password. Since the password is visible to utilities (like ps under Unix) this form provides minimal security.
env:var Obtain the password from the environment variable var. Since the environment of other processes is visible on certain platforms (e.g. ps under certain Unix OSes) this option should be used with caution.
stdin Read the password from standard input. This is the default behaviour and is the most secure option.
-passout arg Specifies the password for new user identity files. See -passin for details of valid arg values. A randomly generated password is used if this argument is not provided.
-verbose Prints details about the operation being performed.
-stdout Causes any new identities, certificates or CRLs to be printed to stdout using PEM format, instead of creating new files in the output directory.

Return codes

0 Success
1 Unknown command
2 Invalid argument
3 Unable to complete command
4 Bad configuration

Web application interface

The Web application (servlet) interface can be used with a servlet container, like Apache Tomcat, to integrate SimpleAuthority with third party software for automating certificate operations. This interface supports all of the CLI commands listed above.

To get started:

  1. Install Apache Tomcat.
  2. (Windows and Linux) Update the Tomcat Java security policy files to enable unlimited strength cryptography.
  3. Copy the SimpleAuthority.war file to the Tomcat webapps/ directory.
  4. Start Tomcat.
  5. Open your browser at http://localhost:8080/SimpleAuthority/

Note that the CA password can be specified in the SimpleAuthority.war deployment descriptor (web.xml) file.

Please contact us if you get stuck.