| 1 | =pod
|
|---|
| 2 |
|
|---|
| 3 | =head1 NAME
|
|---|
| 4 |
|
|---|
| 5 | CA.pl - friendlier interface for OpenSSL certificate programs
|
|---|
| 6 |
|
|---|
| 7 | =head1 SYNOPSIS
|
|---|
| 8 |
|
|---|
| 9 | B<CA.pl>
|
|---|
| 10 | B<-?> |
|
|---|
| 11 | B<-h> |
|
|---|
| 12 | B<-help>
|
|---|
| 13 |
|
|---|
| 14 | B<CA.pl>
|
|---|
| 15 | B<-newcert> |
|
|---|
| 16 | B<-newreq> |
|
|---|
| 17 | B<-newreq-nodes> |
|
|---|
| 18 | B<-xsign> |
|
|---|
| 19 | B<-sign> |
|
|---|
| 20 | B<-signCA> |
|
|---|
| 21 | B<-signcert> |
|
|---|
| 22 | B<-crl> |
|
|---|
| 23 | B<-newca>
|
|---|
| 24 | [B<-extra-I<cmd>> I<parameter>]
|
|---|
| 25 |
|
|---|
| 26 | B<CA.pl> B<-pkcs12> [I<certname>]
|
|---|
| 27 |
|
|---|
| 28 | B<CA.pl> B<-verify> I<certfile> ...
|
|---|
| 29 |
|
|---|
| 30 | B<CA.pl> B<-revoke> I<certfile> [I<reason>]
|
|---|
| 31 |
|
|---|
| 32 | =head1 DESCRIPTION
|
|---|
| 33 |
|
|---|
| 34 | The B<CA.pl> script is a perl script that supplies the relevant command line
|
|---|
| 35 | arguments to the L<openssl(1)> command for some common certificate operations.
|
|---|
| 36 | It is intended to simplify the process of certificate creation and management
|
|---|
| 37 | by the use of some simple options.
|
|---|
| 38 |
|
|---|
| 39 | The script is intended as a simple front end for the L<openssl(1)> program for
|
|---|
| 40 | use by a beginner. Its behaviour isn't always what is wanted. For more control
|
|---|
| 41 | over the behaviour of the certificate commands call the L<openssl(1)> command
|
|---|
| 42 | directly.
|
|---|
| 43 |
|
|---|
| 44 | Most of the filenames mentioned below can be modified by editing the
|
|---|
| 45 | B<CA.pl> script.
|
|---|
| 46 |
|
|---|
| 47 | Under some environments it may not be possible to run the B<CA.pl> script
|
|---|
| 48 | directly (for example Win32) and the default configuration file location may
|
|---|
| 49 | be wrong. In this case the command:
|
|---|
| 50 |
|
|---|
| 51 | perl -S CA.pl
|
|---|
| 52 |
|
|---|
| 53 | can be used and the B<OPENSSL_CONF> environment variable can be set to point to
|
|---|
| 54 | the correct path of the configuration file.
|
|---|
| 55 |
|
|---|
| 56 | =head1 OPTIONS
|
|---|
| 57 |
|
|---|
| 58 | =over 4
|
|---|
| 59 |
|
|---|
| 60 | =item B<-?>, B<-h>, B<-help>
|
|---|
| 61 |
|
|---|
| 62 | Prints a usage message.
|
|---|
| 63 |
|
|---|
| 64 | =item B<-newcert>
|
|---|
| 65 |
|
|---|
| 66 | Creates a new self signed certificate. The private key is written to the file
|
|---|
| 67 | F<newkey.pem> and the request written to the file F<newreq.pem>.
|
|---|
| 68 | Invokes L<openssl-req(1)>.
|
|---|
| 69 |
|
|---|
| 70 | =item B<-newreq>
|
|---|
| 71 |
|
|---|
| 72 | Creates a new certificate request. The private key is written to the file
|
|---|
| 73 | F<newkey.pem> and the request written to the file F<newreq.pem>.
|
|---|
| 74 | Executes L<openssl-req(1)> under the hood.
|
|---|
| 75 |
|
|---|
| 76 | =item B<-newreq-nodes>
|
|---|
| 77 |
|
|---|
| 78 | Is like B<-newreq> except that the private key will not be encrypted.
|
|---|
| 79 | Uses L<openssl-req(1)>.
|
|---|
| 80 |
|
|---|
| 81 | =item B<-newca>
|
|---|
| 82 |
|
|---|
| 83 | Creates a new CA hierarchy for use with the B<ca> program (or the B<-signcert>
|
|---|
| 84 | and B<-xsign> options). The user is prompted to enter the filename of the CA
|
|---|
| 85 | certificates (which should also contain the private key) or by hitting ENTER
|
|---|
| 86 | details of the CA will be prompted for. The relevant files and directories
|
|---|
| 87 | are created in a directory called F<demoCA> in the current directory.
|
|---|
| 88 | Uses L<openssl-req(1)> and L<openssl-ca(1)>.
|
|---|
| 89 |
|
|---|
| 90 | If the F<demoCA> directory already exists then the B<-newca> command will not
|
|---|
| 91 | overwrite it and will do nothing. This can happen if a previous call using
|
|---|
| 92 | the B<-newca> option terminated abnormally. To get the correct behaviour
|
|---|
| 93 | delete the directory if it already exists.
|
|---|
| 94 |
|
|---|
| 95 | =item B<-pkcs12>
|
|---|
| 96 |
|
|---|
| 97 | Create a PKCS#12 file containing the user certificate, private key and CA
|
|---|
| 98 | certificate. It expects the user certificate and private key to be in the
|
|---|
| 99 | file F<newcert.pem> and the CA certificate to be in the file F<demoCA/cacert.pem>,
|
|---|
| 100 | it creates a file F<newcert.p12>. This command can thus be called after the
|
|---|
| 101 | B<-sign> option. The PKCS#12 file can be imported directly into a browser.
|
|---|
| 102 | If there is an additional argument on the command line it will be used as the
|
|---|
| 103 | "friendly name" for the certificate (which is typically displayed in the browser
|
|---|
| 104 | list box), otherwise the name "My Certificate" is used.
|
|---|
| 105 | Delegates work to L<openssl-pkcs12(1)>.
|
|---|
| 106 |
|
|---|
| 107 | =item B<-sign>, B<-signcert>, B<-xsign>
|
|---|
| 108 |
|
|---|
| 109 | Calls the L<openssl-ca(1)> command to sign a certificate request. It expects the
|
|---|
| 110 | request to be in the file F<newreq.pem>. The new certificate is written to the
|
|---|
| 111 | file F<newcert.pem> except in the case of the B<-xsign> option when it is
|
|---|
| 112 | written to standard output.
|
|---|
| 113 |
|
|---|
| 114 | =item B<-signCA>
|
|---|
| 115 |
|
|---|
| 116 | This option is the same as the B<-sign> option except it uses the
|
|---|
| 117 | configuration file section B<v3_ca> and so makes the signed request a
|
|---|
| 118 | valid CA certificate. This is useful when creating intermediate CA from
|
|---|
| 119 | a root CA. Extra params are passed to L<openssl-ca(1)>.
|
|---|
| 120 |
|
|---|
| 121 | =item B<-signcert>
|
|---|
| 122 |
|
|---|
| 123 | This option is the same as B<-sign> except it expects a self signed certificate
|
|---|
| 124 | to be present in the file F<newreq.pem>.
|
|---|
| 125 | Extra params are passed to L<openssl-x509(1)> and L<openssl-ca(1)>.
|
|---|
| 126 |
|
|---|
| 127 | =item B<-crl>
|
|---|
| 128 |
|
|---|
| 129 | Generate a CRL. Executes L<openssl-ca(1)>.
|
|---|
| 130 |
|
|---|
| 131 | =item B<-revoke> I<certfile> [I<reason>]
|
|---|
| 132 |
|
|---|
| 133 | Revoke the certificate contained in the specified B<certfile>. An optional
|
|---|
| 134 | reason may be specified, and must be one of: B<unspecified>,
|
|---|
| 135 | B<keyCompromise>, B<CACompromise>, B<affiliationChanged>, B<superseded>,
|
|---|
| 136 | B<cessationOfOperation>, B<certificateHold>, or B<removeFromCRL>.
|
|---|
| 137 | Leverages L<openssl-ca(1)>.
|
|---|
| 138 |
|
|---|
| 139 | =item B<-verify>
|
|---|
| 140 |
|
|---|
| 141 | Verifies certificates against the CA certificate for F<demoCA>. If no
|
|---|
| 142 | certificates are specified on the command line it tries to verify the file
|
|---|
| 143 | F<newcert.pem>. Invokes L<openssl-verify(1)>.
|
|---|
| 144 |
|
|---|
| 145 | =item B<-extra-I<cmd>> I<parameter>
|
|---|
| 146 |
|
|---|
| 147 | For each option B<extra-I<cmd>>, pass I<parameter> to the L<openssl(1)>
|
|---|
| 148 | sub-command with the same name as I<cmd>, if that sub-command is invoked.
|
|---|
| 149 | For example, if L<openssl-req(1)> is invoked, the I<parameter> given with
|
|---|
| 150 | B<-extra-req> will be passed to it.
|
|---|
| 151 | For multi-word parameters, either repeat the option or quote the I<parameters>
|
|---|
| 152 | so it looks like one word to your shell.
|
|---|
| 153 | See the individual command documentation for more information.
|
|---|
| 154 |
|
|---|
| 155 | =back
|
|---|
| 156 |
|
|---|
| 157 | =head1 EXAMPLES
|
|---|
| 158 |
|
|---|
| 159 | Create a CA hierarchy:
|
|---|
| 160 |
|
|---|
| 161 | CA.pl -newca
|
|---|
| 162 |
|
|---|
| 163 | Complete certificate creation example: create a CA, create a request, sign
|
|---|
| 164 | the request and finally create a PKCS#12 file containing it.
|
|---|
| 165 |
|
|---|
| 166 | CA.pl -newca
|
|---|
| 167 | CA.pl -newreq
|
|---|
| 168 | CA.pl -sign
|
|---|
| 169 | CA.pl -pkcs12 "My Test Certificate"
|
|---|
| 170 |
|
|---|
| 171 | =head1 ENVIRONMENT
|
|---|
| 172 |
|
|---|
| 173 | The environment variable B<OPENSSL> may be used to specify the name of
|
|---|
| 174 | the OpenSSL program. It can be a full pathname, or a relative one.
|
|---|
| 175 |
|
|---|
| 176 | The environment variable B<OPENSSL_CONFIG> may be used to specify a
|
|---|
| 177 | configuration option and value to the B<req> and B<ca> commands invoked by
|
|---|
| 178 | this script. It's value should be the option and pathname, as in
|
|---|
| 179 | C<-config /path/to/conf-file>.
|
|---|
| 180 |
|
|---|
| 181 | =head1 SEE ALSO
|
|---|
| 182 |
|
|---|
| 183 | L<openssl(1)>,
|
|---|
| 184 | L<openssl-x509(1)>,
|
|---|
| 185 | L<openssl-ca(1)>,
|
|---|
| 186 | L<openssl-req(1)>,
|
|---|
| 187 | L<openssl-pkcs12(1)>,
|
|---|
| 188 | L<config(5)>
|
|---|
| 189 |
|
|---|
| 190 | =head1 COPYRIGHT
|
|---|
| 191 |
|
|---|
| 192 | Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.
|
|---|
| 193 |
|
|---|
| 194 | Licensed under the Apache License 2.0 (the "License"). You may not use
|
|---|
| 195 | this file except in compliance with the License. You can obtain a copy
|
|---|
| 196 | in the file LICENSE in the source distribution or at
|
|---|
| 197 | L<https://www.openssl.org/source/license.html>.
|
|---|
| 198 |
|
|---|
| 199 | =cut
|
|---|
