scepclient: Generate uppercase transaction ID.
[strongswan.git] / src / scepclient / scepclient.8
1 .\"
2 .TH "IPSEC_SCEPCLIENT" "8" "2012-05-11" "strongSwan" ""
3 .SH "NAME"
4 ipsec scepclient \- Client for the SCEP protocol
5 .SH "SYNOPSIS"
6 .B ipsec scepclient [argument ...]
7 .sp
8 .B ipsec scepclient
9 .B \-\-help
10 .br
11 .B ipsec scepclient
12 .B \-\-version
13 .SH "DESCRIPTION"
14 .BR scepclient
15 is a client implementation of Cisco System's Simple Certificate Enrollment Protocol (SCEP) written for Linux strongSwan <http://www.strongswan.org>.
16 .BR scepclient
17 is designed to be used for certificate enrollment on machines using the OpenSource IPsec solution
18 .I strongSwan.
19 .SH "FEATURES"
20 .BR scepclient
21 implements the following features of SCEP:
22 .br
23 .IP "\-" 4
24 Automatic enrollment of client certificate using a preshared secret
25 .IP "\-" 4
26 Manual enrollment of client certificate. Offline fingerprint check required!
27 .IP "\-" 4
28 Acquisition of CA certificate(s)
29 .SH "OPTIONS"
30 .SS Basic Startup Options
31 .B \-v, \-\-version
32 .RS 4
33 Display the version of ipsec scepclient.
34 .PP
35 .RE
36 .B \-h, \-\-help
37 .RS 4
38 Display usage of ipsec scepclient.
39 .RE
40
41 .SS General Options
42 .B \-u, \-\-url \fIurl\fP
43 .RS 4
44 Full HTTP URL of the SCEP server to be used for certificate enrollment and CA certificate acquisition.
45 .RE
46 .PP
47 .B \-+, \-\-optionsfrom \fIfilename\fP
48 .RS 4
49 Reads additional options from \fIfilename\fP.
50 .RE
51 .PP
52 .B \-f, \-\-force
53 .RS 4
54 Overwrite existing output file[s].
55 .RE
56 .PP
57 .B \-q, \-\-quiet
58 .RS 4
59 Do not write log output to stderr.
60 .RE
61
62 .SS Options for CA Certificate Acquisition
63 .B \-o, \-\-out cacert[=\fIfilename\fP]
64 .RS 4
65 Output file of acquired CA certificate. If more then one CA certificate is
66 available, \fIfilename\fP is used as prefix for the resulting files (refer to
67 EXAMPLES below for details).
68 .br
69 The default \fIfilename\fP is $CONFDIR/ipsec.d/cacerts/caCert.der.
70 .RE
71
72 .SS Options For Certificate Enrollment
73 .B \-i, \-\-in \fItype\fP[=\fIfilename\fP]
74 .RS 4
75 Input file for certificate enrollment. This option can be specified multiple times to specify input files for every \fItype\fP.
76 Input files can bei either DER or PEM encoded.
77 .PP
78 Supported values for \fItype\fP:
79 .IP "\fBpkcs1\fP" 12
80 RSA private key in PKCS#1 file format. If no input of this type is specified, a RSA key gets generated.
81 .br
82 The default \fIfilename\fP is $CONFDIR/ipsec.d/private/myKey.der.
83 .IP "\fBcacert\-enc\fP" 12
84 CA certificate to encrypt the SCEP request. Has to be specified for certificate enrollment.
85 .br
86 The default \fIfilename\fP is $CONFDIR/ipsec.d/cacerts/caCert.der.
87 .IP "\fBcacert\-sig\fP" 12
88 CA certificate to check signature of SCEP reply. Has to be specified for certificate enrollment.
89 .br
90 The default \fIfilename\fP is $CONFDIR/ipsec.d/cacerts/caCert.der.
91 .RE
92 .PP
93 .B \-k, \-\-keylength \fIbits\fP
94 .RS 4
95 sets the key length for RSA key generation. The default length for a generated rsa key is set to 2048 bit.
96 .RE
97 .PP
98 .B \-D, \-\-days \fIdays\fP
99 .RS 4
100 Validity of the self-signed X.509 certificate in days. The default is 1825 days (5 years).
101 .RE
102 .PP
103 .B \-S, \-\-startdate \fIYYMMDDHHMMSS\fPZ
104 .RS 4
105 defines the \fBnotBefore\fP date when the X.509 certificate  becomes  valid.
106 The  date has the format \fIYYMMDDHHMMSS\fP and  must be specified in UTC (Zulu time).
107 If the \fB--startdate\fP option is not specified then the current date is taken as a default.
108 .RE
109 .PP
110 .B \-E, \-\-enddate \fIYYMMDDHHMMSS\fPZ
111 .RS 4
112 defines the \fBnotAfter\fP date when the X.509 certificate will expire.
113 The date has the format \fIYYMMDDHHMMSS\fP and must be specified in UTC (Zulu time).
114 If the \fB--enddate\fP option is not specified then the default \fBnotAfter\fP value is computed by
115 adding the validity interval specified by the \fB--days\fP option to the \fBnotBefore\fP date.
116 .RE
117 .PP
118 .B \-d, \-\-dn \fIdn\fP
119 .RS 4
120 Distinguished name as comma separated list of relative distinguished names. Use quotation marks for a distinguished name containing spaces. If the \fB\-\-dn\fP parameter is missing then the default "C=CH, O=Linux strongSwan, CN=\fIhostname\fP"
121 is used with \fIhostname\fP being the return value of the \fIgethostname\fP() function.
122 .RE
123 .PP
124 .B \-s, \-\-subjectAltName \fItype\fP=\fIvalue\fP
125 .RS 4
126 Include subjectAltName in certificate request. This option can be specified multiple times to specify a subjectAltName
127 for every \fItype\fP.
128 .PP
129 Supported values for \fItype\fP:
130 .IP "\fBemail\fP" 12
131 subjectAltName is a email address.
132 .IP "\fBdns\fP" 12
133 subjectAltName is a hostname.
134 .IP "\fBip\fP" 12
135 subjectAltName is a IP address.
136 .RE
137 .PP
138 .B \-p, \-\-password \fIpw\fP
139 .RS 4
140 Password to be included as a \fIchallenge password\fP in SCEP request.
141 If \fIpw\fP is \fB%prompt\fP', the password gets prompted for on the command line.
142 .IP
143 \- In automatic mode, this password corresponds to the preshared secret for the given enrollment.
144 .IP
145 \- In manual mode, this password can be used to later revoke the corresponding certificate.
146 .RE
147 .PP
148 .B \-a, \-\-algorithm [\fItype\fP=]\fIalgo\fP
149 .RS 4
150 Change the algorithms to be used when generating and transporting (PKCS#7)
151 certificate requests (PKCS#10).
152 .PP
153 Supported values for \fItype\fP:
154 .IP "\fBenc\fP" 12
155 symmetric encryption algorithm in PKCS#7
156 .IP "\fBdgst\fP" 12
157 hash algorithm for message digest in PKCS#7
158 .IP "\fBsig\fP" 12
159 hash algorithm for the signature in PKCS#10
160 .PP
161 If \fItype\fP is not specified \fBenc\fP is assumed.
162 .PP
163 Supported values for \fIalgo\fP (\fBenc\fP):
164 .IP "\fBdes\fP" 12
165 DES-CBC encryption (key size = 56 bit). Default.
166 .IP "\fB3des\fP" 12
167 Triple DES-EDE-CBC encryption (key size = 168 bit).
168 .IP "\fBaes128\fP" 12
169 AES-CBC encryption (key size = 128 bit).
170 .IP "\fBaes192\fP" 12
171 AES-CBC encryption (key size = 192 bit).
172 .IP "\fBaes256\fP" 12
173 AES-CBC encryption (key size = 256 bit).
174 .IP "\fBcamellia128\fP" 12
175 Camellia-CBC encryption (key size = 128 bit).
176 .IP "\fBcamellia192\fP" 12
177 Camelllia-CBC encryption (key size = 192 bit).
178 .IP "\fBcamellia256\fP" 12
179 Camellia-CBC encryption (key size = 256 bit).
180 .PP
181 Supported values for \fIalgo\fP (\fBdgst\fP or \fBsig\fP):
182 .PP
183 \fBmd5\fP (default), \fBsha1\fP, \fBsha256\fP, \fBsha384\fP, \fBsha512\fP
184 .RE
185 .PP
186 .B \-o, \-\-out \fItype\fP[=\fIfilename\fP]
187 .RS 4
188 Output file for certificate enrollment. This option can be specified multiple times to specify output files for every \fItype\fP.
189 .PP
190 Supported values for \fItype\fP:
191 .IP "\fBpkcs1\fP" 12
192 RSA private key in PKCS#1 file format. If specified, the RSA key used for enrollment is stored in file \fIfilename\fP.
193 If none of the \fItypes\fP listed below are specified, \fBscepclient\fP will stop after outputting this file.
194 .br
195 The default \fIfilename\fP is $CONFDIR/ipsec.d/private/myKey.der.
196 .IP "\fBpkcs10\fP" 12
197 PKCS#10 certificate request. If specified, the PKCS#10 request used or certificate enrollment is stored in file \fIfilename\fP.
198 If none of the \fItypes\fP listed below are specified, \fBscepclient\fP will stop after outputting this file.
199 .br
200 The default \fIfilename\fP is $CONFDIR/ipsec.d/req/myReq.der.
201 .IP "\fBpkcs7\fP" 12
202 PKCS#7 SCEP request as it is sent using HTTP to the SCEP server. If specified, this SCEP request is stored in file \fIfilename\fP.
203 If none of \fItypes\fP listed below is not specified, \fBscepclient\fP will stop after outputting this file.
204 .br
205 The default \fIfilename\fP is $CONFDIR/ipsec.d/req/pkcs7.der.
206 .IP "\fBcert-self\fP" 12
207 Self-signed certificate. If specified the self-signed certificate is stored in file \fIfilename\fP.
208 .br
209 The default \fIfilename\fP is $CONFDIR/ipsec.d/certs/selfCert.der.
210 .IP "\fBcert\fP" 12
211 Enrolled certificate. This \fItype\fP must be specified for certificate enrollment.
212 The enrolled certificate is stored in file \fIfilename\fP.
213 .br
214 The default \fIfilename\fP is set to $CONFDIR/ipsec.d/certs/myCert.der.
215 .RE
216 .PP
217 .B \-m, \-\-method \fImethod\fP
218 .RS 4
219 Change HTTP request method for certificate enrollment. Default is \fBget\fP.
220 .PP
221 Supported values for \fImethod\fP:
222 .IP "\fBpost\fP" 12
223 Certificate enrollment using HTTP POST. Must be supported by the given SCEP server.
224 .IP "\fBget\fP" 12
225 Certificate enrollment using HTTP GET.
226 .RE
227 .PP
228 .B \-t, \-\-interval \fIseconds\fP
229 .RS 4
230 Set interval time in seconds when polling in manual mode.
231 The default interval is set to 5 seconds.
232 .RE
233 .PP
234 .B \-x, \-\-maxpolltime \fIseconds\fP
235 .RS 4
236 Set max time in seconds to poll in manual mode.
237 The default max time is set to unlimited.
238 .RE
239
240 .SS Debugging Output Options:
241 .B \-l, \-\-debug \fIlevel\fP
242 .RS 4
243 Changes the log level (-1..4, default: 1)
244 .RE
245 .SH "EXAMPLES"
246 .B  ipsec scepclient \-\-out caCert \-\-url http://scepserver/cgi\-bin/pkiclient.exe \-f
247 .RS 4
248 Acquire CA certificate from SCEP server and store it in the default file $CONFDIR/ipsec.d/cacerts/caCert.der.
249 If more then one CA certificate is returned, store them in files named
250 \'caCert\-1.der\', \'caCert\-2.der\', etc.
251 If an RA certificate is returned, store it in a file named \'caCert\-ra.der\'.
252 If more than one RA certificate is returned, store them in files named
253 \'caCert\-ra\-1.der\', \'caCert\-ra\-2.der\', etc.
254 .RE
255 .PP
256 .B  ipsec scepclient \-\-out pkcs1=joeKey.der \-k 1024
257 .RS 4
258 Generate RSA private key with key length of 1024 bit and store it in file joeKey.der.
259 .RE
260 .PP
261 .B  ipsec scepclient \-\-in pkcs1=joeKey.der \-\-out pkcs10=joeReq.der \e
262 .br
263 .B \-\-dn \*(rqC=AT, CN=John Doe\*(rq \-s email=john@doe.com \-p mypassword
264 .RS 4
265 Generate a PKCS#10 request and store it in file joeReq.der. Use the RSA private key joeKey.der
266 created earlier to sign the PKCS#10\-Request. In addition to the distinguished name include a
267 email\-subjectAltName and a challenge password in the request.
268 .RE
269 .PP
270 .B  ipsec scepclient \-\-out pkcs1=joeKey.der \-\-out cert==joeCert.der \e
271 .br
272 .B \-\-dn \*(rqC=CH, CN=John Doe\*(rq \-k 512 \-p 5xH2pnT7wq \e
273 .br
274 .B \-\-url http://scep.hsr.ch/cgi\-bin/pkiclient.exe \e
275 .br
276 .B \-\-in cacert\-enc=caCert.der \-\-in cacert\-sig=caCert.der
277 .RS 4
278 Generate a new RSA key for the request and store it in joeKey.der. Then enroll a certificate and store as joeCert.der.
279 The challenge password is '5xH2pnT7wq'. The encryption and signature check has to be made with the same CA certificate
280 caCert.der.
281 .RE
282
283
284 .SH "BUGS"
285 \fB\-\-optionsfrom\fP seems to have parsing problems reading option files containing strings in quotation marks.
286 .SH "COPYRIGHT"
287 Copyright (C) 2005 Jan Hutter, Martin Willi
288 .br
289 Hochschule fuer Technik Rapperswil
290 .PP
291 This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
292 .PP
293 This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.