Skip to content

Commit e05e7d4

Browse files
committed
Improve PKCS#11 and CNG usage instructions in README
1 parent 842bd94 commit e05e7d4

File tree

1 file changed

+33
-16
lines changed

1 file changed

+33
-16
lines changed

README.md

Lines changed: 33 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -133,8 +133,9 @@ To sign a CAB file containing Java class files:
133133
```
134134
Only the 'low' parameter is currently supported.
135135

136-
If you want to use a PKCS#11 token, you should specify the PKCS#11 engine and module.
137-
An example of using osslsigncode with SoftHSM:
136+
### Using the PKCS#11 Engine with osslsigncode
137+
If you want to use a PKCS#11 token, specify the PKCS#11 engine and module.
138+
Example usage with SoftHSM:
138139
```
139140
osslsigncode sign \
140141
-engine /usr/lib64/engines-1.1/pkcs11.so \
@@ -144,8 +145,10 @@ An example of using osslsigncode with SoftHSM:
144145
-in yourapp.exe -out yourapp-signed.exe
145146
```
146147

147-
Since OpenSSL 3.0, you can use a PKCS#11 token with the PKCS#11 provider.
148-
An example of using osslsigncode with OpenSC:
148+
### Using the PKCS#11 Provider with osslsigncode (OpenSSL 3.x only)
149+
OpenSSL 3.0 introduced a new provider-based architecture. To use a PKCS#11 token
150+
with `osslsigncode`, specify the PKCS#11 provider and module.
151+
Example usage with OpenSC:
149152
```
150153
osslsigncode sign \
151154
-provider /usr/lib64/ossl-modules/pkcs11prov.so \
@@ -155,26 +158,40 @@ An example of using osslsigncode with OpenSC:
155158
-in yourapp.exe -out yourapp-signed.exe
156159
```
157160

158-
You can use a certificate and key stored in the Windows Certificate Store with
159-
the CNG engine version 1.1 or later. For more information, refer to
161+
### Using the CNG Engine with osslsigncode (Windows only)
162+
The CNG engine allows using certificates and keys stored in the Windows
163+
Certificate Store. It requires CNG engine version 1.1 or later. For more
164+
information, refer to
160165

161166
https://www.stunnel.org/cng-engine.html
162167

163168
A non-commercial edition of CNG engine is available for testing, personal,
164169
educational, or research purposes.
165170

166-
To use the CNG engine with osslsigncode, ensure that the `cng.dll` library is
167-
placed in the same directory as the `osslsigncode.exe` executable.
171+
To ensure `osslsigncode` can locate and load the CNG engine module (`cng.dll`)
172+
even when it is not installed in the default system engine directory, you can:
168173

169-
Below is an example of how to use osslsigncode with the CNG engine:
174+
- Specify the full or relative path to `cng.dll`:
170175
```
171-
osslsigncode sign \
172-
-engine cng \
173-
-pkcs11cert osslsigncode_cert \
174-
-key osslsigncode_cert \
175-
-engineCtrl store_flags:0 \
176-
-engineCtrl store_name:MY \
177-
-engineCtrl PIN:yourpass \
176+
osslsigncode sign -engine C:\my\engines\cng.dll ...
177+
```
178+
- Or set the `OPENSSL_ENGINES` environment variable to the directory containing
179+
`cng.dll`, and refer to the engine by its ID:
180+
```
181+
set OPENSSL_ENGINES=C:\my\engines
182+
osslsigncode sign -engine cng ...
183+
```
184+
185+
Below is an example of how to use `osslsigncode` with the CNG engine on Windows:
186+
```
187+
set OPENSSL_ENGINES=C:\my\engines
188+
osslsigncode sign ^
189+
-engine cng ^
190+
-pkcs11cert osslsigncode_cert ^
191+
-key osslsigncode_cert ^
192+
-engineCtrl store_flags:0 ^
193+
-engineCtrl store_name:MY ^
194+
-engineCtrl PIN:yourpass ^
178195
-in yourapp.exe -out yourapp-signed.exe
179196
```
180197

0 commit comments

Comments
 (0)