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

Signed-off-by: Clay Kaiser <clay.kai...@ibm.com>
---
 ptp4l.8 | 77 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 76 insertions(+), 1 deletion(-)

diff --git a/ptp4l.8 b/ptp4l.8
index 40c66c2..81ed6f0 100644
--- a/ptp4l.8
+++ b/ptp4l.8
@@ -1,4 +1,4 @@
-.TH PTP4l 8 "February 2023" "linuxptp"
+.TH PTP4l 8 "October 2023" "linuxptp"
 .SH NAME
 ptp4l - PTP Boundary/Ordinary/Transparent Clock
 
@@ -142,6 +142,12 @@ See UNICAST DISCOVERY OPTIONS, below.
 
 .SH PORT OPTIONS
 
+.TP
+.B active_key_id
+Each port must define an active_key_id when using security. This key_id is
+used to determine which key should be used for outbound icv calculations.
+Must be in the range of 0 to 2^32-1, inclusive. The default is 0 (disabled).
+
 .TP
 .B announceReceiptTimeout
 The number of missed Announce messages before the last Announce messages
@@ -415,6 +421,15 @@ 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 for the desired security association
+to be used for authentication tlv support. If specified, the port owning the
+spp will attempt to attach (outbound) and check (inbound) authentication tlvs
+for all messages in accordance to the corresponding security association
+sourced via the \fBsa_file\fR directive. Not compatible with one step ports.
+Must be in the range of -1 to 255, inclusive. The default is -1 (disabled).
+
 .TP
 .B syncReceiptTimeout
 The number of sync/follow up messages that may go missing before
@@ -821,6 +836,14 @@ 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 more info on file contents.
+The default is an empty string. (disabled).
+
 .TP
 .B sanity_freq_limit
 The maximum allowed frequency offset between uncorrected clock and the system
@@ -1014,6 +1037,58 @@ 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. This may cause issues if
+syncs from multiple sources are being received at same time. When set to zero,
+no seqid checking will be performed. Must be in the range of 0 to 32767 
+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 value)
+Each security association must have at least one key entry. These
+entries should use the format 'id type value'. Key ids must be in the
+range of 1 to 2^32-1, inclusive. Key types allowed are SHA256-128, SHA256,
+AES128, AES256. if no key type is defined, SHA256-128 is assumed. Key values
+should be randomally generated if possible. Keys values can be read as ASCII
+characters with the ASCII: prefix, or as a hexadecimal number with the
+HEX: prefix. Ciphers (AES) require the key length to match the cipher length.
+
+.TP
+.B Example
+The following is an example of the contents of a security associations file:
+
+.EX
+[security_association]
+spp 1
+allow_mutable 1
+1 SHA256-128 
HEX:F8ADC6B8B8E9AA709106BA42481EC9E29607334DE2C3C737A11A12931DB27F8C
+2 SHA256 HEX:EE91D469B3A8ADC6AC8EB28E21794C706E08FDE48863828A7B0281AFCA81B17D
+
+[security_association]
+spp 2
+10 AES128 HEX:FAF48EBA01E7C5966A76CB787AED4E7B
+25 AES256 HEX:57F79854E902DC965D8AA65EC6885A28832A26DC18C6D30903C4BD7F3510740B
+.EE
+
 .SH TIME SCALE USAGE
 
 When
-- 
2.42.1



_______________________________________________
Linuxptp-devel mailing list
Linuxptp-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/linuxptp-devel

Reply via email to