| blob | d70ff33c943976819985eb2d72757d9e40958ae2 |
1 '\" te
2 .\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH KSSLCFG 1M "May 27, 2008"
7 .SH NAME
8 ksslcfg \- enable and configure SMF instance of Kernel SSL
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fBksslcfg\fR create \fB-f\fR pkcs11 \fB-T\fR \fItoken_label\fR \fB-C\fR \fIcertificate_label\fR
13 [\fB-d\fR \fIsofttoken_directory\fR]
14 [\fB-p\fR \fIpassword_file\fR [\fB-u\fR \fIusername\fR]]
15 [\fB-h\fR \fIca_certchain_file\fR] [\fB-c\fR \fIciphersuites\fR]
16 [\fB-t\fR \fIssl_session_cache_timeout\fR]
17 [\fB-z\fR \fIssl_session_cache_size\fR] [\fB-v\fR] \fB-x\fR \fIproxy_port\fR [\fIhost\fR] \fIssl_port\fR
18 .fi
20 .LP
21 .nf
22 \fBksslcfg\fR create \fB-f\fR pkcs12 \fB-i\fR \fIcert_and_key_pk12file\fR
23 [\fB-p\fR \fIpassword_file\fR [\fB-u\fR \fIusername\fR]]
24 [\fB-c\fR \fIciphersuites\fR] [\fB-t\fR \fIssl_session_cache_timeout\fR]
25 [\fB-z\fR \fIssl_session_cache_size\fR] [\fB-v\fR] \fB-x\fR \fIproxy_port\fR [\fIhost\fR] \fIssl_port\fR
26 .fi
28 .LP
29 .nf
30 \fBksslcfg\fR create \fB-f\fR pem \fB-i\fR \fIcert_and_key_pemfile\fR
31 [\fB-p\fR \fIpassword_file\fR [\fB-u\fR \fIusername\fR]]
32 [\fB-c\fR \fIciphersuites\fR] [\fB-t\fR \fIssl_session_cache_timeout\fR]
33 [\fB-z\fR \fIssl_session_cache_size\fR] [\fB-v\fR] \fB-x\fR \fIproxy_port\fR [\fIhost\fR] \fIssl_port\fR
34 .fi
36 .LP
37 .nf
38 \fBksslcfg\fR delete [\fB-v\fR] [\fIhost\fR] \fIssl_port\fR
39 .fi
41 .LP
42 .nf
43 \fBksslcfg\fR \fB-V\fR
44 .fi
46 .LP
47 .nf
48 \fBksslcfg\fR \fB-?\fR
49 .fi
51 .SH DESCRIPTION
52 .sp
53 .LP
54 \fBksslcfg\fR manages \fBsmf\fR(5) instances for the Kernel SSL proxy module.
55 An SSL-enabled web server can use the services of its Kernel SSL proxy to
56 improve the performance of the HTTPS packets processing. It does so by creating
57 an instance of the Kernel SSL service, specifying the SSL proxy port and
58 parameters, and by listening on the proxy port.
59 .sp
60 .LP
61 The \fBcreate\fR subcommand creates an instance and enables the service for the
62 given address and SSL port.
63 .sp
64 .LP
65 The \fBdelete\fR subcommand disables the service for the given address and
66 port, if it is enabled, and deletes the instance from the SMF repository.
67 .sp
68 .LP
69 \fBksslcfg\fR can be run as root or by other users assigned to the Network
70 Security profile. See \fBrbac\fR(5) and \fBuser_attr\fR(4). You must run
71 \fBksslcfg\fR to configure your Kernel SSL proxy before you start your
72 application.
73 .sp
74 .LP
75 \fBksslcfg\fR allows you to specify an \fIssl_port\fR operand, described under
76 OPERANDS, and, with the \fB-x\fR option, a \fIproxy_port\fR value. When
77 specified for use with the Kernel SSL proxy, these values cannot also be
78 configured for the Solaris Network Cache and Acceleration (NCA) feature. See
79 \fBnca\fR(1) for a description of the NCA feature.
80 .sp
81 .LP
82 The Fault Managed Resource Identifier (FMRI) for the kernel SSL proxy instances
83 is \fBsvc://network/ssl/proxy\fR. \fBksslcfg\fR creates an instance of that
84 service unique to the combination of host and SSL port. Instance FMRIs for
85 particular proxy entries can be found with \fBsvcs\fR(1) and used for
86 dependencies of other services.
87 .SH OPTIONS
88 .sp
89 .LP
90 The following options are supported:
91 .sp
92 .ne 2
93 .na
94 \fB\fB-c\fR \fIciphersuites\fR\fR
95 .ad
96 .sp .6
97 .RS 4n
98 Set of ciphers a client is allowed to negotiate in a sorted order. The
99 supported SSL version3 and TLS ciphers are listed below. Note that the names
100 are case-insensitive.
101 .sp
102 .in +2
103 .nf
104 rsa_rc4_128_sha
105 rsa_rc4_128_md5
106 rsa_aes_256_cbc_sha
107 rsa_aes_128_cbc_sha
108 rsa_3des_ede_cbc_sha
109 rsa_des_cbc_sha
110 .fi
111 .in -2
113 .RE
115 .sp
116 .ne 2
117 .na
118 \fB\fB-f\fR \fIkey_format\fR\fR
119 .ad
120 .sp .6
121 .RS 4n
122 Uses the certificate/key format specified in \fIkey_format\fR. The supported
123 options are \fBpkcs11\fR, \fBpkcs12\fR, and \fBpem\fR.
124 .RE
126 .sp
127 .ne 2
128 .na
129 \fB\fB-i\fR \fIkey_and_certificate_file\fR\fR
130 .ad
131 .sp .6
132 .RS 4n
133 When \fBpkcs12\fR or \fBpem\fR is specified with the \fB-f\fR option, reads a
134 key and a certificate of the web server from \fIkey_and_certificate_file\fR.
135 This file can also contain any intermediate CA certificates that form the
136 certificate chain to the root CA for the server certificate. These certificates
137 must follow the server certificate in the file and the order must be bottom up:
138 lowest level CA certificate followed by the next higher level CA certificate,
139 and so on.
140 .RE
142 .sp
143 .ne 2
144 .na
145 \fB\fB-C\fR \fIcertificate_label\fR\fR
146 .ad
147 .sp .6
148 .RS 4n
149 PKCS#11 can store multiple certificates in single token. This option enables
150 you to specify a single certificate, identified by \fIcertificate_label\fR.
151 This label must match the \fBCKA_LABEL\fR on the certificate object in the
152 token specified by \fB-T\fR. This option is to be used only with \fB-f\fR
153 \fBpkcs11\fR.
154 .RE
156 .sp
157 .ne 2
158 .na
159 \fB\fB-d\fR \fIsofttoken_directory\fR\fR
160 .ad
161 .sp .6
162 .RS 4n
163 This option is applicable only with the \fBpkcs11\fR key format, when the token
164 label is the Sun Software PKCS#11 softtoken. Use this option to override the
165 default location of the PKCS#11 softtoken directory (\fB$HOME/.sunw\fR). See
166 \fBpkcs11_softtoken\fR(5).
167 .RE
169 .sp
170 .ne 2
171 .na
172 \fB\fB-h\fR \fIca_certchain_file\fR\fR
173 .ad
174 .sp .6
175 .RS 4n
176 When \fBpkcs11\fR is specified with the \fB-f\fR option, reads a set of
177 intermediate CA certificates that form the certificate chain to the root CA for
178 the server certificate (specified with the \fB-C\fR option), from
179 \fIca_certchain_file\fR. The file must be in PEM format.
180 .RE
182 .sp
183 .ne 2
184 .na
185 \fB\fB-p\fR \fIpassword_file\fR\fR
186 .ad
187 .sp .6
188 .RS 4n
189 Obtains the password used to encrypt the private key from \fIpassword_file\fR.
190 When using the \fBpkcs11\fR option (see \fB-f\fR, above), the password is used
191 to authenticate the user to the PKCS #11 token.
192 .RE
194 .sp
195 .ne 2
196 .na
197 \fB\fB-t\fR \fIssl_session_cache_timeout\fR\fR
198 .ad
199 .sp .6
200 .RS 4n
201 The timeout value, in seconds, for an SSL session. It corresponds to
202 \fBSSL3SessionTimeout\fR of the Sun ONE web server configuration or
203 \fBSSLSessionCacheTimeout\fR of \fBmod_ssl\fR.
204 .RE
206 .sp
207 .ne 2
208 .na
209 \fB\fB-T\fR \fItoken_label\fR\fR
210 .ad
211 .sp .6
212 .RS 4n
213 When \fBpkcs11\fR is specified with \fB-f\fR, uses the PKCS#11 token specified
214 in \fItoken_label\fR. Use \fBcryptoadm list\fR \fB-v\fR to display all PKCS#11
215 tokens available.
216 .RE
218 .sp
219 .ne 2
220 .na
221 \fB\fB-u\fR \fIusername\fR\fR
222 .ad
223 .sp .6
224 .RS 4n
225 The username of the user who owns the password file. If omitted, the system
226 will try to read the password file as root.
227 .RE
229 .sp
230 .ne 2
231 .na
232 \fB\fB-v\fR\fR
233 .ad
234 .sp .6
235 .RS 4n
236 Verbose mode.
237 .RE
239 .sp
240 .ne 2
241 .na
242 \fB\fB-V\fR\fR
243 .ad
244 .sp .6
245 .RS 4n
246 Displays the version.
247 .RE
249 .sp
250 .ne 2
251 .na
252 \fB\fB-x\fR \fIproxy_port\fR\fR
253 .ad
254 .sp .6
255 .RS 4n
256 The SSL proxy port. The port number is designated exclusively for clear-text
257 HTTP communication between the web server and the kernel SSL proxy module. No
258 external HTTP packets are delivered to this port.
259 .RE
261 .sp
262 .ne 2
263 .na
264 \fB\fB-z\fR \fIssl_session_cache_size\fR\fR
265 .ad
266 .sp .6
267 .RS 4n
268 The maximum number of SSL sessions that can be cached. It corresponds to
269 \fBSSLCacheEntries\fR of the Sun ONE web server configuration. When this option
270 is not specified, the default is 5000 entries.
271 .RE
273 .sp
274 .ne 2
275 .na
276 \fB\fB-?\fR \fI\fR\fR
277 .ad
278 .sp .6
279 .RS 4n
280 Displays the usage of the command.
281 .RE
283 .SH OPERANDS
284 .sp
285 .ne 2
286 .na
287 \fB\fB[\fIhost\fR] [\fIssl_port\fR]\fR\fR
288 .ad
289 .RS 21n
290 The address and the port of the web server for which the kernel SSL entry is
291 created. If \fIhost\fR is omitted, the entry will be used for all requests that
292 arrived at the \fIssl_port\fR, regardless of the destination address. Both a
293 host name and an IP address are acceptable forms for \fIhost\fR. \fIssl_port\fR
294 is required. Typically, this has a value of 443.
295 .RE
297 .SH EXAMPLES
298 .LP
299 \fBExample 1 \fRCreate and Enable a Kernel SSL Instance
300 .sp
301 .LP
302 The following command creates and enables a Kernel SSL instance using a
303 certificate and a key in PKCS#11 format.
305 .sp
306 .in +2
307 .nf
308 # \fBksslcfg create -f pkcs11 -T "Sun Software PKCS#11 softtoken" \e
309 -C "Server-Cert" -p /some/directory/password -u webservd \e
310 -x 8080 www.mysite.com 443\fR
312 % \fBsvcs svc:/network/ssl/proxy\fR
313 STATE STIME FMRI
314 online Sep_27 svc:/network/ssl/proxy:kssl-www-mysite-com-443
315 .fi
316 .in -2
317 .sp
319 .LP
320 \fBExample 2 \fRCreate and Enable a Default Instance for All Addresses
321 .sp
322 .LP
323 The following command creates and enables a default instance for all addresses
324 from a certicate and key in a \fBpkcs#12\fR file.
326 .sp
327 .in +2
328 .nf
329 # \fBksslcfg create -x 8888 -f pkcs12 -i /some/directory/keypair.p12 \e
330 -p /some/directory/password -u webservd 443\fR
331 .fi
332 .in -2
333 .sp
335 .LP
336 \fBExample 3 \fRCreate and Enable an Instance with Specific Cipher Suites
337 .sp
338 .LP
339 The following command creates and enables an instance with specific cipher
340 suites.
342 .sp
343 .in +2
344 .nf
345 # \fBksslcfg create -x 8080 -f pem \e
346 -i /some/directory/keypair.pem -p /some/directory/password \e
347 -c "rsa_rc4_128_md5,rsa_rc4_128_sha" \e
348 209.249.116.195 443\fR
349 .fi
350 .in -2
351 .sp
353 .LP
354 \fBExample 4 \fRDisable and Delete an Instance
355 .sp
356 .LP
357 The following command disables and deletes an instance.
359 .sp
360 .in +2
361 .nf
362 # \fBksslcfg delete www.mysite.com 443\fR
363 .fi
364 .in -2
365 .sp
367 .SH EXIT STATUS
368 .sp
369 .ne 2
370 .na
371 \fB\fB0\fR\fR
372 .ad
373 .RS 6n
374 Successful completion.
375 .RE
377 .sp
378 .ne 2
379 .na
380 \fB\fB>0\fR\fR
381 .ad
382 .RS 6n
383 An error occurred.
384 .RE
386 .SH ATTRIBUTES
387 .sp
388 .LP
389 See \fBattributes\fR(5) for descriptions of the following attributes:
390 .sp
392 .sp
393 .TS
394 box;
395 c | c
396 l | l .
397 ATTRIBUTE TYPE ATTRIBUTE VALUE
398 _
399 Interface Stability See below.
400 .TE
402 .sp
403 .LP
404 Command line options are Evolving; command output is Unstable. The FMRI service
405 name (\fBsvc://network/ssl/proxy\fR) is Unstable, as is the FMRI instance's
406 name format. The utility name is Stable.
407 .SH SEE ALSO
408 .sp
409 .LP
410 \fBnca\fR(1), \fBsvcprop\fR(1), \fBsvcs\fR(1), \fBcryptoadm\fR(1M),
411 \fBsvcadm\fR(1M), \fBsvccfg\fR(1M), \fBuser_attr\fR(4), \fBattributes\fR(5),
412 \fBpkcs11_softtoken\fR(5), \fBrbac\fR(5), \fBsmf\fR(5)
413 .SH NOTES
414 .sp
415 .LP
416 \fBksslcfg\fR \fBcreate\fR without an host argument creates an \fBINADDR_ANY\fR
417 \fBsmf\fR instance. \fBksslcfg\fR \fBdelete\fR without an host argument deletes
418 only the \fBINADDR_ANY\fR instance. \fBksslcfg\fR \fBdelete\fR needs a host
419 argument to delete any non-\fBINADDR_ANY\fR instance.
420 .sp
421 .LP
422 On a system with \fBzones\fR(5) installed, the \fBksslcfg\fR command can be
423 used only in the global zone at this time.