'\" te
.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved
.\" 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.
.\" 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.
.\" 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]
.TH KSSLCFG 1M "May 27, 2008"
.SH NAME
ksslcfg \- enable and configure SMF instance of Kernel SSL
.SH SYNOPSIS
.LP
.nf
\fBksslcfg\fR create \fB-f\fR pkcs11 \fB-T\fR \fItoken_label\fR \fB-C\fR \fIcertificate_label\fR
     [\fB-d\fR \fIsofttoken_directory\fR]
     [\fB-p\fR \fIpassword_file\fR [\fB-u\fR \fIusername\fR]]
     [\fB-h\fR \fIca_certchain_file\fR] [\fB-c\fR \fIciphersuites\fR]
     [\fB-t\fR \fIssl_session_cache_timeout\fR]
     [\fB-z\fR \fIssl_session_cache_size\fR] [\fB-v\fR] \fB-x\fR \fIproxy_port\fR [\fIhost\fR] \fIssl_port\fR
.fi

.LP
.nf
\fBksslcfg\fR create \fB-f\fR pkcs12 \fB-i\fR \fIcert_and_key_pk12file\fR
     [\fB-p\fR \fIpassword_file\fR [\fB-u\fR \fIusername\fR]]
     [\fB-c\fR \fIciphersuites\fR] [\fB-t\fR \fIssl_session_cache_timeout\fR]
     [\fB-z\fR \fIssl_session_cache_size\fR] [\fB-v\fR] \fB-x\fR \fIproxy_port\fR [\fIhost\fR] \fIssl_port\fR
.fi

.LP
.nf
\fBksslcfg\fR create \fB-f\fR pem \fB-i\fR \fIcert_and_key_pemfile\fR
     [\fB-p\fR \fIpassword_file\fR [\fB-u\fR \fIusername\fR]]
     [\fB-c\fR \fIciphersuites\fR] [\fB-t\fR \fIssl_session_cache_timeout\fR]
     [\fB-z\fR \fIssl_session_cache_size\fR] [\fB-v\fR] \fB-x\fR \fIproxy_port\fR [\fIhost\fR] \fIssl_port\fR
.fi

.LP
.nf
\fBksslcfg\fR delete [\fB-v\fR] [\fIhost\fR] \fIssl_port\fR
.fi

.LP
.nf
\fBksslcfg\fR \fB-V\fR
.fi

.LP
.nf
\fBksslcfg\fR \fB-?\fR
.fi

.SH DESCRIPTION
.sp
.LP
\fBksslcfg\fR manages \fBsmf\fR(5) instances for the Kernel SSL proxy module.
An SSL-enabled web server can use the services of its Kernel SSL proxy to
improve the performance of the HTTPS packets processing. It does so by creating
an instance of the Kernel SSL service, specifying the SSL proxy port and
parameters, and by listening on the proxy port.
.sp
.LP
The \fBcreate\fR subcommand creates an instance and enables the service for the
given address and SSL port.
.sp
.LP
The \fBdelete\fR subcommand disables the service for the given address and
port, if it is enabled, and deletes the instance from the SMF repository.
.sp
.LP
\fBksslcfg\fR can be run as root or by other users assigned to the Network
Security profile. See \fBrbac\fR(5) and \fBuser_attr\fR(4). You must run
\fBksslcfg\fR to configure your Kernel SSL proxy before you start your
application.
.sp
.LP
\fBksslcfg\fR allows you to specify an \fIssl_port\fR operand, described under
OPERANDS, and, with the \fB-x\fR option, a \fIproxy_port\fR value. When
specified for use with the Kernel SSL proxy, these values cannot also be
configured for the Solaris Network Cache and Acceleration (NCA) feature. See
\fBnca\fR(1) for a description of the NCA feature.
.sp
.LP
The Fault Managed Resource Identifier (FMRI) for the kernel SSL proxy instances
is \fBsvc://network/ssl/proxy\fR. \fBksslcfg\fR creates an instance of that
service unique to the combination of host and SSL port. Instance FMRIs for
particular proxy entries can be found with \fBsvcs\fR(1) and used for
dependencies of other services.
.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.na
\fB\fB-c\fR \fIciphersuites\fR\fR
.ad
.sp .6
.RS 4n
Set of ciphers a client is allowed to negotiate in a sorted order. The
supported SSL version3 and TLS ciphers are listed below. Note that the names
are case-insensitive.
.sp
.in +2
.nf
rsa_rc4_128_sha
rsa_rc4_128_md5
rsa_aes_256_cbc_sha
rsa_aes_128_cbc_sha
rsa_3des_ede_cbc_sha
rsa_des_cbc_sha
.fi
.in -2

.RE

.sp
.ne 2
.na
\fB\fB-f\fR \fIkey_format\fR\fR
.ad
.sp .6
.RS 4n
Uses the certificate/key format specified in \fIkey_format\fR. The supported
options are \fBpkcs11\fR, \fBpkcs12\fR, and \fBpem\fR.
.RE

.sp
.ne 2
.na
\fB\fB-i\fR \fIkey_and_certificate_file\fR\fR
.ad
.sp .6
.RS 4n
When \fBpkcs12\fR or \fBpem\fR is specified with the \fB-f\fR option, reads a
key and a certificate of the web server from \fIkey_and_certificate_file\fR.
This file can also contain any intermediate CA certificates that form the
certificate chain to the root CA for the server certificate. These certificates
must follow the server certificate in the file and the order must be bottom up:
lowest level CA certificate followed by the next higher level CA certificate,
and so on.
.RE

.sp
.ne 2
.na
\fB\fB-C\fR \fIcertificate_label\fR\fR
.ad
.sp .6
.RS 4n
PKCS#11 can store multiple certificates in single token. This option enables
you to specify a single certificate, identified by \fIcertificate_label\fR.
This label must match the \fBCKA_LABEL\fR on the certificate object in the
token specified by \fB-T\fR. This option is to be used only with \fB-f\fR
\fBpkcs11\fR.
.RE

.sp
.ne 2
.na
\fB\fB-d\fR \fIsofttoken_directory\fR\fR
.ad
.sp .6
.RS 4n
This option is applicable only with the \fBpkcs11\fR key format, when the token
label is the Sun Software PKCS#11 softtoken. Use this option to override the
default location of the PKCS#11 softtoken directory (\fB$HOME/.sunw\fR). See
\fBpkcs11_softtoken\fR(5).
.RE

.sp
.ne 2
.na
\fB\fB-h\fR \fIca_certchain_file\fR\fR
.ad
.sp .6
.RS 4n
When \fBpkcs11\fR is specified with the \fB-f\fR option, reads a set of
intermediate CA certificates that form the certificate chain to the root CA for
the server certificate (specified with the \fB-C\fR option), from
\fIca_certchain_file\fR. The file must be in PEM format.
.RE

.sp
.ne 2
.na
\fB\fB-p\fR \fIpassword_file\fR\fR
.ad
.sp .6
.RS 4n
Obtains the password used to encrypt the private key from \fIpassword_file\fR.
When using the \fBpkcs11\fR option (see \fB-f\fR, above), the password is used
to authenticate the user to the PKCS #11 token.
.RE

.sp
.ne 2
.na
\fB\fB-t\fR \fIssl_session_cache_timeout\fR\fR
.ad
.sp .6
.RS 4n
The timeout value, in seconds, for an SSL session. It corresponds to
\fBSSL3SessionTimeout\fR of the Sun ONE web server configuration or
\fBSSLSessionCacheTimeout\fR of \fBmod_ssl\fR.
.RE

.sp
.ne 2
.na
\fB\fB-T\fR \fItoken_label\fR\fR
.ad
.sp .6
.RS 4n
When \fBpkcs11\fR is specified with \fB-f\fR, uses the PKCS#11 token specified
in \fItoken_label\fR. Use \fBcryptoadm list\fR \fB-v\fR to display all PKCS#11
tokens available.
.RE

.sp
.ne 2
.na
\fB\fB-u\fR \fIusername\fR\fR
.ad
.sp .6
.RS 4n
The username of the user who owns the password file. If omitted, the system
will try to read the password file as root.
.RE

.sp
.ne 2
.na
\fB\fB-v\fR\fR
.ad
.sp .6
.RS 4n
Verbose mode.
.RE

.sp
.ne 2
.na
\fB\fB-V\fR\fR
.ad
.sp .6
.RS 4n
Displays the version.
.RE

.sp
.ne 2
.na
\fB\fB-x\fR \fIproxy_port\fR\fR
.ad
.sp .6
.RS 4n
The SSL proxy port. The port number is designated exclusively for clear-text
HTTP communication between the web server and the kernel SSL proxy module. No
external HTTP packets are delivered to this port.
.RE

.sp
.ne 2
.na
\fB\fB-z\fR \fIssl_session_cache_size\fR\fR
.ad
.sp .6
.RS 4n
The maximum number of SSL sessions that can be cached. It corresponds to
\fBSSLCacheEntries\fR of the Sun ONE web server configuration. When this option
is not specified, the default is 5000 entries.
.RE

.sp
.ne 2
.na
\fB\fB-?\fR \fI\fR\fR
.ad
.sp .6
.RS 4n
Displays the usage of the command.
.RE

.SH OPERANDS
.sp
.ne 2
.na
\fB\fB[\fIhost\fR] [\fIssl_port\fR]\fR\fR
.ad
.RS 21n
The address and the port of the web server for which the kernel SSL entry is
created. If \fIhost\fR is omitted, the entry will be used for all requests that
arrived at the \fIssl_port\fR, regardless of the destination address. Both a
host name and an IP address are acceptable forms for \fIhost\fR. \fIssl_port\fR
is required. Typically, this has a value of 443.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRCreate and Enable a Kernel SSL Instance
.sp
.LP
The following command creates and enables a Kernel SSL instance using a
certificate and a key in PKCS#11 format.

.sp
.in +2
.nf
# \fBksslcfg create -f pkcs11 -T "Sun Software PKCS#11 softtoken"  \e
-C "Server-Cert" -p /some/directory/password -u webservd \e
-x 8080 www.mysite.com 443\fR

% \fBsvcs svc:/network/ssl/proxy\fR
STATE          STIME    FMRI
online         Sep_27   svc:/network/ssl/proxy:kssl-www-mysite-com-443
.fi
.in -2
.sp

.LP
\fBExample 2 \fRCreate and Enable a Default Instance for All Addresses
.sp
.LP
The following command creates and enables a default instance for all addresses
from a certicate and key in a \fBpkcs#12\fR file.

.sp
.in +2
.nf
# \fBksslcfg create -x 8888 -f pkcs12 -i /some/directory/keypair.p12 \e
    -p /some/directory/password -u webservd 443\fR
.fi
.in -2
.sp

.LP
\fBExample 3 \fRCreate and Enable an Instance with Specific Cipher Suites
.sp
.LP
The following command creates and enables an instance with specific cipher
suites.

.sp
.in +2
.nf
# \fBksslcfg create -x 8080 -f pem \e
-i /some/directory/keypair.pem -p /some/directory/password \e
-c "rsa_rc4_128_md5,rsa_rc4_128_sha" \e
209.249.116.195 443\fR
.fi
.in -2
.sp

.LP
\fBExample 4 \fRDisable and Delete an Instance
.sp
.LP
The following command disables and deletes an instance.

.sp
.in +2
.nf
# \fBksslcfg delete www.mysite.com 443\fR
.fi
.in -2
.sp

.SH EXIT STATUS
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 6n
Successful completion.
.RE

.sp
.ne 2
.na
\fB\fB>0\fR\fR
.ad
.RS 6n
An error occurred.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	See below.
.TE

.sp
.LP
Command line options are Evolving; command output is Unstable. The FMRI service
name (\fBsvc://network/ssl/proxy\fR) is Unstable, as is the FMRI instance's
name format. The utility name is Stable.
.SH SEE ALSO
.sp
.LP
\fBnca\fR(1), \fBsvcprop\fR(1), \fBsvcs\fR(1), \fBcryptoadm\fR(1M),
\fBsvcadm\fR(1M), \fBsvccfg\fR(1M), \fBuser_attr\fR(4), \fBattributes\fR(5),
\fBpkcs11_softtoken\fR(5), \fBrbac\fR(5), \fBsmf\fR(5)
.SH NOTES
.sp
.LP
\fBksslcfg\fR \fBcreate\fR without an host argument creates an \fBINADDR_ANY\fR
\fBsmf\fR instance. \fBksslcfg\fR \fBdelete\fR without an host argument deletes
only the \fBINADDR_ANY\fR instance. \fBksslcfg\fR \fBdelete\fR needs a host
argument to delete any non-\fBINADDR_ANY\fR instance.
.sp
.LP
On a system with \fBzones\fR(5) installed, the \fBksslcfg\fR command can be
used only in the global zone at this time.