]>
Commit | Line | Data |
---|---|---|
2af9fd00 DSH |
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> | |
022696ca | 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> | |
cab33afb | 24 | [B<-extra-I<cmd>> I<parameter>] |
022696ca | 25 | |
cab33afb | 26 | B<CA.pl> B<-pkcs12> [B<-extra-pkcs12> I<parameter>] [I<certname>] |
022696ca | 27 | |
cab33afb | 28 | B<CA.pl> B<-verify> [B<-extra-verify> I<parameter>] I<certfile> ... |
022696ca | 29 | |
cab33afb | 30 | B<CA.pl> B<-revoke> [B<-extra-ca> I<parameter>] I<certfile> [I<reason>] |
2af9fd00 | 31 | |
3dfda1a6 RS |
32 | =head1 DESCRIPTION |
33 | ||
2af9fd00 | 34 | The B<CA.pl> script is a perl script that supplies the relevant command line |
35a810bb | 35 | arguments to the L<openssl(1)> command for some common certificate operations. |
2af9fd00 DSH |
36 | It is intended to simplify the process of certificate creation and management |
37 | by the use of some simple options. | |
38 | ||
cab33afb RS |
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 | ||
3dfda1a6 | 56 | =head1 OPTIONS |
2af9fd00 DSH |
57 | |
58 | =over 4 | |
59 | ||
60 | =item B<?>, B<-h>, B<-help> | |
61 | ||
c4de074e | 62 | Prints a usage message. |
2af9fd00 DSH |
63 | |
64 | =item B<-newcert> | |
65 | ||
c4de074e | 66 | Creates a new self signed certificate. The private key is written to the file |
1948394d | 67 | F<newkey.pem> and the request written to the file F<newreq.pem>. |
8bc93d2f | 68 | Invokes L<openssl-req(1)>. |
2af9fd00 DSH |
69 | |
70 | =item B<-newreq> | |
71 | ||
c4de074e | 72 | Creates a new certificate request. The private key is written to the file |
1948394d | 73 | F<newkey.pem> and the request written to the file F<newreq.pem>. |
8bc93d2f | 74 | Executes L<openssl-req(1)> under the hood. |
2af9fd00 | 75 | |
9b623183 | 76 | =item B<-newreq-nodes> |
d199858e | 77 | |
c4de074e | 78 | Is like B<-newreq> except that the private key will not be encrypted. |
8bc93d2f | 79 | Uses L<openssl-req(1)>. |
d199858e | 80 | |
2af9fd00 DSH |
81 | =item B<-newca> |
82 | ||
c4de074e | 83 | Creates a new CA hierarchy for use with the B<ca> program (or the B<-signcert> |
2af9fd00 DSH |
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 | |
1948394d | 87 | are created in a directory called F<demoCA> in the current directory. |
8bc93d2f | 88 | Uses L<openssl-req(1)> and L<openssl-ca(1)>. |
2af9fd00 | 89 | |
cab33afb RS |
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 | ||
2af9fd00 DSH |
95 | =item B<-pkcs12> |
96 | ||
c4de074e | 97 | Create a PKCS#12 file containing the user certificate, private key and CA |
2af9fd00 | 98 | certificate. It expects the user certificate and private key to be in the |
1948394d RL |
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 | |
2af9fd00 DSH |
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 | |
657e60fa | 104 | list box), otherwise the name "My Certificate" is used. |
8bc93d2f | 105 | Delegates work to L<openssl-pkcs12(1)>. |
2af9fd00 | 106 | |
022696ca | 107 | =item B<-sign>, B<-signcert>, B<-xsign> |
2af9fd00 | 108 | |
35a810bb | 109 | Calls the L<openssl-ca(1)> command to sign a certificate request. It expects the |
1948394d RL |
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 | |
8bc93d2f | 112 | written to standard output. |
d428bf8c DSH |
113 | |
114 | =item B<-signCA> | |
115 | ||
e1c6f762 | 116 | This option is the same as the B<-sign> option except it uses the |
c4de074e P |
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 | |
8bc93d2f | 119 | a root CA. Extra params are passed to L<openssl-ca(1)>. |
d428bf8c | 120 | |
2af9fd00 DSH |
121 | =item B<-signcert> |
122 | ||
c4de074e | 123 | This option is the same as B<-sign> except it expects a self signed certificate |
1948394d | 124 | to be present in the file F<newreq.pem>. |
8bc93d2f | 125 | Extra params are passed to L<openssl-x509(1)> and L<openssl-ca(1)>. |
2af9fd00 | 126 | |
e8185aea RS |
127 | =item B<-crl> |
128 | ||
8bc93d2f | 129 | Generate a CRL. Executes L<openssl-ca(1)>. |
e8185aea | 130 | |
e8769719 | 131 | =item B<-revoke> I<certfile> [I<reason>] |
e8185aea | 132 | |
c4de074e | 133 | Revoke the certificate contained in the specified B<certfile>. An optional |
e8185aea RS |
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>. | |
8bc93d2f | 137 | Leverages L<openssl-ca(1)>. |
e8185aea | 138 | |
2af9fd00 DSH |
139 | =item B<-verify> |
140 | ||
1948394d | 141 | Verifies certificates against the CA certificate for F<demoCA>. If no |
c4de074e | 142 | certificates are specified on the command line it tries to verify the file |
8bc93d2f | 143 | F<newcert.pem>. Invokes L<openssl-verify(1)>. |
2af9fd00 | 144 | |
cab33afb | 145 | =item B<-extra-I<cmd>> I<parameter> |
3dfda1a6 | 146 | |
cab33afb | 147 | For each option B<extra-I<cmd>>, pass I<parameter> to the L<openssl(1)> |
b2bdfb63 | 148 | sub-command with the same name as I<cmd>, if that sub-command is invoked. |
cab33afb | 149 | For example, if L<openssl-req(1)> is invoked, the I<parameter> given with |
b2bdfb63 | 150 | B<-extra-req> will be passed to it. |
cab33afb RS |
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. | |
3dfda1a6 | 154 | |
2af9fd00 DSH |
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 | |
e1c6f762 | 168 | CA.pl -sign |
2af9fd00 DSH |
169 | CA.pl -pkcs12 "My Test Certificate" |
170 | ||
a8055c70 RS |
171 | =head1 ENVIRONMENT |
172 | ||
cab33afb RS |
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 | ||
a8055c70 RS |
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 | ||
2af9fd00 DSH |
181 | =head1 SEE ALSO |
182 | ||
b6b66573 DMSP |
183 | L<openssl(1)>, |
184 | L<openssl-x509(1)>, | |
185 | L<openssl-ca(1)>, | |
186 | L<openssl-req(1)>, | |
187 | L<openssl-pkcs12(1)>, | |
9b86974e | 188 | L<config(5)> |
2af9fd00 | 189 | |
e2f92610 RS |
190 | =head1 COPYRIGHT |
191 | ||
33388b44 | 192 | Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 193 | |
449040b4 | 194 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
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 |