/docs/man3.3/man5/config.html - OpenSSL 繁體中文

config

名稱

config - OpenSSL CONF 函式庫設定檔

說明

此頁面說明 OpenSSL 設定檔的語法，由 NCONF_load(3) 和相關函式解析。此格式由許多 OpenSSL 指令使用，並在任何應用程式使用時初始化函式庫。

第一部分說明設定檔的一般語法，後續部分說明個別模組的語意。其他模組說明於 fips_config(5) 和 x509v3_config(5)。ASN.1 值定義的語法說明於 ASN1_generate_nconf(3)。

語法

設定檔是一系列行。空白行和行元素之間的空白沒有意義。註解以 # 字元開頭；其餘行會被忽略。如果 # 是行中第一個非空白字元，整行會被忽略。

指令

兩個指令可控制設定檔的解析：.include 和 .pragma。

為了相容於舊版 OpenSSL，指令後的等號會被忽略。舊版會將其視為指定，因此如果語意差異很重要，應小心處理。

檔案可以使用 include 語法包含其他檔案

.include [=] pathname

如果 pathname 是簡單檔名，該檔案會直接包含在該點。包含的檔案可以有指定其他檔案的 .include 陳述式。如果 pathname 是目錄，該目錄中所有具有 .cnf 或 .conf 副檔名的檔案都會被包含。（這僅適用於支援 POSIX IO 的系統。）pathname 中找到的任何子目錄都會被忽略。類似地，如果在掃描目錄時開啟檔案，且該檔案有指定目錄的 .include 指令，該目錄也會被忽略。

一般來說，路徑名稱應為絕對路徑；這可以用以下所述的abspath和includedir實用程式來強制執行。如果環境變數OPENSSL_CONF_INCLUDE存在，它會預先加到所有相對路徑名稱。如果路徑名稱仍然是相對的，它會根據目前的作業目錄來詮釋。

若要要求所有檔案包含都指定絕對路徑，請使用下列指令

.pragma [=] abspath:value

預設行為，其中值為false或off，是允許相對路徑。若要要求所有.include路徑名稱為絕對路徑，請使用值為true或on。

在這些檔案中，美元符號$用來參照變數，如下所述。然而，在某些平台上，通常會將$視為符號名稱中的常規字元。支援此行為可以使用下列指令

.pragma [=] dollarid:value

預設行為，其中值為false或off，是將美元符號視為表示變數名稱；foo$bar會詮釋為foo，後接變數bar的擴充。如果值為true或on，則foo$bar為單一的七個字元名稱，且變數擴充必須使用大括弧或括號指定。

.pragma [=] includedir:value

如果在.include指令中指定相對路徑名稱，且環境變數OPENSSL_CONF_INCLUDE不存在，則會將實用程式includedir的值（如果存在）預先加到路徑名稱。

設定

設定檔分為許多區段。區段以方括號中的區段名稱開頭，並在新的區段開始或檔案結束時結束。區段名稱可以包含字母數字字元和底線。名稱和方括號之間的空白會移除。

設定檔的第一個區段很特別，稱為預設區段。此區段通常沒有名稱，且從檔案開始延伸到第一個有名稱的區段。當查詢名稱時，會先在目前的或有名稱的區段中查詢，必要時再查詢預設區段。

環境會對應到一個稱為ENV的區段。

在區段內有一系列名稱/值指定，如下所述。提醒您，此範例中顯示的方括號是必要的，不是可選的

[ section ]
name1 = This is value1
name2 = Another value
...
[ newsection ]
name1 = New value1
name3 = Value 3

名稱可以包含任何字母數字字元，以及一些標點符號，例如. , ;和_。名稱後和等號前的空白會忽略。

如果名稱在同一個區段中重複，則除了最後一個值之外，其餘都會忽略。在某些情況下，例如使用憑證 DN，同一個欄位可能會出現多次。為了支援此功能，像openssl-req(1)這樣的指令會忽略任何以句點開頭的前置文字。例如

1.OU = First OU
2.OU = Second OU

值包含=字元後面的字串，直到行尾，並移除任何前導和尾隨空白。

值字串會進行變數擴充。文字$var或${var}會插入目前區段中指定變數的值。若要使用其他區段的值，請使用$section::name或${section::name}。透過使用$ENV::name，會替換指定環境變數的值。

在參照其值之前，必須先定義變數，否則會標示錯誤，且檔案不會載入。這可以用在變數使用前，在default區段中指定預設值來解決。

ENV區段中的任何名稱/值設定都可供組態檔使用，但不會傳播到環境中。

如果值最後長度超過 64k，則會產生錯誤。

可以使用值周圍的單引號'或雙引號"，或在字元前使用反斜線\來跳脫特定字元，透過將行的最後一個字元設為\，值字串可以跨多行。此外，會辨識序列\n、\r、\b和\t。

上面說明套用於value的擴充和跳脫規則，也套用於.include指令的路徑名稱。

OPENSSL 函式庫組態

以下區段使用非正式術語模組來指 OpenSSL 功能的一部分。這與正式術語FIPS 模組不同，例如。

OpenSSL 組態會在預設區段中查詢openssl_conf的值，並將其視為指定如何組態函式庫中任何模組的區段名稱。將任何模組保留在其預設組態中並非錯誤。應用程式可以透過直接呼叫 CONF_modules_load_file() 等方式指定不同的名稱。

OpenSSL 也會查詢config_diagnostics的值。如果存在且具有非零數值，傳遞給 CONF_modules_load() 的任何錯誤抑制旗標都會被忽略。這對於診斷錯誤組態很有用，但其在生產中的使用需要額外的考量。啟用此選項後，組態錯誤會完全阻止存取服務。在沒有此選項且存在組態錯誤的情況下，將允許存取，但不會使用所需的組態。

# These must be in the default section
config_diagnostics = 1
openssl_conf = openssl_init

[openssl_init]
oid_section = oids
providers = providers
alg_section = evp_properties
ssl_conf = ssl_configuration
engines = engines
random = random

[oids]
... new oids here ...

[providers]
... provider stuff here ...

[evp_properties]
... EVP properties here ...

[ssl_configuration]
... SSL/TLS configuration properties here ...

[engines]
... engine properties here ...

[random]
... random properties here ...

每個模組的語意如下所述。片語「初始化區段」是指由 openssl_conf 或其他名稱（如上述範例中的 openssl_init）識別的區段。以下範例假設上述組態用於指定個別區段。

ASN.1 物件識別碼組態

初始化區段中的名稱 oid_section 命名包含 OID 名稱/值對的區段。名稱是簡短名稱；值是選用的長名稱，後接逗號和數值。雖然有些 OpenSSL 指令有自己的區段用於指定 OID，但此區段讓它們可供所有指令和應用程式使用。

[oids]
shortName = a very long OID name, 1.2.3.4
newoid1 = 1.2.3.4.1
some_other_oid = 1.2.3.5

如果 example.cnf 檔案中包含上述片段的完整組態，則下列命令列

OPENSSL_CONF=example.cnf openssl asn1parse -genstr OID:1.2.3.4.1

將會輸出

0:d=0  hl=2 l=   4 prim: OBJECT            :newoid1

顯示 OID「newoid1」已新增為「1.2.3.4.1」。

提供者組態

初始化區段中的名稱 providers 命名包含密碼編譯提供者組態的區段。此區段中的名稱/值指定各命名一個提供者，並指向該提供者的組態區段。提供者特定區段用於指定如何載入模組、啟用它，以及設定其他參數。

在提供者區段中，下列名稱有意義

identity

這用於指定替代名稱，覆寫提供者清單中指定的預設名稱。例如

[providers]
foo = foo_provider

[foo_provider]
identity = my_fips_module

module

指定要載入的模組（通常是共用函式庫）的路徑名稱。

activate

如果存在且設定為下列值之一：yes、on、true 或 1，則會啟用關聯的提供者。相反地，將此值設定為 no、off、false 或 0 將會阻止啟用提供者。設定可以是大寫或小寫。將 activate 設定為任何其他設定，或省略設定值，將會導致錯誤。

= 項目 soft_load

如果啟用，會通知函式庫在無法啟用請求的提供者時清除錯誤堆疊。值 1、yes、true 或 on（大寫或小寫）將會啟用此設定，而值 0、no、false 或 off（大寫或小寫）將會停用此設定。任何其他值都會產生錯誤。請注意，如果未提供此設定，預設為 off

區段以及子區段中的所有參數都會提供給提供者。

預設提供者及其啟用

如果沒有明確啟用任何提供者，則會隱式啟用預設提供者。請參閱 OSSL_PROVIDER-default(7) 以取得更多詳細資料。

如果您新增一個明確啟用任何其他提供者的區段，您很可能需要明確啟用預設提供者，否則它在 openssl 中將無法使用。它可能會讓系統無法遠端使用。

EVP 組態

初始化區段中的名稱 alg_section 會命名使用 EVP API 時包含演算法屬性的區段。

在演算法屬性區段中，下列名稱具有意義

default_properties

值可以是任何可接受的 EVP_set_default_properties() 屬性查詢字串。

fips_mode (已棄用)

值是一個布林值，可以是 yes 或 no。如果值是 yes，這完全等同於

default_properties = fips=yes

如果值是 no，則不會發生任何事。使用此名稱已棄用，如果使用，它必須是區段中唯一的名稱。

SSL 組態

初始化區段中的名稱 ssl_conf 會命名包含 SSL/TLS 組態清單的區段。與提供者一樣，此區段中的每個名稱都會識別一個區段，其中包含該名稱的組態。例如

[ssl_configuration]
server = server_tls_config
client = client_tls_config
system_default = tls_system_default

[server_tls_config]
... configuration for SSL/TLS servers ...

[client_tls_config]
... configuration for SSL/TLS clients ...

組態名稱 system_default 具有特殊意義。如果它存在，則每當建立 SSL_CTX 物件時都會套用它。例如，要強制套用系統範圍的最低 TLS 和 DTLS 協定版本

[tls_system_default]
MinProtocol = TLSv1.2
MinProtocol = DTLSv1.2

最低 TLS 協定會套用至基於 TLS 的 SSL_CTX 物件，而最低 DTLS 協定會套用至基於 DTLS 的物件。相同的規則也適用於使用 MaxProtocol 設定的最大版本。

每個組態區段都包含名稱/值配對，這些配對會由 SSL_CONF_cmd(3) 進行剖析，而 SSL_CONF_cmd(3) 會由 SSL_CTX_config() 或 SSL_config() 適當地呼叫。請注意，組態區段中初始句點之前的任何字元都會被忽略，因此可以多次使用相同的指令。這對於載入不同的金鑰類型來說可能是最有用的，如下所示

[server_tls_config]
RSA.Certificate = server-rsa.pem
ECDSA.Certificate = server-ecdsa.pem

引擎組態

初始化區段中的名稱 engines 會命名包含 ENGINE 組態清單的區段。與提供者一樣，此區段中的每個名稱都會識別一個引擎，其中包含該引擎的組態。引擎特定區段用於指定如何載入引擎、啟用引擎，以及設定其他參數。

在引擎區段中，下列名稱具有意義

engine_id

這用於指定替代名稱，覆寫引擎清單中指定的預設名稱。如果存在，它必須是第一個。例如

[engines]
foo = foo_engine

[foo_engine]
engine_id = myfoo

dynamic_path

這會載入並新增一個 ENGINE 從給定的路徑。它等同於傳送 ctrls SO_PATH 具有路徑引數，接著是 LIST_ADD 具有值 2 和 LOAD 到動態 ENGINE。如果這不是必要的行為，則可以使用 ctrl 命令直接傳送其他 ctrls 到動態 ENGINE。

init

這會指定是否要初始化 ENGINE。如果值為 0，ENGINE 將不會初始化，如果值為 1，會嘗試立即初始化 ENGINE。如果沒有 init 命令，則會在處理其區段中的所有命令後，嘗試初始化 ENGINE。

default_algorithms

這會設定 ENGINE 將使用 ENGINE_set_default_string() 函數提供的預設演算法。

所有其他名稱都會被視為傳送至 ENGINE 的 ctrl 命令名稱，而值是與命令一起傳遞的引數。特殊值 EMPTY 表示沒有值與命令一起傳送。例如

[engines]
foo = foo_engine

[foo_engine]
dynamic_path = /some/path/fooengine.so
some_ctrl = some_value
default_algorithms = ALL
other_ctrl = EMPTY

隨機組態

初始化區段中的名稱 random 會命名包含亂數產生器設定的區段。

在隨機區段中，下列名稱具有意義

random

這用於指定隨機位元產生器。例如

[random]
random = CTR-DRBG

可用的隨機位元產生器為

CTR-DRBG
HASH-DRBG
HMAC-DRBG

cipher

這會指定 CTR-DRBG 隨機位元產生器將使用的密碼。其他隨機位元產生器會忽略此名稱。預設值為 AES-256-CTR。

digest

這會指定 HASH-DRBG 或 HMAC-DRBG 隨機位元產生器將使用的摘要。其他隨機位元產生器會忽略此名稱。

properties

這會設定在擷取隨機位元產生器和任何基礎演算法時使用的屬性查詢。

seed

這會設定應使用的隨機性來源。預設情況下，會在 FIPS 提供者外部使用 SEED-SRC。FIPS 提供者使用回呼存取驗證邊界外部的相同隨機性來源。

seed_properties

這會設定在擷取隨機性來源時使用的屬性查詢。

範例

此範例顯示如何使用引號和跳脫字元。

# This is the default section.
HOME = /temp
configdir = $ENV::HOME/config

[ section_one ]
# Quotes permit leading and trailing whitespace
any = " any variable name "
other = A string that can \
cover several lines \
by including \\ characters
message = Hello World\n

[ section_two ]
greeting = $section_one::message

此範例顯示如何安全地展開環境變數。在此範例中，變數 tempfile 意指暫存檔案，而環境變數 TEMP 或 TMP（如果存在）會指定檔案應放置的目錄。由於如果變數不存在，系統會檢查預設區段，因此可以設定 TMP 預設為 /tmp，而 TEMP 預設為 TMP。

# These two lines must be in the default section.
TMP = /tmp
TEMP = $ENV::TMP

# This can be used anywhere
tmpfile = ${ENV::TEMP}/tmp.filename

此範例顯示如何對應用程式 sample 執行 FIPS 模式。

sample = fips_config

[fips_config]
alg_section = evp_properties

[evp_properties]
default_properties = "fips=yes"

環境

OPENSSL_CONF: 設定檔的路徑，或沒有設定檔時為空字串。在設定使用者 ID 和設定群組 ID 的程式中會略過。
OPENSSL_ENGINES: 引擎目錄的路徑。在設定使用者 ID 和設定群組 ID 的程式中會略過。
OPENSSL_MODULES: OpenSSL 模組目錄的路徑，例如提供者。在設定使用者 ID 和設定群組 ID 的程式中會略過。
OPENSSL_CONF_INCLUDE: 要加到所有 .include 路徑前面的選用路徑。

BUGS

無法使用八進位 \nnn 形式納入字元。字串都以 Null 結尾，因此 Null 無法成為值的一部分。

跳脫符號不太正確：如果您想使用 \n 等序列，就不能在同一行使用任何引號跳脫符號。

一次只能開啟和讀取一個目錄的限制可以視為錯誤，應該修正。

HISTORY

未記錄的 API，NCONF_WIN32()，使用了一組稍有不同的解析規則，目的是針對 Microsoft Windows 平台進行調整。具體來說，反斜線字元不是跳脫字元，而且可以在路徑名稱中使用，只會辨識雙引號字元，而且註解以分號開頭。此函式已在 OpenSSL 3.0 中標示為已棄用；使用該語法的設定檔的應用程式必須修改。

COPYRIGHT

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

開啟SSL

密碼學和 SSL/TLS 工具包