This article applies to Domain Time II.

Last Updated: 14 July 2020
Subject to further revisions as the IEEE 1588-2019 (PTP v2.1) specification evolves

The original version of IEEE 1588-2008 (PTP) is called PTP v2.0. A newer version, IEEE 1588-2019, is called PTP v2.1. PTP v2.1 is backward-compatible with v2.0, but has some additional features. One of these new features is message authentication.
PTP v2.1 allows grandmasters to add an Authentication TLV to each message they send. The specification supports multiple authentication methods using symmetric keys. Key selection and distribution methods, as well as the cryptographic algorithms, are implementation-dependent. The only requirement is that HMAC-SHA256-128 must be supported. PTP v2.1 is not yet fully standardized, and the extra network components needed to implement secure key discovery and rotation do not yet exist, so Domain Time’s support for Authentication is limited to HMAC-SHA256-128.
Each Authentication TLV carries a Security Parameter Pointer ("SPP"), which may, in theory, be used in conjunction with a Key Distribution Center ("KDC") to select a group of keys. The SPP may also be static, without reference to a KDC, in which case the keys themselves must also be static and already known to the sender and receiver. Valid values for the SPP are 0-255, inclusive.
Each Authentication TLV also carries a KeyId, a 32-bit value indicating which key associated with the SPP is being used to sign the message. Implementations are free to use a single KeyId for all message types, or separate KeyIds for each message type. Domain Time only allows KeyIds in the range of 1-65535 (inclusive).
Authentication TLVs do not contain information about the cryptographic algorithm that corresponds to the hash being sent. When using a KDC, the SPP can be used to fetch this information from the KDC. If the SPP is static, HMAC-SHA256-128 must be assumed.
Domain Time implements a single, static SPP value in its keyring. The keyring has also been expanded to allow SHA256 keys, specified as 64-byte hex strings. In order for Domain Time to validate incoming v2.1 Authentication TLVs, the SPP stored in the keyring may either be zero (which acts like a wildcard) or must match what the grandmaster sends; in addition, a SHA256 key must exist in your keyring for each KeyId the grandmaster uses.

Special Note for Multiple Grandmasters:
If you have multiple PTP v2.1 grandmasters, and you do not have Domain Time’s SPP set to zero, each grandmaster should use the same SPP as the others. Each grandmaster may have its own set of SHA256 keys. Be sure to import all the keys from all masters into Domain Time. If you are signing outgoing delay requests, all of your grandmasters should be configured to accept the same KeyId for incoming delay requests.

Processing of Incoming Signed Messages
Since Domain Time does not use a KDC, it only supports HMAC-SHA256-128 using pre-shared KeyIds and their corresponding SHA256 keys. Domain Time computes the hash over the body of the PTP message and the Authentication TLV, and compares the hash contained in the Authentication TLV to the computed hash. If the SPPs match, the KeyIDs match, and the hashes match, the message is considered authenticated. Note that this means Domain Time does not consider a certain KeyId valid only for a certain message type. Domain Time will accept any KeyId sent by the grandmaster, as long as a corresponding SHA256 key exists in the keyring. Whether to use one KeyId for all messages, or separate KeyIds for different message types, or even to rotate them periodically, is manufacturer-dependent. For this reason, you should import all of the SHA256 keys from your grandmaster(s), because the protocol does not allow any method to determine which KeyId will be used with which message type.
PTP v2.1 allows delayed key disclosure, and several other extensions. Domain Time only supports static SPPs and immediate KeyIds (that is, the SPP must match, and the KeyId with its corresponding SHA256 key must exist and validate at the time of packet reception, without looking up security associations stored in a KDC).
When a PTP v2.1 message is received and contains a Authentication TLV, Domain Time will process the information if you have ticked the PTP v2.1 Authentication TLV processing enabled checkbox on the PTP Options dialog. However, whether to use the information is configurable. If you decide not to enable Authentication TLV processing, Domain Time behaves as if no Authentication TLV was attached. If processing is enabled, you can see the security processing results by changing the log to debug mode and selecting "PTP v2.1 Authentication TLV details" in the Debug Details.
You may select Prefer signed Announces as long as you are rejecting unsigned/incorrectly signed Announces. This changes the IEEE 1588 standard Best-Master-Clock (BMC) algorithm to give preference to grandmasters sending correctly-signed Announces, even if another grandmaster has a better time quality.
Versions of Domain Time newer than 5.2.b.20190331 also allow Require signed Announces. The same rules apply as with Prefer signed Announces, except that only grandmasters sending correctly-signed v2.1 Announces will be considered by the Best-Master-Clock (BMC) algorithm. Use this option with care.
If you decide to enable processing of Authentication TLVs, and the security fails to validate, a warning message will appear in the log, saying which message’s authentication failed, and why.
If you have Authentication TLV processing enabled, you may also require that authentication succeeds. You may choose which types of messages must succeed (and be aware of what happens if it doesn't):
• Announces
  If you choose to reject Announces with failing security, the grandmaster will never qualify, and PTP will remain in the listening state unless another validating grandmaster is available.
• Syncs/Follow-Ups
  If you choose to reject Syncs or Follow-Ups with failing security, PTP will cycle between listening and calibrating. Calibration will never succeed because at least one Sync (or Sync and Follow-Up with two- step clocks) must be received and authenticated before Domain Time can progress from the calibrating state to the slave state.
• Delay Responses
  If you choose to reject delay responses with failing security, Domain Time will not be able to calculate the meanPathDelay, which may significantly reduce overall accuracy. This category includes E2E Delay Response messages, P2P Delay Response messages, and P2P Delay Follow-Up messages (if the P2P mechanism is two-step).
• Other Message Types
  Domain Time does not currently attempt to validate Authentication TLVs attached to Management or Signaling messages.
Domain Time Client, Domain Time Server, and PTP Monitor can send Authentication TLVs with End-to- End Delay Requests or Peer-to-Peer Delay Requests. You configure this by selecting one of your SHA256 KeyIds to use with the message. There is no benefit to authenticating a delay request, since it is only important that the reply be trusted, so the default KeyId is "None," which tells Domain Time not to sign delay requests. Your PTP v2.1 grandmaster may be configured to expect authentication on incoming delay requests. If so, and if you are not signing your delay requests, the grandmaster may not reply, or may reply without a Authentication TLV. In this case, either disable the grandmaster’s requirement for signed delay requests, or configure Domain Time to use the KeyId your grandmaster is expecting.
You may verify that your grandmaster is signing messages correctly by examining the -ptpMasters output from DTCheck, or the graphical version of PTP Masters built into the Control Panel applet. If your grandmaster is v2.0, or is not configured to send Authentication TLVs, the ptpMasters report will not show any security information. If your grandmaster is v2.1, and is sending Authentication TLVs, and you have Authentication TLV processing enabled, the most recent result for each message type will be displayed.
Domain Time’s PTP Monitor (part of Audit Server) relies on having Domain Time Server installed on the same machine. PTP Monitor will process incoming Authentication TLVs, and sign outgoing delay requests, in accordance with the settings for Domain Time Server. PTP Monitor will use the SPP for each grandmaster that the grandmaster used in signing its Announces. If incoming Announces are not signed correctly, PTP Monitor will not try to sign outgoing delay requests.
Domain Time Server as a PTP v2.1 Master
When Domain Time Server is acting as a software PTP master, it normally auto-selects whether to send v2.0 or v2.1 messages based on the domain number. Domain numbers 0-127 pertain to v2.0, whereas v2.1 extends to range to 0-239. Domain Time will always use v2.1 for domain numbers greater than 127, and by default it uses v2.0 for domain numbers less than 128. You may force Domain Time to use v2.1 for the lower-numbered domains by checking the appropriate box on the Master configuration dialog box. Authentication TLVs may only be attached to v2.1 messages.
When Domain Time Server is acting as a software PTP master in v2.1 mode, it can sign outgoing Announces, Syncs, E2E delay responses, and P2P delay responses. By default, no messages are signed. You may change this by selecting which key to send with each message type. The drop-down box for each message type is populated from the SHA256 keys in your symmetric key keyring. If you have no SHA256 keys defined, "None" will be the only selection available. You may use the same KeyId for all message types, or use different KeyIds for each message type. Choose KeyIds that your PTP slaves will be expecting. Note: Domain Time Server will only sign E2E or P2P delay responses if the corresponding request was signed.
We recommend not signing outgoing Announces, Syncs, or delay responses, unless this is a requirement of your industry. There is a small, but measurable, cost to calculating hashes, and the added burden on Domain Time Server will reduce the accuracy of its timestamps by a small amount since the hash cannot be computed until after the timestamp is struck. In addition, if you are using Domain Time Server as a Telecom 2008 server, each outgoing packet must be signed separately since the Telecom profile requires servers to maintain a separate sequence number pool for each message type for each slave.