PKCS #11 Developer Guide for RSA Smart Card Middleware 3.

PKCS #11 Developer Guide for

RSA Smart Card Middleware 3.6

Introduction
RSA Smart Card Middleware 3.6 consists of a smart card module based on:
• The Microsoft Smart Card Minidriver specification
• An implementation of the Public Key Cryptographic Standard #11 (PKCS #11)
Application Programming Interface (API) documented in the PKCS #11 v2.20:
Cryptographic Token Interface Standard
PKCS #11 specifies an API called Cryptoki. It interacts with devices that hold
cryptographic information and perform cryptographic functions. Middleware also
contains PKCS #11 mechanisms that allow you to read one-time passwords from
hardware tokens through a software program. These mechanisms are documented in
PKCS #11 v2.20 Amendment 1 PKCS #11 Mechanisms for One-Time Password
Tokens.
This document lists the functions and mechanisms supported by Middleware for you
to develop applications that exchange information with the smart card portion of the
RSA SecurID 800 Authenticator (SecurID 800). For more information on PKCS #11
standards, see the documents listed in the PKCS #11: Cryptographic Token
Interface Standard.

Note: This guide does not contain information for developers who want to write
applications that use the Microsoft Smart Card Minidriver communication path to a
cryptographic token (applications that use Microsoft Cryptographic Application
Programming Interface [CAPI]). For information on writing applications that use the
CAPI, see the Microsoft Developer Network site.

Preliminary 1
 PKCS #11 Developer Guide for RSA Smart Card Middleware 3.6

System Requirements
The following table lists the system requirements for RSA Smart Card Middleware, as
well as the supported smart cards.

Operating systems One of the following:

• Windows XP, 32-bit Professional SP3 edition
• Windows XP, 64-bit, Professional SP2 edition
• Windows Vista SP2, 32-bit and 64-bit, Business
and Enterprise editions
• Windows 7 SP1, 32-bit and 64-bit, Enterprise and
Professional editions
• Windows 8, 32-bit and 64-bit, Enterprise and
Professional editions
• Windows Server 2003 R2, 32-bit and 64-bit,
Standard, and Enterprise editions
• Windows Server 2008 SP2, 32-bit and 64-bit,
Standard, Enterprise, Data Center, and Web Server
editions
• Microsoft Windows Server 2008 R2 SP1, 64-bit,
Standard, Enterprise, Data Center, and Web Server
editions
• Windows Server 2012 SP2, Standard or Data
Center editions

Disk space 110 MB

Smart cards RSA SecurID 800 Authenticator

Important: If you use a Windows XP or 32-bit Windows Server 2003 operating

system, you must install the Windows Base Smart Card Cryptographic Service
Provider (Base CSP) Package x86 KB909520 for Authentication Client to function
properly. For the 64-bit Windows Server 2003 operating system, you must install the
Microsoft Base Smart Card Cryptographic Service Provider Package
x64 KB909520.

For more details on requirements, see the Installation and Administration Guide.

2 PKCS #11 Developer Guide for RSA Smart Card Middleware 3.6
 PKCS #11 Developer Guide for RSA Smart Card Middleware 3.6

Installation
The installation requires 110 MB of disk space. You must have administrator
privileges on the local computer. The installation program installs the Middleware into
the destination folder.
You can install Middleware on a single computer or multiple computers. For example,
you can run the Windows Installer (MSI) file, RSA Smart Card Middleware
3.6.msi, to install the product on a single computer. For a large-scale deployment to
multiple computers, you must provide account privileges to the appropriate users.
Then deploy Middleware using Microsoft Systems Management Server (SMS) or
another third-party product, such as Tivoli. Or, you can use a command line
installation. For details on installing Middleware, see the Installation and
Administration Guide.

Note: You must separately copy header files containing definitions and data structures
for creating applications. For more information, see the following section,
“Application Development.”

Application Development
RSA Smart Card Middleware was developed using Microsoft Visual C++ 2008. One
component of the Middleware is a PKCS #11 module that is provided as a Dynamic
Link Library (DLL). You can develop an application that communicates with
SecurID 800 authenticators through the PKCS #11 module.
You need the following files to write applications that interact with SecurID 800
authenticators:
• PKCS #11 Dynamic Link Library (pkcs11.dll). Installing Middleware installs this
DLL into the destination directory, usually C:\Program Files\Common
Files\RSA shared\RSA P11.
• Header files containing definitions and data structures for creating applications.
These files are not part of the Middleware installation. Copy them separately from
the APIs\PKCS 11 Support folder on the Middleware CD:
– cryptoki.h
– otp-pkcs11.h
– pkcs11.h
– pkcs11f.h
– pkcs11t.h
– pkcs11t_securid.h
The following sections provide details on the implementation. They contain
information on the PKCS #11 functions, supported objects, and cryptographic
mechanisms.

PKCS #11 Developer Guide for RSA Smart Card Middleware 3.6 3
 PKCS #11 Developer Guide for RSA Smart Card Middleware 3.6

Supported Functions
RSA Smart Card Middleware supports the following functions from the PKCS #11
library. For more information, see the PKCS #11: Cryptographic Token Interface
Standard.

PKCS #11 Function Type Function

General Purpose C_Initialize

C_Finalize

C_GetInfo

C_GetFunctionList

Slot and Token Management C_GetSlotList

C_GetSlotInfo

C_WaitForSlotEvent

C_GetTokenInfo

C_GetMechanismList

C_GetMechanismInfo

C_InitToken

C_InitPIN

C_SetPIN

Session Management C_OpenSession

C_CloseSession

C_CloseAllSessions

C_GetSessionInfo

C_Login

C_Logout

Note: If you log on to a token session as a security officer (user type CKU_SO), use the PIN
Unblock Key (PUK) as the PIN for your SecurID 800 authenticator. The PUK appears in the
XML file that came with the authenticator. It is displayed as an ANSI string of hex values
(usually 16 characters long). When you use the PUK as a PIN, you must convert the hex
representation into a binary array. Every two characters of the hex representation translate
into a single byte. Therefore, a PUK that is 16 characters long in the hex form converts to a
binary array that is eight bytes long.

4 PKCS #11 Developer Guide for RSA Smart Card Middleware 3.6
 PKCS #11 Developer Guide for RSA Smart Card Middleware 3.6

PKCS #11 Function Type Function

Object Management C_CreateObject

C_DestroyObject

C_GetAttributeValue

C_SetAttributeValue

C_FindObjectsInit

C_FindObjects

C_FindObjectsFinal

Encryption C_EncryptInit

C_Encrypt

C_EncryptUpdate

C_EncryptFinal

Decryption C_DecryptInit

C_Decrypt

C_DecryptUpdate

C_DecryptFinal

Message Digesting C_DigestInit

C_Digest

C_DigestUpdate

C_DigestFinal

Signing and MACing C_SignInit

C_Sign

Key Management C_GenerateKey

C_GenerateKeyPair

C_UnwrapKey

Random Number Generation Functions C_SeedRandom

C_GenerateRandom

PKCS #11 Developer Guide for RSA Smart Card Middleware 3.6 5
 PKCS #11 Developer Guide for RSA Smart Card Middleware 3.6

Supported Objects
RSA Smart Card Middleware supports the following objects:
• Data (CKO_DATA)
• Certificate (CKO_CERTIFICATE)
• Public key (CKO_PUBLIC_KEY)
• Private key (CKO_PRIVATE_KEY)
• Secret key (CKO_SECRET_KEY)
• One-time password key (CKO_OTP_KEY)
The following sections provide implementation details of PKCS #11 objects specific
to RSA Smart Card Middleware 3.6. For more information on the PKCS #11 standard,
see the PKCS #11 v2.20: Cryptographic Token Interface Standard document.

Note: Even though the following sections define some attributes as “read only,” the
PKCS #11 module does not return an error if you specify attributes in your template
with values that correspond to the ones listed in this document. For example, the
following “Certificate Object” section lists CKA_TRUSTED as a read-only attribute
always set to CK_FALSE. If your template for a certificate object includes
CKA_TRUSTED set to CK_FALSE, an error is not returned to the application.

Data Object
The Data (CKO_DATA) object supports all the attributes listed in the PKCS #11
standard.

Certificate Object
Allowed value of CKA_CERTIFICATE_TYPE: CKC_X_509.
Read-Only Attributes:
• CKA_PRIVATE is always CK_FALSE.
• CKA_TRUSTED is always CK_FALSE.
• CKA_CERTIFICATE_CATEGORY is always 0.
• CKA_START_DATE is always empty.
• CKA_END_DATE is always empty.
• CKA_ISSUER is always equal to the DER-encoding of the certificate issuer name
extracted from the CKA_VALUE (BER-encoding of the certificate).
• CKA_SERIAL_NUMBER is always equal to the DER-encoding of the certificate
serial number extracted from the CKA_VALUE (BER-encoding of the
certificate).
• CKA_URL is always empty.
• CKA_HASH_OF_SUBJECT_PUBLIC_KEY is always empty.

6 PKCS #11 Developer Guide for RSA Smart Card Middleware 3.6
 PKCS #11 Developer Guide for RSA Smart Card Middleware 3.6

• CKA_HASH_OF_ISSUER_PUBLIC_KEY is always empty.

• CKA_JAVA_MIDP_SECURITY_DOMAIN is always 0.
Token-Specific Default Values: No certificate object attributes have token-specific
defaults.

Notes:
• If you use a smart card in the Middleware 3.x format, you can specify a
CKA_SUBJECT that is different from the one embedded in the certificate object.
If you use a smart card in the Middleware 2.x format, you must specify a
CKA_SUBJECT that is identical to the CKA_SUBJECT embedded in the
certificate object.
• If you use a smart card in the Middleware 3.x format and it has certificates with
CKA_SUBJECTS that are different from the ones embedded in the certificates,
the certificates lose the subjects if you convert the smart card to the Middleware
2.x format. After the conversion, only the CKA_SUBJECTS embedded in the
certificate will be available.

Public Key Object

Allowed value of CKA_KEY_TYPE: CKK_RSA.
Read-only attributes:
• CKA_TOKEN is always CK_TRUE.
• CKA_PRIVATE is always CK_FALSE.
• CKA_TRUSTED is always CK_FALSE.
• CKA_WRAP_TEMPLATE is always empty.

Note: Unless the CKA_ID value is specified in the template used when
C_GenerateKeyPair() is called, the value of CKA_ID will be set to the SHA-1 hash of
the value of the modulus of the public key. In this case, PKCS #11 generates a unique
CKA_ID and sets it the same between the generated public and private keys.
Otherwise, the CKA_ID value is the value specified in the template.

Token-specific default values: No public key attributes with token-specific defaults

are writable.

PKCS #11 Developer Guide for RSA Smart Card Middleware 3.6 7
 PKCS #11 Developer Guide for RSA Smart Card Middleware 3.6

Private Key Object

Allowed value of CKA_KEY_TYPE: CKK_RSA.
Read-only attributes:
• CKA_TOKEN is always CK_TRUE.
• CKA_PRIVATE is always CK_TRUE.
• CKA_DERIVE is always CK_FALSE.
• CKA_ALLOWED_MECHANISMS is always set to the following mechanism
list: CKM_RSA_PKCS, CKM_RSA_PKCS_OAEP, and CKM_RSA_X_509.
• CKA_KEY_GEN_MECHANISM is always set to
CKM_RSA_PKCS_KEY_PAIR_GEN if CKA_LOCAL is CK_TRUE.
Otherwise, it is set to UNAVAILABLE_INFORMATION.
• CKA_SENSITIVE is always CK_TRUE.
• CKA_EXTRACTABLE is always CK_FALSE.
• CKA_ALWAYS_SENSITIVE is always CK_TRUE.
• CKA_NEVER_EXTRACTABLE is always CK_TRUE.
• CKA_WRAP_WITH_TRUSTED is always CK_FALSE.
• CKA_UNWRAP_TEMPLATE is always empty.
• CKA_TRUSTED is always CK_FALSE.
Token-specific default values:
• CKA_SENSITIVE defaults to CK_TRUE.
• CKA_DECRYPT defaults to CK_TRUE.
• CKA_SIGN defaults to CK_TRUE.
• CKA_SIGN_RECOVER defaults to CK_FALSE.
• CKA_UNWRAP defaults to CK_TRUE.
• CKA_EXTRACTABLE defaults to CK_FALSE.

Notes:
• Unless the CKA_ID value is specified in the template used when
C_GenerateKeyPair() is called, the value of CKA_ID will be set to the SHA-1
hash of the value of the modulus of the public key. In this case, PKCS #11
generates a unique CKA_ID and sets it the same between the generated public and
private keys. Otherwise, the CKA_ID value is the value specified in the template.
• When creating a private key using C_CreateObject, specify all the attributes listed
in “Table 36, RSA Private Key Object Attributes” in the PKCS #11 v2.20:
Cryptographic Token Interface Standard document.

8 PKCS #11 Developer Guide for RSA Smart Card Middleware 3.6
 PKCS #11 Developer Guide for RSA Smart Card Middleware 3.6

Secret Key Object

Allowed values of CKA_KEY_TYPE:
• CKK_DES3 (Triple-length DES secret key)
• CKK_AES (AES secret key)
Read-only attributes:
• CKA_PRIVATE is always CK_TRUE.
• CKA_WRAP_WITH_TRUSTED is always CK_FALSE.
• CKA_TRUSTED is always CK_FALSE.
• CKA_WRAP_TEMPLATE is always empty.
• CKA_UNWRAP_TEMPLATE is always empty.
• CKA_ALLOWED_MECHANISMS
– For DES3 secret keys: Is always set to CKM_DES3_CBC and
CKM_DES3_PAD.
– For AES secret keys: Is always set to CKM_AES_CBC and
CKM_AES_PAD.
• CKA_KEY_GEN_MECHANISM
– For DES3 secret keys: Is always set to CKM_DES3_KEY_GEN if
CKA_LOCAL is CK_TRUE. Otherwise, it is set to
UNAVAILABLE_INFORMATION.
– For AES secret keys: Is always set to CKM_AES_KEY_GEN if
CKA_LOCAL is CK_TRUE. Otherwise, it is set to
UNAVAILABLE_INFORMATION.
Token-specific default values:
• CKA_ENCRYPT defaults to CK_TRUE.
• CKA_DECRYPT defaults to CK_TRUE.
• CKA_SIGN defaults to CK_FALSE.
• CKA_VERIFY defaults to CK_FALSE.
• CKA_EXTRACTABLE defaults to CK_FALSE.

PKCS #11 Developer Guide for RSA Smart Card Middleware 3.6 9
 PKCS #11 Developer Guide for RSA Smart Card Middleware 3.6

One-Time Password Key Object

RSA Smart Card Middleware 3.6 supports One-Time Password (OTP) for
RSA SecurID 800 Authenticator (SecurID 800) only. This token ships with a single
OTP key written to the smart card. It does not support writing additional keys to the
card.
Allowed value of CKA_KEY_TYPE: CKK_SECURID.
Read-only attributes:
The OTP key is a secret key. Therefore, the read-only limitations listed in the “Secret
Key Object” section on page 9 also apply to OTP key objects.
• CKA_OTP_FORMAT is always CK_OTP_FORMAT_DECIMAL.
• CKA_OTP_LENGTH is always 6.
• CKA_OTP_USER_FRIENDLY_MODE is always CK_TRUE.
• CKA_OTP_CHALLENGE_REQUIREMENT is always
CK_OTP_PARAM_OPTIONAL.
• CKA_OTP_TIME_REQUIREMENT is always CK_OTP_PARAM_OPTIONAL.
• CKA_OTP_COUNTER_REQUIREMENT is always
CK_OTP_PARAM_OPTIONAL.
• CKA_OTP_COUNTER is always empty.
• CKA_OTP_TIME is always empty.
• CKA_OTP_USER_IDENTIFIER is always empty.
• CKA_OTP_SERVICE_IDENTIFIER is always empty.
• CKA_OTP_SERVICE_LOGO is always empty.
• CKA_OTP_SERVICE_LOGO_TYPE is always empty.
• CKA_TOKEN is always CK_TRUE.
• CKA_ID is always set to the serial number of the token.
• CKA_OTP_TIME_INTERVAL is always 60.
• CKA_VALUE is always empty.
• CKA_VALUE_LEN is always 0.

10 PKCS #11 Developer Guide for RSA Smart Card Middleware 3.6
 PKCS #11 Developer Guide for RSA Smart Card Middleware 3.6

Token-specific default values: OTP key creation is not supported.

Unsupported OTP mechanisms:
• CKM_HOTP_KEY_GEN
• CKM_HOTP
• CKM_ACTI_KEY_GEN
• CKM_ACTI
Unsupported OTP mechanism parameters:
• CK_OTP_CHALLENGE
• CK_OTP_TIME
• CK_OTP_COUNTER
• CK_OTP_FORMAT
• CK_OTP_VALUE
Unsupported OTP mechanism flags:
• CKF_NEXT_OTP
• CKF_EXCLUDE_TIME
• CKF_EXCLUDE_COUNTER
• CKF_EXCLUDE_CHALLENGE
• CKF_USER_FRIENDLY_OTP

PKCS #11 Developer Guide for RSA Smart Card Middleware 3.6 11
 PKCS #11 Developer Guide for RSA Smart Card Middleware 3.6

Cryptographic Mechanisms
RSA Smart Card Middleware supports the following Cryptoki mechanisms for
cryptographic operations. For more information, see the PKCS #11 v2.20:
Cryptographic Token Interface Standard.

Type Mechanism

Single-Part and Multiple-Part Encryption CKM_AES_CBC

CKM_AES_CBC_PAD

CKM_DES3_CBC

CKM_DES3_CBC_PAD

Single-Part Decryption CKM_RSA_PKCS

CKM_RSA_PKCS_OAEP

CKM_RSA_X_509

Single-Part and Multiple-Part Decryption CKM_AES_CBC

CKM_AES_CBC_PAD

CKM_DES3_CBC

CKM_DES3_CBC_PAD

Single-Part and Multiple-Part Digesting CKM_MD5

CKM_SHA_1

CKM_SHA256

Single-Part Signing CKM_RSA_PKCS

CKM_RSA_X_509

CKM_SECURID

Secret Key Generation CKM_AES_KEY_GEN

CKM_DES3_KEY_GEN

Public/Private Key Generation CKM_RSA_PKCS_KEY_PAIR_GEN

Key Unwrapping CKM_RSA_PKCS

CKM_RSA_PKCS_OAEP

CKM_RSA_X_509

One-Time Password CKM_SECURID

12 PKCS #11 Developer Guide for RSA Smart Card Middleware 3.6
 PKCS #11 Developer Guide for RSA Smart Card Middleware 3.6

Trademarks
RSA, the RSA logo and EMC are either registered trademarks or trademarks of EMC Corporation (“EMC”) in the
United States and/or other countries. All other trademarks used herein are the property of their respective owners.
© 2008–2012 EMC Corporation. All rights reserved.
First Printing: September 2008
Revised: October 2012

PKCS #11 Developer Guide for RSA Smart Card Middleware 3.6 13