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