GitHub - Mastercard/pkcs11-tools: A set of tools to manage objects on PKCS#11 cryptographic tokens. Compatible with many PKCS#11 library, including major HSM brands, NSS and softoken. (original) (raw)

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)

News

July 2023

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 and p11setattr 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 and CKA_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.

June 2023

Version 2.6, introduces support for JWK - JOSE Web Key output (RFC 7517) on the p11keygen, p11wrap, and p11rewrapcommands. The JWK format is not supported for importing keys.

October 2021

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.

July 2021

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.

April 2021

Version 2.3, that adds extra options to p11kcv, so that tokens not supporting NULL-length HMAC computation can be also supported.

March 2021

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.

January 2021

Version 2.1 brings support for Edwards Curve.

December 2020

The toolkit has reached v2.0. It features several major changes:

• it supports (and requires) OpenSSL v1.1.1+
• signing commands (p11mkcert, p11req and masqreq) 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.

Introduction

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:

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, p11odcan 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🔞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

Installation

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.

Shell completion

After make install, bash and zsh completion is installed for all p11* tools and is loaded automatically by the completion framework - simply press <TAB>, there is nothing to source.

Completion has three levels, depending on the information available on the command line:

• Static completions (command options, key types, curves, wrapping algorithms, SAN prefixes, file paths) require no token access.
• Slot / token completion activates once a library is known, either via -l <lib> or by exporting PKCS11LIB.
• Object name completion additionally requires a PIN, via -p <pin> or by exporting PKCS11PASSWORD.

A few notes:

• Variables must be exported to be visible to completion. Inline assignments such as PKCS11LIB=... p11ls <TAB> are not seen by the completion logic; use export PKCS11LIB=... instead.
• Each slot, token or object <TAB> performs a live query against the token (it invokes p11slotinfo -L or p11ls), so there may be a short delay on slow or remote tokens. Static completions never contact the token.
• Some vendor libraries require additional environment to expose all slots (for example, Entrust nShield needs export CKNFAST_LOADSHARING=1 for softcards/OCS to appear).

To register the completions manually without installing (e.g. when running from the build tree):

load a single tool (it pulls in p11-common automatically)

source completion/bash/p11ls

or load all tools at once

for f in completion/bash/p11*; do source "$f"; done

To deregister the completions for the current shell:

complete -r p11cat p11cp p11importcert p11importdata p11importpubk p11kcv
p11keycomp p11keygen p11ls p11mkcert p11more p11mv p11od p11req
p11rewrap p11rm p11setattr p11slotinfo p11unwrap p11wrap

To disable all programmable completion for the shell, use shopt -u progcomp (re-enable with shopt -s progcomp). To prevent completion from being installed at all, remove the files under $(datadir)/bash-completion/completions/p11* and $(datadir)/zsh/site-functions/_p11tools; the binaries are unaffected.

Manual

Please refer to docs/MANUAL.md for instructions / how-to guide.

Contributing

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

Author

Eric Devolder (Mastercard, https://www.mastercard.com)

Licensing terms

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

http://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.