Skip to content

Home

Jump to bottom
Eric Devolder edited this page Dec 10, 2018 · 3 revisions

Welcome to the pkcs11-tools wiki!

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

Introduction

To build the source code, simply execute (with appropriate privileges)

$ ./configure
$ make install

To list the methods available on a PKCS#11 token, use p11slotinfo, that will return the list of available echanisms, together with allowed APIs.

$ p11slotinfo -l /usr/local/opt/softhsm/lib/softhsm/libsofthsm2.so
PKCS#11 module slot list:
Slot index: 0
----------------
Description : SoftHSM slot ID 0x14a93125
Token Label : first token
Manufacturer: SoftHSM project


Enter slot index: 0

Slot[0]
-------------
Slot Number : 346632485
Description : SoftHSM slot ID 0x14a93125
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, 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 CKA_SIGN=true CKA_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 uwrapped 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 Installation for installation instructions.

Manual

Please refer to Manual for instructions. There is also an How-to guide for working with NSS keystores.

Contributing

If you wish to contribute to this project, please refer to the rules in docs/CONTRIBUTING.md.

Author

Eric Devolder (Mastercard, http://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.

Clone this wiki locally