Using the pwtokey facility

z/OS® Communications Server provides a facility called pwtokey that allows conversion of passwords into localized and non-localized authentication and privacy keys, for SNMP or OMPROUTE.

For OMPROUTE, pwtokey takes as input a password and generates an authentication key. No localized or privacy keys are needed or generated for OMPROUTE. Some restrictions apply when using pwtokey for OMPROUTE. See the description of the password parameter for more information.
For SNMP, the pwtokey procedure takes as input a password and an identifier of the agent and generates authentication and privacy keys. The procedure used by the pwtokey facility is the same algorithm used by the z/OS UNIX snmp command. The person configuring the SNMP agent can generate appropriate authentication and privacy keys to put in the SNMPD.CONF file for a user, given a particular password and the IP address at which the agent runs.
Tip: For privacy, encryption requires the use of keys of 32 hexadecimal digits (16 bytes) in length. However, if the key is generated by using HMAC-SHA, which produces keys of 40 hexadecimal digits (20 bytes) in length, the truncation from 40 to 32 hexadecimal digits is not done until after the key is localized. Therefore, a non-localized privacy key generated using HMAC-SHA is 40 hexadecimal digits (20 bytes) long, and a localized privacy key generated using HMAC-SHA is 32 hexadecimal digits (16 bytes) long. A privacy key generated with HMAC-MD5 (localized or not) is 32 hexadecimal digits (16 bytes) long.

To convert passwords into authentication and privacy keys, issue the following command from z/OS UNIX to use the pwtokey facility.

Format


                     .- -d--0-.  .- -p HMAC-MD5-.   
>>-pwtokey--+-----+--+--------+--+--------------+--------------->
            '- -e-'  '- -d--n-'  +- -p HMAC-SHA-+   
                                 '- -p all------'   

   .- -u auth------.                                     
>--+---------------+--+-----+--password--+-----------+---------><
   '- -u key_usage-'  '- -s-'            +-IPaddress-+   
                                         +-hostname--+   
                                         '-engineID--'

Parameters

-e

This flag indicates that the agent for which the key is being defined is identified by engineID rather than by IP address or host name. This is applicable only when generating keys for SNMP.

-d n

This flag indicates what level of debug information is wanted. Debug tracing is either on or off, so a value of 1 causes debug tracing to be generated to the screen of the command issuer (sysout), and a value of 0 specifies that no debug tracing be generated. Debug tracing is off (0) by default.

-p protocol

This flag indicates the protocols for which the keys are generated. Valid values are:

HMAC-MD5: Generates keys for use with the HMAC-MD5 authentication protocol. This is the only protocol to use when generating OSPF MD5 keys for OMPROUTE.
HMAC-SHA: Generates keys for use with the HMAC-SHA authentication protocol.
all: Generates both HMAC-MD5 and HMAC-SHA keys.

The default is that keys for the HMAC-MD5 protocol are generated.

-u key_usage

This flag indicates the usage intended for the key. Valid values are:

auth: An authentication key. This is the recommended usage for generating OSPF MD5 keys for OMPROUTE.
priv: A privacy key.
all: Both authentication and privacy keys.
Note: There is no difference between a key generated for authentication and a key generated for privacy. However, the length of privacy keys depends on whether the key is localized or not.

-s

This flag indicates that output data is displayed with additional spaces to improve readability. By default, data is displayed in a condensed format to facilitate cut-and-paste operations on the keys into configuration files or command lines.

password

Specifies the text string to be used in generating the keys. The password must be in the range of 8–255 characters long. In general, while any printable characters can be used in the passwords, the z/OS UNIX shell might interpret some characters rather than passing them to the pwtokey command. Include passwords in single quotation marks to avoid interpretation of the characters by the z/OS UNIX shell.

Note:

This password is not related to the community name (or password) used with community-based security (SNMPv1 and SNMPv2c). This password is used only to generate keys for user-based security, an entirely different security scheme.
For easier OMPROUTE migration from password to MD5 authentication, you can base the input password on the OMPROUTE password (there is no requirement for you to do so). Because the input password must be at least 8 characters and OMPROUTE supports passwords as few as 1 character, it might be necessary for you to pad or otherwise alter the OMPROUTE password to bring it up to 8 characters. Some restrictions apply when using PWTOKEY for OMPROUTE. See the MD5 Authentication specification for OMPROUTE in the z/OS Communications Server: IP Configuration Reference.

IPaddress

Specifies the IP address in IPv4 dotted decimal or IPv6 colon hexadecimal notation of the SNMP agent at which the key will be used on an SNMP request. This parameter is used only in generation of the localized key, and is not needed when generating MD5 keys for OMPROUTE.

hostname

Specifies the SNMP agent at which the key will be used on an SNMP request. This parameter is used only in generation of the localized key and is not needed when generating MD5 keys for OMPROUTE.

engineID

Specifies the engine ID of the SNMP agent at which the key will be used. The engine ID is determined at SNMP agent initialization from the SNMPD.BOOTS file. The engine ID must be a string of 1–32 octets (2–64 hexadecimal digits). If the engineID is specified, the -e option must also be specified. The default is that the agent identification is not an engine ID. This parameter is used only in generation of the localized key and is not needed when generating MD5 keys for OMPROUTE.

Examples

Sample output from the pwtokey command:

# pwtokey testpassword 9.67.113.79
Display of 16 byte HMAC-MD5 authKey:  
 775b109f79a6b71f94cca5d22451cc0e
 
Display of 16 byte HMAC-MD5 localized authKey:
 de25243d5c2765f0ce273e4bcf941701

pwtokey generates two keys – one that is localized (has been tailored to be usable only at the agent identified) and one that has not been localized. Typically, the localized key is used in the configuration for the SNMP agent. The nonlocalized key is used in the configuration for the snmp command.

If pwtokey is invoked requesting HMAC-SHA keys for both authentication and privacy, the output looks like this:

# pwtokey -p HMAC-SHA -u all testpassword 9.67.113.79   
Display of 20 byte HMAC-SHA authKey:                     
 b267809aee4b8ef450a7872d6e348713f04b9c50
 
Display of 20 byte HMAC-SHA localized authKey:
 e5438092d1098a43e27e507e50d32c0edaa39b7c
 
Display of 20 byte HMAC-SHA privKey:
 b267809aee4b8ef450a7872d6e348713f04b9c50
 
Display of 16 byte HMAC-SHA localized privKey: 
 e5438092d1098a43e27e507e50d32c0e

The output for the privacy keys is the same as the output for the authentication keys, except that the localized privacy key has been truncated to 16 bytes Start of change

as is required End of change

Note: If encryption is used, it is more secure to use different passwords for authentication and privacy.

If pwtokey is invoked requesting an MD5 authentication key for OMPROUTE, the output looks like this:

 # pwtokey testpassword    
 Display of 16 byte HMAC-MD5 authKey:  
  775b109f79a6b71f94cca5d22451cc0e

Usage

If the IP address or the host name is specified, the SNMP agent must be an IBM® agent. The engineID is created using a vendor-specific formula that incorporates the IP address of the agent and an Enterprise ID representing IBM.