System Administration Commands ipseckey(1M) NAME ipseckey - manually manipulate an IPsec Security Association Database (SADB) SYNOPSIS ipseckey [-nvp] ipseckey [-nvp] -f filename ipseckey -c filename ipseckey [-nvp] [delete | get] SA_TYPE {EXTENSION value...} ipseckey [-np] [monitor | passive_monitor | pmonitor] ipseckey [-nvp] flush {SA_TYPE} ipseckey [-nvp] dump {SA_TYPE} ipseckey [-nvp] save SA_TYPE {filename} ipseckey [-nvp] -s filename DESCRIPTION The ipseckey command is used to manually manipulate the security association databases of the network security ser- vices, ipsecah(7P) and ipsecesp(7P). You can use the ipseckey command to set up security associations between communicating parties when automated key management is not available. While the ipseckey utility has only a limited number of gen- eral options, it supports a rich command language. The user may specify requests to be delivered by means of a program- matic interface specific for manual keying. See pf_key(7P). When ipseckey is invoked with no arguments, it will enter an interactive mode which prints a prompt to the standard out- put and accepts commands from the standard input until the end-of-file is reached. Some commands require an explicit security association ("SA") type, while others permit the SA type to be unspecified and act on all SA types. ipseckey uses a PF_KEY socket and the message types SADB_ADD, SADB_DELETE, SADB_GET, SADB_UPDATE, SADB_FLUSH, and SADB_X_PROMISC. Thus, you must be a superuser to use this command. SunOS 5.11 Last change: 1 Sep 2006 1 System Administration Commands ipseckey(1M) ipseckey handles sensitive cryptographic keying information. Please read the section for details on how to use this com- mand securely. OPTIONS -f [filename] Read commands from an input file, filename. The lines of the input file are identical to the command line language. The load command provides similar functional- ity. The -s option or the save command can generate files readable by the -f argument. See SECURITY and SMF for more information. -c [filename] As the -f option except that the input is only checked for syntactical correctness, errors are reported to stderr. This option is provided to debug configurations without making changes. See SECURITY and SMF for more information. -n Prevent attempts to print host and network names symbol- ically when reporting actions. This is useful, for exam- ple, when all name servers are down or are otherwise unreachable. -p Paranoid. Do not print any keying material, even if sav- ing SAs. Instead of an actual hexadecimal digit, print an X when this flag is turned on. -s [filename] The opposite of the -f option. If '-' is given for a filename, then the output goes to the standard output. A snapshot of all current SA tables will be output in a form readable by the -f option. The output will be a series of add commands, but with some names not used. This occurs because a single name may often indicate multiple addresses. SunOS 5.11 Last change: 1 Sep 2006 2 System Administration Commands ipseckey(1M) -v Verbose. Print the messages being sent into the PF_KEY socket, and print raw seconds values for lifetimes. COMMANDS add Add an SA. Because it involves the transfer of keying material, it cannot be invoked from the shell, lest the keys be visible in ps(1) output. It can be used either from the interactive ipseckey> prompt or in a command file specified by the -f command. The add command accepts all extension-value pairs described below. update Update SA lifetime, and in the cases of larval SAs (leftover from aborted automated key management), keying material and other extensions. Like add, this command cannot be invoked from the shell because keying material would be seen by the ps(1) command. It can be used either from the interactive ipseckey> prompt or in a command file specified by the -f command. The update command accepts all extension-value pairs, but normally is only used for SA lifetime updates. delete Delete a specific SA from a specific SADB. This command requires the spi extension, and the dest extension for IPsec SAs. Other extension-value pairs are superfluous for a delete message. get SunOS 5.11 Last change: 1 Sep 2006 3 System Administration Commands ipseckey(1M) Lookup and display a security association from a specific SADB. Like delete, this command only requires spi and dest for IPsec. flush Remove all SA for a given SA_TYPE, or all SA for all types. monitor Continuously report on any PF_KEY messages. This uses the SADB_X_PROMISC message to enable messages that a normal PF_KEY socket would not receive to be received. See pf_key(7P). passive_monitor Like monitor, except that it does not use the SADB_X_PROMISC message. pmonitor Synonym for passive_monitor. dump Will display all SAs for a given SA type, or will display all SAs. Because of the large amount of data generated by this command, there is no guarantee that all SA information will be successfully delivered, or that this command will even complete. SunOS 5.11 Last change: 1 Sep 2006 4 System Administration Commands ipseckey(1M) save Is the command analog of the -s option. It is included as a command to provide a way to snapshot a particular SA type, for example, esp or ah. help Prints a brief summary of commands. SA_TYPE all Specifies all known SA types. This type is only used for the flush and dump commands. This is equivalent to hav- ing no SA type for these commands. ah Specifies the IPsec Authentication Header ("AH") SA. esp Specifies the IPsec Encapsulating Security Payload ("ESP") SA. EXTENSION VALUE TYPES Commands like add, delete, get, and update require that cer- tain extensions and associated values be specified. The extensions will be listed here, followed by the commands that use them, and the commands that require them. Require- ments are currently documented based upon the IPsec SunOS 5.11 Last change: 1 Sep 2006 5 System Administration Commands ipseckey(1M) definitions of an SA. Required extensions may change in the future. can be in either hex (0xnnn), decimal (nnn) or octal (0nnn). is a text string. is a long hexadecimal number with a bit-length. Extensions are usually paired with values; however, some extensions require two values after them. spi Specifies the security parameters index of the SA. This extension is required for the add, delete, get and update commands. replay Specifies the replay window size. If not specified, the replay window size is assumed to be zero. It is not recommended that manually added SAs have a replay win- dow. This extension is used by the add and update com- mands. state | Specifies the SA state, either by numeric value or by the strings "larval", "mature", "dying" or "dead". If not specified, the value defaults to mature. This exten- sion is used by the add and update commands. auth_alg | authalg | Specifies the authentication algorithm for an SA, either by numeric value, or by strings indicating an algorithm name. Current authentication algorithms include: SunOS 5.11 Last change: 1 Sep 2006 6 System Administration Commands ipseckey(1M) HMAC-MD5 md5, hmac-md5 HMAC-SH-1 sha, sha-1, hmac-sha1, hmac-sha Often, algorithm names will have several synonyms. This extension is required by the add command for certain SA types. It is also used by the update command. Use the ipsecalgs(1M) command to obtain the complete list of authentication algorithms. encr_alg | encralg | Specifies the encryption algorithm for an SA, either by numeric value, or by strings indicating an algorithm name. Current encryption algorithms include DES ("des"), Triple-DES ("3des"), Blowfish ("blowfish"), and AES ("aes"). This extension is required by the add command for certain SA types. It is also used by the update com- mand. Use the ipsecalgs(1M) command to obtain the complete list of encryption algorithms. The next six extensions are lifetime extensions. There are two varieties, "hard" and "soft". If a hard lifetime expires, the SA will be deleted automatically by the system. If a soft lifetime expires, an SADB_EXPIRE message will be transmitted by the system, and its state will be downgraded SunOS 5.11 Last change: 1 Sep 2006 7 System Administration Commands ipseckey(1M) to dying from mature. See pf_key(7P). The monitor command to key allows you to view SADB_EXPIRE messages. soft_bytes hard_bytes Specifies the number of bytes that this SA can protect. If this extension is not present, the default value is zero, which means that the SA will not expire based on the number of bytes protected. This extension is used by the add and update commands. soft_addtime hard_addtime Specifies the number of seconds that this SA can exist after being added or updated from a larval SA. An update of a mature SA does not reset the initial time that it was added. If this extension is not present, the default value is zero, which means the SA will not expire based on how long it has been since it was added. This exten- sion is used by the add and update commands. soft_usetime hard_usetime Specifies the number of seconds this SA can exist after first being used. If this extension is not present, the default value is zero, which means the SA will not expire based on how long it has been since it was added. This extension is used by the add and update commands. saddr address | name srcaddr address | name saddr6 IPv6 address srcaddr6 IPv6 address src address | name src6 IPv6 address SunOS 5.11 Last change: 1 Sep 2006 8 System Administration Commands ipseckey(1M) srcaddr address and src address are synonyms that indi- cate the source address of the SA. If unspecified, the source address will either remain unset, or it will be set to a wildcard address if a destination address was supplied. To not specify the source address is valid for IPsec SAs. Future SA types may alter this assump- tion. This extension is used by the add, update, get and delete commands. daddr
| dstaddr
| daddr6 | dstaddr6 | dst | dst6 | dstaddr and dst are synonyms that indicate the destination address of the SA. If unspecified, the destination address will remain unset. Because IPsec SAs require a specified destination address and spi for identification, this extension, with a specific value, is required for the add, update, get and delete com- mands. If a name is given, ipseckey will attempt to invoke the command on multiple SAs with all of the destination addresses that the name can identify. This is similar to how ipsecconf handles addresses. If dst6 or dstaddr6 is specified, only the IPv6 addresses identified by a name are used. sport sport specifies the source port number for an SA. It should be used in combination with an upper-layer proto- col (see below), but it does not have to be. SunOS 5.11 Last change: 1 Sep 2006 9 System Administration Commands ipseckey(1M) dport sport specifies the destination port number for an SA. It should be used in combination with an upper-layer protocol (see below), but it does not have to be. proto ulp proto, and its synonym ulp, specify the IP protocol number of the SA. nat_loc
| If the local address in the SA (source or destination) is behind a NAT, this extension indicates the NAT node's globally-routable address. nat_rem
| If the remote address in the SA (source or destination) is behind a NAT, this extension indicates that node's internal (that is, behind-the-NAT) address. nat_lport Designation of a port for packets that use a local (to the current network) NAT node. Identifies the port on which encapsulation of the ESP occurs. nat_rport SunOS 5.11 Last change: 1 Sep 2006 10 System Administration Commands ipseckey(1M) Designation of a port for packets that will be subject to NAT on a remote network. Identifies the port on which encapsulation of the ESP occurs. isrc
| [/] innersrc
| [/] isrc6
| [/] innersrc6
| [/] proxyaddr
| [/] proxy
| [/] isrc
[/] and innersrc
[/] are synonyms. They indicate the inner source address for a tunnel-mode SA. An inner-source can be a prefix instead of an address. As with other address extensions, there are IPv6- specific forms. In such cases, use only IPv6-specific addresses or prefixes. Previous versions referred to this value as the proxy address. The usage, while deprecated, remains. idst
| [/] innerdst
| [/] idst6
| [/] innerdst6
| [/] idst
[/] and innerdst
[/] are synonyms. They indicate the inner destination address for a tunnel-mode SA. An inner-destination can be a prefix instead of an address. As with other address extensions, there are IPv6-specific forms. In such cases, use only IPv6- specific addresses or prefixes. SunOS 5.11 Last change: 1 Sep 2006 11 System Administration Commands ipseckey(1M) innersport isport innersport specifies the source port number of the inner header for a tunnel-mode SA. It should be used in combi- nation with an upper-layer protocol (see below), but it does not have to be. innerdport idport innerdport specifies the destination port number of the inner header for a tunnel-mode SA. It should be used in combination with an upper-layer protocol (see below), but it does not have to be. iproto iulp iproto, and its synonym iulp, specify the IP protocol number of the inner header of a tunnel-mode SA. authkey Specifies the authentication key for this SA. The key is expressed as a string of hexadecimal digits, with an optional / at the end, for example, 123/12. Bits are counted from the most-significant bits down. For exam- ple, to express three '1' bits, the proper syntax is the string "e/3". For multi-key algorithms, the string is the concatenation of the multiple keys. This extension is used by the add and update commands. encrkey Specifies the encryption key for this SA. The syntax of SunOS 5.11 Last change: 1 Sep 2006 12 System Administration Commands ipseckey(1M) the key is the same as authkey. A concrete example of a multi-key encryption algorithm is 3des, which would express itself as a 192-bit key, which is three 64-bit parity-included DES keys. This extension is used by the add and update commands. Certificate identities are very useful in the context of automated key management, as they tie the SA to the public key certificates used in most automated key management pro- tocols. They are less useful for manually added SAs. Unlike other extensions, srcidtype takes two values, a type, and an actual value. The type can be one of the following: prefix An address prefix. fqdn A fully-qualified domain name. domain Domain name, synonym for fqdn. user_fqdn SunOS 5.11 Last change: 1 Sep 2006 13 System Administration Commands ipseckey(1M) User identity of the form user@fqdn. mailbox Synonym for user_fqdn. The value is an arbitrary text string, which should identify the certificate. srcidtype Specifies a source certificate identity for this SA. This extension is used by the add and update commands. dstidtype Specifies a destination certificate identity for this SA. This extension is used by the add and update com- mands Tunnel Mode versus Transport Mode SAs An IPsec SA is a Tunnel Mode SA if the "proto" value is either 4 (ipip) or 41 (ipv6) and there is an inner-address or inner-port value specified. Otherwise, the SA is a Tran- sport Mode SA. SECURITY Keying material is very sensitive and should be generated as randomly as possible. Some algorithms have known weak keys. IPsec algorithms have built-in weak key checks, so that if a weak key is in a newly added SA, the add command will fail with an invalid value. The ipseckey command allows a privileged user to enter cryp- tographic 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 ipseckey command. SunOS 5.11 Last change: 1 Sep 2006 14 System Administration Commands ipseckey(1M) 1. Is the TTY going over a network (interactive mode)? o If it is, then the security of the keying material is the security of the network path for this TTY's traffic. Using ipseckey over a clear-text telnet or rlogin session is risky. o Even local windows may be vulnerable to attacks where a concealed program that reads window events is present. 2. Is the file accessed over the network or readable to the world (-f option)? o 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. 3. The ipseckey command is designed to be managed by the 'manual-key' smf(5) service. Because the smf(5) log files are world-readable, the ipseckey will not record any syntax errors in the log files as these errors might include secret information. If a syntax error is found when the 'manual-key' smf(5) service is enabled, the service will enter maintenance mode. The log file will indicate that there was a syntax error, but won't specify what the error was. The administrator should use ipeckey -c filename from the command line to discover the cause of the errors. See OPTIONS. 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. Administrators are urged to be cautious when using ipseckey. The safest mode of operation is probably on a console, or other hard-connected TTY. For further thoughts on this subject, see the afterward by Matt Blaze in Bruce Schneier's Applied Cryptography: SunOS 5.11 Last change: 1 Sep 2006 15 System Administration Commands ipseckey(1M) Protocols, Algorithms, and Source Code in C. EXAMPLES Example 1 Emptying Out All SAs To empty out all SA: example# ipseckey flush Example 2 Flushing Out IPsec AH SAs Only To flush out only IPsec AH SAs: example# ipseckey flush ah Example 3 Saving All SAs To Standard Output To save all SAs to the standard output: example# ipseckey save all Example 4 Saving ESP SAs To The File /tmp/snapshot To save ESP SAs to the file /tmp/snapshot: example# ipseckey save esp /tmp/snapshot Example 5 Deleting an IPsec SA To delete an IPsec SA, only the SPI and the destination address are needed: SunOS 5.11 Last change: 1 Sep 2006 16 System Administration Commands ipseckey(1M) example# ipseckey delete esp spi 0x2112 dst 224.0.0.1 Example 6 Getting Information on an IPsec SA Likewise, getting information on a SA only requires the des- tination address and SPI: example# ipseckey get ah spi 0x5150 dst mypeer Example 7 Adding or Updating IPsec SAs Adding or updating SAs requires entering interactive mode: example# ipseckey ipseckey> add ah spi 0x90125 src me.domain.com dst you.domain.com authalg md5 authkey 1234567890abcdef1234567890abcdef ipseckey> update ah spi 0x90125 dst you.domain.com hard_bytes 16000000 ipseckey> exit Example 8 Adding an SA in the Opposite Direction In the case of IPsec, SAs are unidirectional. To communicate securely, a second SA needs to be added in the opposite direction. The peer machine also needs to add both SAs. example# ipseckey ipseckey> add ah spi 0x2112 src you.domain.com dst me.domain.com authalg md5 authkey bde359723576fdea08e56cbe876e24ad hard_bytes 16000000 ipseckey> exit Example 9 Monitoring PF_KEY Messages Monitoring for PF_KEY messages is straightforward: SunOS 5.11 Last change: 1 Sep 2006 17 System Administration Commands ipseckey(1M) example# ipseckey monitor Example 10 Using Commands in a File Commands can be placed in a file that can be parsed with the -f option. This file may contain comment lines that begin with the "#" symbol. For example: # This is a sample file for flushing out the ESP table and # adding a pair of SAs. flush esp ### Watch out! I have keying material in this file. See the ### SECURITY section in this manual page for why this can be ### dangerous . add esp spi 0x2112 src me.domain.com dst you.domain.com authalg md5 authkey bde359723576fdea08e56cbe876e24ad encralg des encrkey be02938e7def2839 hard_usetime 28800 add esp spi 0x5150 src you.domain.com dst me.domain.com authalg md5 authkey 930987dbe09743ade09d92b4097d9e93 encralg des encrkey 8bd4a52e10127deb hard_usetime 28800 ## End of file - This is a gratuitous comment Example 11 Adding SAs for IPv6 Addresses The following commands from the interactive-mode create an SA to protect IPv6 traffic between the site-local addresses example # ipseckey ipseckey> add esp spi 0x6789 src6 fec0:bbbb::4483 dst6 fec0:bbbb::7843 authalg md5 authkey bde359723576fdea08e56cbe876e24ad encralg des encrkey be02938e7def2839 hard_usetime 28800 ipseckey>exit SMF IPsec manual keys are managed by the service management facility, smf(5). The following group of services manage the components of IPsec: svc:/network/ipsec/ipsecalgs (See ipsecalgs(1M)) svc:/network/ipsec/policy (See ipsecconf(1M)) svc:/network/ipsec/manual-key (See ipseckey(1M)) svc:/network/ipsec/ike (see ike.config(4)) The manual-key and policy services are delivered 'disabled' because the system administrator needs to create configuration files for each service as described in the respective man pages. Correct administrative proceedure is to create the configuration file for each service then enable each service using svcadm(1M). If the configuration needs to be changed, edit the configuration file then refresh the service. example# svcadm refresh manual-key WARNING: To prevent ipseckey complaining about duplicate Association's, the ipseckey command flushes the Security Association Data Base (SADB) when the ipseckey command is run from smf(5), before adding any new Security Association's defined in the configuration file. This differs from the command line behaviour where the SADB is not flushed before adding new Security Association's. The smf(5) framework will record any errors in the service specific logfile. Use any of the following commands to examine the 'logfile' property: example# svcs -l manual-key example# svcprop manual-key example# svccfg -s manual-key listprop The following property is defined for the 'manual-key' service: config/config_file This property can be modified using svccfg(1M) by users who have been assigned the following authorization: solaris.smf.value.ipsec See auths(1), user_attr(4), rbac(5). The service needs to be refreshed using svcadm(1M) before the new property is effective. General non-modifiable properties can be viewed with the svcprop(1M) command. example# svccfg -s ipsec/manual-key setprop config/config_file = /new/config_file example# svcadm refresh manual-key Administrative actions on this service, such as enabling, disabling, refreshing or requesting restart, can be performed using svcadm(1M). A user who has been assigned the following authorization can perform these actions: solaris.smf.manage.ipsec The service's status can be queried using the svcs(1) command. The ipseckey command is designed to be run under smf(5) management. It is possible to run ipseckey from the command line although this is discouraged. Before attempting to run ipseckey from the command line, make sure the 'manual-key' smf(5) service is disabled first. See svcadm(1M). ATTRIBUTES See attributes(5) for descriptions of the following attri- butes: SunOS 5.11 Last change: 1 Sep 2006 18 System Administration Commands ipseckey(1M) ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |_____________________________|_____________________________| | Availability | SUNWcsu | | Interface Stability | Evolving | |_____________________________|_____________________________| FILES /etc/inet/secret/ipseckeys The default configuration file used at boot time. See SMF and SECURITY for more information. SEE ALSO ps(1), ipsecconf(1M), ipsecalgs(1M), route(1M), attri- butes(5), ipsec(7P), ipsecah(7P), ipsecesp(7P), pf_key(7P), svcadm(1M), smf(5), svccfg(1M) Schneier, B., Applied Cryptography: Protocols, Algorithms, and Source Code in C. Second ed. New York, New York: John Wiley & Sons, 1996. DIAGNOSTICS The ipseckey command will parse the configuration file and report any errors. In the case of multiple errors, ipseckey will report as many of these as possible. The ipseckey command will not attempt to use a COMMAND that has a syntax error. A COMMAND may be syntactically correct but may generate an error because the kernel rejected the request made to pf_key(7), this might occur because a key had an invalid length or because an unsupported algorithm was specified. If there were any errors in the configuration file, ipseckey will report the number of valid COMMANDS and the total number of COMMANDS parsed. Parse error near line N. If an interactive use of ipseckey would print usage information, this would print instead. Usually proceeded by another diagnostic. Because COMMANDS can cover more than a single line in the configuration file by using the back-slash character to delimit lines, its not always possible to pinpoint the exact line in the config file which caused the error. Unexpected end of command line. An additional argument was expected on the command line. Unknown A value for a specific extension was unknown. SunOS 5.11 Last change: 1 Sep 2006 19 System Administration Commands ipseckey(1M) Address type N not supported. A name-to-address lookup returned an unsupported address family. N is not a bit specifier bit length N is too big for string is not a hex string Keying material was not entered appropriately. Can only specify single A duplicate extension was entered. Don't use extension for for . An extension not used by a command was used. Association (type = xx) with spi 0xNNNN and addr y.y.y.y already exists. Each Security Association must be unique, the kernel looks up each Security association using a tuple made from: The Protocol or type (ah or esp). The SPI value. The destination IP address. The error message warns the user that an attempt was made to add a new Security Association which has the same tuple as an existing entry in the Security Assocation Data Base. This error is most likely to occur when the ipseckey command is run mutiple times with the -f flag and the same configuration file. WARNING: Existing Security Associations are NOT replaced. If the values associated with each Protocol/SPI/Address tuple in the configuration file are the same as those loaded into the kernel, then this error can be ignored. If the values have been updated, then the administrator needs to remove the existing Security Association(s) with the delete or flush commands and then add the new Security Association(s) again using the -f flag. See SMF for more information. One of the entered values is incorrect: Diagnostic code NN: This is a general invalid parameter error. The diagnos- tic code and message provides more detail about what precise value was incorrect and why. NOTES In spite of its IPsec-specific name, ipseckey is analogous to route(1M), in that it is a command-line interface to a socket-based administration engine, in this case, PF_KEY. PF_KEY was originally developed at the United States Naval Research Laboratory. SunOS 5.11 Last change: 1 Sep 2006 20 System Administration Commands ipseckey(1M) To have machines communicate securely with manual keying, SAs need to be added by all communicating parties. If two nodes wish to communicate securely, both nodes need the appropriate SAs added. In the future ipseckey may be invoked under additional names as other security protocols become available to PF_KEY. This command requires sys_net_config privilege to operate and thus can run only in the global zone; security associa- tions managed by ipseckey can protect matching network traffic for any zone on the system. SunOS 5.11 Last change: 1 Sep 2006 21