man: add man/README updates for authentication tlv

add necessary updates to the ptp4l man page for how to configure the spp
and security association files.

add feature note to README along with disclaimer about openssl license

Signed-off-by: Clay Kaiser <Clay.Kaiser@ibm.com>
Reviewed-by: Erez Geva <ErezGeva2@gmail.com>
Reviewed-by: Miroslav Lichvar <mlichvar@redhat.com>

README.org

@@ -51,6 +51,13 @@
 
   - Supports bonded, IPoIB, and vlan interfaces.
 
+  - Supports Authentication TLV using Nettle, GnuTLS, or OpenSSL
+
+    - NOTE: OpenSSLv3+ is distributed under Apache 2 license. When
+            compiled with this library, LinuxPTP is distributed
+            under GPL3. An additional flag is required for linking:
+            ~make EXTRA_CFLAGS=-DUSE_OPENSSL~
+
 * Getting the Code
 
   You can download the latest released version at Source Forge.

configs/authentication.cfg

@@ -0,0 +1,36 @@
+#
+# example configuration using Authentication TLV support showing
+# attributes which differ from the defaults.  See the file,
+# default.cfg, for the complete list of available options.
+#
+[global]
+#
+# spp specifies which security association is valid for a port. It may
+# be specified globally or for each port independently.
+spp 0
+#
+# active_key_id specifies which key from security association is to be
+# used on outbound messages. It may also be specified globally or for
+# each port independently.
+#
+active_key_id 2
+#
+# sa_file is defined in global. it contains all security associations
+#
+sa_file configs/sa.cfg
+#
+# eth1 & eth2 override the global spp and active_key_id definitions
+#
+[eth1]
+spp 1
+active_key_id 1
+
+[eth0]
+spp 1
+active_key_id 3
+#
+# eth3 maintains the global spp definition but overrides the
+# active_key_id definition
+#
+[eth3]
+active_key_id 1

configs/sa.cfg

@@ -0,0 +1,51 @@
+#
+# example Security Association file as specified by sa_file directive
+# See the file, ptp4l.8, for the additional information.
+#
+[security_association]
+#
+# spp is valid from [0-255] inclusive, the port spp value should match
+# for each port this security association is to be enforced.
+#
+spp 0
+#
+# allow_mutable allows for mutable correction fields if on path
+# authentication tlv support is not possible. This option is NOT
+# recommended as it leaves the correction field unprotected.
+#
+allow_mutable 1
+#
+# key lines should be in the format: id type length value
+# - id:     Must be in the range of 1 to 2^32-1, inclusive.
+# - type:   Allowed are SHA256-128, SHA256, AES128, AES256.
+# - length: Optional verification key length in octets. Used to
+#           verify the key value is of the length specified.
+# - value:  Can be read as ASCII characters with the "ASCII:" prefix,
+#           as a hexadecimal number with the "HEX:" prefix or as a
+#           Base64 encoded string with the "B64:" prefix. If no
+#           prefix is included, ASCII is assumed. Key values should
+#           be randomally generated if possible. Ciphers (AES)
+#           require the key length to match the cipher length
+#           (ie AES-128 requires key of 128 bits or 16 bytes).
+#
+# Key ID 1 with 'SHA256-128' and 256 bits key, written in hexadecimal
+1 SHA256-128 HEX:F8ADC6B8B8E9AA709106BA42481EC9E29607334DE2C3C737A11A12931DB27F8C
+# Key ID 2 with 'SHA256' and 256 bits key, written in hexadecimal
+# and specify the key octet length of 32
+2 SHA256 32 HEX:EE91D469B3A8ADC6AC8EB28E21794C706E08FDE48863828A7B0281AFCA81B17D
+
+[security_association]
+spp 1
+#
+# seqid_window defines how far sequence id of an incoming sync/follow_up
+# message can advance from the last successfully processed sync/follow_up
+# before being considered a replayed message.
+#
+seqid_window 20
+# Key ID 1 with 'AES128' and 128 bits key, written in hexadecimal
+1 AES128 HEX:FAF48EBA01E7C5966A76CB787AED4E7B
+# Key ID 2 with 'AES256' and 256 bits key, written in Base64
+2 AES256 B64:PKTF9VQz94qPaoAzW4eE3JtFoQ8Ov1OTQSojalWyMbs=
+# Key ID 3 with 'SHA256' and 208 bits key, written in ASCII
+# and specify the key octet length of 26
+3 SHA256 26 abcdefghijklmnopqrstuvwxyz

ptp4l.8

@@ -1,4 +1,4 @@
-.TH PTP4l 8 "February 2023" "linuxptp"
+.TH PTP4l 8 "March 2024" "linuxptp"
 .SH NAME
 ptp4l - PTP Boundary/Ordinary/Transparent Clock
 
@@ -142,6 +142,15 @@ See UNICAST DISCOVERY OPTIONS, below.
 
 .SH PORT OPTIONS
 
+.TP
+.B active_key_id
+Used in conjunction with \fBspp\fR and \fBsa_file\fR directives to
+specify which key from the \fBspp\fR defined Security Association
+should be used for outbound icv calculations. All Security Assocations
+are read from the file specified by \fBsa_file\fR. Requires \fBspp\fR
+and \fBsa_file\fR directives. Must be in the range of 1 to 2^32-1,
+inclusive. The default is 0 (disabled).
+
 .TP
 .B allowedLostResponses
 The number of missed peer delay responses before the asCapable variable is
@@ -479,6 +488,20 @@ messages received on this port. This option's intended use is to
 support the Telecom Profiles according to ITU-T G.8265.1, G.8275.1,
 and G.8275.2. The default value is zero or false.
 
+.TP
+.B spp
+Specifies the Security Parameters Pointer of the desired Security
+Association to be used for Authentication TLV support for a given port.
+Any port with an assigned spp will attach Authentication TLVs to all
+outbound messages and check for Authentication TLVs on all inbound
+messages in accordance to the corresponding security association
+sourced via the \fBsa_file\fR directive. Outbound Authentication TLVs
+are generated using the key specified by \fBactive_key_id\fR. Not
+compatible with one step ports or advertised versions less then
+PTPv2.1. Requires \fBsa_file\fR and \fBactive_key_id\fR directives.
+Must be in the range of 0 to 255, inclusive.
+The default is -1 (disabled).
+
 .TP
 .B syncReceiptTimeout
 The number of sync/follow up messages that may go missing before
@@ -891,6 +914,16 @@ hardware (HW), firmware (FW), and software (SW). Allowed values are of
 the form HW;FW;SW and contain at most 32 utf8 symbols. The default is
 an ";;".
 
+.TP
+.B sa_file
+Specifies the location of the file containing Security Associations
+used for immediate security processing of the Authentication TLV in
+support of the optional security mechanism defined in ieee1588-2019
+ch 14.16. See \fBSECURITY ASSOCIATION OPTIONS\fR for information on how
+this file should be formatted. \fBspp\fR and \fBactive_key_id\fR should
+be specifed for each port to indicate which Security Association from
+the /fBsa_file/fR should be used. The default is an empty string.
+
 .TP
 .B sanity_freq_limit
 The maximum allowed frequency offset between uncorrected clock and the system
@@ -1084,6 +1117,67 @@ Each table must begin with a unique, positive table ID.  The port that
 claims a given table does so by including the ID as the value of
 its 'unicast_master_table' option.
 
+.SH SECURITY ASSOCIATION OPTIONS
+
+.TP
+.B spp
+Each security association must begin with a unique spp. The port that
+claims a given security association does so by including the spp as the
+value of its 'spp' option. Must be in the range of 0 to 255,
+inclusive.
+
+.TP
+.B seqid_window
+This option defines how far sequence id of an incoming sync/follow_up
+message can advance from the last successfully processed sync/follow_up
+before being considered a replayed message. Sync/follow_up seqid
+tracking is reset on port state change and updated upon successful
+processing. When set to zero, no seqid checking will be performed.
+Must be in the range of 0 to 32767 (0x7FFF) inclusive. The default
+value is 3.
+
+.TP
+.B allow_mutable
+This option allows for mutable correction fields if on path
+authentication tlv support is not possible. This option is NOT
+recommended as it leaves the correction field unprotected.
+The default value is 0 (disabled).
+
+.TP
+.B key (format: id type length value)
+Each security association must have at least one key entry. These
+entries should use the format 'id type length value'.
+- Key id:     Must be in the range of 1 to 2^32-1, inclusive.
+- Key type:   Allowed are SHA256-128, SHA256, AES128, AES256.
+- Key length: Optional verification key length in octets. Used to
+              verify the key value is of the length specified.
+- Key value:  Can be read as ASCII characters with the "ASCII:" prefix,
+              as a hexadecimal number with the "HEX:" prefix or as a
+              Base64 encoded string with the "B64:" prefix. If no
+              prefix is included, ASCII is assumed. Key values should
+              be randomally generated if possible. Ciphers (AES)
+              require the key length to match the cipher length
+              (ie AES-128 requires key of 128 bits or 16 bytes).
+
+.TP
+.B Example
+The following is an example of a security associations file:
+
+.EX
+[security_association]
+spp 0
+allow_mutable 1
+1 SHA256-128 HEX:F8ADC6B8B8E9AA709106BA42481EC9E29607334DE2C3C737A11A12931DB27F8C
+2 SHA256 32 HEX:EE91D469B3A8ADC6AC8EB28E21794C706E08FDE48863828A7B0281AFCA81B17D
+
+[security_association]
+spp 1
+seqid_window 20
+1 AES128 HEX:FAF48EBA01E7C5966A76CB787AED4E7B
+2 AES256 B64:PKTF9VQz94qPaoAzW4eE3JtFoQ8Ov1OTQSojalWyMbs=
+3 SHA256 26 abcdefghijklmnopqrstuvwxyz
+.EE
+
 .SH TIME SCALE USAGE
 
 When