]>
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>] | |
16 | [B<-newca>] | |
17 | [B<-xsign>] | |
18 | [B<-sign>] | |
19 | [B<-signreq>] | |
20 | [B<-signcert>] | |
21 | [B<-verify>] | |
22 | [B<files>] | |
23 | ||
24 | =head1 DESCRIPTION | |
25 | ||
26 | The B<CA.pl> script is a perl script that supplies the relevant command line | |
27 | arguments to the B<openssl> command for some common certificate operations. | |
28 | It is intended to simplify the process of certificate creation and management | |
29 | by the use of some simple options. | |
30 | ||
31 | =head1 COMMAND OPTIONS | |
32 | ||
33 | =over 4 | |
34 | ||
35 | =item B<?>, B<-h>, B<-help> | |
36 | ||
37 | prints a usage message. | |
38 | ||
39 | =item B<-newcert> | |
40 | ||
41 | creates a new self signed certificate. The private key and certificate are | |
42 | written to the file "newreq.pem". | |
43 | ||
44 | =item B<-newreq> | |
45 | ||
46 | creates a new certificate request. The private key and request are | |
47 | written to the file "newreq.pem". | |
48 | ||
49 | =item B<-newca> | |
50 | ||
51 | creates a new CA hierarchy for use with the B<ca> program (or the B<-signcert> | |
52 | and B<-xsign> options). The user is prompted to enter the filename of the CA | |
53 | certificates (which should also contain the private key) or by hitting ENTER | |
54 | details of the CA will be prompted for. The relevant files and directories | |
55 | are created in a directory called "demoCA" in the current directory. | |
56 | ||
57 | =item B<-pkcs12> | |
58 | ||
59 | create a PKCS#12 file containing the user certificate, private key and CA | |
60 | certificate. It expects the user certificate and private key to be in the | |
61 | file "newcert.pem" and the CA certificate to be in the file demoCA/cacert.pem, | |
62 | it creates a file "newcert.p12". This command can thus be called after the | |
63 | B<-sign> option. The PKCS#12 file can be imported directly into a browser. | |
64 | If there is an additional argument on the command line it will be used as the | |
65 | "friendly name" for the certificate (which is typically displayed in the browser | |
66 | list box), otherwise the name "My Certifictate" is used. | |
67 | ||
68 | =item B<-sign>, B<-signreq>, B<-xsign> | |
69 | ||
70 | calls the B<ca> program to sign a certificate request. It expects the request | |
71 | to be in the file "newreq.pem". The new certificate is written to the file | |
72 | "newcert.pem" except in the case of the B<-xcert> option when it is written | |
73 | to standard output. | |
74 | ||
75 | =item B<-signcert> | |
76 | ||
77 | this option is the same as B<-sign> except it expects a self signed certificate | |
78 | to be present in the file "newreq.pem". | |
79 | ||
80 | =item B<-verify> | |
81 | ||
82 | verifies certificates against the CA certificate for "demoCA". If no certificates | |
83 | are specified on the command line it tries to verify the file "newcert.pem". | |
84 | ||
85 | =item B<files> | |
86 | ||
87 | one or more optional certificate file names for use with the B<-verify> command. | |
88 | ||
89 | =back | |
90 | ||
91 | =head1 EXAMPLES | |
92 | ||
93 | Create a CA hierarchy: | |
94 | ||
95 | CA.pl -newca | |
96 | ||
97 | Complete certificate creation example: create a CA, create a request, sign | |
98 | the request and finally create a PKCS#12 file containing it. | |
99 | ||
100 | CA.pl -newca | |
101 | CA.pl -newreq | |
102 | CA.pl -signreq | |
103 | CA.pl -pkcs12 "My Test Certificate" | |
104 | ||
105 | =head1 NOTES | |
106 | ||
107 | Most of the filenames mentioned can be modified by editing the B<CA.pl> script. | |
108 | ||
109 | If the demoCA directory already exists then the B<-newca> command will not | |
110 | overwrite it and will do nothing. This can happen if a previous call using | |
111 | the B<-newca> option terminated abnormally. To get the correct behaviour | |
112 | delete the demoCA directory if it already exists. | |
113 | ||
114 | Under some environments it may not be possible to run the B<CA.pl> script | |
115 | directly (for example Win32) and the default configuration file location may | |
116 | be wrong. In this case the command: | |
117 | ||
118 | perl -S CA.pl | |
119 | ||
120 | can be used and the B<OPENSSL_CONF> environment variable changed to point to | |
121 | the correct path of the configuration file "openssl.cnf". | |
122 | ||
123 | The script is intended as a simple front end for the B<openssl> program for use | |
124 | by a beginner. Its behaviour isn't always what is wanted. For more control over the | |
125 | behaviour of the certificate commands call the B<openssl> command directly. | |
126 | ||
127 | =head1 ENVIRONMENT VARIABLES | |
128 | ||
129 | The variable B<OPENSSL_CONF> if defined allows an alternative configuration | |
130 | file location to be specified, it should contain the full path to the | |
131 | configuration file, not just its directory. | |
132 | ||
133 | =head1 SEE ALSO | |
134 | ||
135 | L<x509(1)|x509(1)>, L<ca(1)|ca(1)>, L<req(1)|req(1)>, L<pkcs12(1)|pkcs12(1)>, L<config(1)|config(1)> | |
136 | ||
137 | =cut |