Configuration Files The Basics

23

Chapter 2. Command-Line Interface

OpenSSL is primarily a library that is used by developers to include support for strong cryptography in their programs, but it is also a tool that provides access to much of its functionality from the command line. The command-line tool makes it easy to perform common operations, such as computing the MD5 hash of a files contents. Whats more, the command-line tool provides the ability to access much of OpenSSLs higher-level functionality from shell scripts on Unix or batch files on Windows. It also provides a simple interface for languages that do not have native SSL bindings, but can run shell commands. Theres no question that the command-line tool can seem quite complex to the uninitiated. It sports a large set of commands, and even larger sets of options that can be used to further refine and control those commands. OpenSSL does come with some documentation that covers most of the available commands and options supported by the command-line tool, but even that documentation can seem intimidating. Indeed, when youre trying to discover the magical incantation to create a self-signed certificate, the documentation provided with OpenSSL does not provide an intuitive way to go about finding that information, even though it is in fact buried in there. This chapter contains an overview of the command-line tool, providing some basic background information that will help make some sense of how the tools command structure is organized. Well also provide a high-level overview of how to accomplish many common tasks, including using message digests, symmetric ciphers, and public key cryptography. The Appendix contains a reference for the commands that the command-line tool supports. We will refer to the command-line tool throughout this book, and, in some instances, we also provide examples that are more complex than what weve included in this chapter. In particular, Chapter 3 makes extensive use of the command-line tool.

2.1 The Basics

The command-line tool executable is aptly named openssl on Unix, and openssl.exe on Windows. It has two modes of operation: interactive and batch. When the program is started without any options, it will enter interactive mode. When operating in interactive mode, a prompt is displayed indicating that it is ready to process your command. After each command is completed, the prompt is redisplayed, and its once again ready to process another command. The program can be exited by simply issuing the quit command. Commands entered in interactive mode are handled in precisely the same manner as if youd entered them from the command line in batch mode; the only difference is that you dont need to type openssl before each command. Well normally operate the tool in batch mode in our examples, but if you feel more comfortable using the interactive mode, thats fine. The first part of a command is the name of the command itself. Its followed by any options that you wish to specify, each one separated by a space. Options normally begin with a hyphen and often require a parameter of their own, in which case the parameter is placed after a space. Unless indicated otherwise, the order in which you specify options is not significant. There are only a small number of cases in which the order is significant, usually because a specific option must appear on the command line as the last option specified.

2.1.1 Configuration Files

24 The command-line tool provides a large number of options for each of its many commands. Remembering the option names, their defaults if theyre not specified, and even to include them with a command to obtain the desired result can be difficult, if not downright frustrating at times. The task of managing options is made considerably simpler using configuration files. OpenSSL includes a default configuration file that is normally used unless an alternate one is specified. The settings in the default configuration are all quite reasonable, but it can often be useful to replace them with settings that are better tailored to your own needs. The location of the default configuration file varies greatly, depending on the operating system that youre using and how OpenSSL was built and installed. So, unfortunately, we cant point you to any one specific location to find it. Although it is not at all intuitive, the command-line tool will tell you where the default configuration file is located if you issue the ca command without any options. Any errors that are issued due to the lack of options may be safely ignored. Unfortunately, only three of the many commands supported by the command-line tool make any use of the configuration file. On the bright side, the three commands that do use it are perhaps the most complex of all of the supported commands, and accept the greatest number of options to control their behavior. The commands that do support the configuration file are ca , req , and x509 we discuss these commands below. An OpenSSL configuration file is organized in sections. Each section contains a set of keys, and each key has an associated value. Sections and keys are both named and case-sensitive. A configuration file is parsed from top to bottom with sections delimited by a line containing the name of the section surrounded by square brackets. The other lines contain key and value pairs that belong to the most recently parsed section delimiter. In addition, an optional global section that is unnamed occurs before the first named section in the file. Keys are separated from their associated value by an equals sign =. For the most part, whitespace is insignificant. Comments may begin anywhere on a line with a hash mark , and they end at the end of the line on which they begin. Key and section names may not contain whitespace, but they may be surrounded by it. Leading and trailing whitespace is stripped from a value, but any whitespace in the middle is significant. Example 2-1 shows an excerpt from the default OpenSSL configuration file. Example 2-1. An excerpt from the default OpenSSL configuration file [ ca ] default_ca = CA_default The default ca section [ CA_default ] dir = .demoCA Where everything is kept certs = dircerts Where the issued certs are kept crl_dir = dircrl Where the issued crl are kept database = dirindex.txt database index file new_certs_dir = dirnewcerts default place for new certs certificate = dircacert.pem The CA certificate serial = dirserial The current serial number crl = dircrl.pem The current CRL private_key = dirprivatecakey.pem The private key RANDFILE = dirprivate.rand private random number file x509_extensions = usr_cert The extentions to add to the cert 25 Extensions to add to a CRL. Note: Netscape communicator chokes on V2 CRLs so this is commented out by default to leave a V1 CRL. crl_extensions = crl_ext default_days = 365 how long to certify for default_crl_days= 30 how long before next CRL default_md = md5 which md to use preserve = no keep passed DN ordering A few difference way of specifying how similar the request should look For type CA, the listed attributes must be the same, and the optional and supplied fields are just that :- policy = policy_match In the example, youll notice the use of dir . Used in a value, a key name preceded by a dollar sign is known as a macro, and is replaced with the value for that key. Only macros using keys that are defined within the same section or in the global section will be expanded. Additionally, the key must be defined before you use it as a macro in a value, because the macro is expanded as the configuration file parses rather than when the value is used. Macros are particularly useful when you have a number of values referencing the same path in a filename. Although only a few commands currently make any use of a configuration file, other commands may be modified in the future to take advantage of them. Each command that currently uses the configuration file reads its base configuration information from a section that shares the name of the command. Other sections that are not named after a command may exist, and quite frequently, they do. Many keys values are interpreted as the name of a section to use for finding more keys. Well see frequent examples of this as we examine the commands that do use the configuration file in detail.

2.2 Message Digest Algorithms