Skip to content

Commit ea6967a

Browse files
kojo1claude
kojo1
and
claude
committed
Add configuration file documentation as Appendix
- Create config.md with detailed configuration file format documentation - Move config documentation from req.md to dedicated page - Add Appendix section to navigation (EN/JA) - Update req.md and ca.md to reference config.md Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent c0d5b6a commit ea6967a

5 files changed

Lines changed: 292 additions & 143 deletions

File tree

‎wolfCLU/mkdocs-ja.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,8 @@ nav:
3131
- "VERIFY コマンド": verify.md
3232
- "X509 コマンド": x509.md
3333
- "BASE64 コマンド": base64.md
34+
- "付録":
35+
- "設定ファイル": config.md
3436
theme:
3537
name: null
3638
custom_dir: ../mkdocs-material/material

‎wolfCLU/mkdocs.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,8 @@ nav:
3131
- "VERIFY Command": verify.md
3232
- "X509 Command": x509.md
3333
- "BASE64 Command": base64.md
34+
- "Appendix":
35+
- "Configuration File Format": config.md
3436
theme:
3537
name: null
3638
custom_dir: ../mkdocs-material/material

‎wolfCLU/src/ca.md‎

Lines changed: 2 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
### CA Command
22
Used for signing Certificates. Can handle some basic config file parsing.
33

4-
See [REQ Command - Configuration File Format](req.md#configuration-file-format) for details on config file directives.
4+
See [Configuration File](config.md) for details on config file directives.
55

66
Arguments:
77

@@ -79,21 +79,4 @@ wolfssl ca -config ca.conf -extensions v3_ca -in server.csr -out server-signed.p
7979

8080
### Limitations
8181

82-
#### Serial Number
83-
84-
Without a configuration file, wolfCLU generates a random serial number for each signed certificate.
85-
86-
The configuration file supports the following directives for serial number management:
87-
88-
```ini
89-
[CA_default]
90-
serial = /path/to/serial.txt # File containing serial number in hex
91-
new_certs_dir = /path/to/certs # Output directory for certificates
92-
```
93-
94-
The serial file format (OpenSSL compatible):
95-
```
96-
01
97-
```
98-
99-
**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 the command-line arguments (`-out`, `-keyfile`, `-cert`) directly instead of relying on config file paths until this is resolved.
82+
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.

‎wolfCLU/src/config.md‎

Lines changed: 285 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,285 @@
1+
### Configuration File Format
2+
3+
wolfCLU supports OpenSSL-style configuration files for the `req` and `ca` commands. This page describes the supported directives.
4+
5+
## Basic Structure
6+
7+
Configuration files use INI-style format with sections and key-value pairs:
8+
9+
```ini
10+
[section_name]
11+
key = value
12+
```
13+
14+
## REQ Command Configuration
15+
16+
### Main Section
17+
18+
The `[req]` section contains the main configuration:
19+
20+
| Directive | Description |
21+
|-----------|-------------|
22+
| `prompt` | Set to `no` to disable interactive prompting |
23+
| `default_bits` | Default key size in bits (e.g., 2048) |
24+
| `default_md` | Default hash algorithm (e.g., sha256) |
25+
| `default_keyfile` | Default key file path |
26+
| `distinguished_name` | Section name containing DN fields |
27+
| `attributes` | Section name containing attributes |
28+
| `x509_extensions` | Section name containing X509 extensions |
29+
30+
### Distinguished Name Section
31+
32+
The distinguished name section (referenced by `distinguished_name`) defines certificate subject fields:
33+
34+
| Directive | Description |
35+
|-----------|-------------|
36+
| `countryName` | Country code (2 letters, e.g., US) |
37+
| `stateOrProvinceName` | State or province name |
38+
| `localityName` | City or locality name |
39+
| `organizationName` | Organization name |
40+
| `organizationalUnitName` | Organizational unit name |
41+
| `commonName` or `CN` | Common name (e.g., domain name) |
42+
| `emailAddress` | Email address |
43+
| `name` | Name |
44+
| `surname` | Surname |
45+
| `givenName` | Given name |
46+
| `initials` | Initials |
47+
| `dnQualifier` | DN qualifier |
48+
49+
Each field can have optional modifiers:
50+
51+
| Modifier | Description |
52+
|----------|-------------|
53+
| `<field>_default` | Default value if not provided |
54+
| `<field>_min` | Minimum length |
55+
| `<field>_max` | Maximum length |
56+
57+
### Attributes Section
58+
59+
The attributes section (referenced by `attributes`) defines PKCS#9 attributes:
60+
61+
| Directive | Description |
62+
|-----------|-------------|
63+
| `challengePassword` | PKCS#9 challenge password |
64+
| `unstructuredName` | PKCS#9 unstructured name |
65+
66+
## X509 Extensions Section
67+
68+
The extensions section (referenced by `x509_extensions`) defines certificate extensions:
69+
70+
| Directive | Description |
71+
|-----------|-------------|
72+
| `basicConstraints` | CA constraint and path length |
73+
| `subjectKeyIdentifier` | Subject key identifier |
74+
| `authorityKeyIdentifier` | Authority key identifier |
75+
| `keyUsage` | Key usage flags |
76+
| `subjectAltName` | Subject alternative names |
77+
78+
### basicConstraints
79+
80+
Defines whether the certificate is a CA and the maximum path length.
81+
82+
Format: `[critical, ]CA:TRUE|FALSE[, pathlen:<n>]`
83+
84+
| Value | Description |
85+
|-------|-------------|
86+
| `critical` | Mark as critical extension |
87+
| `CA:TRUE` | This is a CA certificate |
88+
| `CA:FALSE` | This is not a CA certificate |
89+
| `pathlen:<n>` | Maximum certification path length |
90+
91+
Examples:
92+
```ini
93+
basicConstraints = critical, CA:TRUE, pathlen:0
94+
basicConstraints = CA:FALSE
95+
```
96+
97+
### keyUsage
98+
99+
Defines the purpose of the key contained in the certificate.
100+
101+
Format: `[critical, ]<usage>[, <usage>...]`
102+
103+
| Value | Description |
104+
|-------|-------------|
105+
| `digitalSignature` | Digital signature |
106+
| `nonRepudiation` | Non-repudiation (also `contentCommitment`) |
107+
| `keyEncipherment` | Key encipherment |
108+
| `dataEncipherment` | Data encipherment |
109+
| `keyAgreement` | Key agreement |
110+
| `keyCertSign` | Certificate signing |
111+
| `cRLSign` | CRL signing |
112+
| `encipherOnly` | Encipher only (with keyAgreement) |
113+
| `decipherOnly` | Decipher only (with keyAgreement) |
114+
115+
Examples:
116+
```ini
117+
keyUsage = critical, digitalSignature, keyEncipherment
118+
keyUsage = keyCertSign, cRLSign
119+
```
120+
121+
### subjectKeyIdentifier
122+
123+
Identifies the public key in the certificate.
124+
125+
| Value | Description |
126+
|-------|-------------|
127+
| `hash` | Use hash of public key |
128+
129+
Example:
130+
```ini
131+
subjectKeyIdentifier = hash
132+
```
133+
134+
### subjectAltName
135+
136+
Specifies additional identities for the certificate subject. Use `@section_name` to reference a section containing the alternative names.
137+
138+
Example:
139+
```ini
140+
subjectAltName = @alt_names
141+
```
142+
143+
#### Alternative Names Section
144+
145+
| Directive | Description |
146+
|-----------|-------------|
147+
| `DNS.<n>` | DNS name (e.g., `DNS.1 = example.com`) |
148+
| `IP.<n>` | IP address (e.g., `IP.1 = 192.168.1.1`) |
149+
| `URI.<n>` | URI (e.g., `URI.1 = https://example.com`) |
150+
| `email.<n>` | Email address (e.g., `email.1 = admin@example.com`) |
151+
| `RID.<n>` | Registered ID / OID |
152+
153+
Example:
154+
```ini
155+
[alt_names]
156+
DNS.1 = example.com
157+
DNS.2 = www.example.com
158+
IP.1 = 192.168.1.1
159+
email.1 = admin@example.com
160+
```
161+
162+
## CA Command Configuration
163+
164+
### Main Section
165+
166+
The `[ca]` section specifies the default CA section:
167+
168+
```ini
169+
[ca]
170+
default_ca = CA_default
171+
```
172+
173+
### CA Section
174+
175+
The CA section (e.g., `[CA_default]`) contains CA-specific settings:
176+
177+
| Directive | Description |
178+
|-----------|-------------|
179+
| `serial` | File containing serial number (hex format) |
180+
| `new_certs_dir` | Directory for new certificates |
181+
| `certificate` | CA certificate file |
182+
| `private_key` | CA private key file |
183+
| `default_days` | Default validity period in days |
184+
| `default_md` | Default hash algorithm |
185+
| `x509_extensions` | Section name for extensions |
186+
| `policy` | Section name for DN policy |
187+
| `database` | Certificate database file |
188+
| `unique_subject` | Require unique subjects |
189+
| `crl_dir` | Directory for CRLs |
190+
| `crl` | CRL file |
191+
| `RANDFILE` | Random seed file |
192+
193+
## Complete Examples
194+
195+
### Server Certificate Request
196+
197+
```ini
198+
[req]
199+
prompt = no
200+
default_bits = 2048
201+
default_md = sha256
202+
distinguished_name = req_dn
203+
x509_extensions = v3_server
204+
205+
[req_dn]
206+
countryName = US
207+
stateOrProvinceName = Washington
208+
localityName = Seattle
209+
organizationName = wolfSSL
210+
commonName = example.com
211+
emailAddress = info@example.com
212+
213+
[v3_server]
214+
basicConstraints = critical, CA:FALSE
215+
keyUsage = digitalSignature, keyEncipherment
216+
subjectKeyIdentifier = hash
217+
subjectAltName = @alt_names
218+
219+
[alt_names]
220+
DNS.1 = example.com
221+
DNS.2 = www.example.com
222+
IP.1 = 192.168.1.1
223+
```
224+
225+
Usage:
226+
```
227+
wolfssl req -new -config server.conf -key server.priv -out server.csr
228+
wolfssl req -new -x509 -config server.conf -key server.priv -out server.pem -days 365
229+
```
230+
231+
### CA Certificate
232+
233+
```ini
234+
[req]
235+
prompt = no
236+
default_bits = 4096
237+
default_md = sha256
238+
distinguished_name = ca_dn
239+
x509_extensions = v3_ca
240+
241+
[ca_dn]
242+
countryName = US
243+
stateOrProvinceName = Washington
244+
localityName = Seattle
245+
organizationName = wolfSSL
246+
commonName = wolfSSL CA
247+
248+
[v3_ca]
249+
basicConstraints = critical, CA:TRUE, pathlen:1
250+
keyUsage = critical, keyCertSign, cRLSign
251+
subjectKeyIdentifier = hash
252+
```
253+
254+
Usage:
255+
```
256+
wolfssl req -new -x509 -config ca.conf -key ca.priv -out ca.pem -days 3650
257+
```
258+
259+
### Simple CSR (Minimal)
260+
261+
```ini
262+
[req]
263+
prompt = no
264+
distinguished_name = req_dn
265+
266+
[req_dn]
267+
commonName = myserver
268+
```
269+
270+
Usage:
271+
```
272+
wolfssl req -new -config simple.conf -key server.priv -out server.csr
273+
```
274+
275+
## Limitations
276+
277+
### Serial Number File
278+
279+
The `serial` directive specifies a file containing the serial number in hexadecimal format:
280+
281+
```
282+
01
283+
```
284+
285+
**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.

0 commit comments

Comments
 (0)