From acc38d089d98834f111d75a38f1bc598822ad90f Mon Sep 17 00:00:00 2001 From: Bing Sun Date: Tue, 3 Nov 2020 01:25:39 -0800 Subject: [PATCH] add support for NTP authentication --- doc/SONiC_OC_NTP_HLD.md | 389 +++++++++++++++++++++++++++++++++++----- 1 file changed, 341 insertions(+), 48 deletions(-) diff --git a/doc/SONiC_OC_NTP_HLD.md b/doc/SONiC_OC_NTP_HLD.md index 6df0e3ba81..9701803241 100644 --- a/doc/SONiC_OC_NTP_HLD.md +++ b/doc/SONiC_OC_NTP_HLD.md @@ -3,7 +3,7 @@ NTP Support in Management Framework # High Level Design Document -#### Rev 0.1 +#### Rev 0.4 # Table of Contents * [List of Tables](#list-of-tables) @@ -21,6 +21,7 @@ NTP Support in Management Framework | 0.1 | 05/03/2020 | Bing Sun | Initial version | | 0.2 | 06/15/2020 | Bing Sun | Update based on comments | | 0.3 | 09/21/2020 | Bing Sun | Add dhcp behavior | +| 0.4 | 11/02/2020 | Bing Sun | Add support for NTP authentication| # About this Manual @@ -55,15 +56,36 @@ In addition, it provides users to configure NTP source interface and NTP vrf. Fo ### 1.1.1 Front end configuration and get capabilities -#### 1.1.1.1 add/delete NTP server +#### 1.1.1.1 add/delete NTP server +``` +ntp server 99.1.1.1 +ntp server pool.ntp.org +``` Add/delete NTP server information in the Redis ConfigDB and in the ntp.conf file (NTP configuration file). The NTP server can be IPv4 address, IPv6 address , or a ntp pool name. Mutliple NTP servers can be configured. #### 1.1.1.2 add/delete NTP source interface +``` +ntp source-interface Ethernet36 +``` + +``` +ntp source-interface PortChannel 100 +``` + +``` +ntp source-interface Vlan 100 +``` + +``` +ntp source-interface Management 0 +``` + + Add/delete the global NTP source interface in the Redis ConfigDB and in the ntp.conf file. The ip address of this interface will be used by ntpd as source ip for all NTP packets. Only one NTP source interface can be configured. -Following interfaces can be used as NTP source interface when "mgmt" is not configured as NTP vrf. +Following interfaces can be used as NTP source interface, - Ethernet interface - PortChannel - Vlan interface @@ -71,10 +93,22 @@ Following interfaces can be used as NTP source interface when "mgmt" is not conf - eth0 #### 1.1.1.3 add/delete VRF name +``` +ntp vrf default +``` + +``` +ntp vrf mgmt +``` + Add/delete the global NTP VRF information in the Redis ConfigDB. It is used by /etc/init.d/ntp script to start the ntpd in a specific VRF context. For this release, only Management VRF and default instance are supported. #### 1.1.1.4 Get NTP association +``` +show ntp association +``` + This displays the output of "ntpq -np" command. #### 1.1.1.5 Overall Behavior related to NTP source interface and NTP vrf @@ -87,14 +121,49 @@ c.if "default" is configured as NTP vrf, ntp service starts in default vrf conte ntp service always starts in default vrf context ##### NTP source interface related -a.if NTP vrf is empty or "default", NTP source interface can be configured -b.if NTP vrf is "mgmt", configuration of “ntp source-interface” will be rejected -c.if NTP source interface is configured, configuration of "mgmt" as NTP vrf will be rejected -d.if NTP source interface has ip configured, ip address of this interface will be used as source ip for all ntp packets -e.if NTP source interface has no ip configured, it is treated as if no ntp source interface is configured -f.if NTP vrf is "mgmt", eth0/mgmt interface ip will be used as source ip for all ntp packets by default +a.if NTP source interface has ip configured, ip address of this interface will be used as source ip for all ntp packets +b.if NTP source interface has no ip configured, it is treated as if no ntp source interface is configured +#### 1.1.1.6 NTP authentication configuration +NTP authentication enables an NTP client or peer to authenticate time received from their servers and peers. + +##### ntp authenticate +``` +ntp authenticate +``` + +This command enable the NTP authentication feature + +##### ntp authentication-key +``` +ntp authentication-key 1 md5 "ntp client 1" + +ntp authentication-key 2 md5 ntp_client2 +``` + +This command defines an authentication key with key number, authentication type and password. +The key number is from 1 to 65535. +The authentication type supported is MD5, SHA1 and SHA2-256. +The password is configured with plaintext the first time. In runnning-configuration, it is encrypted with the flag "encrypted" at the end. Authentication key can then be configured with encrypted format and "encrypted" flag. + + +##### ntp trusted key +``` +ntp trusted-key 1 + +ntp trusted-key 2 +``` +This command adds the list of key numbers that the NTP server must provide in its NTP packets in order for the NTP clients +to synchronize to it. + +##### ntp server key +``` +ntp server 99.1.1.1 key 1 +``` + +This command configures the key expected from a specific NTP server. + ### 1.1.2 Backend mechanisms to support configuration and get #### 1.1.2.1 add/delete NTP server @@ -165,7 +234,129 @@ SONiC click CLI can be extended to include this configuration. #### 1.1.2.4 get NTP associations -Transformer function issues "ntpq -p" command, parses the response and maps the outputs to the OpenConfig system YANG NTP states. +Transformer function issues "ntpq -pn" command, parses the response and maps the outputs to the OpenConfig system YANG NTP states. + +#### 1.1.2.5 NTP authentication + +##### 1.1.2.5.1 enable or disable ntp authenticate + +When "authenticate" is enabled, "enable-ntp-auth" field is set to "true" in the NTP global entry, + +``` +"NTP|global": { + "type": "hash", + "value": { + "enable-ntp-auth": "true", + } +} +``` + +This change triggers /etc/ntp.conf to get generated with the line indicating where to find the configured keys +``` +key /etc/ntp.keys +``` + +When "authenticate" is removed, the same attribute is set to "false". The file /etc/ntp.conf is generated without "key /etc/ntp.keys" but with the line +``` +disable auth +``` + +The file /etc/ntp.keys will be created with the configured authentication keys if "authenticate" is enabled, and removed if "authenticate" is disabled. + +##### 1.1.2.5.2 Add or delete ntp authentication key + +When an authentication key is configured with a key number, authentication type and password in plaintext, a transformer function will change the plaintext password to the encrypted format and puts the key in an NTP_AUTHENTICATION_KEY ConfigDB entry. A boolean "key_encrypted" is set to true and added in the same entry as well. This is done so that "show running-configuration" from CLI or GET from REST/gNMI will be able to display the password in encrypted format. For example, +``` + "NTP_AUTHENTICATION_KEY|1": { + "type": "hash", + "value": { + "key_encrypted": "true", + "key_type": "MD5", + "key_value": "3b88c0eb8406a9e76722b84baf1d94e5e185eb7f64f8dd46c759719c33557876" + } + } +``` + +If "authenticate" is enabled, the file /etc/ntp.keys is populated with the configured authentication keys. The password in this file is in the plaintext format. + +When an ntp authentication key is removed, the ConfigDb and /etc/ntp.keys will be updated accordingly. + +##### 1.1.2.5.3 Add or delete ntp trusted key + +When a ntp trusted key number is configured, the key number is added to the "trustedkeys" list in the NTP global entry, e.g +``` + "NTP|global": { + "type": "hash", + "value": { + "authenticat": enabled, + "trustedkeys@": "1,2" + } + } +``` + +/etc/ntp.conf will be generated with the line +``` +trustedkey 1 2 +``` + +When a ntp trusted key number is removed, the key number is removed from the "trustedkey" list. + + +##### 1.1.2.5.4 Add a key for NTP server + +When a ntp server is created with a key number, the "key_id" with the key number will be added as a field for the NTP server ConfigDb entry, e.g +``` +"NTP_SERVER|99.1.1.1": { + "type": "hash", + "value": { + "key_id": "1" + } + } +``` + +The file /etc/ntp.conf will be generated with the same key number for that NTP server, e.g +``` +server 99.1.1.1 iburst key 1 +``` + +##### 1.1.2.5.5 Sample ntp.conf and ntp.keys +###### Relevant entries in ntp.conf for NTP server +``` +keys /etc/ntp.keys + +server 10.14.8.140 iburst + +# By default, exchange time with everybody, but don't allow configuration. +restrict -4 default kod notrap nomodify nopeer noquery +restrict -6 default kod notrap nomodify nopeer noquery + +interface listen Loopback100 +interface listen 127.0.0.1 + +trustedkey 1 2 +``` + +###### Relevant entries in ntp.keys on NTP server +``` +1 MD5 ntp client 1 +2 MD5 ntp_client_2 +``` + +###### Relevant entries in ntp.conf on NTP client +``` +keys /etc/ntp.keys + +server 99.1.1.1 iburst key 1 + +interface listen Vlan100 + +trustedkey 1 +``` + +###### Relevant entries in ntp.keys on NTP client +``` +1 MD5 ntp client 1 +``` ### 1.1.3 Functional Requirements @@ -173,7 +364,8 @@ Provide management framework support to - configure NTP server - configure NTP source interface - configure NTP vrf - +- configure NTP authentication + ### 1.1.4 Configuration and Management Requirements - CLI style configuration and show commands - REST API support @@ -182,16 +374,13 @@ Provide management framework support to Details described in Section 3. ### 1.1.5 Configurations not supported by this feature using management framework: -- NTP authenticate -- NTP authentication-key -- configure local server as a NTP server -- trusted key +- configure local server as a NTP master - broadcast mode - + ### 1.1.6 Scalability Requirements -Only 1 source interface. -Ntpd runs in one VRF context, default vrf or mgmt vrf. -Multiple ntp servers supported. +Only 1 source interface, assuming the remote NTP peer has route to this source interface +Ntpd runs in one VRF context, default vrf or mgmt vrf. +Multiple ntp servers supported. ### 1.1.7 Warm Boot Requirements NA @@ -206,7 +395,7 @@ The front end code change will be done in management-framework container includi - XML file for the CLI - Python script to handle CLI request (actioner) - Jinja template to render CLI output (renderer) -- front-end code to support "show running-configuration ntp" +- front-end code to support "show running-configuration" - OpenConfig YANG model for NTP openconfig-system.yang and openconfig-system-ext.yang - SONiC NTP model for NTP based on Redis DB schema of NTP - transformer functions to @@ -224,7 +413,7 @@ Manage/configure NTP via gNMI, REST and CLI interfaces. Provide CLI, gNMI and REST supports for NTP related configurations. ## 2.3 Backend change to support new configurations -Provide changes in hostcfgd, ntp.conf.j2 and /etc/init.d/ntp. +Provide changes in hostcfgd, ntp.conf.j2, ntp.keys.j2 and /etc/init.d/ntp. SONiC click CLI enhancement if possible. ## 2.4 Behavior when Management IP Address is acquired via DHCP @@ -281,26 +470,28 @@ Supported yang objects and attributes: +--rw ntp | +--rw config | | +--rw enabled? boolean - | | +--rw enable-ntp-auth? boolean ++ | | +--rw enable-ntp-auth? boolean + | | +--rw oc-sys-ext:ntp-source-interface? oc-if:base-interface-ref + | | +--rw oc-sys-ext:vrf? string | +--ro state | | +--ro enabled? boolean - | | +--ro enable-ntp-auth? boolean ++ | | +--ro enable-ntp-auth? boolean | | +--ro auth-mismatch? oc-yang:counter64 + | | +--ro oc-sys-ext:ntp-source-interface? oc-if:base-interface-ref + | | +--ro oc-sys-ext:vrf? string - | +--rw ntp-keys - | | +--rw ntp-key* [key-id] - | | +--rw key-id -> ../config/key-id - | | +--rw config - | | | +--rw key-id? uint16 - | | | +--rw key-type? identityref - | | | +--rw key-value? string - | | +--ro state - | | +--ro key-id? uint16 - | | +--ro key-type? identityref - | | +--ro key-value? string ++ | +--rw ntp-keys ++ | | +--rw ntp-key* [key-id] ++ | | +--rw key-id -> ../config/key-id ++ | | +--rw config ++ | | | +--rw key-id? uint16 ++ | | | +--rw key-type? identityref ++ | | | +--rw key-value? string ++ | | | +--rw oc-sys-ext:key-encrypted? boolean ++ | | +--ro state ++ | | +--ro key-id? uint16 ++ | | +--ro key-type? identityref ++ | | +--ro key-value? string ++ | | +--rw oc-sys-ext:key-encrypted? boolean | +--rw servers | +--rw server* [address] + | +--rw address -> ../config/address @@ -311,6 +502,7 @@ Supported yang objects and attributes: | | +--rw association-type? enumeration | | +--rw iburst? boolean | | +--rw prefer? boolean ++ | | +--rw oc-sys-ext:key-id? uint16 + | +--ro state + | +--ro address? oc-inet:host | +--ro port? oc-inet:port-number @@ -318,6 +510,7 @@ Supported yang objects and attributes: | +--ro association-type? enumeration | +--ro iburst? boolean | +--ro prefer? boolean ++ | +--rw oc-sys-ext:key-id? uint16 + | +--ro stratum? uint8 | +--ro root-delay? uint32 | +--ro root-dispersion? uint64 @@ -331,18 +524,28 @@ Supported yang objects and attributes: + | +--ro oc-sys-ext:peertype? string + | +--ro oc-sys-ext:now? uint32 + | +--ro oc-sys-ext:reach? uint8 - +``` + +```diff module: sonic-system-ntp - -+ +--rw sonic-system-ntp -+ +--rw NTP -+ | +--rw NTP_LIST* [global_key] -+ | +--rw global_key enumeration -+ | +--rw src_intf? union -+ | +--rw vrf? string -+ +--rw NTP_SERVER -+ +--rw NTP_SERVER_LIST* [server_address] -+ +--rw server_address inet:host ++ +--rw sonic-system-ntp ++ +--rw NTP ++ | +--rw NTP_LIST* [global_key] ++ | +--rw global_key enumeration ++ | +--rw src_intf? union ++ | +--rw vrf? union ++ | +--rw enable-ntp-auth? boolean ++ | +--rw trustedkeys* -> /sonic-system-ntp/NTP_AUTHENTICATION_KEY/NTP_AUTHENTICATION_KEY_LIST/key_id ++ +--rw NTP_AUTHENTICATION_KEY ++ | +--rw NTP_AUTHENTICATION_KEY_LIST* [key_id] ++ | +--rw key_id uint16 ++ | +--rw key_type? enumeration ++ | +--rw key_value? string ++ | +--rw key_encrypted? boolean ++ +--rw NTP_SERVER ++ +--rw NTP_SERVER_LIST* [server_address] ++ +--rw server_address inet:host ++ +--rw key_id? -> /sonic-system-ntp/NTP_AUTHENTICATION_KEY/NTP_AUTHENTICATION_KEY_LIST/key_id ``` @@ -356,9 +559,12 @@ sonic# configure terminal sonic(config)# sonic(config)# ntp - server Configure NTP server - source-interface Configure NTP source interface to pick the source IP, used for the NTP packets - vrf Enable NTP on VRF + authenticate Authenticate time sources + authentication-key Authentication key for trusted time sources + server Configure NTP server + source-interface Configure NTP source interface to pick the source IP, used for the NTP packets + trusted-key Key numbers for trusted time sources + vrf Enable NTP on VRF ``` @@ -451,6 +657,66 @@ sonic(config)# no ntp vrf ``` +##### 3.6.2.1.7 Enable NTP authentication +``` +sonic(config)#ntp + authenticate Authenticate time sources +sonic(config)#ntp authenticate +``` + +##### 3.6.2.1.8 Disable NTP authentication +``` +sonic(config)#no ntp authenticate +``` + +##### 3.6.2.1.9 Configure NTP authentication-key +``` +sonic(config)#ntp authentication-key + <1-65535> Key number + +sonic(config)#ntp authentication-key 1 + md5 MD5 authentication + sha1 SHA1 authentication + sha2-256 SHA2-256 authentication + +sonic(config)#ntp authentication-key 1 md5 + String Authentication key (max 64 chars, keys longer than 20 chars must be hex) + +sonic(config)#ntp authentication-key 1 md5 "ntp client 1" + +``` + +##### 3.6.2.1.10 Delete NTP authentication-key +``` +sonic(config)#no ntp authentication-key 1 +``` + +##### 3.6.2.1.11 Configure NTP trusted-key +``` +sonic(config)#ntp trusted-key + <1-65535> Key number + +sonic(config)#ntp trusted-key 1 +``` + +##### 3.6.2.1.12 Delete NTP trusted-key +``` +sonic(config)no ntp trusted-key 1 +``` + +##### 3.6.2.1.13 Add NTP server with key +``` +sonic(config)#ntp server 99.1.1.1 + key Configure peer authentication key + +sonic(config)#ntp server 99.1.1.1 key 1 +``` + +##### 3.6.2.1.14 Delete NTP server with key +``` +sonic(config)#no ntp server 99.1.1.1 +``` + #### 3.6.2.2 Show ntp ``` sonic# show ntp @@ -497,6 +763,22 @@ NTP vrf: default ##### 3.6.2.2.4 Show running-configuration ``` +sonic(config)#ntp authenticate +sonic(config)#ntp authentication-key 1 md5 "ntp client 1" +sonic(config)#ntp authentication-key 1 md5 ntp_client_2 +sonic(config)#ntp server 99.1.1.1 key 1 +sonic(config)#ntp trusted-keys 1 +sonic(config)#ntp trusted-keys 2 +sonic(config)# do show running-configuration +! +ntp authenticate +ntp authentication-key 1 md5 3b88c0eb8406a9e76722b84baf1d94e5e185eb7f64f8dd46c759719c33557876 encrypted +ntp authentication-key 2 md5 771de7710005c5d6aa5b3313812b721d5d0d4a93fb1548572994464495476c4e encrypted +ntp server 99.1.1.1 key 1 +ntp trusted-keys 1 +ntp trusted-keys 2 +! + sonic(config)# ntp server 10.11.0.1 sonic(config)# ntp server pool.ntp.org sonic(config)# ntp source-interface Ethernet 16 @@ -547,6 +829,8 @@ check /etc/ntp.conf check /var/log/syslog and look for ntp +check "docker exec -it mgmt tail -f /var/log/rest_server/rest_server.log" for rest logs + ifconfig lo ifconfig lo-m @@ -594,6 +878,15 @@ The unit-test for this feature will include: | | Verify that only default and mgmt can be configured as NTP vrf| | | Verify that mgmt cannot be configured as NTP vrf if NTP source interface is configured| | Delete NTP vrf| Verify that NTP vrf is removed from the configDB and ntp service is running in the default instance| +| Configure NTP authentication for NTP server| Verify that NTP authentication-key can be created correctly| +| | Verify that NTP trusted-keys can be added correctly| +| | Verify that NTP authentiate can be enabled and disabled| +| Configure NTP authentication for NTP client| Verify that NTP authentication-key can be created correctly| +| | Verify that NTP trusted-keys can be added correctly| +| | Verify that key number can be added to a NTP server | +| | Verify that NTP authenticate can be enabled and disabled| +| | Verify NTP server is accepted if authentication keys match on NTP server and NTP client| +| | Verify NTP server is rejected if authentication keys mismatch on NTP server and NTP client| | show ntp associations | Verify ntp associations are displayed correctly | | show ntp server | Verify ntp servers are displayed correctly | | show ntp global | Verify ntp global configurations are displayed correctly |