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