OpenSSL

openssl-req

名稱

openssl-req - PKCS#10 憑證要求和憑證產生指令

語法

openssl req [-help] [-inform DER|PEM] [-outform DER|PEM] [-in filename] [-passin arg] [-out filename] [-passout arg] [-text] [-pubkey] [-noout] [-verify] [-modulus] [-new] [-newkey arg] [-pkeyopt opt:value] [-noenc] [-nodes] [-key filename|uri] [-keyform DER|PEM|P12|ENGINE] [-keyout filename] [-keygen_engine id] [-digest] [-config filename] [-section name] [-x509] [-x509v1] [-CA filename|uri] [-CAkey filename|uri] [-days n] [-set_serial n] [-newhdr] [-copy_extensions arg] [-extensions section] [-reqexts section] [-addext ext] [-precert] [-utf8] [-reqopt] [-subject] [-subj arg] [-multivalue-rdn] [-sigopt nm:v] [-vfyopt nm:v] [-batch] [-verbose] [-quiet] [-nameopt option] [-rand files] [-writerand file] [-engine id] [-provider name] [-provider-path path] [-propquery propq]

說明

此指令主要建立和處理 PKCS#10 格式的憑證要求 (CSR)。它還可以建立自簽憑證，例如用作根 CA。

選項

-help

列印使用說明。

-inform DER|PEM

要使用的 CSR 輸入檔案格式；預設會先嘗試 PEM。有關詳細資料，請參閱 openssl-format-options(1)。

-outform DER|PEM

輸出格式；預設未指定。有關詳細資料，請參閱 openssl-format-options(1)。

資料為 PKCS#10 物件。

-in filename

指定用於讀取要求的輸入檔名。除非指定 -x509 或 -CA，否則預設為標準輸入。只有在未指定建立選項 (-new 或 -newkey 或 -precert) 時才會讀取要求。

-sigopt nm:v

在簽署作業期間傳遞選項給簽章演算法。這些選項的名稱和值取決於演算法。

-vfyopt nm:v

在驗證作業期間傳遞選項給簽章演算法。這些選項的名稱和值取決於演算法。

-passin arg

私密金鑰和憑證輸入的密碼來源。有關 arg 格式的詳細資訊，請參閱 openssl-passphrase-options(1)。

-passout arg

輸出檔案的密碼來源。有關 arg 格式的詳細資訊，請參閱 openssl-passphrase-options(1)。

-out filename

這會指定要寫入的輸出檔名或預設的標準輸出。

-text

以文字形式列印憑證要求。

-subject

列印憑證要求主旨 (或如果使用 -x509，則列印憑證主旨)。

-pubkey

列印公開金鑰。

-noout

此選項會防止輸出憑證要求的編碼版本。

-modulus

列印要求中所含公開金鑰的模數值。

-verify

驗證要求上的自簽章。如果驗證失敗，程式會立即結束，也就是說會略過後續的選項處理 (例如 -text)。

-new

此選項會產生新的憑證要求。它會提示使用者輸入相關欄位值。實際提示的欄位及其最大和最小大小會在組態檔和任何要求的擴充功能中指定。

如果未提供 -key 選項，它會使用組態檔中指定的資訊或使用 -newkey 和 -pkeyopt 選項提供的資訊產生新的私密金鑰，否則預設會產生長度為 2048 位元的 RSA 金鑰。

-newkey arg

此選項用於產生新的私密金鑰，除非已提供 -key。它會隨後使用，就像使用 -key 選項提供的一樣。

此選項暗示 -new 旗標，以產生新的憑證要求或新的憑證 (如果使用 -x509)。

引數採用下列幾種形式之一。

[rsa:]nbits 會產生大小為 nbits 的 RSA 金鑰。如果省略 nbits，也就是說指定 -newkey rsa，如果存在，則會使用組態檔中使用 default_bits 選項指定的預設金鑰大小，否則為 2048。

所有其他演算法都支援 -newkey algname:file 形式，其中 file 是使用 openssl genpkey -genparam 或具有適當演算法的金鑰的 X.509 憑證建立的演算法參數檔案。

param:file 會使用參數檔案或憑證 file 產生金鑰，演算法由參數決定。

演算法名稱[:檔案] 使用指定的演算法 演算法名稱 產生金鑰。如果提供參數檔案 檔案，則會使用其中指定的參數，其中演算法參數必須與 演算法名稱 相符。如果未提供演算法參數，則應透過 -pkeyopt 選項指定任何必要的參數。

dsa:檔名 使用 檔名 檔案中的參數產生 DSA 金鑰。ec:檔名 產生 EC 金鑰（可用於 ECDSA 或 ECDH 演算法），gost2001:檔名 產生 GOST R 34.10-2001 金鑰（需要在組態檔中設定 gost 引擎）。如果只指定 gost2001，則應透過 -pkeyopt paramset:X 指定參數組。

-pkeyopt 選項:值

將公開金鑰演算法選項 選項 設定為 值。支援的精確選項組取決於所使用的公開金鑰演算法及其實作。請參閱 "openssl-genpkey(1) 中的 KEY GENERATION OPTIONS" 以取得更多詳細資料。

-key 檔名|uri

此選項提供用於簽署新憑證或憑證要求的私密金鑰。除非提供 -in，否則對應的公開金鑰會放置在新憑證或憑證要求中，產生自簽署。

對於憑證簽署，此選項會被 -CA 選項覆寫。

此選項也接受 PEM 格式檔案的 PKCS#8 格式私密金鑰。

-keyform DER|PEM|P12|ENGINE

私密金鑰的格式；預設未指定。請參閱 openssl-format-options(1) 以取得詳細資料。

-keyout 檔名

這會提供檔名以寫入任何已新建立或從 -key 讀取的私密金鑰。如果未提供 -keyout 選項或 -key 選項，則會使用組態檔中使用 default_keyfile 選項指定的檔名（如果存在）。因此，如果您要寫入私密金鑰且提供了 -key 選項，您應明確提供 -keyout 選項。如果產生新的金鑰且未指定檔名，則會將金鑰寫入標準輸出。

-noenc

如果指定此選項，則在建立私密金鑰時不會對其加密。

-nodes

此選項已於 OpenSSL 3.0 中棄用；請改用 -noenc。

-摘要

這會指定用於簽署要求的訊息摘要。可以使用 OpenSSL dgst 指令支援的任何摘要。這會覆寫組態檔中指定的摘要演算法。

某些公開金鑰演算法可能會覆寫此選擇。例如，DSA 簽章總是使用 SHA1，GOST R 34.10 簽章總是使用 GOST R 34.11-94（-md_gost94），Ed25519 和 Ed448 從不使用任何摘要。

-config 檔名

這允許指定替代組態檔。選用；如需預設值的說明，請參閱 "openssl(1) 中的 COMMAND SUMMARY"。

-section 名稱

指定要使用的區段名稱；預設為 req。

-subj arg

設定新要求的主體名稱，或在處理憑證要求時取代主體名稱。

arg 必須以 /type0=value0/type1=value1/type2=... 格式化。特殊字元可以用 \ (反斜線) 進行跳脫，空白會保留。允許空值，但對應的類型不會包含在要求中。只給一個 / 會導致 RDN 的序列為空 (NULL-DN)。多值 RDN 可以透過在指定集合成員的屬性值斷言 (AVA) 之間放置 + 字元，而不是 / 來形成。範例

/DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe

-multivalue-rdn

此選項已棄用，且不具任何作用。

-x509

此選項會輸出憑證，而不是憑證要求。這通常用於產生測試憑證。-CA 選項暗示了此選項。

如果未提供 -in，此選項暗示 -new 標記。

如果使用 -in 選項指定現有要求，則會將其轉換為憑證；否則會從頭建立要求。

除非使用 -set_serial 選項指定，否則會使用一個隨機大數字作為序號。

除非使用 -copy_extensions 選項，否則不會從任何提供的要求輸入檔案複製 X.509 延伸模組。

可以透過設定檔指定要新增的 X.509 延伸模組，可能使用 -config 和 -extensions 選項，和/或使用 -addext 選項。

除非提供 -x509v1，否則產生的憑證會採用 X.509 版本 3。除非另有指定，否則會包含金鑰識別延伸模組，如 x509v3_config(5) 所述。

-x509v1

要求產生 X.509 版本 1 的憑證。暗示 -x509。如果提供 X.509 延伸模組，則無論如何都會設定 X.509 版本 3。

-CA 檔名|uri

指定要使用來簽署新憑證的「CA」憑證，並暗示使用 -x509。如果存在，則會以「微型 CA」的方式執行，如下所示：將「CA」憑證的主體名稱置於新憑證的發行者名稱中，然後使用下面指定的「CA」金鑰簽署。

-CAkey 檔名|uri

設定要使用來簽署憑證的「CA」私人金鑰。私人金鑰必須與使用 -CA 提供的憑證的公開金鑰相符。如果未提供此選項，則金鑰必須存在於 -CA 輸入中。

-days n

當 -x509 使用中，這會指定認證憑證的天數，否則會被忽略。n 應為正整數。預設為 30 天。

-set_serial n

輸出自簽憑證時要使用的序號。如果在前面加上 0x，這可以指定為十進位值或十六進位值。如果未提供，將會使用一個隨機大數字。

-copy_extensions arg

當 -x509 使用中，決定憑證要求中的 X.509 延伸功能應如何處理。如果 arg 為 none 或此選項不存在，則會忽略延伸功能。如果 arg 為 copy 或 copyall，則要求中的所有延伸功能都會複製到憑證中。

此選項的主要用途是允許憑證要求提供某些延伸功能的值，例如 subjectAltName。

-extensions section, -reqexts section

可用於覆寫組態檔區段的名稱，其中 X.509 延伸功能包含在憑證（當 -x509 使用中）或憑證要求中。這允許在同一個組態檔中使用幾個不同的區段，以指定各種用途的要求。

-addext ext

將特定延伸功能新增到憑證（如果 -x509 使用中）或憑證要求。參數必須具有 key=value 對的形式，就像它出現在組態檔中一樣。

此選項可以提供多次。

-precert

會將一個有害延伸功能新增到憑證中，使其成為「預先憑證」（請參閱 RFC6962）。這可以提交到憑證透明度記錄，以取得簽署的憑證時間戳記 (SCT)。然後，這些 SCT 可以作為延伸功能嵌入到預先憑證中，然後移除有害部分並簽署憑證。

這暗示 -new 旗標。

-utf8

此選項會導致欄位值被解釋為 UTF8 字串，預設會將它們解釋為 ASCII。這表示欄位值，無論是從終端機提示還是從組態檔取得，都必須是有效的 UTF8 字串。

-reqopt option

自訂與 -text 一起使用的列印格式。option 參數可以是單一選項或多個選項，以逗號分隔。

請參閱 openssl-x509(1) 指令中的 -certopt 參數說明。

-newhdr

在輸出的要求中，將字詞 NEW 加入到 PEM 檔案的標頭和尾端列。某些軟體（Netscape 憑證伺服器）和某些 CA 需要此項。

-batch

非互動模式。

-verbose

列印執行中作業的額外詳細資料。

-quiet

列印執行中作業較少的詳細資料，這在批次指令碼或管線中可能很方便（特別是會抑制金鑰產生中的「進度點」）。

-keygen_engine id

指定一個引擎（透過其唯一的 id 字串），將用於金鑰產生作業。

-nameopt option

這會指定主旨或發行者名稱的顯示方式。有關詳細資料，請參閱 openssl-namedisplay-options(1)。

-rand files, -writerand file

有關詳細資料，請參閱 openssl(1) 中的「隨機狀態選項」。

-engine id

請參閱 openssl(1) 中的「引擎選項」。此選項已不建議使用。

-provider name

-provider-path path

-propquery propq

請參閱 openssl(1) 中的「提供者選項」、provider(7) 和 property(7)。

組態檔格式

組態選項會指定在組態檔的 req 區段中。可以透過使用 -section 選項來指定替代名稱。與所有組態檔一樣，如果在特定區段中未指定值，也會搜尋最初未命名或 default 區段。

可用的選項如下詳細說明。

input_password, output_password

輸入私密金鑰檔案（如果存在）和輸出私密金鑰檔案（如果將建立一個檔案）的密碼。命令列選項 passin 和 passout 會覆寫組態檔值。

default_bits

指定預設金鑰大小（以位元為單位）。

此選項會與 -new 選項結合使用，以產生新的金鑰。它可以透過在 -newkey 選項中指定明確的金鑰大小來覆寫。最小的可接受金鑰大小為 512 位元。如果未指定金鑰大小，則會使用 2048 位元。

default_keyfile

這是用來寫入私密金鑰的預設檔名。如果未指定，金鑰會寫入標準輸出。這可以透過 -keyout 選項來覆寫。

oid_file

這會指定一個包含其他物件識別碼的檔案。檔案的每一行都應包含物件識別碼的數字形式，後接空白、簡短名稱、後接空白，最後是長名稱。

oid_section

這會指定組態檔中包含額外物件識別碼的區段。每一行都應包含物件識別碼的簡短名稱，後接=和數字形式。使用此選項時，簡短名稱和長名稱相同。

RANDFILE

在啟動時，指定的檔案會載入亂數產生器，而在結束時，會寫入 256 位元組到該檔案。它用於私密金鑰產生。

encrypt_key

如果這設定為否，則如果產生私密金鑰，則不會加密。這等同於-noenc命令列選項。為了相容性，encrypt_rsa_key是等效選項。

default_md

此選項指定要使用的摘要演算法。任何由 OpenSSL dgst 命令支援的摘要都可以使用。此選項可以在命令列中覆寫。某些簽署演算法（例如 Ed25519 和 Ed448）會忽略已設定的任何摘要。

string_mask

此選項會遮罩在特定欄位中使用特定字串類型的功能。大多數使用者不需要變更此選項。它可以設定為下列數個值

utf8only - 僅使用 UTF8 字串（這是預設值）

pkix - 任何字串類型，T61 字串除外

nombstr - 任何字串類型，BMP 字串和 UTF8 字串除外

default - 任何類型的字串

請注意，utf8only是 RFC2459 中 2003 年後的 PKIX 建議，也是預設的string_mask；default不是預設選項。nombstr值是針對某些在變數大小的 BMP 字串和 UTF8 字串方面有問題的軟體的解決方法。

req_extensions

這會指定組態檔區段，其中包含要新增至憑證要求的延伸清單。它可以由-reqexts命令列開關覆寫。請參閱x509v3_config(5)手冊頁面，以取得延伸區段格式的詳細資料。

x509_extensions

這會指定在使用 -x509 時，包含要新增至憑證的擴充功能清單的組態檔區段。它可以被 -extensions 命令列開關覆寫。

prompt

如果設定為 no，這會停用憑證欄位的提示，並直接從組態檔取得值。它也會變更 distinguished_name 和 attributes 區段的預期格式。

utf8

如果設定為 yes，則欄位值會被解釋為 UTF8 字串，預設會被解釋為 ASCII。這表示欄位值（無論是從終端機提示或從組態檔取得）都必須是有效的 UTF8 字串。

attributes

這會指定包含任何要求屬性的區段：其格式與 distinguished_name 相同。通常這些可能會包含 challengePassword 或 unstructuredName 類型。它們目前會被 OpenSSL 的要求簽署公用程式忽略，但有些 CA 可能需要它們。

distinguished_name

這會指定在產生憑證或憑證要求時，要提示的識別名稱欄位所包含的區段。格式會在下一節中說明。

識別名稱和屬性區段格式

識別名稱和屬性區段有兩種不同的格式。如果 prompt 選項設定為 no，則這些區段只會包含欄位名稱和值：例如

CN=My Name
OU=My Organization
emailAddress=someone@somewhere.org

這允許外部程式（例如基於 GUI 的程式）產生包含所有欄位名稱和值的範本檔，並將其傳遞給此命令。此類組態檔的範例包含在 範例 區段中。

或者，如果 prompt 選項不存在或未設定為 no，則檔案會包含欄位提示資訊。它包含以下格式的列：

fieldName="prompt"
fieldName_default="default field value"
fieldName_min= 2
fieldName_max= 4

"fieldName" 是正在使用的欄位名稱，例如 commonName (或 CN)。"prompt" 字串用於要求使用者輸入相關詳細資料。如果使用者未輸入任何內容，則會使用預設值；如果沒有預設值，則會略過該欄位。如果使用者只輸入 '.' 字元，則即使有預設值，欄位仍可以被略過。

輸入的字元數必須介於 fieldName_min 和 fieldName_max 限制之間：可能會根據正在使用的欄位有額外的限制（例如 countryName 永遠只能有兩個字元長，且必須符合 PrintableString）。

有些欄位（例如 organizationName）可以在 DN 中使用多次。這會造成一個問題，因為組態檔案不會辨識兩次出現的相同名稱。為避免這個問題，如果 fieldName 包含一些字元，後面接著一個句點，這些字元將會被忽略。因此，例如，可以透過呼叫「1.organizationName」來輸入第二個 organizationName。

實際允許的欄位名稱是任何物件識別碼的簡短或長名稱。這些會編譯到 OpenSSL 中，並包含常見值，例如 commonName、countryName、localityName、organizationName、organizationalUnitName、stateOrProvinceName。此外，emailAddress 也包含在內，以及 name、surname、givenName、initials 和 dnQualifier。

可以在組態檔案中使用 oid_file 或 oid_section 選項定義其他物件識別碼。任何其他欄位將會被視為 DirectoryString。

範例

檢查和驗證憑證要求

openssl req -in req.pem -text -verify -noout

建立私密金鑰，然後從中產生憑證要求

openssl genrsa -out key.pem 2048
openssl req -new -key key.pem -out req.pem

相同，但只使用 req

openssl req -newkey rsa:2048 -keyout key.pem -out req.pem

產生自簽署根憑證

openssl req -x509 -newkey rsa:2048 -keyout key.pem -out req.pem

建立 SM2 私密金鑰，然後從中產生憑證要求

openssl ecparam -genkey -name SM2 -out sm2.key
openssl req -new -key sm2.key -out sm2.csr -sm3 -sigopt "distid:1234567812345678"

檢查和驗證 SM2 憑證要求

openssl req -verify -in sm2.csr -sm3 -vfyopt "distid:1234567812345678"

由 oid_file 選項指向的檔案範例

1.2.3.4        shortName       A longer Name
1.2.3.6        otherName       Other longer Name

由 oid_section 指向的區段範例，利用變數擴充

testoid1=1.2.3.5
testoid2=${testoid1}.6

提示輸入欄位值的範例組態檔案

[ req ]
default_bits           = 2048
default_keyfile        = privkey.pem
distinguished_name     = req_distinguished_name
attributes             = req_attributes
req_extensions         = v3_ca

dirstring_type = nobmp

[ req_distinguished_name ]
countryName                    = Country Name (2 letter code)
countryName_default            = AU
countryName_min                = 2
countryName_max                = 2

localityName                   = Locality Name (eg, city)

organizationalUnitName         = Organizational Unit Name (eg, section)

commonName                     = Common Name (eg, YOUR name)
commonName_max                 = 64

emailAddress                   = Email Address
emailAddress_max               = 40

[ req_attributes ]
challengePassword              = A challenge password
challengePassword_min          = 4
challengePassword_max          = 20

[ v3_ca ]

subjectKeyIdentifier=hash
authorityKeyIdentifier=keyid:always,issuer:always
basicConstraints = critical, CA:true

包含所有欄位值的範例組態

[ req ]
default_bits           = 2048
default_keyfile        = keyfile.pem
distinguished_name     = req_distinguished_name
attributes             = req_attributes
prompt                 = no
output_password        = mypass

[ req_distinguished_name ]
C                      = GB
ST                     = Test State or Province
L                      = Test Locality
O                      = Organization Name
OU                     = Organizational Unit Name
CN                     = Common Name
emailAddress           = test@email.address

[ req_attributes ]
challengePassword              = A challenge password

在命令列中提供最常見屬性（主旨和延伸）的範例

openssl req -new -subj "/C=GB/CN=foo" \
                 -addext "subjectAltName = DNS:foo.co.uk" \
                 -addext "certificatePolicies = 1.2.3.4" \
                 -newkey rsa:2048 -keyout key.pem -out req.pem

附註

由 Xenroll 使用 MSIE 產生的憑證要求會加入延伸。它包含 keyUsage 延伸，用來決定金鑰類型（僅簽章或一般用途），以及腳本在 extendedKeyUsage 延伸中輸入的任何其他 OID。

診斷

下列訊息經常被詢問

Using configuration from /some/path/openssl.cnf
Unable to load config info

一段時間後，接著出現

unable to find 'distinguished_name' in config
problems making Certificate Request

第一個錯誤訊息是線索：找不到組態檔案！某些作業（例如檢查憑證要求）不需要組態檔案，因此不會強制使用。然而，產生憑證或要求確實需要組態檔案。這可以視為一個錯誤。

另一個令人困惑的訊息是

Attributes:
    a0:00

當沒有屬性且要求包含正確的空 SET OF 結構（其 DER 編碼為 0xa0 0x00）時，會顯示此訊息。如果您只看到

Attributes:

則表示遺失 SET OF，且編碼在技術上無效（但可以容忍）。請參閱命令列選項 -asn1-kludge 的說明以取得更多資訊。

錯誤

OpenSSL 處理 T61Strings（又稱 TeletexStrings）的方式有問題：它實際上將它們視為 ISO-8859-1（Latin 1），Netscape 和 MSIE 也有類似的行為。如果您需要無法在 PrintableStrings 中取得的字元，且您不想要或無法使用 BMPStrings，這可能會造成問題。

由於處理 T61String，在 OpenSSL 中表示重音字元的唯一正確方法是使用 BMPString：很不幸的是，Netscape 目前會中斷這些字元。如果您必須在 Netscape 和 MSIE 中使用重音字元，則您目前需要使用無效的 T61String 形式。

目前的提示並不友善。它不允許您確認您剛剛輸入的內容。認證要求中的延伸等其他項目在組態檔中以靜態方式定義。其中一些項目：例如 subjectAltName 中的電子郵件地址，應該由使用者輸入。

另請參閱

openssl(1)、openssl-x509(1)、openssl-ca(1)、openssl-genrsa(1)、openssl-gendsa(1)、config(5)、x509v3_config(5)

歷史記錄

-section 選項已新增至 OpenSSL 3.0.0。

-multivalue-rdn 選項已在 OpenSSL 3.0.0 中過時，且無效。

-engine 選項已在 OpenSSL 3.0 中棄用。<-nodes> 選項也已在 OpenSSL 3.0 中棄用；請改用 -noenc。

-reqexts 選項已在 OpenSSL 3.2 中成為 -extensions 的別名。

自 OpenSSL 3.2 起，除非提供 -x509v1，否則產生的憑證會採用 X.509 版本 3，且預設會包含金鑰識別碼延伸。

自 OpenSSL 3.3 起，-verify 選項會在失敗時退出，且狀態為 1。

版權

版權所有 2000-2024 OpenSSL 專案作者。保留所有權利。

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