diff --git a/docs/source/advanced/domain_name_resolution/domain_name_resolution.rst b/docs/source/advanced/domain_name_resolution/domain_name_resolution.rst index 8631d518f..1122eb682 100644 --- a/docs/source/advanced/domain_name_resolution/domain_name_resolution.rst +++ b/docs/source/advanced/domain_name_resolution/domain_name_resolution.rst @@ -93,7 +93,7 @@ Edit **/etc/resolv.conf** to contain the cluster domain value you set in the sit Legacy ISC DHCP and BIND TSIG Key Options ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -xCAT uses **xcat_key** with **hmac-md5** by default for legacy ISC DHCP OMAPI and BIND DDNS updates. Existing installations should keep that default unless a site policy or external DNS provider requires a different key. +xCAT uses **xcat_key** for BIND DDNS updates and legacy ISC DHCP OMAPI. New installations on Enterprise Linux 9 or later and Ubuntu 20.04 or later set **hmac-sha256**. Ubuntu 18.04, SLES 12, SLES 15, and openSUSE Leap 15 leave **dhcpomapialgorithm** unset because their bundled ``omshell`` does not support the ``key-algorithm`` command. If **dhcpomapialgorithm** is not set, including on an existing installation, xCAT continues to use **hmac-md5** for compatibility. HMAC-MD5 is not approved for FIPS mode; a FIPS-mode site that needs OMAPI must provide an ``omshell`` supporting ``key-algorithm`` and set a SHA-2 algorithm explicitly. Kea does not use OMAPI, but Kea DDNS uses this TSIG algorithm. To use another supported algorithm, set **dhcpomapialgorithm** in the site table and update the matching **passwd** table secret. Supported values are **hmac-md5**, **hmac-sha1**, **hmac-sha224**, **hmac-sha256**, **hmac-sha384**, and **hmac-sha512**. For example: :: @@ -519,4 +519,3 @@ Execute ``confignetwork -s`` to configure provision IP address as static IP addr b. If the compute node is already running, use ``updatenode`` command to run ``confignetwork -s`` postscript without rebooting the node :: updatenode cn1 -P "confignetwork -s" - diff --git a/docs/source/guides/admin-guides/references/man5/site.5.rst b/docs/source/guides/admin-guides/references/man5/site.5.rst index bf93eb98e..0496a919e 100644 --- a/docs/source/guides/admin-guides/references/man5/site.5.rst +++ b/docs/source/guides/admin-guides/references/man5/site.5.rst @@ -92,11 +92,21 @@ site Attributes: ------------- DHCP ATTRIBUTES ------------- - dhcpomapialgorithm: The TSIG/OMAPI algorithm used by legacy ISC DHCP and - BIND DDNS integration. Valid values are hmac-md5, + dhcpomapialgorithm: The TSIG algorithm used by BIND DDNS and, for legacy + ISC DHCP, OMAPI. Valid values are hmac-md5, hmac-sha1, hmac-sha224, hmac-sha256, hmac-sha384, - and hmac-sha512. The default is hmac-md5 for - compatibility with existing ISC DHCP installations. + and hmac-sha512. New installations on Enterprise Linux + 9 or later and Ubuntu 20.04 or later set hmac-sha256. + Ubuntu 18.04, SLES 12, SLES 15, and openSUSE Leap 15 + leave this attribute unset because their bundled + omshell does not support the key-algorithm command. + When this attribute is not set, including on an + existing installation, xCAT uses hmac-md5 for + compatibility. HMAC-MD5 is not approved for FIPS + mode; a FIPS-mode site that needs OMAPI must provide + an omshell supporting key-algorithm and explicitly + select a SHA-2 algorithm. Kea does not use OMAPI, but + Kea DDNS uses this TSIG algorithm. dhcpomapikeyname: The TSIG/OMAPI key name used by legacy ISC DHCP and BIND DDNS integration. The default is xcat_key. The diff --git a/perl-xCAT/xCAT/DHCP/OmapiPolicy.pm b/perl-xCAT/xCAT/DHCP/OmapiPolicy.pm index 36b2b6d77..a3621a3ce 100644 --- a/perl-xCAT/xCAT/DHCP/OmapiPolicy.pm +++ b/perl-xCAT/xCAT/DHCP/OmapiPolicy.pm @@ -64,6 +64,24 @@ sub normalize_algorithm { return; } +sub new_install_default_algorithm { + my ( $class, %args ) = @_; + + my $platform = $args{platform}; + my $os = $args{os}; + + return unless $args{is_new_install}; + return 'hmac-sha256' + if defined($platform) && $platform =~ /^el(\d+)\b/i && $1 >= 9; + if ( defined($os) && $os =~ /^ubuntu,(\d+\.\d+(?:\.\d+)*)\b/i ) { + my $ubuntu_version = $1; + require xCAT::Utils; + return 'hmac-sha256' + if xCAT::Utils->version_cmp( $ubuntu_version, '20.04' ) >= 0; + } + return; +} + sub normalize_key_name { my ( $class, $key_name ) = @_; diff --git a/perl-xCAT/xCAT/Schema.pm b/perl-xCAT/xCAT/Schema.pm index cca78aa90..7f1578a3b 100644 --- a/perl-xCAT/xCAT/Schema.pm +++ b/perl-xCAT/xCAT/Schema.pm @@ -1042,11 +1042,21 @@ passed as argument rather than by table value', " reservations use JSON render and reload unless Control\n" . " Agent operations are explicitly enabled and the Kea\n" . " host-commands hook is installed.\n\n" . -" dhcpomapialgorithm: The TSIG/OMAPI algorithm used by legacy ISC DHCP and\n" . -" BIND DDNS integration. Valid values are hmac-md5,\n" . +" dhcpomapialgorithm: The TSIG algorithm used by BIND DDNS and, for legacy\n" . +" ISC DHCP, OMAPI. Valid values are hmac-md5,\n" . " hmac-sha1, hmac-sha224, hmac-sha256, hmac-sha384,\n" . -" and hmac-sha512. The default is hmac-md5 for\n" . -" compatibility with existing ISC DHCP installations.\n\n" . +" and hmac-sha512. New installations on Enterprise Linux\n" . +" 9 or later and Ubuntu 20.04 or later set hmac-sha256.\n" . +" Ubuntu 18.04, SLES 12, SLES 15, and openSUSE Leap 15\n" . +" leave this attribute unset because their bundled\n" . +" omshell does not support the key-algorithm command.\n" . +" When this attribute is not set, including on an\n" . +" existing installation, xCAT uses hmac-md5 for\n" . +" compatibility. HMAC-MD5 is not approved for FIPS\n" . +" mode; a FIPS-mode site that needs OMAPI must provide\n" . +" an omshell supporting key-algorithm and explicitly\n" . +" select a SHA-2 algorithm. Kea does not use OMAPI, but\n" . +" Kea DDNS uses this TSIG algorithm.\n\n" . " dhcpomapikeyname: The TSIG/OMAPI key name used by legacy ISC DHCP and\n" . " BIND DDNS integration. The default is xcat_key. The\n" . " value maps to the passwd table entry where key=omapi\n" . diff --git a/xCAT-server/sbin/xcatconfig b/xCAT-server/sbin/xcatconfig index 7eec28355..829116d93 100755 --- a/xCAT-server/sbin/xcatconfig +++ b/xCAT-server/sbin/xcatconfig @@ -25,6 +25,7 @@ use strict; use xCAT::Utils; use xCAT::SvrUtils; use xCAT::DHCP::Backend; +use xCAT::DHCP::OmapiPolicy; use xCAT::TLSPolicy qw(tls_setting_warnings); use xCAT::NetworkUtils; use Getopt::Long; @@ -134,6 +135,13 @@ else $::osname = 'Linux'; } +# Record whether this invocation is creating a new site before database setup +# runs. Reinitializing an existing site must preserve its key algorithm. +my $initializing_new_site = + $::INITIALINSTALL + && !-r "/etc/xcat/site.sqlite" + && !-r "/etc/xcat/cfgloc"; + # if on rhel6, check to see if perl-IO-Compress-Zlib* is installed if (($::INITIALINSTALL) || ($::UPDATEINSTALL)) { @@ -1253,6 +1261,16 @@ sub initDB $chtabcmds .= "$::XCATROOT/sbin/chtab key=vsftp site.value=n;"; $chtabcmds .= "$::XCATROOT/sbin/chtab key=cleanupxcatpost site.value=no;"; $chtabcmds .= "$::XCATROOT/sbin/chtab key=cleanupdiskfullxcatpost site.value=no;"; + my $omapi_algorithm = + xCAT::DHCP::OmapiPolicy->new_install_default_algorithm( + is_new_install => $initializing_new_site, + platform => xCAT::Utils->osver("platform"), + os => xCAT::Utils->osver("all"), + ); + if ($omapi_algorithm) { + $chtabcmds .= + "$::XCATROOT/sbin/chtab key=dhcpomapialgorithm site.value=$omapi_algorithm;"; + } $chtabcmds .= "$::XCATROOT/sbin/chtab key=dhcplease site.value=43200;"; $chtabcmds .= "$::XCATROOT/sbin/chtab key=auditnosyslog site.value=0;"; $chtabcmds .= "$::XCATROOT/sbin/chtab key=xcatsslversion site.value=;"; diff --git a/xCAT-test/autotest/testcase/dhcp_unit/cases0 b/xCAT-test/autotest/testcase/dhcp_unit/cases0 index b95fe7e68..51f51c286 100644 --- a/xCAT-test/autotest/testcase/dhcp_unit/cases0 +++ b/xCAT-test/autotest/testcase/dhcp_unit/cases0 @@ -6,3 +6,12 @@ cmd:prove -I/opt/xcat/lib/perl -I/opt/xcat/lib/perl/xCAT /opt/xcat/share/xcat/to check:rc==0 check:output=~All tests successful end + +start:ddns_omapi_policy_unit_tests +description:Run the DDNS OMAPI policy Perl unit test through xcattest +os:Linux +label:mn_only,ci_test,dhcp,dns,unit,ddns_unit +cmd:prove -I/opt/xcat/lib/perl -I/opt/xcat/lib/perl/xCAT /opt/xcat/share/xcat/tools/autotest/unit/ddns_omapi_policy.t +check:rc==0 +check:output=~All tests successful +end diff --git a/xCAT-test/unit/ddns_omapi_policy.t b/xCAT-test/unit/ddns_omapi_policy.t index 5244eed87..a0ccc8aed 100644 --- a/xCAT-test/unit/ddns_omapi_policy.t +++ b/xCAT-test/unit/ddns_omapi_policy.t @@ -21,7 +21,27 @@ else { require xCAT_plugin::ddns; } -my $defaults = xCAT::DHCP::OmapiPolicy->settings( site_values => {} ); +sub omapi_settings { + my (%overrides) = @_; + return xCAT::DHCP::OmapiPolicy->settings( + site_values => { + dhcpomapialgorithm => undef, + dhcpomapikeyname => undef, + dhcpomshellpath => undef, + %overrides, + } + ); +} + +# Model a populated xCAT site and require each fixture to override it fully. +our %XCATSITEVALS; +local %XCATSITEVALS = ( + dhcpomapialgorithm => 'hmac-sha256', + dhcpomapikeyname => 'site-key', + dhcpomshellpath => '/opt/site/bin/omshell', +); + +my $defaults = omapi_settings(); is( xCAT_plugin::ddns::ddns_key_contents( { @@ -33,11 +53,9 @@ is( 'default DDNS key remains xcat_key with hmac-md5' ); -my $sha512 = xCAT::DHCP::OmapiPolicy->settings( - site_values => { - dhcpomapialgorithm => 'hmac-sha512', - dhcpomapikeyname => 'provider.key', - } +my $sha512 = omapi_settings( + dhcpomapialgorithm => 'hmac-sha512', + dhcpomapikeyname => 'provider.key', ); is( diff --git a/xCAT-test/unit/dhcp_backend_selection.t b/xCAT-test/unit/dhcp_backend_selection.t index 8363a851d..544d0cf76 100644 --- a/xCAT-test/unit/dhcp_backend_selection.t +++ b/xCAT-test/unit/dhcp_backend_selection.t @@ -91,6 +91,39 @@ is( 'Ubuntu LTS releases newer than 24.04 default to Kea' ); +is( + xCAT::DHCP::Backend->default_backend( + platform => '', + os => 'sles12', + os_name => 'sles', + version => 12 + ), + 'isc', + 'SLES 12 defaults to ISC' +); + +is( + xCAT::DHCP::Backend->default_backend( + platform => '', + os => 'sles15', + os_name => 'sles', + version => 15 + ), + 'isc', + 'SLES 15 defaults to ISC' +); + +is( + xCAT::DHCP::Backend->default_backend( + platform => '', + os => 'opensuse-leap15', + os_name => 'opensuse-leap', + version => 15 + ), + 'isc', + 'openSUSE Leap 15 defaults to ISC' +); + is( xCAT::DHCP::Backend->choose( requested => 'isc', os => 'rhel10', platform => 'el10' )->{name}, 'isc', diff --git a/xCAT-test/unit/dhcp_omapi_policy.t b/xCAT-test/unit/dhcp_omapi_policy.t index 15d74e79b..a871ade34 100644 --- a/xCAT-test/unit/dhcp_omapi_policy.t +++ b/xCAT-test/unit/dhcp_omapi_policy.t @@ -9,7 +9,31 @@ use Test::More; use xCAT::DHCP::OmapiPolicy; -my $defaults = xCAT::DHCP::OmapiPolicy->settings( site_values => {} ); +sub omapi_settings { + my (%overrides) = @_; + return xCAT::DHCP::OmapiPolicy->settings( + site_values => { + dhcpomapialgorithm => undef, + dhcpomapikeyname => undef, + dhcpomshellpath => undef, + %overrides, + } + ); +} + +# Model a populated xCAT site and require each fixture to override it fully. +our %XCATSITEVALS; +local %XCATSITEVALS = ( + dhcpomapialgorithm => 'hmac-sha256', + dhcpomapikeyname => 'site-key', + dhcpomshellpath => '/opt/site/bin/omshell', +); + +my $site_settings = xCAT::DHCP::OmapiPolicy->settings(); +is( $site_settings->{algorithm}, 'hmac-sha256', + 'runtime settings read the configured site algorithm' ); + +my $defaults = omapi_settings(); is( $defaults->{algorithm}, 'hmac-md5', 'default OMAPI algorithm remains hmac-md5' ); is( $defaults->{key_name}, 'xcat_key', @@ -28,12 +52,143 @@ is( 'default omshell preamble keeps legacy key command without key-algorithm' ); -my $sha512 = xCAT::DHCP::OmapiPolicy->settings( - site_values => { - dhcpomapialgorithm => ' HMAC-SHA512 ', - dhcpomapikeyname => 'external.key-name', - dhcpomshellpath => '/opt/dhcp/bin/omshell', - } +is( + xCAT::DHCP::OmapiPolicy->new_install_default_algorithm( + is_new_install => 1, + platform => 'el9' + ), + 'hmac-sha256', + 'new EL9 installations default to hmac-sha256' +); +is( + xCAT::DHCP::OmapiPolicy->new_install_default_algorithm( + is_new_install => 1, + platform => 'el8' + ), + undef, + 'new EL8 installations retain the implicit MD5 default' +); +is( + xCAT::DHCP::OmapiPolicy->new_install_default_algorithm( + is_new_install => 1, + platform => 'el10' + ), + 'hmac-sha256', + 'new EL10 installations default DDNS TSIG to hmac-sha256' +); +is( + xCAT::DHCP::OmapiPolicy->new_install_default_algorithm( + is_new_install => 0, + platform => 'el9' + ), + undef, + 'existing EL9 installations retain their key algorithm choice' +); + +is( + xCAT::DHCP::OmapiPolicy->new_install_default_algorithm( + is_new_install => 1, + os => 'ubuntu,18.04' + ), + undef, + 'new Ubuntu 18.04 installations retain the implicit MD5 default' +); +is( + xCAT::DHCP::OmapiPolicy->new_install_default_algorithm( + is_new_install => 1, + os => 'ubuntu,20.04' + ), + 'hmac-sha256', + 'new Ubuntu 20.04 installations default to hmac-sha256' +); +is( + xCAT::DHCP::OmapiPolicy->new_install_default_algorithm( + is_new_install => 1, + os => 'ubuntu,20.04.6' + ), + 'hmac-sha256', + 'Ubuntu 20.04 point releases default to hmac-sha256' +); +is( + xCAT::DHCP::OmapiPolicy->new_install_default_algorithm( + is_new_install => 1, + os => 'ubuntu,22.04' + ), + 'hmac-sha256', + 'new Ubuntu 22.04 installations default to hmac-sha256' +); +is( + xCAT::DHCP::OmapiPolicy->new_install_default_algorithm( + is_new_install => 1, + os => 'ubuntu,24.04' + ), + 'hmac-sha256', + 'new Ubuntu 24.04 installations default to hmac-sha256' +); +is( + xCAT::DHCP::OmapiPolicy->new_install_default_algorithm( + is_new_install => 1, + os => 'ubuntu,26.04' + ), + 'hmac-sha256', + 'newer Ubuntu installations default to hmac-sha256' +); +is( + xCAT::DHCP::OmapiPolicy->new_install_default_algorithm( + is_new_install => 0, + os => 'ubuntu,24.04' + ), + undef, + 'existing Ubuntu installations retain their key algorithm choice' +); + +is( + xCAT::DHCP::OmapiPolicy->new_install_default_algorithm( + is_new_install => 1, + os => 'sles,12.5' + ), + undef, + 'new SLES 12 installations retain the implicit MD5 default' +); +is( + xCAT::DHCP::OmapiPolicy->new_install_default_algorithm( + is_new_install => 1, + os => 'sles,15.6' + ), + undef, + 'new SLES 15 installations retain the implicit MD5 default' +); +is( + xCAT::DHCP::OmapiPolicy->new_install_default_algorithm( + is_new_install => 1, + os => 'opensuse-leap,15.6' + ), + undef, + 'new openSUSE Leap 15 installations retain the implicit MD5 default' +); +is( + xCAT::DHCP::OmapiPolicy->new_install_default_algorithm( + is_new_install => 0, + os => 'sles,15.6' + ), + undef, + 'existing SLES installations retain their key algorithm choice' +); + +my $explicit_md5 = omapi_settings( + dhcpomapialgorithm => 'hmac-md5', +); +is( $explicit_md5->{algorithm}, 'hmac-md5', + 'an explicit hmac-md5 setting remains supported' ); +ok( $explicit_md5->{algorithm_explicit}, + 'an explicit hmac-md5 setting remains marked as explicit' ); +ok( !$explicit_md5->{needs_omshell_key_algorithm}, + 'explicit MD5 keeps the legacy omshell command format' ); + +my $sha512 = omapi_settings( + dhcpomapialgorithm => ' HMAC-SHA512 ', + dhcpomapikeyname => 'external.key-name', + dhcpomshellpath => '/opt/dhcp/bin/omshell', ); is( $sha512->{algorithm}, 'hmac-sha512', 'algorithm is canonicalized' ); is( $sha512->{key_rr_type}, 165, 'SHA512 KEY RR type is mapped' ); @@ -61,32 +216,32 @@ is( xCAT::DHCP::OmapiPolicy->key_owner($sha512), 'external.key-name.', 'DNS key owner is fully qualified' ); like( - xCAT::DHCP::OmapiPolicy->settings( - site_values => { dhcpomapialgorithm => 'sha512' } + omapi_settings( + dhcpomapialgorithm => 'sha512', )->{error}, qr/site\.dhcpomapialgorithm/, 'invalid algorithm is rejected' ); like( - xCAT::DHCP::OmapiPolicy->settings( - site_values => { dhcpomapikeyname => 'bad;name' } + omapi_settings( + dhcpomapikeyname => 'bad;name', )->{error}, qr/site\.dhcpomapikeyname/, 'unsafe key name is rejected' ); like( - xCAT::DHCP::OmapiPolicy->settings( - site_values => { dhcpomshellpath => 'omshell' } + omapi_settings( + dhcpomshellpath => 'omshell', )->{error}, qr/site\.dhcpomshellpath/, 'relative omshell path is rejected' ); like( - xCAT::DHCP::OmapiPolicy->settings( - site_values => { dhcpomshellpath => '/tmp/omshell;touch' } + omapi_settings( + dhcpomshellpath => '/tmp/omshell;touch', )->{error}, qr/site\.dhcpomshellpath/, 'shell metacharacters are rejected from omshell path'