nonceg: Insert id mapping when allocating nonce
[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 be 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 "\fBpkcs10\fP" 12
84 PKCS#10 certificate request to be used in the SCEP request. If no input of this type is specified, a request is generated.
85 .br
86 The default \fIfilename\fP is $CONFDIR/ipsec.d/req/myReq.der.
87 .IP "\fBcacert\-enc\fP" 12
88 CA certificate to encrypt the SCEP request. Has to be specified for certificate enrollment.
89 .br
90 The default \fIfilename\fP is $CONFDIR/ipsec.d/cacerts/caCert.der.
91 .IP "\fBcacert\-sig\fP" 12
92 CA certificate to check signature of SCEP reply. Has to be specified for certificate enrollment.
93 .br
94 The default \fIfilename\fP is $CONFDIR/ipsec.d/cacerts/caCert.der.
95 .IP "\fBcert-self\fP" 12
96 Certificate to be used in the SCEP request.  If it is not specified a
97 self-signed certificate is generated automatically.
98 .br
99 The default \fIfilename\fP is $CONFDIR/ipsec.d/certs/selfCert.der.
100 .RE
101 .PP
102 .B \-k, \-\-keylength \fIbits\fP
103 .RS 4
104 sets the key length for RSA key generation. The default length for a generated rsa key is set to 2048 bit.
105 .RE
106 .PP
107 .B \-D, \-\-days \fIdays\fP
108 .RS 4
109 Validity of the self-signed X.509 certificate in days. The default is 1825 days (5 years).
110 .RE
111 .PP
112 .B \-S, \-\-startdate \fIYYMMDDHHMMSS\fPZ
113 .RS 4
114 defines the \fBnotBefore\fP date when the X.509 certificate  becomes  valid.
115 The  date has the format \fIYYMMDDHHMMSS\fP and  must be specified in UTC (Zulu time).
116 If the \fB--startdate\fP option is not specified then the current date is taken as a default.
117 .RE
118 .PP
119 .B \-E, \-\-enddate \fIYYMMDDHHMMSS\fPZ
120 .RS 4
121 defines the \fBnotAfter\fP date when the X.509 certificate will expire.
122 The date has the format \fIYYMMDDHHMMSS\fP and must be specified in UTC (Zulu time).
123 If the \fB--enddate\fP option is not specified then the default \fBnotAfter\fP value is computed by
124 adding the validity interval specified by the \fB--days\fP option to the \fBnotBefore\fP date.
125 .RE
126 .PP
127 .B \-d, \-\-dn \fIdn\fP
128 .RS 4
129 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"
130 is used with \fIhostname\fP being the return value of the \fIgethostname\fP() function.
131 .RE
132 .PP
133 .B \-s, \-\-subjectAltName \fItype\fP=\fIvalue\fP
134 .RS 4
135 Include subjectAltName in certificate request. This option can be specified multiple times to specify a subjectAltName
136 for every \fItype\fP.
137 .PP
138 Supported values for \fItype\fP:
139 .IP "\fBemail\fP" 12
140 subjectAltName is a email address.
141 .IP "\fBdns\fP" 12
142 subjectAltName is a hostname.
143 .IP "\fBip\fP" 12
144 subjectAltName is a IP address.
145 .RE
146 .PP
147 .B \-p, \-\-password \fIpw\fP
148 .RS 4
149 Password to be included as a \fIchallenge password\fP in SCEP request.
150 If \fIpw\fP is \fB%prompt\fP', the password gets prompted for on the command line.
151 .IP
152 \- In automatic mode, this password corresponds to the preshared secret for the given enrollment.
153 .IP
154 \- In manual mode, this password can be used to later revoke the corresponding certificate.
155 .RE
156 .PP
157 .B \-a, \-\-algorithm [\fItype\fP=]\fIalgo\fP
158 .RS 4
159 Change the algorithms to be used when generating and transporting (PKCS#7)
160 certificate requests (PKCS#10).
161 .PP
162 Supported values for \fItype\fP:
163 .IP "\fBenc\fP" 12
164 symmetric encryption algorithm in PKCS#7
165 .IP "\fBdgst\fP" 12
166 hash algorithm for message digest in PKCS#7
167 .IP "\fBsig\fP" 12
168 hash algorithm for the signature in PKCS#10
169 .PP
170 If \fItype\fP is not specified \fBenc\fP is assumed.
171 .PP
172 Supported values for \fIalgo\fP (\fBenc\fP):
173 .IP "\fBdes\fP" 12
174 DES-CBC encryption (key size = 56 bit). Default.
175 .IP "\fB3des\fP" 12
176 Triple DES-EDE-CBC encryption (key size = 168 bit).
177 .IP "\fBaes128\fP" 12
178 AES-CBC encryption (key size = 128 bit).
179 .IP "\fBaes192\fP" 12
180 AES-CBC encryption (key size = 192 bit).
181 .IP "\fBaes256\fP" 12
182 AES-CBC encryption (key size = 256 bit).
183 .IP "\fBcamellia128\fP" 12
184 Camellia-CBC encryption (key size = 128 bit).
185 .IP "\fBcamellia192\fP" 12
186 Camelllia-CBC encryption (key size = 192 bit).
187 .IP "\fBcamellia256\fP" 12
188 Camellia-CBC encryption (key size = 256 bit).
189 .PP
190 Supported values for \fIalgo\fP (\fBdgst\fP or \fBsig\fP):
191 .PP
192 \fBmd5\fP (default), \fBsha1\fP, \fBsha256\fP, \fBsha384\fP, \fBsha512\fP
193 .RE
194 .PP
195 .B \-o, \-\-out \fItype\fP[=\fIfilename\fP]
196 .RS 4
197 Output file for certificate enrollment. This option can be specified multiple times to specify output files for every \fItype\fP.
198 .PP
199 Supported values for \fItype\fP:
200 .IP "\fBpkcs1\fP" 12
201 RSA private key in PKCS#1 file format. If specified, the RSA key used for enrollment is stored in file \fIfilename\fP.
202 If none of the \fItypes\fP listed below are specified, \fBscepclient\fP will stop after outputting this file.
203 .br
204 The default \fIfilename\fP is $CONFDIR/ipsec.d/private/myKey.der.
205 .IP "\fBpkcs10\fP" 12
206 PKCS#10 certificate request. If specified, the PKCS#10 request used or certificate enrollment is stored in file \fIfilename\fP.
207 If none of the \fItypes\fP listed below are specified, \fBscepclient\fP will stop after outputting this file.
208 .br
209 The default \fIfilename\fP is $CONFDIR/ipsec.d/req/myReq.der.
210 .IP "\fBpkcs7\fP" 12
211 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.
212 If none of \fItypes\fP listed below is not specified, \fBscepclient\fP will stop after outputting this file.
213 .br
214 The default \fIfilename\fP is $CONFDIR/ipsec.d/req/pkcs7.der.
215 .IP "\fBcert-self\fP" 12
216 Self-signed certificate. If specified the self-signed certificate is stored in file \fIfilename\fP.
217 .br
218 The default \fIfilename\fP is $CONFDIR/ipsec.d/certs/selfCert.der.
219 .IP "\fBcert\fP" 12
220 Enrolled certificate. This \fItype\fP must be specified for certificate enrollment.
221 The enrolled certificate is stored in file \fIfilename\fP.
222 .br
223 The default \fIfilename\fP is set to $CONFDIR/ipsec.d/certs/myCert.der.
224 .RE
225 .PP
226 .B \-m, \-\-method \fImethod\fP
227 .RS 4
228 Change HTTP request method for certificate enrollment. Default is \fBget\fP.
229 .PP
230 Supported values for \fImethod\fP:
231 .IP "\fBpost\fP" 12
232 Certificate enrollment using HTTP POST. Must be supported by the given SCEP server.
233 .IP "\fBget\fP" 12
234 Certificate enrollment using HTTP GET.
235 .RE
236 .PP
237 .B \-t, \-\-interval \fIseconds\fP
238 .RS 4
239 Set interval time in seconds when polling in manual mode.
240 The default interval is set to 5 seconds.
241 .RE
242 .PP
243 .B \-x, \-\-maxpolltime \fIseconds\fP
244 .RS 4
245 Set max time in seconds to poll in manual mode.
246 The default max time is set to unlimited.
247 .RE
248
249 .SS Debugging Output Options:
250 .B \-l, \-\-debug \fIlevel\fP
251 .RS 4
252 Changes the log level (-1..4, default: 1)
253 .RE
254 .SH "EXAMPLES"
255 .B  ipsec scepclient \-\-out caCert \-\-url http://scepserver/cgi\-bin/pkiclient.exe \-f
256 .RS 4
257 Acquire CA certificate from SCEP server and store it in the default file $CONFDIR/ipsec.d/cacerts/caCert.der.
258 If more then one CA certificate is returned, store them in files named
259 \'caCert\-1.der\', \'caCert\-2.der\', etc.
260 If an RA certificate is returned, store it in a file named \'caCert\-ra.der\'.
261 If more than one RA certificate is returned, store them in files named
262 \'caCert\-ra\-1.der\', \'caCert\-ra\-2.der\', etc.
263 .RE
264 .PP
265 .B  ipsec scepclient \-\-out pkcs1=joeKey.der \-k 1024
266 .RS 4
267 Generate RSA private key with key length of 1024 bit and store it in file joeKey.der.
268 .RE
269 .PP
270 .B  ipsec scepclient \-\-in pkcs1=joeKey.der \-\-out pkcs10=joeReq.der \e
271 .br
272 .B \-\-dn \*(rqC=AT, CN=John Doe\*(rq \-s email=john@doe.com \-p mypassword
273 .RS 4
274 Generate a PKCS#10 request and store it in file joeReq.der. Use the RSA private key joeKey.der
275 created earlier to sign the PKCS#10\-Request. In addition to the distinguished name include a
276 email\-subjectAltName and a challenge password in the request.
277 .RE
278 .PP
279 .B  ipsec scepclient \-\-out pkcs1=joeKey.der \-\-out cert==joeCert.der \e
280 .br
281 .B \-\-dn \*(rqC=CH, CN=John Doe\*(rq \-k 512 \-p 5xH2pnT7wq \e
282 .br
283 .B \-\-url http://scep.hsr.ch/cgi\-bin/pkiclient.exe \e
284 .br
285 .B \-\-in cacert\-enc=caCert.der \-\-in cacert\-sig=caCert.der
286 .RS 4
287 Generate a new RSA key for the request and store it in joeKey.der. Then enroll a certificate and store as joeCert.der.
288 The challenge password is '5xH2pnT7wq'. The encryption and signature check has to be made with the same CA certificate
289 caCert.der.
290 .RE
291
292
293 .SH "BUGS"
294 \fB\-\-optionsfrom\fP seems to have parsing problems reading option files containing strings in quotation marks.
295 .SH "COPYRIGHT"
296 Copyright (C) 2005 Jan Hutter, Martin Willi
297 .br
298 Hochschule fuer Technik Rapperswil
299 .PP
300 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>.
301 .PP
302 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.