pkcs11-tools is a toolkit containing a bunch of small utilities to perform key management tasks on cryptographic tokens
implementing a PKCS#11 interface. It features a number of commands similar to the unix CLI utilities, such as ls
, mv
, rm
, od
, and more
. It also has specific commands to generate keys, generate CSRs, import certificates and
other files, in a fashion compatible with most implementations, including both IBM and Oracle JVMs. It is also able to
interface with NSS libraries from mozilla.org.
Some features:
- support for DES, 3DES, AES, HMAC, RSA, DSA, DH, Elliptic curves (NIST curves, Edwards curves)
- generation of PKCS#10 (CSR) and self-signed certificates
- import of certificates, public keys, data files
- support for wrapping and unwrapping keys, for both symmetric and asymmetric keys
- support for templates during key creation, public key import, key wrapping and key unwrapping
- support for session key generation and direct wrapping under one or several keys, in a single command
- support for key rewrapping (i.e. key unwrapping and key wrapping)
Version 2.6 brings support for the AWS CloudHSM platform, library version 5.9. Limitations are:
- Certificates are not supported by the platform, therefore any command handling certificates will fail
- Changing attributes values is not supported by the platform; several commands rely on that capability to adjust
CKA_ID
accross objects. These commands may occasionally report an error when executed; key material is usually created. - For the same reason,
p11mv
andp11setattr
will not operate on this platform. - The platform does not allow for duplicate
CKA_ID
attributes, which occasionally brings issues when generating key material. This will be adjusted in a later release. p11od
command will not work, due to the way CloudHSM handles attributes.- When using wrapped key files,
CKA_SIGN_RECOVER
andCKA_VERIFY_RECOVER
are not supported, and should be commented out. - Wrap and unwrap templates are not supported by this platform. These should also be commented out in wrapped key files. AWS CloudHSM support is disabled by default; please refer to installation instructions for more details.
Version 2.6, introduces support for JWK - JOSE Web Key output (RFC 7517) on the p11keygen
, p11wrap
, and p11rewrap
commands. The JWK format is not supported for importing keys.
Version 2.5, that brings support for CKA_ALLOWED_MECHANISMS
, on many key management commands: p11keygen
, p11wrap
, p11unwrap
, p11rewrap
, p11od
, p11ls
. Note that the wrapped key grammar has changed; the grammar version number
has been incremented to 2.2
.
Version 2.4, to support templates in many commands: p11keygen
, p11importpubk
, p11wrap
, p11unwrap
, p11od
, p11ls
. Keys created with a template can be wrapped, the template attributes will be carried. Note that the wrapped
key grammar has changed, and the grammar version number has been incremented to 2.1
.
Version 2.3, that adds extra options to p11kcv, so that tokens not supporting NULL-length HMAC computation can be also supported.
Version 2.2 is slightly changing the layout of p11slotinfo
. Edwards Curve support enhanced. The toolkit is also
adapted to be packaged as a FreeBSD port.
Version 2.1 brings support for Edwards Curve.
The toolkit has reached v2.0. It features several major changes:
- it supports (and requires) OpenSSL v1.1.1+
- signing commands (
p11mkcert
,p11req
andmasqreq
) implement OpenSSL algorithm methods. This will enable supporting more algorithms in the future. - major overhaul of the wrapping/unwrapping system: it is now possible to perform double wrapping (aka envelope wrapping) with a single command, in a secure fashion
p11keygen
can now generate a session key and wrap it under one or several wrapping keys- a new command,
p11rewrap
, allows to unwrap a key and immediately rewrap in under one or several wrapping keys, in a secure fashion.
Ensure the prerequisites listed in the Install Document are installed before proceeding
To build the source code, simply execute (with appropriate privileges)
$ ./bootstrap.sh
$ ./configure
$ make install
To list the methods available on a PKCS#11 token, use p11slotinfo
, that will return the list of available mechanisms,
together with allowed APIs.
$ using PKCS11LIB at /opt/softhsm2-devel/lib/softhsm/libsofthsm2.so
PKCS#11 Library
---------------
Name : /opt/softhsm2-devel/lib/softhsm/libsofthsm2.so
Lib version : 2.6
API version : 2.40
Description : Implementation of PKCS11
Manufacturer: SoftHSM
PKCS#11 module slot list:
Slot index: 0
----------------
Description : SoftHSM slot ID 0x4fbfdc13
Token Label : token1
Manufacturer: SoftHSM project
Enter slot index: 0
Slot[0]
-------------
Slot Number : 1337973779
Description : SoftHSM slot ID 0x4fbfdc13
Manufacturer: SoftHSM project
Slot Flags : [ CKF_TOKEN_PRESENT ]
Token
-------------
Label : first token
Manufacturer: SoftHSM project
Token Flags : [ CKF_RNG CKF_LOGIN_REQUIRED CKF_USER_PIN_INITIALIZED CKF_RESTORE_KEY_NOT_NEEDED CKF_TOKEN_INITIALIZED ]
Mechanisms:
-----------
CKM_MD5 --- --- hsh --- --- --- --- --- --- --- --- --- SW (00000210)
CKM_SHA_1 --- --- hsh --- --- --- --- --- --- --- --- --- SW (00000220)
CKM_SHA224 --- --- hsh --- --- --- --- --- --- --- --- --- SW (00000255)
CKM_SHA256 --- --- hsh --- --- --- --- --- --- --- --- --- SW (00000250)
CKM_SHA384 --- --- hsh --- --- --- --- --- --- --- --- --- SW (00000260)
CKM_SHA512 --- --- hsh --- --- --- --- --- --- --- --- --- SW (00000270)
CKM_MD5_HMAC --- --- --- sig --- vfy --- --- --- --- --- --- SW (00000211)
CKM_SHA_1_HMAC --- --- --- sig --- vfy --- --- --- --- --- --- SW (00000221)
CKM_SHA224_HMAC --- --- --- sig --- vfy --- --- --- --- --- --- SW (00000256)
CKM_SHA256_HMAC --- --- --- sig --- vfy --- --- --- --- --- --- SW (00000251)
CKM_SHA384_HMAC --- --- --- sig --- vfy --- --- --- --- --- --- SW (00000261)
CKM_SHA512_HMAC --- --- --- sig --- vfy --- --- --- --- --- --- SW (00000271)
CKM_RSA_PKCS_KEY_PAIR_GEN --- --- --- --- --- --- --- --- gkp --- --- --- SW (00000000)
CKM_RSA_PKCS enc dec --- sig --- vfy --- --- --- wra unw --- SW (00000001)
...
To list the objects sitting on the token at slot with index 0, use p11ls
. objects are listed together with their
attributes;
$ p11ls -l /usr/local/opt/softhsm/lib/softhsm/libsofthsm2.so -s 0
Enter passphrase for token: ******
seck/des-double tok,prv,r/w,loc,enc,dec,sen,ase,nxt,des(128)
pubk/rsa tok,pub,r/w,loc,vfy,rsa(2048)
seck/des-simple tok,prv,r/w,loc,enc,dec,sen,ase,nxt,des(64)
seck/aes-wrapping tok,prv,r/w,imp,wra,unw,sen,NAS,WXT,aes
pubk/dh tok,pub,r/w,loc,enc,vre,wra,dh(2048)
pubk/rsa-wrapping tok,pub,r/w,loc,wra,rsa(2048)
prvk/rsa-disclosed tok,prv,r/w,loc,sig,NSE,NAS,XTR,WXT,rsa(2048)
prvk/rsa-wrapping tok,prv,r/w,loc,unw,sen,ase,nxt,rsa(2048)
seck/aes-128 tok,prv,r/w,loc,enc,dec,sen,ase,nxt,aes(128)
seck/aes-256 tok,prv,r/w,loc,wra,unw,sen,ase,nxt,aes(256)
prvk/rsa tok,prv,r/w,loc,sig,sen,ase,nxt,rsa(2048)
pubk/rsa-disclosed tok,pub,r/w,loc,vfy,rsa(2048)
prvk/dh tok,prv,r/w,loc,dec,sir,unw,sen,ase,nxt,dh(2048)
seck/des-triple tok,prv,r/w,loc,enc,dec,sen,ase,nxt,des(192)
prvk/dsa tok,prv,r/w,loc,dec,sig,sir,unw,sen,ase,nxt,dsa(2048)
pubk/dsa tok,pub,r/w,loc,enc,vfy,vre,wra,dsa(2048)
data/dsaparam tok,prv,
seck/hmac-256 tok,prv,r/w,loc,sig,vfy,sen,ase,nxt,generic
data/dhparam tok,prv,
To avoid specifying command line arguments, environment variables can be specified for the following items:
optional arg | description | environment variable |
---|---|---|
-l |
path to library | PKCS11LIB |
-m |
path to NSS keystore (for NSS only) | PKCS11NSSDIR |
-s |
slot index number | PKCS11SLOT |
-t |
token name | PKCS11TOKEN |
-p |
token password | PKCS11PASSWORD |
To extract the value of a non-sensitive object, use p11cat
:
$ p11cat pubk/rsa
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA2zd+HKrd1u7TBMfvlpO2
1eT8uoY+aLw6/yT9treLk67czyA6XQ8NMtspacgxLXbC0XbaObGJDOswFN2o+zjA
hgKkBY6mEZKO3dzmqtQupQvxybyrj0pg0e+YoZe34rIjVvCdJ9T48etvCyrDZata
XYMw9pT2JvlJQG2ddPVjR83tGNayGYWmz5L0JwDLlb0NwJTJItIaabseIKHqQOzN
tSgeLsOmy08aqSq87WKEAilXrxcv8mWl/gbu18Chu4z7KJ76dWHnJfXzIMJCNNxf
HjhvKZx6bFMEi/gI9gCkUekO+6clrEjSxWzgnC8IDZCLGAvNBZ0pKBW9yEuayPiX
rQIDAQAB
-----END PUBLIC KEY-----
To see an object's value, use p11more
:
$ p11more cert/rootca
Certificate:
Data:
Version: 3 (0x2)
Serial Number: 2933735351 (0xaedd3fb7)
Signature Algorithm: sha256WithRSAEncryption
Issuer: C=BE, O=Dummy CA Inc., CN=Dummy Root CA G1
Validity
Not Before: Sep 28 08:10:48 2018 GMT
Not After : Sep 28 08:10:48 2028 GMT
Subject: C=BE, O=Dummy CA Inc., CN=Dummy Root CA G1
Subject Public Key Info:
Public Key Algorithm: rsaEncryption
Public-Key: (2048 bit)
Modulus:
00:a9:a6:a5:99:d0:3e:0e:00:c1:f7:df:9f:9c:92:
40:ac:67:d3:77:e0:d5:6d:eb:a0:5c:29:12:ad:57:
a3:23:9a:27:03:cb:dc:62:43:c3:04:a8:e8:a3:ab:
...
Moreover, p11od
can be used to extract all attribute values from an object:
$ p11od pubk/dh
pubk/dh:
CKA_CLASS:
0000 02 00 00 00 00 00 00 00 CKO_PUBLIC_KEY
CKA_TOKEN:
0000 01 CK_TRUE
CKA_PRIVATE:
0000 00 CK_FALSE
CKA_LABEL:
0000 64 68 dh
CKA_VALUE:
0000 7e cc a1 d2 c2 e7 90 b9 fa 68 fc ae 49 46 2e 0f ~........h..IF..
0010 62 1e 2c 69 2e 94 f2 eb 46 63 d7 fd 57 1f 5d 02 b.,i....Fc..W.].
0020 30 f4 3b 48 44 0c eb d7 7e 83 d5 26 7c 7a a3 f5 0.;HD...~..&|z..
...
Generating a key is easy: just use p11keygen
with the proper arguments.
$ p11keygen -k ec -q prime256v1 -i my-ec-key sign=true verify=true
Generating, please wait...
key generation succeeded
Likewise, p11req
is used to generate a CSR.
$ p11req -i my-ec-key -d '/CN=my.site.org/O=My organization/C=BE' -e 'DNS:another-url-for-my.site.org' -v
Certificate Request:
Data:
Version: 0 (0x0)
Subject: C=BE, O=My organization, CN=my.site.org
Subject Public Key Info:
Public Key Algorithm: id-ecPublicKey
Public-Key: (256 bit)
pub:
04:3f:56:11:f8:38:c7:f0:c1:87:a4:75:1a:ca:2e:
46:38:9e:6a:79:3a:3e:a5:90:54:48:be:81:18:c6:
f3:1c:92:8b:72:35:cd:e3:32:8c:40:a4:d4:e7:33:
50:13:34:4a:87:e0:8c:17:77:39:ed:ef:de:d3:1a:
26:b3:11:87:13
ASN1 OID: prime256v1
NIST CURVE: P-256
Attributes:
Requested Extensions:
X509v3 Subject Alternative Name:
DNS:another-url-for-my.site.org
Signature Algorithm: ecdsa-with-SHA256
30:45:02:21:00:e8:b7:c0:49:bc:77:8d:94:29:18:66:8f:9d:
6a:62:cd:f0:84:46:89:73:93:11:d8:67:98:95:12:1c:53:f7:
5f:02:20:4a:b6:98:fd:66:be:7c:7f:d1:02:07:d0:5b:dc:8b:
fd:3f:89:f0:ed:03:ec:2e:a4:1c:72:a2:21:22:9f:a5:7d
-----BEGIN CERTIFICATE REQUEST-----
MIIBMTCB2AIBADA9MQswCQYDVQQGEwJCRTEYMBYGA1UECgwPTXkgb3JnYW5pemF0
aW9uMRQwEgYDVQQDDAtteS5zaXRlLm9yZzBZMBMGByqGSM49AgEGCCqGSM49AwEH
A0IABD9WEfg4x/DBh6R1GsouRjieank6PqWQVEi+gRjG8xySi3I1zeMyjECk1Ocz
UBM0SofgjBd3Oe3v3tMaJrMRhxOgOTA3BgkqhkiG9w0BCQ4xKjAoMCYGA1UdEQQf
MB2CG2Fub3RoZXItdXJsLWZvci1teS5zaXRlLm9yZzAKBggqhkjOPQQDAgNIADBF
AiEA6LfASbx3jZQpGGaPnWpizfCERolzkxHYZ5iVEhxT918CIEq2mP1mvnx/0QIH
0Fvci/0/ifDtA+wupBxyoiEin6V9
-----END CERTIFICATE REQUEST-----
Later, p11importcert
can be used to import the certificate back to the keystore. Public keys can be imported
using p11importpubk
, and data files with p11importdata
.
If you need to wrap or unwrap a key, you can use the command p11wrap
:
$ p11wrap -w aes-wrapping -i rootca -a cbcpad >wrapped-key.wrap
key wrapping succeeded
The key can be unwrapped later, reusing the wrapped-key.wrap
file created earlier:
$ p11unwrap -f wrapped-key.wrap
key unwrapping succeeded
The project can compile on many platforms, including Linux, AIX, Solaris. Using cross-compilers, it is also possible to compile for the Windows platform. Compilation under macOS requires brew. Please refer to docs/INSTALL.md for installation instructions.
Please refer to docs/MANUAL.md for instructions / how-to guide.
If you wish to contribute to this project, please refer to the rules in docs/CONTRIBUTING.md.
Contributors:
- Georg Lippold (Mastercard, https://www.mastercard.com) - JWK output, GitHub build & CodeQL integration
Eric Devolder (Mastercard, https://www.mastercard.com)
Except when specified differently in source files, the following license apply:
Copyright (c) 2018 Mastercard
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
https://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an " AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.