diff --git a/wolfCLU/mkdocs-ja.yml b/wolfCLU/mkdocs-ja.yml index 17273b10..f91da117 100644 --- a/wolfCLU/mkdocs-ja.yml +++ b/wolfCLU/mkdocs-ja.yml @@ -31,6 +31,8 @@ nav: - "VERIFY コマンド": verify.md - "X509 コマンド": x509.md - "BASE64 コマンド": base64.md + - "付録": + - "設定ファイル": config.md theme: name: null custom_dir: ../mkdocs-material/material diff --git a/wolfCLU/mkdocs.yml b/wolfCLU/mkdocs.yml index ed80b6c0..8711f8fc 100644 --- a/wolfCLU/mkdocs.yml +++ b/wolfCLU/mkdocs.yml @@ -7,9 +7,13 @@ nav: - "1. Introduction": index.md - "2. Building wolfCLU": build.md - "3. Commands": + - "Command List": command_list.md - "BENCH Command": bench.md + - "CA Command": ca.md - "CRL Command": crl.md + - "DSAPARAM Command": dsaparam.md - "DGST Command": dgst.md + - "DHPARAM Command": dhparam.md - "ECPARAM Command": ecparam.md - "ENC Command": enc.md - "GENKEY Command": genkey.md @@ -22,10 +26,13 @@ nav: - "RAND Command": rand.md - "REQ Command": req.md - "RSA Command": rsa.md + - "SHA Command": sha.md - "S_CLIENT Command": s_client.md - "VERIFY Command": verify.md - "X509 Command": x509.md - "BASE64 Command": base64.md + - "Appendix": + - "Configuration File Format": config.md theme: name: null custom_dir: ../mkdocs-material/material diff --git a/wolfCLU/src-ja/Intro.md b/wolfCLU/src-ja/Intro.md index d8f151d0..0e70d1ca 100644 --- a/wolfCLU/src-ja/Intro.md +++ b/wolfCLU/src-ja/Intro.md @@ -1,8 +1,8 @@ # wolfCLU マニュアル - wolfSSL コマンドラインユーティリティ (version 0.0.7) -2021/Nov/24 +wolfSSL コマンドラインユーティリティ (version 0.1.8) +2025/April/4 ## 始めに diff --git a/wolfCLU/src-ja/bench.md b/wolfCLU/src-ja/bench.md index 5d992bb9..efaec9a1 100644 --- a/wolfCLU/src-ja/bench.md +++ b/wolfCLU/src-ja/bench.md @@ -1,2 +1,31 @@ ### BENCH コマンド -ベンチマーク アルゴリズムのコマンドは現在実装途中です。現在使用できるコマンドは、全アルゴリズムを実行する、"wolfSSL bench -all" です。 +アルゴリズムのベンチマークに使用されます。すべてのアルゴリズムをベンチマークするには `wolfssl bench -a` を実行します。 + +利用可能なアルゴリズム（設定に依存）： + +- aes-cbc +- aes-ctr +- 3des +- camellia +- md5 +- sha +- sha256 +- sha384 +- sha512 +- blake2b + +引数： + +- [algorithm] ベンチマークするアルゴリズム +- [-time] 実行時間（秒、1-10） +- [-a] または [-all] すべての利用可能なアルゴリズムをテスト +- [-in] 入力ファイル +- [-out] 出力ファイル + +使用例： + +``` +wolfssl bench aes-cbc -time 10 + +wolfssl bench -a -time 5 +``` diff --git a/wolfCLU/src-ja/ca.md b/wolfCLU/src-ja/ca.md index 02288f0b..3e7b09b3 100644 --- a/wolfCLU/src-ja/ca.md +++ b/wolfCLU/src-ja/ca.md @@ -1,21 +1,82 @@ ### CA コマンド -証明書への署名に使用されます。このコマンドはコンフィグレーションファイルを指定し、そのファイルから基本的なコンフィグレーション内容を取得することが可能です。 +証明書への署名に使用されます。設定ファイルの基本的な解析を処理できます。 -指定可能な引数: +設定ファイルのディレクティブの詳細は[設定ファイル](config.md)を参照してください。 -- [-in] 入力となるCSRファイル +引数: + +- [-in] 入力CSRファイル - [-out] 出力先ファイル - [-keyfile] 秘密鍵ファイル - [-cert] CA証明書ファイル -- [-extensions] コンフィグレーションファイル内の解析すべきセクション -- [-md] ハッシュタイプ（sha, sha256, ...） +- [-extensions] 設定ファイル内の拡張セクション +- [-md] ハッシュタイプ（sha、sha256 など） - [-inform] CSRファイル形式（PEM/DER） -- [-config] コンフィグレーションファイル -- [-days] 証明書に与える有効期間（日数） -- [-selfsign] 自己署名する +- [-config] 設定ファイル +- [-days] 証明書の有効期間（日数） +- [-selfsign] 入力証明書に関連付けられた鍵で署名 使用例: ``` wolfssl ca -config ca.conf -in test.csr -out test.pem -md sha256 -selfsign -keyfile ./key ``` + +### 典型的なワークフロー：CAでCSRに署名 + +**ステップ1: CA鍵と証明書を作成**（[GENKEY コマンド](genkey.md)と[REQ コマンド](req.md)を参照） + +``` +wolfssl genkey rsa -size 2048 -out ca -outform pem -output KEYPAIR +wolfssl req -new -x509 -key ca.priv -out ca.pem -days 3650 -subj "/C=JP/ST=Tokyo/L=Shinjuku/O=Example/CN=Example CA" +``` + +**ステップ2: サーバー鍵とCSRを作成** + +``` +wolfssl genkey rsa -size 2048 -out server -outform pem -output KEYPAIR +wolfssl req -new -key server.priv -out server.csr -subj "/C=JP/ST=Tokyo/L=Shinjuku/O=Example/CN=example.com" +``` + +**ステップ3: サーバーCSRをCAで署名** + +``` +wolfssl ca -in server.csr -out server-signed.pem -keyfile ca.priv -cert ca.pem -days 365 -md sha256 +``` + +**ステップ4: 署名済み証明書を検証**（[VERIFY コマンド](verify.md)を参照） + +``` +wolfssl verify -CAfile ca.pem server-signed.pem +``` + +### CAでの設定ファイルの使用 + +`-config` オプションを使用すると、署名時に追加する証明書拡張を指定できます。 + +CA設定ファイルの例（`ca.conf`）： + +```ini +[ca] +x509_extensions = v3_ca + +[v3_ca] +basicConstraints = critical, CA:FALSE +keyUsage = digitalSignature, keyEncipherment +subjectKeyIdentifier = hash +subjectAltName = @alt_names + +[alt_names] +DNS.1 = example.com +DNS.2 = www.example.com +``` + +設定ファイルの拡張を使用してCSRに署名： + +``` +wolfssl ca -config ca.conf -extensions v3_ca -in server.csr -out server-signed.pem -keyfile ca.priv -cert ca.pem -days 365 -md sha256 +``` + +### 制限事項 + +設定ファイルを使用しない場合、wolfCLUは署名された各証明書にランダムなシリアル番号を生成します。設定ファイルベースのシリアル番号管理とその現在の制限事項については、[設定ファイル - 制限事項](config.md#制限事項)を参照してください。 diff --git a/wolfCLU/src-ja/command_list.md b/wolfCLU/src-ja/command_list.md index cf1e34d6..8ad1aec5 100644 --- a/wolfCLU/src-ja/command_list.md +++ b/wolfCLU/src-ja/command_list.md @@ -1,26 +1,31 @@ -## コマンドリスト: +## コマンド一覧 + - base64 - bench - ca - crl -- dsaparam - dgst +- dhparam +- dsaparam +- ecc - ecparam -- enc +- ed25519 +- enc / encrypt / decrypt - genkey - hash - md5 -- pkcs12 - pkcs7 - pkcs8 +- pkcs12 - pkey - rand - req - rsa - s_client -- verify -- x509 -- dhparam +- s_server - sha256 - sha384 - sha512 +- verify +- version +- x509 diff --git a/wolfCLU/src-ja/config.md b/wolfCLU/src-ja/config.md new file mode 100644 index 00000000..d5925459 --- /dev/null +++ b/wolfCLU/src-ja/config.md @@ -0,0 +1,285 @@ +### 設定ファイル形式 + +wolfCLUは `req` および `ca` コマンドでOpenSSLスタイルの設定ファイルをサポートしています。このページでは、サポートされているディレクティブについて説明します。 + +## 基本構造 + +設定ファイルはINIスタイルの形式で、セクションとキー・バリューのペアで構成されます： + +```ini +[section_name] +key = value +``` + +## REQコマンドの設定 + +### メインセクション + +`[req]` セクションには主要な設定が含まれます： + +| ディレクティブ | 説明 | +|---------------|------| +| `prompt` | `no` に設定すると対話的なプロンプトを無効化 | +| `default_bits` | デフォルトの鍵サイズ（ビット単位、例：2048） | +| `default_md` | デフォルトのハッシュアルゴリズム（例：sha256） | +| `default_keyfile` | デフォルトの鍵ファイルパス | +| `distinguished_name` | DN フィールドを含むセクション名 | +| `attributes` | 属性を含むセクション名 | +| `x509_extensions` | X509拡張を含むセクション名 | + +### Distinguished Name セクション + +distinguished name セクション（`distinguished_name` で参照）は証明書のサブジェクトフィールドを定義します： + +| ディレクティブ | 説明 | +|---------------|------| +| `countryName` | 国コード（2文字、例：JP、US） | +| `stateOrProvinceName` | 都道府県名 | +| `localityName` | 市区町村名 | +| `organizationName` | 組織名 | +| `organizationalUnitName` | 部署名 | +| `commonName` または `CN` | コモンネーム（例：ドメイン名） | +| `emailAddress` | メールアドレス | +| `name` | 名前 | +| `surname` | 姓 | +| `givenName` | 名 | +| `initials` | イニシャル | +| `dnQualifier` | DN修飾子 | + +各フィールドにはオプションの修飾子を設定できます： + +| 修飾子 | 説明 | +|--------|------| +| `_default` | 指定されない場合のデフォルト値 | +| `_min` | 最小文字数 | +| `_max` | 最大文字数 | + +### 属性セクション + +属性セクション（`attributes` で参照）はPKCS#9属性を定義します： + +| ディレクティブ | 説明 | +|---------------|------| +| `challengePassword` | PKCS#9 チャレンジパスワード | +| `unstructuredName` | PKCS#9 非構造化名 | + +## X509拡張セクション + +拡張セクション（`x509_extensions` で参照）は証明書の拡張を定義します： + +| ディレクティブ | 説明 | +|---------------|------| +| `basicConstraints` | CA制約とパス長 | +| `subjectKeyIdentifier` | サブジェクト鍵識別子 | +| `authorityKeyIdentifier` | 認証局鍵識別子 | +| `keyUsage` | 鍵用途フラグ | +| `subjectAltName` | サブジェクト代替名 | + +### basicConstraints + +証明書がCAかどうかと、最大パス長を定義します。 + +形式: `[critical, ]CA:TRUE|FALSE[, pathlen:]` + +| 値 | 説明 | +|----|------| +| `critical` | クリティカル拡張としてマーク | +| `CA:TRUE` | CA証明書である | +| `CA:FALSE` | CA証明書ではない | +| `pathlen:` | 最大証明書パス長 | + +例： +```ini +basicConstraints = critical, CA:TRUE, pathlen:0 +basicConstraints = CA:FALSE +``` + +### keyUsage + +証明書に含まれる鍵の用途を定義します。 + +形式: `[critical, ][, ...]` + +| 値 | 説明 | +|----|------| +| `digitalSignature` | デジタル署名 | +| `nonRepudiation` | 否認防止（`contentCommitment` も可） | +| `keyEncipherment` | 鍵暗号化 | +| `dataEncipherment` | データ暗号化 | +| `keyAgreement` | 鍵共有 | +| `keyCertSign` | 証明書署名 | +| `cRLSign` | CRL署名 | +| `encipherOnly` | 暗号化のみ（keyAgreementと併用） | +| `decipherOnly` | 復号のみ（keyAgreementと併用） | + +例： +```ini +keyUsage = critical, digitalSignature, keyEncipherment +keyUsage = keyCertSign, cRLSign +``` + +### subjectKeyIdentifier + +証明書内の公開鍵を識別します。 + +| 値 | 説明 | +|----|------| +| `hash` | 公開鍵のハッシュを使用 | + +例： +```ini +subjectKeyIdentifier = hash +``` + +### subjectAltName + +証明書サブジェクトの追加識別子を指定します。`@section_name` を使用して代替名を含むセクションを参照します。 + +例： +```ini +subjectAltName = @alt_names +``` + +#### 代替名セクション + +| ディレクティブ | 説明 | +|---------------|------| +| `DNS.` | DNS名（例：`DNS.1 = example.com`） | +| `IP.` | IPアドレス（例：`IP.1 = 192.168.1.1`） | +| `URI.` | URI（例：`URI.1 = https://example.com`） | +| `email.` | メールアドレス（例：`email.1 = admin@example.com`） | +| `RID.` | 登録ID / OID | + +例： +```ini +[alt_names] +DNS.1 = example.com +DNS.2 = www.example.com +IP.1 = 192.168.1.1 +email.1 = admin@example.com +``` + +## CAコマンドの設定 + +### メインセクション + +`[ca]` セクションはデフォルトのCAセクションを指定します： + +```ini +[ca] +default_ca = CA_default +``` + +### CAセクション + +CAセクション（例：`[CA_default]`）にはCA固有の設定が含まれます： + +| ディレクティブ | 説明 | +|---------------|------| +| `serial` | シリアル番号を含むファイル（16進形式） | +| `new_certs_dir` | 新規証明書のディレクトリ | +| `certificate` | CA証明書ファイル | +| `private_key` | CA秘密鍵ファイル | +| `default_days` | デフォルトの有効期間（日数） | +| `default_md` | デフォルトのハッシュアルゴリズム | +| `x509_extensions` | 拡張のセクション名 | +| `policy` | DNポリシーのセクション名 | +| `database` | 証明書データベースファイル | +| `unique_subject` | 一意のサブジェクトを要求 | +| `crl_dir` | CRLのディレクトリ | +| `crl` | CRLファイル | +| `RANDFILE` | 乱数シードファイル | + +## 設定例 + +### サーバー証明書リクエスト + +```ini +[req] +prompt = no +default_bits = 2048 +default_md = sha256 +distinguished_name = req_dn +x509_extensions = v3_server + +[req_dn] +countryName = JP +stateOrProvinceName = Tokyo +localityName = Shinjuku +organizationName = Example Corp +commonName = example.com +emailAddress = info@example.com + +[v3_server] +basicConstraints = critical, CA:FALSE +keyUsage = digitalSignature, keyEncipherment +subjectKeyIdentifier = hash +subjectAltName = @alt_names + +[alt_names] +DNS.1 = example.com +DNS.2 = www.example.com +IP.1 = 192.168.1.1 +``` + +使用方法： +``` +wolfssl req -new -config server.conf -key server.priv -out server.csr +wolfssl req -new -x509 -config server.conf -key server.priv -out server.pem -days 365 +``` + +### CA証明書 + +```ini +[req] +prompt = no +default_bits = 4096 +default_md = sha256 +distinguished_name = ca_dn +x509_extensions = v3_ca + +[ca_dn] +countryName = JP +stateOrProvinceName = Tokyo +localityName = Shinjuku +organizationName = Example Corp +commonName = Example CA + +[v3_ca] +basicConstraints = critical, CA:TRUE, pathlen:1 +keyUsage = critical, keyCertSign, cRLSign +subjectKeyIdentifier = hash +``` + +使用方法： +``` +wolfssl req -new -x509 -config ca.conf -key ca.priv -out ca.pem -days 3650 +``` + +### シンプルなCSR（最小構成） + +```ini +[req] +prompt = no +distinguished_name = req_dn + +[req_dn] +commonName = myserver +``` + +使用方法： +``` +wolfssl req -new -config simple.conf -key server.priv -out server.csr +``` + +## 制限事項 + +### シリアル番号ファイル + +`serial` ディレクティブは、16進形式のシリアル番号を含むファイルを指定します： + +``` +01 +``` + +**注意:** 現在のバージョン（v0.1.8）では、設定ファイルベースのシリアル番号管理にパス処理の問題があります。この問題が解決されるまで、コマンドライン引数を直接使用することを推奨します。設定ファイルを使用しない場合、wolfCLUは署名された各証明書にランダムなシリアル番号を生成します。 diff --git a/wolfCLU/src-ja/crl.md b/wolfCLU/src-ja/crl.md index 74dd6b24..30a3e3d1 100644 --- a/wolfCLU/src-ja/crl.md +++ b/wolfCLU/src-ja/crl.md @@ -1,17 +1,20 @@ ### CRL コマンド -CA を指定して CRL ファイルを検証するために使用されます。 または、CRL を フォーマット変換 [DER|PEM] することもできます。-out が指定されておらず、-noout が使用されていない場合、このコマンドは CRL を stdout に出力します。 検証が成功すると「OK」を出力します。 +CAを使用してCRLファイルを検証するか、CRLを一方の形式[DER | PEM]から他方に変換するために使用されます。-out が指定されず -noout が使用されていない場合、CRLはstdoutに出力されます。検証が成功すると「OK」が出力されます。 引数： -- [-CAfile] CA証明書ファイル -- [-inform] 入力フォーマット：pem あるいは der -- [-in] the CRLファイル -- [-outform] 出力フォーマット：pem あるいは der +- [-CAfile] CAファイル名 +- [-inform] 入力形式：pem または der +- [-in] 入力ファイル +- [-outform] 出力形式：pem または der - [-out] 出力ファイル -- [-noout] 指定がある場合には出力しません +- [-noout] 設定時は出力しない +- [-text] CRLの人間が読める形式のテキストを出力 -使用例: +使用例： ``` wolfssl crl -CAfile ./certs/ca-cert.pem -in ./certs/crl.der -inform DER -noout -``` \ No newline at end of file + +wolfssl crl -in ./certs/crl.pem -text +``` diff --git a/wolfCLU/src-ja/dgst.md b/wolfCLU/src-ja/dgst.md index d4a120bf..7bd45ada 100644 --- a/wolfCLU/src-ja/dgst.md +++ b/wolfCLU/src-ja/dgst.md @@ -1,34 +1,33 @@ ### DGST コマンド -署名を検証することが可能です。最後の引数は署名対象となったデータです。 +デジタル署名の作成と検証に使用されます。最後の引数は署名されたデータです。 -サポートしているハッシュアルゴリズム: +サポートされているハッシュアルゴリズム： +- [-md5] - [-sha] - [-sha224] - [-sha256] - [-sha384] - [-sha512] -**署名** +引数： -引数: +- [-signature] 署名を含むファイル +- [-inform] 入力形式：pem または der +- [-verify] 署名を検証するための鍵 +- [-sign] 署名を作成するための秘密鍵 +- [-out] 署名の出力ファイル -- [-sign] 署名作成に必要な鍵 -- [-out] 署名出力先のファイル +**署名** -使用例: +使用例： ``` -wolfssl dgst -sign keyPrivate.pem -out test.sig testfile +wolfssl dgst -sha256 -sign keyPrivate.pem -out test.sig testfile ``` **検証** -引数: - -- [-verify] 署名を検証する為に使用する鍵 -- [-signature] 署名を含んだファイル - -使用例: +使用例： ``` -wolfssl dgst -verify keyPublic.pem -signature test.sig testfile +wolfssl dgst -sha256 -signature test.sig -verify keyPublic.pem testfile ``` diff --git a/wolfCLU/src-ja/ecparam.md b/wolfCLU/src-ja/ecparam.md index d0eb6dbe..38ae650b 100644 --- a/wolfCLU/src-ja/ecparam.md +++ b/wolfCLU/src-ja/ecparam.md @@ -1,17 +1,33 @@ ### ECPARAM コマンド -ECC鍵生成に使用します。 +ECC鍵の作成に使用されます。 +引数： -指定可能な引数： +- [-genkey] 新しい鍵を作成 +- [-out] 出力ファイル +- [-name] 曲線名 -- [-genkey] 新しい鍵を生成する -- [-out] 出力先ファイル -- [-name] 楕円曲線名（secp384r1等） +利用可能な曲線名： +- PRIME239V1 +- PRIME239V2 +- PRIME239V3 +- SECP256R1 +- SECP224R1 +- SECP384R1 +- SECP521R1 +- SECP256K1 +- BRAINPOOLP224R1 +- BRAINPOOLP256R1 +- BRAINPOOLP320R1 +- BRAINPOOLP384R1 +- BRAINPOOLP512R1 -使用例: +使用例： ``` wolfssl ecparam -genkey -out new.key -name secp384r1 -``` \ No newline at end of file + +wolfssl ecparam -genkey -out brainpool.key -name BRAINPOOLP256R1 +``` diff --git a/wolfCLU/src-ja/enc.md b/wolfCLU/src-ja/enc.md index 5319c4ae..34e59b51 100644 --- a/wolfCLU/src-ja/enc.md +++ b/wolfCLU/src-ja/enc.md @@ -1,9 +1,8 @@ ### ENC コマンド -入力の暗号化に使用され、(-d) で復号することもできます。 +入力の暗号化に使用されます。-d を設定すると復号が有効になります。 - -指定可能な暗号化と復号アルゴリズム： +利用可能な暗号化/復号アルゴリズム（設定に依存）： - aes-cbc-128 - aes-cbc-192 @@ -14,26 +13,33 @@ - 3des-cbc-56 - 3des-cbc-112 - 3des-cbc-168 - -指定可能な引数： - -- [-in]　対象の入力ファイル -- [-out] 出力先ファイル（デフォルト：stdout) -- [-pwd] パスワード -- [-key] 鍵データ（hex) -- [-iv] 鍵初期化ベクトル(hex) -- [-inkey] 鍵ファイル -- [-pbkdf2] KDF version2を使用する -- [-md] ハッシュアルゴリズムを指定（ md5, sha256等） -- [-d] 入力ファイルを復号する -- [-p] デバッグ出力(key / iv 等)をプリントアウトする -- [-k] パスワード入力のオプション -- [-base64] base64エンコードされている入力を処理する -- [-nosalt] KDFにソルトを使用しない - - -使用例: +- camellia-cbc-128 +- camellia-cbc-192 +- camellia-cbc-256 + +引数： + +- [-in] 入力ファイル +- [-out] 出力先ファイル（デフォルト：stdout） +- [-pwd] パスワード入力 +- [-k] パスワード入力の別オプション +- [-pass] パスワードソースのオプション（例：pass:password） +- [-key] 16進数の鍵入力 +- [-iv] 16進数のIV入力 +- [-inkey] 鍵の入力ファイル +- [-pbkdf2] KDFバージョン2を使用 +- [-md] 使用するハッシュアルゴリズムを指定（例：md5、sha256） +- [-d] 入力ファイルを復号 +- [-p] デバッグ情報を表示（鍵/IVなど） +- [-base64] base64入力のデコードを処理 +- [-nosalt] KDFにソルト入力を使用しない + +使用例： ``` wolfssl enc -aes-128-cbc -k Thi$i$myPa$$w0rd -in somefile.txt -``` \ No newline at end of file + +wolfssl enc aes-cbc-256 -pwd Thi$i$myPa$$w0rd -in somefile.txt -out encryptedfile.txt + +wolfssl enc aes-cbc-256 -d -pwd Thi$i$myPa$$w0rd -in encryptedfile.txt -out decryptedfile.txt +``` diff --git a/wolfCLU/src-ja/genkey.md b/wolfCLU/src-ja/genkey.md index eb0ad421..21775826 100644 --- a/wolfCLU/src-ja/genkey.md +++ b/wolfCLU/src-ja/genkey.md @@ -1,18 +1,47 @@ ### GENKEY コマンド -RSA、ECC、ED25519、および DSA 鍵の生成に使用されます。 `-output KEY`を使用すると、-out 引数で与えたファイル名に .priv が追加された秘密鍵ファイルあるいは.pub が追加された公開鍵ファイルが作成されます。 ED25519 鍵を生成する場合には、wolfSSL を --enable-ed25519 でコンパイルしておく必要があります。 +RSA、ECC、ED25519鍵の生成に使用されます。"-output KEYPAIR" を使用すると、-out引数に .priv を付加した秘密鍵と .pub を付加した公開鍵が作成されます。ED25519鍵を生成する場合は、wolfSSLを --enable-ed25519 でコンパイルしてください。 -指定可能な引数： +利用可能な鍵タイプ（設定に依存）： +- rsa +- ecc +- ed25519 + +引数： + +- [rsa | ecc | ed25519] 生成する鍵タイプ +- [-size] 生成する鍵のサイズ（ビット） - [-out] 出力先ファイル -- [rsa | ecc | ed25519] 生成する鍵のタイプ -- [-inkey] 入力ファイル -- [-size] 生成する鍵のサイズ（ビット数） -- [-outform] 出力形式（DER あるいは PEM）(デフォルト： DER) -- [-output] 生成する鍵（PUB, PRIV あるいは KEYPAIR）(デフォルト：KEYPAIR) -- [-exponent] RSA指数サイズ +- [-outform] 出力形式：DER または PEM（デフォルト：DER） +- [-output] 生成する鍵：PUB、PRIV または KEYPAIR（デフォルト：KEYPAIR） + +使用例： + +``` +wolfssl genkey rsa -size 2048 -out mykey -outform pem -output KEYPAIR + +wolfssl genkey ecc -out ecckey -outform pem -output KEYPAIR + +wolfssl genkey ed25519 -out ed25519key -outform pem -output KEYPAIR +``` -使用例: +上記のコマンドは mykey.priv と mykey.pub ファイルを出力します。 +-output オプションを PRIV のみに変更すると、秘密鍵のみを出力します。 + +### 典型的なワークフロー：RSA鍵から証明書まで + +**ステップ1: サーバー用RSA鍵ペアを生成** + +``` +wolfssl genkey rsa -size 2048 -out server -outform pem -output KEYPAIR +``` + +これにより `server.priv`（秘密鍵）と `server.pub`（公開鍵）が作成されます。 + +**ステップ2: CA用RSA鍵ペアを生成** ``` -wolfssl genkey rsa -size 2048 -out mykey -outform pem -output KEYPAIR +wolfssl genkey rsa -size 2048 -out ca -outform pem -output KEYPAIR ``` + +CSRと証明書の作成については[REQ コマンド](req.md)を、証明書の署名については[CA コマンド](ca.md)を参照してください。 diff --git a/wolfCLU/src-ja/hash.md b/wolfCLU/src-ja/hash.md index d1c59344..0d59209a 100644 --- a/wolfCLU/src-ja/hash.md +++ b/wolfCLU/src-ja/hash.md @@ -1,19 +1,26 @@ ### HASH コマンド -入力データのハッシュを生成します。 +入力データのハッシュを作成するために使用されます。 -サポートしているハッシュアルゴリズム: +利用可能なアルゴリズム（設定に依存）： - md5 - sha - sha256 - sha384 - sha512 +- blake2b - base64enc - base64dec +引数： -使用例: +- [algorithm] 使用するハッシュアルゴリズム +- [-in] ハッシュするファイル +使用例： + +``` +wolfssl hash sha256 -in somefile.txt + +wolfssl hash blake2b -in somefile.txt ``` -wolfssl -hash sha -in -``` \ No newline at end of file diff --git a/wolfCLU/src-ja/pkey.md b/wolfCLU/src-ja/pkey.md index fc4646b6..0033414d 100644 --- a/wolfCLU/src-ja/pkey.md +++ b/wolfCLU/src-ja/pkey.md @@ -1,15 +1,19 @@ ### PKEY コマンド -一般的な鍵操作を処理するために使用されます。 読み込まれた鍵を stdout に出力します。 +汎用的な鍵操作を扱うために使用されます。読み込んだ鍵をstdoutに出力します。 -引数: +引数： -- [-in] 入力される鍵ファイル -- [-inform] 入力ファイル形式：pem あるいは der (デフォルト：pem) -- [-pubout] 公開鍵のみプリントアウトする -- [-pubin] 公開鍵を入力として期待する +- [-in] 読み込む鍵の入力ファイル +- [-out] 出力先ファイル（デフォルト：stdout） +- [-inform] 入力形式：pem または der（デフォルト：pem） +- [-outform] 出力形式：pem または der +- [-pubout] 公開鍵を出力 +- [-pubin] 公開鍵の読み込みを期待 -使用例: +使用例： ``` -./wolfssl pkey -in ./certs/server-key.pem -inform pem -pubout +wolfssl pkey -in ./certs/server-key.pem -inform pem -pubout + +wolfssl pkey -in ./certs/server-key.pem -out pubkey.pem -pubout ``` diff --git a/wolfCLU/src-ja/rand.md b/wolfCLU/src-ja/rand.md index 7fe4b67d..73692aaf 100644 --- a/wolfCLU/src-ja/rand.md +++ b/wolfCLU/src-ja/rand.md @@ -1,12 +1,12 @@ ### RAND コマンド -raw または base64 形式でランダムデータのバイト列を生成します。 デフォルトでは、結果を stdout に出力しますが、'-out' 引数を使用してリダイレクトできます。 渡される最後の引数は、生成するランダムデータのバイト数です。 +生またはbase64形式でランダムバイトを生成します。デフォルトでは結果をstdoutに出力しますが、'-out' 引数でリダイレクトできます。渡される最後の引数は生成するランダムバイト数です。 -引数: +引数： -- [-base64] ランダムデータをbase64エンコードする -- [-out] 結果を出力するファイル +- [-base64] 結果のランダムバイトをbase64エンコード +- [-out] 結果を書き込む出力ファイル -使用例: +使用例： ``` wolfssl rand -base64 10 diff --git a/wolfCLU/src-ja/req.md b/wolfCLU/src-ja/req.md index b332afb2..372e3a1b 100644 --- a/wolfCLU/src-ja/req.md +++ b/wolfCLU/src-ja/req.md @@ -1,22 +1,75 @@ ### REQ コマンド -証明書要求または自己署名証明書の作成に使用されます。 証明書をセットアップするための .conf ファイルのいくつかの基本的な解析を処理できます。 構成ファイルが使用されていない場合、stdin は証明書情報の入力を求められます。 +証明書署名リクエスト（CSR）または自己署名証明書の作成に使用されます。証明書をセットアップするための設定ファイル（.conf）の基本的な解析を処理できます。設定ファイルが使用されていない場合、stdinで証明書情報の入力を求められます。 +設定ファイルのディレクティブの詳細は[設定ファイル](config.md)を参照してください。 -指定可能な引数: +引数: - [-in] 入力ファイル -- [-out] 出力先ファイル(デフォルト：stdout) -- [-key] 証明書要求に含める公開鍵ファイル -- [-inform] 入力ファイル形式：pem あるいは der (デフォルト：pem) -- [-outform] 出力ファイル形式：pem あるいは der (デフォルト：pem) -- [-config] 証明書のコンフィグレーションファイル +- [-out] 出力先ファイル（デフォルト：stdout） +- [-key] 証明書リクエストに含める公開鍵ファイル +- [-inform] 入力ファイル形式：der または pem（デフォルト：pem） +- [-outform] 出力ファイル形式：der または pem（デフォルト：pem） +- [-config] 証明書の設定ファイル - [-days] 有効期間（日数） -- [-x509] 自己署名証明書を生成する +- [-x509] 自己署名証明書を生成 +- [-extensions] 拡張を取得するセクションを上書き +- [-nodes] 秘密鍵出力にDES暗号化を使用しない +- [-newkey] reqで使用する秘密鍵を生成 +- [-inkey] reqで使用する秘密鍵 +- [-keyout] 鍵の出力先ファイル +- [-subj] サブジェクト名を指定（例：O=wolfSSL/C=JP/ST=Tokyo/L=Shinjuku/CN=example.com/OU=dev） +- [-verify] リクエストの署名を検証 +- [-text] 人間が読める形式でリクエストを出力 +- [-noout] 生成結果を出力しない 使用例: ``` wolfssl ecparam -genkey -out ecc.key -name secp384r1 -wolfssl req -new -x509 -days 3650 -config selfsigned.conf -key ecc.key -out ecc.cert \ --outform der -sha256 + +wolfssl req -new -x509 -days 3650 -config selfsigned.conf -key ecc.key -out ecc.cert -outform der -sha256 + +wolfssl req -newkey rsa:2048 -keyout mykey.pem -out myreq.csr -subj "O=wolfSSL/C=JP/CN=test" +``` + +### 典型的なワークフロー：RSA鍵から証明書まで + +**ステップ1: RSA鍵ペアを生成**（[GENKEY コマンド](genkey.md)を参照） + +``` +wolfssl genkey rsa -size 2048 -out server -outform pem -output KEYPAIR +``` + +**ステップ2: 秘密鍵からCSRを作成** + +``` +wolfssl req -new -key server.priv -out server.csr -subj "/C=JP/ST=Tokyo/L=Shinjuku/O=Example/CN=example.com" +``` + +**ステップ3a: 自己署名証明書を作成** + +``` +wolfssl req -x509 -key server.priv -in server.csr -out server.pem -days 365 +``` + +**ステップ3b: またはCA署名証明書を作成**（[CA コマンド](ca.md)を参照） + +まず、CA証明書を作成： + +``` +wolfssl genkey rsa -size 2048 -out ca -outform pem -output KEYPAIR +wolfssl req -new -x509 -key ca.priv -out ca.pem -days 3650 -subj "/C=JP/ST=Tokyo/L=Shinjuku/O=Example/CN=Example CA" +``` + +次に、サーバーCSRをCAで署名： + +``` +wolfssl ca -in server.csr -out server-signed.pem -keyfile ca.priv -cert ca.pem -days 365 -md sha256 +``` + +**ステップ4: 証明書を検証**（[VERIFY コマンド](verify.md)を参照） + +``` +wolfssl verify -CAfile ca.pem server-signed.pem ``` diff --git a/wolfCLU/src-ja/rsa.md b/wolfCLU/src-ja/rsa.md index 6611aacf..e54930cd 100644 --- a/wolfCLU/src-ja/rsa.md +++ b/wolfCLU/src-ja/rsa.md @@ -1,14 +1,44 @@ ### RSA コマンド -RSA操作を行います。 RSA鍵の読み取り、RSA鍵またはモジュラスの出力、暗号化された PEM ファイルの読み取りが含まれます。 入力と出力の DER と PEM 形式の両方を処理できます。 - -引数: - -- [-in] 入力となる鍵ファイル -- [-inform] 入力ファイル形式：PEM あるいは DER (デフォルト：PEM) -- [-out] 出力ファイル(デフォルト：stdout) -- [-outform] 出力ファイル形式：PEM あるいは DER (デフォルト：PEM) -- [-passin] PEM形式の暗号化されたファイルのパスワード -- [-noout] 鍵をプリントアウトしない -- [-modulus] RSA modulus (n value)をプリントする -- [-RSAPublicKey_in] 公開鍵入力を期待する +署名、検証、鍵管理を含むRSA操作を実行します。入出力にDERおよびPEM形式を処理できます。 + +**RSA署名** + +``` +wolfssl rsa -sign -inkey -in -out +``` + +**秘密鍵でRSA検証** + +``` +wolfssl rsa -verify -inkey -sigfile -out +``` + +**公開鍵でRSA検証** + +``` +wolfssl rsa -verify -inkey -sigfile -out -pubin +``` + +引数： + +- [-sign] 入力データに署名 +- [-verify] 署名を検証 +- [-inkey] 署名/検証用の鍵ファイル +- [-in] 署名または処理する入力ファイル +- [-out] 結果の出力先ファイル（デフォルト：stdout） +- [-sigfile] 検証用の署名ファイル +- [-pubin] 公開鍵入力を期待 +- [-inform] 入力形式：PEM または DER（デフォルト：PEM） +- [-outform] 出力形式：PEM または DER（デフォルト：PEM） +- [-passin] PEM暗号化ファイルのパスワード +- [-noout] 設定時に鍵を出力しない +- [-modulus] RSAモジュラス（n値）を出力 + +使用例： + +``` +wolfssl rsa -sign -inkey private.pem -in data.txt -out signature.bin + +wolfssl rsa -verify -inkey public.pem -sigfile signature.bin -out verified.txt -pubin +``` diff --git a/wolfCLU/src-ja/s_client.md b/wolfCLU/src-ja/s_client.md index 2d5cce87..9565aecc 100644 --- a/wolfCLU/src-ja/s_client.md +++ b/wolfCLU/src-ja/s_client.md @@ -1,14 +1,26 @@ ### S_CLIENT コマンド -基本的なTLS接続がサポートされています。 現在、ピアを検証していません。-CAfile オプションはまだ完了していません。 - +接続テスト用の基本的なTLSクライアントです。 引数： -- [-connect] ipアドレス:port番号 +- [-connect] `:` または `<[ipv6]>:` +- [-starttls] STARTTLSのプロトコル（例：smtp） +- [-CAfile] 検証用のCAファイル名 +- [-verify_return_error] 検証エラー時に接続を閉じる +- [-disable_stdin_check] 標準入力チェックを無効化 + +IPv6の例： +- `-connect '[::1]:11111'` +- `-connect '[fe80::63:57c0:9b88:77ca%en0]:11111'` +- `-connect '[2001:4860:4860::8888]:443'` -使用例 : +使用例： ``` wolfssl s_client -connect 127.0.0.1:11111 -``` \ No newline at end of file + +wolfssl s_client -connect example.com:443 -CAfile ./certs/ca-cert.pem + +wolfssl s_client -connect '[::1]:11111' +``` diff --git a/wolfCLU/src-ja/verify.md b/wolfCLU/src-ja/verify.md index 1bbb1b37..bc96835c 100644 --- a/wolfCLU/src-ja/verify.md +++ b/wolfCLU/src-ja/verify.md @@ -1,15 +1,33 @@ ### VERIFY コマンド +CAを使用してX509証明書を検証します。コマンドに渡される最後の引数は、検証する証明書ファイル名です。検証が成功すると「OK」がstdoutに出力されます。それ以外の場合は、エラー値と理由が出力されます。 -CA が指定された X509 証明書を検証します。 コマンドに渡される最後の引数は、検証する証明書ファイルの名前です。 検証が成功すると、「OK」が stdout に出力されます。 それ以外の場合、エラー値と理由が出力されます。 +引数： -引数: +- [-CAfile] 検証に使用するCAのファイル名 +- [-untrusted] 検証に使用する中間証明書のファイル名（現在1つの-untrusted証明書のみサポート） +- [-crl_check] CRLチェックを使用する場合 +- [-partial_chain] 中間CAでの検証を許可 -- [-CAfile] 検証に使用するCA証明書ファイル -- [-crl_check] CRL検証が必要 -- [-untrusted] 検証に使用する中間証明書のファイル名（現在は1つの-untrusted証明書のみサポートしています） - -使用例: +使用例： ``` wolfssl verify -CAfile ./certs/ca-cert.pem ./certs/server-cert.pem -``` \ No newline at end of file + +wolfssl verify -CAfile ./certs/ca-cert.pem -untrusted ./certs/intermediate.pem ./certs/server-cert.pem +``` + +### 典型的なワークフロー：CA署名証明書の検証 + +CA署名証明書を作成した後（[CA コマンド](ca.md)を参照）、検証： + +``` +wolfssl verify -CAfile ca.pem server-signed.pem +``` + +成功時の期待される出力： + +``` +verifying certificate file server-signed.pem +using CA file ca.pem +OK +``` diff --git a/wolfCLU/src-ja/x509.md b/wolfCLU/src-ja/x509.md index b25a1cc9..02b2c5dc 100644 --- a/wolfCLU/src-ja/x509.md +++ b/wolfCLU/src-ja/x509.md @@ -1,17 +1,48 @@ ### X509 コマンド -このコマンドは、証明書の解析と出力に使用されます。 +証明書の解析と表示に使用されます。 -引数: +引数： -- [-in] 入力となるX509証明書ファイル -- [-inform] 入力ファイル形式：pem あるいは der (デフォルト：pem) +- [-in] X509ファイル入力 +- [-inform] 入力形式：pem または der（デフォルト：pem） - [-out] 出力先ファイル -- [-outform] 出力ファイル形式：pem あるいは der(デフォルト：pem) -- [-pubkey] 公開鍵のみ出力する -- [-text] 証明書を出力する +- [-outform] 出力形式：pem または der（デフォルト：pem） +- [-req] 入力ファイルがCSRファイル +- [-signkey] 署名用の鍵 +- [-*] 署名用のダイジェスト（例：-sha256） +- [-extfile] 設定ファイル +- [-extensions] 使用する設定ファイルのセクション +- [-noout] 出力しない +- [-subject] サブジェクト名を表示 +- [-issuer] 発行者名を表示 +- [-serial] シリアル番号を16進数で表示 +- [-dates] 証明書の有効期間を表示 +- [-email] サブジェクト名のメールアドレスを表示 +- [-fingerprint] 証明書のDER形式のハッシュを表示 +- [-purpose] 証明書の目的を表示 +- [-hash] 証明書サブジェクト名のハッシュを表示 +- [-text] X509の人間が読める形式のテキストを表示 +- [-modulus] RSA鍵のモジュラスを表示 +- [-pubkey] 公開鍵を表示 -使用例: +使用例： ``` wolfssl x509 -in ./certs/server-cert.pem -text + +wolfssl x509 -inform pem -in certs/ca-cert.pem -outform der -out certs/ca-cert-converted.der +``` + +### 典型的なワークフロー：証明書の詳細を確認 + +証明書を作成した後（[REQ コマンド](req.md)または[CA コマンド](ca.md)を参照）、詳細を確認： + +``` +wolfssl x509 -in server.pem -text -noout +``` + +特定の情報を表示： + +``` +wolfssl x509 -in server.pem -subject -issuer -dates -noout ``` diff --git a/wolfCLU/src/Intro.md b/wolfCLU/src/Intro.md index 7950f239..b355362f 100644 --- a/wolfCLU/src/Intro.md +++ b/wolfCLU/src/Intro.md @@ -1,8 +1,8 @@ # wolfCLU Manual - wolfSSL's Command Line Utility (version 0.0.7) -Nov, 24, 2021 +wolfSSL's Command Line Utility (version 0.1.8) +April 4, 2025 ## Intro diff --git a/wolfCLU/src/bench.md b/wolfCLU/src/bench.md index efc0d692..29ed5efe 100644 --- a/wolfCLU/src/bench.md +++ b/wolfCLU/src/bench.md @@ -1,2 +1,31 @@ ### BENCH Command -Command in progress for benchmarking algorithms. To benchmark all algorithms run "wolfssl bench -all". +Used for benchmarking algorithms. To benchmark all algorithms run `wolfssl bench -a`. + +Available algorithms (depends on configure settings): + +- aes-cbc +- aes-ctr +- 3des +- camellia +- md5 +- sha +- sha256 +- sha384 +- sha512 +- blake2b + +Arguments: + +- [algorithm] algorithm to benchmark +- [-time] time in seconds to run (1-10) +- [-a] or [-all] test all available algorithms +- [-in] input file to read from +- [-out] output file to write to + +Example: + +``` +wolfssl bench aes-cbc -time 10 + +wolfssl bench -a -time 5 +``` diff --git a/wolfCLU/src/ca.md b/wolfCLU/src/ca.md index 6cc1cd16..4738c5d3 100644 --- a/wolfCLU/src/ca.md +++ b/wolfCLU/src/ca.md @@ -1,7 +1,9 @@ ### CA Command Used for signing Certificates. Can handle some basic config file parsing. -Available arguments are: +See [Configuration File](config.md) for details on config file directives. + +Arguments: - [-in] input CSR file - [-out] file to write to @@ -19,3 +21,62 @@ Example: ``` wolfssl ca -config ca.conf -in test.csr -out test.pem -md sha256 -selfsign -keyfile ./key ``` + +### Typical Workflow: Sign CSR with CA + +**Step 1: Create CA key and certificate** (see [GENKEY Command](genkey.md) and [REQ Command](req.md)) + +``` +wolfssl genkey rsa -size 2048 -out ca -outform pem -output KEYPAIR +wolfssl req -new -x509 -key ca.priv -out ca.pem -days 3650 -subj "/C=US/ST=Washington/L=Seattle/O=wolfSSL/CN=wolfSSL CA" +``` + +**Step 2: Create server key and CSR** + +``` +wolfssl genkey rsa -size 2048 -out server -outform pem -output KEYPAIR +wolfssl req -new -key server.priv -out server.csr -subj "/C=US/ST=Washington/L=Seattle/O=wolfSSL/CN=example.com" +``` + +**Step 3: Sign server CSR with CA** + +``` +wolfssl ca -in server.csr -out server-signed.pem -keyfile ca.priv -cert ca.pem -days 365 -md sha256 +``` + +**Step 4: Verify the signed certificate** (see [VERIFY Command](verify.md)) + +``` +wolfssl verify -CAfile ca.pem server-signed.pem +``` + +### Using Configuration File with CA + +The `-config` option allows specifying certificate extensions to be added when signing. + +Example CA config file (`ca.conf`): + +```ini +[ca] +x509_extensions = v3_ca + +[v3_ca] +basicConstraints = critical, CA:FALSE +keyUsage = digitalSignature, keyEncipherment +subjectKeyIdentifier = hash +subjectAltName = @alt_names + +[alt_names] +DNS.1 = example.com +DNS.2 = www.example.com +``` + +Sign CSR with extensions from config: + +``` +wolfssl ca -config ca.conf -extensions v3_ca -in server.csr -out server-signed.pem -keyfile ca.priv -cert ca.pem -days 365 -md sha256 +``` + +### Limitations + +Without a configuration file, wolfCLU generates a random serial number for each signed certificate. See [Configuration File - Limitations](config.md#limitations) for details on config file-based serial number management and its current limitations. diff --git a/wolfCLU/src/command_list.md b/wolfCLU/src/command_list.md index e34b99b6..b1ac622a 100644 --- a/wolfCLU/src/command_list.md +++ b/wolfCLU/src/command_list.md @@ -1,26 +1,31 @@ -## List Of Commands: +## List Of Commands + - base64 - bench - ca - crl -- dsaparam - dgst +- dhparam +- dsaparam +- ecc - ecparam -- enc +- ed25519 +- enc / encrypt / decrypt - genkey - hash - md5 -- pkcs12 - pkcs7 - pkcs8 +- pkcs12 - pkey - rand - req - rsa - s_client -- verify -- x509 -- dhparam +- s_server - sha256 - sha384 - sha512 +- verify +- version +- x509 diff --git a/wolfCLU/src/config.md b/wolfCLU/src/config.md new file mode 100644 index 00000000..82f25c7b --- /dev/null +++ b/wolfCLU/src/config.md @@ -0,0 +1,285 @@ +### Configuration File Format + +wolfCLU supports OpenSSL-style configuration files for the `req` and `ca` commands. This page describes the supported directives. + +## Basic Structure + +Configuration files use INI-style format with sections and key-value pairs: + +```ini +[section_name] +key = value +``` + +## REQ Command Configuration + +### Main Section + +The `[req]` section contains the main configuration: + +| Directive | Description | +|-----------|-------------| +| `prompt` | Set to `no` to disable interactive prompting | +| `default_bits` | Default key size in bits (e.g., 2048) | +| `default_md` | Default hash algorithm (e.g., sha256) | +| `default_keyfile` | Default key file path | +| `distinguished_name` | Section name containing DN fields | +| `attributes` | Section name containing attributes | +| `x509_extensions` | Section name containing X509 extensions | + +### Distinguished Name Section + +The distinguished name section (referenced by `distinguished_name`) defines certificate subject fields: + +| Directive | Description | +|-----------|-------------| +| `countryName` | Country code (2 letters, e.g., US) | +| `stateOrProvinceName` | State or province name | +| `localityName` | City or locality name | +| `organizationName` | Organization name | +| `organizationalUnitName` | Organizational unit name | +| `commonName` or `CN` | Common name (e.g., domain name) | +| `emailAddress` | Email address | +| `name` | Name | +| `surname` | Surname | +| `givenName` | Given name | +| `initials` | Initials | +| `dnQualifier` | DN qualifier | + +Each field can have optional modifiers: + +| Modifier | Description | +|----------|-------------| +| `_default` | Default value if not provided | +| `_min` | Minimum length | +| `_max` | Maximum length | + +### Attributes Section + +The attributes section (referenced by `attributes`) defines PKCS#9 attributes: + +| Directive | Description | +|-----------|-------------| +| `challengePassword` | PKCS#9 challenge password | +| `unstructuredName` | PKCS#9 unstructured name | + +## X509 Extensions Section + +The extensions section (referenced by `x509_extensions`) defines certificate extensions: + +| Directive | Description | +|-----------|-------------| +| `basicConstraints` | CA constraint and path length | +| `subjectKeyIdentifier` | Subject key identifier | +| `authorityKeyIdentifier` | Authority key identifier | +| `keyUsage` | Key usage flags | +| `subjectAltName` | Subject alternative names | + +### basicConstraints + +Defines whether the certificate is a CA and the maximum path length. + +Format: `[critical, ]CA:TRUE|FALSE[, pathlen:]` + +| Value | Description | +|-------|-------------| +| `critical` | Mark as critical extension | +| `CA:TRUE` | This is a CA certificate | +| `CA:FALSE` | This is not a CA certificate | +| `pathlen:` | Maximum certification path length | + +Examples: +```ini +basicConstraints = critical, CA:TRUE, pathlen:0 +basicConstraints = CA:FALSE +``` + +### keyUsage + +Defines the purpose of the key contained in the certificate. + +Format: `[critical, ][, ...]` + +| Value | Description | +|-------|-------------| +| `digitalSignature` | Digital signature | +| `nonRepudiation` | Non-repudiation (also `contentCommitment`) | +| `keyEncipherment` | Key encipherment | +| `dataEncipherment` | Data encipherment | +| `keyAgreement` | Key agreement | +| `keyCertSign` | Certificate signing | +| `cRLSign` | CRL signing | +| `encipherOnly` | Encipher only (with keyAgreement) | +| `decipherOnly` | Decipher only (with keyAgreement) | + +Examples: +```ini +keyUsage = critical, digitalSignature, keyEncipherment +keyUsage = keyCertSign, cRLSign +``` + +### subjectKeyIdentifier + +Identifies the public key in the certificate. + +| Value | Description | +|-------|-------------| +| `hash` | Use hash of public key | + +Example: +```ini +subjectKeyIdentifier = hash +``` + +### subjectAltName + +Specifies additional identities for the certificate subject. Use `@section_name` to reference a section containing the alternative names. + +Example: +```ini +subjectAltName = @alt_names +``` + +#### Alternative Names Section + +| Directive | Description | +|-----------|-------------| +| `DNS.` | DNS name (e.g., `DNS.1 = example.com`) | +| `IP.` | IP address (e.g., `IP.1 = 192.168.1.1`) | +| `URI.` | URI (e.g., `URI.1 = https://example.com`) | +| `email.` | Email address (e.g., `email.1 = admin@example.com`) | +| `RID.` | Registered ID / OID | + +Example: +```ini +[alt_names] +DNS.1 = example.com +DNS.2 = www.example.com +IP.1 = 192.168.1.1 +email.1 = admin@example.com +``` + +## CA Command Configuration + +### Main Section + +The `[ca]` section specifies the default CA section: + +```ini +[ca] +default_ca = CA_default +``` + +### CA Section + +The CA section (e.g., `[CA_default]`) contains CA-specific settings: + +| Directive | Description | +|-----------|-------------| +| `serial` | File containing serial number (hex format) | +| `new_certs_dir` | Directory for new certificates | +| `certificate` | CA certificate file | +| `private_key` | CA private key file | +| `default_days` | Default validity period in days | +| `default_md` | Default hash algorithm | +| `x509_extensions` | Section name for extensions | +| `policy` | Section name for DN policy | +| `database` | Certificate database file | +| `unique_subject` | Require unique subjects | +| `crl_dir` | Directory for CRLs | +| `crl` | CRL file | +| `RANDFILE` | Random seed file | + +## Complete Examples + +### Server Certificate Request + +```ini +[req] +prompt = no +default_bits = 2048 +default_md = sha256 +distinguished_name = req_dn +x509_extensions = v3_server + +[req_dn] +countryName = US +stateOrProvinceName = Washington +localityName = Seattle +organizationName = wolfSSL +commonName = example.com +emailAddress = info@example.com + +[v3_server] +basicConstraints = critical, CA:FALSE +keyUsage = digitalSignature, keyEncipherment +subjectKeyIdentifier = hash +subjectAltName = @alt_names + +[alt_names] +DNS.1 = example.com +DNS.2 = www.example.com +IP.1 = 192.168.1.1 +``` + +Usage: +``` +wolfssl req -new -config server.conf -key server.priv -out server.csr +wolfssl req -new -x509 -config server.conf -key server.priv -out server.pem -days 365 +``` + +### CA Certificate + +```ini +[req] +prompt = no +default_bits = 4096 +default_md = sha256 +distinguished_name = ca_dn +x509_extensions = v3_ca + +[ca_dn] +countryName = US +stateOrProvinceName = Washington +localityName = Seattle +organizationName = wolfSSL +commonName = wolfSSL CA + +[v3_ca] +basicConstraints = critical, CA:TRUE, pathlen:1 +keyUsage = critical, keyCertSign, cRLSign +subjectKeyIdentifier = hash +``` + +Usage: +``` +wolfssl req -new -x509 -config ca.conf -key ca.priv -out ca.pem -days 3650 +``` + +### Simple CSR (Minimal) + +```ini +[req] +prompt = no +distinguished_name = req_dn + +[req_dn] +commonName = myserver +``` + +Usage: +``` +wolfssl req -new -config simple.conf -key server.priv -out server.csr +``` + +## Limitations + +### Serial Number File + +The `serial` directive specifies a file containing the serial number in hexadecimal format: + +``` +01 +``` + +**Note:** In the current version (v0.1.8), the configuration file-based serial number management has known issues with path handling. It is recommended to use command-line arguments directly until this is resolved. Without a configuration file, wolfCLU generates a random serial number for each signed certificate. diff --git a/wolfCLU/src/crl.md b/wolfCLU/src/crl.md index 175e8e25..aa7ea791 100644 --- a/wolfCLU/src/crl.md +++ b/wolfCLU/src/crl.md @@ -1,15 +1,20 @@ ### CRL Command Used to verify a CRL file given a CA, or to convert a CRL from one format [DER | PEM] to the other. The command will print out the CRL to stdout if -out is not specified and -noout is not used. Prints out "OK" on successful verification. -- [-CAfile] +Arguments: + +- [-CAfile] CA file name - [-inform] pem or der in format - [-in] the file to read from - [-outform] pem or der out format - [-out] output file to write to - [-noout] do not print output if set +- [-text] output human readable text of CRL Example: ``` wolfssl crl -CAfile ./certs/ca-cert.pem -in ./certs/crl.der -inform DER -noout + +wolfssl crl -in ./certs/crl.pem -text ``` diff --git a/wolfCLU/src/dgst.md b/wolfCLU/src/dgst.md index bbfba125..2bff5ce9 100644 --- a/wolfCLU/src/dgst.md +++ b/wolfCLU/src/dgst.md @@ -1,34 +1,33 @@ ### DGST Command -Can verify the signature. The last argument is the data that was signed. +Used for creating and verifying digital signatures. The last argument is the data that was signed. -Hash algos supported: +Hash algorithms supported: +- [-md5] - [-sha] - [-sha224] - [-sha256] - [-sha384] - [-sha512] -**Sign** +Arguments: -Parameters: +- [-signature] file containing the signature +- [-inform] pem or der in format +- [-verify] key used to verify the signature +- [-sign] private key used to create the signature +- [-out] output file for signature -- [-sign] key used to create signature -- [-out] file to write signature to +**Sign** Example: ``` -wolfssl dgst -sign keyPrivate.pem -out test.sig testfile +wolfssl dgst -sha256 -sign keyPrivate.pem -out test.sig testfile ``` **Verify** -Parameters: - -- [-verify] key used to verify the signature -- [-signature] file containing the signature - Example: ``` -wolfssl dgst -verify keyPublic.pem -signature test.sig testfile +wolfssl dgst -sha256 -signature test.sig -verify keyPublic.pem testfile ``` diff --git a/wolfCLU/src/ecparam.md b/wolfCLU/src/ecparam.md index 8af51fea..07b21ea1 100644 --- a/wolfCLU/src/ecparam.md +++ b/wolfCLU/src/ecparam.md @@ -2,15 +2,32 @@ Used for creating ECC keys. -Available arguments are: +Arguments: - [-genkey] create new key - [-out] output file -- [-name] curve name i.e. secp384r1 +- [-name] curve name +Available curve names: -Example: +- PRIME239V1 +- PRIME239V2 +- PRIME239V3 +- SECP256R1 +- SECP224R1 +- SECP384R1 +- SECP521R1 +- SECP256K1 +- BRAINPOOLP224R1 +- BRAINPOOLP256R1 +- BRAINPOOLP320R1 +- BRAINPOOLP384R1 +- BRAINPOOLP512R1 + +Example: ``` wolfssl ecparam -genkey -out new.key -name secp384r1 -``` \ No newline at end of file + +wolfssl ecparam -genkey -out brainpool.key -name BRAINPOOLP256R1 +``` diff --git a/wolfCLU/src/enc.md b/wolfCLU/src/enc.md index bbc3001a..e5d15768 100644 --- a/wolfCLU/src/enc.md +++ b/wolfCLU/src/enc.md @@ -2,7 +2,7 @@ Used for encrypting an input. Setting -d enables decryption. -Available encryption and decryption algorithms are: +Available encryption and decryption algorithms (depends on configure settings): - aes-cbc-128 - aes-cbc-192 @@ -13,26 +13,33 @@ Available encryption and decryption algorithms are: - 3des-cbc-56 - 3des-cbc-112 - 3des-cbc-168 +- camellia-cbc-128 +- camellia-cbc-192 +- camellia-cbc-256 -Available arguments are: +Arguments: - [-in] input file to read from - [-out] file to write to (default stdout) - [-pwd] password input +- [-k] another option for password input +- [-pass] option for password source, e.g., pass:password - [-key] hex key input -- [-iv] hex iv input +- [-iv] hex iv input - [-inkey] input file for key - [-pbkdf2] use kdf version 2 -- [-md] specify hash algo to use i.e md5, sha256 +- [-md] specify hash algo to use, e.g., md5, sha256 - [-d] decrypt the input file - [-p] display debug information (key / iv ...) -- [-k] another option for password input - [-base64] handle decoding a base64 input - [-nosalt] do not use a salt input to kdf - -Example: +Example: ``` wolfssl enc -aes-128-cbc -k Thi$i$myPa$$w0rd -in somefile.txt + +wolfssl enc aes-cbc-256 -pwd Thi$i$myPa$$w0rd -in somefile.txt -out encryptedfile.txt + +wolfssl enc aes-cbc-256 -d -pwd Thi$i$myPa$$w0rd -in encryptedfile.txt -out decryptedfile.txt ``` diff --git a/wolfCLU/src/genkey.md b/wolfCLU/src/genkey.md index 7fc50672..87de5089 100644 --- a/wolfCLU/src/genkey.md +++ b/wolfCLU/src/genkey.md @@ -1,18 +1,47 @@ ### GENKEY Command -Used to generate RSA, ECC, ED25519 and DSA keys. If using "-output KEY" a private key is created having .priv appended to -out argument and a public key is created with .pub appended to the -out argument. If generating ED25519 keys compile wolfSSL with --enable-ed25519. +Used to generate RSA, ECC and ED25519 keys. If using "-output KEYPAIR" a private key is created having .priv appended to -out argument and a public key is created with .pub appended to the -out argument. If generating ED25519 keys compile wolfSSL with --enable-ed25519. -Available arguments are: +Available key types (depends on configure settings): + +- rsa +- ecc +- ed25519 + +Arguments: -- [-out] file to write to - [rsa | ecc | ed25519] key type to generate -- [-inkey] input file for key -- [-size] size of key to generate +- [-size] size of key to generate (bits) +- [-out] file to write to - [-outform] output form, either DER or PEM (defaults to DER) -- [-output] key to generate, either PUB, PRIV or KEYPAIR (defaults to KEYPAIR) -- [-exponent] RSA exponent size +- [-output] key to generate, either PUB, PRIV or KEYPAIR (defaults to KEYPAIR) Example: ``` -wolfssl genkey rsa -size 2048 -out mykey -outform pem -output KEYPAIR +wolfssl genkey rsa -size 2048 -out mykey -outform pem -output KEYPAIR + +wolfssl genkey ecc -out ecckey -outform pem -output KEYPAIR + +wolfssl genkey ed25519 -out ed25519key -outform pem -output KEYPAIR +``` + +The above command would output the files: mykey.priv and mykey.pub. +Changing the -output option to just PRIV would output only the private key. + +### Typical Workflow: RSA Key to Certificate + +**Step 1: Generate RSA key pair for server** + +``` +wolfssl genkey rsa -size 2048 -out server -outform pem -output KEYPAIR ``` + +This creates `server.priv` (private key) and `server.pub` (public key). + +**Step 2: Generate RSA key pair for CA** + +``` +wolfssl genkey rsa -size 2048 -out ca -outform pem -output KEYPAIR +``` + +See the [REQ Command](req.md) for creating CSR and certificates, and the [CA Command](ca.md) for signing certificates. diff --git a/wolfCLU/src/hash.md b/wolfCLU/src/hash.md index ce88a166..a1dcc95c 100644 --- a/wolfCLU/src/hash.md +++ b/wolfCLU/src/hash.md @@ -1,19 +1,26 @@ ### HASH Command Used to create a hash of input data. -Algorithms: +Available algorithms (depends on configure settings): - md5 - sha - sha256 - sha384 - sha512 +- blake2b - base64enc - base64dec +Arguments: -Example: +- [algorithm] hash algorithm to use +- [-in] file to hash +Example: + +``` +wolfssl hash sha256 -in somefile.txt + +wolfssl hash blake2b -in somefile.txt ``` -wolfssl -hash sha -in -``` \ No newline at end of file diff --git a/wolfCLU/src/pkey.md b/wolfCLU/src/pkey.md index 0a1c1cda..6cdb9414 100644 --- a/wolfCLU/src/pkey.md +++ b/wolfCLU/src/pkey.md @@ -1,13 +1,19 @@ ### PKEY Command Used for dealing with generic key operations. Prints the key read in to stdout. -- [-in] file input for key +Arguments: + +- [-in] file input for key to read +- [-out] file to output to (default stdout) - [-inform] pem or der input format (defaults to pem) -- [-pubout] only print out the public key -- [-pubin] expect to public key as input +- [-outform] pem or der output format +- [-pubout] output the public key +- [-pubin] expect to read public key in Example: ``` -./wolfssl pkey -in ./certs/server-key.pem -inform pem -pubout +wolfssl pkey -in ./certs/server-key.pem -inform pem -pubout + +wolfssl pkey -in ./certs/server-key.pem -out pubkey.pem -pubout ``` diff --git a/wolfCLU/src/rand.md b/wolfCLU/src/rand.md index 1d86fbc9..e0899667 100644 --- a/wolfCLU/src/rand.md +++ b/wolfCLU/src/rand.md @@ -2,7 +2,7 @@ Generates random bytes in raw or base64 form. By default it outputs the result to stdout but can be redirected with the '-out' argument. The last argument passed in is the number of random bytes to generate. - [-base64] base64 encode the resulting random bytes -- [-out] ouput file to write results to +- [-out] output file to write results to Example: diff --git a/wolfCLU/src/req.md b/wolfCLU/src/req.md index 1a57ccde..722a6104 100644 --- a/wolfCLU/src/req.md +++ b/wolfCLU/src/req.md @@ -1,16 +1,27 @@ ### REQ Command Used for creating a certificate request or a self-signed certificate. Can handle some basic parsing of a .conf file for certificate setup. If no configuration file is used then stdin is prompted for certificate information. -Available arguments are: +See [Configuration File](config.md) for details on the config file directives. + +Arguments: - [-in] input file to read from - [-out] file to write to (default stdout) - [-key] public key to put into certificate request -- [-inform] der or pem format for '-in' (defaults to pem) +- [-inform] der or pem format for '-in' (defaults to pem) - [-outform] der or pem format for '-out' (defaults to pem) - [-config] file to parse for certificate configuration - [-days] number of days should be valid for - [-x509] generate self signed certificate +- [-extensions] overwrite the section to get extensions from +- [-nodes] no DES encryption on private key output +- [-newkey] generate the private key to use with req +- [-inkey] private key to use with req +- [-keyout] file to output key to +- [-subj] use a specified subject name, e.g., O=wolfSSL/C=US/ST=WA/L=Seattle/CN=wolfSSL/OU=org-unit +- [-verify] check the signature on the req +- [-text] output human readable text of req +- [-noout] do not print out the generated results Example: @@ -18,4 +29,48 @@ Example: wolfssl ecparam -genkey -out ecc.key -name secp384r1 wolfssl req -new -x509 -days 3650 -config selfsigned.conf -key ecc.key -out ecc.cert -outform der -sha256 + +wolfssl req -newkey rsa:2048 -keyout mykey.pem -out myreq.csr -subj "O=wolfSSL/C=US/CN=test" +``` + +### Typical Workflow: RSA Key to Certificate + +**Step 1: Generate RSA key pair** (see [GENKEY Command](genkey.md)) + +``` +wolfssl genkey rsa -size 2048 -out server -outform pem -output KEYPAIR +``` + +**Step 2: Create CSR from private key** + +``` +wolfssl req -new -key server.priv -out server.csr -subj "/C=US/ST=Washington/L=Seattle/O=wolfSSL/CN=example.com" +``` + +**Step 3a: Create self-signed certificate** + +``` +wolfssl req -x509 -key server.priv -in server.csr -out server.pem -days 365 ``` + +**Step 3b: Or create CA-signed certificate** (see [CA Command](ca.md)) + +First, create a CA certificate: + +``` +wolfssl genkey rsa -size 2048 -out ca -outform pem -output KEYPAIR +wolfssl req -new -x509 -key ca.priv -out ca.pem -days 3650 -subj "/C=US/ST=Washington/L=Seattle/O=wolfSSL/CN=wolfSSL CA" +``` + +Then sign the server CSR with the CA: + +``` +wolfssl ca -in server.csr -out server-signed.pem -keyfile ca.priv -cert ca.pem -days 365 -md sha256 +``` + +**Step 4: Verify the certificate** (see [VERIFY Command](verify.md)) + +``` +wolfssl verify -CAfile ca.pem server-signed.pem +``` + diff --git a/wolfCLU/src/rsa.md b/wolfCLU/src/rsa.md index d9f9c130..5c4c4aaf 100644 --- a/wolfCLU/src/rsa.md +++ b/wolfCLU/src/rsa.md @@ -1,12 +1,44 @@ ### RSA Command -Does RSA operations. Including reading in RSA keys, outputing RSA keys or modulus, and reading encrypted PEM files. Can handle both DER and PEM format for input and output. The following is a list of options +Performs RSA operations including signing, verification, and key management. Can handle both DER and PEM format for input and output. -- [-in] file input for key to read -- [-inform] PEM or DER input format (defaults to PEM) +**RSA Sign** + +``` +wolfssl rsa -sign -inkey -in -out +``` + +**RSA Verify with Private Key** + +``` +wolfssl rsa -verify -inkey -sigfile -out +``` + +**RSA Verify with Public Key** + +``` +wolfssl rsa -verify -inkey -sigfile -out -pubin +``` + +Arguments: + +- [-sign] sign the input data +- [-verify] verify the signature +- [-inkey] key file for signing/verification +- [-in] input file to sign or process - [-out] file to write result to (defaults to stdout) +- [-sigfile] signature file for verification +- [-pubin] expect a public key input +- [-inform] PEM or DER input format (defaults to PEM) - [-outform] PEM or DER output format (defaults to PEM) - [-passin] password for PEM encrypted files - [-noout] do not print the key out when set - [-modulus] print out the RSA modulus (n value) -- [-RSAPublicKey_in] expecting a public key input + +Example: + +``` +wolfssl rsa -sign -inkey private.pem -in data.txt -out signature.bin + +wolfssl rsa -verify -inkey public.pem -sigfile signature.bin -out verified.txt -pubin +``` diff --git a/wolfCLU/src/s_client.md b/wolfCLU/src/s_client.md index a9f5f924..67ccc089 100644 --- a/wolfCLU/src/s_client.md +++ b/wolfCLU/src/s_client.md @@ -1,13 +1,26 @@ ### S_CLIENT Command -Very basic TLS connection supported. Currently does not verify the peer, -CAfile option is not yet completed. +Basic TLS client for testing connections. Arguments: -- [-connect] : +- [-connect] `:` or `<[ipv6]>:` +- [-starttls] protocol for STARTTLS (e.g., smtp) +- [-CAfile] CA file name for verification +- [-verify_return_error] close connection on verification error +- [-disable_stdin_check] disable stdin check +IPv6 Examples: -Example : +- `-connect '[::1]:11111'` +- `-connect '[fe80::63:57c0:9b88:77ca%en0]:11111'` +- `-connect '[2001:4860:4860::8888]:443'` + +Example: ``` wolfssl s_client -connect 127.0.0.1:11111 -``` \ No newline at end of file + +wolfssl s_client -connect example.com:443 -CAfile ./certs/ca-cert.pem + +wolfssl s_client -connect '[::1]:11111' +``` diff --git a/wolfCLU/src/verify.md b/wolfCLU/src/verify.md index a6da2f9a..d3f74529 100644 --- a/wolfCLU/src/verify.md +++ b/wolfCLU/src/verify.md @@ -1,12 +1,33 @@ ### VERIFY Command Verifies an X509 certificate given a CA. The last argument passed into the command is the certificate file name to be verified. If the verification is successful then "OK" will be printed out to stdout. Otherwise an error value and reason will be printed out. +Arguments: + - [-CAfile] file name for CA to be used with verify -- [-crl_check] if CRL checking should be used - [-untrusted] file name for intermediate certificate to be used in verification (only one -untrusted cert is currently supported) +- [-crl_check] if CRL checking should be used +- [-partial_chain] allow verification with intermediate CA Example: ``` wolfssl verify -CAfile ./certs/ca-cert.pem ./certs/server-cert.pem + +wolfssl verify -CAfile ./certs/ca-cert.pem -untrusted ./certs/intermediate.pem ./certs/server-cert.pem +``` + +### Typical Workflow: Verify CA-Signed Certificate + +After creating a CA-signed certificate (see [CA Command](ca.md)), verify it: + +``` +wolfssl verify -CAfile ca.pem server-signed.pem +``` + +Expected output on success: + +``` +verifying certificate file server-signed.pem +using CA file ca.pem +OK ``` diff --git a/wolfCLU/src/x509.md b/wolfCLU/src/x509.md index 253b013a..263334d6 100644 --- a/wolfCLU/src/x509.md +++ b/wolfCLU/src/x509.md @@ -1,17 +1,48 @@ -### X509 Commnad +### X509 Command This command is used for parsing and printing out certificates. -Arguments: +Arguments: - [-in] X509 file input - [-inform] pem or der format for input (defaults to pem) - [-out] file to output to - [-outform] pem or der format for output (defaults to pem) -- [-pubkey] print out the public key only -- [-text] print out the certificate +- [-req] input file is a CSR file +- [-signkey] a key for signing +- [-*] supported digests for signing (e.g., -sha256) +- [-extfile] config file +- [-extensions] section of the config file to use +- [-noout] no output +- [-subject] print out the subject name +- [-issuer] print out the issuer name +- [-serial] print out the serial number in hex +- [-dates] print out the valid dates of cert +- [-email] print out the subject name's email address +- [-fingerprint] print out the hash of the certificate in DER form +- [-purpose] print out the certificate's purpose +- [-hash] print out the hash of the certificate subject name +- [-text] print human readable text of X509 +- [-modulus] print out the RSA key modulus +- [-pubkey] print out the public key Example: ``` wolfssl x509 -in ./certs/server-cert.pem -text + +wolfssl x509 -inform pem -in certs/ca-cert.pem -outform der -out certs/ca-cert-converted.der +``` + +### Typical Workflow: View Certificate Details + +After creating a certificate (see [REQ Command](req.md) or [CA Command](ca.md)), view its details: + +``` +wolfssl x509 -in server.pem -text -noout +``` + +View specific information: + +``` +wolfssl x509 -in server.pem -subject -issuer -dates -noout ```