NAME

       pkcs11sign.cnf - Configuration for OpenSSL PKCS#11 sign provider module

DESCRIPTION

       The  pkcs11-sign-provider  implements  the  OpenSSL  3.0  provider  interface  and provides cryptographic
       operation on asymmetric key material, available in PKCS#11 infrastructure (e.g. opencryptoki).  For  more
       information see pkcs11sign(7).

CONFIGURATION

   OpenSSL Configuration
       The  pkcs11-sign-provider  can  be  configured  application-specific  or  system-wide. In both cases, the
       configuration file need to define and reference a section for  the  pkcs11-sign-provider,  following  the
       OpenSSL configuration syntax (config(5)).

       The  pkcs11-sign-provider  section  specifies  the shared library of the provider itself (mandatory), the
       shared library of the Cryptoki implementation (mandatory) and initialization parameters for the  Cryptoki
       implementation  (optional).  It is also possible to specify a forward provider. If no forward provider is
       specified, the OpenSSL built-in default-provider is selected.

       The pkcs11-sign-provider must also be preferred in the algorithm-properties, so  that  all  requests  are
       directed  to the pkcs11-sign-provider. This can either be done in the application or in the configuration
       file (recommended).

   Provider Section
       A provider section in the OpenSSL configuration define generic parameters, as well  as  provider-specific
       parameters.  Each  provider  section can be references in a providers sections.  The pkcs11-sign-provider
       requires at least the generic provider section parameters  module,  identity,  and  activate.   For  more
       details about the generic provider parameters, see config(5).

       module (mandatory)
              This  parameter takes a path to the provider shared object file. For the pkcs11-sign-provider, use
              the path to the installation location of pkcs11sign.so (provider shared object).

       identity (optional)
              This parameter specifies an alias name for the provider and overrides the  provider  name  in  the
              providers section. It is recommended to use the same name as in the providers.

       activate (optional)
              If present, this parameter activates the provider section.

       The  pkcs11-sign-provider  defines  the  provider specific parameters pkcs11sign-module-path, pkcs11sign-
       module-init-args, and pkcs11sign-forward.

       pkcs11sign-module-path (mandatory)
              This  parameter  takes  the  path  to  the  shared  object  file  of  a  PKCS#11  Cryptoki  module
              implementation.  The  provider can be used with PKCS#11 Cryptoki modules, implementing the PKCS#11
              standard version 3.0 (or compatible).

       pkcs11sign-forward (optional)
              The pkcs11sign-forward parameter takes the name  of  a  provider,  to  which  all  operations  are
              forwarded,  which  are  not  handled  by  the pkcs11-sign-provider itself, e.g. key derivation for
              ECDHE. If this parameter is not specified in the provider section, the  pkcs11-sign-provider  will
              use the built-in OpenSSL default provider as forward.

              The  syntax  for  this  parameter  is "provider=<name_of_forward_provider>". See the configuration
              example for more details.

       pkcs11sign-module-init-args (optional, not PKCS#11-3.0 conform)
              The pkcs11sign-module-init-args takes a parameter string whose reference is passed to the Cryptoki
              module as pReserved in CK_C_INITIALIZE_ARGS during initialization.

              Note: The PKCS#11 standard v3.0 specifies that the initialization of a Cryptoki  module  fails  if
              pReserved  is  not  a NULL_PTR. This parameter will only work with Cryptoki modules (e.g.  libnss)
              which do not implement this strict behavior. A Cryptoki  module,  which  strictly  implements  the
              PKCS#11 standard v3.0 will fail on C_Initialize() with CKR_ARGUMENTS_BAD if this parameter is set.

   EVP Configuration (alg_section)
       This  section configures the algorithm-properties for the EVP API. The pkcs11-sign-provider should be set
       as the preferred provider for all EVP algorithms by adding the expression "?provider=pkcs11sign"  to  the
       default_properties.

   Configuration example
       This example shows a pkcs11-sign-provider configuration for opencryptoki.
           openssl_conf = openssl_init

           [openssl_init]
           providers = provider_sect
           alg_section = evp_properties

           [provider_sect]
           default = default_sect
           base = base_sect
           pkcs11sign = pkcs11sign_sect

           [evp_properties]
           default_properties = ?provider=pkcs11sign

           [pkcs11sign_sect]
           module = /path/to/pkcs11sign.so
           identity = pkcs11sign
           pkcs11sign-module-path = /path/to/libopencryptoki.so.0
           pkcs11sign-forward = provider=default
           activate = 1

ENVIRONMENT

       The  pkcs11-sign-provider  allows to generate a detailed log-file. The log-file generation can be enabled
       by setting the environment variable PKCS11SIGN_DEBUG and PKCS11SIGN_DEBUG_LEVEL.  The internal logging is
       disabled, until the environment variables are set.

       PKCS11SIGN_DEBUG
              This variable specifies the path to the log-file. If specified, it will enable  the  logging.  The
              pkcs11-sign-provider will override an existing file in this location.

       PKCS11SIGN_DEBUG_LEVEL
              This  variable  specifies  the  debugging level. Supported values are error (0), warning (1), info
              (2), and debug (3).

SEE ALSO

       config(5), pkcs11sign(7)

Copyright

       Copyright © International Business Machines Corp. 2022, 2023

pkcs11sign.cnf                                     2023-05-17                                  PKCS11SIGN.CNF(5)