Tribblix: manual page: ikeadm.8

IKEADM(8) Maintenance Commands and Procedures IKEADM(8)

NAME

ikeadm - manipulate Internet Key Exchange (IKE) parameters and state

SYNOPSIS

ikeadm [-np]

ikeadm [-np] get [debug | priv | stats | defaults]

ikeadm [-np] set [debug | priv] [level] [file]

ikeadm [-np] [get | del] [p1 | rule | preshared] [id]

ikeadm [-np] add [rule | preshared] { description }

ikeadm [-np] token [login | logout] PKCS#11_Token_Object

ikeadm [-np] [read | write] [rule | preshared | certcache] file

ikeadm [-np] [dump | pls | rule | preshared]

ikeadm [-np] flush [p1 | certcache]

ikeadm help
[get | set | add | del | read | write | dump | flush | token]

DESCRIPTION

The ikeadm utility retrieves information from and manipulates the
configuration of the Internet Key Exchange (IKE) protocol daemon,
in.iked(8).

ikeadm supports a set of operations, which may be performed on one or
more of the supported object types. When invoked without arguments,
ikeadm 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.

Because ikeadm 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.

For details on how to use this command securely see .

OPTIONS

The following options are supported:

-n

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.

-p

Paranoid. Do not print any keying material, even if saving
Security Associations. Instead of an actual hexadecimal digit,
print an X when this flag is turned on.

USAGE

Commands

The following commands are supported:

add

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 ID FORMATS
section.

del

Delete a specific object or objects from in.iked's current
configuration. This operation is available for IKE (Phase 1)
SAs, policy rules, and preshared keys. The object to be deleted
is specified as described in the Id Formats.

dump

Display all objects of the specified type known to in.iked. This
option can be used to display all Phase 1 SAs, policy rules,
preshared keys, or the certificate cache. A large amount of
output may be generated by this command.

flush

Remove all IKE (Phase 1) SAs or cached certificates from in.iked.

Note that flushing the certcache will also (as a side-effect)
update IKE with any new certificates added or removed.

get

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 IKE (Phase 1) SA, 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.

help

Print a brief summary of commands, or, when followed by a
command, prints information about that command.

read

Update the current in.iked configuration by reading the policy
rules or preshared keys from either the default location or from
the file specified.

set

Adjust the current debug or privilege level. If the debug level
is being modified, an output file may optionally be specified;
the output file must 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.

write

Write the current in.iked 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.

token

Log into a PKCS#11 token object and grant access to keying
material or log out and invalidate access to keying material.

token can be run as a normal user with the following
authorizations:

o token login: solaris.network.ipsec.ike.token.login

o token logout: solaris.network.ipsec.ike.token.logout

Object Types

debug

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.

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

When specifying the debug level, either a number (decimal or
hexadecimal) or a string of nicknames may be given. For example,
88, 0x58, and phase1+phase2+policy are all equivalent, and will
turn on debug for phase 1 sa creation, phase 2 sa creation, and
policy management. A string of nicknames may also be used to
remove certain types of information; all-op has the effect of
turning on all debug except for operational messages; it is
equivalent to the numbers 1019 or 0x3fb.

priv

Specifies the daemon's access privilege level. The possible
values are:

Description Level Nickname
Base level 0 base
Access to preshared key info 1 modkeys
Access to keying material 2 keymat

By default, in.iked is started at the base level. A command-line
option can be used to start the daemon at a higher level. ikeadm
can be used to lower the level, but it cannot be used to raise
the level.

Either the numerical level or the nickname may be used to specify
the target privilege level.

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 SAs.

stats

Global statistics from the daemon, covering both successful and
failed Phase 1 SA creation.

Reported statistics include:

o Count of current P1 SAs which the local entity
initiated

o Count of current P1 SAs where the local entity was the
responder

o Count of all P1 SAs which the local entity initiated
since boot

o Count of all P1 SAs where the local entity was the
responder since boot

o Count of all attempted P1 SAs since boot, where the
local entity was the initiator; includes failed
attempts

o Count of all attempted P1 SAs since boot, where the
local entity was the responder; includes failed
attempts

o Count of all failed attempts to initiate a P1 SA,
where the failure occurred because the peer did not
respond

o Count of all failed attempts to initiate a P1 SA,
where the peer responded

o Count of all failed P1 SAs where the peer was the
initiator

o Whether a PKCS#11 library is in use, and if
applicable, the PKCS#11 library that is loaded. See .

defaults

Display default values used by the in.iked daemon. Some values
can be overridden in the daemon configuration file (see
ike.config(5)); for these values, the token name is displayed in
the get defaults output. The output will reflect where a
configuration token has changed the default.

Default values might be ignored in the event a peer system makes
a valid alternative proposal or they can be overridden by per-
rule values established in ike.config. In such instances, a get
defaults command continues to display the default values, not the
values used to override the defaults.

p1

An IKE Phase 1 SA. A p1 object is identified by an IP address
pair or a cookie pair; identification formats are described
below.

rule

An IKE policy rule, defining the acceptable security
characteristics for Phase 1 SAs between specified local and
remote identities. A rule is identified by its label;
identification formats are described below.

preshared

A preshared key, including the local and remote identification
and applicable IKE mode. A preshared key is identified by an IP
address pair or an identity pair; identification formats are
described below.

Id Formats

Commands like add, del, and get 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.

Minimal identification is accomplished in most cases by a pair of
values. For IP 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.

Identity pairs are made up of a local type-value pair, followed by
the remote type-value pair. Valid types are:

prefix

An address prefix.

fqdn

A fully-qualified domain name.

domain

Domain name, synonym for fqdn.

user_fqdn

User identity of the form user@fqdn.

mailbox

Synonym for user_fqdn.

A cookie pair is made up of the two cookies assigned to a Phase 1
Security Association (SA) when it is created; first is the
initiator's, followed by the responder's. A cookie is a 64-bit
number.

Finally, a label (which is used to identify a policy rule) is a
character string assigned to the rule when it is created.

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 ({ and }). See
ike.config(5) and ike.preshared(5) for details on the formatting of
rules and preshared keys.

SECURITY

The ikeadm 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 ikeadm command.

o Is the TTY going over a network (interactive mode)?

If it is, then the security of the keying material is the
security of the network path for this TTY's traffic. Using
ikeadm 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.

o Is the file accessed over the network or readable to the
world (read/write commands)?

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.

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.

Security weaknesses often lie in misapplication of tools, not the
tools themselves. It is recommended that administrators are cautious
when using the ikeadm command. The safest mode of operation is
probably on a console, or other hard-connected TTY.

For additional information regarding this subject, see the afterward
by Matt Blaze in Bruce Schneier's Applied Cryptography: Protocols,
Algorithms, and Source Code in C.

EXAMPLES

Example 1: Emptying out all Phase 1 Security Associations

The following command empties out all Phase 1 Security Associations:

example# ikeadm flush p1

Example 2: Displaying all Phase 1 Security Associations

The following command displays all Phase 1 Security Associations:

example# ikeadm dump p1

Example 3: Deleting a Specific Phase 1 Security Association

The following command deletes the specified Phase 1 Security
Associations:

example# ikeadm del p1 local_ip remote_ip

Example 4: Adding a Rule From a File

The following command adds a rule from a file:

example# ikeadm add rule rule_file

Example 5: Adding a Preshared Key

The following command adds a preshared key:

example# ikeadm
ikeadm> add preshared { localidtype ip localid local_ip
remoteidtype ip remoteid remote_ip ike_mode main
key 1234567890abcdef1234567890abcdef }

Example 6: Saving All Preshared Keys to a File

The following command saves all preshared keys to a file:

example# ikeadm write preshared target_file

Example 7: Viewing a Particular Rule

The following command views a particular rule:

example# ikeadm get rule rule_label

Example 8: Reading in New Rules from ike.config

The following command reads in new rules from the ike.config file:

example# ikeadm read rules

Example 9: Lowering the Privilege Level

The following command lowers the privilege level:

example# ikeadm set priv base

Example 10: Viewing the Debug Level

The following command shows the current debug level

example# ikeadm get debug

Example 11: Using stats to Verify Hardware Accelerator

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.

example# ikeadm get stats
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#

Example 12: Displaying the Certificate Cache

The following command shows the certificate cache and the status of
associated private keys, if applicable:

example# ikeadm dump certcache

Example 13: Logging into a PKCS#11 Token

The following command shows logging into a PKCS#11 token object and
unlocking private keys:

example# ikeadm token login "Sun Metaslot"
Enter PIN for PKCS#11 token:
ikeadm: PKCS#11 operation successful

EXIT STATUS

The following exit values are returned:

0
Successful completion.

non-zero
An error occurred. Writes an appropriate error message to
standard error.

ATTRIBUTES

NOTES

As in.iked can run only in the global zone and exclusive-IP zones,
this command is not useful in shared-IP zones.

January 27, 2009 IKEADM(8)