openssl-pkeyutl
名稱
openssl-pkeyutl - 公開金鑰演算法指令
語法
openssl pkeyutl [-help] [-in 檔案] [-rawin] [-digest 演算法] [-out 檔案] [-sigfile 檔案] [-inkey 檔名|uri] [-keyform DER|PEM|P12|ENGINE] [-passin 參數] [-peerkey 檔案] [-peerform DER|PEM|P12|ENGINE] [-pubin] [-certin] [-rev] [-sign] [-verify] [-verifyrecover] [-encrypt] [-decrypt] [-derive] [-kdf 演算法] [-kdflen 長度] [-pkeyopt opt:值] [-pkeyopt_passin opt[:passarg]] [-hexdump] [-asn1parse] [-engine id] [-engine_impl] [-rand 檔案] [-writerand 檔案] [-provider 名稱] [-provider-path 路徑] [-propquery propq] [-config 設定檔]
說明
此指令可用於執行低階公開金鑰操作，使用任何支援的演算法。
選項
- -help
-
列印使用說明訊息。
- -in 檔名
-
此選項指定要從中讀取資料的輸入檔名，或如果未指定此選項，則為標準輸入。
- -rawin
-
這表示輸入資料為未經任何訊息摘要演算法雜湊的原始資料。使用者可以使用 -digest 選項指定摘要演算法。此選項只能與 -sign 和 -verify 搭配使用，且必須與 Ed25519 和 Ed448 演算法搭配使用。
- -digest 演算法
-
此選項指定摘要演算法，用於在使用輸入金鑰簽署或驗證輸入資料之前對其進行雜湊。如果簽章演算法不需要此選項，則可以省略此選項 (例如，EdDSA)。如果省略此選項但簽章演算法需要此選項，則會使用預設值。對於 RSA、DSA 和 ECDSA 等簽章演算法，SHA-256 將會是預設摘要演算法。對於 SM2，則會是 SM3。如果存在此選項，則還必須指定 -rawin 選項。
- -out 檔名
-
指定要寫入的輸出檔名，或預設為標準輸出。
- -sigfile 檔案
-
簽章檔案，僅限於 -verify 操作
- -inkey 檔名|uri
-
輸入金鑰，預設應為私人金鑰。
- -keyform DER|PEM|P12|ENGINE
-
金鑰格式；預設未指定。有關詳細資訊，請參閱 openssl-format-options(1)。
- -passin arg
-
輸入金鑰密碼來源。有關 arg 格式的詳細資訊，請參閱 openssl-passphrase-options(1)。
- -peerkey file
-
對等金鑰檔案，用於金鑰衍生（協定）作業。
- -peerform DER|PEM|P12|ENGINE
-
對等金鑰格式；預設未指定。有關詳細資訊，請參閱 openssl-format-options(1)。
- -pubin
-
預設情況下，會從金鑰輸入中讀取私人金鑰。使用此選項，會讀取公開金鑰。如果輸入不包含公開金鑰，但包含私人金鑰，則會使用其公開部分。
- -certin
-
輸入是包含公開金鑰的憑證。
- -rev
-
反轉輸入緩衝區的順序。這對於某些以小端序格式表示緩衝區的函式庫（例如 CryptoAPI）很有用。
- -sign
-
簽署輸入資料（必須是雜湊），並輸出已簽署的結果。這需要私人金鑰。
- -verify
-
驗證輸入資料（必須是雜湊）與簽章檔案，並指出驗證是否成功或失敗。
- -verifyrecover
-
驗證輸入資料（必須是雜湊），並輸出已復原的資料。
- -encrypt
-
使用公開金鑰加密輸入資料。
- -decrypt
-
使用私人金鑰解密輸入資料。
- -derive
-
使用對等金鑰衍生共用機密。
- -kdf algorithm
-
使用金鑰衍生函數 algorithm。目前支援的演算法為 TLS1-PRF 和 HKDF。注意：通常必須設定額外參數和 KDF 輸出長度才能執行此作業。有關每個演算法支援的字串參數，請參閱 EVP_PKEY_CTX_set_hkdf_md(3) 和 EVP_PKEY_CTX_set_tls1_prf_md(3)。
- -kdflen length
-
設定 KDF 的輸出長度。
- -pkeyopt opt:value
-
指定為 opt:value 的公開金鑰選項。有關詳細資訊，請參閱下列注意事項。
- -pkeyopt_passin opt[:passarg]
-
允許從 stdin 或密碼來源讀取公開金鑰選項 opt。如果只指定 opt，系統會提示使用者在 stdin 中輸入密碼。或者，可以指定 openssl-passphrase-options(1) 支援的任何值 passarg。
- -hexdump
-
將輸出資料以十六進位格式傾印。
- -asn1parse
-
分析 ASN.1 輸出資料，當 ASN1 結構已簽署時，這與 -verifyrecover 選項結合使用時很有用。
- -engine id
-
請參閱 openssl(1) 中的「引擎選項」。此選項已棄用。
- -engine_impl
-
與 -engine 選項一起使用時，指定也使用引擎 id 進行加密操作。
- -rand files, -writerand file
-
有關詳細資訊，請參閱 openssl(1) 中的「隨機狀態選項」。
- -provider name
- -provider-path path
- -propquery propq
- -config configfile
-
請參閱 openssl(1) 中的「組態選項」。
注意事項
支援的操作和選項會根據金鑰演算法及其實作而有所不同。OpenSSL 操作和選項如下所示。
除非另有說明，否則所有演算法都支援 digest:alg 選項，它指定用於簽署、驗證和驗證回復操作的摘要。值 alg 應表示 EVP_get_digestbyname() 函式中使用的摘要名稱，例如 sha1。此值不用於對輸入資料進行雜湊。它（由某些演算法）用於檢查傳入資料的長度，以及建立組成簽章的結構（例如 RSASSA PKCS#1 v1.5 簽章中的 DigestInfo）。
此指令不會對輸入資料進行雜湊（除非使用 -rawin），而是會直接將資料用作簽章演算法的輸入。根據金鑰類型、簽章類型和填充模式，輸入資料可接受的最大長度會有所不同。使用 RSA 時，已簽署的資料長度不能超過金鑰模數。使用 ECDSA 和 DSA 時，資料長度不能超過欄位大小，否則會在不提示的情況下將資料截斷為欄位大小。在任何情況下，輸入大小都不能大於支援的最大摘要大小。
換句話說，如果摘要值為 sha1，則輸入應為 SHA-1 雜湊函數輸出的 20 位元組長度二進位編碼。
RSA 演算法
RSA 演算法通常支援加密、解密、簽署、驗證和驗證復原作業。但是，某些填充模式僅支援這些作業的子集。支援下列其他 pkeyopt 值
- rsa_padding_mode:mode
-
這會設定 RSA 填充模式。mode 可接受的值為 pkcs1（用於 PKCS#1 填充）、none（不填充）、oaep（用於 OAEP 模式）、x931（用於 X9.31 模式）和 pss（用於 PSS）。
在 PKCS#1 填充中，如果未設定訊息摘要，則會直接簽署或驗證提供的資料，而不是使用 DigestInfo 結構。如果設定摘要，則會使用 DigestInfo 結構，且其長度必須與摘要類型相符。
請注意，對於 pkcs1 填充，為了防範 Bleichenbacher 攻擊，在填充檢查失敗時，解密不會失敗。使用 none 和手動檢查已解密訊息，以驗證已解密值是否具有正確的 PKCS#1 v1.5 填充。
對於 oaep 模式，僅支援加密和解密。
對於 x931，如果設定摘要類型，則會使用該類型來格式化區塊資料，否則會使用第一個位元組來指定 X9.31 摘要 ID。可以在此模式中執行簽署、驗證和驗證復原。
對於 pss 模式，僅支援簽署和驗證，且必須指定摘要類型。
- rsa_pss_saltlen:len
-
僅針對 pss 模式，此選項會指定鹽長度。支援三個特殊值：digest 會將鹽長度設定為摘要長度，max 會將鹽長度設定為允許的最大值。驗證時，auto 會根據 PSS 區塊結構自動決定鹽長度。
- rsa_mgf1_md:摘要
-
對於 PSS 和 OAEP 填充，設定 MGF1 摘要。如果在 PSS 模式中未明確設定 MGF1 摘要，則會使用簽署摘要。
- rsa_oaep_md:摘要
-
設定用於 OAEP 雜湊函數的摘要。如果未明確設定，則會使用 SHA1。
- rsa_pkcs1_implicit_rejection:旗標
-
停用 (設定為 0) 或啟用 (設定為 1) PKCS#1 v1.5 解密時使用隱含拒絕。啟用時 (預設)，為了防止 Bleichenbacher 攻擊，函式庫會產生一個確定性的隨機明文，並在填充檢查失敗時傳回給呼叫方。停用時，呼叫方有責任以不側信道的方式處理傳回的錯誤。
RSA-PSS 演算法
RSA-PSS 演算法是 RSA 演算法的受限版本，僅支援使用 PSS 填充的簽署和驗證作業。支援下列其他 -pkeyopt 值
- rsa_padding_mode:模式, rsa_pss_saltlen:長度, rsa_mgf1_md:摘要
-
這些與 RSA 演算法具有相同的意義，但有一些額外的限制。填充模式只能設定為 pss，這是預設值。
如果金鑰有參數限制，則摘要、MGF1 摘要和鹽長度會設定為參數中指定的值。摘要和 MG 無法變更，而鹽長度無法設定為小於最小限制的值。
DSA 演算法
DSA 演算法僅支援簽署和驗證作業。目前沒有其他 -pkeyopt 選項，只有 摘要。預設假設為 SHA1 摘要。
DH 演算法
DH 演算法僅支援衍生作業，沒有其他 -pkeyopt 選項。
EC 演算法
EC 演算法支援簽署、驗證和衍生作業。簽署和驗證作業使用 ECDSA，而衍生作業使用 ECDH。-pkeyopt 摘要 選項預設假設為 SHA1。
X25519 和 X448 演算法
X25519 和 X448 演算法僅支援金鑰衍生。目前沒有其他選項。
ED25519 和 ED448 演算法
這些演算法僅支援簽署和驗證。OpenSSL 僅實作這些演算法的「純粹」變體，因此原始資料可以傳遞給它們，而無需先對它們進行雜湊。選項 -rawin 必須與這些演算法一起使用，且未指定 -digest。此外，OpenSSL 僅支援這些演算法的「一次性」操作。這表示在處理要簽署/驗證的整個檔案之前，必須將其讀入記憶體。應避免簽署或驗證非常大的檔案。此外，必須知道檔案的大小才能執行此操作。如果無法確定檔案的大小（例如，如果輸入是 stdin），則簽署或驗證操作將會失敗。
SM2
SM2 演算法支援簽署、驗證、加密和解密操作。對於簽署和驗證操作，SM2 需要傳入一個區別 ID 字串。支援下列 -pkeyopt 值
- distid:字串
-
這會設定在 SM2 簽署或驗證操作中使用的 ID 字串。在驗證 SM2 簽章時，ID 字串必須與簽署資料時使用的字串相同。否則，驗證將會失敗。
- hexdistid:十六進位字串
-
這會設定在 SM2 簽署或驗證操作中使用的 ID 字串。在驗證 SM2 簽章時，ID 字串必須與簽署資料時使用的字串相同。否則，驗證將會失敗。此選項提供的 ID 字串應為有效的十六進位值。
範例
使用私鑰簽署一些資料
openssl pkeyutl -sign -in file -inkey key.pem -out sig復原已簽署的資料（例如，如果使用 RSA 金鑰）
openssl pkeyutl -verifyrecover -in sig -inkey key.pem驗證簽章（例如，DSA 金鑰）
openssl pkeyutl -verify -in file -sigfile sig -inkey key.pem使用訊息摘要值簽署資料（目前僅對 RSA 有效）
openssl pkeyutl -sign -in file -inkey key.pem -out sig -pkeyopt digest:sha256衍生共用密碼值
openssl pkeyutl -derive -inkey key.pem -peerkey pubkey.pem -out secret使用雜湊 SHA256 和由單一位元組 0xFF 組成的共用密碼和種子，十六進位傾印 48 位元組的 TLS1 PRF
openssl pkeyutl -kdf TLS1-PRF -kdflen 48 -pkeyopt md:SHA256 \
-pkeyopt hexsecret:ff -pkeyopt hexseed:ff -hexdump使用 scrypt 衍生金鑰，其中密碼從命令列讀取
openssl pkeyutl -kdf scrypt -kdflen 16 -pkeyopt_passin pass \
-pkeyopt hexsalt:aabbcc -pkeyopt N:16384 -pkeyopt r:8 -pkeyopt p:1使用相同的演算法衍生，但從環境變數 MYPASS 讀取金鑰
openssl pkeyutl -kdf scrypt -kdflen 16 -pkeyopt_passin pass:env:MYPASS \
-pkeyopt hexsalt:aabbcc -pkeyopt N:16384 -pkeyopt r:8 -pkeyopt p:1使用 SM2(7) 私鑰和特定 ID 簽署一些資料
openssl pkeyutl -sign -in file -inkey sm2.key -out sig -rawin -digest sm3 \
-pkeyopt distid:someid使用 SM2(7) 憑證和特定 ID 驗證一些資料
openssl pkeyutl -verify -certin -in file -inkey sm2.cert -sigfile sig \
-rawin -digest sm3 -pkeyopt distid:someid使用使用 SHA256 的 OAEP 填充的私鑰解密一些資料
openssl pkeyutl -decrypt -in file -inkey key.pem -out secret \
-pkeyopt rsa_padding_mode:oaep -pkeyopt rsa_oaep_md:sha256另請參閱
openssl(1)、openssl-genpkey(1)、openssl-pkey(1)、openssl-rsautl(1) openssl-dgst(1)、openssl-rsa(1)、openssl-genrsa(1)、openssl-kdf(1) EVP_PKEY_CTX_set_hkdf_md(3)、EVP_PKEY_CTX_set_tls1_prf_md(3)，
歷程
-engine 選項已在 OpenSSL 3.0 中棄用。
版權
版權所有 2006-2023 OpenSSL 專案作者。保留所有權利。
在 Apache 許可證 2.0（「許可證」）下取得授權。您只能在遵守許可證的情況下使用此檔案。您可以在原始程式碼散佈中的 LICENSE 檔案中取得副本，或在 https://www.openssl.org/source/license.html 取得。