HP TCP/IP Services for OpenVMS
Management

The cryptographic values used by the Autokey protocol are incorporated as a set of files generated by the ntp_keygen utility program, including symmetric key, host key and public certificate files, as well as sign key, identity parameters and leapseconds files. Alternatively, host and sign keys and certificate files can be generated by the OpenSSL utilities, and certificates can be imported from public certificate authorities. Note that symmetric keys are necessary for the ntpq and ntpdc utility programs. The remaining files are necessary only for the Autokey protocol.

Certificates imported from OpenSSL or public certificate authorities have certian limitations. The certificate should be in ASN.1 syntax, X.509 Version 3 format and encoded in PEM, which is the same format used by OpenSSL. The overall length of the certificate encoded in ASN.1 must not exceed 1024 bytes. The subject distinguished name field ( CN ) is the fully qualified name of the host on which it is used; the remaining subject fields are ignored. The certificate extension fields must not contain either a subject key identifier or a issuer key identifier field; however, an extended key usage field for a trusted host must contain the value trustRoot . Other extension fields are ignored.

13.7.6 Authentication Statements and Commands

Table 13-3 describes describes authentication statements and commands.

Table 13-3 Authentication Commands

Command	Description
autokey [ logsec]	Specifies the interval between regenerations of the session key list used with the Autokey protocol. Note that the size of the key list for each association depends on this interval and the current poll interval. The default value is 12 (4096 s or about 1.1 hours). For poll intervals above the specified interval, a session key list with a single entry will be regenerated for every message sent.
controlkey key-ID	Specifies the key identifier to use with the ntpq utility, which uses the standard protocol defined in RFC-1305. The key-ID argument is the key identifier for a trusted key, where the value can be in the range 1 to 65,534, inclusive.
crypto [cert file] [leap file] [randfile file] [host file] [sign file] [iffpar file] [gqpar file] [mvpar file] [pw password]	This command requires the OpenSSL library. It activates public key cryptography, selects the message digest and signature encryption scheme, and loads the required private and public values described above. If one or more files are left unspecified, the default names are used as described above. Unless the complete path and name of the file are specified, the location of a file is relative to the keys directory specified in the keysdir command or default SYS$SPECIFIC:[TCPIP$NTP] . Following are the subcommands: cert file : Specifies the location of the required host public certificate file. This overrides the link tcpip$ntpkey_cert_hostname in the keys directory. gqpar file : Specifies the location of the client GQ parameters file. This overrides the link tcpip$ntpkey_gq_hostname. in the keys directory. host file : Specifies the location of the required host key file. This overrides the link tcpip$ntpkey_key_hostname. in the keys directory. iffpar file : Specifies the location of the optional IFF parameters file. This overrides the link tcpip$ntpkey_iff_hostname. in the keys directory. leap file : Specifies the location of the client leapsecond file. This overrides the link tcpip$ntpkey_leap. in the keys directory. mvpar file : Specifies the location of the client MV parameters file. This overrides the link tcpip$ntpkey_mv_hostname. in the keys directory. pw password : Specifies the password to decrypt files containing private keys and identity parameters. This is required only if these files have been encrypted. randfile file : Specifies the location of the random seed file used by the OpenSSL library. The defaults are described in the main text above. sign file : Specifies the location of the optional sign key file. This overrides the link tcpip$ntpkey_sign_hostname. in the keys directory. If this file is not found, the host key is also the sign key.
keys keyfile	Specifies the complete path and location of the MD5 key file containing the keys and key identifiers used by the NTP server, ntpq , and ntpdc when operating with symmetric key cryptography.
keysdir path	This command specifies the default directory path for cryptographic keys, parameters and certificates. The default is SYS$SPECIFIC:[TCPIP$NTP] .
requestkey key-ID	Specifies the key identifier to use with the ntpdc utility program, which uses a proprietary protocol specific to this implementation of NTP. The key-ID argument is a key identifier for the trusted key, where the value can be in the range 1 to 65,534, inclusive.
revoke [logsec]	Specifies the interval between re-randomization of certain cryptographic values used by the Autokey scheme, as a power of 2 in seconds. These values need to be updated frequently in order to deflect brute-force attacks on the algorithms of the scheme; however, updating some values is a relatively expensive operation. The default interval is 16 (65,536 s or about 18 hours). For poll intervals above the specified interval, the values will be updated for every message sent.
trustedkey key-ID[...]	Specifies the key identifiers that are trusted for the purposes of authenticating peers with symmetric key cryptography, as well as keys used by the ntpq and ntpdc programs. The authentication procedures require that both the local and remote servers share the same key and key identifier for this purpose, although different keys can be used with different servers. The key-ID arguments are 32-bit unsigned integers with values from 1 to 65,534.

13.7.7 Error Code

Errors can occur due to mismatched configurations, unexpected restarts, expired certificates, and unfriendly people. In most cases the protocol state machine recovers automatically by retransmission, timeout and restart, where necessary. Some errors are due to mismatched keys, digest schemes or identity schemes and must be corrected by installing the correct media and/or correcting the configuration file. One of the most common errrors is expired certificates, which must be regenerated and signed at least once per year using the tcpip$ntp_keygen program.

The following error codes are reported via the NTP control and monitoring protocol trap mechanism.

Error	Description
101	Bad field format or length. The packet has invalid version, length or format.
102	Bad timestamp. The packet has invalid version, length or format.
103	Bad filestamp. The packet filestamp is the same or older than the most recent received. This could be due to a replay or a key file generation error.
104	Bad or missing public key. The public key is missing, has incorrect format or is an unsupported type.
105	Unsupported digest type. The server requires an unsupported digest/signature scheme.
106	Unsupported identity type. The client or server has requested an identity scheme the other does not support.
107	Bad signature length. The signature length does not match the current public key.
108	Signature not verified. The message fails the signature check. It could be bogus or signed by a different private key.
109	Certificate not verified. The certificate is invalid or signed with the wrong key.
110	Host certificate expired. The old server certificate has expired.
111	Bad or missing cookie. The cookie is missing, corrupted, or bogus.
112	Bad or missing leapseconds table. The leapseconds table is missing, corrupted, or bogus.
113	Bad or missing certificate. The certificate is missing, corrupted, or bogus.
114	Bad or missing group key. The identity key is missing, corrupt, or bogus.
115	Protocol error. The protocol state machine has wedged due to unexpected restart.
116	Server certificate expired. The old server certificate has expired.

13.7.8 Leapseconds Table

The NIST provides a file documenting the epoch for all historic occasions of leap second insertion since 1972. The leapsecond table shows each epoch of insertion along with the offset of International Atomic Time (TAI) with respect to Coordinated Universal Time (UTC), as disseminated by NTP. The table can be obtained directly from NIST national time servers.

While not strictly a security function, the Autokey protocol provides a means to securely retrieve the leapsecond table from a server or peer. Servers load the leapsecond table directly from the file specified in the crypto command, with default ntpkey_leap , while clients can obtain the table indirectly from the servers using the Autokey protocol. Once loaded, the table can be provided on request to other clients and servers.

13.7.9 Configuring Autokey

This section provides a step-by-step guide for setting up NTP Autokey Authentication. There are three Identity Schemes available in the NTP Reference Implemenation: IFF, GQ, and MV. Although examples of server parameter generation and client parameter installation are provided for all available Identity Schemes, it is not necessary to use all of them.

The servers that are designated to function as trusted roots must be at the root of the hierarchy of time servers. That is, they must not themselves be the client of another NTP server in which there is no Autokey configuration setup. That does not mean that all trusted roots must be stratum 1 servers. If on an isolated network for example with no external reference clock, you may designate a server as the root time source by enabling the following commands in TCPIP$NTP.CONF :

server 127.127.1.0 prefer fudge 127.127.1.0 stratum 0

In this particular example the stratum is set to 0, but it could be set to any low stratum value.

13.7.9.1.1 Using The Default TC Identity Scheme (Method 1)

1. On both Alice and Bob, add two lines to TCPIP$NTP.CONF :

   keysdir SYS$SPECIFIC:[TCPIP$NTP] crypto

2. On Bob, add the server line for Alice to Bob's TCPIP$NTP.CONF :

   server alice autokey

3. On Alice, generate the keys and trusted certificate:

   ALICE>ntp_keygen -"T"

4. On Bob, generate the keys and non-trusted certificate:

   BOB>ntp_keygen

5. Start NTP on Alice and Bob:

   ALICE>@sys$startup:tcpip$ntp_startup BOB>@sys$startup:tcpip$ntp_startup

Perform the following steps:

1. On Alice, add two lines to TCPIP$NTP.CONF :

   keysdir SYS$SPECIFIC:[TCPIP$NTP] crypto pw littlesecret

2. On Bob, add three lines to TCPIP$NTP.CONF :

   keysdir SYS$SPECIFIC:[TCPIP$NTP] crypto pw bigsecret server alice autokey

3. On Alice, generate the keys and trusted certificate using passwords:

   ALICE>ntp_keygen -"T" -p littlesecret -q bigsecret

4. On Bob, generate the keys and non-trusted certificate using passwords:

   BOB>ntp_keygen -q bigsecret

5. Start NTP on Alice and Bob:

   ALICE>@sys$startup:tcpip$ntp_startup BOB>@sys$startup:tcpip$ntp_startup

The following steps describe how the PC Identity Scheme generates keys and a trusted certificate on the server. The PC scheme supports only one trusted host.

1. On both Alice and Bob, add two lines to TCPIP$NTP.CONF :

   keysdir SYS$SPECIFIC:[TCPIP$NTP] crypto pw littlesecret

2. On Bob, add the server line for Alice to Bob's TCPIP$NTP.CONF :

   server alice autokey

3. On Alice, generate the keys and certificate:

   ALICE>ntp_keygen -"P" -p littlesecret

4. Copy the certificate ( tcpip$ntpkey_rsa-md5cert_alice.timestamp ) and the key ( tcpip$ntpkey_rsakey_alice.timestamp ) from Alice to Bob's keysdir.
5. On Bob, create symbolic links to the files:

   BOB>ntp_keygen -"P" -l tcpip$ntpkey_rsakey_alice.timestamp - _BOB> tcpip$ntpkey_rsa-md5cert_alice.timestamp

6. Start NTP on Alice and Bob:

   ALICE>@sys$startup:tcpip$ntp_startup BOB>@sys$startup:tcpip$ntp_startup

The IFF parameter generation process produces a server key that should not be distributed to other members of the NTP Trust Group. The IFF Group Key is exported to each client and may be distributed through encrypted email or even by pasting them across terminal windows.

To use the IFF scheme, perform the following steps:

1. On both Alice and Bob, add two lines to TCPIP$NTP.CONF :

   keysdir SYS$SPECIFIC:[TCPIP$NTP] crypto pw littlesecret

2. On Bob, add the server line for Alice to Bob's TCPIP$NTP.CONF :

   server alice autokey

3. On Alice, create the trusted public key and identity scheme parameter file. Use a password with at least four characters.

   ALICE>ntp_keygen -"T" -"I" -p littlesecret

4. On Bob, generate the client parameters using the server password:

   BOB>ntp_keygen -"H" -p littlesecret

5. Copy the tcpip$ntpkey_iffpar_alice.timestamp from Alice to Bob's keysdir.
6. On Bob, create a symbolic link to the file:

   BOB>ntp_keygen -"I" -l tcpip$ntpkey_iffpar_alice_tcpip_zko_h.3344261784

7. Start NTP on Alice and Bob:

   ALICE>@sys$startup:tcpip$ntp_startup BOB>@sys$startup:tcpip$ntp_startup

To use the alternate IFF scheme, perform the following steps:

1. On Alice, add two lines to TCPIP$NTP.CONF :

   keysdir SYS$SPECIFIC:[TCPIP$NTP] crypto pw littlesecret

2. On Bob, add three lines to TCPIP$NTP.CONF :

   keysdir SYS$SPECIFIC:[TCPIP$NTP] crypto pw bigsecret server alice autokey

3. On Alice, create the trusted public key and identity scheme parameter file. Use a password with at least four characters.

   ALICE>ntp_keygen -"T" -"I" -p littlesecret

4. On Bob, generate the client parameters using the client password:

   BOB>ntp_keygen -"H" -p bigsecret

5. On Alice, extract the client key specifying the server password and the client password:

   ALICE>ntp_keygen -e -q littlesecret -p bigsecret

   
   The output displays on the screen.

6. On Bob, create a file with the name specified in the screen output from the previous step, the file name after "Writing new IFF key." Paste the output from the previous step into the file. Following is an example of the final file on Bob (the first two lines starting with # are comments but required for proper operation):

   BOB> typ SYS$SPECIFIC:[TCPIP$NTP]TCPIP$NTPKEY_IFFKEY_ALICE.3344272304 # SYS$SPECIFIC:[TCPIP$NTP]TCPIP$NTPKEY_IFFKEY_ALICE.3344272304 # Thu Dec 22 15:32:10 2005 -----BEGIN DSA PRIVATE KEY----- Proc-Type: 4,ENCRYPTED DEK-Info: DES-CBC,E03763213C218BDC O9xAmWUEfJzCYEO6Zgn1KWm67M9NKlc/LzqHH+1K/kWQ/YXudUIf1ugdj+Umpphy R5UyrpVz8kWms4M/VsPZBvMgP2SIXPyYO5ANz0WlMYbk9Myd8Xfc/6LEhYMEhxeM Mjo95aUuWq/+YtlEAzrVvWjhQnHvNpHJtQxNw/7L6/ftVOGT0MuB1e9jJoaGo+lp yBSbhUYmwiyZfJUYvteXfOME/XH3rEx3h8/8k88zL1qACetHxeFmUMIoQq7lUqjg CeKMAidxgUWlmhixYVcUtvuD0ZNYqQ4jjUFfDrlgfAPmeHNLndehEStcQbB3ItLC -----END DSA PRIVATE KEY-----

7. Create a symbolic link to the client key:

   BOB>ntp_keygen -"I" -l tcpip$ntpkey_iffkey_alice.3344272304

8. Start NTP on Alice and Bob:

   ALICE>@sys$startup:tcpip$ntp_startup BOB>@sys$startup:tcpip$ntp_startup