000017095 - MES: How to read from a PKCS #11 device and list certificates

Document created by RSA Customer Support Employee on Jun 16, 2016Last modified by RSA Customer Support Employee on Apr 21, 2017
Version 2Show Document
  • View in full screen mode

Article Content

Article Number000017095
RSA BSAFE Micro Edition Suite
IssueMES: How to read from a PKCS #11 device and list certificates

See the MES sample program "r_hwrdcert" (samples/source/hdw/cert/r_hwrdcert.c, samples/source/hdw/r_hwrdcert.vcproj) for how to list the certificates on a PKCS #11 device, and the MES sample program "cert" (samples/source/cert/cert.c, samples/source/cert/cert/cert.vcproj) for how to parse the fields in the certificate.  Running the "cert" sample program with the command-line argument "-subject" calls R_CERT_subject_name_to_string() to print the subject name of the certificate.

The PKCS #11 device may be specified in the "RSA_MES_HDW_DLL" environment variable, or in the R_HW_CONFIG_HW_FUNC_T() callback function.

From the MES Developer's Guide > Getting Started with MES > Setting the Hardware Environment Variable:

Setting the Hardware Environment Variable

This section describes how to set system environment variables when using hardware devices. The RSA_MES_HDW_DLL system environment variable must be set to specify the following information about the hardware:

The name of the hardware device.
The name of the OEM DLL, including the OEM DLL's file extension.
The type of hardware driver. (Note that only PKCS #11 is supported.)
Optionally, the login PIN. (Note that a different PIN can be defined for each physical OEM device present.)
The following example demonstrates setting the hardware environment variable.

 RSA_MES_HDW_DLL=name=pkcs11,type=pkcs11,driver= C:/WINDOWS/system32/K1PK112.DLL,pin=1:PASSWORD,2:77777777

The above configuration string can also be returned via a callback.
For more information, see "Hardware Configuration".


From the MES Developer's Guide > API Reference Guide > Cryptographic Operations > Hardware Operations > Hardware Configuration:

Hardware Configuration

This section describes the user-defined routines used to specify hardware configuration.

typedef char* R_HW_CONFIG_HW_FUNC_T (void)


Typedef Documentation
typedef char* R_HW_CONFIG_HW_FUNC_T(void) 
   A callback that returns the configuration string for a hardware device or devices.

The input data string can contain the definitions for any number of Original Equipment Manufacturer (OEM) Dynamic Linked Libraries (DLLs).

Each OEM DLL definition has value assignments, which are sets of identifiers and assigned values in the format identifier=data, where the equal sign assigns the information in data to the identifier. Value assignments are separated by a comma or, if it is the last assignment in a DLL definition, terminated a semi-colon.

The following table lists and describes the available value assignments.

Identifier  State  Description 
name  Mandatory  The name of the hardware device. 
driver  Mandatory  The name of the OEM DLL, including the OEM DLL's file extension. 
type  Mandatory  The type of hardware driver. Currently only PKCS #11 is supported. 
pin  Optional  The login pin value used for validation. A different pin can be defined for each physical OEM device present. For example a PKCS #11 device pin data, pin=10:12aBc23, means "load slot id '10'" with the ASCII login pin data "12aBc23". Pins for multiple devices indexes can be specified. For example, two PKCS #11 pins are pin=1:12aBc23,pin=2:fRoG2iNkEt2lE. 

Multiple OEM DLL definitions can be chained together in the variable. For example, two PKCS #11 definitions are represented as name=deviceA,driver=devideA.dll,type=pkcs11;name=p11s,driver=p11s.dll, type=pkcs11

A string containing the configuration details for the hardware device.

See also:

   Callback that returns a function that provides configuration for a hardware device. 

Legacy Article IDa43694