/docs/man3.3/man1/openssl-verification-options.html

openssl-verification-options

名稱

openssl-verification-options - 通用 X.509 憑證驗證選項

語法

openssl command [ options ... ] [ parameters ... ]

說明

在 OpenSSL 函式庫和各種 OpenSSL 指令中，驗證 X.509 憑證的情況很多。

X509_verify_cert(3) 實作憑證驗證。這是一個複雜的程序，包含許多步驟，並取決於許多選項。最重要的選項在以下各節中詳述。

簡而言之，需要建立並驗證有效的憑證鏈，從要驗證的目標憑證開始，並以由於某種政策而受信任的憑證結束。驗證是根據給定的目的進行的，也就是目標憑證的預期用途，例如 SSL 伺服器，或預設為任何目的。

每個 OpenSSL 指令如何處理錯誤的詳細資訊記載在特定指令頁面上。

DANE 支援記載在 openssl-s_client(1)、SSL_CTX_dane_enable(3)、SSL_set1_host(3)、X509_VERIFY_PARAM_set_flags(3) 和 X509_check_host(3) 中。

信任錨點

一般來說，根據 RFC 4158 和 RFC 5280，信任錨點是任何公鑰和相關主體識別名稱 (DN)，由於某些原因而被視為受信任，因此可作為憑證鏈的根部。

實際上，信任錨點以憑證的形式提供，其基本欄位為公鑰和主體 DN。除了 RFC 5280 中的要求外，OpenSSL 還會檢查此類憑證的有效期，並使用一些其他欄位。特別是，如果存在主體金鑰識別碼延伸，則會在建立鏈的過程中用於比對信任錨點。

在最簡單且最常見的情況下，信任錨點預設為所有置於信任儲存中的自簽署「根」CA 憑證，信任儲存是針對特定用途受信任的憑證集合。這類似於 Mozilla Firefox、Apple 和 Microsoft 的憑證儲存中使用的內容...

從 OpenSSL 的角度來看，信任錨點是一個憑證，應該加上明確指定目標憑證的用途，該憑證可以用作信任錨點。在 PEM 編碼中，這由TRUSTED CERTIFICATE 字串表示。此類指定提供一組正向信任屬性，明確說明對所列用途的信任，和/或一組負向信任屬性，明確拒絕對所列用途的使用。這些用途使用定義給最終實體憑證的 X.509 延伸中延伸金鑰用途 (EKU) 的值的編碼。另請參閱下方的「延伸金鑰用途」部分。

目前已識別的用途為 clientAuth (SSL 客戶端使用)、serverAuth (SSL 伺服器使用)、emailProtection (S/MIME 電子郵件使用)、codeSigning (物件簽署者使用)、OCSPSigning (OCSP 回應器使用)、OCSP (OCSP 要求使用)、timeStamping (TSA 伺服器使用) 和 anyExtendedKeyUsage。自 OpenSSL 1.1.0 起，最後一個區塊會在被拒絕時封鎖所有用途，或在受信任時啟用所有用途。

如果且僅如果符合下列所有條件，憑證（可能是 CA 憑證或終端實體憑證）才被視為給定用途的信任錨點：

它是信任儲存的元素。
它沒有拒絕給定用途的負面信任屬性。
它具有接受給定用途的正面信任屬性，或（預設）套用下列其中一個相容性條件：它是自簽署的，或已提供 -partial_chain 選項（對應於設定 X509_V_FLAG_PARTIAL_CHAIN 旗標）。

憑證路徑建置

首先，從目標憑證建置憑證鏈，並以信任錨點結束。

鏈會反覆建置，依序尋找具有適當金鑰用途的憑證，並符合下列所述的目前「主旨」憑證的發行者。如果存在此類憑證，則會採用找到的第一個目前有效的憑證，否則採用所有此類憑證中最近過期的憑證。為了提高效率，不會執行回溯，因此會忽略任何其他符合條件的候選發行者憑證。

當已新增自簽署憑證時，鏈建置會停止。在這種情況下，它必須完全符合信任錨點，否則鏈建置會失敗。

如果符合下列所有條件，候選發行者憑證會符合主旨憑證：

其主旨名稱符合主旨憑證的發行者名稱。
如果主旨憑證具有授權金鑰識別碼擴充功能，其每個子欄位都等於候選發行者憑證的對應主旨金鑰識別碼、序號和發行者欄位（只要兩個憑證中都存在這些欄位）。
用於簽署主旨憑證的憑證簽章演算法獲得支援，且等於候選發行者憑證的公開金鑰演算法。

查詢會先在信任儲存中搜尋發行者憑證。如果在此處找不到符合條件的憑證，它會諮詢未受信任（「中間」CA）憑證清單（如果已提供）。

憑證路徑驗證

當憑證鏈建置程序成功時，會徹底檢查鏈組成部分及其連結。

第一步是檢查每個憑證是否格式正確。只有在提供 -x509_strict 選項時，才會啟用這些檢查的一部分。

第二個步驟是檢查每個不受信任憑證的延伸是否與提供的用途相符。如果未提供 -purpose 選項，則不會執行此類檢查，但 SSL/TLS 連線設定除外，預設會檢查 sslserver 或 sslclient。目標或「根」憑證，以及任何其他不受信任的憑證，都必須具有與指定用途相容的延伸。除了目標或「根」憑證以外，所有憑證都必須是有效的 CA 憑證。在 openssl-x509(1) 中的「憑證延伸」中更詳細地描述了所需的確切延伸。

第三個步驟是檢查最後一個憑證（通常是自簽署根 CA 憑證）的信任設定。它必須受信任才能用於給定的用途。為了與以前版本的 OpenSSL 相容，沒有信任屬性的自簽署憑證被視為對所有用途都有效。

第四個也是最後一個步驟是檢查憑證鏈的有效性。對於鏈中的每個元素，包括根 CA 憑證，會根據 notBefore 和 notAfter 欄位指定的有效期，與目前的系統時間進行比對。-attime 旗標可用於使用「現在」以外的參考時間。也會檢查憑證簽章（除了通常自簽署根 CA 憑證的簽章，只有在提供 -check_ss_sig 選項時才會驗證）。驗證憑證簽章時，會檢查候選發行者憑證的 keyUsage 延伸（如果存在），以允許 digitalSignature 簽署代理憑證，或允許 keyCertSign 簽署其他憑證。如果所有作業都順利完成，則憑證會被視為有效。如果任何作業失敗，則憑證無效。

選項

受信任憑證選項

下列選項指定如何提供可用作特定用途信任錨點的憑證。如前所述，此類憑證的集合稱為信任儲存。

請注意，OpenSSL 沒有提供預設的信任錨點集。許多 Linux 發行版都包含系統預設值，並將 OpenSSL 設定為指向該預設值。Mozilla 維護一個有影響力的信任儲存，可在 https://www.mozilla.org/en-US/about/governance/policies/security-group/certs/ 找到。

可以使用下列選項指定要新增到信任儲存的憑證。

-CAfile file

載入指定的文件，其中包含 DER 格式的可信賴憑證，或在輸入為 PEM 格式的情況下，可能包含多個可信賴憑證。PEM 編碼的憑證也可以設定信任屬性。

-no-CAfile

不要載入預設的可信賴憑證檔案。

-CApath dir

將指定目錄用作可信賴憑證的集合，即信任儲存。檔案應以每個憑證的 X.509 主體名稱雜湊值命名。這樣，程式庫就可以擷取發行者名稱，對其進行雜湊處理，並直接查詢檔案以取得發行者憑證。有關建立此類目錄的資訊，請參閱 openssl-rehash(1)。

-no-CApath

不要使用預設的可信賴憑證目錄。

-CAstore uri

使用 uri 作為 CA 憑證的儲存。URI 可以表示單一憑證，也可以表示憑證集合。在 file: 架構中的 URI 中，這會作為 -CAfile 或 -CApath，具體取決於 URI 是否表示單一檔案或目錄。有關 file: 架構的更多資訊，請參閱 ossl_store-file(7)。

在建置伺服器憑證鏈（例如使用 openssl-s_server(1)）或用戶端憑證鏈（例如使用 openssl-s_time(1)）時，也會使用這些憑證。

-no-CAstore

不要使用預設的可信賴 CA 憑證儲存。

驗證選項

可以使用下列旗標微調憑證驗證。

-verbose

列印有關執行作業的額外資訊。

-attime timestamp

使用 timestamp 指定的時間（而非目前的系統時間）執行驗證檢查。timestamp 是自 1970 年 1 月 1 日（即 Unix 紀元）以來經過的秒數。

-no_check_time

此選項會抑制檢查憑證和 CRL 的有效期是否符合目前時間。如果使用 -attime 選項指定驗證時間，則不會抑制檢查。

-x509_strict

這會停用針對損毀憑證的非相容解決方案。因此，會針對不符合 RFC 5280 的憑證擲回錯誤。

設定此選項時，除了其他條件外，還會檢查下列憑證格式條件

CA 憑證的基本限制必須標示為關鍵。
CA 憑證必須明確包含 keyUsage 延伸。
如果給定 pathlenConstraint，則必須允許 keyCertSign 主要用途。
對於非 CA 憑證，不得給定 pathlenConstraint。
任何憑證的發行者名稱不得為空。
CA 憑證的主體名稱、具有 crlSign 主要用途的憑證，以及沒有 subjectAlternativeName 的憑證的主體名稱不得為空。
如果給定 subjectAlternativeName 延伸，則不得為空。
signatureAlgorithm 欄位和憑證簽章必須一致。
任何給定的 authorityKeyIdentifier 和任何給定的 subjectKeyIdentifier 都不得標示為關鍵。
除非 X.509v3 憑證是自簽憑證，否則必須提供 authorityKeyIdentifier。
必須為所有 X.509v3 CA 憑證提供 subjectKeyIdentifier。

-ignore_critical

通常，如果存在 OpenSSL 不支援的未處理關鍵延伸，則會拒絕該憑證（如 RFC5280 所要求）。如果設定此選項，則會忽略關鍵延伸。

-issuer_checks

已忽略。

-crl_check

透過嘗試查詢有效的 CRL 來檢查終端實體憑證的有效性。如果找不到有效的 CRL，則會發生錯誤。

-crl_check_all

透過嘗試查詢有效的 CRL 來檢查鏈中所有憑證的有效性。

-use_deltas

啟用對增量 CRL 的支援。

-extended_crl

啟用延伸 CRL 功能，例如間接 CRL 和備用 CRL 簽署金鑰。

-suiteB_128_only, -suiteB_128, -suiteB_192

分別在 128 位元安全層級、128 位元或 192 位元，或僅在 192 位元安全層級啟用 Suite B 模式運作。有關詳細資訊，請參閱 RFC6460。特別是，支援的簽章演算法已減少為僅支援 ECDSA 和 SHA256 或 SHA384，且僅支援橢圓曲線 P-256 和 P-384。

-auth_level level

將憑證鏈驗證安全層級設定為level。驗證憑證鏈時，驗證安全層級會決定可接受的簽章和公開金鑰強度。要驗證憑證鏈，所有憑證的公開金鑰都必須符合指定的安全性level。簽章演算法安全層級會強制套用在鏈中的所有憑證，但鏈的信任錨點除外，信任錨點會直接受到信任或透過簽章以外的方式驗證。請參閱 SSL_CTX_set_security_level(3) 以取得可用層級的定義。預設安全層級為 -1 或「未設定」。在安全層級 0 或更低時，所有演算法都可接受。安全層級 1 至少需要 80 位元等效安全性，且具有廣泛的互通性，但它會拒絕 MD5 簽章或小於 1024 位元的 RSA 金鑰。

-partial_chain

如果可以建構不完整的鏈，則允許驗證成功。也就是說，以通常不會受到信任的憑證（因為它沒有匹配的正面信任屬性且不是自簽憑證）結尾的鏈，但它是信任儲存庫的元素。此憑證可能是自發行的，或屬於中間 CA。

-check_ss_sig

如果憑證假設是自簽署的，請驗證鏈中最後一個憑證的簽章。這項操作是禁止的，如果這是個非相容的 CA 憑證，且其金鑰使用限制不包含 keyCertSign 位元，這項操作將導致錯誤。這項驗證預設停用，因為它不會增加任何安全性。

-allow_proxy_certs

允許驗證代理憑證。

-trusted_first

從 OpenSSL 1.1.0 開始，這個選項預設開啟，且無法停用。

在建構憑證鏈時，透過 -CAfile、-CApath、-CAstore 或 -trusted 指定的受信任憑證，總是在透過 -untrusted 指定的任何憑證之前使用。

-no_alt_chains

從 OpenSSL 1.1.0 開始，由於 -trusted_first 始終開啟，這個選項沒有作用。

-trusted file

將 file 解析為一組一個或多個憑證。如果每個憑證具有合適的正向信任屬性，或者它是自簽署的，或者指定了 -partial_chain 選項，則每個憑證都符合受信任的資格。這個選項暗示 -no-CAfile、-no-CApath 和 -no-CAstore 選項，且無法與 -CAfile、-CApath 或 -CAstore 選項搭配使用，因此只有使用 -trusted 選項指定的憑證才是信任錨點。這個選項可以多次使用。

-untrusted file

將 file 解析為一組一個或多個憑證。所有憑證（通常是中間 CA）都被視為不受信任，且可用於從目標憑證建構憑證鏈到信任錨點。這個選項可以多次使用。

-policy arg

啟用政策處理，並將 arg 新增至使用者初始政策集（請參閱 RFC5280）。政策 arg 可以是數字形式的物件名稱 OID。這個引數可以出現多次。

-explicit_policy

設定政策變數 require-explicit-policy（請參閱 RFC5280）。

-policy_check

啟用憑證政策處理。

-policy_print

列印與政策處理相關的診斷資料。

-inhibit_any

設定政策變數 inhibit-any-policy（請參閱 RFC5280）。

-inhibit_map

設定政策變數 inhibit-policy-mapping（請參閱 RFC5280）。

-purpose purpose

憑證的預期用途。目前定義的用途為 sslclient、sslserver、nssslserver、smimesign、smimeencrypt、crlsign、ocsphelper、timestampsign、codesign 和 any。如果啟用對等憑證驗證，預設情況下，TLS 實作以及指令 s_client 和 s_server 分別檢查與 TLS 伺服器或 TLS 用戶端使用的相容性。

雖然 IETF RFC 5280 指出 id-kp-serverAuth 和 id-kp-clientAuth 僅供 WWW 使用，但實際上它們用於各種 TLS 用戶端和伺服器，而 OpenSSL 也假設如此。

-verify_depth num

將憑證鏈限制為 num 個中間 CA 憑證。最大深度鏈最多可以有 num+2 個憑證，因為最終實體憑證和信任錨定憑證都不會計入 -verify_depth 限制。

-verify_email 電子郵件

驗證 電子郵件 是否與主體備用名稱中的電子郵件地址或主體識別名稱中的電子郵件相符。

-verify_hostname 主機名稱

驗證 主機名稱 是否與主體備用名稱中的 DNS 名稱或主體憑證中的主體名稱相符。

-verify_ip ip

驗證 ip 是否與主體憑證的主體備用名稱中的 IP 地址相符。

-verify_name 名稱

使用預設驗證政策，例如信任模型和由名稱識別的必要憑證政策。信任模型決定哪個輔助信任或拒絕 OID 適用於驗證給定的憑證鏈。它們可以使用 -addtrust 和 -addreject 選項提供給 openssl-x509(1)。支援的政策名稱包括：預設、pkcs7、smime_sign、ssl_client、ssl_server。這些模擬 SSL、CMS 和 S/MIME 中使用的目的和信任設定組合。從 OpenSSL 1.1.0 開始，當未指定時，信任模型會從目的推斷出來，因此 -verify_name 選項在功能上等同於對應的 -purpose 設定。

延伸驗證選項

有時可能有多個憑證鏈導致最終實體憑證。這通常發生在根或中間 CA 為另一個組織中的 CA 簽發憑證時。另一個原因是 CA 可能有使用兩種不同簽章格式的中間憑證，例如 SHA-1 和 SHA-256 摘要。

以下選項可用於提供資料，讓 OpenSSL 指令產生替代鏈。

-xkey 輸入檔、-xcert 輸入檔、-xchain: 指定額外的憑證、私人金鑰和憑證鏈。它們的行為與 -cert、-key 和 -cert_chain 選項相同。指定時，回呼會傳回第一個有效鏈，並由用戶端使用。
-xchain_build: 指定應用程式是否應建立憑證鏈，以透過 -xkey、-xcert 和 -xchain 選項提供給伺服器以取得額外憑證。
-xcertform DER|PEM|P12: 額外憑證的輸入格式。此選項無效，僅保留以維持向下相容性。
-xkeyform DER|PEM|P12: 額外金鑰的輸入格式。此選項無效，僅保留以維持向下相容性。

憑證擴充

-purpose 等選項會導致檢查憑證擴充，此擴充會決定目標憑證和中間 CA 憑證可做何用途。

基本限制

basicConstraints 擴充的 CA 旗標用於判斷憑證是否可用作 CA。如果 CA 旗標為 true，則為 CA，如果 CA 旗標為 false，則不是 CA。所有 CA 的 CA 旗標都應設定為 true。

如果 basicConstraints 擴充不存在，包括它是 X.509v1 憑證的情況，則憑證會被視為「可能的 CA」，而其他擴充會根據憑證的預期用途進行檢查。目前支援將沒有 basicConstraints 的憑證視為 CA，但這可能會在未來變更。

金鑰用途

如果 keyUsage 擴充存在，則會對憑證用途進行額外限制。如果 keyUsage 擴充存在，CA 憑證必須設定 keyCertSign 位元。

延伸金鑰用途

extKeyUsage (EKU) 擴充對憑證用途施加額外的限制。如果此擴充存在（無論是否為關鍵），金鑰只能用於指定的用途。

以下是各項檢查的完整說明。上述關於 basicConstraints、keyUsage 和 X.509v1 憑證的說明適用於所有 CA 憑證。

SSL 客戶端: 延伸金鑰用途擴充必須不存在或包含「網頁客戶端驗證」OID。keyUsage 擴充必須不存在或必須設定 digitalSignature 位元。Netscape 憑證類型必須不存在或必須設定 SSL 客戶端位元。
SSL 客戶端 CA: 延伸金鑰用途擴充必須不存在或包含「網頁客戶端驗證」OID。Netscape 憑證類型必須不存在或必須設定 SSL CA 位元。如果 basicConstraints 擴充不存在，這會用作解決方法。
SSL 伺服器: 延伸金鑰使用擴充功能必須不存在或包含「網頁伺服器驗證」和/或其中一個 SGC OID。keyUsage 擴充功能必須不存在或必須設定 digitalSignature、keyEncipherment 或同時設定這兩個位元。Netscape 憑證類型必須不存在或設定 SSL 伺服器位元。
SSL 伺服器 CA: 延伸金鑰使用擴充功能必須不存在或包含「網頁伺服器驗證」和/或其中一個 SGC OID。Netscape 憑證類型必須不存在或必須設定 SSL CA 位元。如果 basicConstraints 擴充功能不存在，這將用作解決方法。
Netscape SSL 伺服器: 如果 keyUsage 擴充功能存在，Netscape SSL 用戶端才能連線到 SSL 伺服器，則必須設定 keyEncipherment 位元。這並不總是有效的，因為有些加密組使用金鑰進行數位簽章。否則，它與一般的 SSL 伺服器相同。
常見的 S/MIME 用戶端測試: 延伸金鑰使用擴充功能必須不存在或包含「電子郵件保護」OID。Netscape 憑證類型必須不存在或應設定 S/MIME 位元。如果 S/MIME 位元未設定在 Netscape 憑證類型中，則 SSL 用戶端位元可作為替代，但會顯示警告。這是因為有些 Verisign 憑證未設定 S/MIME 位元。
S/MIME 簽署: 除了常見的 S/MIME 用戶端測試外，如果 keyUsage 擴充功能存在，則必須設定 digitalSignature 位元或 nonRepudiation 位元。
S/MIME 加密: 除了常見的 S/MIME 測試外，如果 keyUsage 擴充功能存在，則必須設定 keyEncipherment 位元。
S/MIME CA: 延伸金鑰使用擴充功能必須不存在或包含「電子郵件保護」OID。Netscape 憑證類型必須不存在或必須設定 S/MIME CA 位元。如果 basicConstraints 擴充功能不存在，這將用作解決方法。
CRL 簽署: keyUsage 擴充功能必須不存在或必須設定 CRL 簽署位元。
CRL 簽署 CA: 適用正常的 CA 測試。但在此情況下，必須存在 basicConstraints 擴充功能。

BUG

發行者檢查仍受 X509_LOOKUP API 中的限制影響。這其中一項後果是，具有相符主旨名稱的可信憑證必須出現在檔案中（如 -CAfile 選項所指定）、目錄中（如 -CApath 所指定）或儲存區中（如 -CAstore 所指定）。如果有多個此類相符項，可能位於多個位置，則只會辨識第一個相符項（依據所述位置順序）。

另請參閱

X509_verify_cert(3)、openssl-verify(1)、openssl-ocsp(1)、openssl-ts(1)、openssl-s_client(1)、openssl-s_server(1)、openssl-smime(1)、openssl-cmp(1)、openssl-cms(1)

歷程

OpenSSL 3.0 已擴充 -x509_strict 啟用的檢查。

版權

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