'\" te
.\" Copyright (c) 2005, 2015, Oracle and/or its affiliates. All rights                reserved.
.TH ksslcfg 1M "24 Feb 2015" "SunOS 5.11" "System Administration Commands"
.SH NAME
ksslcfg \- enable and configure SMF instance of Kernel SSL
.SH SYNOPSIS
.LP
.nf
ksslcfg create -f pkcs11 -T <\fItoken_label\fR> [-d \fIsofttoken_directory\fR] -C 
  <\fIcertificate_label\fR> [-h <\fIca_certchain_file\fR>] 
             -p <\fIpassword_file\fR> [options] -x <\fIproxy_port\fR> [<\fIserver_address\fR>] 
  [<\fIserver_port\fR>] 
.fi

.LP
.nf
ksslcfg create -f pkcs12 -i <\fIcert_and_key_pk12file\fR> 
             -p <\fIpassword_file\fR> [options] -x <\fIproxy_port\fR> [<\fIserver_address\fR>] 
  [<\fIserver_port\fR>] 
.fi

.LP
.nf
ksslcfg create -f pem -i <\fIcert_and_key_pemfile\fR> 
             -p <\fIpassword_file\fR> [options] -x <\fIproxy_port\fR> [<\fIserver_address\fR>] 
  [<\fIserver_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).
.sp
.LP
After \fBksslcfg\fR successfully configures the service in the kernel, the proxy application must be started, or restarted if it is already running.
.sp
.LP
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.
.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. The state of the service instance tracks in-kernel configuration only. It does not reflect the presence or state of the application listening on the proxy port.
.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.mk
.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 SSLv3 and TLSv1.0 ciphers are listed below. Note that the names are separated by comma and 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
.mk
.na
\fB\fB-s\fR \fIversions\fR\fR
.ad
.sp .6
.RS 4n
Set of versions of SSL/TLS protocol which are administratively enabled for Kernel SSL proxy module. Recognized values are SSLv3 and TLSv1.0. By default only TLSv1.0 is enabled. Note that the versions are separated by comma and are case-insensitive.
.RE

.sp
.ne 2
.mk
.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
.mk
.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
.mk
.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
.mk
.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
.mk
.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
.mk
.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
.mk
.na
\fB\fB-k\fR \fIssl_handshake_timeout\fR\fR
.ad
.sp .6
.RS 4n
The timeout value in seconds for SSL handshake to finish. If the handshake does not finish until the timeout specified the connection will be torn down. The default value is 30 seconds.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-n\fR \fIssl_handshake_limit\fR\fR
.ad
.sp .6
.RS 4n
Maximum number of simultaneous SSL handshakes. Once the number of handshakes reaches this number, all new handshakes will get refused. The default value is 65536. 
.RE

.sp
.ne 2
.mk
.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
.mk
.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
.mk
.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
.mk
.na
\fB\fB-v\fR\fR
.ad
.sp .6
.RS 4n
Verbose mode.
.RE

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

.sp
.ne 2
.mk
.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
.mk
.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
.mk
.na
\fB\fB-?\fR \fI\fR\fR
.ad
.sp .6
.RS 4n
Displays the usage of the command.
.RE

.SH OPERANDS
.sp
.ne 2
.mk
.na
\fB\fB[\fIhost\fR] [\fIssl_port\fR]\fR\fR
.ad
.sp .6
.RS 4n
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
# ksslcfg 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

% svcs svc:/network/ssl/proxy
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 certificate and key in a \fBpkcs#12\fR file.

.sp
.in +2
.nf
# ksslcfg create -x 8888 -f pkcs12 -i /some/directory/keypair.p12 \e
    -p /some/directory/password -u webservd 443
.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
# ksslcfg 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
.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
# ksslcfg delete www.mysite.com 443
.fi
.in -2
.sp

.LP
\fBExample 5 \fREstablishing Dependency of Proxy Application
.sp
.LP
The sequence of commands shown below establishes a dependency of a proxy application on a KSSL instance. Note that he proxy application should only be started after the SSL kernel proxy instance has been started.

.sp
.LP
The following commands establish the dependency of an Apache 2.2 web server. KSSL has been configured to listen on SSL port 443 and a wildcard address.

.sp
.in +2
.nf
# \fBsvccfg -s svc:/network/http:apache22\fR
svc:/network/http:apache22> \fBaddpg kssl dependency\fR
svc:/network/http:apache22> \fBsetprop kssl/entities = fmri:svc:/network/\e\fR
\fBssl/proxy:kssl-INADDR_ANY-443\fR
svc:/network/http:apache22> \fBsetprop kssl/grouping = astring: require_all\fR
svc:/network/http:apache22> \fBsetprop kssl/restart_on = astring: refresh\fR
svc:/network/http:apache22> \fBsetprop kssl/type = astring: service\fR
svc:/network/http:apache22> \fBend\fR
.fi
.in -2
.sp

.sp
.LP
Following these commands, enable the web server:

.sp
.in +2
.nf
# \fBsvcadm enable svc:/network/http:apache22\fR
.fi
.in -2
.sp

.sp
.LP
If the web server was already running, restart it:

.sp
.in +2
.nf
# \fBsvcadm refresh svc:/network/http:apache22\fR
# \fBsvcadm restart svc:/network/http:apache22\fR
.fi
.in -2
.sp

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

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

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

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Availabilitysystem/core-os
_
Interface StabilitySee below.
.TE

.sp
.LP
Command line options and the utility name are Committed. The command output, the FMRI service name (\fBsvc://network/ssl/proxy\fR), and the FMRI instance's name format are Uncommitted
.SH SEE ALSO
.sp
.LP
\fBsvcprop\fR(1), \fBsvcs\fR(1), \fBcryptoadm\fR(1M), \fBsvcadm\fR(1M), \fBsvccfg\fR(1M), \fBuser_attr\fR(4), \fBattributes\fR(5), \fBkssl\fR(5), \fBpkcs11_softtoken\fR(5), \fBrbac\fR(5), \fBsmf\fR(5), \fBnca\fR(7d)
.sp
.LP
Chown, P., \fIAdvanced Encryption Standard (AES) Ciphersuites for Transport Layer Security (TLS)\fR, RFC 3268, June 2002.
.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.