path: root/usr/src/man/man1m/ikeadm.1m

'\" te
.\" Copyright (c) 2009, 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 IKEADM 1M "Jan 27, 2009"
.SH NAME
ikeadm \- manipulate Internet Key Exchange (IKE) parameters and state
.SH SYNOPSIS
.LP
.nf
\fBikeadm\fR [\fB-np\fR]
.fi

.LP
.nf
\fBikeadm\fR [\fB-np\fR] get [debug | priv | stats | defaults]
.fi

.LP
.nf
\fBikeadm\fR [\fB-np\fR] set [debug | priv] [level] [file]
.fi

.LP
.nf
\fBikeadm\fR [\fB-np\fR] [get | del] [p1 | rule | preshared] [id]
.fi

.LP
.nf
\fBikeadm\fR [\fB-np\fR] add [rule | preshared] { \fIdescription\fR }
.fi

.LP
.nf
ikeadm [\fB-np\fR] token [login | logout] \fIPKCS#11_Token_Object\fR
.fi

.LP
.nf
\fBikeadm\fR [\fB-np\fR] [read | write] [rule | preshared | certcache] \fIfile\fR
.fi

.LP
.nf
\fBikeadm\fR [\fB-np\fR] [dump | pls | rule | preshared]
.fi

.LP
.nf
\fBikeadm\fR [\fB-np\fR] flush [p1 | certcache]
.fi

.LP
.nf
\fBikeadm\fR help
     [get | set | add | del | read | write | dump | flush | token]
.fi

.SH DESCRIPTION
.sp
.LP
The \fBikeadm\fR utility retrieves information from and manipulates the
configuration of the Internet Key Exchange (\fBIKE\fR) protocol daemon,
\fBin.iked\fR(1M).
.sp
.LP
\fBikeadm\fR supports a set of operations, which may be performed on one or
more of the supported object types. When invoked without arguments,
\fBikeadm\fR enters interactive mode which prints a prompt to the standard
output and accepts commands from the standard input until the end-of-file is
reached.
.sp
.LP
Because \fBikeadm\fR manipulates sensitive keying information, you must be
superuser to use this command. Additionally, some of the commands available
require that the daemon be running in a privileged mode, which is established
when the daemon is started.
.sp
.LP
For details on how to use this command securely see .
.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.na
\fB\fB-n\fR\fR
.ad
.sp .6
.RS 4n
Prevent attempts to print host and network names symbolically when reporting
actions. This is useful, for example, when all name servers are down or are
otherwise unreachable.
.RE

.sp
.ne 2
.na
\fB\fB-p\fR\fR
.ad
.sp .6
.RS 4n
Paranoid. Do not print any keying material, even if saving Security
Associations. Instead of an actual hexadecimal digit, print an \fBX\fR when
this flag is turned on.
.RE

.SH USAGE
.SS "Commands"
.sp
.LP
The following commands are supported:
.sp
.ne 2
.na
\fB\fBadd\fR\fR
.ad
.sp .6
.RS 4n
Add the specified object. This option can be used to add a new policy rule or a
new preshared key to the current (running) in.iked configuration. When adding a
new preshared key, the command cannot be invoked from the command line, as it
will contain keying material. The rule or key being added is specified using
appropriate id-value pairs as described in the \fBID FORMATS\fR section.
.RE

.sp
.ne 2
.na
\fB\fBdel\fR\fR
.ad
.sp .6
.RS 4n
Delete a specific object or objects from \fBin.iked\fR's current configuration.
This operation is available for \fBIKE\fR (Phase 1) \fBSA\fRs, policy rules,
and preshared keys. The object to be deleted is specified as described in the
\fBId Formats\fR.
.RE

.sp
.ne 2
.na
\fB\fBdump\fR\fR
.ad
.sp .6
.RS 4n
Display all objects of the specified type known to \fBin.iked\fR. This option
can be used to display all Phase 1 \fBSA\fRs, policy rules, preshared keys, or
the certificate cache. A large amount of output may be generated by this
command.
.RE

.sp
.ne 2
.na
\fB\fBflush\fR\fR
.ad
.sp .6
.RS 4n
Remove all \fBIKE\fR (Phase 1) \fBSA\fRs or cached certificates from
\fBin.iked\fR.
.sp
Note that flushing the \fBcertcache\fR will also (as a side-effect) update IKE
with any new certificates added or removed.
.RE

.sp
.ne 2
.na
\fB\fBget\fR\fR
.ad
.sp .6
.RS 4n
Lookup and display the specified object. May be used to view the current debug
or privilege level, global statistics and default values for the daemon, or a
specific \fBIKE\fR (Phase 1) \fBSA\fR, policy rule, or preshared key. The
latter three object types require that identifying information be passed in;
the appropriate specification for each object type is described below.
.RE

.sp
.ne 2
.na
\fB\fBhelp\fR\fR
.ad
.sp .6
.RS 4n
Print a brief summary of commands, or, when followed by a command, prints
information about that command.
.RE

.sp
.ne 2
.na
\fB\fBread\fR\fR
.ad
.sp .6
.RS 4n
Update the current \fBin.iked\fR configuration by reading the policy rules or
preshared keys from either the default location or from the file specified.
.RE

.sp
.ne 2
.na
\fB\fBset\fR\fR
.ad
.sp .6
.RS 4n
Adjust the current debug or privilege level. If the debug level is being
modified, an output file may optionally be specified; the output file
\fBmust\fR be specified if the daemon is running in the background and is not
currently printing to a file. When changing the privilege level, adjustments
may only be made to lower the access level; it cannot be increased using
ikeadm.
.RE

.sp
.ne 2
.na
\fB\fBwrite\fR\fR
.ad
.sp .6
.RS 4n
Write the current \fBin.iked\fR policy rule set or preshared key set to the
specified file. A destination file must be specified. This command should not
be used to overwrite the existing configuration files.
.RE

.sp
.ne 2
.na
\fB\fBtoken\fR\fR
.ad
.sp .6
.RS 4n
Log into a PKCS#11 token object and grant access to keying material or log out
and invalidate access to keying material.
.sp
\fBtoken\fR can be run as a normal user with the following authorizations:
.RS +4
.TP
.ie t \(bu
.el o
\fBtoken\fR login: \fBsolaris.network.ipsec.ike.token.login\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBtoken\fR logout: \fBsolaris.network.ipsec.ike.token.logout\fR
.RE
.RE

.SS "Object Types"
.sp
.ne 2
.na
\fBdebug\fR
.ad
.sp .6
.RS 4n
Specifies the daemon's debug level. This determines the amount and type of
output provided by the daemon about its operations. The debug level is actually
a bitmask, with individual bits enabling different types of information.
.sp

.sp
.TS
c c c
l l l .
Description	Flag	Nickname
_
Certificate management	0x0001	cert
Key management	0x0002	key
Operational	0x0004	op
Phase 1 SA creation	0x0008	phase1
Phase 2 SA creation	0x0010	phase2
PF_KEY interface	0x0020	pfkey
Policy management	0x0040	policy
Proposal construction	0x0080	prop
Door interface	0x0100	door
Config file processing	0x0200	config
All debug flags	0x3ff	all
.TE

When specifying the debug level, either a number (decimal or hexadecimal) or a
string of nicknames may be given. For example, \fB88\fR, \fB0x58\fR, and
\fBphase1\fR+\fBphase2\fR+\fBpolicy\fR are all equivalent, and will turn on
debug for \fBphase 1\fR \fBsa\fR creation, \fBphase 2 sa\fR creation, and
policy management. A string of nicknames may also be used to remove certain
types of information; \fBall-op\fR has the effect of turning on all debug
\fBexcept\fR for operational messages; it is equivalent to the numbers
\fB1019\fR or \fB0x3fb\fR.
.RE

.sp
.ne 2
.na
\fBpriv\fR
.ad
.sp .6
.RS 4n
Specifies the daemon's access privilege level. The possible values are:
.sp
.in +2
.nf
Description                  Level   Nickname
Base level                   0       base
Access to preshared key info 1       modkeys
Access to keying material    2       keymat
.fi
.in -2
.sp

By default, \fBin.iked\fR is started at the base level. A command-line option
can be used to start the daemon at a higher level. \fBikeadm\fR can be used to
lower the level, but it cannot be used to raise the level.
.sp
Either the numerical level or the nickname may be used to specify the target
privilege level.
.sp
In order to get, add, delete, dump, read, or write preshared keys, the
privilege level must at least give access to preshared key information.
However, when viewing preshared keys (either using the get or dump command),
the key itself will only be available if the privilege level gives access to
keying material. This is also the case when viewing Phase 1 \fBSA\fRs.
.RE

.sp
.ne 2
.na
\fBstats\fR
.ad
.sp .6
.RS 4n
Global statistics from the daemon, covering both successful and failed Phase 1
\fBSA\fR creation.
.sp
Reported statistics include:
.RS +4
.TP
.ie t \(bu
.el o
Count of current P1 \fBSA\fRs which the local entity initiated
.RE
.RS +4
.TP
.ie t \(bu
.el o
Count of current P1 \fBSA\fRs where the local entity was the responder
.RE
.RS +4
.TP
.ie t \(bu
.el o
Count of all P1 \fBSA\fRs which the local entity initiated since boot
.RE
.RS +4
.TP
.ie t \(bu
.el o
Count of all P1 \fBSA\fRs where the local entity was the responder since boot
.RE
.RS +4
.TP
.ie t \(bu
.el o
Count of all attempted \fBP1\fR \fBSA\fRs since boot, where the local entity
was the initiator; includes failed attempts
.RE
.RS +4
.TP
.ie t \(bu
.el o
Count of all attempted P1 \fBSA\fRs since boot, where the local entity was the
responder; includes failed attempts
.RE
.RS +4
.TP
.ie t \(bu
.el o
Count of all failed attempts to initiate a \fBP1\fR \fBSA\fR, where the failure
occurred because the peer did not respond
.RE
.RS +4
.TP
.ie t \(bu
.el o
Count of all failed attempts to initiate a P1 \fBSA\fR, where the peer
responded
.RE
.RS +4
.TP
.ie t \(bu
.el o
Count of all failed \fBP1\fR \fBSA\fRs where the peer was the initiator
.RE
.RS +4
.TP
.ie t \(bu
.el o
Whether a PKCS#11 library is in use, and if applicable, the PKCS#11 library
that is loaded. See .
.RE
.RE

.sp
.ne 2
.na
\fBdefaults\fR
.ad
.sp .6
.RS 4n
Display default values used by the \fBin.iked\fR daemon. Some values can be
overriden in the daemon configuration file (see \fBike.config\fR(4)); for these
values, the token name is displayed in the \fBget defaults\fR output. The
output will reflect where a configuration token has changed the default.
.sp
Default values might be ignored in the event a peer system makes a valid
alternative proposal or they can be overriden by per-rule values established in
\fBike.config\fR. In such instances, a \fBget defaults\fR command continues to
display the default values, not the values used to override the defaults.
.RE

.sp
.ne 2
.na
\fBp1\fR
.ad
.sp .6
.RS 4n
An \fBIKE\fR Phase 1 \fBSA\fR. A \fBp1\fR object is identified by an \fBIP\fR
address pair or a cookie pair; identification formats are described below.
.RE

.sp
.ne 2
.na
\fBrule\fR
.ad
.sp .6
.RS 4n
An \fBIKE\fR policy rule, defining the acceptable security characteristics for
Phase 1 \fBSA\fRs between specified local and remote identities. A rule is
identified by its label; identification formats are described below.
.RE

.sp
.ne 2
.na
\fBpreshared\fR
.ad
.sp .6
.RS 4n
A preshared key, including the local and remote identification and applicable
\fBIKE\fR mode. A preshared key is identified by an \fBIP\fR address pair or an
identity pair; identification formats are described below.
.RE

.SS "Id Formats"
.sp
.LP
Commands like \fBadd\fR, \fBdel\fR, and \fBget\fR require that additional
information be specified on the command line. In the case of the delete and get
commands, all that is required is to minimally identify a given object; for the
add command, the full object must be specified.
.sp
.LP
Minimal identification is accomplished in most cases by a pair of values. For
\fBIP\fR addresses, the local addr and then the remote addr are specified,
either in dot-notation for IPv4 addresses, colon-separated hexadecimal format
for IPv6 addresses, or a host name present in the host name database. If a host
name is given that expands to more than one address, the requested operation
will be performed multiple times, once for each possible combination of
addresses.
.sp
.LP
Identity pairs are made up of a local type-value pair, followed by the remote
type-value pair. Valid types are:
.sp
.ne 2
.na
\fBprefix\fR
.ad
.sp .6
.RS 4n
An address prefix.
.RE

.sp
.ne 2
.na
\fBfqdn\fR
.ad
.sp .6
.RS 4n
A fully-qualified domain name.
.RE

.sp
.ne 2
.na
\fBdomain\fR
.ad
.sp .6
.RS 4n
Domain name, synonym for fqdn.
.RE

.sp
.ne 2
.na
\fBuser_fqdn\fR
.ad
.sp .6
.RS 4n
User identity of the form \fIuser\fR@fqdn.
.RE

.sp
.ne 2
.na
\fBmailbox\fR
.ad
.sp .6
.RS 4n
Synonym for \fBuser_fqdn\fR.
.RE

.sp
.LP
A cookie pair is made up of the two cookies assigned to a Phase 1 Security
Association (\fBSA\fR) when it is created; first is the initiator's, followed
by the responder's. A cookie is a 64-bit number.
.sp
.LP
Finally, a label (which is used to identify a policy rule) is a character
string assigned to the rule when it is created.
.sp
.LP
Formatting a rule or preshared key for the add command follows the format rules
for the in.iked configuration files. Both are made up of a series of id-value
pairs, contained in curly braces (\fB{\fR and \fB}\fR). See \fBike.config\fR(4)
and \fBike.preshared\fR(4) for details on the formatting of rules and preshared
keys.
.SH SECURITY
.sp
.LP
The \fBikeadm\fR command allows a privileged user to enter cryptographic keying
information. If an adversary gains access to such information, the security of
IPsec traffic is compromised. The following issues should be taken into account
when using the \fBikeadm\fR command.
.RS +4
.TP
.ie t \(bu
.el o
Is the \fBTTY\fR going over a network (interactive mode)?
.sp
If it is, then the security of the keying material is the security of the
network path for this \fBTTY\fR's traffic. Using \fBikeadm\fR over a clear-text
telnet or rlogin session is risky. Even local windows may be vulnerable to
attacks where a concealed program that reads window events is present.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Is the file accessed over the network or readable to the world (read/write
commands)?
.sp
A network-mounted file can be sniffed by an adversary as it is being read. A
world-readable file with keying material in it is also risky.
.RE
.sp
.LP
If your source address is a host that can be looked up over the network, and
your naming system itself is compromised, then any names used will no longer be
trustworthy.
.sp
.LP
Security weaknesses often lie in misapplication of tools, not the tools
themselves. It is recommended that administrators are cautious when using the
\fBikeadm\fR command. The safest mode of operation is probably on a console, or
other hard-connected \fBTTY\fR.
.sp
.LP
For additional information regarding this subject, see the afterward by Matt
Blaze in Bruce Schneier's \fIApplied Cryptography: Protocols, Algorithms, and
Source Code in C.\fR
.SH EXAMPLES
.LP
\fBExample 1 \fREmptying out all Phase 1 Security Associations
.sp
.LP
The following command empties out all Phase 1 Security Associations:

.sp
.in +2
.nf
example# \fBikeadm flush p1\fR
.fi
.in -2
.sp

.LP
\fBExample 2 \fRDisplaying all Phase 1 Security Associations
.sp
.LP
The following command displays all Phase 1 Security Associations:

.sp
.in +2
.nf
example# \fBikeadm dump p1\fR
.fi
.in -2
.sp

.LP
\fBExample 3 \fRDeleting a Specific Phase 1 Security Association
.sp
.LP
The following command deletes the specified Phase 1 Security Associations:

.sp
.in +2
.nf
example# \fBikeadm del p1 local_ip remote_ip\fR
.fi
.in -2
.sp

.LP
\fBExample 4 \fRAdding a Rule From a File
.sp
.LP
The following command adds a rule from a file:

.sp
.in +2
.nf
example# \fBikeadm add rule rule_file\fR
.fi
.in -2
.sp

.LP
\fBExample 5 \fRAdding a Preshared Key
.sp
.LP
The following command adds a preshared key:

.sp
.in +2
.nf
example# \fBikeadm\fR
     ikeadm> \fBadd preshared { localidtype ip localid local_ip
             remoteidtype ip remoteid remote_ip ike_mode main
             key 1234567890abcdef1234567890abcdef }\fR
.fi
.in -2
.sp

.LP
\fBExample 6 \fRSaving All Preshared Keys to a File
.sp
.LP
The following command saves all preshared keys to a file:

.sp
.in +2
.nf
example# \fBikeadm write preshared target_file\fR
.fi
.in -2
.sp

.LP
\fBExample 7 \fRViewing a Particular Rule
.sp
.LP
The following command views a particular rule:

.sp
.in +2
.nf
example# \fBikeadm get rule rule_label\fR
.fi
.in -2
.sp

.LP
\fBExample 8 \fRReading in New Rules from \fBike.config\fR
.sp
.LP
The following command reads in new rules from the ike.config file:

.sp
.in +2
.nf
example# \fBikeadm read rules\fR
.fi
.in -2
.sp

.LP
\fBExample 9 \fRLowering the Privilege Level
.sp
.LP
The following command lowers the privilege level:

.sp
.in +2
.nf
example# \fBikeadm set priv base\fR
.fi
.in -2
.sp

.LP
\fBExample 10 \fRViewing the Debug Level
.sp
.LP
The following command shows the current debug level

.sp
.in +2
.nf
example# \fBikeadm get debug\fR
.fi
.in -2
.sp

.LP
\fBExample 11 \fRUsing stats to Verify Hardware Accelerator
.sp
.LP
The following example shows how stats may include an optional line at the end
to indicate if IKE is using a PKCS#11 library to accelerate public-key
operations, if applicable.

.sp
.in +2
.nf
example# \fBikeadm get stats\fR
Phase 1 SA counts:
Current:  initiator:     0    responder:      0
Total:    initiator:    21   responder:      27
Attempted:initiator:    21   responder:      27
Failed:   initiator:     0   responder:       0
	         initiator fails include 0 time-out(s)
PKCS#11 library linked in from /opt/SUNWconn/lib/libpkcs11.so
example#
.fi
.in -2
.sp

.LP
\fBExample 12 \fRDisplaying the Certificate Cache
.sp
.LP
The following command shows the certificate cache and the status of associated
private keys, if applicable:

.sp
.in +2
.nf
example# \fBikeadm dump certcache\fR
.fi
.in -2
.sp

.LP
\fBExample 13 \fRLogging into a PKCS#11 Token
.sp
.LP
The following command shows logging into a PKCS#11 token object and unlocking
private keys:

.sp
.in +2
.nf
example# \fBikeadm token login "Sun Metaslot"\fR
Enter PIN for PKCS#11 token:
ikeadm: PKCS#11 operation successful
.fi
.in -2
.sp

.SH EXIT STATUS
.sp
.LP
The following exit values are returned:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 12n
Successful completion.
.RE

.sp
.ne 2
.na
\fB\fBnon-zero\fR\fR
.ad
.RS 12n
An error occurred. Writes an appropriate error message to standard error.
.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	Not an Interface
.TE

.SH SEE ALSO
.sp
.LP
\fBin.iked\fR(1M), \fBike.config\fR(4), \fBike.preshared\fR(4),
\fBattributes\fR(5), \fBipsec\fR(7P)
.sp
.LP
Schneier, Bruce, \fIApplied Cryptography: Protocols, Algorithms, and Source
Code in C\fR, Second Edition, John Wiley & Sons, New York, NY, 1996.
.SH NOTES
.sp
.LP
As \fBin.iked\fR can run only in the global zone and exclusive-IP zones, this
command is not useful in shared-IP zones.