/docs/man3.3/man1/openssl-fipsinstall.html

openssl-fipsinstall

名稱

openssl-fipsinstall - 執行 FIPS 組態安裝

語法

openssl fipsinstall [-help] [-in configfilename] [-out configfilename] [-module modulefilename] [-provider_name providername] [-section_name sectionname] [-verify] [-mac_name macname] [-macopt nm:v] [-noout] [-quiet] [-pedantic] [-no_conditional_errors] [-no_security_checks] [-ems_check] [-no_drbg_truncated_digests] [-self_test_onload] [-self_test_oninstall] [-corrupt_desc selftest_description] [-corrupt_type selftest_type] [-config parent_config]

說明

此指令用於產生 FIPS 模組組態檔。此組態檔可在每次載入 FIPS 模組時使用，以傳遞資料至 FIPS 模組自我測試。FIPS 模組總是會驗證其 MAC，但選擇性地僅需在安裝時執行一次 KAT。

產生的組態檔包含

- FIPS 模組檔案的 MAC。
- 測試狀態指標。: 此指標表示已知答案自我測試 (KAT) 是否已成功執行。
- 狀態指標的 MAC。
- 有條件自我測試錯誤的控制項。: 預設情況下，如果連續測試 (例如金鑰對測試) 失敗，則 FIPS 模組將進入錯誤狀態，且之後將無法存取任何服務或加密演算法。預設值「1」將導致進入 fips 模組錯誤狀態。如果值為「0」，則不會進入模組錯誤狀態。無論是否進入錯誤狀態，目前的作業 (例如金鑰產生) 都會傳回錯誤。如果未進入模組錯誤狀態，則使用者負責重試作業。
- 控制項用於指示是否執行執行時期安全性檢查。: 此控制項表示是否使用與執行安全性參數 (例如金鑰的最低安全性強度和核准曲線名稱) 相關的執行時期檢查。預設值「1」將執行檢查。如果值為「0」，則不執行檢查，且 FIPS 相容性必須由相關安全性政策中記載的程序執行。

此檔案說明於 fips_config(5) 中。

選項

-help

列印使用說明訊息。

-module filename

要執行完整性檢查的 FIPS 模組檔案名稱。檔案名稱中提供的路徑用於在模組啟動時載入模組，且此路徑會覆寫環境變數 OPENSSL_MODULES。

-out configfilename

輸出組態資料的檔案名稱；預設為標準輸出。

-in configfilename

從中載入組態資料的輸入檔名。如果指定了 -verify 選項，則必須使用。

-verify

驗證輸入組態檔是否包含正確的資訊。

-provider_name providername

組態檔內提供者的名稱。預設值為 fips。

-section_name sectionname

組態檔內區段的名稱。預設值為 fips_sect。

-mac_name name

指定將使用的支援 MAC 演算法的名稱。可用的 MAC 機制會依據建置 OpenSSL 時所使用的選項而定。若要查看支援的 MAC 清單，請使用指令 openssl list -mac-algorithms。預設為 HMAC。

-macopt nm:v

傳遞選項給 MAC 演算法。可以在 EVP_MAC 實作文件找到完整的控制清單。此指令常用的控制字串為

key:string: 將 MAC 金鑰指定為字母數字字串（僅在金鑰只包含可列印字元時使用）。字串長度必須符合 MAC 演算法的任何限制。必須為每個 MAC 演算法指定金鑰。如果未提供金鑰，則使用 OpenSSL 組態時指定的預設值。
hexkey:string: 以十六進位形式指定 MAC 金鑰（每個位元組兩個十六進位數字）。金鑰長度必須符合 MAC 演算法的任何限制。必須為每個 MAC 演算法指定金鑰。如果未提供金鑰，則使用 OpenSSL 組態時指定的預設值。
digest:string: 由 HMAC 用作字母數字字串（僅在金鑰只包含可列印字元時使用）。字串長度必須符合 MAC 演算法的任何限制。若要查看支援的摘要清單，請使用指令 openssl list -digest-commands。預設摘要為 SHA-256。

-noout

停用自我測試記錄。

-pedantic

將模組組態為嚴格符合 FIPS，而非向下相容。這會啟用條件式錯誤、安全性檢查等。請注意，任何先前的組態選項都將被覆寫，而任何違反 FIPS 相容性的後續組態選項都將導致錯誤。

-no_conditional_errors

將模組組態為如果條件式自我測試失敗，則不會進入錯誤狀態，如上所述。

-no_security_checks

設定模組，使其不執行如上所述的執行時間安全性檢查。

啟用設定選項「no-fips-securitychecks」提供另一種方法，可在編譯時關閉檢查。

-ems_check

設定模組，使其在使用 TLS1_PRF KDF 演算法時，啟用執行時間擴充主機密碼 (EMS) 檢查。此檢查預設為停用。請參閱 RFC 7627，以取得與 EMS 相關的資訊。

-no_drbg_truncated_digests

設定模組，使其不允許在雜湊和 HMAC DRBG 中使用截斷摘要。請參閱 FIPS 140-3 IG D.R，以取得詳細資料。

-self_test_onload

不要將與「測試狀態指示器」和「MAC 狀態指示器」相關的兩個欄位寫入輸出設定檔。沒有這些欄位，每次載入模組時，自我測試 KATS 都會執行。此選項可用於交叉編譯，因為自我測試需要在每個目標機器上至少執行一次。一旦自我測試在目標機器上執行，使用者就可以使用其他機制將 2 個欄位新增至設定中。

這是預設值。

-self_test_oninstall

-self_test_oninstall 的相反。與「測試狀態指示器」和「MAC 狀態指示器」相關的兩個欄位會寫入輸出設定檔。

-quiet

不要輸出通過/失敗訊息。暗示 -noout。

-corrupt_desc selftest_description, -corrupt_type selftest_type

損壞選項可用於透過名稱測試一個或多個自我測試的失敗。任一選項或兩個選項都可以用於選擇要損壞的測試。請參閱 OSSL_PROVIDER-FIPS(7) 中 st-desc 和 st-type 的項目，以取得可使用的值。

-config parent_config

測試是否可以從指定的設定檔載入 FIPS 提供者。需要先呼叫此應用程式，以產生由基本 parent_config 設定檔包含的額外設定資料。請參閱 config(5)，以取得如何設定提供者區段的更多資訊。如果使用「-config」，所有其他選項都會被忽略。

備註

如果未指定選項 -quiet 和 -noout，或者使用了選項 -corrupt_desc 或 -corrupt_type，則預設會記錄自測結果。如果基本設定檔設定為自動載入 fips 模組，則 fips 模組將在 fipsinstall 應用程式有機會設定自己的自測回呼之前載入並自測。因此，自測輸出和選項 -corrupt_desc 和 -corrupt_type 將會被忽略。對於一般使用，基本設定檔應在產生 fips 設定檔時使用預設提供者。

在 OpenSSL 3.1 中新增了 -self_test_oninstall 選項，並將 -self_test_onload 選項設為預設。

在 OpenSSL 3.0 中新增了指令和所有其他選項。

範例

計算 FIPS 模組 fips.so 的 mac，並執行模組的 FIPS 自測，並儲存 fips.cnf 設定檔

openssl fipsinstall -module ./fips.so -out fips.cnf -provider_name fips

驗證設定檔 fips.cnf 是否包含正確的資訊

openssl fipsinstall -module ./fips.so -in fips.cnf  -provider_name fips -verify

破壞任何描述為 SHA1 的自測

openssl fipsinstall -module ./fips.so -out fips.cnf -provider_name fips \
        -corrupt_desc 'SHA1'

驗證是否可以從基本設定檔載入 fips 模組

export OPENSSL_CONF_INCLUDE=<path of configuration files>
export OPENSSL_MODULES=<provider-path>
openssl fipsinstall -config' 'default.cnf'

另請參閱

config(5)、fips_config(5)、OSSL_PROVIDER-FIPS(7)、EVP_MAC(3)

版權

根據 Apache License 2.0（「授權」）授權。您只能在遵守授權的條件下使用此檔案。您可以在原始程式碼散發檔案中的 LICENSE 檔案或 https://www.openssl.org/source/license.html 取得副本。