1PKCS11SIGN(7)          Miscellaneous Information Manual          PKCS11SIGN(7)
2
3
4

NAME

6       pkcs11sign - OpenSSL PKCS#11 sign provider module
7

DESCRIPTION

9       The  pkcs11-sign-provider implements the OpenSSL 3.0 provider interface
10       and provides cryptographic operation on asymmetric key material, avail‐
11       able  in  PKCS#11  infrastructure (e.g. opencryptoki). The pkcs11-sign-
12       provider will register a key storage for PKCS#11 URIs (RFC  7512).  All
13       keys  which  are  referenced  by  a  PKCS#11 URI will be handled by the
14       pkcs11-sign-provider.  Other keys (e.g.  file-based) are are  forwarded
15       by  the  pkcs11-sign-provider  to  another  OpenSSL-Provider,  e.g. the
16       built-in OpenSSL default provider.
17
18       The pkcs11-sign-provider will only  process  algorithms  with  existing
19       (private)  asymmetric  keys  in the related PKCS11-token. All other ac‐
20       tions will be handled by the forward-provider as clear-key operations.
21
22       The pkcs11-sign-provider does not support key creation  or  removal  of
23       PKCS#11 keys. For key management, external tools are required.
24
25       Supported PKCS#11 mechanisms for RSA:
26
27       • CKM_RSA_PKCS
28
29       • CKM_RSA_PKCS_OAEP
30
31       • CKM_RSA_PSS
32
33       • CKM_RSA_X_509
34
35       Supported PKCS#11 mechanisms for EC:
36
37       • CKM_ECDSA
38

APPLICATION INTERFACE

40       An application, which should use asymmetric keys in PKCS#11 infrastruc‐
41       ture, must use an OpenSSL configuration  for  the  pkcs11-sign-provider
42       and  refer  to  the keys by an PKCS#11 URI. The rest of the application
43       should not need any changes.
44
45   Configuration
46       If  the  system-wide  OpenSSL  configuration  does  not  configure  the
47       pkcs11-sign-provider,  the application can use its own OpenSSL configu‐
48       ration file and refer to it in its environment  variable  OPENSSL_CONF.
49       For more details about the configuration see pkcs11sign.cnf(5).
50
51   Key references
52       Instead    of    referring    to    a    private    key    file   (e.g.
53       "file:/path/to/key.pem"), the application should use the PKCS#11 URI of
54       the key ("pkcs11:<path-attributes>?<queue-attributes>").
55
56       The PKCS#11 URI should specify path parameters of the key, at least the
57       ID or label of the key, as well as its type. The key  reference  should
58       be unique.
59
60       Example for a PKCS#11 URI to a private key:
61           pkcs11:token=mytok;object=ec-key;type=private&pin-source=/path/to/token-pinfile.txt
62
63       Note   The  current  version  of pkcs11-sign-provider supports only the
64              queue parameters pin-value and pin-source.  All other queue  pa‐
65              rameters are not yet supported.
66
67   PIN handling
68       The PIN is required to login to a PKCS#11 token, to manage or work with
69       sensitive PKCS#11 objects (keys) and should not be proposed  to  anyone
70       without a need-to-know.
71
72       An  application,  which  is  using key material in a PKCS#11 token, has
73       such a need-to-know, so the PIN should be under control of the applica‐
74       tion.
75
76       The  pkcs11-sign-provider  supports the PIN handling in the PKCS#11 URI
77       with the queue attributes pin-value and pin-source.   While  the  first
78       one contains the plain-text PIN, the latter one refers to a file, which
79       contains the PIN. It is highly recommended to use  the  file  reference
80       and set the access permissions of the PIN file accordingly.
81
82   PIN file
83       The PIN gives access to a PKCS#11 token and its objects (keys, certifi‐
84       cated, data). It should be treated as a secret information and only the
85       application  should  have access to it. With the right setup, the usage
86       of a PIN file provides the best protection for the PIN.
87
88       Rules for the PIN file:
89
90       • one PIN per PIN file
91
92       • the PIN file must only contain the PIN, no comments, no  linefeed  or
93         other characters
94
95       • the PIN file must be readable by the application
96
97       • the PIN file should not be writable by the application
98
99       • the  PIN file must not be readable nor writable by other unprivileged
100         users.
101
102       The following snippet shows, how to create a  protected  PIN  file.  It
103       will  prompt for the PIN and write it to a file, which is only accessi‐
104       ble for the user.
105
106           PINFILE="/path/to/my_pinfile.txt"
107           touch "${PINFILE}"
108           chmod u=rw,g=,o= "${PINFILE}"
109           (read -rsp "Enter PIN: " PIN; echo -n ${PIN}) > "${PINFILE}"
110
111       If required, the file ownership can later be changed  to  another  user
112       and  group.  This  would  require  extra  capabilities  (e.g.  by using
113       "sudo").
114

SEE ALSO

116       pkcs11sign.cnf(5), EVP(7)
117

119       Copyright © International Business Machines Corp. 2022, 2023
120
121pkcs11sign                        2022-11-21                     PKCS11SIGN(7)
Impressum