CryptoKit Developers Guide

CryptoKit
Developer’s Guide
---------------------------------
Version 3.9
Notice
This manual contains information that is proprietary to ARX (Algorithmic Research)
No part of this manual may be reproduced in any form whatsoever without
prior written approval by ARX.
ARX reserves the right to revise this publication and make any changes without
obligation to notify any person of such revisions and changes.
For further information, contact ARX at the address below, or contact your local distributor.
Trademarks
CryptoKit, MiniKey, PrivateCard, CryptoSafe, PrivateSafe, and PrivateSafe
PCMCIA are trademarks of ARX. Other names are trademarks or registered trademarks of
respective owners and are used solely for identification purposes.
ARX (Algorithmic Research) 855 Folsom St. Suite 939, San Francisco, CA 94107 Tel: (415) 839 8161 Fax: (415) 723 7110 www.arx.com
© Copyright 2005 ARX (Algorithmic Research). CryptoKit Developer’s Guide

All rights reserved. Pub. Date 18.07.05
Pub. No. CK .V3.00601
Table of Contents
Chapter 1: Introduction to Cryptography .......................................................................... 1-1

Security Issues ....................................................................................................................... 1-1
Cryptographic Algorithms ..................................................................................................... 1-1
Symmetric Schemes ............................................................................................................... 1-2
Asymmetric Schemes............................................................................................................. 1-3
Hybrid Symmetric/Asymmetric Schemes .............................................................................. 1-5
Chapter 2: Component-Related Technologies................................................................. 2-1

Key Media..................................................................................................................................... 2-2
Smart Cards ........................................................................................................................... 2-2
Software Key Media .............................................................................................................. 2-5
MiniKey Token...................................................................................................................... 2-8
Hardware Security Module – PrivateServer ........................................................................ 2-10
CoSign – Digital Signatures Appliance ............................................................................... 2-11
Smart Card Readers ............................................................................................................. 2-11
PrivateSafe........................................................................................................................... 2-13
PrivateSafe PCMCIA........................................................................................................... 2-14
CryptoSafe ........................................................................................................................... 2-15
Media Independence ................................................................................................................... 2-16
Platform Independence ............................................................................................................... 2-16
Advanced Capabilities ................................................................................................................ 2-17
Simplicity of Use ........................................................................................................................ 2-17
Performance ................................................................................................................................ 2-17
Stability and Exception Handling ............................................................................................... 2-18
Compliance with Industry Standards........................................................................................... 2-18
Chapter 3 SmartAdaptor Technology ................................................................................ 3-1

General Concepts .......................................................................................................................... 3-2
CryptoKit Architecture ................................................................................................................. 3-2
SmartAdaptor General Concepts ........................................................................................... 3-4
Main SmartAdaptor Cryptographic API ....................................................................................... 3-5
PKCS#11 General Terminology ................................................................................................... 3-5
i
CryptoKit Developer's Guide
CryptoKit PKCS#11 Architecture .................................................................................................3-6

Supported Functions and Mechanisms ..........................................................................................3-7
Using DES2 and DES Keys with DES3 Mechanisms ..........................................................3-13
DES Stream mechanisms......................................................................................................3-13
Users, Administrators and Sessions .............................................................................................3-15
CryptoKit PKCS#11 Versions .....................................................................................................3-16
Algorithmic Research CryptoKit PKCS#11 Releases ..........................................................3-16
Tokens and Slots..........................................................................................................................3-17
Data Stored as Objects.................................................................................................................3-18
PIN Functionality.........................................................................................................................3-19
PIN Default Parameters ........................................................................................................3-20
Thread Safety...............................................................................................................................3-24
Date and Time .............................................................................................................................3-24
Platform- and Compiler-Dependent Directives............................................................................3-25
Platform-Specific Macros.....................................................................................................3-26
Registration API ..........................................................................................................................3-29
Registration API Data Types ................................................................................................3-29
SmartAdaptor Registration API Functions ...........................................................................3-34
Reader Provider Development.....................................................................................................3-49
Reader Provider API ............................................................................................................3-51
PKCS#11 API Extensions ...........................................................................................................3-59
Provider Architecture Functionality.............................................................................................3-61
Software Tokens Extensions........................................................................................................3-69
Token Event Extensions ..............................................................................................................3-71
Token and Object Extensions ......................................................................................................3-74
User Interface Extensions ............................................................................................................3-76
User Interface Customization ......................................................................................................3-82
Chapter 4: AR Cryptographic Service Provider.................................................................4-1

Microsoft CryptoAPI and Crypto Service Providers .....................................................................4-2
CSP Types ..............................................................................................................................4-3
CAPI Data Objects .................................................................................................................4-5
ARCSP Provider............................................................................................................................4-6
ARCSP Provider Types..........................................................................................................4-6
Architecture ............................................................................................................................4-6
Provider Registration..............................................................................................................4-9
Signature.................................................................................................................................4-9
Versions................................................................................................................................4-10
Supported Algorithms...........................................................................................................4-10
ii
Table of Contents
Supported Functions ............................................................................................................ 4-12

Certificate Store .......................................................................................................................... 4-16
Store Functionality on Win 98, ME and NT ........................................................................ 4-16
Physical Certificate Store on Windows 2000, XP and 2003................................................ 4-17
Export/Import Functionality........................................................................................................ 4-18
Chapter 5: SmartAdaptor Add-On Adapters...................................................................... 5-1

Java Adapter ................................................................................................................................. 5-2
ARJCA................................................................................................................................... 5-2
AR Java PKCS..................................................................................................................... 5-10
Entrust Adapter ........................................................................................................................... 5-14
X.509 Toolkit.............................................................................................................................. 5-16
Overview.............................................................................................................................. 5-16
Additional Reading .............................................................................................................. 5-21
Working with the X.509 Toolkit.......................................................................................... 5-22
Constants.............................................................................................................................. 5-38
General Data Types ............................................................................................................. 5-51
Functions.............................................................................................................................. 5-73
PKCS#10,#7 Certificate Request and Reply............................................................................... 5-86
General Data Types ............................................................................................................. 5-87
Functions.............................................................................................................................. 5-93
Programming Samples ......................................................................................................... 5-98
PKCS#12 Import and Export .................................................................................................... 5-116
Functions............................................................................................................................ 5-116
Chapter 6: SmartAdaptor Utilities ...................................................................................... 6-1

AR Genie Utility ........................................................................................................................... 6-1
User Mode Token Operations................................................................................................ 6-2
Administrative Token Operations .......................................................................................... 6-4
Running AR Genie From Command Line............................................................................ 6-19
PKCS#12 Import/Export Utility ................................................................................................. 6-24
Import Operation ................................................................................................................. 6-24
Export Operation ................................................................................................................. 6-24
DlmLoad Utility.......................................................................................................................... 6-26
Chapter 7: Installation ......................................................................................................... 7-1

Installation Packages..................................................................................................................... 7-1
Installation From CD .................................................................................................................... 7-2
Installing On a Clean Machine............................................................................................... 7-2
iii
CryptoKit Developer's Guide
Modifying or Removing an Existing Installation....................................................................7-7

Upgrading an Existing Installation .........................................................................................7-8
Silent Installation ...........................................................................................................................7-9
Centralized Installation from Active Directory............................................................................7-11
Step 1 – Create CryptoKit Installation Package on the Server .............................................7-11
Step 2 – Create the Startup Script.........................................................................................7-12
Step 3 – Assign the Startup Script ........................................................................................7-14
Centralized Installation Using Microsoft SMS 2003 Server........................................................7-20
Step 3 – Assign CryptoKit Package to SMS Collection .......................................................7-20
Installation in Citrix Environment ...............................................................................................7-26
Citrix Server Configuration ..................................................................................................7-26
Citrix Client Configuration...................................................................................................7-28
Installation in Terminal Server Environment...............................................................................7-31
Terminal Server Configuration.............................................................................................7-31
Client Configuration .............................................................................................................7-32
CryptoKit Installation Package ....................................................................................................7-35
Customizing the Installation ........................................................................................................7-37
String Constants....................................................................................................................7-38
Feature Names ......................................................................................................................7-38
CK_SETUP.INI....................................................................................................................7-40
CK_LANG.INI.....................................................................................................................7-47
CryptoKit Files and Registry Entries ..........................................................................................7-55
General Guidelines ...............................................................................................................7-55
SmartAdaptor .......................................................................................................................7-56
AR Client Service and Daemon............................................................................................7-70
ARCSP .................................................................................................................................7-72
Software Token ....................................................................................................................7-78
Single Sign On (SSO)...........................................................................................................7-79
PrivateSafe Reader ...............................................................................................................7-81
MiniKey5..............................................................................................................................7-84
Siemens PKCS#11 Provider.................................................................................................7-85
Ifdh Driver for Siemens MiniKey.........................................................................................7-86
Terminal Services.................................................................................................................7-88
Citrix Server .........................................................................................................................7-88
Utility Programs ...................................................................................................................7-89
SDK Files .............................................................................................................................7-91
Entrust Plug-in in the Registry..............................................................................................7-92
Shortcuts...............................................................................................................................7-93
Package Information.............................................................................................................7-93
iv
Chapter 1: Introduction to Cryptography
In this chapter we review some of the concepts and terms of modern
cryptography. If you are new to this field, it might be worthwhile to consult
introductory reference material. Three sources worth referencing are:
Applied Cryptography, Second Edition, Bruce Schneier, John Wiley & Sons,
1996.
Contemporary Cryptology, Edited by Gustavus J. Simmons, IEEE press, 1992.
Security for Computer Networks, Second Edition, D.W. Davies and W. L. Price,
John Wiley & Sons, 1989.
Security Issues
Cryptographic-Strength Data Security deals with four primary issues:
♦ Two-way participant authentication – During data exchange, each side
wants to be sure of the identity of the other.
♦ Data authentication (integrity) – This is a general term that roughly
means the data is reliable and was not tampered with.
♦ Data secrecy – This is needed when sensitive data is transferred.
♦ Non-repudiation – Provides a mechanism for the recipient to prove that
the information was generated by a particular sender.
Cryptographic Algorithms
Data security as described above is maintained through the use of cryptographic
algorithms. A cryptographic algorithm is a method, usually based on some
mathematical function, used for authentication and/or secrecy. Some
applications require only secrecy or only authentication; others require both. The
security of a cryptographic scheme resides entirely in the secret key, and not in
the secrecy of the algorithm. Cryptographic schemes are classified as either
Symmetric or Asymmetric.
1-1
1 CryptoKit Developer's Guide
Symmetric Schemes
Classical (Symmetric) schemes, such as DES, are based on a common secret key
for both encryption and decryption:
User A User B
Ciphertext
Key Encrypt Decrypt Key
Cleartext Cleartext
In Symmetric schemes, authentication is often performed with Message

Authentication Codes (MACs) in the following way:
1. The initial vector (which may include date & time) is encrypted and
joined (i.e., XORed) with the first block of data.
2. The result is encrypted and joined with next block of data.
3. The final block is MAC - clearly a function of the initial vector and
the entire message.
1-2
Introduction to Cryptography 1
User A User B
Key MAC
Compute MAC Verify MAC Key
Cleartext + Cleartext +
Initial Vector Initial Vector
Symmetric schemes have both strengths and weaknesses. Their strengths include
fast encryption/decryption and participant/data authentication using MACs.
However, their weaknesses include the need for a separate (secure) channel for
key transfer, and the need for very complex key management.
Asymmetric Schemes
Asymmetric cryptographic schemes are based on principles that differ to those
governing Symmetric schemes in the following ways:
♦ The encryption key is different than the decryption key.
♦ The decryption key cannot be calculated from the encryption key (i.e. it
is a one-way function).
Such a scheme is also called a Public Key System, because the encryption key is
made public. This way, a complete stranger can use the encryption key to
encrypt a message, but only someone with the corresponding decryption key can
decrypt the message. The encryption key is called the Public Key, and the
decryption key is called the Private Key. The best-known Asymmetric scheme is
RSA.
Asymmetric schemes provide secrecy by having the sender use the receiver's
public key to encrypt the data, while only the intended receiver, using his private
key, can decrypt the data and use it:
1-3
User A User B
Ciphertext
Public Key Encrypt Decrypt Private Key
Cleartext Cleartext
Asymmetric schemes provide authentication by using Digital Signatures in the

following way:
♦ A hash function generates a result that reflects an entire message
(including date & time).
♦ The result is signed with the sender’s private key.
♦ The signature is verified by the receiver using the sender’s public key:
User A User B
Generate Digital Verify

User A Signature User A
Digital Digital
Private Key Signature Signature Public Key
Date & Time Date & Time
Digital signatures are applied to authentication of both participants and data.

They also ensure non-repudiation.
1-4
Asymmetric schemes offer both strengths and weaknesses. Their primary
weakness is that encryption/decryption is relatively slow, involving intensive
computations. Their many strengths include:
♦ Fewer security issues in key transfer (all public).
♦ Simple key management (N users => N public keys).
♦ Participant/data authentication using digital signatures.
♦ Non-repudiation through digital signatures.
Symmetric and Asymmetric schemes are useful, and both have strengths and
weaknesses. Thus, it would be ideal to combine the strengths of both and avoid
the weaknesses. The following section describes an attempt to do this.
Hybrid Symmetric/Asymmetric Schemes
Hybrid Symmetric/Asymmetric schemes (e.g., DES + RSA), combine the best

of both worlds:
♦ Strong RSA two-way authentication of participants.
♦ Simple RSA key management (N users => N public keys).
♦ Secure RSA transfer of DES keys (per session).
♦ Fast DES encryption/decryption.
♦ RSA/DES data authentication (digital signatures/MACs).
♦ Transaction non-repudiation using RSA digital signatures.
We will now review the above points.
1-5
Two-way Authentication
Two-way authentication is achieved with an RSA-based Challenge-Response
protocol performed in both directions at the beginning of each session.
Suppose, for example, that we have a Host and a Client.

♦ Host sends Client a random string (“challenge”).
♦ Client signs string with Client’s private key and sends it back
(“response”) to Host, along with Client’s identity.
♦ Host finds Client’s public key in the database that stores all of the public
keys, and reads the response by using that key.
♦ If "response" matches "challenge" that Host sent to Client initially, then
Host knows that Client is indeed who it claims to be, i.e. host has verified
that the Client is a legitimate receiver of secret data.
♦ A similar protocol is performed in the other direction, so that the Client
will not log on to an illegitimate host.
Secure Key Transfer

Secure key transfer is achieved by an RSA-based exchange of session-specific
encryption DES keys at the beginning of each Client-Host session:
♦ After both sides authenticate each other, they exchange DES encryption
keys, “packaged” within RSA-encrypted messages.
♦ The session key is the result of joining the two keys.
♦ DES used for encryption/decryption of any further data throughout that
session.
♦ DES keys are per session (new session => new DES keys are
exchanged).
1-6
Fast Encryption/Decryption
Fast Encryption/Decryption of actual data is DES-based:
User A User B
Ciphertext
Key Encrypt Decrypt Key
Cleartext Cleartext
Data Authentication
As for data authentication, this is done with MACs:
User A User B
MAC
Key Compute MAC Verify MAC Key
Initial Vector Initial Vector
1-7
Transaction Non-Repudiation
Transactions that involve payments are authenticated with a Digital Signature,
which also ensures non-repudiation.
User A User B
Generate Digital Verify

User A Signature User A
Digital Digital
Private Key Public Key
Signature Signature
Date & Time Date & Time
1-8
] Chapter 2: Component-Related
Technologies
CryptoKit enables the use of several types of smart card solutions including
smart cards, readers and USB smart card tokens, such as MiniKey, which
enhances security, allows storage of sensitive data and the use of secure PINs.
CryptoKit also enables the full emulation of smart card tokens in software,
providing virtual (software-only based) tokens.
Several basic elements contribute to CryptoKit’s architecture:

♦ Key media (smart cards, tokens, virtual tokens)
♦ Media independence
♦ Platform independence
♦ Advanced cryptographic capabilities
♦ Simplicity
♦ High performance
♦ Stability and exception handling
♦ Compliance with industry standards
2-1
Key Media
One of the most important aspects of public key cryptography systems is

protecting the secrecy of the private key. Therefore, this key is securely stored in
a location called the key media. Key media can also store other user-related
information as well as application data that may need protection from
unauthorized use. CryptoKit supports several types of key media:
♦ PrivateCard smart card
♦ Virtual tokens (Software)
♦ MiniKey Token
♦ PrivateServer HSM
♦ CoSign server
Smart Cards
Smart card chips are secure, single chip microprocessors, produced in a way that
prevents external probing of their memory contents. With a single serial I/O port
as the only means of communication with the outside world and with no external
bus, smart card chips provide a safe place for storing secret information such as
encryption keys, passwords and secret user data. This sensitive information is
kept in non-volatile memory, which provides long-term storage and does not
depend on continuous power supply. The smart card microprocessor runs the
smart card operating system, which controls the resources of the smart card. The
operating system communicates with the outside world using a protocol and
commands specified in ISO standard 7816. Data is organized in a hierarchical
file system (tree).
Password Protection
The most common method for protecting data is by use of a password, which
must be presented before permitting access, or modification of data in files. To
2-2
Component-Related Technologies 2
prevent the type of attack that presents a large number of password attempts in
succession, a smart card operating system can lock the smart card from further
password presentations after a small number of unsuccessful attempts.
Cryptographic Operations
Since encryption keys are kept on the smart card and are not exposed to the
outside world, the algorithms that use them must also reside on the card. Most
smart cards contain symmetric encryption algorithms (such as DES) as part of
the operating system. More advanced smart cards implement asymmetric
algorithms, or public key cryptography, such as RSA, utilizing a special
arithmetic processor that is optimized for performing fast modular arithmetic.
Applications
With the features described above, smart card chips can be used for a wide range
of applications, including: Network login, personal identification, authentication,
digital signatures, e-commerce and more.
Smart cards are the most flexible solution available for enforcing controlled
access to Web pages, Internet services, databases and applications. They
empower organizations to distribute sensitive information over the Net by
implementing user authentication, digital signatures and data encryption.
CryptoKit enables integration of smart cards in any PKCS#11-standard or CAPI

application. It enables integration with applications from vendors such as
Microsoft, Netscape, Baltimore, Entrust, CheckPoint and many more.
Removal/Insertion
Smart cards can be changed during application execution. When the smart card
is removed from the reader, applications automatically log off. When the new
smart card is inserted, CryptoKit detects the smart card type and, if supported,
works with it.
2-3
PrivateCard, developed by AR, has the following advantages and features:

♦ RSA functionality Supports generation of RSA private and public keys
up to 2048-bits.
♦ Hardware-based random number generation Approaching pure
randomness.
♦ Support for multi-application and multiple key storage Multiple keys
may be stored on the token and keys may be accessed by several
applications.
♦ Access control and PIN verification PrivateCard provides a
sophisticated mechanism offering Challenge/Response PIN presentation
to prevent replay, ensuring that only authorized users can access data
stored on the chip.
♦ Authorization masks PrivateCard provides a secure file-store and
hierarchical-directory structure that allows authorization/access rules to
be established for each file and directory on the card.
♦ Support for industry standard algorithms such as
DES (FIPS PUB 46)
SHA-1 (FIPS PUB 180-1) used for verification of PINs and access
control
RSA algorithm is used for digital identity
ISO 7816 smart card communication protocol
♦ Key generation RSA private keys are generated and used on the smart
card itself. RSA private keys are never moved from the smart card, and
thus cannot be compromised by any other code.
♦ Password policy PrivateCard smart card has a built-in password-related
policy handling (such as password validity period, minimal password
length, minimal password change period).
♦ Objective time servers PrivateCard smart card can work with secure
time servers (although this feature is not used by CryptoKit).
2-4
♦ X.509 certificates PrivateCard can conveniently store X.509 certificates
to provide digital identity. With its enhanced storage capacity of up to
64K, PrivateCard can be used to secure a current application, and store
additional personal data in the future, such as biometric information.
PrivateCard can be used with all types of smart card readers supported by
CryptoKit.
Models of PrivateCard
CryptoKit supports different PrivateCard models that run Algorithmic Research

smart card operating system. The following table shows the different models:
Smartcard Chip Memory RSA Communication Operating

Size Capability Speed (baud) System Version
Siemens* 8K 1024 bit 9600 1.2
Atmel 32K 1024 bit 9600 1.13

AT90SC3232C* 38400 1.14-1.17
Atmel 64K 2048 bit 38400 2.21-2.22

AT90SC6464C 115200 2.30-2.34
Atmel 144K 2048 bit 115200 3.01

AT90SC144144CT
* This model is supported for backward compatibility and is not available

anymore.
Software Key Media
CryptoKit supports the use of virtual tokens, which store all PKCS#11 objects in
a specially formatted file that can be created on the hard disk or on a diskette.
Since all cryptographic operations are performed in software, no additional
drivers need to be installed.
2-5
The distinction between slot and token for software tokens is irrelevant, so these
files can be considered as both slot and token simultaneously.
As a development solution, software key media (virtual tokens) are simpler and
cheaper to implement than smart cards, but at the same time, they provide a
lower level of security. For convenience, you could begin the development
process utilizing key files (software key media), since these make it easy to
maintain a separation of potential development problems from possible
hardware issues. However, it is recommended to switch to smart cards at a later
stage of development for enhanced security, as well as for distribution purposes.
When an application uses software key media, all security-related operations are
performed in the computer. Security depends on the operating system used. All
protected data units in the key file are encrypted. Even in the event of
unauthorized access, the protected data in a key file cannot be compromised as
long as the passwords remain unknown.
Software tokens support RSA 4096 bit operations. A special library, which was
specifically designed for Pentium 4 computers, provides very high performance
of the RSA operations.
CryptoKit supports two types of software key media: static and dynamic. The
number of virtual slots, the maximum number of dynamic slots (which must be
less than the total number of slots) and the directory name for virtual tokens is
stored in the System Registry. System administrators can change these defaults.
For more information how to change the defaults for software tokens refer to
Chapter 7.
Calling the function C_GetSlotInfo can retrieve the name of a virtual token. The
Description field contains only the software token file name, not including the
file path.
Virtual tokens can be initialized and user PINs set by calling C_InitToken and
C_InitPIN functions. For dynamic slots, the appropriate file is created and
initialized during C_InitToken.
2-6
Note: During the first initialization of a virtual token, the value supplied as the
parameter of SO PIN is not checked and it is taken as the initial value of SO
PIN.
Static Software Slots

When software token is installed, CryptoKit places it in a specific directory (the
default is <TARGETDIR>\sft_tok subdirectory. During startup (C_Initialize),
CryptoKit enumerates all the files in this directory and presents them as separate
slots to the application. The maximum number of software slots is set to 2 by
default, but users can configure it according to their needs. Regardless of how
many files are actually stored in the folder, this setting determines the maximum
number of software slots available.
When the folder contains fewer files than the maximum, the system displays the
unused number of software slots as empty of tokens. In this case, if new files are
added to the folder, the system continues to display the same number of unused
empty slots until the user fully exits (C_Finalize) and re-initializes the CryptoKit
application.
Dynamic Software Slots

CryptoKit also permits the use of virtual slots that are not placed in the specified
folder. These are called dynamic slots. CryptoKit always displays a dynamic slot
as initially empty, but certain tokens can be bound to it (inserted) using
CryptoKit’s C_EXT_Bind function (see Chapter 3). The virtual token’s file
name is given as a parameter to this function. When it succeeds, an empty slot
that was allocated as dynamic is assigned to the token. The binding between a
dynamic slot and a token can be released by calling to the C_EXT_Unbind
function.
An application always retrieves the full slot list, containing both non-dynamic
and dynamic slots. If no dynamic slots were configured, the system defines all
software slots as non-dynamic, blocking the capability of dynamic insertion of
tokens.
2-7
MiniKey Token
MiniKey, AR’s portable, personal token, allows users to conveniently manage

their keys and authenticate their identity when connecting to enterprise, e-
commerce or other secure applications as well as to store data securely on token.
With AR’s advanced ISO standard smart card

chip operating system, MiniKey has its own
secure file storage and RSA functionality,
enabling a full range of cryptographic services
and secure connection.
PKI-Ready
Unlike most other solutions, including memory-based tokens or password

generators that do not support secure PKI features such as on-token key
generation, MiniKey is suitable for a wide range of security applications
including PKI based applications.
MiniKey performs cryptographic functions in a secure, isolated environment,

just like a smart card. Private information cannot be retrieved or changed even if
the token is tampered with.
Powerful, Convenient and Affordable
Today’s technology has produced new, more powerful processing chips.

Algorithmic Research has taken advantage of this potential and has developed
an advanced chip operating system that enables MiniKey to perform
cryptographic functionality on the chip itself.
Thanks to its standard interface and USB Plug &Play capability, MiniKey is
easy to use and does not require any additional hardware. MiniKey is an overall
low-cost solution, since the token itself is inexpensive and it eliminates the need
for a reader, making MiniKey the most attractive, high security PKI token
available.
2-8
Since MiniKey contains AR’s PrivateCard smart card chip, the detailed
description of PrivateCard’s functionality and features provided above is equally
relevant to AR’s MiniKey token.
With its cutting-edge cryptographic performance, MiniKey can replace both

smart card and reader in smart card-based applications.
Universal Serial Bus (USB)
The Universal Serial Bus (USB) port is used to connect both fast peripheral
devices such as printers, scanners and digital cameras, as well as slow
peripherals such as keyboard, mouse and smart card reader or token. All these
devices can be connected to the same USB port and they are identified by the PC
host controller, which assigns each one a distinct I/O address. USB hubs enable
connection of multiple devices (up to 127) concurrently to the same PC.
Using the computer’s USB port, AR’s MiniKey acts as a USB device, and offers
the same advantages as any other USB peripheral. Since these devices directly
connect through the USB hub, there is no need for special configuration, making
it simple and transparent for users to plug in MiniKey and use its enhanced
security features.
Models of MiniKeys
There are some models of MiniKeys available. The following table shows the
difference between them:
Model Memory RSA Smartcard Operating Driver ITSEC
Size Capability Chip System Cert.
Version
MiniKey* 32K 1024 bit Atmel AR Proprietary No

AT90SC3232C 1.12-1.14
MiniKey5 32K 1024 bit Atmel AR - PC/SC No

AT90SC3232C 1.14-1.16 - Signed
- CryptoIdentity
device
- Linux
2-9
Model Memory RSA Smartcard Operating Driver ITSEC

Size Capability Chip System Cert.
Version
MiniKey5 64K 2048 bit Atmel AR - PC/SC No

AT90SC6464C 2.21-2.22 - Signed
- CryptoIdentity
device
- Linux
Siemens 32K 1024 bit Siemens Siemens - PC/SC Yes

MiniKey SLE66CX320P CardOS - Signed
M4.01 - CryptoIdentity
or
IFDH device
Siemens 32K 1024 bit Siemens Siemens - PC/SC Yes

MiniKey SLE66CX322P CardOS - Signed
M4.01a - CryptoIdentity
device
* This model is supported for backward compatibility and is not available

anymore.
Hardware Security Module – PrivateServer
CryptoKit enables PKI applications to use AR’s hardware security module

(HSM) called PrivateServer. The PrivateServer enables organizations to perform
all their PKI based activities such as digital signatures in a centralized and
secure way (the PrivateServer is FIPS 140-1 level 3 certified). It is connected to
the organization network and performs the requested cryptographic operations.
It supports many hash and symmetric algorithms as well as RSA of up to 4096
bit.
For more information about the functionality and operation of the PrivateServer,
refer to the PrivateServer installation manual and to PrivateServer API guide.
2-10
CoSign – Digital Signatures Appliance
CoSign is a non-forgeable, simple-to-use digital-signature appliance. It delivers

an innovative way to electronically sign documents, forms and, messages within
major applications such as MS-Word, Adobe-Acrobat, ERP and Content
Management systems. CoSign creates digital signatures, based on PKI
technology and ensures the data integrity of the transactions and documents.
CoSign is connected to the organization network and user-management system.

Through CryptoKit, CoSign supports the three most commonly used
cryptographic APIs available: Microsoft CAPI, PKCS#11, and JCA/JCE. In
addition, CoSign comes with AR’s Signature API (AR-SAPI), which provides
an easy way to integrate with digital signature applications by providing all the
functionality needed to handle PKI based operations and graphical signatures.
For more information about the functionality and operation of the CoSign, refer
to the CoSign manual.
Smart Card Readers
In order to enable smart cards to communicate with PCs, workstations, laptops,

etc., users must attach smart card reader devices. AR’s CryptoKit supports all
PC/SC and CT-API compliant readers, as well as those developed by AR:
PrivateSafe®, CryptoSafe, and PrivateSafe PCMCIA readers and the MiniKey
USB token.
2-11
The PrivateSafe and CryptoSafe readers have the unique capability to receive
the user’s PIN when he enters it and then present it securely to the inserted smart
card. The following table illustrates the differences between these options:
PrivateSafe® CryptoSafe PrivateSafe MiniKey

PCMCIA
Reader
Tokens Supports any ISO Supports Supports any MiniKey is also a

7816-compliant PrivateCard. ISO 7816- token.
smart card. compliant smart
Requires loading
card.
the appropriate
DLM.
Protected Supports Supports Does not Does not support
Authentication support
Path (Secure
Keypad Password
Entry)
Date Uses date Includes an Uses date Uses date supplied by

supplied by the internal clock. supplied by the the host computer.
host computer. host computer.
Connection to Keyboard Can be connected Recommended Recommended for any
Host Computer connection only. to the PC in for use with PC/laptop with a USB
Designed for use various ways. laptop port
with desktop CryptoKit computers
computers. supports only the
keyboard
connection type.
Designed for use
with desktop
computers.
Plug&Play Does not support Does not support Supports Supports
2-12
PrivateSafe
PrivateSafe advantages include:

♦ AR’s patented keyboard connectivity Ensures full control for all
communications between the keyboard and PC. PrivateSafe disables
keyboard communications to and from the computer when sensitive
information is entered. During regular operation, the keyboard
communicates transparently with the PC.
♦ Secure communications and PIN entry Prevents exposure of sensitive

data entry in a software environment. All secret information and PINs
entered via the keyboard are protected by PrivateSafe and not exposed to
"shadowing" or other software-based attacks.
♦ Regular keyboard functionality Used for convenient and secure
PIN-pad entry. Conventional devices, equipped with a small keypad to
prevent exposing PINs to the workstation environment, suffer from
several drawbacks: increased manufacturing cost keypad quality
lower than that of PC keyboard inconvenient—frequent switching
between PC keyboard and the device’s keypad.
♦ Easy to install
♦ No need for external power supply PrivateSafe draws its power from
the keyboard port.
2-13
♦ Does not occupy a serial communication port Unlike conventional

smart card readers, PrivateSafe connects through the keyboard port.
♦ Supports Windows 98, ME, NT, 2000, XP and 2003.
♦ PrivateSafe specifications:
Complies with ISO 7816 standard smart cards
Multiple mode light indication
Physical dimensions: 73x78x16 mm
Weight: 60 g (net)
Power consumption: Idle- 30 mA, Operating-60 mA maximum
Power supply: 5 volts.
Communication to host via keyboard interface
Keyboard management support
Programmable interface from 9600 baud to 69 Kbaud
Connector cable length: 150 cm
Adapter for a standard PC or PS/2 keyboard connector
PrivateSafe PCMCIA
The PrivateSafe PCMCIA reader is a

standard PCMCIA device for use with
laptop computers. It has a standard PC/SC
driver, which can be installed by the
CryptoKit installation.
2-14
CryptoSafe
CryptoSafe is a smart card reader for the PC and workstation. CryptoSafe

provides the same isolated environment as PrivateSafe for performing sensitive
data-security functions with both PrivateCard. CryptoKit supports only the
keyboard model of CryptoSafe.
CryptoSafe features include:

♦ Broad range of security functions performed internally
♦ Secure PIN verification
♦ Mutual smart card/reader authentication
Note: If you use AR’s CryptoSafe reader, you have to load into it an appropriate
DLM. The DLM is program that is digitally signed by AR special private key
and the signature is verified once the program is loaded into the reader, so that
no information (passwords or private keys) can be compromised.
2-15
Media Independence
The CryptoKit API is media independent – it can be used for various types of
key media with minimal or no change. For example, an application written to
use key files can make use of smart cards or MiniKeys with minimal or no
change at all.
Platform Independence
CryptoKit has an ANSI standard, C-like API that is the same for all supported
platforms. An application using CryptoKit can be smoothly ported to any
supported platform. Currently, CryptoKit is available for the following
platforms:
♦ Windows (98, ME, NT, 2000, XP and 2003)
♦ Linux (RedHat, SUSE and Debian)
CryptoKit may be used from C/C++ programs or any other development

environment that can access C API, such as Visual Basic, Delphi, or
PowerBuilder.
CryptoKit has a Java interface that allows Java applications to utilize all
supported devices. It includes two Java libraries: a proprietary Java adapter that
provides PKCS#11 style API to Java applications and a standard Java
Cryptography Architecture (JCA) provider. For more information refer to
chapter 5.
The file format used by CryptoKit to store a virtual token is identical for all
platforms. This guaranties that key files can be created and used across different
platforms.
2-16
Advanced Capabilities
CryptoKit supports a wide variety of cryptographic algorithms and functions:
Symmetric Algorithms Hash Algoritms

DES MD5
2DES SHA-1
3DES SHA256
AES SHA384
RC2 SHA512
RC4 RIPEMD160
Asymmetric Algorithms Other

RSA SSL
DSA TLS
Diffie-Hellman AR Proprietary
Simplicity of Use
CryptoKit provides application programmers with cryptographic tools to cope

with the complexity of modern cryptography in an easy-to-use format via the
API. Knowledge of cryptography or cryptographic algorithms is not required.
Performance
The implementations of cryptographic algorithms used by CryptoKit are among

the fastest available, which is especially important when dealing with on-line
encryption or large numbers of public key operations.
2-17
Stability and Exception Handling
CryptoKit is fully designed for server side applications. It has full exception
handling mechanism for stability and recovery from unexpected errors. In
addition, it includes a sophisticated logging mechanism that allows collection of
data to be used for investigation of such problems if they occur.
Compliance with Industry Standards
CryptoKit supports the most common cryptographic standards used by the

software industry.
CryptoKit provides a full implementation of PKCS#11 V2.20 standard as well

as Microsoft’s CSP provider for RSA and Schannel cryptographic operations.
Algorithmic Research’s implementation includes most of the functionalities
defined by these standards. In addition to that, CryptoKit includes a PKCS#11
like Java library and a standard Java Cryptography Architecture (JCA)
provider.
Algorithmic Research is comitted to maintaining compatibility with upgrades to

these standards in the future.
2-18
Chapter 3 SmartAdaptor Technology
CryptoKit is a powerful cryptographic platform that includes the main Software

Development Kit (SDK), as well as several plug-ins, adapters and extensions.
The following list summarizes the overall CryptoKit environment:
CryptoKit Component Description
SmartAdaptor Supplies core cryptographic functionality through PKCS#11

API
CSP adapter Supplies Microsoft CAPI functionality for CAPI based

applications such as Internet Explorer, Outlook, smart card
logon, Microsoft Office, Microsoft VPN, IIS and more.
The CSP adapter is based on the PKCS#11 provider.
Entrust adapter Serves as plug-in for Entrust products
Java adapter Includes two libraries:

• A standard Java Cryptography Architecture (JCA)
provider.
• A proprietary adapter that provides PKCS#11 style

API to Java applications.
Standard applications Serves as plug-in for Netscape Navigator, Baltimore

PKCS#11 plug-in
X.509 extension These extensions provide functionality for working with X.509
certificates (request, response, parsing)
PKCS#10,PKCS#7
extension
PKCS#12 extension This extension provides import and export functionality of

PKCS#12 files (PFX)
3-1
General Concepts
SmartAdaptor, providing the main CryptoKit functionality, contains an

independent library that adapts PrivateCard smart cards, MiniKey tokens,
PrivateServer HSM, CoSign, PrivateSafe reader and readers from a range of
vendors to enable them to secure a large variety of applications. SmartAdaptor
also serves as the base for building high security adapters, plug-ins and
extensions.
CryptoKit Architecture
CryptoKit’s main component, SmartAdaptor, is a library that transforms the
PKCS#11API, into multifunctional smart card architecture. SmartAdaptor
creates a connection between several PKCS#11 providers and enables smart
card and reader independence from implementations.
3-2
SmartAdaptor Technology 3
Applications
MS CAPI
Applications
User
Java PKCS#11-based Applications
Applications e.g., e.g., Entrust, Baltimore, Netscape
IE/Outlook
Extensions
Adapters
Java CAPI Entrust PKCS PKCS
X.509
Adapter Adapter Adapter #10,7 #12
PKCS#11
Registration
Extension
API *
User Interface
SmartAdaptor
11
S# I SmartAdaptor Engine for
C P
PK A Multi-thread, Multi-process,
Multi-slot, Multi-provider
Reader
Smartcard
Provider
Provider API
API
Providers
Core PKCS#11 AR PrivateCard CT-API PCSC Proprietary

Interface
Providers Provider Readers Readers Readers
* The Registration API can be used by all applications built on SmartAdaptor

and must be used by any provider that operates under SmartAdaptor, except for
PCSC readers.
3-3
SmartAdaptor General Concepts
SmartAdaptor supports three different types of providers: Core, Reader and

Smart card.
Core providers are stand-alone PKCS#11 providers requiring no change to

their existing structure. SmartAdaptor enables various PKCS#11 providers to
work together in a way that is transparent to the user, with no configurational
changes needed.
A Reader provider, written for each smart card reader, supplies the reader’s
operational functionality. SmartAdaptor supports three kinds of readers: PCSC,
CT-API and proprietary readers. PCSC readers do not need to be registered by
SmartAdaptor since they are already registered in the Windows operating
system, allowing SmartAdaptor to detect them automatically.
When a reader has two (or more) supported interfaces, and one of them is PCSC,
SmartAdaptor may display the reader twice on the slot list. In order to prevent a
multiple listing of the same reader, SmartAdaptor provides an option in the API
to block the display of a particular reader as a PCSC device. In this case, it is
listed as a proprietary device only.
In order to register a CT-API or proprietary reader, the reader’s dll (module)

must be supported. The module should contain the functions used to access the
reader as well as an entry function, which is used to retrieve the pointers to
reader functions.
SmartAdaptor only supports AR PrivateCard Smart card provider. The smart
card provider translates the high level PKCS#11 API into a sequence of smart
card ISO 7816 commands, which in turn, are transmitted through the Reader
provider. Third party smart cards can only be supported using their given
PKCS#11 core provider dll.
SmartAdaptor supports multi-slot, multi-provider, multi-process, and

multi-thread environments for applications. Since the PKCS#11 standard does
not support multi-provider architectures, SmartAdaptor converts its
multi-provider architecture to the PKCS#11 multi-slot architecture and
enumerates Reader slot providers in addition to Core slot providers.
3-4
Main SmartAdaptor Cryptographic API
The PKCS#11 standard. is described in Cryptoki 2.11 API, available for

downloading from the RSA Web site:
www.rsasecurity.com\rsalabs\pkcs\pkcs-11\index.html.
Algorithmic Research has added important enhancements to the basic API,

enabling developers to amplify the level of security for communications with
Internet software and solutions providers such as Netscape and Microsoft, and
incorporate X.509 certificates in their applications.
PKCS#11 General Terminology
The PKCS#11 standard utilizes terms whose specific implications are listed
below:
Mechanisms Security algorithms performed with various types of keys and other
cryptographic objects
Objects Data, certificates and keys stored on tokens
Tokens Smart card, MiniKey or other key media
Slots Smart card readers connected to application computer (e.g.,
Algorithmic Research’s PrivateSafe®, CryptoSafe and PrivateSafe
PCMCIA readers)
Protected PIN entry from protected keypad, finger-print reader, and other
Authentication devices
Path
3-5
CryptoKit PKCS#11 Architecture
CryptoKit PKCS#11 includes a high-level Application Programming

Interface (API) together with supporting cryptographic modules. The
following diagram illustrates the security services and tokens supported
by CryptoKit PKCS#11 as well as its relationship to applications.
AR or 3 rd Party Applications
AR CryptoKit PKCS#11
Application Programming Interface (API)

Standard PKCS#11
PIN Key Key Encryption/ Signatures/ PK-User Certificate

Management Management Exchange Decryption Verification Authentication Processing
(policies)
Tokens
MiniKey ISO Smartcard – Private Card
PrivateServer CoSign
3-6
Supported Functions and Mechanisms
Algorithmic Research’s PKCS#11 library supplies all the functions documented

in the Cryptoki PKCS#11 2.11 API in a fully compatible form.
To function properly with a PKCS#11 application, the user’s token must be

initialized and his PIN set, which is accomplished by calls to C_InitToken
and C_InitPIN respectively. In some cases, such as a Netscape plug-in, the
token must be initialized and the PIN set prior to use with the plug-in.
In normal cases, the user initializes his token and sets the PIN when working
with the library. However, for convenience, the special utility argenie.exe is
included in the CryptoKit installation, containing the C_InitToken and
C_InitPIN functions, enabling preparation of the token to use. The utility can
be used after installation to initialize additional tokens and PINs on the tokens
(see Chapter 6).
The full set of RSA, DSS, Diffie-Hellman, RC2, RC4, DES, Triple-DES,
Double-length DES, AES, MD2, MD5, SHA-1, SHA-256, SHA-384, SHA-512,
RIPEMD160, SSL3, TLS and key derivation mechanisms are supported by the
CryptoKit PKCS#11 library. Additional proprietary algorithms are also included
for backward compatibility with older versions of CryptoKit (Ver 1.63). The
following table lists all supported mechanisms:
Mechanisms Functions
CKM_RSA_PKCS_KEY_PAIR_GEN GenerateKeyPair
CKM_RSA_PKCS Encrypt/Decrypt, Sign/Verify,

SignRecover/VerifyRecover,
Wrap/Unwrap
CKM_RSA_PKCS_OAEP Encrypt/Decrypt, Wrap/Unwrap
3-7
CKM_RSA_PKCS_PSS Sign/Verify
CKM_RSA_9796 Sign/Verify,
SignRecover/VerifyRecover
CKM_RSA_X_509 Encrypt/Decrypt, Sign/Verify,

SignRecover/VerifyRecover,
Wrap/Unwrap
CKM_MD2_RSA_PKCS Sign/Verify
CKM_MD5_RSA_PKCS Sign/Verify
CKM_SHA1_RSA_PKCS Sign/Verify
CKM_RIPEMD160_RSA_PKCS Sign/Verify
CKM_DSA_KEY_PAIR_GEN GenerateKeyPair
CKM_DSA Sign/Verify
CKM_DSA_SHA1 Sign/Verify
CKM_DH_PKCS_KEY_PAIR_GEN GenerateKeyPair
CKM_DH_PKCS_DERIVE Derive
CKM_GENERIC_SECRET_KEY_GEN GenerateKey
CKM_RC2_KEY_GEN GenerateKey
CKM_RC2_ECB Encrypt/Decrypt, Wrap/Unwrap
3-8
CKM_RC2_CBC Encrypt/Decrypt, Wrap/Unwrap
CKM_RC2_CBC_PAD Encrypt/Decrypt, Wrap/Unwrap
CKM_RC2_MAC_GENERAL Sign/Verify
CKM_RC2_MAC Sign/Verify
CKM_RC4_KEY_GEN GenerateKey
CKM_RC4 Encrypt/Decrypt
CKM_DES_KEY_GEN GenerateKey
CKM_DES_ECB Encrypt/Decrypt, Wrap/Unwrap
CKM_DES_CBC Encrypt/Decrypt, Wrap/Unwrap
CKM_DES_CBC_PAD Encrypt/Decrypt, Wrap/Unwrap
CKM_DES_MAC_GENERAL Sign/Verify
CKM_DES_MAC Sign/Verify
CKM_DES2_KEY_GEN GenerateKey
CKM_DES3_KEY_GEN GenerateKey
CKM_DES3_ECB Encrypt/Decrypt, Wrap/Unwrap
CKM_DES3_CBC Encrypt/Decrypt, Wrap/Unwrap
CKM_DES3_CBC_PAD Encrypt/Decrypt, Wrap/Unwrap
CKM_DES3_MAC_GENERAL Sign/Verify
CKM_DES3_MAC Sign/Verify
CKM_AES_KEY_GEN GenerateKey
3-9
CKM_AES_ECB Encrypt/Decrypt, Wrap/Unwrap
CKM_AES_CBC Encrypt/Decrypt, Wrap/Unwrap
CKM_AES_CBC_PAD Encrypt/Decrypt, Wrap/Unwrap
CKM_AES_MAC Sign/Verify
CKM_AES_MAC_GENERAL Sign/Verify
CKM_MD2 Digest
CKM_MD2_HMAC_GENERAL Sign/Verify
CKM_MD2_HMAC Sign/Verify
CKM_MD5 Digest
CKM_MD5_HMAC_GENERAL Sign/Verify
CKM_MD5_HMAC Sign/Verify
CKM_SHA_1 Digest
CKM_SHA_1_HMAC_GENERAL Sign/Verify
CKM_SHA_1_HMAC Sign/Verify
CKM_SHA_256 Digest
CKM_SHA_384 Digest
3-10
CKM_SHA_512 Digest
CKM_RIPEMD160 Digest
CKM_RIPEMD160_HMAC_GENERAL Sign/Verify
CKM_RIPEMD160_HMAC Sign/Verify
CKM_MD5_KEY_DERIVATION Derive
CKM_MD2_KEY_DERIVATION Derive
CKM_SHA1_KEY_DERIVATION Derive
CKM_CONCATENATE_BASE_AND_KEY Derive
CKM_CONCATENATE_BASE_AND_DATA Derive
CKM_CONCATENATE_DATA_AND_BASE Derive
CKM_XOR_BASE_AND_DATA Derive
CKM_EXTRACT_KEY_FROM_KEY Derive
CKM_SSL3_PRE_MASTER_KEY_GEN GenerateKey
CKM_SSL3_MASTER_KEY_DERIVE Derive
CKM_SSL3_KEY_AND_MAC_DERIVE Derive
3-11
CKM_TLS_PRE_MASTER_KEY_GEN GenerateKey
CKM_TLS_MASTER_KEY_DERIVE Derive
CKM_TLS_KEY_AND_MAC_DERIVE Derive
CKM_TLS_PRF Derive
Additional AR Proprietary Mechanisms
CKM_ARDFP1 Digest
CKM_ARDFP2 Digest
CKM_ARDFP3 Digest
CKM_ARDFP4 Digest
CKM_DES_STREAM Encrypt/Decrypt
CKM_DES3_STREAM Encrypt/Decrypt
CKM_DES3EEE_ECB Encrypt/Decrypt
CKM_DES3EEE_CBC Encrypt/Decrypt
3-12
Using DES2 and DES Keys with DES3 Mechanisms
The PKCS#11 standard defines encrypt/decrypt and sign/verify operation

mechanisms for Triple-DES (DES3) keys only, but not for Double-length DES
(DES2) keys. Algorithmic Research’s PKCS#11 API enables applications to use
DES2 keys with mechanisms defined for DES3, by allowing handles to DES2
objects to be supplied as parameters to encrypt/decrypt and sign/verify functions
with the following DES3 mechanisms:
♦ CKM_DES3_ECB
♦ CKM_DES3_CBC
♦ CKM_DES3_CBC_PAD
♦ CKM_DES3_MAC_GENERAL
♦ CKM_DES3_MAC
The Algorithmic Research’s PKCS#11 library implements an additional

enhancement that enables use of these mechanisms with single-DES keys as
well, producing the same results as single-DES mechanisms.
DES Stream mechanisms
Algorithmic Research’s PKCS#11 includes proprietary DES stream algorithms

for backward compatibility with older versions of CryptoKit (Ver 1.63). These
algorithms can be used with single-DES keys, Double length DES (DES2) and
Triple-DES (DES3) keys to achieve full compatibility. The following table
describes how the old algorithms are mapped into CryptoKit:
CryptoKit Version 1.63 CryptoKit 3.5 and above
Algorithm Mode Mechanism Key Type
HL_ALG_DES HL_MODE_CBC CKM_DES_CBC DES
HL_ALG_DES HL_MODE_ECB CKM_DES_ECB DES
3-13
CryptoKit Version 1.63 CryptoKit 3.5 and above

Algorithm Mode Mechanism Key Type
HL_ALG_DES HL_MODE_STREAM CKM_DES_STREAM DES
HL_ALG_DES3_EDE HL_MODE_CBC CKM_DES3_CBC DES2
HL_ALG_DES3_EDE HL_MODE_ECB CKM_DES3_ECB DES2
HL_ALG_DES3_EDE HL_MODE_STREAM CKM_DES3_STREAM DES2
HL_ALG_DES3_EEE HL_MODE_CBC CKM_DES3EEE_CBC DES3
HL_ALG_DES3_EEE HL_MODE_ECB CKM_DES3EEE_ECB DES3
HL_ALG_DES3_EEE HL_MODE_STREAM CKM_DES3_STREAM DES3
3-14
Users, Administrators and Sessions
The PKCS#11standard specifies two types of token users: Security Officers

(SO), and normal users. In most cases, SO administers the users in an
organization (in PKCS#11 implementations for Windows NT4 or UNIX, for
example, the system Administrator could be the SO).
The first session using a token must be in “Public mode” in PKCS#11

terminology. At this stage, an application can access all public data that does not
require user authentication. Only authenticated users, however, can access
“private” data.
To enable user authentication, an application should call the C_Login function.

When the function succeeds, the current session (and all other sessions that were
initiated with a token) switches to the “Private mode”. This grants the
application full access to all data on the token: Both public and private.
The SO must initialize the token (by calling the C_InitToken function) and
set the user’s initial PIN before a normal user can log in. In order to initialize the
user’s PIN, the SO must log into the public session (it is assumed that the SO
PIN was already initialized on each token, and call the C_InitPIN function.
Though the SO can manipulate certain public data, PKCS#11 does not allow the
SO to gain access to private data. However, since PKCS#11 does not impose a
distinction between the SO and users, the SO may also be a user, and gain access
to private data by logging on as a normal user.
3-15
CryptoKit PKCS#11 Versions
Based on licensing approval, the Algorithmic Research PKCS#11 library is

shipped in three versions:
♦ Extended – a supports DES, Triple-DES, Double-length DES, AES, RC2
(key length up to 1024 bits), and RC4 (key length up to 2048 bits). This
version includes the CryptoKit SDK with include, lib and sample files.
♦ Runtime – supports the same algorithms as the Extended version but
does not include the SDK files.
♦ Basic – only supports DES with effective key length of 40 bits. RSA
keys in this version are generated for Demo purposes only. This version
does not include the SDK files too.
These versions support the same RSA (key length up to 4096, DSS and
Diffie-Hellman key lengths (up to 1024 bits) and the same hash and key
derivation algorithms.
Algorithmic Research CryptoKit PKCS#11 Releases
An application can check the library version currently in use by calling the
C_GetInfo function. The resulting libraryDescription and libraryVersion
fields contain version information.
3-16
Tokens and Slots
In PKCS#11 terminology, cryptographic “tokens” are cryptographic devices,

e.g., smart cards that provide a highly secure form of sensitive information
storage, offering PIN (password) protection. Algorithmic Research’s
PrivateCard smart card, MiniKey PKI USB token, CoSign and PrivateServer
HSM serve as tokens in the CryptoKit PKCS#11 context.
“Slots” are smart card readers or other device interfaces connected to the
application computer enabling use of the smart card token as storage for
cryptographic objects and for performing cryptographic functions.
CryptoKit supports many types of smart card readers. It supports readers

manufactured by Algorithmic Research such as: PrivateSafe®, CryptoSafe and
PrivateSafe PCMCIA as well as any standard PCSC or CT-API compliant
reader, manufactured by other vendor. Refer to the Token and Slot section in
Chapter 2 for more information about these readers and their facilities.
PrivateCard is one of the most intelligent and high performance smart cards
available, performing all operations with the RSA private key located internally
on the smart card chip.
MiniKey is Algorithmic Research’s cryptographic device that functions as both

the "Token" and the "Slot". It can be viewed as a smart card reader with
PrivateCard built in, and it is plugged into a computer's USB port. MiniKey
allows users to conveniently manage their keys and authenticate their identity
when connecting to enterprise, e-commerce or other secure applications.
CoSign, which provides digital signature services, acts as a network attached

smart card. The PKCS#11 interface can be used to access the data stored on the
CoSign and to perform digital signatures with the keys stored on the device. For
more information refer to the CoSign manual.
Algorithmic Research’s PrivateServer may also serve as a high performance

network attached smart card device. It can be used by applications that need
3-17
PKCS#11 interface to perform cryptographic operations in a large scale for

example with CA server, Web server etc. For more information refer to the
PrivateServer manual.
Data Stored as Objects
Cryptographic tokens (PrivateCard, MiniKey) store data as objects (in addition

to performing cryptographic operations). The PKCS#11 standard specifies three
types of data objects: Raw data, Certificates and Keys.
♦ Raw data is not defined as an object by its content—the PKCS#11
provider and the application set the data object definition for the data.
♦ Certificate objects store public-key certificates or attribute certificates.
♦ Key objects store cryptographic keys. The PKCS#11 standard identifies
three types of key objects: Public keys, Private keys and Secret keys.
Each type has subtypes that can be used in relevant mechanisms. For
example, PKCS#11 recognizes the following Private key object
subtypes: RSA, DSS, etc. Similarly, Secret key objects include DES,
DES3, RC2, etc.
Objects are classified by token and by session. While token objects remain on
the token even after all sessions using the token are closed, and even after the
token has been removed from the slot, session objects are temporary. The
lifetime of session objects is limited by the duration of the session during which
they were created. After closing a session, (by calling the C_CloseSession
function or by removing the token from the slot), all objects created in that
session as session objects, are automatically deleted.
Objects are also classified as Public or Private. To view or use Public objects,
there is no need for applications to log into the token. However, authentication is
necessary to gain access to Private objects (see the Users, Administrators and
Sessions section above).
3-18
Tokens can generate, destroy, manipulate, and search for objects—they can also
use them (e.g., key objects) to perform cryptographic operations.
PIN Functionality
Private objects can be accessed only after a user has successfully presented his
PIN to the token, authenticating himself as the owner of the key media. The
following explanation of PIN presentation is valid for C_Login,
C_InitToken, C_InitPIN and C_SetPIN functions (all functions that
contain PIN as a parameter).
An application can implement PIN presentation by passing either of the

following to all the functions mentioned above:
♦ The PIN as a parameter, causing CryptoKit to present it to the token
without presenting the user any dialog.
♦ NULL instead of the PIN, causing the library to prompt the user for PIN
entry. In that case, if the token supports secure PIN entry then it will be
used; otherwise a regular PIN entry dialog is displayed.
CryptoKit has three special modes for presenting the PIN to the token:
♦ Secure PIN entry mode, which is activated when NULL is passed as
parameter to the login functions. As documented in the Cryptoki 2.11
standard, this option can be used with tokens that have a protected
authentication path (i.e., protected keypad entry). Algorithmic
Research’s PrivateCard enables this form of authentication when used
with PrivateSafe and CryptoSafe readers, but not with the PrivateSafe
PCMCIA reader or MiniKey. During PIN entry, the reader disconnects
the keyboard from the computer thus disables exposure of sensitive data.
An application can check whether secure PIN entry is enabled on a
specific token by calling C_GetTokenInfo and checking the value of
protected authentication path flag in the CK_TOKEN_INFO structure.
3-19
♦ SSO mode, in which the user is required to present the PIN only once.
The PIN is stored in memory and afterwards it is automatically retrieved
by CyptoKit everytime logon to the token is required. The SSO
functionality is able to store both the user and SO PINs for each slot.
When the token is removed or when the user logs off from the
workstation, the stored PIN’s are cleared from memory.
♦ Unattended mode, which enables automatic presentation of a PIN that
was previously stored in the registry. This mode can be used to
automatically authenticate to tokens in unattended machines.
Note: Some applications do not enable implementation of the protected

authentication path. They display their own dialog box, prompting MiniKey and
PrivateCard users to enter the password (they do not pass NULL instead of the
PIN to the C_Login function).
PIN Default Parameters
The PKCS#11 standard does not enable additional PIN-related functionality

(e.g., setting the expiration period, maximum number of presentation attempts,
minimum PIN length, etc.). On the other hand, MiniKey and PrivateCard require
setting such parameters for PINs. The application, based on the Cryptoki
PKCS#11 API, is not able to set these values
Algorithmic Research’s CryptoKit provides a solution by assigning initial

default values to user PINs parameters during token initialization.
For example, a PIN becomes “expired” if it has not been replaced within the
default period of time. Subsequent attempts to use it will return the
CKR_PIN_EXPIRED result code and the user should change the PIN by calling
the C_SetPIN function. The expiration date is automatically re-computed
after replacing the PIN.
Due to inconsistencies, the Cryptoki PKCS#11 API does not grant PIN update
functionality to its applications when a PIN has expired. As a result, if a user
3-20
tries to login after his PIN has expired, he will be locked out of the application
since he can use C_Set PIN functionality only after logging in.
The current version of Algorithmic Research’s CryptoKit PKCS#11 provides a

workaround to this problem in the following way:
♦ If during C_Login, an expired PIN is entered using a protected keypad,
the library prompts the user to change his PIN immediately, without
exiting from C_Login
♦ If during C_Login, an expired PIN is supplied as a parameter, the

library allows the application to call C_SetPIN immediately in order to
change his PIN (normally, this function is called in the login state only).
If another function is after C_Login then C_SetPIN will fail.
CryptoKit offers the exceptional remedies described above, to handle PIN

inconsistencies in Cryptoki PKCS#11 API. Algorithmic Research reserves the
right to modify this special PIN functionality in the future without prior
notification.
CryptoKit provides also additional functionality when calling functions that

require PIN entry (C_Login, C_InitToken, C_InitPIN and C_SetPIN),
with NULL parameter as the password. In this case an appropriate PIN entry
dialog box is automatically opened.
During a call to C_SetPIN, if the old PIN was entered by protected keypad, the
replacement PIN must be entered the same way (i.e., if the old PIN was passed
as NULL to the C_SetPIN function, the new PIN must be also passed as
NULL). Another security feature provided by the CryptoKit: A new PIN must
be different than the one it replaces.
Whenever an application needs to be authenticated to the MiniKey or

PrivateCard token, it has a restricted number of attempts to present the correct
PIN. After exceeding this number, the user PIN is locked and the application
may never access sensitive information on the token (though public objects
remain accessible). In this event, every C_Login function call will fail with a
return code of CKR_PIN_LOCKED.
3-21
In the case of successful PIN presentation, the unsuccessful-attempts counter on

the MiniKey or PrivateCard token is set to zero again.
The C_GetTokenInfo function can supply additional information about the

state of the PIN presentations on the token. This state is reported in the
following flags in the CK_TOKEN_INFO structure:
♦ CKF_USER_PIN_COUNT_LOW – TRUE if an incorrect user login PIN

has been entered at least once since the last successful authentication.
♦ CKF_USER_PIN_FINAL_TRY – TRUE if supplying an incorrect user
PIN will it to become locked.
♦ CKF_USER_PIN_LOCKED – TRUE if the user PIN has been locked.
User login to the token is not possible.
♦ CKF_SO_PIN_COUNT_LOW – TRUE if an incorrect SO login PIN has
been entered at least once since the last successful authentication.
♦ CKF_SO_PIN_FINAL_TRY – TRUE if supplying an incorrect SO PIN
will it to become locked.
♦ CKF_SO_PIN_LOCKED – TRUE if the SO PIN has been locked. User
login to the token is not possible.
The following table describes the default PIN parameters that are set by the
CryptoKit installation program for MiniKey, PrivateCard and software tokens.
For details how to change these default settings, refer to the CryptoKit Files and
Registry Entries section in Chapter 7.
3-22
Parameter Default Values for Default Values for Explanation &
MiniKey and Software token Valid Values
PrivateCard
Minimum period 0 0 0 – PIN can be changed
for PIN change at any time
1-7 – Minimum number
of days between PIN
changes
Period of validity 889 days 0 0 – PIN never expires

(which are 127weeks, 1-889 – Maximum
approx. 2.5 years) number of days until the
PIN will expire
Minimum PIN 6 alphanumeric 5 alphanumeric

length characters characters
Maximum number 12 0 0 – Unlimited

of PIN retries for 3-12 – Number of
user allowed presentations.
PIN locked afterwards
Maximum number 6 0 0 – Unlimited

of PIN retries for 3-12 – Number of
SO allowed presentations.
If the SO PIN is locked,
the token cannot be used
anymore
Note: CoSign and PrivateServer devices have their own authentication

mechanism, which obsolete the required PIN for the login operation.
MiniKey and PrivateCard tokens are supplied to customers with an initial SO

(Security Officer) PIN value of 11111111. To change this value, an application
can call to C_SetPIN when SO is logged in. Users can also use the AR Genie
utility program to change the SO PIN.
3-23
Thread Safety
The Algorithmic Research implementation of the PKCS#11 standard is thread

safe and fully compatible with all PKCS#11 requirements for accessing from
multiple threads. If two threads attempt to access the same library
simultaneously, the second thread is blocked until the first thread’s request is
processed. An application that possesses the parameters to the C_Initialize
function can disable this safeguard (in full accordance with
PKCS#11specifications).
The CryptoKit will serialize requests when several processes share a library.
Additionally, according to PKCS#11 specifications, token objects are visible to
all applications (possessing sufficient permissions) connected to the token.
Date and Time
When the CryptoSafe reader is used, the library acquires the current date and
time for PIN presentation and PIN replacement from the reader’s internal clock.
For all other cases, CryptoKit uses the computer’s time and date and attempts to
factor in the time zone. However, there may be some variation in dates and
times due to differences in operating systems, sometimes even on the same
computer.
3-24
Platform- and Compiler-Dependent Directives
Some details in the declaration of Cryptoki data structures and functions may
vary between platforms. Therefore it may be necessary to implement some
preprocessor directives or compiler options.
All Cryptoki types and defines are stored in the pkcs11t.h file. Information
about function prototypes is contained in the pkcs11f.h file. In order to
include the main H-file pkcs11.h (or the pkcs11t.h file by itself), it is
necessary to define four platform-specific macros, described below, with their
typical definitions. Note that these definitions are both platform- and compiler-
dependent (and may also be affected by whether a Cryptoki library is linked
statically or dynamically).
For the Algorithmic Research PKCS#11 implementation, the AR_PLATFORM

preprocessor symbol is used during the compilation of every C or C++ file that
includes CryptoKit H-files. This forces correct compilation of all other platform-
dependent definitions in the H-files.
In most cases, the AR_PLATFORM preprocessor symbol is defined

automatically by CryptoKit H-files and all definitions required are automatically
provided for correct functioning of the CryptoKit macros.
If no platform is detected, the value AR_DEFAULT_PLATFORM (99) is

assigned, which suppresses the use of all platform-specific definitions. If
AR_PLATFORM is defined during the compilation, automatic platform
detection is suppressed and other platform-dependent definitions will be adopted
according to the defined platform.
The following values for AR_PLATFORM are currently supported:
AR_WIN32 (3)
AR_SOLARIS (8)
AR_AIX (10)
AR_LINUX (12)
3-25
Refer to your C or C++ compiler reference guide for information on how to set
preprocessor symbols.
The Cryptoki standard states that on Windows 32bit platform, any structure
should be packed with 1-byte alignment. However, CryptoKit is compiled in
such a way that any program that uses this library will be able to work properly,
regardles of its byte alignment. (The 1-byte packing convention that was
required by older versions of CryptoKit is no longer needed).
Platform-Specific Macros
The following four platform-specific macros are defined in platform.h file:
CK_PTR
The indirection string, for making a pointer into an object, can be used as
follows:
typedef CK_BYTE CK_PTR CK_BYTE_PTR;
For the Windows 32bit platform the following definition was used:
#define CK_PTR *
CK_DECLARE_FUNCTION(returnType, name)
This macro creates an importable Cryptoki library function declaration out of a
return type and a function name. It is used as follows:
extern CK_DECLARE_FUNCTION( CK_RV, C_Initialize )
( CK_VOID_PTR pReserved );
For the Windows 32bit platform the following definition was used to declare a
function in a DLL:
#define CK_DECLARE_FUNCTION( returnType, name ) \
returnType __declspec( dllimport ) name
3-26
CK_DECLARE_FUNCTION_POINTER(returnType, name)
This macro creates a Cryptoki API function pointer declaration or function
pointer type declaration out of a return type and a function name. It isused as
follows:
CK_DECLARE_FUNCTION_POINTER( CK_RV, funcPtr )
( args );
This macro defines funcPtr as a pointer to a Cryptoki API function taking

arguments args and returning CK_RV. You can also use it as follows:
typedef CK_DECLARE_FUNCTION_POINTER
( CK_RV, funcPtrType )( args );
funcPtrType funcPtr;
Here it defines funcPtrType to be the type of pointer to a Cryptoki API

function that takes arguments args and returns CK_RV, and then defines
funcPtr to be a variable of type funcPtrType.
For the Windows 32 bit platform the following definition was used to access
functions in a DLL:
#define CK_DECLARE_FUNCTION_POINTER
( returnType, name ) \
returnType __declspec( dllimport ) ( *name )
CK_CALLBACK_FUNCTION(returnType, name)
This macro creates a function pointer type for an application callback using both
a return type for the callback and a name for the callback:
CK_CALLBACK_FUNCTION( CK_RV, myCallback )( args );
This macro can be used to declare a function pointer, myCallback, to a

callback, which takes arguments args and returns CK_RV. You can also use it as
follows:
typedef CK_CALLBACK_FUNCTION
( CK_RV, myCallbackType )( args );
myCallbackType myCallback;
3-27
For the Windows 32bit platform the following definition was used:
#define CK_CALLBACK_FUNCTION( returnType, name ) \
returnType( *name )
3-28
Registration API
The SmartAdaptor Registration API provides developers with tools to manage

the various types of providers supported by SmartAdaptor. The API contains
functions to register, unregister, list and retrieve specific information about the
providers. The following is a list of SmartAdaptor Registration API functions
that are defined in the first part of the sadaptor.h file:
UMB_CreatePKCS11ProviderContext
UMB_CreatePKCS11SmartcardProviderContext
UMB_CreateSmartcardReaderContext
UMB_CreateFindContext
UMB_SetProviderData
UMB_AddATRToList
UMB_GetProviderData
UMB_RegisterProvider
UMB_UnregisterProvider
UMB_AddFindContext
UMB_ListProviders
UMB_FreeContext
UMB_GetProviderType
See the Registration API functions section below for a description of each
function.
Registration API Data Types
The data structures listed below are in C-notation and are defined in the
sadaptor.h file.
3-29
UMB_RV
typedef UINT32 UMB_RV;
Retrieves return code types that are returned by all the Registration API
functions:
♦ UMB_RV_OK Operation successful
♦ UMB_RV_END Reached end of database in a multi-step
operation (e.g., Find)
♦ UMB_RV_MEMORY Insufficient memory
♦ UMB_RV_INVALID_PARAMETERS Invalid parameters detected
♦ UMB_RV_INSUFFICIENT_BUFFER Allocated buffer too small
♦ UMB_RV_NOT_FOUND Object not found in database
♦ UMB_RV_HARDWARE Hardware error
♦ UMB_RV_CARD_NOT_POWERED Card inserted but not powered up
♦ UMB_RV_CARD_NOT_PRESENTED Card not inserted
♦ UMB_RV_COMMUNICATION Communication problem occurred
♦ UMB_RV_TIMEOUT Operation took too much time, interrupted by
with timeout state
♦ UMB_RV_SHARING_VIOLATION Smart card or reader temporary inaccessible
(locked by another application)
♦ UMB_RV_INTERNAL_ERROR Internal error occurred
UMB_CONTEXT
typedef void * UMB_CONTEXT;
The UMB_CONTEXT is used as a handle to a specific provider that may or

may not be registered yet. This structure is created and returned by one of the
following functions:
3-30
♦ UMB_CreatePKCS11ProviderContext
♦ UMB_CreatePKCS11SmartcardProviderContext
♦ UMB_CreateSmartcardReaderContext
♦ UMB_CreateFindContext
♦ UMB_ListProviders
All the other Registration API functions need this handle as a parameter to
specify the provider.
UMB_PROVIDER_INFO
typedef struct {
UINT32 api_version; // high word - major version,
// low word – minor version
UINT32 impl_version;// high word - major version,
// low word – minor version
char vendor_name[64]; // NULL terminated string
char provider_name[64];// NULL terminated string
} UMB_PROVIDER_INFO;
This structure stores general information about a provider. It is mandatory for all
three types of providers: Core, Reader and Smart card. Functions that create the
context receive this structure as a parameter.
UMB_PCSC_EXCLUDE_STRUCT
typedef struct {
UMB_COMPARE_STYLE flag;// UMB_COMPARE_ALL,
// UMB_COMPARE_START or
// UMB_COMPARE_PART
char readerName[256]; // NULL terminated string
} UMB_PCSC_EXCLUDE_STRUCT;
This structure is used for readers with a PC/SC interface that are nonetheless
registered as a CT-API or proprietary reader and therefore should be excluded
3-31
from the enumeration of PC/SC readers. The flag field defines how the reader
name should be matched. This attribute can only be assigned to a Reader
provider type context with Reader type set to
UMB_SC_READER_TYPE_PCSC.
Parameters
♦ UMB_COMPARE_ALL – compares readerName to the exact reader
name received from PC/SC.
♦ UMB_COMPARE_START – looks for readerName in the PC/SC
reader name at the start (similar to file compare “name*”).
♦ UMB_COMPARE_PART – looks for readerName somewhere inside
the PC/SC reader name (similar to file compare “*name*”).
UMB_CTAPI_PORT_DESCR
typedef struct {
short phys_number;
short ICC_mask;
} UMB_CTAPI_PORT_DESCR;
This structure describes a CT-API reader port. It can only be assigned to a
Reader provider type context with Reader type set to
UMB_SC_READER_TYPE_CTAPI. For more information, refer to
documentation on CT-API specifications.
Parameters
♦ phys_number – number of the port to which the reader is connected.
This number is passed to the CT_Init function as pn parameter.
♦ ICC_mask – bit mask of the slots available for use in a reader. The
lowest bit accords to the first slot, which must be available.
3-32
UMB_CTAPI_PORTS
typedef struct {
int number_of_ports;
UMB_CTAPI_PORT_DESCR ports[16];
} UMB_CTAPI_PORTS;
This structure describes some or all of available CT-API reader ports. It can only
be assigned to a Reader provider type context with Reader type set to
UMB_SC_READER_TYPE_CTAPI. For more information, refer to
documentation on CT-API specifications.
Parameters
♦ number_of_ports – number of cells used in “ports” array.
♦ ports – an array of 16 cells. Each member is a structure of
UMB_CTAPI_PORT_DESCR type, including description of a reader, its
port and slots.
UMB_ATR_DESCRIPTION
typedef struct {
int atr_len; // length of the ATR
char atr[32]; // ATR
char atr_mask[32]; // indicates which bits in
// the ATR read from the
// smart card should be
// compared with this ATR
} UMB_ATR_DESCRIPTION;
This structure can only be assigned to a Smart card provider type context and it
describes one ATR of a smart card supported by this provider. One Smart card
provider can have a number of ATR descriptions (if it supports many smart
cards) but at least one must be provided.
3-33
SmartAdaptor Registration API Functions
All Registration API functions return UMB_RV values.
UMB_CreatePKCS11ProviderContext
This function creates a Core PKCS#11 provider context. After creating the
provider context, call UMB_SetProviderData to add additional parameters.
Then, register the provider by calling UMB_RegisterProvider.
Syntax
UMB_RV UMB_CreatePKCS11ProviderContext(
const UMB_PROVIDER_INFO * info,
const char * module,
UMB_CONTEXT * context);
Parameters
♦ info [in] – contains a general description of the Core provider. Refer to
the Registration API data types section above for a detailed explanation
of this parameter (Type UMB_PROVIDER_INFO).
♦ module [in] – contains the full path and name of the dll of the Core
provider.
♦ context [out] – receives a pointer to the created context, upon successful
termination of the function.
Note: Since this function’s arguments are mandatory, they cannot be NULL.
Return Values
UMB_RV_OK – context created successfully.
3-34
UMB_RV_INVALID_PARAMETERS – invalid parameter detected, a
pointer is probably NULL. Note that the function does not check whether
the file specified in the module parameter exists.
UMB_RV_MEMORY – insufficient memory.
UMB_RV_INTERNAL_ERROR – an internal error occurred.
UMB_CreatePKCS11SmartcardProviderContext
This function creates a Smart card provider context. A mandatory ATR
parameter must be specified to indicate, which smart card ATRs are supported
by that provider. Each Smart card provider can support multiple ATRs, which
can be added to the context by calling UMB_AddATRToList or
UMB_SetProviderData. Then, register the provider by calling
UMB_RegisterProvider.
Syntax
UMB_RV UMBAPI
UMB_CreatePKCS11SmartcardProviderContext(
const char * entry,
const UMB_ATR_DESCRIPTION * atr,
Parameters
♦ info [in] – contains a general description of the Smart card provider.
Refer to the Registration API data types section above for a detailed
explanation of this parameter (Type UMB_PROVIDER_INFO).
♦ module [in] – the full path and name of the dll of the Smartcard
provider.
3-35
♦ entry [in] – the name of the entry function for this dll, which is called
after it has been loaded. The entry function passes to the Smart card
provider pointers of the reader functions.
♦ atr [in] – description of the ATR for the Smart card provider.
Note: Since all of these parameters are mandatory, they cannot be NULL.
Return Values
UMB_RV_OK – context successfully created.
UMB_CreateSmartcardReaderContext
Similar to the functions described above, this function creates a Smart card
reader context. It can be used to create a CT-API or proprietary reader context or
to create a PC/SC reader to be excluded from the readers list. After creating the
context, call UMB_SetProviderData to add additional parameters. Then, register
the provider by calling UMB_RegisterProvider.
Syntax
UMB_RV UMBAPI UMB_CreateSmartcardReaderContext(
int type,
const char * entry,
3-36
Parameters
♦ type [in] – there are three possible types of Reader providers, which are
defined in sadaptor.h:
UMB_SC_READER_TYPE_CTAPI, which is used to register a
CT-API reader provider
UMB_SC_READER_TYPE_PROPRIETARY, which is used to
register a proprietary reader provider
UMB_SC_READER_TYPE_PCSC, which is used to exclude a
PC/SC reader from the readers list
♦ info [in] – contains a general description of the Reader provider. Refer to
the Registration API data types section above for a detailed explanation
of this parameter (Type UMB_PROVIDER_INFO).
This parameter is ignored when the reader type is PC/SC and in that case
should be an empty string.
♦ module [in] – contains the full path and name of the dll of the Reader
provider. This parameter must be specified for CT-API and proprietary
Reader providers. It is ignored when the reader type is PC/SC and in that
case should be an empty string.
♦ entry [in] – the name of the entry function for the provider’s dll. This
function is called by sadaptor.dll after the provider’s dll has been
loaded, to retrieve pointers to functions that access the reader. For more
information about the data structure that is returned by the entry function
and the different reader functions, refer to the Reader Provider
Development section, later in this chapter.
This parameter should be specified only for proprietary Reader providers.
It is not required for CT-API and PC/SC Reader providers and in that
case should be an empty string.
Note: Since all of these parameters are mandatory, they cannot be NULL.
3-37
Return Values
UMB_RV_OK – context successfully created.
UMB_SetProviderData
After creating the context for a provider using one of the functions described
above, you can use this function to assign additional attributes to the provider
before registering it in the system. The fieldTag parameter indicates the
assigned attribute, len contains its size and data denotes its value.
Syntax
UMB_RV UMBAPI UMB_SetProviderData(
UMB_CONTEXT * context,
int fieldTag,
int len,
const void * data);
Parameters
♦ context [in] – the context of the provider for which to set the data.
♦ len [in] – the length of the data passed in the data pointer.
♦ data [in] – the pointer to the attribute to be written in the context.
♦ fieldTag [in] – the following tags may be appended (defined in the
sadaptor.h file)
UMB_PROVIDER_FIELD_INFO – general information about
the provider based on the UMB_PROVIDER_INFO structure.
3-38
UMB_PROVIDER_FIELD_MODULE – NULL terminated
string. The full path to the module’s dll.
UMB_PROVIDER_FIELD_ENTRY – NULL terminated string.
The name of the entry function.
UMB_PROVIDER_FIELD_FLAGS – DWORD – has no special
significance for SmartAdaptor and can be used for the needs of the
provider.
UMB_PROVIDER_FIELD_EXCLUDE_FROM_PCSC – derived
from UMB_PCSC_EXCLUDE_STRUCT structure, this flag
marks a PC/SC reader as excluded from the readers list. It requires
that reader context was already created and registered using
UMB_CreateSmartcardReaderContext, with type set to
UMB_SC_READER_TYPE_PCSC, followed by
UMB_RegisterProvider.
UMB_PROVIDER_FIELD_CTAPI_PORTS – derived from
UMB_CTAPI_PORTS structure, this parameter can only be added
to a CT-API type Reader provider. This parameter is mandatory
and must be updated for each CT_API reader provider.
UMB_PROVIDER_FIELD_ATR_LIST – derived from
UMB_ATR_DESCRIPTION structure, this parameter can only be
added to a Smart card provider and indicates the ATRs supported
by this provider. One Smart card provider can support a number of
ATRs.
UMB_PROVIDER_FIELD_READER_TYPE – DWORD – this
tag, which can only be assigned to Reader providers, may be one
of following:
UMB_SC_READER_TYPE_CTAPI
UMB_SC_READER_TYPE_PROPRIETARY
UMB_SC_READER_TYPE_PCSC
UMB_PROVIDER_FIELD_DESCRIPTION – NULL terminated
string with the provider’s description.
UMB_PROVIDER_FIELD_LOG_FILE_NAME – NULL
terminated string with a path to the file used for logging the
provider.
3-39
UMB_PROVIDER_FIELD_LOGGING_LEVEL – DWORD –
logging level for the provider.
UMB_PROVIDER_FIELD_VENDOR_SPECIFIC – not really a
tag, it is the shift from which the vendor specific fields are written.
Allows a provider to store information in the registry. The data is
treated in the same way as a binary buffer.
Return Values
UMB_RV_OK – data successfully written to the context.
pointer is probably NULL.
UMB_AddATRToList
Provides an easy way to specify additional ATRs for a Smart card provider (see
also UMB_SetProviderData).
Syntax
UMB_RV UMBAPI UMB_AddATRToList(
UMB_ATR_DESCRIPTION * atr);
Parameters
♦ atr [in] – the description of the ATR to add to the context.
Return Values
UMB_RV_OK – data successfully written to the context.
pointer is probably NULL.
3-40
UMB_GetProviderData
This function can be used to retrieve information from the context. The tags are
the same as those used with UMB_SetProviderData. If the value for len is too
small, it is adjusted to the correct length and the
UMB_RV_INSUFFICIENT_BUFFER is returned. If the context does not
contain the record, UMB_RV_NOT_FOUND is returned – otherwise
UMB_RV_OK is returned and the data field is filled with the appropriate value.
When there are multiple occurrences of the requested record in the context
(UMB_PROVIDER_FIELD_ATR_LIST and
UMB_PROVIDER_FIELD_EXCLUDE_FROM_PCSC tags only),
SmartAdaptor treats the len parameter as the size of an array and the data
parameter as the array of the appropriate type of records.
Syntax
UMB_RV UMBAPI UMB_GetProviderData(
UMB_CONTEXT context,
int fieldTag,
int * len,
void * data);
Parameters
♦ context [in] – the context to read from.
♦ fieldTag [in] – the tag of the field to extract from the context. See the
section on UMB_SetProviderData for a description of this parameter.
♦ len [in/out] – on entry to the function should contain the size of the
buffer pointed by data. Upon return, len contains the actual size of the
data returned. This parameter cannot be NULL.
♦ data [out] – the data marked by fieldTag. Can be NULL – in which case
only the size of the data is returned.
3-41
Return Values
UMB_RV_OK – data read successfully.
UMB_RV_INVALID_PARAMETERS – invalid parameter detected.
UMB_RV_INSUFFICIENT_BUFFER – the size of the buffer is too
small.
UMB_E_GENERAL – the data identified by the specified tag is not in
the context.
UMB_RegisterProvider
Registers the provider after creation of the context (with one of the
“CreateContext” functions) and after writing all the appropriate parameters to
the context using the UMB_SetProviderData and UMB_AddATRToList
functions.
Syntax
UMB_RV UMBAPI UMB_RegisterProvider(
Parameter
♦ context [in] – the context of the provider to register.
Return Values
UMB_RV_OK – data read successfully.
UMB_RV_INTERNAL_ERROR – unable to store context.
3-42
UMB_CreateFindContext
This function creates a find context, which is a special type of context. This
context can be used to find the context of a registered provider. Then, the
context can be used to add new parameters or to delete parameters from the
provider. This context cannot be registered.
Syntax
UMB_RV UMBAPI UMB_CreateFindContext(
Parameter
♦ context [out] – the created context.
Return Values
UMB_RV_OK – data successfully read.
UMB_AddFindContext
This function is similar to UMB_SetProviderData but it can be applied only on
find contexts. It is used to build a specific find context that describes one of the
registered providers. After the find context is created, call UMB_ListProviders
to get a list of all providers that match the search criteria. You can also remove
from the system all providers that match the search criteria by calling
UMB_UnregisterProvider with find context.
All the tags that can be defined for the provider using UMB_SetProviderData
can be used to search for the provider. There are also additional special tags that
can be used only with find context.
Syntax
UMB_RV UMBAPI UMB_AddFindContext (
3-43
UMB_COMPARE_STYLE flag,
int fieldTag,
int len,
const void * data);
Parameters
♦ flag [in] – tells the function how to perform string matching, can be one
of the following:
UMB_COMPARE_ALL
UMB_COMPARE_START
UMB_COMPARE_PART – only string tags are affected by this
parameter
♦ len [in] – the length of the data passed in the data pointer.
♦ data [in] – the pointer to the attribute to be written in the context.
♦ fieldTag [in] – all tags for regular context are supported (see the
description of UMB_SetProviderData); additional tags are supported for
find context:
UMB_PROVIDER_FIELD_PROVIDER_TYPE – DWORD –
uses one of the following (defined in sadaptor.h) –
UMB_PROVIDER_TYPE_PKCS11
UMB_PROVIDER_TYPE_READER
UMB_PROVIDER_TYPE_PKCS11_SCARD
UMB_PROVIDER_FIELD_API_VER – DWORD – part of the
provider info structure, it specifies the API version of the provider.
UMB_PROVIDER_FIELD_IMPL_VER – DWORD – part of the
provider info structure, it specifies the implementation version of
the provider.
UMB_PROVIDER_FIELD_VENDOR_NAME – NULL
terminated string. Part of the provider info structure, it specifies
the vendor name of the provider.
3-44
UMB_PROVIDER_FIELD_PROVIDER_NAME – NULL
terminated string. Part of the provider info structure, it specifies
the provider name of the provider.
UMB_PROVIDER_FIELD_ATR_BUFFER – binary buffer. The
length of the ATR is set by the len parameter – may not exceed 32
bytes. Use to set ATR only, without the ATR mask.
Return Values
UMB_RV_OK – data successfully read.
UMB_UnregisterProvider
This function removes a provider from the system. If the context parameter is
NULL, all registered providers are removed. The context may be of any type. If
the type is find, it must include both the provider type and module attributes,
otherwise UMB_E_PARAMS is returned. Any provider that matches the
context attributes is removed from the system and UMB_RV_OK is returned,
otherwise UMB_RV_NOT_FOUND is returned.
Syntax
UMB_RV UMBAPI UMB_UnregisterProvider(
Parameter
♦ context [in] – the context of the provider to remove from the system.
Return Values
UMB_RV_OK – providers matching the context were successfully
removed.
UMB_RV_NOT_FOUND – no provider that matched the context was
found.
3-45

UMB_ListProviders
Lists the providers that are registered in the system. The patterns parameter
defines how to search for providers. If patterns parameter is NULL, all
registered providers are returned. The number parameter is set to the number of
contexts that are found, i.e., those returned by the found parameter.
Syntax
UMB_RV UMBAPI UMB_ListProviders(
UMB_CONTEXT patterns,
UMB_CONTEXT ** found,
int * number);
Parameters
♦ patterns [in] – context of find type, provides the pattern for searching for
registered providers.
♦ found [in/out] – on entry to the function should contain the pointer to
pointer of context array; if successful, the array is allocated by the
function and the user should free the memory associated with this array
by using UMB_FreeContext.
♦ number [out] – the number of contexts found.
Return Values
UMB_RV_OK – data was successfully read.
3-46
UMB_FreeContext
This function frees the memory associated with previously allocated context.
Syntax
UMB_RV UMBAPI UMB_FreeContext(
Parameter
♦ context [in] – pointer to the context to be released.
Return Values
UMB_RV_OK – context memory successfully freed.
UMB_RV_INVALID_PARAMETERS – context is NULL or *context
is NULL.
UMB_GetProviderType
This function returns the context type, which should be one of the following:
♦ UMB_PROVIDER_TYPE_PKCS11
♦ UMB_PROVIDER_TYPE_READER
♦ UMB_PROVIDER_TYPE_PKCS11_SCARD
♦ UMB_PROVIDER_TYPE_FIND
Syntax
UMB_RV UMBAPI UMB_GetProviderType(
UMB_CONTEXT context,
int * type);
3-47
Parameters
♦ context [in] – the context for which to check the type.
♦ type [out] – the context type (one of the four values listed above).
Return Value
UMB_RV_OK – successful result.
3-48
Reader Provider Development
SmartAdaptor supports the PC/SC and CT-API standard reader APIs.

SmartAdaptor provides an additional API that enables the system to integrate
proprietary readers (not supported by either of the standard APIs). While each
reader provider usually has one slot, there is no restriction on the number of slots
possible. From the user’s perspective, each slot of a multi-slot reader displays as
one independent PKCS#11 slot.
PC/SC Readers
No additional development is necessary for PC/SC readers since they are

registered in the Windows operating system – SmartAdaptor recognizes them
automatically. SmartAdaptor also enables you to exclude PC/SC readers from
the registry, when, for example, users do not wish to use a specific reader. Also,
when a reader supports both the PC/SC API and an additional API (CT-API or
proprietary) the reader is listed both in the Windows registry and in
SmartAdaptor. Since this double listing causes the same reader to display twice
in the Slot list, you can exclude the PC/SC reader from the registry in order to
limit the display of the reader in the Slot list to just one time. Use the
SmartAdaptor Registration API (or directly edit the registry) to exclude PC/SC
readers from the registry – this cannot be accomplished during runtime (see the
Registration API section for details).
CTAPI Readers
Since SmartAdaptor can use the standard CT-API interface, it is not necessary to
develop a specific library for CT-API readers. However, you must register
CT-API readers in SmartAdaptor since operating systems do not automatically
recognize CT-API readers. (For more stable performance in stress situations,
vendors can supply a dll with additional functionality, for example, an entry
function and an i_am_closed function. For more details see below.)
3-49
Proprietary Readers
In order to work with a proprietary reader provider, a special dll has to be

developed and registered by SmartAdaptor registration API. The dll should
include implementation of several functions and an additional special entry
function. SmartAdaptor loads the dll and retrieves pointers to the provider’s
functions using the entry function. Then, SmartAdaptor mediates between the
reader and the Smart card provider by giving the Smart card provider the
functions that operate with the reader. As a result, Smart card providers can
operate with any reader registered in the SmartAdaptor system. Refer to the
following section for a list of the functions that each proprietary reader provider
should supply in order to operate correctly.
3-50
Reader Provider API
Each proprietary Reader provider must contain an implementation of all the

functions listed below:
UMB_ENTRY
UMB_READER_GET_NAME
UMB_READER_GET_STATE
UMB_READER_POWER_ON
UMB_READER_POWER_OFF
UMB_READER_TRANSMIT
UMB_READER_GET_NATIVE_RESULT_VALUE
UMB_READER_CLOSE
UMB_ENTRY
The entry function is the first function that SmartAdaptor calls. It is used to
initialize the provider and to load pointers to all other functions of the provider.
The entry function is also used to provide SmartAdaptor with the number of
slots that are supported by the Reader provider. By convention, the slots are
counted from zero.
Syntax
typedef UMB_RV (UMBAPI * UMB_ENTRY)
(UMB_ENV * env,
UMB_PROVIDER_READER * reader);
Since the entry function is not pre-named, you can assign it any name. This
name must be provided (in the entry parameter) when the provider is registered.
For more information, refer to function UMB_CreateSmartcardReaderContext
in the section SmartAdaptor Registration API Functions.
The pointers to all of the Reader provider’s functions are supplied in the output
UMB_PROVIDER_READER structure.
3-51
struct _tag_UMB_PROVIDER_READER {
UMB_PROVIDER_HEADER header;
// This parameter is filled by SmartAdaptor
// and is not relevant for reader provider.
UINT32 slots_number;
// This parameter is filled by the reader
// provider and informs SmartAdaptor how
// many slots are supported by the provider.
// The following parameters are pointers to

// functions filled by the reader provider.
UMB_READER_GET_NAME get_name;
UMB_READER_GET_STATE get_state;
UMB_READER_POWER_ON power_on;
UMB_READER_POWER_OFF power_off;
UMB_READER_TRANSMIT transmit;
native_res_value;
UMB_READER_CLOSE close;
} UMB_PROVIDER_READER;
Parameters
♦ env [in] – pointer to UMB_ENV structure, which contains only one
member that is relevant for the Reader provider – the i_am_closed
function. The provider should call this function during the
DLL_DETACH process, although this is not mandatory.
♦ reader [out] – pointer to the output UMB_PROVIDER_READER
structure.
Return Values
UMB_RV_INTERNAL_ERROR – general error occured.
3-52
UMB_RV_INVALID_PARAMETERS – if the value of a parameter is
NULL.
UMB_RV_OK – successful result.
UMB_READER_GET_NAME
This function should return the reader name to SmartAdaptor according to the
slot number.
Syntax
typedef UMB_RV (UMBAPI * UMB_READER_GET_NAME)
(UINT32 slotID,
char * nameBuf,
UINT32 * nameLen);
Parameters
♦ slotID [in] – number of the slot.
♦ nameBuf [out] – pointer to buffer, which receives the NULL terminated
name. If this parameter is NULL, it returns needed buffer size in the
nameLen parameter and UMB_RV_INSUFFICIENT_BUFFER in
return value.
♦ nameLen [in/out] – on entry to the function should contain the
maximum length of nameBuf buffer. Upon return, nameLen contains
the actual length of the reader name, not including the NULL terminator.
Return Values
UMB_RV_INSUFFICIENT_BUFFER – when nameBuf is too small.
UMB_RV_INVALID_PARAMETERS – when the slot number is
invalid or when the pointer to nameLen is NULL.
UMB_RV_OK – operation successful.
3-53
UMB_READER_GET_STATE
This function should return the state of the slot to SmartAdaptor.
Syntax
typedef UMB_RV (UMBAPI * UMB_READER_GET_STATE)
(UINT32 slotID,
UINT32 * slotState);
Parameters
♦ slotState [out] – state of the slot. Can be one of three states:
UMB_READER_STATE_ABSENT – no card in the slot.
UMB_READER_STATE_INSERTED – card in the slot, not
powered.
UMB_READER_STATE_POWERED – card in the slot,
powered.
Return Values
invalid or when the pointer to slotState is NULL.
UMB_READER_POWER_ON
This function should power-on the smart card and return it’s ATR.
Syntax
typedef UMB_RV (UMBAPI * UMB_READER_POWER_ON)
(UINT32 slotID,
3-54
char * ATRBuf,
UINT32 * ATRlen);
Parameters
♦ ATRBuf [out] – pointer to buffer, which receives the ATR of the smart
card. The maximum size needed to receive any ATR is 32 bytes.
♦ ATRLen [in/out] – on entry to the function should contain the maximum
length of ATRBuf. Upon return, ATRLen contains the actual length of
the ATR.
Return Values
UMB_RV_INSUFFICIENT_BUFFER – when ATRBuf is too small.
invalid or another parameter is NULL.
UMB_READER_POWER_OFF
This function should power-off the smart card.
Syntax
typedef UMB_RV (UMBAPI * UMB_READER_POWER_OFF)
(UINT32 slotID);
Parameters
Return Values
3-55

invalid.
UMB_READER_TRANSMIT
This function should send command to smart card and return the answer.
Syntax
typedef UMB_RV (UMBAPI * UMB_READER_TRANSMIT)
(UINT32 slotID,
char * sendBuf,
UINT32 sendLen,
char * recvBuf,
UINT32 * recvLen);
Parameters
♦ sendBuf [in] – pointer to buffer with outgoing command.
♦ sendLen [in] – size of buffer of outgoing command.
♦ recvBuf [out] – pointer to buffer that receives the answer.
♦ recvLen [in/out] – on entry to the function should contain the maximum
length of recvBuf buffer. Upon return, recvLen contains the actual
length of the answer.
Return Values
UMB_RV_INSUFFICIENT_BUFFER – when ATRBuf is too small.
3-56
This function should return from the Reader provider the “native” result code of
the last operation.
Syntax
typedef UMB_RV
(UMBAPI * UMB_READER_GET_NATIVE_RESULT_VALUE)
(UINT32 slotID,
UINT32 * result);
Parameters
♦ SlotID [in] – number of the slot.
♦ result [out] – pointer to DWORD that receives the native result code.
Return Values
UMB_READER_CLOSE
This function should finalize the operation with the reader. It is called only once
by SmartAdaptor in the event of DLL_DETACH.
Syntax
typedef UMB_RV (UMBAPI * UMB_READER_CLOSE)
3-57
(void);
Parameters
None.
Return Values
UMB_READER_I_AM_CLOSED
When the entry function is called, SmartAdaptor provides to the Reader provider
a pointer to the function UMB_READER_I_AM_CLOSED. The reader provider
can call this function during the DLL_DETACH process to notify SmartAdaptor
that the reader is no longer available. Calling this function is not mandatory and
it is mainly used for handling abnormal termination of the program.
Syntax
typedef UMB_RV (UMBAPI * UMB_READER_I_AM_CLOSED)
(UMB_ENV * env);
Parameters
♦ env [in] – environment variable passed in entry function.
Return Values
UMB_RV_INTERNAL_ERROR – general error occurred.
3-58
PKCS#11 API Extensions
SmartAdaptor supports the full PKCS#11 API functionality. In addition,
SmartAdaptor supports functions that enhance the standard PKCS#11 API.
These functions are defined in the files pkcsgext.h and pkcs_ui.h.
The list below summarizes the SmartAdaptor PKCS#11 enhancements, followed

by a more detailed description of the functions.
♦ Functions that provide information about the providers that are registered
in the SmartAdaptor system:
C_EXT_GetProviderList
C_EXT_GetProviderInfo
C_EXT_GetProviderContext
C_EXT_GetProviderSlotList
C_EXT_GetSlotProvider
C_EXT_PassToProvider
♦ Functions that support software tokens extensions:

C_EXT_Bind
C_EXT_Unbind
SmartAdaptor supports two types of software key media: static and

dynamic. Only Algorithmic Research’s PKCS #11 Core provider
provides this type of slots in which a file represents a token. While static
slots are loaded during SmartAdaptor startup, the dynamic slots can be
“inserted” or “unplugged” during runtime by calling C_EXT_Bind and
C_EXT_Unbind functions. The number of static and dynamic slots in the
system is determined when the AR Core PKCS#11 provider is registered.
♦ Functions that support extended token events:
C_EXT_WaitForSingleSlotEvent
C_EXT_WaitForSlotEvent
The standard PKCS#11 WaitForSlotEvent function is very limited: It is

not possible to specify a group of slots for event waiting, it doesn't return
the exact slot on which the event occurred nor does it provide a timeout
3-59
option. SmartAdaptor provides these two functions to overcome these

limitations.
♦ Functions that provide additional token and object handling:
C_EXT_ChangeTokenLabel
This function provides additional token management capability by

enabling changing the token label.
♦ Functions that extend the user interface functionality and are defined in p
pkcs_ui.h file:
C_UI_GetPassword
C_UI_SetMessage
C_UI_GetMessage
SmartAdaptor can display a window for password entry. The window

pops up when users call a PKCS#11 function that requires a password
with NULL_PTR. A SmartAdaptor extension mechanism enables users
to pop this window and to replace the standard SmartAdaptor messages
with customized messages.
3-60
Provider Architecture Functionality
C_EXT_GetProviderList
This function returns the list of providers that are registered in the SmartAdaptor
system.
Syntax
CK_RV C_EXT_GetProviderList(
CK_PROVIDER_ID_PTR pProviderList,
CK_ULONG_PTR pulCount);
The calling convention of this function is the same as for all PKCS#11 functions
that return an array. If the pProviderList pointer is NULL, pulCount returns
the size of the needed array and CKR_OK is returned. If pProviderList is not
NULL and the pulCount array size is too small, CKR_BUFFER_TOO_SMALL
is returned. Otherwise, the array is filled with CK_PROVIDER_IDs and
pulCount is updated with the actual number of providers returned. Each
CK_PROVIDER_ID is a unique handle that represents a provider. This handle
can be used to retrieve additional information about the provider. For additional
information, see the functions below.
Parameters
♦ pProviderList (output) – receives array of IDs.
♦ pulCount [in/out] – on entry to the function should contain the
maximum size of the pProviderList array. Upon return, pulCount
contains the actual number of providers read.
Return Values
CKR_OK – operation successful.
CKR_FUNCTION_FAILED – erroneous parameters.
3-61
CKR_BUFFER_TOO_SMALL – the buffer is too small to hold all the

providers.
CKR_CRYPTOKI_NOT_INITIALIZED – the Cryptoki has not been
initialized.
C_EXT_GetProviderInfo
This function returns information about a specific provider.
Syntax
CK_RV C_EXT_GetProviderInfo(
CK_PROVIDER_ID provider_id,
CK_INFO_PTR pInfo);
Parameters
♦ provider_id [in] – the ID of the provider.
♦ pInfo [in/out] – pointer to CK_INFO structure, which receives the

provider information.
Return Values
initialized.
CKR_PROVIDER_ID_INVALID - the provider ID is incorrect. This
return code is not a standard PKCS#11 return code. It is defined in the
pkcsgext.h file.
CKR_FUNCTION_FAILED – incorrect parameters.
C_EXT_GetProviderContext
This function returns the context of the provider, read from the registry. For
PC/SC readers, SmartAdaptor itself creates and fills the context.
3-62
Syntax
CK_RV C_EXT_GetProviderContext(
UMB_CONTEXT * pContext);
Parameters
♦ pContext [in/out] – pointer to a buffer, which receives the provider’s
context.
Return Values
initialized.
CKR_PROVIDER_ID_INVALID – the provider ID is incorrect. This
pkcsgext.h file.
C_EXT_GetProviderSlotList
This function retrieves the list of slots that are handled by a specific provider.
For Reader providers, the list includes the slot(s) of the reader. For Core
providers, the list includes the slots of the core provider. Smart card providers do
not have slots.
Syntax
CK_RV C_EXT_GetProviderSlotList(
CK_SLOT_ID_PTR pSlotList,
CK_ULONG_PTR pulCount);
3-63
The calling convention of this function is the same as for all PKCS#11 functions
that return an array. If the pSlotList pointer is NULL_PTR, pulCount returns
the size of the needed array and CKR_OK is returned. If pSlotList is not NULL
and the pulCount array size is too small, CKR_BUFFER_TOO_SMALL is
returned. Otherwise, the array is filled with CK_SLOT_IDs and pulCount is
updated with the actual number of slotss returned.
Parameters
♦ pSlotList [in/out] – receives array of slot IDs.
♦ pulCount [in/out] – on entry to the function should contain the
maximum size of the pSlotList array. Upon return, pulCount contains
the actual number of slots retrieved.
Return Values
initialized.
CKR_PROVIDER_ID_INVALID – the provider ID is incorrect. This
pkcsgext.h file.
CKR_BUFFER_TOO_SMALL – the size of the slot list array is too
small.
C_EXT_GetSlotProvider
This function returns the provider associated with a specific slot.
Syntax
CK_RV C_EXT_GetSlotProvider(
3-64
CK_SLOT_ID slot,
CK_ULONG type,
CK_PROVIDER_ID_PTR pProvider);
The type parameter is used to specify which provider to return in cases when
more than one provider is hadling the same slot. This is the normal situation
when a smart card is inserted into a reader. In that case, both a Smart card
provider and a Reader provider are attached to the same slot. The possible
values of the type parameter are defined in sadaptor.h file:
♦ UMB_PROVIDER_TYPE_PKCS11
♦ UMB_PROVIDER_TYPE_PKCS11_SCARD
♦ UMB_PROVIDER_TYPE_READER
Parameters
♦ slot [in] – the ID of the slot.
♦ type [in] – the type of provider to be returned.
♦ pProvider [out] – the ID of the provider, which is associated with that
slot.
Return Values
initialized.
CKR_SLOT_ID_INVALID – the slot parameter is not a valid slot
number.
CKR_ARGUMENTS_BAD – the type parameter is not one of the three
listed above.
3-65
C_EXT_PassToProvider
This function enables an application to use functions specific to a provider but
not contained in the standard PKCS#11 API. The function must be of the special
C_EXT_PROVIDER_FUNCTION type, which is defined in pkcsgext.h
file.
Syntax
CK_RV C_EXT_PassToProvider(
const CK_CHAR_PTR name,
CK_SLOT_ID slotID,
CK_SESSION_HANDLE hSession,
CK_OBJECT_HANDLE_PTR phObjectList,
CK_ULONG ulCount,
CK_VOID_PTR parameter);
The name parameter contains the NULL terminated string with name of the
function. The following is an example of this special function:
CK_RV GetProviderSpecialUndocumentedInfoNow(
CK_SLOT_ID slot,
CK_OBJECT_HANDLE_PTR phObjectList,
CK_ULONG ulCount,
CK_VOID_PTR parameter);
To call this function using SmartAdaptor:

rc = C_EXT_PassToProvider(
"GetProviderSpecialUndocumentedInfoNow",
provider_id, 1, 0, NULL_PTR, 0,
&special_undocumented_parameters);
3-66
Since SmartAdaptor translates slotIDs, objects and session handles supplied by
applications to internal handles, any function relevant to the provider, which
uses these internal handles, should pass them to the C_EXT_PassToProvider
function separately. This means that parameter may not contain these handles.
The slotID, hSession and phObjectList parameters pass handles to some

objects to the function when necessary. When slotID or hSession are not used
by the function, they should have a zero value. SmartAdaptor passes the
parameter parameter, which can be any pointer, directly to the function in the
dll.
Parameters
♦ name [in] – the name of function to call.
♦ provider_id [in] – the ID of provider to which the call should be passed.
♦ slotID [in] – the ID of the slot, if any.
♦ hSession [in] – the handle to session, if any.
♦ phObjectList [in] – the list of object handles passed to provider.
♦ ulCount [in] – the number of object handles in the previous parameter.
♦ parameter [in] – pointer to any structure, only for use with the function
that was called.
Return Values
initialized.
CKR_SLOT_ID_INVALID - the slot parameter is not a valid slot
number (if slotID is not 0).
CKR_SESSION_HANDLE_INVALID – the session handle is not valid
(if hSession is not 0).
3-67
CKR_OBJECT_HANDLE_INVALID – one of the object handles

specified is not valid.
Note: In the event of success (C_EXT_PassToProvider calls the relevant

function in the provider), the resulting code returned by
C_EXT_PassToProvider is according to the code returned by the specific
function.
3-68
Software Tokens Extensions
C_EXT_Bind
This function binds a specific file to a dynamic software slot. If no free
(unbound) dynamic slot is available, CKR_DEVICE_MEMORY is returned.
When one process binds a file to a specific slot, if another process binds the
same file, it is assigned the same slot. When two processes share the same
dynamic slot (using the same file), if one unbinds the file, the other can still use
the slot, until it unbinds the file as well.
Syntax
CK_RV C_EXT_Bind(
const CK_CHAR_PTR name,
CK_SLOT_ID_PTR slot);
Parameters
♦ name [in] – the name of the file to associate with a slot.
♦ slot [out] – the ID of the slot to which the file is assigned.
Return Values

CKR_CRYPTOKI_NOT_INITIALIZED – the Cryptoki library has not
been initialized.
CKR_DEVICE_MEMORY – there are no more free dynamic slots for
this file.
CKR_ARGUMENTS_BAD – the slot parameter is NULL. Note that the
function does not check whether the specified file exists.
3-69
C_EXT_Unbind
This function unbinds a dynamic slot from a previously assigned file. The slot
becomes free again and can be used in next C_EXT_Bind calls. If
C_EXT_Unbind is called when a slot is not bound, CKR_GENERAL_ERROR
is returned.
Syntax
CK_RV C_EXT_Unbind(
CK_SLOT_ID slot);
Parameter
♦ slot [in] – the slot number to unbind.
Return Values
CKR_CRYPTOKI_NOT_INITIALIZED – the Cryptoki library has not
been initialized.
CKR_GENERAL_ERROR – the slot is not a bound dynamic slot.
3-70
Token Event Extensions
C_EXT_WaitForSingleSlotEvent
This function waits for an event on a specific slot for a limited period of time. It
has two modes of operation: blocking and non-blocking.
Syntax
CK_RV C_EXT_WaitForSingleSlotEvent(
CK_SLOT_ID slot,
CK_FLAGS flags,
CK_ULONG timeout,
CK_VOID_PTR pReserved);
When the flags parameter is equal to zero the function operates in blocking
mode. It returns CKR_OK if a slot event had occurred or CKR_NO_EVENT
when the timeout has expired.
When the flags parameter is equal to CKF_DONT_BLOCK, the function
operates in non-blocking mode. It checks if the status of the smart card has
changed since the last call to this function and returns immediately to the calling
application. The return codes in this case are CKR_OK if a change had occurred
or since the last call to the function and CKR_NO_EVENT if no change was
detected.
Parameters
♦ slot [in] – ID of slot on which an event is monitored.
♦ flags [in] – mode of operation. 0= blocking mode,
CKF_DONT_BLOCK=non-blocking mode.
♦ timeout [in] – timeout in milliseconds.
♦ pReserved [in] – reserved. Should be NULL_PTR.
3-71
Return Values
CKR_OK – event occurred.
CKR_FUNCTION_FAILED – one of the arguments or a combination of
arguments was invalid.
initialized.
CKR_NO_EVENT – no event occurred before the timeout expired.
C_EXT_WaitForSlotEvent
This function is similar to C_EXT_WaitForSingleSlotEvent, but it can handle a
group of slots. The function receives an array of CK_SLOT_EVENT structures
(defined in the pkcsgext.h file). These structures consist of two fields:
slot – indicates the slot on which to check for an event,
bEvent – a boolean flag, which is TRUE if an event occurred on the slot
The function exits upon the first occurrence of an event on one of the slots in the
array, or when timeout expires.
Syntax
CK_RV C_EXT_WaitForSlotEvent(
CK_SLOT_EVENT_PTR pSlots,
CK_ULONG number,
CK_FLAGS flags,
CK_ULONG timeout,
CK_VOID_PTR pReserved);
Parameters
♦ pSlots [in/out] – on entry to the function should contain an array of
structures with the list of slots to be checked. Upon return, bEvent field
of the slots is set to TRUE if an event occurred.
3-72
♦ number [in] – number of slots to be checked.
♦ flags [in] – mode of operation. 0= blocking mode,
CKF_DONT_BLOCK=non-blocking mode.
♦ timeout [in] – timeout in milliseconds.
♦ pReserved [in] – reserved. Should be NULL_PTR.
Return Values
CKR_OK – event occured.
CKR_FUNCTION_FAILED – one of the arguments, or a combination of
arguments was invalid.
initialized.
CKR_NO_EVENT – no event occurred before the timeout expired.
3-73
Token and Object Extensions
C_EXT_ChangeTokenLabel
The PKCS#11 standard only enables setting the token label when the token is
formatted with C_InitToken function. The C_EXT_ChangeTokenLabel function
allows modifying the label of a formatted token. The operation can be performed
only after the user opens a R/W session and performs successful login with the
token.
Syntax
CK_RV C_EXT_ChangeTokenLabel(
CK_CHAR_PTR pLabel);
Parameters
♦ hSession [in] – handle to an open session with the token.
♦ pLabel [in] – pointer to a 32 byte blank padded buffer containing the
token label.
Return Values
CKR_OK – operation successful
CKR_FUNCTION_FAILED – pLabel parameter is NULL; Token is not
AR proprietary token (PrivateCard or file) or is not formatted properly.
CKR_SESSION_HANDLE_INVALID – the session handle is invalid.
CKR_USER_NOT_LOGGED_IN – user is not logged on.
CKR_FUNCTION_NOT_SUPPORTED – function not supported by
provider correspondent to current session
CKR_GENERAL_ERROR – unexpected error in provider dll
3-74
CKR_TOKEN_NOT_PRESENT – token not present or was removed
CKR_TOKEN_NOT_RECOGNIZED – token is not AR proprietary
token or not proprietary formatted
3-75
User Interface Extensions
C_UI_GetPassword
Note: SmartAdaptor supports this function only for backward compatibility with
previous versions. The functionality is now supported by the standard PKCS#11
functions as described below.
This function is used to pop up password entry dialog boxes that get the current
password and/or get a new password from the user for tokens that do not support
“Protected Authentication Path”. The returned passwords, could then be used in
standard PKCS#11 functions: C_Login, C_InitToken, C_InitPIN and
C_SetPIN as parameters in plain text. In old versions SmartAdaptor disabled
execution of these functions with NULL parameters for this type of tokens.
From CryptoKit version 3.6.0, this function is not needed anymore. When
calling functions that require password entry (C_Login, C_InitToken,
C_InitPIN and C_SetPIN) with NULL parameter as the password, an
appropriate PIN entry dialog box is opened.
Syntax
CK_RV C_UI_GetPassword(
CK_SLOT_ID slotID,
CK_ULONG reason,
AR_CB_PWD_DESCR_PTR pwdDescr,
CK_CHAR_PTR password,
CK_CHAR_PTR newPassword
CK_USER_TYPE userType);
Parameters
♦ slotID [in] – slot number
3-76
♦ reason [in] – reason for the call. May be one of the following values:
ARCB_REASON_LOGIN – open login dialog box and get password for
C_Login or C_InitToken.
ARCB_REASON_NEW_PWD – open init PIN dialog box and get
password for C_InitPIN.
ARCB_REASON_CNG_PWD – open change password dialog box and
get passwords for C_SetPIN
♦ pwdDescr [in] – password parameters structure
♦ password [out] – the current password
♦ newPassword [out] – the new password. NULL if the reason is
ARCB_REASON_LOGIN.
♦ userType [in] – type of the user: CKU_SO or CKU_USER
Return Values
CKR_CRYPTOKI_NOT_INITIALIZED – Cryptoki library not
initialized with C_Initialize.
CKR_SLOT_ID_INVALID – slot number is invalid.
CKR_CANCEL – the user canceled the password entry.
CKR_GENERAL_ERROR – the function was called for a token with
Protected Authentication Path; the returned password is NULL or does
not match the password parameters in pwdDescr structure.
3-77
C_UI_SetMessage
The C_UI_SetMessage function enables users to replace the standard
SmartAdaptor messages with customized messages.
Syntax
CK_RV C_UI_SetMessage(
CK_SLOT_ID slotID,
CK_ULONG ulMsgCode,
CK_CHAR_PTR message);
It is possible to dynamically set the messages that appear in the following PIN
entry dialog boxes:
Login Dialog
3-78
Init PIN Dialog
Change PIN Dialog
3-79
Parameters
♦ slotID [in] – the slot number.
♦ ulMsgCode [in] – the code of message to set. May be one of the
following values:
ARCB_HEADER_LOGIN – Login dialog header
ARCB_HEADER_INIT – Init PIN dialog header
ARCB_HEADER_CHANGE – Change PIN dialog header
ARCB_PROMPT_ENTER_PWD – prompt the user to enter password in
the Login and Change PIN dialogs
ARCB_PROMPT_INIT_PWD – prompt the user to enter new password
in the Init PIN dialog
ARCB_PROMPT_ENTER_NEW_PWD – prompt the user to enter new
password in the Change PIN dialog
ARCB_PROMPT_REENTER_NEW_PWD – prompt the user to confirm
new password in the Init PIN and Change PIN dialogs
♦ message [in] – customized message value to set
Return Values
CKR_GENERAL_ERROR – function failed
3-80
C_UI_GetMessage
The C_UI_GetMessage function enables users to get the current values of the
messages that appear in the different PIN entry dialog boxes. The returned value
is the default message or the last customized message value that was set with
C_UI_SetMessage.
Syntax
CK_RV C_UI_GetMessage(
CK_SLOT_ID slotID,
CK_ULONG ulMsgCode,
CK_CHAR_PTR message);
Parameters
♦ slotID [in] – the slot number.
♦ ulMsgCode [in] – the code of message to get. For a complete list see
values of this parameter in C_UI_SetMessage above.
♦ message [out] – the current value of the message
Return Values
CKR_GENERAL_ERROR – function failed
3-81
User Interface Customization

SmartAdaptor has a built-in mechanism that allows organizations to customize
and localize the PIN entry dialogs. You can change the images, the position and
size of the controls and their text and font to suite your needs. Then, you can add
the modified user interface file to your installation package of CryptoKit and
make it available to your clients.
To do that, follow the steps below:

♦ Copy the file ArGui.dll, which is part of the CryptoKit installation
package into a new file called ArUsrGui.dll.
♦ Open the file ArUsrGui.dll for editing as Resource using

Microsoft’s Visual C++ Editor.
♦ Edit the dialogs to suite your needs: change the images, the position and
size of the controls and their text and font to suite your needs
♦ Open the string table and change the dialog texts if needed
♦ Save the file and copy it to the CryptoKit installation package
♦ Edit the CK_SETUP.INI file in the CryptoKit installation package and
add the following line to the [CopyFiles] section:
arusrgui.dll = <WINSYSDIR>\arusrgui.dll
This command will copy the new user interface dll to your client’s
machines during the installation.
3-82
Chapter 4: AR Cryptographic Service Provider
AR cryptographic service provider is an integral part of the CryptoKit package.

Built over SmartAdaptor, it provides advanced cryptographic services for
Microsoft CAPI-based applications. CryptoKit has been successfully tested with
the following applications:
♦ Authentication to Windows domain with Microsoft Windows smart card
logon (Windows 2000 and Windows XP)
♦ Authentication to VPN networks such as: Microsoft VPN, CheckPoint
SecuRemote, Cisco and others
♦ SSL based authentication to connect to secure Web sites with Microsoft
Internet Explorer
♦ Signing and encrypting mail with Microsoft Outlook, Outlook Express
and Novell GroupWise.
♦ Signing and encrypting Microsoft Word documents with Office XP
♦ Enrollment with Microsoft CA, Verisign, Baltimore, SSH and more.
♦ SChannel provider for Microsoft IIS
♦ And many more applications …
4-1
Microsoft CryptoAPI and Crypto Service Providers
Microsoft provides an API called Crypto API (CAPI) to support cryptographic

and PKI (Public Key Infrastructure) operations. The API includes support for
general cryptographic operations such as hash, encryption with symmetric keys
as well as operations on certificates, public keys and private keys.
Microsoft CryptoAPI can work with a number of Cryptographic Service

Providers (CSPs) that perform the actual cryptographic functions. Each CSP
may be from a different vendor and may have different cryptographic
capabilities. By default the Microsoft CSP is installed on any Windows
operating system.
Applications do not communicate directly with a CSP. Instead, they call

CryptoAPI functions (with a "Crypt" prefix) exposed by the operating system's
Advapi32.dll and Crypt32.dll files. Applications specify which CSP
will be used to perform the required operation. The operating system
communicates with CSPs through the cryptographic service provider interface
(CSPI). It filters the function-calls and passes them to the appropriate CSP
functions through CryptoSPI.
A CSP consists of a dynamic-link library (DLL) that implements the functions

in CryptoSPI. The CSP must be signed by Microsoft to ensure its authenticity
and validity and has to be registered in the operating system before applications
can use it.
As mentioned above, the CryptoAPI also provides support for handling PKI
applications and specifically functions for handling certificates, which are kept
in certificate stores. The CryptoAPI provides functions that manage certificate
stores, and work with the certificates within those stores. These functions (with a
"Cert" prefix) provide tools to store, retrieve, delete, list (enumerate), and verify
certificates.
Certificates in a certificate store are normally kept in some kind of permanent

storage. Each user has a personal store called MY. The store contains all the
4-2
AR Cryptographic Service Provider 4
user's certificates. The MY store can be at any one of many physical locations,
including the registry on a local or remote computer, a file, data base, directory,
a smart card, or other location. While any certificate can be stored in the MY
store, this store should be reserved for user's personal certificates which are used
for performing cryptographic operations such as signing and decrypting that
user's messages.
The following illustration shows these concepts.
Application A Application B
Application
Crypto API
Layer
“Crypt…” API “Cert…” API Operating
System
System certificate store
Crypto SPI
CSP #1 CSP #2 CSP #… Physical Physical

Store #1 Store …
Microsoft ARCSP Other Service
Base Vendors Provider
Crypto CSP
Provider
CSP Types
Cryptographic standards are organized into groups known as families. Each

family includes a set of data formats and protocols. Even if they use the same
algorithm, two families will often use different cipher modes, key lengths, and
default modes. In CryptoAPI, each CSP type represents a distinct family.
4-3
By default, when an application connects to a particular type of CSP, each of the

CryptoAPI functions operates in a way prescribed by the family that corresponds
to that CSP type. An application's choice of provider type specifies the
following items:
CSP Type Description

Property
Key exchange Each provider type specifies only one key exchange algorithm
algorithm and every CSP of that type must implement the same algorithm.
Applications specify the key exchange algorithm by selecting a
CSP of the appropriate provider type.
Digital Each provider type specifies only one digital signature algorithm
signature and every CSP of that type must implement the same algorithm.
algorithm Applications specify the digital signature algorithm by selecting
a CSP of the appropriate provider type.
Key BLOB The provider type determines the format of the key BLOB used to
formats export keys from the CSP and to import keys into a CSP.
Digital The provider type determines the digital signature format. This
signature ensures that a signature produced by a CSP of a given provider
format type can be verified by any CSP of the same type.
Session key The provider type determines the method used to derive a session
derivation key from a hash.
scheme
Key length Some provider types specify the length of public/private key
pairs and the session keys.
Default modes The provider type often specifies default modes for various
options, such as the block encryption cipher mode or the block
encryption padding method.
For additional information about the CSP concept, certificate stores, CryptoAPI
functions refer to Microsoft documentation. The documentation also includes
4-4
many sample programs that demonstrate how to perform cryptographic
operations using the CryptoAPI.
CAPI Data Objects
CAPI Applications use handles to refer to data objects in the CSP such as key
containers, hash objects, session key objects, and public/private key pair objects.
Context
A context is a temporary object that contains key objects, hash objects, and a
handle to a specific key container. It enables applications to query and set info of
the specific CSP it uses.
Key Objects
Key objects may be symmetric keys (DES, RC4, etc.) or asymmetric public
keys. They are created only for temporary use and each is associated with a
specific context. A key object is destroyed when the context is released. The
only case when key objects are stored on the token is when importing private
asymmetric keys (RSA key).
Hash Objects
Hash objects are temporary objects that are used to hash data. They are
associated with a specific context and destroyed when the context is released.
Key Containers
Key containers are not temporary objects. They are stored on the smart card and
contain up to two pairs of public and private keys. The signature key pair is used
to create digital signatures and the exchange key pair is used to both encrypt
session keys and create digital signatures.
A specific key container is available for the application only when the
cryptographic token on which it is stored is available.
4-5
A key container may be empty i.e. without any keys. It is possible to create the
key container at a specific time and to generate the keys later.
Each key container must have a unique name to distinguish it from other key
containers. When an application wants to use a specific key container, it can
acquire a context to it, by specifying its name.
ARCSP Provider
ARCSP Provider Types
Algorithmic Research provides two types of CSPs.
Base RSA Provider

The base RSA cryptographic provider offers a board range of cryptographic
services such as hash, encryption and digital signature. It is using the RSA
public-key algorithm for public-key operations. It is available for all Windows
operating systems.
RSA SChannel Provider

The SChannel cryptographic provider offers various cryptographic services that
are required for data integrity, session key exchange, and authentication during
secure Web communications with the SSL3 and TLS protocols. The SChannel
provider allows integration of Algorithmic Research’s PrivateServer HSM with
Microsoft IIS. It is available only on Windows 2003 server.
Architecture
ARCSP provides cryptographic support for applications that use Microsoft

CAPI. It serves as an interface between the CryptoAPI and the
PKCS#11-compliant SmartAdaptor. Therefore, it benefits all the special
advantages of SmartAdaptor.
4-6
Following is a list of some of the major characteristics of ARCSP provider:
♦ Support for all AR tokens – ARCSP enables an application to use
simultaneously all the key containers that reside in any of the
cryptographic tokens, which are present at a given time. SmartAdaptor
provides easy access to all the key containers, which reside in a
PrivateCard inserted to a reader (PrivateSafe, CryptoSafe, PrivateSafe
PCMCIA or any other PC/SC reader), a MiniKey, a software token,
PrivateServer HSM or CoSign appliance.
♦ Multiprocess/Multithread – ARCSP is thread safe and process safe as
the CSP is built over SmartAdaptor technology.
However, in a multi-threaded application it is recommended not to share
context handles between threads. If you use the same key container in
several threads, you should acquire a new context for each thread. This
will prevent errors when one thread needs to perform an operation with
an object that is locked by another thread at the same time.
♦ Shared keys and objects with PKCS#11 applications – It is possible to
use the same keys and certificates with both CAPI and PKCS#11
applications. A PKCS#11 application can access the objects that were
created in the token with ARCSP and vise versa. However, in some cases
PKCS#11 objects may need to be modified in order to be recognized by
ARCSP. For more information refer to standardize operation in AR
Genie utility.
ARCSP stores the key containers as PKCS#11 objects. The private key is
stored as a RSA private object and the public key is stored as a RSA
public object. Both objects have the same CKA_ID attribute, as the
corresponding certificate. This enables to group the objects of the same
key container together. ARCSP differentiates between the exchange and
signature key pairs by setting a different value to the PKCS#11 WRAP
attribute. The exchange public key has the wrap flag set, while the
signature public key has it cleared.
♦ Support for tokens with protected authentication path – When using a
token with protected authentication path such as AR PrivateSafe, the PIN
is entered in a secure way.
4-7
♦ Support for general cryptographic operations – In some cases an

application needs to perform operations that do not require a specific key
container. ARCSP enables performing such operations even if no
cryptographic token is available.
♦ Support for read only tokens – An application can use read only tokens.
ARCSP will access the existing key containers but will not be able to
create new ones.
♦ SmartAdaptor provides the user interface – The ARCSP uses the same
user interface, which is provided by the SmartAdaptor. No additional
GUI is required from an application that uses ARCSP.
♦ Support for unattended processes – SmartAdaptor provides means for
unattended processes to gain access to private keys on the token. This
feature is required by some CAPI applications that cannot present any
user interface such as services. SmartAdaptor also provides an SSO
mechanism, which can be used by CAPI applications that acquire a silent
context.
♦ CAPI adapter for other core providers – It is possible to register in
SmartAdapter PKCS#11 core providers of other vendors and provide
them with a full CAPI functionality. The vendor’s PKCS#11
implementation has to comply with some minimum requirements.
However, there are some limitations that arise when using PKCS#11 for
performing the cryptographic operations. ARCSP is designed to minimize them:
♦ If a token is inserted to a reader and an application acquires a context to
the key container on it. Then, the token is removed and inserted into
another reader. When the application will access the key container that
was received when the card was in the previous reader, it will find it on
the new reader and continue to work as if nothing has changed.
♦ The CSP requires that at any given time, only one key container with a
specific key container name should be available in all present tokens.
But, it is possible to create two smart cards with the same key container
name and insert them at the same time into two different readers. In that
case the behavior of ARCSP is undetermined.
4-8
♦ If you install a new reader, it will not be available to existing applications
until you reset the application. However, it is possible to configure
ARCSP to load the list of the available readers when the application
releases all open contexts. For more information refer to explanation
about the parameter FinalizeLibraryUse in Chapter 7.
Provider Registration
When installing CAPI feature in the CryptoKit installation program, the

following provider is added to the list of registered CSPs:
CSP Provider Name AR Base Cryptographic Provider
Provider Type PROV_RSA_FULL (1)
Image Path Arcsp.dll
ARCSP indicates that it supports hardware, software and removable devices.
On Windows 2003 server, an additional cryptographic service provider is

registered:
CSP Provider Name AR RSA SChannel Cryptographic Provider
Provider Type PROV_RSA_SCHANNEL (12)
Image Path Arcsp.dll
Signature
ARCSP is digitally signed by Microsoft and can be used with the released
versions of Windows 2003 server, Windows XP, Windows 2000,
Windows NT(SP6), Windows 98(+SE) and Windows ME.
4-9
Prior to Windows 2000, the signature is placed appropriately in the registry.

Windows 2000 introduces placing the digital signature as a resource in the CSP
DLL (arcsp.dll).
Versions
ARCSP is built over the SmartAdaptor PKCS#11 interface. The type of

SmartAdaptor in use (Basic or Extended) determines the type of ARCSP. The
two versions are characterized as follows:
♦ Basic supports DES 40 bit key length, RC2 (key length up to 64 bits),
RC 64 (key length up to 64 bits).
♦ Extended supports DES, Triple-DES, Double-DES, RC2 (key length up
to 1024 bits), and RC4 (key length up to 2048 bits).
All versions support the RSA, hash and key derivation algorithms.
Supported Algorithms
The following table lists the algorithms supported by AR Base Cryptographic

Provider:
Algorithm ID Description Comments

CALG_MD2 MD2 hash algorithm
CALG_MD5 MD5 hash algorithm
CALG_SHA SHA hash algorithm
CALG_SHA1 Same as CALG_SHA
CALG_SHA_256 SHA-256 hash algorithm
4-10
CALG_SSL3_SHAMD5 SHA & MD5 hash
algorithm
CALG_MAC MAC keyed-hash Block cipher MAC

algorithm
CALG_HMAC MAC keyed-hash HMAC computation

algorithm
CALG_RSA_SIGN RSA public-key signature Key length: adjustable,

algorithm 512 bits to 4096 bits in
256 bit increments
(depends on the token
used)
Default key length: 1024
bits
CALG_RSA_KEYX RSA public-key exchange Same as

algorithm CALG_RSA_SIGN
CALG_RC2 RC2 block encryption Default key length: 128

algorithm bits
Default effective key len:
40 bits
Default mode: Cipher
block chaining (CBC)
Block size: 64 bits
Salt not supported
CALG_RC4 RC4 stream encryption Default key length: 128

algorithm bits
Salt not supported
CALG_DES DES block encryption Key length: 56 bits

algorithm Default mode: Cipher
padding
4-11

CALG_3DES_112 2DES block encryption Key length: 112 bits
padding
CALG_3DES 3DES block encryption Key length: 168 bits

padding
The AR RSA SChannel Cryptographic Provider supports all the algorithms that
are supported by the RSA provider and also additional algorithms that are
needed for SSL3 and TLS.
Algorithm ID Description
CALG_SSL3_MASTER
CALG_TLS1_MASTER
All these algorithms are used by the
CALG_SCHANNEL_MASTER_HASH SChannel system to derive SSL3 and
TLS session keys
CALG_SCHANNEL_MAC_KEY
CALG_SCHANNEL_ENC_KEY
Supported Functions
ARCSP supports most of the functions that are required from a CSP by
Microsoft. However, there are a few differences in AR’s implementation: some
functions and flags are not supported; there are few proprietary parameters and
finally, there are cases where the standard is not binding and may be interpreted
in different ways.
4-12
The following table describes the functions that are supported by AR
cryptographic service providers and highlights only the specific differences in
AR’s implementation:
Function Comments
CryptAcquireContext In addition to the regular use, it is possible to
enumerate the containers or get information on a
specific smart card. To do that, set the
CRYPT_VERIFYCONTEXT flag and specify the
name of the specific reader in the container name in a
fully qualified container name format (\\.\”
readername”). Then call CryptGetProvParam to
enumerate the containers with that context.
If CRYPT_VERIFYCONTEXT flag is set, the

container name must be NULL or empty string
(except for the case described above).
CRYPT_MACHINE_KEYSET is ignored.
CryptReleaseContext
CryptSetProvParam PP_KEYSET_SEC_DESCR – not relevant for smart

card CSP
PP_ADMIN_PIN – not supported
CryptGetProvParam PP_KEYSET_SEC_DESCR – not relevant for smart

card CSP
PP_UNIQUE_CONTAINER – returns the unique

container name of the current key. The behavior of
the CSP, though, is unpredicted if you insert two
tokens which both have a container with same name.
PP_USE_HARDWARE_RNG – ARCSP always

returns FALSE in this flag because it can’t guaranty
that a hardware token will be selected. However, if
that is the case, the random will be from the hardware
source.
4-13
Function Comments
CryptGenRandom If the key of the container is stored on hardware token
then the random number is also generated on the
hardware token.
CryptCreateHash
CryptDestroyHash
CryptGetHashParam
CryptSetHashParam
CryptHashData
CryptGenKey CRYPT_CREATE_SALT – not supported

CRYPT_ARCHIVABLE – not supported
CryptDeriveKey CRYPT_CREATE_SALT – not supported
CryptDestroyKey
CryptGetKeyParam KP_SALT – not supported

KP_SALT_EX – not supported
CryptSetKeyParam KP_SALT – not supported

KP_SALT_EX – not supported
CryptEncrypt CRYPT_OAEP – not supported
CryptDecrypt CRYPT_OAEP – not supported
CryptHashSessionKey CRYPT_LITTLE_ENDIEN – not supported on non

extractable key
CryptExportKey SYMMETRICWRAPKEYBLOB – not supported

PLAINTEXTKEYBLOB – not supported
CRYPT_OAEP – not supported
4-14
Function Comments
CryptImportKey SYMMETRICWRAPKEYBLOB – not supported
PLAINTEXTKEYBLOB – not supported
CRYPT_OAEP – not supported
CryptGetUserKey
CryptSignHash SDescription parameter is not supported. It must be

NULL, as recommended by Microsoft.
CryptVerifySignature
CryptDuplicateHash Supported only by the SChannel provider
CryptDuplicateKey Function not supported
4-15
Certificate Store
Certificates are kept and maintained in certificate stores. Certificates can be

issued to users, computers, services or any other entity that has to be identified.
Each entity has certificate store to maintain its own certificates (MY store), root
certificates, intermediate certificates and others.
The MY store can be implemented by any one of many physical locations.

While any certificate can be stored in the MY store, this store should be reserved
for a user's personal certificates which are used for performing cryptographic
operations. The matching keys for these certificates are expected to be available.
In order to make the keys stored in AR’s tokens available for use, ARCSP has to
make sure that the certificates of these keys are placed into MY store of the user.
When the token is not available the certificate has to be removed from the store.
This mechanism is implemented in two ways, depending on the operating

system.
Store Functionality on Win 98, ME and NT
The certificates from all available tokens are loaded into the MY store of the
user that logged in to the computer. A special process monitors token insertion
and removal. When a token is inserted, the process adds the certificates to the
MY store and when removed, the certificates are removed from the store.
When a new certificate is written into the MY store and it is not placed in any
available token but its matching keys are placed in one of the tokens, the same
process will recognize the event and add that certificate to that token. This
normally happens during key/certificate enrollment or key/certificate import
operation.
This process does not provide a solution in cases where a newer certificate
replaced the previous one, while the token was inserted. In that case the MY
store will still contain the old certificate.
4-16
Physical Certificate Store on Windows 2000, XP and 2003
On Windows 2000, Windows XP and Windows 2003, Microsoft developed a

new mechanism called physical certificate store that allows better handling of
certificate stores. Each certificate store has two layers: logical layer and physical
layer. The logical layer is called system store and does not contain any
certificates. Rather, it contains several physical certificate stores. Each operation
on the system store activates one or more of its physical certificate store
members. Each system store has at least one member, which is the Microsoft
default physical certificate store.
AR physical store implementation hooks some of the store operations. When

called, it performs the required operation on the available tokens. AR hooks to
the following store functions:
♦ Open – This store event results from an application calling the functions
CertOpenSystemStore or CertOpenStore. The application wants to
receive all the available certificates. This triggers ARCSP to enumerate
all key containers on the currently available tokens.
♦ Add – This store event results from an application calling the function
CertAddCertificateContextToStore in an attempt to add a certificate to
the system store. If the certificate being added has it’s matching keys on
one of AR’s available tokens, it is written into it. If not, AR’s physical
store will report the system store that it did not handle it and the
certificate will be placed at a different physical store, probably the
Microsoft default store.
♦ Delete – This store event results from an application calling the function
CertDeleteCertificateFromStore in an attempt to delete a certificate from
the store. If the certificate has a matching key pair on one of AR’s
available tokens it should be deleted from the token. Currently, AR’s
implementation does not physically remove the certificate from the
token.
♦ Close – This store event results from an application calling the function
CertCloseStore to close the store. No specific operation is done in that
event.
4-17
Export/Import Functionality
ARCSP offers Export/Import capabilities of keys and certificates:

♦ Export – this operation can be performed on both hardware and software
tokens but only on extractable keys. Keys that are not extractable or that
are sensitive cannot be exported.
♦ Import – though supported for all kind of tokens, Microsoft applications
(IE and Outlook) permit import operations only in the case of objects that
were exported using the same provider.
As a result, when working with ARCSP, Export/Import operations can only be

performed from AR’s tokens to any of AR’s (hardware or software) tokens.
CryptoKit offers another method for importing and exporting keys using the
PKCS#12 Import/Export utility. This utility can export any extractable key from
AR tokens and to import it to any other token. For more information about this
utility refer to PKCS#12 Import/Export utility in Chapter 6.
4-18
Chapter 5: SmartAdaptor Add-On Adapters
The main SmartAdaptor cryptographic API focuses on the PKCS#11 interface,

enabling PKCS#11-based applications to use it directly. SmartAdaptor
technology also permits developers to build a variety of other adapters over the
PKCS#11 interface for applications and platforms that are not PKCS#11-based,
allowing their required functionality to be implemented over PKCS#11
functionality.
Thanks to the robustness of the CryptoKit PKCS#11 API, most of the other
cryptographic interfaces can be implemented on top of it. The CryptoKit
package contains the following adapters and extensions:
♦ Java adapter
♦ Entrust adapter
♦ X.509 Toolkit extension
♦ PKCS#10,#7 Toolkit extension
♦ PKCS#12 Toolkit Extension
All these adapters have multi-provider, multi-slot, multi-process, and multi-

thread functionality.
5-1
Java Adapter
The CryptoKit package includes two Java libraries:

♦ ARJCA – standard Java Cryptography Architecture (JCA) provider.
♦ AR Java PKCS – AR proprietary Java adapter that provides PKCS#11
style API to Java applications.
ARJCA
The Java Security API is a core API of the Java programming language, built
around the java.security package and its sub-packages. This API is designed to
allow developers to incorporate both low-level and high-level security
functionality into their programs.
The first release of Security API in JDK 1.1 introduced the Java Cryptography
Architecture (JCA), a framework for accessing and developing cryptographic
functionality for the Java platform. In JDK 1.1, the JCA included APIs for
digital signatures and message digests.
In subsequent releases, the Java 2 SDK significantly extended the Java

Cryptography Architecture. It also upgraded the certificate management
infrastructure to support X.509 v3 certificates, and introduced a new Java
Security Architecture for fine-grain, highly configurable, flexible, and extensible
access control.
The JCA encompasses the parts of the Java 2 SDK Security API related to
cryptography, as well as a set of conventions and specifications provided in this
document. It includes a provider architecture that allows for multiple and
interoperable cryptography implementations.
5-2
SmartAdaptor Add-On Adapters 5
The detailed explanation about JCA and numerous samples can be found on the
Sun Java home page at:
http://java.sun.com/j2se/1.4.2/docs/guide/security/Cry
ptoSpec.html
AR implementation
The ARJCA implements the following JCA interfaces:
♦ KeyPairGenerator methods for the generation of RSA keys.
♦ Signature methods for RSA signatures. Supported algorithms are
SHA1withRSA and MD5withRSA.
♦ KeyFactory methods for creating a key from a specification or returning
a key specification of a key. ARJCA supports creation of objects from
the following specifications:
Private keys can be created from PKCS8EncodedKeySpec or
RSAPrivateCrtKeySpec.
Public keys can be created from X509EncodedKeySpec or
RSAPublicKeySpec.
ARJCA returns key specification in the following formats:
RSAPrivateKeySpec or RSAPrivateCrtKeySpec for RSA private
keys.
RSAPublicKeySpec for RSA public key.
The KeyFactory also enables to translate Sun RSA keys into AR RSA
keys.
♦ KeyStore methods are used for saving keys into the key store (token).
Supported functionalities are:
Storing of RSA public/private keys generated or created using
ARJCA KeyPairGenerator or KeyFactory.
Storing of RSA public/private keys generated or created by any
other JCA provider. This operation will succeed only if the
5-3
provider can supply the necessary data for creation of the key
objects.
Storing of X.509 certificates.
Installation
ARJCA has to be installed on a computer with CryptoKit and Java Runtime
Environment. Follow the steps below:
♦ Copy arjca.jar and ckit.jar files to:
...\JAVA_DIR\jre\lib\ext
where JAVA_DIR is the directory where Java is installed on the
computer.
♦ Edit the Java security file java.security in the
...\JAVA_DIR\jre\lib\security directory.
Find the place in the file where the list of installed providers is
declared. It should look as follows:
security.provider.1=sun.security.provider.Sun
security.provider.2=...
If you want the AR provider to be the default provider, for the
functionalities it supports, put it first in the list and adjust the
priorities for others, so the list will look as follows:
security.provider.1=COM.arx.jca.ARJCA
security.provider.2=sun.security.provider.Sun
security.provider.3=...
Otherwise, put it at the end of the list and set it's priority
accordingly. Since many applications access only the default
provider, it is recommended to set the ARJCA as such.
♦ Copy the arjca.conf file into user home directory. For example on
Windows 2000:
C:\Documents and Settings\UserName.DomainName
5-4
Configuration File Parameters
The configuration file enables setting different parameters for the ARJCA
provider. The arjca.conf file has to be in the user home directory. If it
doesn’t exist, then default values are taken. The file is read during the
initialization of the library. It has a standard windows INI file format with three
sections: General, Log and RSA.
The General section has the following parameters:

♦ NoGUI – this parameter is used during generation or creation of a key. If
there is more than one slot installed and inserted, ARJCA pops a window
in which the user is requested to select the token on which the operation
will to be performed. When the NoGUI parameter is 1, this behavior is
disabled and the DefaultSlot parameter is used instead. The default of
NoGUI parameter is 0 (false), i.e. GUI is allowed.
♦ DefaultSlot – this parameter sets the default slot on which ARJCA will
generate and create RSA keys when user interface is disabled (NoGUI
parameter is true). The default for this parameter is 1, i.e. to use the first
slot.
♦ PKCS11Lib – this parameter lets you change the deafult PKCS#11
library (sadaptor) to a new one. Enter the name of the PKCS#11 library
to be used in this parameter
The Log section has only one parameter:

♦ LogLevel – this parameter controls the ARJCA log level. Value of 0,
which is the default, disables the log. Values 1, 2 and 3 sets it to basic,
medium and high levels respectively. The log file is called arjca.log
and is located in the user’s home directory.
The RSA section has the following parameters:

♦ KeySize – this parameter sets the default key size for RSA key
generation. It is used only when the user didn’t specify explicitly the size
5-5
of the RSA key using the initialize method of the KeyPairGenerator

class. The default value for this parameter is 1024
♦ Extractable – this parameter controls whether ARJCA will generate or
create extractable keys. The default of this parameter is 0, i.e. ARJCA
normally generates non-extractable keys.
5-6
Sample JCA Program
The following sample demonstrates a basic usage of three JCA classes:
KeyPairGenerator, Signature and KeyStore. It generates an RSA key pair, signs
a buffer with the private key, verifies the result with the public key and then
stores the public key on the token. The program explicitly uses ARJCA
provider, but it can be easily modified to work with any other provider that
supports similar functionalities.
import java.io.*;
import java.util.*;
import java.security.*;
import java.security.cert.*;
import java.security.spec.*;
import java.security.interfaces.*;
public class JHL {

private byte[] data = new byte[100];
private byte[] sig = null;
String passw = "12345678";
public static void main(String[] args) {

new JHL();
}
public JHL() {
for (int i = 0; i < data.length; i++) {
data[i] = (byte) i;
}
basic_test();
}
public void abort(String error) {
System.out.println(error);
System.exit(1);
}
public void exc_abort(Exception e) {
e.printStackTrace(System.out);
System.exit(1);
}
private void basic_test() {
KeyPair k_pair = GenerateRSAKeys();
5-7
sig = RSAsign(data, k_pair);

if (RSAverify(data, sig, k_pair)) {
System.out.println("Verify OK");
}
else {
abort("Verify NOT OK");
}
StorePublic("pub key1", k_pair);
System.out.println("Test OK!");
}
public boolean StorePublic(String pubName,

KeyPair RSAkeys) {
System.out.println("Storing RSA public key..");
try {
KeyStore ks =
KeyStore.getInstance("JKS", "ARJCA");
ks.load(null, null);
Key pub = RSAkeys.getPublic();
ks.setKeyEntry(pubName, pub, passw.toCharArray(),
null);
return true;
}
catch (Exception ex){
exc_abort(ex);
}
return false;
}
public boolean RSAverify(byte[] buffer, byte[]
signature, KeyPair RSAkeys) {
System.out.println("Verifying..");
try {
PublicKey pub = RSAkeys.getPublic();
Signature sig=Signature.getInstance("SHA1withRSA",
"ARJCA");
sig.initVerify(pub);
sig.update(buffer);
return sig.verify(signature);
}
catch (Exception e) {
5-8
exc_abort(e);
return false;
}
}
public byte[] RSAsign(byte[] buffer, KeyPair RSAkeys) {
System.out.println("Signing..");
try {
PrivateKey priv = RSAkeys.getPrivate();
Signature sig=Signature.getInstance("SHA1withRSA",
"ARJCA");
sig.initSign(priv);
sig.update(buffer);
System.out.println("Sign OK");
return sig.sign();
}
exc_abort(e);
}
return null;
}
public KeyPair GenerateRSAKeys() {
System.out.println("Generating RSA pair..");
KeyPairGenerator keyGen = null;
try {
keyGen=KeyPairGenerator.getInstance("RSA",
"ARJCA");
keyGen.initialize(1024);
KeyPair keypair = keyGen.genKeyPair();
System.out.println("Generate OK");
return keypair;
}
exc_abort(e);
}
return null;
}
}
5-9
AR Java PKCS
The AR Java package (ckit.jar) provides PKCS#11 style API access to Java
applications. The Java adapter is implemented through a JNI interface (Java
Native Interface) over a C-based PKCS#11 SmartAdaptor interface, providing a
set of Java classes for use by developers. While these classes present PKCS#11
functionality in proprietary manner, it remains very similar to the native
PKCS#11 architecture, structures and functions, enabling developers already
familiar with the PKCS#11 standard to start using these Java classes without a
significant learning curve. The detailed information about these Java classes is
provided in the JavaDoc files, which is archived in the JavaCKit folder of the
CryptoKit installation.
Main Packages
The ckit.jar contains two packages: COM.arx.jpkcs11 and
COM.arx.jpkcs11.Native.
The COM.arx.jpkcs11 package defines classes that are very similar to

PKCS#11 standard. It uses the JNI to communicate with the AR native Java dll
(ar_jpk11.dll), which calls the underlying PKCS#11 provider supplied by
SmartAdaptor (sadaptor.dll).
The COM.arx.jpkcs11.Native package contains the classes that extend the

classes in the COM.arx.jpkcs11 package and communicate directly with the
ar_jpk11.dll using JNI.
Main Classes
Following is a list of some of the main classes in ckit.jar. These classes belong
to the COM.arx.jpkcs11 package and are extended by the corresponding classes
in the COM.arx.jpkcs11.Native package. For a complete list refer to the JavaDoc
files in CryptoKit installation.
♦ AR_JPKCS11 This class initializes the PKCS#11 library through the
getInstance method. It returns the slot list and provides additional general
functions.
5-10
♦ AR_JPKCS11Slot This class implements all the PKCS#11 slot
functionality. All PKCS#11 functions, which relate to a slot, are mapped
into a corresponding method in this class with the same functionality.
Some of the methods in this class are: openSession, getMechanismList,
initToken, waitForSlotEvent etc.
♦ AR_JPKCS11Session This class implements all the PKCS#11 session
related functionality, such as login, creation of objects, generation of
keys and performing cryptographic operations like hash, sign, encrypt,
decrypt etc. A session object is created by openSession method of the
AR_JPKCS11Slot class.
♦ AR_JPKCS11Object This class implements all the PKCS#11 object
related functionality, such as setting and getting object attributes,
destroying objects etc. It includes the object template constants such as
class, token, sensitive, extractable etc. An object of this class can be
created by several methods for example by generateKeyPair method of
the AR_JPKCS11Session class.
♦ AR_JPKCS11Mechanism This is an abstract class that defines the
PKCS#11 mechanisms and returns the mechanism info object through
the getInfo method.
♦ AR_JPKCS11Exception This is an extension of Java Exception class.
All the PKCS#11 errors are thrown through it. It is possible to get a text
explanation about each error by using the errorMessage method.
Sample Program
The following sample program shows how to use AR Java PKCS provider to
generate an RSA key pair and then sign a buffer with the private key.
import java.io.*;
import COM.arx.jpkcs11.*;
import COM.arx.jpkcs11.Native.*;
try {
// Initialize
5-11
AR = (AR_NativePKCS11)
(AR_JPKCS11.getInstance("Sadaptor", null, 0));
AR_JPKCS11Slot[] slots;
// Get slot list

slots = AR.getSlotList(true);
AR_JPKCS11Session sess;
if (slots.length > 0) {
sess = slots[0].openSession(
AR_JPKCS11SessionInfo.AR_JPKCS11_FLG_RW_SESSION |
AR_JPKCS11SessionInfo.AR_JPKCS11_FLG_SERIAL_SESSION,
null, null);
}
else {
return;
}
// Create the templates for RSA key pair generation

AR_JPKCS11ObjectAttribute[] attr_pub =
new AR_JPKCS11ObjectAttribute[4];
AR_JPKCS11ObjectAttribute[] attr_priv =
new AR_JPKCS11ObjectAttribute[2];
byte[] Exponent =
{(byte)0x0,(byte)0x1,(byte)0x0,(byte)0x1};
// Public key template

attr_pub[0] = new AR_JPKCS11ObjectAttribute(
AR_JPKCS11Object.AR_JPKCS11_CLASS,
AR_JPKCS11Object.AR_JPKCS11_CLASS_PUBLIC_KEY);

AR_JPKCS11Object.AR_JPKCS11_KEY_TYPE,
AR_JPKCS11Object.AR_JPKCS11_KEY_TYPE_RSA);

AR_JPKCS11Object.AR_JPKCS11_MODULUS_BITS,
new Integer(1024));
5-12
AR_JPKCS11Object.AR_JPKCS11_PUBLIC_EXPONENT,
new BigInteger(Exponent));
// Private key template

attr_priv[0] = new AR_JPKCS11ObjectAttribute(
AR_JPKCS11Object.AR_JPKCS11_CLASS,
AR_JPKCS11Object.AR_JPKCS11_CLASS_PRIVATE_KEY);
attr_priv[1] = new AR_JPKCS11ObjectAttribute(

AR_JPKCS11Object.AR_JPKCS11_KEY_TYPE,
AR_JPKCS11Object.AR_JPKCS11_KEY_TYPE_RSA);
// Create mechanism object

AR_JPKCS11Mechanism mech_gen =
new AR_NativePKCS11Mechanism(
AR_JPKCS11Mechanism.AR_JPKCS11_MECH_RSA_PKCS_KEY_PAIR_GEN,
sess.getSlot(), null);
// Generate key pair: keys[0] public, keys[1] private

AR_JPKCS11Object keys[] = sess.generateKeyPair(mech_gen,
attr_pub, attr_priv);
AR_JPKCS11Mechanism mech_sign =
new AR_NativePKCS11Mechanism(
AR_JPKCS11Mechanism.AR_JPKCS11_MECH_MD5_RSA_PKCS,
sess.getSlot(), null);
// Perform sign operation

sess.signInit(mech_sign, keys[1]);
byte [] buffer = "To be signed".getBytes();
byte [] signature = new byte[128];
sess.sign(buffer, 0, buffer.length, signature, 0);
}
catch (Exception ex) {

System.out.println(“Exception!”);
ex.printStackTrace(System.out);
System.exit(1);
}
5-13
Entrust Adapter
Entrust Desktop solutions are PKCS#11-based applications. They use PKCS#11

version 2.01 API, but are not always fully PKCS#11 compliant. In some cases
they interpret some PKCS#11 specifications in a proprietary manner. To
overcome this limitation, SmartAdaptor contains a specially developed Entrust
adapter (cycpten5.dll) for Entrust versions 5 and 6. CryptoKit has been
tested successfully on the following Entrust applications:
Entrust PKI system
Entrust/RA v5.1 Graphical interface to Entrust PKI system used to

manage a secure database of Entrust PKI.
Entrust/Entelligence Works with Entrust/Authority to automate key

v5.1, v6.0 management for users. It enables users to encrypt,
decrypt, digitally sign and verify data.
Entrust Desktop Solution applications v5.1, v6.0
Entrust/Express Fully featured e-mail application that provides key and

certificate management. It enables users to encrypt,
decrypt, digitally sign and verify e-mails.
Entrust/TrueDelete Works in the background to delete files from disk

according U.S. Department of Defense standards. It
protects the swap file, locates hidden temporary files,
and deletes files so that they cannot be retrieved by
disk recovery utility.
Entrust ICE Protects sensitive information by encrypting files in a

specified folder.
5-14
Entrust Desktop Solution applications v5.1, v6.0
Entrust/Direct Provides permanent records of user transactions.

Works with standard browsers and Web servers to
provide strong encryption and centralized control over
security policy.
Entrust/SingOn Allows user to login once to the Windows operating

system and all Entrust-Ready applications.
Entrust 6 CA enables using the keys and certificates with CAPI based
applications. When this option is selected in the Entrust CA, the user certificates
are written on the public area of the token. In order for ARCSP to be able to use
these keys there is an additional step that has to be done. A special procedure
called “standardize” which can be activated from AR Genie utility program
creates a corresponding public key and verifies that all objects have the same ID
value. In that way ARCSP is capable of identifying the containers on the token
and makes them available for CAPI applications. For more information refer to
explanation about the AR Genie utility in chapter 6.
5-15
X.509 Toolkit
With the addition of the X.509 Toolkit, The PKCS#11 CryptoKit now supports
the X.509 v.3 certificate standard.
The X.509 Toolkit provides a set of programming tools for compliance with
ITU-T Recommendation X.509, and the IETF-PKIX's RFC 2459. This library
enables parsing and encoding of X.509 certificates and Certificate Revocation
Lists (CRLs), while using the cryptographic power of CryptoKit for signing and
verifying signatures.
The functions and data types in the X.509 Toolkit are very straightforward,
extracted directly from the X.509 definition, and are therefore easy to
understand and use.
The X.509 Toolkit does not supply a CA (Certificate Authority) or any functions
for communicating with one; application programmers should obtain the
certificates and CRLs independently.
Overview
Using the X.509 Toolkit assumes a good working knowledge of public key
cryptography and PKI (Public Key Infrastructure), including the X.509
recommendation. The following section provides a short overview of these
topics, and while useful as background material, it does not replace extensive
study of these subjects.
Public Key Cryptography

A cryptographic algorithm is a method, usually based on some mathematical
function, used for authentication and/or secrecy. Some applications demand only
secrecy or only authentication; others demand both. The security of a
cryptographic scheme resides entirely in the secret key, and not in the secrecy of
the algorithm.
5-16
Classic cryptography uses symmetric schemes in which both sides have a mutual
secret: the secret key. If Alice and Bob want to pass secret messages to one
another, they must meet and decide on a secret key, known to both of them
alone. Then Alice can encrypt a message using the secret key and send it to Bob
who will use the same key to decrypt the message and read it. With a good
algorithm and a key that is practically impossible to guess, Alice and Bob can
pass messages safely without anyone else being able to understand them.
Symmetric schemes have a catch: Alice and Bob must meet in order to agree on
a secret key (if they send the key, someone could intercept it). This might be
problematic if Alice and Bob live far away from each other, or if Alice wants to
maintain secure communications with many people.
Asymmetric schemes, or public key algorithms, were designed to overcome
these limitations. In this case Alice now has two keys: a private key, known only
to her, and a public key, which is widely known. Messages encrypted using
Alice’s public key can only be decrypted by her private key – this means that
Bob can ask Alice for her public key, and then send her messages that only she
can read.
Using her private key, Alice can also affix digital signatures to her messages.
When Bob receives a message signed by Alice with her private key, he can use
Alice’s public key to verify that Alice really wrote the message.
Certificates and Certificate Authorities (CAs)

A problem still exists with this method: when Bob asks Alice for her public key,
Mallory can intercept Bob’s request and pretend to be Alice. Mallory can then
send Bob his (Mallory’s) own public key. Bob, believing he was in
communication with Alice, would send his secret messages encrypted with
Mallory’s public key, and only Mallory would be able to read them!
How can Bob be fully confident that the public key he receives is truly Alice’s?
This is accomplished via a trusted third party – a Certification Authority (CA).
Let’s assume that Bob wants Alice’s public key. He sends a request for Alice’s
public key to the CA. The CA sends Alice’s public key to Bob, digitally signed
by the CA. By using the CA’s public key (assuming he possesses it), Bob can
verify that it was indeed Alice’s public key that he received.
5-17
The CA has a list of users and their public keys. Each user must give the CA his
own public key, and receive the CA’s public key in a secure way. Then the user
can securely obtain any other user’s public key from the CA.
The CA stores a user’s public key in a data structure known as a Certificate,

which also includes other relevant data concerning the public key: the
cryptographic algorithm it is used with, and its period of validity, amongst other
important details.
X.509
The following is an excerpt from the X.509 standard that was formulated by the
ITU-T:
“This Recommendation – International Standard defines a framework for

the provision of authentication services by Directory to its users. It
describes… strong authentication, involving credentials formed using
cryptographic techniques… only strong authentication should be used as
the basis for providing secure services.”
X.509 defines a common methodology for working with certificates. X.509

includes definitions of a standard certificate, as well as a Certificate Revocation
List (CRL). A CRL lists certificates that have been invalidated for some reason
before their date of expiration. The certificate, CRL, and their components are
defined using ASN.11
The X.509 certificate has evolved through several versions. Version 1 included
seven fields. This was extended to nine fields in version 2. Version 3 introduced
a tenth field (extensions), which enables the addition of any number of fields,
and makes the standard more robust. The Internet Engineering Task Force's
Public Key Infrastructure working group (IETF-PKIX) defines in RFC 2459
some more extensions, and the correct procedures for using X.509 certificates
and extensions. Some extension types are standard, and others may be added to
customize certificates for specific applications.
1
Abstract Syntax Notation One, as defined in ITU-T Recommendation X.680.
5-18
The standard certificate fields are:
Version The version of the certificate (currently 1, 2 or 3).
Serial Number A CA specific, unique serial number for the certificate.
Signature Information about the CA’s signature on the certificate.
Issuer The Distinguished Name2 of the certificate issuer (the

CA).
Validity The time period in which the enclosed public key is

valid.
Subject The Distinguished Name of the owner of the enclosed

public key.
Subject Public Key Information about the enclosed public key, including the
Info key itself, its size, and the algorithm it should be used
for.
Issuer Unique The CA’s unique identifier (added in version 2). This
Identifier field is optional, and is not recommended for use.
Subject Unique The user’s unique identifier (added in version 2). This
Identifier field is optional, and is not recommended for use.
Extensions A sequence of extensions (added in version 3).
The Certificate Revocation List (CRL) is a list of revoked certificates that the
CA issues at regular intervals, and more often if necessary. A certificate can be
revoked for many reasons: the user’s private key has been compromised, the
CA’s database has been compromised, the user has moved to another CA, etc.
2
Distinguished Names are defined in ITU-T Recommendation X.501 – The Directory: Models.
5-19
The CRL includes a certificate list with the following standard fields:
Version The version of the certificate list (currently 1 or 2).
Signature Information about the CA’s signature on the certificate

list.
Issuer The Distinguished Name of the CA.
This Update When this list was issued.
Next Update Planned time for next update (added in version 2).
Revoked List of the revoked certificates’ serial numbers, when they

Certificates were revoked, and some optional extensions.
CRL Extensions A list of extensions (added in version 2).
For a list of the various extensions of certificates and CRLs defined in the
standard and supported by X.509 Toolkit, refer to General Data Types on page
4-51.
The data cannot be transported in these structures, and is therefore encoded into
a series of bytes using a subset of the ASN.1 Basic Encoding Rules (BER), as
defined in the recommendation. The X.509 Toolkit implementation encodes the
data using the ASN.1 Distinguished Encoding Rules (DER), which are a more
tightly defined subset of BER, and therefore also comply with the rules defined
in X.509.
5-20
Additional Reading
X.509
ITU-T Recommendation X.509 (1997) | “Information Technology – Open
Systems Interconnection – The Directory: Authentication Framework”
RFC 2459 "Internet X.509 Public Key Infrastructure Certificate and CRL
Profile", D. Solo, Russ Housley, Warwick Ford, T. Polk, 1999.3
X.509 Background
Systems Interconnection – The Directory: Overview of concepts, models and
services.”

Systems Interconnection – The Directory: Models.”

Systems Interconnection – The Directory: Selected attribute types.”
ASN.1
ITU-T Recommendation X.680 (1994) | “Information Technology – Abstract
Syntax Notation One (ASN.1): Specification of basic notation.”
ITU-T Recommendation X.690 (1994) | “Information Technology – ASN.1

encoding rules: Specification of Basic Encoding Rules (BER), Canonical
Encoding Rules (CER) and Distinguished Encoding Rules (DER).”
3
At the time of this writing, the following Internet site http://ietf.org/ids.by.wg/pkix.html contains
this document, in addition to many other relevant ones.
5-21
Working with the X.509 Toolkit
The X.509 Toolkit uses two types of data:

♦ DER encoded ASN.1 data
♦ Structured decoded data
The transition between these types is not trivial, due to the robust nature of the
certificate and CRL definitions. Decoding or encoding data involves numerous
memory allocations that can cause greatly fragmented memory and necessitate
complex memory management.
For this reason, X.509 Toolkit functions do not perform any real memory
allocation: the calling function supplies a memory block for the X.509 Toolkit
function, and the X.509 Toolkit function does all memory allocation inside this
memory block. This method assures that all the data is arranged in a continuous
block of memory, which can be easily disposed of when the function is
complete.
Decoding Certificates and CRLs

A DER encoded certificate is an array of bytes that is difficult to manage. In
order to work with a certificate, you have to decode it into structured data using
C_X509_Decode. The following example shows how to decode a certificate.
Note that this example contains no error handling.

#include "ck_x509.h"
#include <stdio.h>
int main(int argc, char **argv)
{
FILE * f;
X509_certificate * cert;
CK_BYTE encCert[5000];
CK_BYTE decCert[5000];
5-22
CK_ULONG encCertLen;
CK_ULONG decCertLen = sizeof(decCert);
CK_RV rc;
f = fopen(argv[1],"rb");
encCertLen = fread(encCert,1,5000,f);
fclose(f);
rc = C_X509_Decode(CK_X509_ID_CERT, encCert,
encCertLen,decCert,&decCertLen);
cert = (X509_certificate *)decCert;
printf("Certificate version %d\n",cert->tbs.version);

return 0;
}
The program first reads the encoded certificate from a file. The memory block
needed for decoding the certificate into is provided by an array. The buffer is
decoded. At the end the program prints the certificate version number.
C_X509_Decode is called with the following parameters:

♦ CK_X509_ID_CERT – the input buffer is a certificate. When decoding
a CRL the value of this parameter should be CK_X509_ID_CRL.
♦ encCert – the input encoded certificate.
♦ encCertLen – the size in bytes, of the encoded certificate.
♦ decCert – a buffer for putting the decoded certificate into.
♦ decCertLen – the size, in bytes, of the decCert buffer.
The formal declaration of hl_x509_decode is:

int C_X509_Decode(CK_ASN_ID Type,
CK_VOID_PTR pEncoded,
CK_ULONG ulEncodedLen,
CK_VOID_PTR pDecoded,
CK_ULONG_PTR pulDecodedLen);
5-23
By casting decCert to the X509_certificate structure, the program gets the

structured data into cert. This data can then be checked and manipulated as
required.
Decoding One Field

The previous example is useful for cases when all or most of the certificate
fields are required by the application. When you only need to decode one field,
the sample below shows a more efficient way, using the following method.
#include <stdio.h>
{
FILE * f;
CK_RV rc;
CK_ULONG version;
CK_ULONG verLen;
fclose(f);
verLen = sizeof(version);
rc = C_X509_GetField(CK_X509_ID_CERT,
encCert,encCertLen,(CK_VOID_PTR)&version,
&verLen,CK_X509_CERT_FIELD_VERSION);
printf("Certificate version %d\n",version);

return 0;
}
In this example, C_X509_GetField is used for decoding only the version field
of the encoded certificate, by specifying the
CK_X509_CERT_FIELD_VERSION constant as the last parameter. This is
possible for all fields; refer to the Constants section of this chapter for a
5-24
complete list of the field type constants. Since version is already a CK_ULONG
variable, there is no need to cast it after the call to C_X509_GetField; the
version value is put directly in the variable version when the function is run.
The formal declaration of C_X509_GetField is:

int C_X509_GetField( CK_ASN_ID Type,
CK_ULONG_PTR pulDecodedLen,
CK_X509_FIELD Field);
Verifying the Signature and Date on the Certificate/CRL

When obtaining a new certificate/CRL, you should verify the following:
♦ The signature on the certificate/CRL is valid.
♦ The certificate is still within its period of validity.
♦ All critical extensions are known and accounted for.
C_X509_Verify accomplishes this by using cryptographic functions from the

PKCS#11 CryptoKit, therefore a handle to a cryptographic session has to be
obtained before calling C_X509_Verify, and has to be disposed of afterwards,
or at the end of the cryptographic session. For more information on using the
cryptographic functions, refer to the PKCS#11 documentation.
The following example illustrates how to verify a CA (self signed) certificate –

one in which the public key in the subject public key info field of the certificate
is used for verifying the signature.
#include <stdio.h>
5-25
{
FILE * f;
CK_RV rc;
CK_SLOT_ID pSlotList[10];
CK_ULONG ulCount = 10;
CK_SESSION_HANDLE hSession;
fclose(f);
rc = C_Initialize(NULL_PTR);
rc = C_GetSlotList(FALSE,pSlotList,&ulCount);
rc = C_OpenSession(pSlotList[0],CKF_RW_SESSION |
CKF_SERIAL_SESSION,NULL_PTR,NULL_PTR,&hSession);
rc = C_X509_Verify(hSession,CK_INVALID_HANDLE,
CK_X509_ID_CERT,encCert,encCertLen,NULL_PTR,0);
if (rc != CKR_OK)
printf("*** error verifying – %x\n",rc);
else
printf("Verification successful!\n");
rc = C_CloseSession(hSession);
rc = C_Finalize(NULL_PTR);
return 0;
}
After reading the input file and opening a cryptographic session,

C_X509_Verify is called with the following parameters:
♦ hSession – handle to an open session.
5-26
♦ CK_INVALID_HANDLE – No external key is needed for verification.
♦ CK_X509_ID_CERT – the input buffer is a certificate. When decoding
a CRL the value of this parameter should be CK_X509_ID_CRL.
♦ encCert – the input encoded certificate.
♦ encCertLen – the size, in bytes, of the encoded certificate.
♦ NULL_PTR – no external CA certificate is needed for verification.
♦ 0 – the size of the CA certificate, if present.
The return code CKR_OK indicates that the signature is valid.
Usually the pCACert parameter would be the certificate of the CA, which
signed the certificate that is now being verified.
The formal declaration of C_X509_Verify is:

int C_X509_Verify(CK_SESSION_HANDLE hSess,
CK_OBJECT_HANDLE hKey,
CK_ASN_ID Type,
CK_VOID_PTR pSignedObject,
CK_ULONG ulSignedObjectLen,
CK_VOID_PTR pCACert,
CK_ULONG ulCACertLen);
Fully Validating a Certificate

Full validation of a certificate usually requires building a full chain of
certificates to a CA trusted by the verifiying entity (A certification path). For
each certificate in the certification path C_X509_Verify should be called for
validating the signature, validity period and critical extensions. However, to
fully validate the certificate, an application must process the path as described in
section 6 of "RFC 2459 – Internet X.509 Public Key Infrastructure Certificate
and CRL Profile”- Certification Path Validation. These validation actions are
out of the scope of the X.509 Toolkit, and must be processed by the application.
5-27
Encoding and Signing a Certificate/CRL

After creating a certificate/CRL in its structured form, a two-step process is
required to prepare the certificate/CRL for sending:
♦ Encode the data in DER format.
♦ Add your CA signature to the encoded data.
This functionality can be achieved in two ways, either through consecutive calls
to C_X509_Encode for encoding, and then C_X509_Sign for signing, or
through one call to C_X509_EncodeSign for both encoding and signing. For
most applications the single call to C_X509_EncodeSign is preferable,
however, for demonstrating the use of more functions, the following example
uses the two step approach.
C_X509_Sign and C_X509_EncodeSign, similarly to C_X509_Verify, use

PKCS#11 cryptographic functions; therefore they should only be called after
opening a cryptographic session and retrieving a handle to the appropriate
private key object.
The following sample illustrates a function for encoding and signing a certificate
or CRL, and also incorporates some error handling. In this example, it is
assumed that the key media has already been formatted and generated.
CK_RV encodeAndSign( CK_ASN_ID type,
void * structuredData,
CK_ULONG structuredDataLen,
CK_BYTE * encoded,
CK_ULONG * encodedLen)
{
CK_RV rc;
CK_BYTE_PTR pCertBuf;
CK_ULONG certBufLen = 0;
CK_ULONG encTbsLen;
CK_CHAR_PTR pin = "12345678";
CK_ULONG attribPrivateKey = CKO_PRIVATE_KEY;
5-28
CK_ULONG attribRSA = CKK_RSA;
CK_ATTRIBUTE findRSAPrivateKey[] = {
{CKA_CLASS,&attribPrivateKey, sizeof(attribPrivateKey)},
{CKA_KEY_TYPE, &attribRSA, sizeof(attribRSA)},
};
CK_ULONG ulObjectsFound;
CK_OBJECT_HANDLE hPrivateKey;
rc = C_X509_Encode(type,structuredData,
structuredDataLen,NULL,&certBufLen);
if (rc == CKR_BUFFER_TOO_SMALL)
pCertBuf = malloc(certBufLen);
else if (rc != CKR_OK) {
printf("*** error in encode – %x\n",rc);
return rc;
}
encTbsLen = certBufLen;
rc = C_X509_Encode(type,structuredData,
structuredDataLen,pCertBuf,&certBufLen);
if (rc != CKR_OK) {
printf("*** error encoding – %x\n",rc);
return rc;
}
if (rc != CKR_OK) {
printf("*** Error in C_Initialize – %x\n",rc);
return rc;
}
if (rc != CKR_OK) {
printf("*** Error in C_GetSlotList – %x\n",rc);
C_Finalize(NULL_PTR);
return rc;
}
CKF_SERIAL_SESSION,NULL_PTR,NULL_PTR,&hSession);
if (rc != CKR_OK) {
printf("*** Error in C_OpenSession – %x\n",rc);
5-29
return rc;
}
rc = C_Login(hSession,CKU_USER,pin,8);
if (rc != CKR_OK) {
printf("*** Error in C_Login – %x\n",rc);
return rc;
}
rc = C_FindObjectsInit(hSession,findRSAPrivateKey,2);
if (rc != CKR_OK) {
printf("*** Error in C_FindObjectsInit – %x\n",rc);
return rc;
}
rc = C_FindObjects(hSession,&hPrivateKey,1, &ulObjectsFound);
if ((rc != CKR_OK) || (ulObjectsFound != 1)) {
printf("*** Error in C_FindObjects – %x,
ulObjectsFound=%d\n",rc,ulObjectsFound);
return rc;
}
rc = C_FindObjectsFinal(hSession);
if (rc != CKR_OK) {
printf("*** Error in C_FindObjectsFinal – %x\n",rc);
return rc;
}
rc = C_X509_Sign(hSession,hPrivateKey,type,pCertBuf,
encTbsLen,encoded,encodedLen);
if (rc != CKR_OK) {
printf("*** Error signing – %x\n",rc);
return rc;
}
rc = C_Logout(hSession);
if (rc != CKR_OK) {
printf("*** Error in C_Logout - %x\n",rc);
return rc;
}
5-30
return CKR_OK;
}
The first call to C_X509_Encode is done with an empty output buffer;

C_X509_encode returns the size of required memory in certBufLen. Now we
can allocate the necessary memory for the encoding function. C_X509_Encode
is called again, this time for actual encoding.
After encoding the certificate, a cryptographic session is opened, and a handle to
the user's private key object is acquired. The encoded data is then signed using
C_X509_Sign. C_X509_Sign knows which hash algorithm and signature
algorithm to use by checking the signature_alg field of the certificate/CRL.
A call to encode_and_sign may look like this:
rc = encodeAndSign(CK_X509_ID_CRL,crl,decCrlLen,
encCrl,&encCrlLen);
crl is an object of type X509_crl, and encCrl is a buffer for the encoded and
signed CRL.
The formal declaration of C_X509_Encode is:

int C_X509_Encode(CK_ASN_ID Type,
CK_ULONG ulDecodedLen,
CK_ULONG_PTR pulEncodedLen);
5-31
The formal declaration of C_X509_Sign is:

int C_X509_Sign(CK_SESSION_HANDLE hSess,
CK_ASN_ID Type,
CK_VOID_PTR pObject,
CK_ULONG ulObjectLen,
CK_ULONG_PTR pulSignedObjectLen);
Checking for a Revoked Certificate

A certificate is only valid for a specified period of time. This period is provided
in the certificate’s validity field. In the event that a certificate is revoked before
the end of its intended validity period, the certificate’s serial number appears in
a CRL. Use C_X509_FindInCrl to check if a certificate’s serial number
appears in a CRL.
The example belows illustrates one way of using C_X509_FindInCrl to check

if a certificate’s serial number appears in a CRL (checking if a certificate has
been revoked).
#include <stdio.h>
{
FILE * f;
CK_BYTE encCrl[5000];
CK_ULONG encCrlLen;
CK_RV rc;
CK_ULONG result;
5-32
fclose(f);
encCrlLen = fread(encCrl,1,5000,f);
fclose(f);
rc = C_X509_FindInCRL(encCert,encCertLen,encCrl,
encCrlLen,CK_X509_ID_CERT,NULL,NULL,&result);
if (rc == CKR_OK) {
if (result == CKR_X509_DIFFERENT_ISSUERS)
printf("Certificate and crl are from different
issuers\n");
else if ((result >= CKR_X509_FOUND) && (result
< CKR_X509_NOT_FOUND))
printf("Certificate has been revoked!\n");
else if (result == CKR_X509_NOT_FOUND)
printf("certificate has not been revoked\n");
}
else
printf("*** Error in C_X509_FindInCRL – %x\n",rc);
return 0;
}
In this example, C_X509_FindInCrl is given the full certificate and CRL as

input. The function finds the certificate’s serial number and issuer, checks that
the CRL and certificate are from the same issuer, and then looks for the serial
number in the revocation list.
5-33
The formal declaration of C_X509_FindInCrl is:

int C_X509_FindInCRL(CK_VOID_PTR pEncodedObj,
CK_ULONG ulEncodedObjLen,
CK_VOID_PTR pEncodedCRL,
CK_ULONG ulEncodedCRLLen,
CK_ASN_ID Type,
CK_VOID_PTR pRevoked,
CK_ULONG_PTR pulRevokedLen,
CK_ULONG_PTR pulResult);
Each revoked item in the CRL has a serial number, revocation time, and some
optional extensions. If you want C_X509_FindInCrl to return the complete
structure associated with the serial number, send a memory buffer in pRevoked.
This will provide all the relevant data in X509_Revoked structure pointed to by
pRevoked.
A revoked certificate’s extensions field may include a reasons extension. In this

case, the pulResult value returned from C_X509_FindInCrl is not
CKR_X509_FOUND, but rather includes the reason for revocation, such as
CKR_X509_FOUND_KEY_COMPROMISE.
An alternative way to use C_X509_FindInCrl is to send it an X509_tbs

structure, or just the serial number of the certificate. For example, you could use
C_X509_GetField to retrieve the serial number of the certificate, and then call
C_X509_FindInCrl. This call may appear as follows:
rc = C_X509_FindInCRL(serialNum,serialNumLen,encCrl,
encCrlLen,CK_X509_ID_SER_NUM,NULL,NULL,&result);
Using this technique, C_X509_FindInCrl cannot check if the issuer is the same
for both certificate and CRL; the application programmer must do this.
5-34
Copying a Complete Data Structure
A complete X509_certificate or X509_crl structure contains a great deal of data
and numerous pointers. It is not possible to copy these structures simply by
using memcpy; rather it is a laborious process of following pointers and
allocating new ones. C_X509_copy enables you to copy any complete structure,
such as X509_certificate, X509_crl, and X509_Dname.
Let’s assume you want to manipulate the certificate issuer’s distinguished name
without changing the original data. The following example shows how
C_X509_copy can be used to to copy a complete certificate.
#include <stdio.h>
#include <stdlib.h>
{
FILE * f;
X509_certificate * certificate;
CK_BYTE decCert[5000];
CK_ULONG decCertLen = sizeof(decCert);
CK_BYTE dnameBuf[1000];
CK_ULONG dnameBufLen = sizeof(dnameBuf);
X509_Dname * issuerDname;
CK_RV rc;
fclose(f);
rc = C_X509_Decode(CK_X509_ID_CERT, encCert,
encCertLen,decCert,&decCertLen);
certificate = (X509_certificate *)decCert;
rc = C_X509_Copy(CK_X509_ID_DNAME, &(certificate->tbs.issuer),
1000,dnameBuf,&dnameBufLen);
5-35
issuerDname = (X509_Dname *)dnameBuf;
// Manipulations on issuer's distinguished name
return 0;
}
The certificate is decoded using C_X509_Decode. Then C_X509_Copy is

called for copying the certificate’s issuer distinguished name with the following
parameters:
♦ CK_X509_ID_DNAME – tells the function to copy a structure of type
X509_Dname
♦ &(certificate->tbs.issuer) – the source structure.
♦ 1000 – an approximation of the size of the input and has no real
relevance.
♦ DnameBuf – a buffer for receiving the output X509_Dname structure.
The formal declaration of C_X509_copy is:

int C_X509_Copy(CK_ASN_ID Type,
CK_VOID_PTR pSrc,
CK_ULONG ulSrcLen,
CK_VOID_PTR pDst,
CK_ULONG_PTR pulDstLen);
5-36
Building Certificates
Building the structured certificates is not an easy task. The installation disk
contains a sample project called creatcrt, which helps you create a simple
certificate with user-friendly menus. This utility can be used also to create a
self-signed certificate. Note that it does not check the integrity of the data you
provide. You must verify that the certificate is valid by checking it against the
X.509 specification.
Although we will not explain creatcrt in full, reviewing it can provide a good
understanding of how to work with the X.509 data structures.
Object Identifiers
Object identifiers are defined in ASN.1 as a universal way of describing objects
as a sequence of integer components. The object identifiers are built as a tree,
where each node inherits the integer sequence from its parent, and adds a new
integer at the end. Thus, an entity receives its unique object identifier, and is
allowed to assign object identifiers inherited from its integer sequence. This
ensures that no two entities are able to accidentally assign the same object
identifier.
For example, the general object identifier for an X.509 certificate extension is:
id-ce OBJECT IDENTIFIER::= {joint-iso-ccitt(2) ds(5)
29}
The object identifier for the Key Usage extension is:

id-ce-KeyUsage OBJECT IDENTIFIER::= {joint-iso-
ccitt(2) ds(5) ce(29) 15 }
Object identifiers are used in X.509 for various applications: identifying

encryption and hash algorithms, extension types, distinguished names and more.
In the X.509 Toolkit, the object identifiers are stored in a data structure of type
X509_obj_id. The object identifiers that are known to the X.509 Toolkit are
given an internal constant integer value for easier manipulation, and are stored
as integers in X509_obj_id's int_id field; for the key usage extension, this
constant is ASN1_EXT_KEY_USAGE.
5-37
When one of X.509 Toolkit’s functions meets an unknown object identifier, it

saves the entire integer sequence as a character string of the integer numbers
separated by dots in X509_obj_id_EX’s char_id field. For example, the Key
Usage extension would look like this: “2.5.29.15”.
A complete list of the object identifiers recognized by the X.509 Toolkit can be
found in the Constants section of this chapter (below), they are defined in the
file obj_ids.h.
Constants
This section describes some of the ASN.1 constants defined in the X.509
Toolkit. For a full list refer to the H-file cx509def.h. These constants are
categorized as follows:
♦ Certificate/CRL Fields
♦ Object Types
♦ Types of General Names
♦ Object Identifiers:
Algorithm Identifiers
PKCS (#7, #9 and #12)
Attribute Types (for Distinguished Names)
Extensions
Qualifier Types
Key Purposes
Hold Instructions
Attribute Certificates
5-38
Certificate/CRL Fields
The following are field identifiers for C_X509_GetField. Note that extension
types have two names: an extension number, and a meaningful name. Since both
refer to the same extension, they are interchangeable.
CK_X509_FIELD_ENTIRE The entire certificate/CRL.
CK_X509_CRL_FIELD_ENTIRE The entire CRL.
CK_X509_CRL_FIELD_SIG The signature field of the CRL.
CK_X509_CRL_FIELD_VERSION The version field of crl_tbs.
CK_X509_CRL_FIELD_SIG_ALG The signature_alg field of crl_tbs.
CK_X509_CRL_FIELD_ISSUER The issuer field of crl_tbs.
CK_X509_CRL_FIELD_THIS_UPDATE The this_update field of crl_tbs.
CK_X509_CRL_FIELD_NEXT_UPDATE The next_update field of crl_tbs.
CK_X509_CRL_FIELD_EXTENSIONS The extensions field of crl_tbs.
CK_X509_CRL_FIELD_EXT_2920 The CRL_number
CK_X509_CRL_FIELD_EXT_CRL_NUMBER (X509_ext_2920) extension.
CK_X509_CRL_FIELD_EXT_2921 The CRL_reason
CK_X509_CRL_FIELD_EXT_REASON_CODE (X509_ext_2921) extension.
CK_X509_CRL_FIELD_EXT_2923 The HoldInstructionCode
CK_X509_CRL_FIELD_EXT_INSTRUCTION_CODE (X509_ext_2923) extension.
CK_X509_CRL_FIELD_EXT_2924 The InvalidityDate
CK_X509_CRL_FIELD_EXT_INVALIDITY_DATE (X509_ext_2924) extension.
CK_X509_CRL_FIELD_EXT_2927 The DeltaCRLIndicator
CK_X509_CRL_FIELD_EXT_DELTA_CRL_INDICATOR (X509_ext_2927) extension.
CK_X509_CRL_FIELD_EXT_2928 The IssuingDistributionPoint
CK_X509_CRL_FIELD_EXT_ISSUING_DIST_POINT (X509_ext_2928) extension.
5-39
CK_X509_CRL_FIELD_EXT_2929 The CertificateIssuer
CK_X509_CRL_FIELD_EXT_CERT_ISSUER (X509_ext_2929) extension.
CK_X509_CERT_FIELD_ENTIRE The entire certificate.
CK_X509_CERT_FIELD_SIG The signature field of certificate.
CK_X509_CERT_FIELD_VERSION The version field of the certificate
to be signed.
CK_X509_CERT_FIELD_SER_NUM The serial_number field of the
certificate to be signed.
CK_X509_CERT_FIELD_SER_NUM_DER The DER encoded serial_number
field of the certificate. Used to
create a PKCS#11 certificate
object.
CK_X509_CERT_FIELD_SIG_ALG The signature_alg field of the
CK_X509_CERT_FIELD_ISSUER The issuer field of the certificate
to be signed.
CK_X509_CERT_FIELD_ISSUER_DER The DER encoded issuer field of
the certificate. Used to create a
PKCS#11 certificate object.
CK_X509_CERT_FIELD_VALIDITY The validity field of the certificate
to be signed.
CK_X509_CERT_FIELD_SUBJECT The subject field of the certificate
to be signed.
CK_X509_CERT_FIELD_SUBJECT_DER The DER encoded subject field of
the certificate. Used to create a
PKCS#11 certificate object.
CK_X509_CERT_FIELD_PUB_KEY_INFO The subject_key_info field of the
5-40
CK_X509_CERT_FIELD_ISSUER_ID The issuer_id field of the
CK_X509_CERT_FIELD_SUBJECT_ID The subject_id field of the
CK_X509_CERT_FIELD_EXTENSIONS The extensions field of the
CK_X509_CERT_FIELD_EXT_2914 The X509_ext_2914 extensions
CK_X509_CERT_FIELD_EXT_SUBJECT_KEY_ID field (if it exists).
CK_X509_CERT_FIELD_EXT_2915 The X509_ext_2915 extension
CK_X509_CERT_FIELD_EXT_KEY_USAGE field (if it exists).
CK_X509_CERT_FIELD_EXT_PRIV_USAGE_PERIOD field (if it exists).
CK_X509_CERT_FIELD_EXT_2917 The subject_alt_name extension
CK_X509_CERT_FIELD_EXT_SUBJECT_ALT_NAME field (X509_ext_2917_8) (if it
exists).
CK_X509_CERT_FIELD_EXT_2918 The issuer_alt_name extension
CK_X509_CERT_FIELD_EXT_ISSUER_ALT_NAME field (X509_ext_2917_8) (if it
exists).
CK_X509_CERT_FIELD_EXT_BASIC_CONSTRAINTS field (if it exists).
CK_X509_CERT_FIELD_EXT_NAME_CONSTRAINTS field (if it exists).
CK_X509_CERT_FIELD_EXT_CRL_DIST_POINT field (if it exists).
CK_X509_CERT_FIELD_EXT_CERTIFICATE_POLICIES field (if it exists).
CK_X509_CERT_FIELD_EXT_POLICY_MAPPING field (if it exists).
5-41
CK_X509_CERT_FIELD_EXT_AUTH_KEY_ID field (if it exists).
CK_X509_CERT_FIELD_EXT_POLICY_CONSTRAINTS field (if it exists).
CK_X509_CERT_FIELD_EXT_EXTENDED_KEY_USAGE field (if it exists).
5-42
Object Types
The following are internal object types used as the Type variable in the X.509
functions.
Object Types
CK_X509_ID_CERT An X509_certificate structure
CK_X509_ID_CRL An X509_crl structure
CK_X509_ID_SIG An X509_signature structure
CK_X509_ID_TBS An X509_tbs structure
CK_X509_ID_CRL_TBS An X509_crl_tbs structure
CK_X509_ID_SER_NUM A serial number (char *)4
CK_X509_ID_ALG_STRUCT An X509_alg_struct structure
CK_X509_ID_DNAME An X509_Dname structure
CK_X509_ID_KEY_INFO An X509_key_info structure
CK_X509_ID_UNIQUE_ID An X509_unique_id structure
CK_X509_ID_EXTENSIONS An X509_extensions structure
CK_X509_ID_EXTENSION An X509_ext structure
CK_X509_ID_REVOKED_LIST An X509_rev_list structure
CK_X509_ID_REVOKED An X509_revoked structure
CK_X509_ID_GENERAL_NAMES An X509_general_names structure
CK_X509_ID_GENERAL_NAME An X509_general_name structure
CK_X509_ID_GENERAL_SUBTREE An X509_general_subtree structure
4
A printable hex representation of the serial number.
5-43
Types of General Names

The following are types of general names. The data field of
X509_general_name is cast according to these types.
Types of General Names

X509_GN_OTHER_NAME General name type is OTHER NAME; data is the original
unparsed encoded data.
X509_GN_RFC822_NAME General name is an e-mail address; data is cast to char *.
X509_GN_DNS_NAME General name is a Domain Name Server (DNS); data is cast to
char *.
X509_GN_X400_ADDR General name is an X400 Address; data is the original unparsed
encoded data.
X509_GN_DNAME General name is a distinguished name; data is cast to
X509_Dname *.
X509_GN_EDI_NAME General name is an EDI Party name; data is the original unparsed
encoded data.
X509_GN_URL General name is a Universal Resource Identifier; data is cast to
char *.
X509_GN_IP_ADDR General name is an IP address, which is an array of bytes; data is
cast to unsigned char *.
X509_GN_REG_ID General name is a registered Identifier; data is cast to
X509_obj_id *.
5-44
Object Identifiers
The following are tables of object identifiers recognized by the X.509 Toolkit,
as defined in obj_ids.h:
Object Identifiers: Algorithm Identifiers

ASN1_OI_RSA_ENC RSA encryption
ASN1_OI_RSA Another identifier for RSA encryption
ASN1_OI_RSAES_OAEP PKCS#1 RSA OAEP encryption
ASN1_OI_RSASSA_PSS PKCS#1 RSA PSS signature
ASN1_OI_DSA DSA signature
ASN1_OI_MD2_RSA Hash algorithms with RSA signature
ASN1_OI_MD4_RSA
ASN1_OI_MD5_RSA
ASN1_OI_SHA1_RSA
ASN1_OI_RIPEMD128_RSA
ASN1_OI_RIPEMD160_RSA
ASN1_OI_SHA1_DSA SHA-1 hash with DSA signature

ASN1_OI_SHA1_RSA_MTT SHA-1 hash with RSA encryption (MTT-1 Object
identifier)
ASN1_OI_MD2_HASH Hash algorithms
ASN1_OI_MD4_HASH
ASN1_OI_MD5_HASH
ASN1_OI_SHA1_HASH
ASN1_OI_RIPEMD128_HASH
ASN1_OI_RIPEMD160_HASH
ASN1_OI_DH Diffie-Hellman key exchange
5-45
Object Identifiers: Algorithm Identifiers

ASN1_OI_RC2_CBC Symmetric encryption algorithms in different modes
ASN1_OI_RC4
ASN1_OI_RC5_CBC
ASN1_OI_DES_CBC
ASN1_OI_DES_OFB
ASN1_OI_DES_ECB
ASN1_OI_DES_CFB
ASN1_OI_DES3_CBC
ASN1_OI_AES
ASN1_OI_AES128_ECB
ASN1_OI_AES128_CBC
ASN1_OI_AES128_OFB
ASN1_OI_AES128_CFB
ASN1_OI_AES192_ECB
ASN1_OI_AES192_CBC
ASN1_OI_AES192_OFB
ASN1_OI_AES192_CFB
ASN1_OI_AES256_ECB
ASN1_OI_AES256_CBC
ASN1_OI_AES256_OFB
ASN1_OI_AES256_CFB
Object Identifiers: PKCS

ASN1_OI_PKCS7_1 PKCS#7 data
ASN1_OI_PKCS7_2 PKCS#7 Signed data
ASN1_OI_PKCS7_3 PKCS#7 Enveloped data
ASN1_OI_PKCS7_4 PKCS#7 Signed and Enveloped data
ASN1_OI_PKCS7_5 PKCS#7 Digested Data
ASN1_OI_PKCS7_6 PKCS#7 Encrypted Data
ASN1_OI_PKCS9_1 PKCS#9 E-mail Address
ASN1_OI_PKCS9_2 PKCS#9 Unstructured Name
5-46
Object Identifiers: PKCS
ASN1_OI_PKCS9_3 PKCS#9 Content Type
ASN1_OI_PKCS9_4 PKCS#9 Message Digest
ASN1_OI_PKCS9_5 PKCS#9 Signing Time
ASN1_OI_PKCS9_6 PKCS#9 Counter Signature
ASN1_OI_PKCS9_7 PKCS#9 Challenge Password
ASN1_OI_PKCS9_8 PKCS#9 Unstructured Address
ASN1_OI_PKCS9_9 PKCS#9 Extended Certificate attribute
Object Identifiers: Attribute Types (for Distinguished Names)

ASN1_OI_COMMON_NAME Common name
ASN1_OI_COUNTRY Country
ASN1_OI_ORG Organization
ASN1_OI_ORG_UNIT Organizational Unit
ASN1_OI_SURNAME Surname
ASN1_OI_SERIAL_NUM Serial Number
ASN1_OI_LOCALITY Locality
ASN1_OI_STATE State
ASN1_OI_STREET Street
ASN1_OI_POSTAL_ADDR Postal Address
ASN1_OI_POSTAL_CODE Postal Code
ASN1_OI_POB Post Office Box
5-47
Object Identifiers: Attribute Types (for Distinguished Names)

ASN1_OI_PHONE_NUM Phone Number
ASN1_OI_TELEX_NUM Telex Number
ASN1_OI_FAX_NUM FAX Number
ASN1_OI_USER_PASSWD User Password
ASN1_OI_USER_CERT User Certificate
ASN1_OI_CA_CERT CA Certificate
ASN1_OI_IP_ADDR IP Address
ASN1_OI_TELEX_TERM_ID Telex Terminal Number
ASN1_OI_TITLE Title
Object Identifiers: Extensions

ASN1_EXT_SUBJECT_KEY_ID Subject Key Identifier extension
ASN1_EXT_KEY_USAGE Key Usage extension
ASN1_EXT_PRIV_USAGE_PERIOD Private Key Usage Period extension
ASN1_EXT_SUBJECT_ALT_NAME Subject Alternative Name extension
ASN1_EXT_ISSUER_ALT_NAME Issuer Alternative Name extension
ASN1_EXT_BASIC_CONSTRAINTS Basic Constraints extension
ASN1_EXT_CRL_NUMBER CRL Number extension
ASN1_EXT_REASON_CODE CRL Reason Code extension
ASN1_EXT_INSTRUCTION_CODE Instruction Code extension
ASN1_EXT_INVALIDITY_DATE Invalidity Date extension
5-48
Object Identifiers: Extensions
ASN1_EXT_DELTA_CRL_INDICATOR Delta CRL Indicator extension
ASN1_EXT_ISSUING_DIST_POINT Issuing Distribution Point extension
ASN1_EXT_CERT_ISSUER Certificate Issuer extension
ASN1_EXT_NAME_CONSTRAINTS Name Constraints extension
ASN1_EXT_CRL_DIST_POINT CRL Distribution Point extension
ASN1_EXT_CERTIFICATE_POLICIES Certificate Policies extension
ASN1_EXT_POLICY_MAPPING Policy Mapping extension
ASN1_EXT_AUTH_KEY_ID Authority Key Identifier extension
ASN1_EXT_POLICY_CONSTRAINTS Policy Constraints extension
ASN1_EXT_EXTENDED_KEY_USAGE Extended Key Usage extension
Object Identifiers: Qualifier Types

ASN1_OI_QT_CPS Certification Practice Statement
ASN1_OI_QT_UNOTICE User Notice
Object Identifiers: Key Purposes

ASN1_OI_KP_SERVER_AUTH Web Server Authentication
ASN1_OI_KP_CLIENT_AUTH Web Client Authentication
ASN1_OI_KP_CODE_SIGNING Signing of Downloadable
Executable Code
ASN1_OI_KP_EMAIL_PROT E-mail Protection
5-49
Object Identifiers: Key Purposes

ASN1_OI_KP_IP_SEC_END IP Security End System
ASN1_OI_KP_IP_SEC_TUN IP Security Tunnel Termination
ASN1_OI_KP_IP_SEC_USER IP Security User
ASN1_OI_KP_IP_KP_TIME_STAMP Time Stamping
ASN1_OI_KP_DOC_SIGN Document Signing
Object Identifiers: Hold Instructions

ASN1_OI_HI_NONE None
ASN1_OI_HI_CALL_ISSUER Call Issuer
ASN1_OI_HI_REJECT Reject
5-50
General Data Types
The following are the application-specific data definitions for the X.509 Toolkit,
as defined in cx509def.h. Note that the X.509 Toolkit also uses some data
types defined in PKCS#11.
These data types are used to represent the ASN.1 structures of X.509 certificates
and CRLs. The following figure shows the hierarchical relationship between the
different structures that are defined in the X.509 Toolkit. The right tree structure
shows the X509_certificate structure while the left tree shows X509_crl. The
different data structures are explained below.
5-51
5-52
Basic Data Types
The following are basic data types, as defined in the X.509 Toolkit:
IDs of the various data types:

#define CK_ASN_ID int
Fields to be decoded:
#define CK_X509_FIELD int
#define CK_X509_CERT_FIELD int
#define CK_X509_CRL_FIELD int
CK_DATA
CK_DATA is a general data structure for holding any kind of data and its size in
bytes.
typedef struct {
CK_VOID_PTR ptr;
CK_ULONG size;
} CK_DATA;
CK_TIME_T
CK_TIME_T is the time (in seconds) that has elapsed since midnight, 1/1/1970.
For dates until the year 2038, this value is identical to time_t (long integer).
CK_TIME_T (unsigned long) can represent all subsequent dates until the year
2106.
#define CK_TIME_T unsigned long
X509_certificate
X509_certificate is the main certificate data structure. It consists of two parts:
the information to be signed (tbs), and the signature. The C_X509_Decode
function returns data in this format, when applied on a certificate.
5-53
typedef struct {
X509_tbs tbs; // to be signed information
X509_signature signature;
// signature of the certificate
} X509_certificate;
X509_tbs
The X509_tbs represents the “to be signed” part of an X.509 certificate. The
serial_number field is the printable hex representation of the integer certificate
serial number.
typedef struct {
int version;
// certificate version
// number 1,2 or 3
char CK_PTR serial_number;
// certificate serial number
X509_alg_struct signature_alg;
// signature algorithm
X509_Dname issuer;
// issuer distinguished name
X509_validity validity;
// validity of this certificate
X509_Dname subject;
// subject distinguished name
X509_key_info subject_key_info;
// subject key info
X509_unique_id issuer_id; // issuer unique id
X509_unique_id subject_id; // subject unique id
X509_extensions extensions;
// certificate extensions
} X509_tbs;
5-54
X509_crl
X509_crl represents the main CRL data structure. It consists of two parts: the
information to be signed (tbs), and the signature of the CRL. The
C_X509_decode function returns data in this format, when applied on a CRL.
typedef struct {
X509_crl_tbs tbs; // to be signed information
// signature of the CRL
} X509_crl;
X509_crl_tbs
The X509_crl_tbs represents the “to be signed” part of a CRL.
typedef struct {
int version;
// CRL version number 1 or 2
X509_alg_struct signature_alg;
// signature algorithm
X509_Dname issuer;
// issuer distinguished name
CK_TIME_T this_update; // CRL update time
CK_TIME_T next_update;
// CRL next update time
X509_rev_list rev_list;
// list of revoked certificates
// global CRL extensions
} X509_crl_tbs;
X509_signature
The X509_signature structure represents the signature part of an X.509
certificate or CRL. It contains data about the signature and hash algorithms, as
well as the signature itself.
5-55
typedef struct {
X509_alg_struct sign_alg;
// algorithm of the signature
int sig_len; // signature length
CK_BYTE_PTR signature; // binary signature
} X509_signature;
X509_alg_struct
The X509_alg_struct contains data about a cryptographic algorithm: the
algorithm object identifier, and algorithm parameters such as key_size and
initialization vector (iv). For example, for DSA, params is cast to
X509_DSA_params.
typedef struct {
X509_obj_id alg_id; // algorithm id
CK_DATA params; // additional parameters
} X509_alg_struct;
X509_obj_id
TheX509_obj_id structure contains information about an object identifier. When
the X.509 Toolkit recognizes the object identifier, its stores its internal code in
int_id. When the object identifier is not recognized, the whole object identifier is
stored in char_id as a sequence of numbers separated by dots (for example,
2.5.29.15 for the key usage extension).
typedef struct {
int int_id;
char CK_PR char_id;
} X509_obj_id;
5-56
X509_alg_params_key_iv
The params field of X509_alg_struct is cast to the X509_alg_params_key_iv
data type if the algorithm parameters include both key size and initialization
vector. Note that this is irrelevant for public key algorithms.
typedef struct {
int key_size;
CK_BYTE_PTR iv;
} X509_alg_params_key_iv;
X509_alg_params_key
The params field of X509_alg_struct is cast to the X509_alg_params_key data
type if the algorithm parameters include only key size.
typedef struct {
int key_size;
} X509_alg_params_key;
X509_DSA_params
The params field of X509_alg_struct is cast to the X509_DSA_params data type
for the DSA signature algorithm.
typedef struct{
int key_size; // length of p in bytes
BYTE p[128];
// prime number of length key_size
BYTE q[20];
// 160-bit prime factor of p-1
BYTE g[128];
// h^((p-1)/q) mod p for
// smallest h s.t. g>1
} X509_DSA_params;
5-57
X509_alg_params_dh
The params field of X509_alg_struct is cast to the X509_DH_params data type
for the Diffie-Hellman key exchange algorithm.
typedef struct {
int plen; // length of p in bytes
CK_BYTE_PTR p; // prime number
int glen; // length of g in bytes
CK_BYTE_PTR g; // generator
int qlen; // length of q in bytes
CK_BYTE_PTR q; // prime factor of p-1
int jlen; // length of j in bytes.
// j=0 means no value given
CK_BYTE_PTR j; // subgroup factor, p = qj+1
X509_validation_params CK_PTR vp;
// validation params
} X509_alg_params_dh;
X509_validation_params
The X509_validation_params contains validation parameters for the Diffie-
Hellman key exchange algorithm.
typedef struct {
int seed_len; // seed length in bytes
CK_BYTE_PTR seed; // seed
int pgen_len;
// length of pgenCounter in bytes
CK_BYTE_PTR pgenCounter;
} X509_validation_params;
5-58
X509_Dname
The X509_Dname contains the main structure for Distinguished Names, as
defined in X.500. The Distinguished name is constructed of Relative
Distinguished Names (RDNs).
RDNs is an array of num_of_RDNs pointers. For example, to access the third

RDN of a distinguished name use dname.RDNs[2].
typedef struct {
int num_of_RDNs;
X509_RDN CK_PTR RDNs;
} X509_Dname; // Distinguished name
X509_RDN
The X509_RDN structure represents a Relative Distinguished Name, consisting
of ATAVs (Attribute Types and Values; in X.501, it is called ATA – Attribute
Type Assertion).
ATAVs is an array of num_of_ATAVs pointers. For example, to access the

second ATAV of the X509_signature a distinguished name, use
dname.RDNs[0].ATAVs[1].
typedef struct {
int num_of_ATAVs;
X509_ATAV CK_PTR ATAVs;
} X509_RDN; // Relative Distinguished Name
X509_ATAV
The X509_ATAV structure is used to store an Attribute Type and Value.
Available types are listed in the Constants section above.
5-59
ASN.1 has three different types of printable strings. value_type stores the
original ASN.1 coding of a printable string. It used to ensure that decoding
followed by encoding would result in the same ASN.1 sequence.
typedef struct {
X509_obj_id type; // object id of type
BYTE value_type; // asn1 type of value
int value_len; // length of value
CK_BYTE_PTR value; // value itself
} X509_ATAV; // Attribute Type and Value
X509_validity
The X509_validity contains the validity period of the certificate: neither before
nor after specific dates. The dates are saved as CK_TIME_T type variables and
are therefore easy to compare. You can use the ANSI localtime or gmtime
functions to convert this to a readable time/date format.
typedef struct {
CK_TIME_T not_before;
// certificate not valid before
CK_TIME_T not_after;
// certificate not valid after
} X509_validity;
X509_key_info
The X509_key_info structure contains information about the public key of a
user. It consists of two fields: algorithm_id and public_key. The algorithm_id
has the public key algorithm’s details. The public_key is a CK_DATA structure
cast to X509_RSA_key_info for the RSA algorithm, or X509_def_key_info for
all other algorithms.
typedef struct {
X509_alg_struct algorithm_id;
// algorithm id of the key
5-60
CK_DATA public_key; // public key data
} X509_key_info;
X509_def_key_info
X509_def_key_info structure contains public key data for algorithms, whose
information consists of the key length and the key itself (such as DSA).
typedef struct {
int key_length; // key length
CK_BYTE_PTR public_key; // public key
} X509_def_key_info;
X509_RSA_key_info
X509_RSA_key_info structure contains public key data, when the algorithm is
RSA, and both the key and the exponent are required.
typedef struct {
int key_length; // key length
CK_BYTE_PTR public_key; // public key
int exp_length; // exponent length
CK_BYTE_PTR exp; // exponent
} X509_RSA_key_info;
X509_unique_id
X509_unique_id structure contains in the data field a unique id (unparsed) and
its length in the length field.
typedef struct {
int length; // length of data
CK_BYTE_PTR data; // unique id as was in the cert
} X509_unique_id;
5-61
X509_revoked
X509_revoked is a structure that contains one revoked item in the CRL. The
serial_number field is the printable hex representation of the integer serial
number.
typedef struct {
char CK_PTR serial_number;
// revoked serial number
CK_TIME_T revoked_time; // revoked time
// specific revoke extensions
} X509_revoked;
X509_rev_list
X509_rev_list contains the list of revoked certificates inside a CRL. The
revoked field is an array of num_of_rev revoked items. For example, the serial
number of the fifth revoked item on the list rev_list would be:
rev_list.revoked[4].serial_number.
typedef struct {
int num_of_rev;
X509_revoked CK_PTR revoked;
} X509_rev_list;
X509_extensions
X509_extensions structure contains a group of extensions. The extensions field
is an array of num_of_ext extensions. For example, the extension type of the
fourth extension on the extension list cert_exts would be:
cert_exts.extensions[3].ext_id.
typedef struct {
int num_of_ext;
X509_ext CK_PTR extensions;
} X509_extensions;
5-62
X509_ext
The X509_ext is a general structure for one extension. It contains data about the
type of extension, and how critical it is. The data pointer is cast to a structure
according to the type of extension. For example, if ext_id = 2915, you could use
the following line:
X509_ext_2915 KeyUsage=
(X509_ext_2915*)cert_exts.extensions[3].data;
Note that extension structures can be named interchangeably with a full name, or
a shorter extension number (see Certificate/CRL fields in the section on
Constants).
When the extension is unknown (understood = = FALSE), data will be cast to

X509_ext_0000.
typedef struct _Ext {
X509_obj_id ext_id; // obj id of extension type
CK_BBOOL critical;// is the extension critical
CK_BBOOL understood;
// is the extension understood
int ext_length; // extension length
CK_VOID_PTR data; // the extension itself
} X509_ext;
X509_ext_0000, X509_ext_unknown
This structure is used when the X.509 Toolkit is unable to parse an extension.
The extension is then copied unparsed into ext_data, and the data’s length is put
in ext_length.
typedef struct {
int ext_length;
CK_BYTE_PTR ext_data;
} X509_ext_0000, X509_ext_unknown;
5-63
X509_ext_2914, X509_ext_SubjectKeyIdentifier
X509_ext_2914 structure contains the subject key identifier extension. It holds a
printable string, as well as the string’s length.
typedef struct {
int len;
char CK_PTR data;
} X509_ext_2914, X509_ext_SubjectKeyIdentifier;
X509_ext_2915, X509_ext_KeyUsage
X509_ext_2915 structure contains the permitted key usage. A TRUE value
means that the public key may be used for that purpose.
typedef struct {
CK_BBOOL digitalSignature;
CK_BBOOL nonRepudiation;
CK_BBOOL keyEncipherment;
CK_BBOOL dataEncipherment;
CK_BBOOL keyAgreement;
CK_BBOOL keyCertSign;
CK_BBOOL cRLSign;
CK_BBOOL encipherOnly;
CK_BBOOL decipherOnly;
} X509_ext_2915, X509_ext_KeyUsage;
X509_ext_2916, X509_ext_PrivateKeyUsagePeriod
X509_ext_2916 structure contains the private key usage period extension, which
states the time period in which the private key is valid.
typedef struct {
CK_TIME_T not_before;
// private key not valid before
5-64
CK_TIME_T not_after;
// private key not valid after
} X509_ext_2916, X509_ext_PrivateKeyUsagePeriod;
X509_ ext_2917_8, X509_ext_AltName

X509_ext_2917 structure is used to store subject and issuer alternative names.
This estension is a linked list of general names.
typedef struct _Ext_2917_8 {
X509_general_name CK_PTR general_name;
struct _Ext_2917_8 CK_PTR next_name;
} X509_ext_2917_8, X509_ext_AltName;
X509_general_name
The X509_general_name structure contains a general name. The possible types
of general names are listed in the Constants section above. The general name is
parsed into the data field and should be cast according to its type (string,
distinguished name, etc.). When the general name is unparsed (parsed = =
FALSE), the full-unparsed general name is stored in the data field.
typedef struct {
int type;
CK_BBOOL parsed;
int len;
CK_VOID_PTR data;
} X509_general_name;
X509_ext_2919, X509_ext_BasicConstraints
The X509_ext_2919 structure contains the basic constraints extension. If ca field
is TRUE, the subject is certified to act as a CA. The pathLenConstraint field
indicates the number of CA-certificates that may follow this one (if ca is
TRUE). The value –1 means that no value was specified for this field.
typedef struct {
5-65
CK_BBOOL ca;
int pathLenConstraint;
} X509_ext_2919, X509_ext_BasicConstraints;
X509_ext_2920, X509_ext_CRLNumber
The X509_ext_2920 structure contains the CRL number extension. It enables a
CRL user to detect when a particular CRL supersedes another CRL.
typedef struct {
int CRLnumber;
} X509_ext_2920, X509_ext_CRLNumber;
X509_ext_2921, X509_ext_CRLreason
X509_ext_2921 structure is usually used as an extension to a revoked item in a
CRL. It specifies the reason for the revocation. The data structure is also used as
part of the X509_distribution_point structure for specifying the types of
revocation reasons that may be distributed through the CRL distribution point.
typedef struct {
CK_BBOOL unspecified;
CK_BBOOL keyCompromise;
CK_BBOOL cACompromise;
CK_BBOOL affiliationChanged;
CK_BBOOL superseded;
CK_BBOOL cessationOfOperation;
CK_BBOOL certificateHold;
CK_BBOOL removeFromCRL;
} X509_ext_2921, X509_ext_CRLreason;
X509_ext_2923, X509_ext_HoldInstructionCode
The X509_ext_2923 structure contains the hold Instruction Code CRL
extension. It is used to prove a registered instruction identifier, which indicates
5-66
the action to be taken after encountering a certificate that has been placed on
hold.
typedef struct {
X509_obj_id holdInstructionCode;
} X509_ext_2923, X509_ext_HoldInstructionCode;
X509_ext_2924, X509_ext_InvalidityDate
The X509_ext_2924 structure contains the CRL invalidity date extension. It
provides the date on which it is known or suspected that the private key was
compromised or that the certificate otherwise became invalid.
typedef struct {
CK_TIME_T invalidityDate;
} X509_ext_2924, X509_ext_InvalidityDate;
X509_ext_2927, X509_ext_DeltaCRLIndicator
The X509_ext_2927 structure contains the CRL delta Indicator extension. It
identifies the CRL as a delta CRL. The baseCRLNumber is the number of the
CRL that this Delta CRL is based on.
typedef struct {
int baseCRLNumber;
} X509_ext_2927, X509_ext_DeltaCRLIndicator;
X509_ext_2928, X509_ext_IssuingDistributionPoint
The X509_ext_2928 structure contains the CRL Issuing Distribution Point
extension. It identifies the CRL distribution point for a particular CRL, and
indicates certain restrictions on the contents of the CRL.
typedef struct {
X509_DPN CK_PTR DP;
CK_BBOOL onlyContainsUserCerts;
CK_BBOOL onlyContainsCACerts;
X509_ext_CRLreason CK_PTR onlySomeReasons;
5-67
CK_BBOOL indirectCRL;
} X509_ext_2928, X509_ext_IssuingDistributionPoint;
X509_ext_2929, X509_ext_CertificateIssuer
The X509_ext_2929 structure contains CRL Certificate Issuer extension. It
identifies the certificate issuer associated with an entry in an indirect CRL.
typedef struct {
X509_general_names certificateIssuer;
} X509_ext_2929, X509_ext_CertificateIssuer;
X509_ext_2930, X509_ext_NameConstraints
The X509_ext_2930 structure contains the name constraints extension. It is built
of two general subtrees: permitted and excluded.
typedef struct {
X509_general_subtree CK_PTR permitted;
X509_general_subtree CK_PTR excluded;
} X509_ext_2930, X509_ext_NameConstraints;
X509_general_subtree
The X509_general_subtree structure represents a single general subtree within a
connected list of general subtrees. The base field is the general name of the base
of the subtree, and min and max are the upper and lower bounds in the tree. The
next_subtree field is a pointer to the next subtree.
typedef struct _General_subtree {
X509_general_name CK_PTR base;
int min;
int max;
struct _General_subtree CK_PTR next_subtree;
} X509_general_subtree;
5-68
X509_ext_2931, X509_ext_CRLDistributionPoint
X509_ext_2931 structure contains a list of CRL Distribution points (points
where the CRLs can be obtained). The DPs field is an array of num_of_DPs
pointers to individual distribution points.
typedef struct {
int num_of_DPs;
X509_distribution_point CK_PTR DPs;
} X509_ext_2931, X509_ext_CRLDistributionPoint;
X509_distribution_point
The X509_distribution_point structure contains an individual CRL distribution
point. The distribution_point field is the distribution point’s name, the reasons
field are the possible revocation reasons this distribution point is allowed to
give, and the CRLissuer field is the issuer whose CRL’s are available at this
distribution point. Any of these fields may be NULL.
typedef struct {
X509_DPN CK_PTR distribution_point;
X509_ext_2921 CK_PTR reasons;
X509_general_names CK_PTR CRLissuer;
} X509_distribution_point;
X509_DPN
The X509_DPN structure contains the name of a distribution point. It may be
either a full name, or the distribution point’s name relative to the CRL issuer
(but not both).
typedef struct {
X509_general_names CK_PTR full_name;
X509_RDN CK_PTR name_relative_to_CRL_issuer;
} X509_DPN; // Distribution Point Name
5-69
X509_general_names
X509_general_names structure contains a linked list of X509_general_name
structures.
typedef struct _General_names {
X509_general_name CK_PTR general_name;
struct _General_names CK_PTR next_name;
} X509_general_names;
X509_ext_2932, X509_ext_CertificatePolicies
X509_ext_2932 structure contains the certificate policies extension, via a linked
list of single policies. The cpid field is the policy’s object identifier. The
qualifiers are saved unparsed in qualifiers field, and the next pointer points to
the next policy.
typedef struct _Ext_2932 {
X509_obj_id cpid;
int qualifiers_len;
CK_BYTE_PTR qualifiers;
struct _Ext_2932 CK_PTR next;
} X509_ext_2932, X509_ext_CertificatePolicies;
X509_ext_2933, X509_ext_PolicyMappings
X509_ext_2933 structure is used for mapping policies from the issuer domain to
the subject domain. Issuer_domain_policy and subject_domain_policy are both
arrays of num_of_policies object identifiers, where
subject_domain_policy[i] is the mapping of
issuer_domain_policy[i].
typedef struct {
int num_of_policies;
X509_obj_id CK_PTR issuer_domain_policy;
X509_obj_id CK_PTR subject_domain_policy;
5-70
} X509_ext_2933, X509_ext_PolicyMappings;
X509_ext_2935, X509_ext_AuthorityKeyIdentifier
X509_ext_2935 structure contains the authority key identifier extension data.
The key may be identified in two different ways:
♦ As key_id – an octet string identifying the key. The octet string and its
length are stored in CK_DATA data structure.
♦ By identifying the certificate associated with the key. As
auth_cert_issuer, the issuer of the certificate, and cert_ser_num, the
certificate’s serial number.
typedef struct {
CK_DATA key_id;
X509_general_names CK_PTR auth_cert_issuer;
char CK_PTR cert_ser_num;
} X509_ext_2935, X509_ext_AuthorityKeyIdentifier;
X509_ext_2936, X509_ext_PolicyConstraints
X509_ext_2936 structure specifies constraints, which may require explicit
certificate policy identification or inhibit policy mapping for the remainder of
the certification path. The RequireExplicitPolicy and inhibitPolicyMapping
fields specify the number of certificates in the path to skip before starting with
these constraints. A value of (–1) for any of these fields means that no value was
specified.
typedef struct {
int requireExplicitPolicy;
int inhibitPolicyMapping;
} X509_ext_2936, X509_ext_PolicyConstraints;
5-71
X509_ext_2937, X509 _ext_ExtendedKeyUsage

X509_ext_2937 structure specifies one or more purposes for which the public
key may be used, in addition to, or instead of the basic purposes indicated in the
key usage extension.
The key_purpose_id field is an array of num_of_ids object identifiers, each

specifying one key usage.
typedef struct {
int num_of_ids;
X509_obj_id CK_PTR key_purpose_id;
} X509_ext_2937, X509_ext_ExtendedKeyUsage;
5-72
Functions
This section describes the X.509 Toolkit functions as defined in ck_x509.h.

For each function, the following information is provided:
♦ Description
♦ Syntax
♦ Return codes
For examples of how to use these functions, refer to Working with the X.509
Toolkit, earlier in this chapter.
C_X509_Decode
C_X509_Decode receives a BER encoded structure of a certificate/CRL, and
decodes it.
Syntax
int C_X509_Decode(CK_ASN_ID Type,
CK_ULONG_PTR pulDecodedLen);
Parameters
♦ Type [in] – the internal type of the structure (Certificate, CRL).
♦ pEncoded [in] – the BER encoded certificate/CRL.
♦ ulEncodedLen [in] – the size in bytes of the encoded certificate/CRL in
pEncoded.
5-73
♦ pDecoded [in/out] – on entry, points to a buffer for holding the decoded

structure. Upon return, pDecoded points to the output decoded structure.
♦ pulDecodedLen [in/out] on entry holds the size in bytes of pDecoded
buffer. Upon return, it contains the number of unused bytes in pDecoded
buffer.
Return codes
CKR_OK – function was completed successfully.
CKR_BUFFER_TOO_SMALL – the buffer supplied was too small. The
amount of memory required (beyond what was supplied) is returned in
pulDecodedLen.
CKR_BADLY_FORMATTED_INPUT – pEncoded is not a valid BER
encoded structure of type Type.
CKR_ARGUMENTS_BAD – one of the function parameters is invalid.
C_X509_Encode
C_X509_Encode receives a decoded structure of a certificate/CRL and DER
encodes it.
Syntax
int C_X509_Encode(CK_ASN_ID Type,
CK_ULONG_PTR pulEncodedLen);
Parameters
♦ pDecoded [in] – the decoded data structure.
5-74
♦ ulDecodedLen [in] – the size in bytes of the input data structure
pDecoded.
♦ pEncoded [in/out] – on entry, points to a buffer for holding the output
DER encoded certificate/CRL. Upon return, points to the DER encoded
structure.
♦ pulEncodedLen [in/out] – on entry, holds the size in bytes of the input
pEncoded buffer. Upon return, it contains the number of unused bytes in
the pEncoded buffer.
Return codes
pulEncodedLen.
CKR_X509_BAD_STRUCTURE – a bad data structure was given to the
function.
C_X509_GetField
C_X509_GetField receives a BER encoded structure of a certificate/CRL, and
decodes only one of its fields. If the specified field does not appear in the
certificate (such as a specific extension), an empty structure is returned.
Syntax
int C_X509_GetField( CK_ASN_ID Type,
CK_ULONG_PTR pulDecodedLen,
5-75
CK_X509_FIELD Field);
Parameters
♦ pEncoded [in] – the BER encoded certificate/CRL.
♦ ulEncodedLen [in] – the size in bytes of the input certificate/CRL in
pEncoded.
♦ pDecoded [in/out] – on entry, points to a buffer for holding the output
decoded structure. Upon return, points to the decoded structure. This
structure should be cast to a structure according to the field type. For
example, if Field is X509_CERT_FIELD_ISSUER, cast pDecoded to
X509_Dname.
♦ pulDecodedLen [in/out] – on entry, holds the size in bytes of pDecoded
buffer. Upon return, it contains the number of unused bytes in the
pDecoded buffer.
♦ Field [in] – the desired field. A list of fields can be found in the
Constants section above.
Return codes
pulDecodedLen.
CKR_BADLY_FORMATTED_INPUT – pEncoded is not a valid BER
C_X509_Copy
C_X509_Copy copies a complex structure into a duplicate in a continuous
memory block.
5-76
Syntax
int C_X509_Copy( CK_ASN_ID Type,
CK_VOID_PTR pSrc,
CK_ULONG ulSrcLen,
CK_VOID_PTR pDst,
CK_ULONG_PTR pulDstLen);
Parameters
♦ Type [in] – the internal type of the structure (Certificate, CRL, Dname,
extension etc.).
♦ pSrc [in] – the source structure.
♦ ulSrcLen [in] – the size in bytes of the source structure.
♦ pDst [in/out] – on entry, points to a buffer for holding the destination
structure. Upon return, pDst points to the copied structure.
♦ pulDstLen [in/out] – on entry, holds the size of pDst buffer. Upon
return, it contains the number of unused bytes in pDst buffer.
Return codes
pulDstLen.
CKR_BADLY_FORMATTED_INPUT – a bad structure was given to
the function.
5-77
C_X509_Sign
C_X509_Sign receives a BER encoded ToBeSigned section of a certificate or
CRL and signs it using the user’s private key, thereby constructing a fully signed
X.509 certificate or CRL object. C_X509_Sign requires that a cryptographic
session be opened before it is called. C_X509_sign uses the signature_alg field
of the input to know which hash and signature algorithm to use.
Note that a DSA signature incorporates random data, which results in different
lengths of ASN.1 encoding. When the function is not given enough memory, the
return size may be a few bytes more than actually required for the signing.
Syntax
int C_X509_Sign(CK_SESSION_HANDLE hSess,
CK_ASN_ID Type,
CK_VOID_PTR pObject,
CK_ULONG ulObjectLen,
Parameters
♦ hSess [in] – handle to a cryptographic session.
♦ hKey [in] – handle to the private key object of the signer.
♦ pObject [in] – the object to be signed.
♦ ulObjectLen [in] – the size in bytes of the input object pObject.
♦ pSignedObject [in/out] – on entry, points to a buffer for holding the
signed certificate/CRL. Upon return, points to the signed object.
5-78
♦ pulSignedObjectLen [in/out] – on entry, holds the size in bytes of the
input pSignedObject buffer. Upon return, it contains the number of
unused bytes in the pSignedObject buffer.
Return codes
pulSignedObjectLen.
CKR_BADLY_FORMATTED_INPUT – pObject is not a valid BER
CKR_UNSUPPORTED_ENC_ALG – X.509 Toolkit does not support
the encryption algorithm.
CKR_UNSUPPORTED_HASH_ALG – X.509 Toolkit does not support
the hash algorithm.
CKR_KEY_SIZE_RANGE – key size not supported by the X.509
Toolkit for this algorithm.
C_X509_EncodeSign
C_X509_EncodeSign receives an X509_certificate or X509_crl data struture,
DER encodes it, and signs it with the user’s private key, thereby constructing a
fully signed X.509 certificate or CRL object. C_X509_EncodeSign requires that
a cryptographic session be opened before it is called. C_X509_EncodeSign uses
the signature_alg field of the input to know which hash and signature algorithm
to use.
Note that a DSA signature incorporates random data, which results in different
lengths of ASN.1 encoding. When the function is not given enough memory, the
return size may be a few bytes more than actually required for the signing.
5-79
Syntax
int C_X509_EncodeSign(
CK_SESSION_HANDLE hSess,
CK_ASN_ID Type,
Parameters
♦ hKey [in] – handle to the private key object of the signer.
♦ pDecoded [in] – the X509_certificate or X509_crl structure to be
encoded and signed.
♦ ulDecodedLen [in] – the size in bytes of the input object pDecoded.
♦ pSignedObject [in/out] – on entry, points to a buffer for holding the
encoded and signed certificate/CRL. Upon return, points to the encoded
and signed object.
♦ pulSignedObjectLen [in/out] – on entry, holds the size in bytes of the
input pSignedObject buffer. Upon return, it contains the number of
unused bytes in the pSignedObject buffer.
Return codes
5-80
pulSignedObjectLen.
CKR_X509_BAD_STRUCTURE – pDecoded is not a valid data
structure of type Type.
the hash algorithm.
CKR_KEY_SIZE_RANGE – X.509 Toolkit does not support the
required key size for this algorithm.
C_X509_Verify
C_X509_Verify verifies the signature and time validity of a BER encoded
certificate/CRL. It also checks if an unknown critical extension is present.
C_X509_Verify requires that a cryptographic session be opened before it is
called. C_X509_Verify uses the signature_alg field of the input to know which
hash and signature algorithm to use.
Note that C_X509_Verify first checks the signature, then the time validity, and
finally the critical extensions. If one of the KEY_NOT_VALID or the
CKR_X509_UNKNOWN_CRITICAL_EXTENSION codes is returned, this
indicates that the signature was checked and is valid.
If no key is specified in the form of hKey or pCACert, it is assumed that the
input is a self-signed certificate.
Syntax
int C_X509_Verify(
5-81
CK_ASN_ID Type,
CK_ULONG ulSignedObjectLen,
CK_VOID_PTR pCACert,
CK_ULONG ulCACertLen);
Parameters
♦ hKey [in] – handle to the public key object of the signer.
♦ pSignedObject [in] – the BER encoded signed object to be verified.
♦ pSignedObjectLen [in] – the size in bytes of pSignedObject.
♦ pCACert [in] – the certificate of the CA, which signed the above
certificate/CRL. If hKey is NULL and pCACert is not NULL, the
public key from pCACert will be used to verify the signature. If both
hKey and pCACert are NULL, it is assumed that the input is a self-
signed certificate.
♦ ulCACertLen [in] – the size in bytes of pCACert.
Return codes
CKR_SIGNATURE_INVALID – signature is invalid.
CKR_X509_KEY_NOT_VALID_YET – validity period has not begun.
CKR_X509_KEY_NOT_VALID_ANYMORE – validity period has
ended.
CKR_X509_UNKNOWN_CRITICAL_EXTENSION – certificate/CRL
has an unknown extension, which is marked critical.
5-82
CKR_BADLY_FORMATTED_INPUT – pSignedObject is not a valid
BER encoded structure of type Type.
the hash algorithm.
CKR_KEY_SIZE_RANGE – X.509 Toolkit does not support the
required key size for this algorithm.
C_X509_FindInCrl
C_X509_FindInCrl checks if a certificate is listed in a CRL. This is
accomplished by checking that the issuer (if a complete certificate or X509_tbs
is supplied) is the same, and then comparing the certificate's serial number to the
serial numbers specified in the revocation list.
Syntax
int C_X509_FindInCRL(
CK_VOID_PTR pEncodedObj,
CK_ULONG ulEncodedObjLen,
CK_VOID_PTR pEncodedCRL,
CK_ULONG ulEncodedCRLLen,
CK_ASN_ID Type,
CK_VOID_PTR pRevoked,
CK_ULONG_PTR pulRevokedLen,
CK_ULONG_PTR pulResult);
Parameters
5-83
♦ pEncodedObj [in] – the BER encoded certificate, an X509_tbs structure,

or just a serial number.
♦ pEncodedObjLen [in] – the size in bytes of pEncodedObj.
♦ pEncodedCRL [in] – the BER encoded CRL.
♦ ulEncodedCRLLen [in] – the size in bytes of pEncodedCRL.
♦ Type [in] – the internal type of the input structure pEncodedObj:
CK_X509_ID_CERT, CK_X509_ID_TBS, CK_X509_ID_SER_NUM.
♦ pRevoked [in/out] – on entry, points to a memory buffer for holding an
X509_Revoked structure, if found. Upon return, if the certificate is found
pRevoked points to the complete X509_Revoked structure of the
certificate in the CRL. If pRevoked is NULL, the structure is not
returned.
♦ pulRevokedLen [in/out] – on entry, holds the size in bytes of pRevoked
buffer. Upon return, it contains the number of unused bytes in
pRevoked.
♦ pulResult [out] – when the function returns CKR_OK, this field returns
the revocation reason. Possible result values are listed below:
CKR_X509_DIFFERENT_ISSUERS – the certificate and CRL
are from different issuers.
CKR_X509_NOT_FOUND – the certificate was not found in the
CRL.
CKR_X509_FOUND – the certificate was found in the CRL, but
no reason for revocation was specified.
CKR_X509_FOUND_KEY_COMPROMISE – the certificate was
revoked because the key was compromised.
CKR_X509_FOUND_CA_COMPROMISE – the certificate was
revoked because the CA was compromised.
CKR_X509_FOUND_AFFILIATION_CHANGED – the
certificate was revoked because of a change in the subject’s name
or other information.
5-84
CKR_X509_FOUND_SUPERSEDED – the certificate was
revoked because it was superseded.
CKR_X509_FOUND_CESSATION_OF_OPERATION – the
certificate was revoked because it is no longer required for the
purpose it was issued for.
CKR_X509_FOUND_CERTIFICATE_HOLD – the certificate
was placed on hold.
CKR_X509_FOUND_REMOVE_FROM_CRL – the certificate
should be removed from the CRL (used only with delta-CRLs).
Return codes
CKR_BADLY_FORMATTED_INPUT – pEncodedObj or
pEncodedCrl is not a valid BER encoded structure.
CKR_X509_BAD_STRUCTURE- a bad structure was given to the
function (when X509_tbs is given as input).
5-85
PKCS#10,#7 Certificate Request and Reply
The building blocks for any application based on PKI (Public Key
Infrastructure) are public key certificates. These serve as a digital ID for the End
Entity, which can be a person, a software application or a hardware device. A
public key certificate is issued to the End Entity by a trusted third party called a
CA (Certificate Authority), which must first receive a certificate request
message from the End Entity. The CA verifies that the request is valid and was
indeed sent by the End Entity, and then creates a certificate reply message,
which includes the End Entity's certificate.
Currently, some standard and legacy message protocols are used for processing
certificate requests and issuing certificates. Applications implemented around
the world use protocols such as PKIX, CMP/CRMF, PEM, VeriSign's CRS and
Cisco's SCEP. One of the simplest and most popular methods for certification
messages uses PKCS#10 certificate requests, and PKCS#7 certificate replies
(also known as a "certificates only SignedData PKCS#7 message").
The PKCS#10,#7 Toolkit is an add-on to PKCS#11 for handling certificate

requests and replies through PKCS#10 and PKCS#7 formatted messages. This
library includes functions for encoding and decoding both PKCS#10 certificate
requests and PKCS#7 certificate replies, including signing and signature
verification where needed.
The PKCS#10,#7 Toolkit uses Algorithmic Research's X.509 Toolkit library to

process certificate operations, such as signature verification.
5-86
General Data Types
The PKCS#10,#7 Toolkit defines

specific data types in ck_pk107.h.
It also uses generic data types as
defined in PKCS#11 and in
Algorithmic Research's X.509
Toolkit.
These data types are used to

represent the ASN.1 structure of a
PKCS#10 certificate request. The
following figure shows the
hierarchical relationship between
the different structures described
later in this section.
5-87
CRQ_FORMAT
DER encoding is used to encode PKCS#10 certificate requests. It creates a
binary message from the stream of data. Some applications though, require that
the binary certificate request be converted to a text message, possibly with a
header and footer. CRQ_FORMAT defines the exact format of the PKCS#10
certificate request.
#define CRQ_FORMAT int
Possible Values
♦ BASIC_PKCS10 – DER encoded binary data.
♦ BASE64_PKCS10 – Base64 encoding of the DER data, results in a text
message.
♦ VERISIGN_CSR – Base64 encoding of the DER data with header and
footer as defined for VeriSign's CSR message.
CRP_FORMAT
Similarly to the PKCS#10 certificate request, the PKCS#7 certificate reply can
be encoded as a binay stream of data in DER format. Some applications though,
require that the binary certificate reply be converted to a text message, possibly
with a header and footer. CRP_FORMAT defines the exact format of the
PKCS#7 certificate reply.
#define CRP_FORMAT int
Possible Values
♦ BASIC_PKCS7 – DER encoded binary data.
♦ BASE64_PKCS7 – Base64 encoding of the DER data, results in a text
message.
♦ VERISIGN_PKCS7 – Base64 encoding of the DER data with header and
footer as defined by VeriSign for replies to CSR messages.
5-88
pkcs10_cr
This data structure represents the contents of a PKCS#10 certificate request. It is
used as input to the C_PKCS10_CreateCRQ function and as output of the
C_PKCS10_AcceptCRQ function. All the fields of the structure (except for the
signature) must be filled before calling C_PKCS10_CreateCRQ. For a simpler
version of certificate request, which is sufficient for most applications, see
simple_dname later in this section.
typedef struct {
pkcs10_cri cri;
} pkcs10_cr;
♦ cri – certificate request information.

♦ signature – signature acquired by using the subject's private key on the
encoded cri.
pkcs10_cri
The pkcs10_cri data structure represents the Certificate request info section, of
a PKCS#10 certificate request.
typedef struct {
int version;
X509_Dname subject;
X509_key_info subject_key_info;
X509_attributes CK_PTR attributes;
} pkcs10_cri;
♦ version – PKCS#10 protocol version: Always 0.
♦ subject – distinguished name of the subject (person or machine
requesting the certificate).
5-89
♦ subject_key_info – public key of the subject (must be the public key

paired with the private key used to sign the message).
♦ attributes – additional attributes.
X509_attributes
The X509_attributes structure contains a set of attributes that provide
additional information about the requesting entity and its keys.
typedef struct {
int num_of_attributes;
X509_attribute CK_PTR attributes;
} X509_attributes;
♦ num_of_attributes – number of attributes in this set.
♦ attributes – array of num_of_attributes attributes.
X509_attribute
The X509_attribute contains one attribute consisting of its type and its value(s).
typedef struct {
X509_obj_id type;
int num_of_values;
X509_attr_value CK_PTR values;
} X509_attribute;
♦ type – object Identifier defining the attribute type.
♦ num_of_values – number of different values defined for this attribute.
♦ values – array of num_of_values values.
5-90
X509_attr_value
The X509_attr_value structure contains the value of an attribute.
typedef struct {
CK_BYTE value_type;
int value_len;
CK_BYTE_PTR value;
} X509_attr_value;
♦ value_type – ASN.1 value type (e.g., Printable String – 0x13).
♦ value_len – length of the value, in bytes.
♦ value – actual value.
simple_dname
The simple_dname structure is a simplified version of a certificate request. It
can be used as input for creating a PKCS#10 certificate request, with the
C_PKCS10_SimpleCreateCRQ function.
typedef struct {
CK_ASN_ID RDN_type;
char value[64];
} simple_dname;
♦ RDN_type – type of the RDN (Relative Distinguished Name) value.
♦ value – actual value (a null terminated string).
certs_and_crls
The certs_and_crls structure contains a list of certificates and CRLs. This
structure is used as input or output to different PKCS#7 functions.
typedef struct {
5-91
cert_list CK_PTR certs;

cert_list CK_PTR crls;
} certs_and_crls;
♦ certs – list of certificates.
♦ crls – list of CRLs.
cert_list
The cert_list data structure contains a list of certificates or CRLs.
typedef struct {
CK_BYTE_PTR CK_PTR certs;
CK_ULONG_PTR certLen;
CK_ULONG numOfCerts;
} cert_list;
♦ certs – an array of numOfCerts binary (DER encoded)
certificates/CRLs.
♦ certLen – array featuring the size, in bytes, of each corresponding
certificate/CRL – array size is defined by numOfCerts.
♦ numOfCerts – the number of certificates/CRLs in the list.
5-92
Functions
This section describes the functions contained in the CryptoKit PKCS#10,#7

Toolkit, as defined in the ck_pk107.h file. For each function, the following
information is provided:
♦ Description
♦ Syntax
Samples of these functions are provided in the Programming samples section

below.
C_PKCS10_CreateCRQ
C_PKCS10_CreateCRQ creates a PKCS#10 certificate request in the format
specified by crqFormat, according to the data in pkcs10_cri (Certificate
Request Information).
Syntax
int C_PKCS10_CreateCRQ(
CRQ_FORMAT crqFormat,
pkcs10_cr CK_PTR pCR,
CK_BYTE_PTR pEncodedCrq,
CK_ULONG_PTR pulEncodedCrqLen);
Parameters
♦ hKey [in] – handle to the user’s private key.
♦ crqFormat [in] – the format of the output certificate request.
5-93
♦ pCR [in] – pointer to the certificate request information structure.

♦ pEncodedCrq [out] – buffer for the output encoded PKCS#10 certificate
request in the format specified by crqFormat.
♦ pulEncodedCrqLen [in/out] – on entry, holds the initial size of the
pEncodedCrq buffer. Upon return, contains the actual size of the
encoded data, or the required size, if the buffer is not large enough.
C_PKCS10_SimpleCreateCRQ
C_PKCS10_SimpleCreateCRQ also creates a PKCS#10 certificate request. The
simple input parameters, enables you to create the cretificate request without
building the complex data structure of pkcs10_cri. The public key information
is taken from the key media, and no attributes are included in the message.
Syntax
int C_PKCS10_SimpleCreateCRQ(
simple_dname CK_PTR pDname,
CK_ULONG ulNumOfRDNs,
CK_ULONG_PTR pulEncodedCrqLen);
Parameters
♦ hKey [in] – handle to the user’s private key.
♦ crqFormat [in] – the format of the output certificate request.
♦ pDname [in] – an array of RDN values that comprises the subject’s
dname.
5-94
♦ ulNumOfRDNs [in] – the number of entries in the dname array.
♦ pEncodedCrq [out] – a buffer for the output encoded PKCS#10
certificate request in the format specified by crqFormat.
♦ pulEncodedCrqLen [in/out] – on entry, holds the initial size of the
pEncodedCrq buffer. Upon return, it contains the actual size of the
C_PKCS10_AcceptCRQ
C_PKCS10_AcceptCRQ accepts a PKCS#10 certificate request. It verifies that
the signature that was affixed to it was by the private key that corresponds to the
public key it contains. Then, it returns its contents in a pkcs10_cr data
structure.
Syntax
int C_PKCS10_AcceptCRQ(
CK_ULONG ulEncodedCrqLen,
CK_BYTE_PTR pDecodedCrq,
CK_ULONG_PTR pulDecodedCrqLen);
Parameters
♦ crqFormat [in]- the format of the input certificate reply.
♦ pEncodedCrq [in] – the input PKCS#10 certificate request.
♦ ulEncodedCrqLen [in] – the size in bytes of pEncodedCrq.
♦ pDecodedCrq [out] – the buffer for the output pkcs10_cr structure.
5-95
♦ pulDecodedCrqLen [in/out] – on entry, holds the initial size of the

pDecodedCrq buffer. Upon return, it contains the actual size of the
decoded data, or the required size, if the buffer is not large enough.
C_PKCS7_AcceptCRP
C_PKCS7_AcceptCRP accepts a PKCS#7 certificate reply and returns the
certificate(s) contained in it. If CA certificates are included, the complete
certification chain is constructed and verified. If the reply also contains CRLs,
the verification process includes the data in the CRLs.
Syntax
int C_PKCS7_AcceptCRP(
CRP_FORMAT crpFormat,
CK_BYTE_PTR pEncodedCrp,
CK_ULONG ulEncodedCrpLen,
CK_BYTE_PTR pDecodedCrp,
CK_ULONG_PTR pulDecodedCrpLen,
cert_list CK_PTR pCACerts);
Parameters
♦ crpFormat [in] – the format of the input certificate reply.
♦ pEncodedCrp [in] – the certificate reply comprised of certificates-only
PKCS#7 signed data.
♦ ulEncodedCrpLen [in] – the size in bytes of pEncodedCrp.
♦ pDecodedCrp [out] – a buffer for the output certificate(s). It should be
cast to certs_and_crls.
5-96
♦ pulDecodedCrpLen [in/out] – on entry holds the initial size of the
pDecodedCrp buffer. Upon return, it contains the actual size of the
decoded data, or the required size, if the buffer is not large enough.
♦ pCACerts [in] – CA certificate(s) (or fingerprints of these certificates)
needed for verifying the signature on the certificate and the message. If
this value is NULL, then no signature will be verified.
C_PKCS7_CreateCRP
C_PKCS7_CreateCRP creates a PKCS#7 certificate reply with the certificates
and CRLs in pCertsAndCrls.
Syntax
int C_PKCS7_CreateCRP(
CRP_FORMAT crpFormat,
certs_and_crls CK_PTR pCertsAndCrls,
CK_BYTE_PTR pEncodedCrp,
CK_ULONG_PTR pulEncodedCrpLen);
Parameters
♦ crpFormat [in] – the format of the output certificate reply.
♦ pCertsAndCrls [in] – the certificates and CRLs to be included in the
reply.
♦ pEncodedCrp [out] – a buffer for the output encoded PKCS#7
certificate reply in the format specified by crpFormat.
♦ pulEncodedCrpLen [in/out] – on entry holds the initial size of
pEncodedCrp buffer. Upon return, contains the actual size of the
5-97
Programming Samples
Some programming samples are included with the PKCS#10,#7 Toolkit to

enable developers to become familiar with the various functions.
Generating a Certificate Request

The following sample demonstrates how to create a certificate request using the
C_PKCS10_SimpleCreateCRQ function. For the purposes of the sample, it is
assumed that the key media is already initialized, and a user key pair was
generated.
This sample is included on the AR CryptoKit Installation CD in the

CreateCrq.c file.
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include "ck_pk107.h"
#include "pkcs11.h"
int main()
{
CK_RV rc;
// Attributes for finding the private key object

CK_ULONG attribDSA = CKK_DSA;
{CKA_CLASS,&attribPrivateKey,sizeof(attribPrivateKey)},
{CKA_KEY_TYPE,&attribRSA,sizeof(attribRSA)},};
CK_ATTRIBUTE findDSAPrivateKey[] = {
{CKA_KEY_TYPE,&attribDSA,sizeof(attribDSA)},};
5-98
CK_OBJECT_HANDLE hPrivateKey;
FILE * f;
simple_dname dnames[10];
BYTE encodedCrq[2048];
CK_ULONG encodedCrqLen = sizeof(encodedCrq);
// Change these for different key types, crq formats, or

// output file names
int keyType = ASN1_OI_RSA;
CRQ_FORMAT crqFormat = BASE64_PKCS10;
char fname[32] = {"out.crq"};
// Setup distinguished name values

sprintf(dnames[0].value,"IL");
dnames[0].RDN_type = ASN1_OI_COUNTRY;
sprintf(dnames[1].value,"Algorithmic Research Ltd.");
dnames[1].RDN_type = ASN1_OI_ORG;
sprintf(dnames[2].value,"PKCS#10 Sample");
dnames[2].RDN_type = ASN1_OI_COMMON_NAME;
// Open cryptographic session

if (rc != CKR_OK) {
exit(0);
}
if (rc != CKR_OK) {
exit(0);
}
rc = C_OpenSession(pSlotList[0],CKF_RW_SESSION
|CKF_SERIAL_SESSION,NULL_PTR,NULL_PTR,&hSession);
if (rc != CKR_OK) {
exit(0);
}
rc = C_Login(hSession,CKU_USER,NULL_PTR,0);
if (rc != CKR_OK) {
5-99

exit(0);
}
// Find private key object

if (keyType == ASN1_OI_DSA)
rc = C_FindObjectsInit(hSession,findDSAPrivateKey,2);
else
if (rc != CKR_OK) {
exit(0);
}
rc = C_FindObjects(hSession,&hPrivateKey,1,&ulObjectsFound);
exit(0);
}
if (rc != CKR_OK) {
exit(0);
}
// Create the PKCS#10 CRQ

rc = C_PKCS10_SimpleCreateCRQ(hSession,hPrivateKey,
crqFormat,dnames,3, encodedCrq,&encodedCrqLen);
if (rc != CKR_OK) {
printf("*** Error %x in SimpleCreatePKCS10CRQ\n",rc);
exit(0);
}
// Save CRQ to file

f = fopen(fname,"wb");
if (f) {
5-100
fwrite(encodedCrq,1,encodedCrqLen,f);
fclose(f);
printf("CRQ created successfully and saved in file
%s\n",fname);
}
else
printf("*** Error – Unable to open output file
%s\n",fname);
// Close crypto
rc = C_Logout(hSession);
if (rc != CKR_OK)
printf("*** Error in C_Logout – %x\n",rc);
return(0);
}
Before calling C_PKCS10_SimpleCreateCRQ the program prepares two

important items:
♦ The user's Distinguished Name in an array of simple_dname structures.
♦ A handle to a cryptographic session and to the user's private key.
Once the program has completed these assignments it is ready to call the
function:
rc = C_PKCS10_SimpleCreateCRQ(
hSession,hPrivateKey,crqFormat,dnames,3,
encodedCrq,&encodedCrqLen)
This function call contains the following parameters:

♦ hSession – handle to the cryptographic session.
♦ hPrivateKey – handle to the user's private key.
♦ crqFormat – the format for the certificate request.
5-101
♦ dnames – array of simple_dname structures which constitute the user's

Distinguished Name.
♦ 3 – number of Relative Distinguished Names in the dname – size of the
dnames array.
♦ encodedCrq – buffer for the output certificate request.
♦ encodedCrqLen – size of the encodedCrq buffer.
After the call has been completed successfully, the certificate request is saved to
a file. It can also be displayed to a user for cut&paste, or sent directly over
TCP/IP.
Processing a Certificate Reply

Upon receiving a certificate reply from the CA the function
C_PKCS7_AcceptCRP is called to parse it and extract the End Entity's
certificate, as well as any other certificates and CRLs present in the certificate
reply.
The following sample is included on the AR CryptoKit Installation CD in the

AcceptCrp.c file.
#include <stdio.h>
#include <stdlib.h>
#include "pkcs11.h"
{
FILE * f;
char fname[32];
CK_SESSION_HANDLE hSess;
CK_CHAR_PTR pin = "12345678";
5-102
CK_RV rc;
BYTE encodedCrp[4096];
CK_ULONG encodedCrpLen = sizeof(encodedCrp);
BYTE decodedCrp[4096];
CK_ULONG decodedCrpLen = sizeof(decodedCrp);
CK_ULONG tmpLen;
certs_and_crls * CertsAndCrls;
CRP_FORMAT crpFormat = BASE64_PKCS7;
CK_ULONG i;
if (argc != 2) {
printf("Usage: AcceptCrp crp_file\n\n");
exit(0);
}
// Read crp from file

if (!f) {
printf("*** Error opening crp file\n");
exit(0);
}
tmpLen = fread(encodedCrp,1,encodedCrpLen,f);
fclose(f);
if (tmpLen == encodedCrpLen) {
printf("*** Internal Error – Buffer too short for Crp
file\n");
exit(0);
}
encodedCrpLen = tmpLen;
// Start crypto
if (rc != CKR_OK) {
exit(0);
}
if (rc != CKR_OK) {
exit(0);
}
5-103
CKF_SERIAL_SESSION,NULL_PTR,NULL_PTR,&hSess);
if (rc != CKR_OK) {
exit(0);
}
// The value of crpFormat doesn't really matter since the

// function determines the format according to the input
rc =
C_PKCS7_AcceptCRP(hSess,crpFormat,encodedCrp,encodedCrpLen,
decodedCrp,&decodedCrpLen,NULL);
if (rc != CKR_OK) {
printf("*** Error in C_PKCS7_AcceptCRP – %x\n",rc);
exit(0);
}
printf("Certificate reply parsed successfully!\n",rc);

CertsAndCrls = (certs_and_crls *)decodedCrp;
// Write certificates to files

if (CertsAndCrls->certs) {
for (i=0;i<CertsAndCrls->certs->numOfCerts;i++) {
sprintf(fname,"cert%d.crt",i+1);
if (f) {
fwrite(CertsAndCrls
->certs>certs[i],1,CertsAndCrls
->certs->certLen[i],f);
printf("Certificate written to file
%s\n",fname);
}
else
printf("*** Error – Failed to open file %s
for output\n",fname);
}
}
// Write CRLs to files
5-104
if (CertsAndCrls->crls) {
for (i=0;i<CertsAndCrls->crls->numOfCerts;i++) {
sprintf(fname,"crl%d.crl",i+1);
if (f) {
fwrite(CertsAndCrls->crls
->certs[i],1,CertsAndCrls
->crls->certLen[i],f);
printf("Certificate written to file
%s\n",fname);
}
else
printf("*** Error – Failed to open file %s
for output\n",fname);
}
}
// End crypto
return(0);
}
The program first reads the certificate reply data from a file. Then it opens a
cryptographic session, and calls C_PKCS7_AcceptCRP to process the certificate
reply. The program does not check the validity of the certificate. You can check
for the certificate validity by loading the known CA's certificates, placing them
in a cert_list structure, and adding them to the parameters when calling the
function.
The call to C_PKCS7_AcceptCRP in this sample:

rc = C_PKCS7_AcceptCRP(hSess,crpFormat,encodedCrp,
encodedCrpLen, decodedCrp,&decodedCrpLen,NULL);
contains the following parameters:

♦ hSess – handle to cryptographic session.
♦ crpFormat – the format of the certificate reply – in this example it is
BASE64_PKCS7.
5-105
♦ encodedCrp – buffer into which the certificate reply was loaded.

♦ encodedCrpLen – length of the certificate reply.
♦ decodedCrp – buffer for the function output, it is later cast to the
structure certs_and_crls.
♦ decodedCrpLen – the size of the decodedCrp buffer.
♦ NULL – no CA certificates are supplied to the function – no certificate
verification is performed.
The data that results from calling the function is placed in decodedCrp and cast
to certs_and_crls. Then, all the certificates and CRLs present in the certificate
reply are saved to disk. In actual applications, the certificates and CRLs are
probably stored in a database, or even in the key media. For example, using
Algorithmic Research's PrivateWire, the End Entity's certificate is saved in the
key media.
Processing Certificate Requests and Creating Replies

Certificate Authorities mainly process certificate requests from users, create the
certificates, and send them back to users in a certificate reply.
This is illustrated in the following sample and, in fact, this application can serve
as a fully functional CA, or be used as the basis for a comprehensive CA.
This sample is included on the AR PKCS#11 Toolkit Installation CD in the

MicroCA.c file.
#include <stdio.h>
#include <stdlib.h>
#include <time.h>
#include "pkcs11.h"
CK_RV GetKeyHandle(CK_SESSION_HANDLE hSession,

CK_OBJECT_HANDLE CK_PTR hKey,
int alg_id);
5-106
{
FILE * f;
CK_SESSION_HANDLE hSess;
CK_OBJECT_HANDLE hKey;
CK_RV rc;
BYTE encodedCrq[4096];
CK_ULONG encodedCrqLen = sizeof(encodedCrq);
BYTE encodedCrt[4096];
CK_ULONG encodedCrtLen = sizeof(encodedCrt);
BYTE decodedCrq[4096];
CK_ULONG decodedCrqLen = sizeof(decodedCrq);
BYTE decodedCrt[4096];
CK_ULONG decodedCrtLen = sizeof(decodedCrt);
BYTE encodedCrp[4096];
CK_ULONG encodedCrpLen = sizeof(encodedCrp);
CK_ULONG tmpLen;
certs_and_crls CertsAndCrls;
cert_list CertList;
CRQ_FORMAT crqFormat;
CRP_FORMAT crpFormat;
char outFile[3][16] = {
{"reply.der"},{"reply.b64"},{"reply.pk7"}};
pkcs10_cr * pCr;
X509_certificate * pCert;
CK_BYTE_PTR pCerts[2];
CK_ULONG CertsLen[2];
if (argc != 5) {
printf("Usage: MicroCA <CA_file> <crq_file> <crq/p
format> <SN>\n");
printf("\t<CA_file> = CA certificate file\n");
printf("\t<crq_file> = file with crq\n");
printf("\t<crq/p format> = (1)basic der, (2)basic
base64, (3)VeriSign csr\n");
printf("\t<SN> = Serial number to be given to the new
certificate\n\n");
exit(0);
5-107
}
// Read the CA certificate from file
if (!f) {
printf("*** Error opening crt file\n");
exit(0);
}
tmpLen = fread(encodedCrt,1,encodedCrtLen,f);
fclose(f);
if (tmpLen == encodedCrtLen) {
printf("*** Internal Error – Buffer too short for Crt
file\n");
exit(0);
}
encodedCrtLen = tmpLen;
// Read crq from file

if (!f) {
printf("*** Error opening crq file\n");
exit(0);
}
tmpLen = fread(encodedCrq,1,encodedCrqLen,f);
fclose(f);
if (tmpLen == encodedCrqLen) {
printf("*** Internal Error – Buffer too short for Crq
file\n");
exit(0);
}
encodedCrqLen = tmpLen;
// Get crq/p format

crqFormat = atoi(argv[3]);
if ((crqFormat<1) || (crqFormat>3)) {
printf("*** Invalid value for crqFormat –
<%s>\n",argv[3]);
exit(0);
}
crpFormat = crqFormat;
5-108
// Start crypto
if (rc != CKR_OK) {
exit(0);
}
if (rc != CKR_OK) {
exit(0);
}
rc = C_OpenSession(pSlotList[0],CKF_RW_SESSION|
CKF_SERIAL_SESSION, NULL_PTR,NULL_PTR,&hSess);
if (rc != CKR_OK) {
exit(0);
}
// Verify and parse certificate request

rc =
C_PKCS10_AcceptCRQ(hSess,crqFormat,encodedCrq,encodedCrqLen,
decodedCrq,&decodedCrqLen);
if (rc != CKR_OK) {
printf("*** Error %x in C_PKCS10_AcceptCRQ\n",rc);
exit(0);
}
pCr = (pkcs10_cr *)decodedCrq;
// Decode CA certificate
rc = C_X509_Decode(CK_X509_ID_CERT,encodedCrt,encodedCrtLen,
decodedCrt,&decodedCrtLen);
if (rc != CKR_OK) {
printf("*** Error in C_X509_Decode – %x\n",rc);
exit(0);
}
pCert = (X509_certificate *)decodedCrt;
5-109
// Create new certificate using CA certificate data as a basis
// Set Serial Number

pCert->tbs.serial_number = argv[4];
// Subject distinguished name
pCert->tbs.subject.num_of_RDNs = pCr->cri.subject.num_of_RDNs;
pCert->tbs.subject.RDNs = pCr->cri.subject.RDNs;
// Subject public key info

pCert->tbs.subject_key_info.algorithm_id.alg_id.int_id =
pCr->cri.subject_key_info.algorithm_id.alg_id.int_id;
pCert->tbs.subject_key_info.algorithm_id.alg_id.char_id =
pCr->cri.subject_key_info.algorithm_id.alg_id.char_id;
pCert->tbs.subject_key_info.algorithm_id.params.ptr =
pCr->cri.subject_key_info.algorithm_id.params.ptr;
pCert->tbs.subject_key_info.algorithm_id.params.size =
pCr->cri.subject_key_info.algorithm_id.params.size;
pCert->tbs.subject_key_info.public_key.ptr =
pCr->cri.subject_key_info.public_key.ptr;
pCert->tbs.subject_key_info.public_key.size =
pCr->cri.subject_key_info.public_key.size;
// Set validity period for one year

time(&(pCert->tbs.validity.not_before));
pCert->tbs.validity.not_after = pCert->tbs.validity.not_before
+ 3600*24*365;
// For this example we will not use any extensions

pCert->tbs.extensions.extensions = NULL;
pCert->tbs.extensions.num_of_ext = 0;
// Logon to media
rc = C_Login(hSess,CKU_USER,NULL_PTR,0);
if (rc != CKR_OK) {
exit(0);
}
// Find the signing key
5-110
rc = GetKeyHandle(hSess,&hKey,pCert
->signature.sign_alg.alg_id.int_id);
if (rc != CKR_OK) {
exit(0);
}
// Encode and sign the certificate

encodedCrtLen = sizeof(encodedCrt); // Write over the CA cert
rc =
C_X509_EncodeSign(hSess,hKey,CK_X509_ID_CERT,pCert,decodedCrtLen,
encodedCrt,&encodedCrtLen);
encodedCrtLen = sizeof(encodedCrt) – encodedCrtLen;
/* Close crypto, not needed anymore

rc = C_Logout(hSess);
if (rc != CKR_OK) {
printf("*** Error in C_Logout – %x\n",rc);
exit(0);
}
// Prepare certs_and_crls structure for PKCS#7 cert reply

pCerts[0] = encodedCrt;
CertsLen[0] = encodedCrtLen;
CertList.certs = pCerts;
CertList.certLen = CertsLen;
CertList.numOfCerts = 1;
CertsAndCrls.certs = &CertList;
CertsAndCrls.crls = NULL_PTR;
// Encode crp
rc = C_PKCS7_CreateCRP(crpFormat,&CertsAndCrls,
encodedCrp,&encodedCrpLen);
if (rc != CKR_OK) {
printf("*** Error in C_PKCS7_CreateCRP – %x\n",rc);
exit(0);
}
5-111
// Save crp to file

f = fopen(outFile[crpFormat-1], "wb");
if (!f) {
printf("*** Error opening file %s for
output\n",outFile[crpFormat-1]);
exit(0);
}
fwrite(encodedCrp,1,encodedCrpLen,f);
fclose(f);
printf("Certificate reply saved to file

%s\n",outFile[crpFormat-1]);
return(0);
}
// Get a handle to the private key object

CK_RV GetKeyHandle( CK_SESSION_HANDLE hSession,
CK_OBJECT_HANDLE CK_PTR hKey,
int alg_id)
{
CK_RV rc;
CK_ULONG attribDSA = CKK_DSA;
{CKA_KEY_TYPE,&attribRSA,sizeof(attribRSA)},};
CK_ATTRIBUTE findDSAPrivateKey[] = {
{CKA_KEY_TYPE,&attribDSA,sizeof(attribDSA)},};
if ((alg_id == ASN1_OI_DSA) || (alg_id == ASN1_OI_SHA1_DSA))

rc = C_FindObjectsInit(hSession,findDSAPrivateKey,2);
else
if (rc != CKR_OK) {
return rc;
}
rc = C_FindObjects(hSession,hKey,1,&ulObjectsFound);
5-112
return rc;
}
if (rc != CKR_OK) {
return rc;
}
return CKR_OK;
}
The input parameters of this application are:

♦ CA_file – the name of the CA certificate file, which is used for
extracting the CA's Distinguished Name.
♦ crq_file – the name of the certificate request file.
♦ crq/p format – the format of the certificate request. The same format is
used for the certificate reply.
♦ SN – the serial number for the newly created certificate.
Other data needed for creating the certificate:

♦ Signature algorithm – same signature algorithm as the one used on the
CA certificate.
♦ Validity period – the application uses the PC clock to define the start of
the validity period, and adds one year to set the end of the validity
period.
♦ Subject Distinguished Name – copied from the certificate request.
♦ Subject key info – copied from the certificate request.
♦ Extensions – no extensions are used.
5-113
See the X.509 Toolkit section for more information about decoding of the CA
certificate, and encoding and signing of the End Entity certificate.
The program processes certificate requests and replies in three stages:

1. First, it reads the certificate request and the CA certificate from the input
files. Then, it opens a cryptographic session, and calls
C_PKCS10_AcceptCRQ for parsing and verifying the certificate request:
rc = C_PKCS10_AcceptCRQ(hSess,crqFormat,encodedCrq,
encodedCrqLen, decodedCrq,&decodedCrqLen);
The input parameters are:
♦ hSess – handle to cryptographic session.
♦ crqFormat – the format of the certificate request, as indicated by the
third program parameter.
♦ encodedCrq – the buffer into which the certificate request was loaded.
♦ encodedCrqLen – the length of the certificate request.
♦ decodedCrq – the buffer for the output pkcs10_cr structure.
♦ decodedCrqLen – the length of the decodedCrq buffer.
Note: This application does not check whether the certificate request actually
originated from the entity written in the Distinguished Name section of the
certificate request, nor whether this entity is approved to get a certificate from
this CA.
2. Then, the program parses the CA certificate and builds the End Entity's
certificate with the data described above. In this case the End Entity's
certificate is built directly on top of the CA certificate because it contains
many of the same fields. This changes the parsed version of the CA
certificate only, but does not affect either the encoded CA certificate, or
the original CA certificate from the disk.
3. Finally, it logs on to the key media and retrieves a handle to the CA's
private key for signing the End Entity's certificate. It calls the X.509
5-114
Toolkit function C_X509_EncodeSign to encode and sign the certificate.
The certificate is placed in a certs_and_crls structure which is used as a
parameter for C_PKCS7_CreateCRP:
rc = C_PKCS7_CreateCRP(crpFormat,&CertsAndCrls,
encodedCrp,&encodedCrpLen);
♦ crpFormat – same format as the certificate request.
♦ CertsAndCrls – a structure that includes the newly created End Entity
certificate.
♦ encodedCrp – buffer for the encoded certificate reply.
♦ encodedCrpLen – the size of the encodedCrp buffer.
The certificate reply is saved into a file that can be sent to the End Entity.
5-115
PKCS#12 Import and Export
The PKCS#12 Toolkit allows importing and exporting of keys and certificates,
which are stored in standard PKCS#12 files (PFX files). The toolkit provides
two simple functions. One for importing and the other for exporting keys and
certificates.
The PKCS#12 utility program pkcs12util.exe, which is part of the

CryptoKit installation, uses the PKCS#12 Toolkit to import and export PFX
files. The code of this utility, which demonstrates how to use the PKCS#12
ToolKit functions is included in the CryptoKit SDK.
Functions
This section describes the functions contained in the CryptoKit PKCS#12

Toolkit, as defined in the ckpkcs12.h file. Some of the constants and data
types, which are used, are defined in the standard pkcs11.h header file.
ImportPKCS12
This function imports a private key and certificate from a standard PKCS#12
file.
Syntax
CK_RV ImportPKCS12(
char * pfxfile,
char * password,
char errmsg[128]);
Parameters
5-116
♦ hSession [in] – handle to a cryptographic session with the token into
which the keys and certificate will be imported to. The user must be
already logged on.
♦ pfxfile [in] – the name of the PKCS#12 file with the keys and certificates
to be imported..
♦ password [in] – password of the PKCS#12 file.
♦ errMsg [out] – buffer to which a message will be copied upon
completion of the function.
Return codes
CKR_GENERAL_ERROR – open or read file operation failed
CKR_MECHANISM_INVALID – unsupported mechanism is needed to
import the file.
ExportPKCS12
This function exports a private key and certificate from the token into a standard
PKCS#12 file. The private key must be extractable.
Syntax
CK_RV ExportPKCS12(
CK_OBJECT_HANDLE hPrivKey,
char * outfile,
char * password,
CK_MECHANISM_TYPE mech,
char errmsg[128]);
Parameters
5-117
♦ hSession [in] – handle to a cryptographic session with the token, from

which the keys and certificate will be exported to. The user must be
already logged on.
♦ hPrivKey [in] – handle to the private key object to be exported. If a
certificate with the same CKA_ID exists on the token it will be included
in the exported PKCS#12 file.
♦ outfile [in] – name of the PKCS#12 file into which the exported objects
will be saved.
♦ password [in] – password of the PKCS#12 file.
♦ mech [in] – PKCS#11 mechanism type, which will be used to encrypt
the private key inside the PKCS#12 file. This mechanism is used to
unwrap the key. The valid values are: CKM_RC2_CBC_PAD or
CKM_DES3_CBC_PAD.
♦ errMsg [out] – buffer to which a message will be copied upon
completion of the function.
Return codes
CKR_OK – function was completed successfully
CKR_GENERAL_ERROR – open or write file operation failed
5-118
Chapter 6: SmartAdaptor Utilities
This chapter describes the utilities available with SmartAdaptor to manage
tokens: format, change PIN, view contents, import and export keys and
certificates, prepare for use with other applications and more.
AR Genie Utility
The AR Genie utility application enables the user to perform routine operations
on tokens. The operations include password maintenance, token formatting,
default setting, token standardization and more.
The utility has two modes of operation:

♦ User mode, in which only a limited set of operations, is available. This is
the default mode of operation and it was designed specifically for the
simple user who needs to perform only basic token operations such as
changing the token password. This mode displays only the available slots
i.e. slots where the token is inserted.
♦ Administrator mode, in which an extended set of operations, can be
performed on the tokens. In this mode all slots installed are displayed.
The user can see the list of objects on each slot and view their contents.
To run in this mode enter the following command:
argenie /br
6-1
User Mode Token Operations
Following is a description of the different menu options and their uses.
Change Password
Use this option to change the user password (PIN) that protects the token. The
password should be changed periodically. In order to change the password, you
must present the current password.
Note: The initial password of AR tokens is "12345678" .It is recommended that

you change it before using the token.
Login
This option is used to login into the token. It can be used with the Single Sign
On (SSO) mechanism to set the password for a specific token. Then it is
possible to run an application that does not have any user interface but still be
6-2
SmartAdaptor Utilities 6
able to access the private keys that are stored on that token. Selection of this
option opens the PIN entry dialog box.
Format Token
Use this option to format the token and prepare it for work. This operation
erases all objects stored on a token (keys, certificates and data objects) and
should be performed only once. To format the token:
1. Select the token from the list.
2. Shut down any CryptoKit applications that may be running or using the
token.
3. Click Action menu and then select Format.
4. In the PIN entry dialog box, enter the new token password (minimum 6,
to maximum 54 alphanumeric characters) and confirm it.
5. Wait until the operation is finished. Now the token is initialized and
ready for operation.
Note: By initializing a token, you overwrite any information contained on the

device. Therefore, special care must be taken before performing this option.
Note: It is possible to hide this option by setting an entry in the registry. Please
refer to explanation about GenieFormat parameter in Chapter 7.
Set as Default Slot

Use this option to set the default slot to be used when more than one token is
available at one time with CAPI applications that do not have a user interface
but need to write data or generate keys. This option enables you to indicate the
token that data should be written on. To set the default slot:
1. Select the desired slot
2. Click Slot menu and then select Set as Default Slot.
6-3
Clear Default Slot

Use this option to clear the selection of a slot as default slot.
Standardize Token
AR CryptoKit supports the two most common cryptographic standards. One is
PKCS#11 (by RSA) and the second is CryptoAPI (by Microsoft). Most
applications use one of these standards. However, in some cases, applications
(such as Entrust) create keys using PKCS#11 standard in a way that AR
CryptoKit is unable to work with them in applications that use CryptoAPI.
Use this option to standardize the objects on the token in such a way that would
enable CryptoAPI applications to use the keys that were created via the
PKCS#11 standard without damaging the original keys and still enable these
keys to be used by their original applications.
refer to explanation about GenieStandardize utility in Chapter 7.
Administrative Token Operations
As mentioned above, AR Genie can run in administrator mode (by entering the
command: argenie /br). In that mode, you can perform different actions on
slots, tokens and objects.
Note: It is possible to disable this option by setting an entry in the registry.

Please refer to explanation about GenieDisableAdmin parameter in Chapter 7.
Slot Menu
The Slot menu includes operations that can be performed on PKCS#11 slots,
such as: Get Information, Refresh List, Bind, Unbind, Set Default Slot an Clear
Default Slot.
The options in the Slot menu that are available only in administrator mode are:
6-4
Viewing List of Slots
In administrator mode all the slots that are installed are displayed. Non-inserted
slots are insensitive.
Slot Information
To view the slot information:
1. Select the desired slot.
2. Click Slot menu and then select Get Information.
6-5
The window displays the slot information as returned by the PKCS#11

C_GetSlotInfo function. For specific explanation about the parameters
displayed please refer to the PKCS#11 standard.
Refresh List
This option will refresh the displayed list.
Bind
This option allows the user to dynamically bind to a software token file. This
option is displayed in the menu only if CryptoKit was installed with software
token feature. To bind to a software token:
1. Click Slot menu and then select Bind option.
2. Browse your computer and select a CryptoKit software token file.
Usually, these files will have the *.sft extension.
3. If there is an empty dynamic slot that the file can be bound to and the file
is valid software token then it will be bound to an empty software slot.
The slot will appear as if a token was inserted.
6-6
Unbind
This option allows the user to unbind a dynamic software slot. This option is
displayed in the menu only if CryptoKit was installed with software token
feature. To unbind to a software token:
1. Select the software slot that was previously bound.
2. Click Slot menu and then select Unbind option.
3. The slot should appear as if the token was removed.
Token Menu
The Token menu includes operations that can be performed on the available
tokens, such as: Get Information, Change User and SO PIN, View Objects,
Login, Standardize, Format, Change Label, Dump and Import Key.
The options in the Token menu that are available only in administrator mode
are:
Token Information
To view the token information:
1. Select the slot where the token is inserted.
2. Click Token menu and then select Get Information.
6-7
The window displays the token information as returned by the PKCS#11

C_GetTokenInfo function. For specific explanation about the parameters
displayed please refer to the PKCS#11 standard.
Change SO Password
Use this option to change the SO password (PIN) that protects the token. In
order to change the password, you must present the current password.
6-8
Note: The initial SO password of AR tokens is "11111111" and we recommend

that you change it before using the token.
Change Label
Using this option you can change the token label:
1. Select the token you want to change its label.
2. Click Token menu and then select Change Label.
3. If you are not logged in, the PIN entry dialog will be displayed.
4. Enter the new token label in the Set Token Label dialog.
CryptoKit provides two additional methods to change the token label.

♦ Execute the Change Label command by running AR Genie utility from
the command prompt. For more information refer to the next section.
♦ Call CryptoKit’s extension API function C_EXT_ChangeTokenLabel
from your application. For more information refer to Chapter 3.
Dump
Use this option to print the whole token contents into a text file:
6-9
1. Select the token you want to dump its contents.

2. Click Token menu and then select Dump.
3. Enter the name and location of the text file that will be created.
4. If you are logged in, the file will contain both public and private objects
information. If you are not logged in, you will be asked whether you
want to login or not. If you select not to login, the file will contain only
the public objects information.
Note: You can dump the contents of a specific object from the Objects window.
Import Key
Use this option to import a PKCS#12 file (*.pfx, *.p12) into the token. These
files are used to transfer private, public and certificate objects from one token to
another. The PFX file may be protected by a password. To import a PFX file
contents into the token do the following:
1. Select the token you want to import the PFX file to.
2. Click Token menu and then select Import Key.
3. Enter the name and location of a valid PKCS#12 file (*.pfx or *.p12) or
click Browse button to search for the file to import.
4. Enter the password that protects the PFX file. You may leave the
password empty if the PFX file is not protected by password.
5. Click OK to import the file.
6. If you are not logged in, you will be requested to enter the token PIN.
7. The file contents will be imported into the token. You can view the new
objects in the Objects window.
Note: You can import PFX files also by using the PKCS#12 import/export
utility as explained later in this chapter.
6-10
View Objects
Use this option to view the objects that are stored on the token: data objects,
keys and certificates. Use the Login option to login into the token and to view
the private objects as well. Press the title of the table to sort the objects by:
Type, Label, Size, Private/Public or their ID. Double click an object to view its
details. Right click an object or click Object in the menu to perform additional
operations on the selected object.
6-11
View Object Attributes

For each object type there is an additional window that presets its attributes. To
view the object attributes:
1. Open the object list window.
2. Select the object you want to view from the list.
3. Click Object menu and then select View, right-click the object and
select View from the pull down menu or simply double click the object.
6-12
The following window shows the details of RSA public key object. Please refer
to the PKCS#11 standard for specific explanation about the meaning of the
parameters displayed in this window.
6-13
When viewing a data object, you can see its contents in binary or hex format.
You can copy the value of the object into the clipboard.
Similar windows are displayed also for private RSA keys and secret keys.
6-14
When a certificate object is selected, the following window is displayed:
6-15
Click the View certificate button to view the contents of the certificate:
6-16
Refresh List
This option will refresh the displayed list of objects.
Dump Object
Use this option to print the object content into a text file:
1. Select the object you want to dump its contents.
2. Click Object menu and then select Dump or right-click the object and
select Dump from the pull down menu.
3. Enter the name and location of the text file that will be created and then
click Save button.
4. The object contents and attributes will be written into the file.
Export Object
Use this option to export private and public RSA keys and their corresponding
certificate into a PKCS#12 file (*.pfx). You must be logged in for this option to
be available. The operation will fail if the RSA private key is not extractable.
To export a PFX file do the following:
1. Select an RSA public or private key object that you want to export into a
PFX file.
2. Click Object menu and then select Export or right-click the object and
select Export from the pull down menu.
3. The Export Key File dialog will open.
4. Enter the name and location of the PFX file that will be created or click
Browse button.
5. Enter the password that will protect the PFX file
6. From the Encryption Mechanism list, select the algorithm that will be
used to encrypt the objects inside the PFX file: RC2 or 3DES.
6-17
7. Click OK button to export the objects.
Note: You can export PFX files also by using the PKCS#12 import/export utility
as explained later in this chapter.
Delete Object
To delete an object, which is stored on the token:
1. Open the object list window.
2. Select the object you want to delete.
3. Click Object menu and then select Delete or right-click the object and
select Delete from the pull down menu.
refer to explanation about GenieDeleteMode parameter in Chapter 7.
6-18
Running AR Genie From Command Line
All operations that AR Genie provides are available from the command line,
without any user interface.
Note: The parameters are not case sensitive. Parameters in [ ] are optional. If
a parameter is omitted a default value will be used or an appropriate dialog
box will appear. The default slotId is 1.
Following is a list of the commands and their parameters.
Usage
Display the list of all available command line parameters.
Syntax:
ARgenie /?
User Mode
Run AR Genie in user mode.
Syntax:
ARgenie
Administrator Mode
Run AR Genie in administrator mode.
Syntax:
ARgenie /BR
Format
Format the token and set the user PIN.
6-19
Syntax:
ARgenie /cmd=Format [/slotId=XX] [/label="abc"]
[/oldSOPin="abc"] [/newPin="abc"]
Parameters:
slotId – The number of the slot to format. If omitted, the default is slot 1.
label – The label of the token. If omitted, the label will be CryptoKit’s
default.
oldSOPin – The SO PIN, which is needed to format the token. If omitted, the
default "11111111" is used. If the default PIN fails, the PIN entry dialog box
will open, requesting the user to enter the SO PIN.
newPin – The new user PIN. If omitted, the default is "12345678".
Change User PIN

Change the user PIN.
Syntax:
ARgenie /cmd=ChangePIN [/slotId=XX] [/oldPin="abc"]
[/newPin="abc"]
Parameters:
slotId – The number of the slot you want to change the user PIN. If omitted,
the default is slot 1.
oldPin – The current user PIN. If omitted, then the user will be prompted to
login and then to change the PIN. Two dialogs will be displayed: the first is the
login dialog and then the change PIN dialog.
newPin – The new user PIN. If omitted, and oldPin is also omitted then the
user will be prompted to login and then to change the PIN. If omitted and
oldPin is not empty, the operation will fail.
Change SO PIN
Change the SO PIN.
Syntax:
ARgenie /cmd=ChangePIN [/slotId=XX] [/oldSOPin="abc"]
[/newSOPin="abc"]
6-20
Parameters:
slotId – The number of the slot you want to change the user PIN. If omitted,
oldSOPin – The current SO PIN. If omitted, then the user will be prompted to
login and then to change the SO PIN. Two dialogs will be displayed: the first is
the login dialog and then the change PIN dialog.
newSOPin – The new SO PIN. If omitted, and oldSOPin is also omitted then
the user will be prompted to login and then to change the SO PIN. If omitted
and oldSOPin is not empty, the operation will fail.
Change Label
Change the token label.
Syntax:
ARgenie /cmd=ChangeLabel /label="abc" [/slotId=XX]
[/oldPin="abc"]
Parameters:
label – The new label of the token. If omitted, the current token label will not
be changed.
slotId – The number of the slot you want to change its label. If omitted, the
default is slot 1.
oldPin – The current user PIN. If omitted the PIN dialog will be displayed.
Set Default Slot

Set as default CAPI slot.
Syntax:
ARgenie /cmd=SetDefaultSlot [/slotId=XX]
Parameters:
slotId – The number of the slot you want to be the default slot number for
CAPI applications. If omitted, the default is slot 1.
6-21
Clear Default Slot

Clear the default CAPI slot.
Syntax:
ARgenie /cmd=ClearDefaultSlot
Dump
Dump token contents into a text file.
Syntax:
ARgenie /cmd=Dump [/slotId=XX] [/filename="abc"]
[/oldPin="abc"]
Parameters:
slotId – The number of the slot you want to dump its contents. If omitted,
filename – The output filename. If omitted it will be "DumpToken.txt".
Import
Import objects from a PKCS#12 (*.pfx, *.p12) file into the token.
Syntax:
ARgenie /cmd=Import /filename="abc" [/slotId=XX]
[/oldPin="abc"] [/filePin="abc"]
Parameters:
filename – The name of the PFX file you want to import
slotId – The number of the slot you want to import to. If omitted, the default
is slot 1.
filePin – The PFX file password. May be omitted if the PFX is not protected
by a password.
6-22
Standardize
Standardize the token.
Syntax:
ARgenie /cmd=Standardize [/slotId=XX] [/oldPin="abc"]
Parameters:
slotId – The number of the slot you want to standardize. If omitted, the
default is slot 1.
6-23
PKCS#12 Import/Export Utility
The pkcs12util.exe program is a command line utility that can be used to

import and export keys and certificates, which are stored in a PKCS#12 PFX
file. It can be used to easily transfer objects from one token to another.
Import Operation
To import objects contained in a PKCS#12 file into a token, run the utility with
the following command line parameters:
pkcs12util -i f=filename p=password <s=slot>

♦ -i – import keys and certificates stored in a PFX file into a token.
♦ filename – the name of the PFX file to be imported.
♦ password – the password that protects the PFX file.
♦ slot – the slot number of the token. The default is the first slot with token
inserted.
Export Operation
To export objects contained in a token into a PKCS#12 PFX file, run the utility
with the following command line parameters:
pkcs12util -e p=password <f=filename> <i=id>

<l=label> <s=slot> <a=3des>
♦ -e – export keys and certificates stored in a token into a PFX file.
♦ password – the password that will protect the PFX file.
6-24
♦ filename – the name of PFX file to be created. If not specified, the
default output file name is out.pfx.
♦ id – the id of the key and certificate to export. The default is the first key
found on the token.
♦ label – the label of the key and certificate to export. The default is the
first key found on the token.
♦ slot – the slot number of the token. The default is the first slot with token
inserted.
♦ 3des – the algorithm that will be used to encrypt the objects inside the
PFX file. The default is RC2. If this parameter is specified, 3DES is
used.
6-25
DlmLoad Utility
The DlmLoad.exe utility program is a command line utility that can be used
to load DLMs into the PrivateSafe reader. A DLM is a special program that is
loaded into the reader and provides additional functionality.
CryptoKit installs this utility when the PrivateSafe reader feature is selected.
After the driver is installed the user has to reboot the machine and then the
DlmLoad utility is automatically executed to install the latest DLM into the
PrivateSafe reader. When this utility is loading a DLM into the reader, the user
keyboard is disabled because the PrivateSafe is connected to the keyboard.
The utility can also be used to view which version of DLM is loaded and it can
erase the loaded DLM. The command line parameters of this utility are:
Usage
Display the list of all available command line parameters.
Syntax:
Dlmload /?
Status
Display the PrivateSafe version and DLM version.
Syntax:
Dlmload
Description:
Running the utility without any parameter will display a message box:
6-26
The PrivateSafe version may be 2.5 or 2.6.
Load DLM
Load a DLM file into the PrivateSafe reader. You can specify up to three DLM
files. Only DLMs that match the PrivateSafe reader you have will be loaded.
Syntax:
Dlmload DlmFile1 [DlmFile2] [DlmFile3] [/Replace] [/Silent]
Parameters:
DlmFile1 – The name of the DLM file you want to load
DlmFile2 – Optional additional DLM file to load
DlmFile3 – Optional additional DLM file to load
Replace – By default the utility will replace an existing DLM only if the new
one has a higher version number. Use this flag if you want to suppress the
version check and force DLM load.
Silent – Use this parameter to disable any dialog box during the execution
of this utility.
Kill DLM
Delete the existing DLM from the PrivateSafe reader.
Syntax:
Dlmload /Kill
Note: Some applications will not function correctly if no DLM is loaded in the
PrivateSafe reader. Use this option with care.
6-27
Chapter 7: Installation
The following chapter describes different aspects of CryptoKit installation. It

explains:
♦ How to install CryptoKit and all its components
♦ How to modify an existing installation, upgrade to a newer version or
uninstall CryptoKit
♦ How to create and run a silent installation
♦ How to centrally install CryptoKit using active directory group policy
mechanism or Microsoft 2003 SMS server
♦ How to install CryptoKit in Citrix and Terminal Server environments
♦ How to customize the installation
♦ How each component of CryptoKit is installed: files, registry entries, and
additional logic.
Installation Packages
CryptoKit installation package is an InstallShield based setup program. The

installation program is using the high capabilities of InstallShield scripting
language as well as Microsoft’s installer technology (MSI), which is part of
Windows operating system. There are two types of installation packages:
♦ Extended – includes all CryptoKit components and SDK files.
♦ Runtime – includes all components except the SDK.
7-1
Installation From CD
To install CryptoKit, simply insert the installation CD. CryptoKit has an
AUTORUN option, which runs the setup automatically. If this option is disabled
on the user’s computer, run the setup program (setup.exe) from the root
directory of the installation CD.
Important Note: In order to be able to install CryptoKit, you must have
administrator rights.
Installing On a Clean Machine

In the Welcome screen, click the Next button.
7-2
Installation 7
In the License Agreement screen, click I accept the license agreement and then
click the Next button.
7-3
In the Destination directory screen, enter the installation directory and then click
the Next button. You can change the default folder by entering a different
directory name in the Destination Folder edit box or by clicking the Browse
button and selecting an existing directory.
7-4
Installation 7
In the Features tree screen, select the features you want to install, and then click
the Next button.
In the confirmation screen, click Yes button to start the CryptoKit installation.
7-5
When the installation is complete, the Finish screen will appear. Click the
Finish button to exit the installation program and if requested, reboot the
machine.
The CryptoKit installation requires reboot only in cases when it is needed for
example, when installing hardware drivers that need reboot to operate or when
the installation needs to replace a file, which is currently locked. If no reboot is
required, the Finish screen will allow you to exit the installation program and
immediately start working with CryptoKit.
Note: When the Netscape plug-in is selected, the setup program runs the
Netscape Navigator with an installation applet.
7-6
Installation 7
Modifying or Removing an Existing Installation
It is possible to add or remove any CryptoKit component from an existing

installation by running the setup program again. You can either:
• Enter the control panel, Add/remove programs and select CryptoKit
• Select Add Remove CryptoKit components from the CryptoKit
Menu.
• Insert the CryptoKit installation CD and wait for the installation to
start.
In any case, the following window is displayed:
7-7
Select the Modify option to add or remove components. Select Repair to

reinstall again the currently selected components. Select Remove to uninstall
CryptoKit.
Note: I f you do not want to allow users to modify or repair the installation, you
can hide this window by setting the parameter showMaint to FALSE. In this
case, the user will be prompted to confirm uninstalling CryptoKit. For more
information, please refer to explanation how to customize the installation, later
in this chapter.
Upgrading an Existing Installation
The CryptoKit installation is designed to automatically upgrade from older

versions. When you run the setup program on a computer with an older version
of CryptoKit installed, an automatic upgrade is performed and all the currently
installed features are upgraded.
Press Yes to confirm CryptoKit upgrade.
Note: Due to changes in the installation program, this feature is supported only
when upgrading from version 3.5.x. When upgrading from older versions, such
as 3.2 and 3.4, you must first uninstall the old version.
7-8
Installation 7
In the Welcome screen, click the Next button to upgrade existing installed
features to the newer version of CryptoKit.
Silent Installation
CryptoKit can be installed in unattended and silent mode. This means that no
user interaction is needed and no indication of the progress of installation is
displayed. This feature is supported by the InstallShield program, which is used
to install CryptoKit.
7-9
In order to create a silent installation you need to perform the following steps:
• On a test system, run the installation in record mode, which generates a

response file.
• On an end user's system, run the installation in silent mode, using the
data in the response file in place of user input.
To generate the response file, you have to run the setup.exe with the /r switch.
This displays the installer's dialog boxes, and additionally records the data you
enter in the dialog boxes in a text response file. By default, the response file is
generated in the Windows folder and is called setup.iss. The response file
uses the .iss (for "InstallShield silent") file name extension. However, you can
specify an alternative file name and location, with the /f1 argument. For
example:
setup /r /f1"C:\sample\install.iss"
Note: there is no space between /f1 and the quoted path to the response file to
create.
To deploy CryptoKit silently, based on the response file, you need to copy the
response file to the CryptoKit installation package and run silent installation
with the /s switch. Again, using the /f1 switch you can specify the name and
location of the response file to be used. For example:
setup /s /f1"C:\sample\install.iss"
Note: When silent installation is used, no dialog box appears to the end user,
even the reboot confirmation dialog. If reboot is needed after installation, and
you selected to reboot the computer when recording the response file, then
reboot will be executed automatically on the client machine. You can either
select to reboot later or run the silent installation when no user is logged on as
explained in the next section.
7-10
Installation 7
Centralized Installation from Active Directory
CryptoKit installation package is an InstallShield based setup program. Since the

installation is very complex it uses the high capabilities of InstallShield scripting
language. Even though the package contains an MSI file, this file cannot be
assigned to install the software through active directory group policy
mechanism, as you would assign a basic MSI package.
However, it is possible to install CryptoKit by assigning a startup script to a

group policy object. The startup script is executed when a machine that belongs
to the group policy object is rebooted. The script is run with administrator
privileges.
To use group policies to centrally install CryptoKit, you need to perform three
steps:
1. Create CryptoKit installation package on the server
2. Create the startup script
3. Assign the startup script
Following is a detailed explanation of each step:
Step 1 – Create CryptoKit Installation Package on the Server
The first step will be to create a silent CryptoKit installation with the features
you want to install in your network:
♦ Copy the CryptoKit installation package files to a clean machine.
♦ Modify the CK_SETUP.INI file and customize the installation

according to your needs. Modify the [ComponentSelect] section to
select or deselect the CryptoKit features you want to install. Modify the
[General] section to disable the user dialogs by setting to FALSE the
parameters: ShowWelcome, ShowDestPath and ShowTree.
7-11
♦ Prepare an InstallShield response file for silent installation (as explained

in previous section), by entering the command.
setup /r /f1"c:\install.iss"
♦ Now, create a new directory on the server and share it. Grant this
directory with read access permissions to all domain users.
♦ Copy the CryptoKit installation package files and the InstallShield
response file to the shared directory.
Step 2 – Create the Startup Script
The following VBscript sample copies the installation files from the server into
a temporary directory on the client machine. Then it runs a silent installation.
The script file has to be saved with .vbs extension.
Note: You need to change the variable strSourceDir to the name of the
shared directory, where the CryptoKit setup files are located.
'===============================================================
' Script Name: CryptoKit.vbs
'
' Install CryptoKit from active directory or Microsoft SMS server
'===============================================================
'---------------------------------------------------------------
' Variables declaration
'---------------------------------------------------------------
Dim objFileSystem, objShell, objProvEnv
Dim strTmpDir, strRegistry, strSourceDir, strDestDir
'---------------------------------------------------------------
' !!! Change strSourceDir to the name of a shared directory !!!
' !!! where the CryptoKit setup files are located !!!
'---------------------------------------------------------------
strSourceDir = "\\Server_Name\Share_Name"
'---------------------------------------------------------------
' Initialize Variables
'---------------------------------------------------------------
7-12
Installation 7
On Error Resume Next
Set objShell = CreateObject("Wscript.Shell")
Set objFileSystem = CreateObject("Scripting.FileSystemObject")
Set objProvEnv = objShell.Environment("Process")
'---------------------------------------------------------------
' Read from registry and quit if CryptoKit is already installed
'---------------------------------------------------------------
strRegistry =
objShell.RegRead("HKLM\Software\ARL\SmartAdaptor\Main\CkitDir")
If Err.number = vbEmpty and strRegistry <> "" then
Wscript.Quit
End If
'---------------------------------------------------------------
' Find TEMP directory on local computer
'---------------------------------------------------------------
strTmpDir = objProvEnv("TEMP")
If strTmpDir <> "" And objFileSystem.FolderExists(strTmpDir)Then
strDestDir = strTmpDir
Else
strDestDir = "C:\Temp"
End If
If Right(strDestDir, 1) <> "\" then

strDestDir = strDestDir & "\"
End If
strDestDir = strDestDir & "CryptoKit"
'---------------------------------------------------------------
' Copy installation files to local computer and run silent setup
'---------------------------------------------------------------
objFileSystem.CopyFolder strSourceDir, strDestDir, True
objShell.run strDestDir & "\setup.exe /s /f1""" & strdestDir &

"\install.iss""", 1, True
WSCript.Quit
The script can be used not only to install CryptoKit on a clean machine, but it
can be easily changed to handle CryptoKit upgrade. The CryptoKit installation
7-13
program automatically handles upgrade from an older version so you need to

record an appropriate response file for upgrade situation. The script can check in
the registry which version of CryptoKit is installed and then run the installation
with the upgrade response file.
The script runs with administrator privileges and is executed as if the

administrator visited the client machine, logged in and then launched the setup
locally. If a specific station needs additional CryptoKit components, the
administrator can easily run the setup locally from the control panel and modify
the installation.
Step 3 – Assign the Startup Script
The final step is to assign the startup script to a group of computers in the
domain:
♦ From a Windows 2000-based computer in the domain, log on as a
domain administrator, and start the Active Directory Users and
Computers snap-in.
♦ Click the container you want to have the Group Policy Object (GPO)
linked to. Right-click that container, click Properties, and then click the
Group Policy tab.
7-14
Installation 7
♦ Create a new GPO for installing the CryptoKit package, and give it a
descriptive name.
♦ While the GPO is selected, click Edit to start the Group Policy snap-in
and edit this GPO.
7-15
♦ Click Computer Configuration, Administrative Templates, System,

Logon.
♦ Change the parameter Run startup scripts asynchronously to Enable.
7-16
Installation 7
♦ Click Computer Configuration, Windows Setting, Scripts
(Startup/Shutdown)
7-17
♦ Right click Startup in the right pane and select Properties.
♦ Click Show Files to open the default folder where startup scripts
assigned to this GPO are stored on your domain controller. The startup
scripts are stored in a subfolder of the SYSVOL share on the domain
controller, which is named:
\SYSVOL\<domain_DNS_name>\Policies\<policy_GUID>\
MACHINE\scripts\Startup
The contents of this folder are automatically replicated to all domain
controllers in the domain.
7-18
Installation 7
♦ Using Windows Explorer copy into this folder the startup VBscript script
that was created in the previous step.
♦ Close the folder window and return to the Logon Properties screen and
click Add button to open the Add a Script dialog box.
♦ In the Script Name field, type the name of the startup script file you
want to assign and press OK.
♦ In the Logon Properties dialog press the Apply button or press OK
button twice to assign the new startup script.
7-19
The startup script will be executed when the machines in the container will
reboot.
Centralized Installation Using Microsoft SMS 2003 Server
It is possible to install CryptoKit from Microsoft SMS 2003 Server. The steps
are very similar to installation from active directory. However, the assignment to
groups of computers has to be done in a different way.
To use Microsoft SMS 2003 Server to centrally install CryptoKit, you need to
perform three steps:
1. Create CryptoKit installation package on the server
2. Create the startup script
3. Assign CryptoKit package to SMS collection
The first two steps are exactly the same as when centrally installing CryptoKit
using active directory group policies mechanism. Please refer to the previous
section for a detailed explanation. The third step however, has to be done from
the SMS Management console.
Step 3 – Assign CryptoKit Package to SMS Collection
The following section assumes that you have an SMS 2003 server working in
your network environment and that you have some minimal knowledge in using
this software. It assumes that you are familiar with the basic concepts of SMS
server such as collections, packages, advertisements etc. This section shows only
the minimal operations you have to do in order to install CryptoKit using SMS
2003 server. You may need to modify other SMS parameters according to your
needs, for example: creating collections or changing the schedule of the
installation and more.
7-20
Installation 7
For more information about using SMS 2003 server, please refer to Microsoft’s
documentation and manuals.
To install CryptoKit, run the SMS Management console and perform the
following operations:
♦ Right click Packages and select New | Package
♦ In the Package Properties dialog, enter package Name, Version and

Publisher. Press the Apply button to create the package.
♦ Expand the new package to view its Access Accounts, Distribution
Points and Programs.
♦ Right click the Distribution Points and select New | Distribution
Points.
7-21
♦ In the New Distribution Points Wizard, select the checkbox next to the
distribution point and click Finish.
♦ Right click Programs and select New | Program.

♦ In the General tab of the Program Properties dialog, enter "CryptoKit"
in the name of program. In the Command line enter the path to VBscript
that installs CryptoKit which should be in the shared directory with all
other installation files:
wscript \\Server\Share\Cryptokit.vbs
7-22
Installation 7
♦ In the Environment tab, allow program to run Whether or not a user is

logged on.
7-23
♦ Right click Advertisments, and select New | Advertisment.
♦ In the General tab of the Advertisement Properties dialog, enter the

Name of the advertisement, in the Package select the newly created
package, in the Program select the newly created program and in the
7-24
Installation 7
Collection click Browse and select a collection of computers you want
to install to.
♦ For testing purposes click the button in the Schedule tab, and assign
the advertisement As soon as possible and click Apply.
♦ The advertisement should now be active and will begin pushing the
CryptoKit package to the systems in the collection. You can view the
advertisement status in the System Status, Advertisement Status
screen.
7-25
Installation in Citrix Environment
CryptoKit supports both Citrix MetaFrame XP Server and Citrix

Presentation Server 3 that are installed on Windows 2000 server or windows
2003 server.
CryptoKit enables you to use smart card authentication to the server and then
use the smart card with other applications that run on the Citrix server. You can
work with both CAPI and PKCS#11 applications. Moreover, you can install
CryptoKit on the client machine as well and then access it from applications that
run on the server and on the client at the same time.
To work in this environment you need to install and configure both the server
and the client machines.
The following explanation assumes that you already have a working Citrix
environment and that you want to add to it smart card support.
Citrix Server Configuration
Perform the following on a Windows 2000 or Windows 2003 server running

Citrix MetaFrame XP Server or Citrix Presentation Server 3:
♦ Login as administrator and copy the CryptoKit installation package from
the CD to the server.
♦ If you want to use a standard PC/SC reader then install the drivers of the
reader on the server.
♦ If you want to use Algorithmic Research MiniKey5 then you need to
install only one virtual driver. Edit the SETUP.INI file in the CryptoKit
installation package and change the setup command line to:
CmdLine=ZZN_READER="1"
7-26
Installation 7
♦ Open Control Panel, Add Remove Software and click the Install
Software from CD button.
♦ Run Setup.exe from the CryptoKit installation package.
♦ The CryptoKit installation program should automatically detect it is
being installed on a Citrix server and display the Citrix feature in the
features tree screen. Select the features: Citrix, CAPI, Logon and
optionally the MiniKey5.
Note: The terminal Server feature is automatically selected when the Citrix
feature is selected.
♦ Complete the installation and then reboot the server.
♦ Load the root CA certificate into the local machine store of the server.
♦ Use the Citrix SCCONFIG.EXE utility to register any additional
applications that run on the server and need access the smart card on the
client's computer. The utility has to be run from the command line. For
example, to register Microsoft Internet Explorer enter the command:
SCCONFIG /ENABLE_PROCESS:iexplore.exe /FARM
To view the list of registered applications, enter the command:
SCCONFIG /QUERY
The CryptoKit installation automatically registers: Arcltsrv.exe,

Ardaemon.exe, Argenie.exe and the utility program PHL.exe.
♦ If you use the Citrix Web client or want to work with other CAPI
applications then you would need to register: iexplore.exe,
rundll32.exe and explorer.exe.
For more information about the SCCONFIG.EXE utility, please refer to

the Citrix documentation.
Note: You can use smart card to logon to the Citrix server. However, you should
not lock the machine if the smart card is removed. Defining this policy will
7-27
cause clients that are connected to the server to be disconnected when the user
removes his smart card.
Citrix Client Configuration
The Citrix client machine can be configured with or without local smart card
logon. In each case you may want to work with a standard PC/SC reader or with
MiniKey5 USB token. For each one of these cases there is a slightly different
installation procedure.
Perform the following on a Citrix client machine:

♦ If you want to use a standard PC/SC reader then connect it to the client
machine and install the drivers of the reader.
♦ If you want to use Algorithmic Research MiniKey5 then you need to
install only one virtual driver. Edit the SETUP.INI file in the CryptoKit
installation package and change the setup command line to:
CmdLine=ZZN_READER="1"
Note: If you install more than one MiniKey5 device then the
Citrix client will fail to initialize and you will get an error
message: "ICA Client Error 1043: Invalid Parameter"
immediately after it is opened.
♦ If you want the client to perform smart card logon locally then you need
to install CryptoKit and select CAPI and Logon features in the features
tree screen. If you want to use MiniKey5 for smart card logon, then you
need to install also the MiniKey5 drivers by selecting this feature too.
♦ If you want to use MiniKey5 without smart card logon on the client
machine, then you need to install only the MiniKey5 drivers. Install
CryptoKit and select only MiinKey5 feature in the features tree screen.
7-28
Installation 7
♦ To configure the ICA client to use smart cards, right click the Citrix
client icon and select Properties.
7-29
♦ In the Logon Information, select Smart Card and click OK.
♦ Open the ICA client and then insert the smart card with appropriate
public, private and certificate. Enter the PIN and login to the Citrix
server.
7-30
Installation 7
Installation in Terminal Server Environment
CryptoKit can be installed in a terminal server environment. The terminal server

can be a Windows 2003 Terminal server or Windows XP. The client can be a
Windows 2K or Windows XP running Microsoft’s Remote Desktop
Connection application.
CryptoKit enables the client machine to perform smart card authentication to the
server and then to use the smart card with other CAPI and PKCS#11
applications that run on the server. Moreover, you can install CryptoKit on the
client machine as well, and then access the smart card from applications that run
on the server and on the client machine at the same time.
To work in this environment you need to install and configure both the server
and the client machines.
The following explanation assumes that you already have a working terminal
server environment and that you want to add to it smart card support.
Terminal Server Configuration
Perform the following on a Windows 2003 server or Windows XP with terminal

services installed and enabled:
♦ Login as administrator and copy the CryptoKit installation package from
the CD to the server.
♦ If you want to use a standard PC/SC reader then install the drivers of the
reader on the server.
♦ Open Control Panel, Add Remove Software and click the Install
Software from CD button.
♦ Run Setup.exe from the CryptoKit installation package.
7-31
♦ The CryptoKit installation program should automatically detect it is

being installed on a terminal server machine and display the Terminal
Services feature in the features tree screen. Select the features: CAPI,
Terminal Services and Logon. If you want to use Algorithmic Research
MiniKey5 then select the MiniKey5 feature too.
♦ Complete the installation and then reboot the server.
♦ Load the root CA certificate into the local machine store of the server.
Client Configuration
The client machine connects to the server using Microsoft’s Remote Desktop
Connection application. This application is part of the Windows XP operating
system. On windows 2000 machines, it has to be separately installed.
The client machine can be configured with or without local smart card logon. In
each case you may want to work with a standard PC/SC reader or with
MiniKey5 USB token. For each one of these cases there is a slightly different
installation procedure.
Perform the following on the client machine:

♦ If you want to use a standard PC/SC reader then connect it to the client
machine and install the drivers of the reader.
7-32
Installation 7
♦ Now, depending on the configuration, the token you want to use and the
operating system, you need to install different CryptoKit features on the
client machine:
No smart card logon is Smart card logon to

required to client machine client machine also is
required
Use AR PrivateCard If the client is running Install CryptoKit with:
and a standard PC/SC Windows 2000 then install CAPI and Logon
reader CryptoKit with no feature features selected.
selected (*).
If the client is running

Windows XP, no installation
is required.
Use AR MiniKey5 USB Install CryptoKit with Install CryptoKit with:

token MiniKey5 feature selected. CAPI, Logon and
MiniKey5 features
selected.
* Actually, only two registry entries are needed in this case. Those entries
are placed in:
HKEY_LOCAL_MACHINE\Software\Microsoft\
Cryptography\Calais\SmartCards\PrivateCard
and
Cryptography\Calais\SmartCards\PrivateCardEx
For more information about the values in these entries see later in this
chapter.
7-33
♦ To connect to the terminal server run the Remote Desktop Connection

application.
♦ Insert the smart card and enter PIN to login to the server.
7-34
Installation 7
CryptoKit Installation Package
CryptoKit installation package is an InstallShield based setup program. The

installation program is using the high capabilities of InstallShield scripting
language as well as Microsoft’s installer technology (MSI), which is part of
Windows operating system.
The following section describes the files in the CryptoKit installation package.
File Name Description

Setup.exe Main setup program that activates the CryptoKit installation
instmsia.exe Microsoft installer program for Windows 98 and ME.

This file is automatically installed by setup.exe, if
msiexec.exe file is too old or missing.
instmsiw.exe Microsoft installer program for Windows NT, 2000 and XP.
This file is automatically installed by setup.exe, if
msiexec.exe file is too old or missing.
Note: The default version on Windows 2000 and XP platforms
is sufficient enough.
CK_SETUP.INI CryptoKit customization file. Read how to customize the setup

using this file, later in this chapter.
CK_LANG.INI A file that contains all the text that is displayed during the setup
process. This text can be translated to different languages. Read
how to customize the setup text using this file, later in this
chapter.
Setup.ini InstallShield INI file
Autorun.inf This file runs the installation program automatically when the
CD is inserted
License.txt CryptoKit license agreement file
7-35
File Name Description

Release.txt CryptoKit release notes file
CryptoKit.msi CryptoKit main installation file, with all the logic and
definitions
Note: This file cannot be assigned to computers in the domain

by using group policy software assignment. Please refer to
instructions about centralized installation in this chapter.
ISScript8.Msi InstallShield scripting language installation file. It is

automatically installed by setup.exe
0x0409.ini InstallShield internal file
Setup.bmp Image that is displayed in the background when the installation

is run from CD
*.cab Cab files that contain the files of the different CryptoKit
features. Each feature is contained in a different Cab file
7-36
Installation 7
Customizing the Installation
The CryptoKit installation program is very flexible and can be customized

according to the organization needs. It is possible to externally set different
parameters by modifying configuration files, which are part of the installation.
It is possible to customize the user interface by:

♦ Changing the language of the messages and dialog boxes.
♦ Selecting which dialog boxes will be presented to the user during
installation.
♦ Changing the images of the dialog boxes.
♦ Defining which features will be displayed in the features tree.
It is also possible to customize the logic of the installation by:

♦ Selecting which components will be selected and installed.
♦ Setting different default parameters.
♦ Adding files and registry entries to the installation.
♦ Executing external applications at the end of the installation or after
reboot.
The CK_SETUP.INI file, which is included in the CryptoKit installation has

several sections, each controls a different aspect of the installation.
7-37
String Constants
The following string constants can be used in different sections of

CK_SETUP.INI file:
Key Description
<TARGETDIR> or The full path of the directory where CryptoKit is installed
<INSTALLDIR>
<WINDIR> The full path of the Windows directory
<WINSYSDIR> The full path of the Windows System directory
<SRCDIR> The location of the setup program
<TARGETDISK> The disk on which CryptoKit is installed
<WINDISK> The disk with the Windows directory
<PROGRAMFILES> The full path to the Program Files folder
Feature Names
The following table lists the CryptoKit feature names. Some features are visible
by default in the feature tree window and some are hidden. Some features are
selected by default and some are not. Both defaults can be overidden by the
[Hidden] and [ComponentSelect] sections of the CK_SETUP.INI file.
Feature Name Description Visible Selected

Readers_And_Tokens CryptoKit’s core PKCS#11 (1)
provider
Readers_And_Tokens\Minikey MiniKey4 USB token
Readers_And_Tokens\Minikey5 MiniKey5 USB token
Readers_And_Tokens\PrivateSafe PrivateSafe reader
7-38
Installation 7
Readers_And_Tokens\PrivateSafe_ PrivateSafe PCMCIA reader
PCMCIA
Readers_And_Tokens\Software Software token
Readers_And_Tokens\Siemens Siemens USB token
Plugins\CAPI AR CAPI provider
Plugins\SSO Single Sign On
Plugins\Netscape Netscape plugin (2)
Plugins\IPSEC Microsoft IPSEC support (3)
Plugins\Entrust Entrust plugin (2)
Plugins\Logon Smart Card logon (3)
Plugins\Terminal_Services Terminal Services support (4)
Plugins\Logical_Channels Smart card logical channels (3)
support for terminal server and
Citrix environments
Plugins\Citrix Citrix MetaFrame Server (2)
support
Plugins\Utils CryptoKit utilities
Plugins\Utils\Argenie AR Genie utility
Plugins\Utils\pkcs12util PKCS#12 utility
Plugins\Utils\PHL PHL utility
(5)
SDK SDK files and sample (5)
programs for developers
SDK\headers Developer header files (5) (5)
SDK\libraries Developer library files (5) (5)
SDK\Documentation CryptoKit documentation (5) (5)
SDK\Samples Sample programs (PKCS#11 (5) (5)
and PHL)
SDK\Java_API JCA provider and Java adaptor (5) (5)
7-39

SDK\X509 X509 sample programs (5) (5)
SDK\PKCS7_10 PKCS#7, #10 certificate (5) (5)
request and reply sample
programs
SDK\PKCS12 PKCS#12 sample program (5) (5)
Notes:
(1) This feature is mandatory and must be selected and installed
(2) This feature is automatically displayed on machines with this software
installed
(3) This feature is available only for Windows 2K, XP and 2003
(4) This feature is automatically displayed on Windows XP an Windows 2003
(5) All SDK features are available only in the extended version of CryptoKit
CK_SETUP.INI
The following section describes the different parameters of the CK_SETUP.INI

file.
[General]
The General section in the CK_SETUP.INI file contains the following
parameters:
Key Description Example

ShowSelectLang Controls whether to display the ShowSelectLang =
Installation language selection TRUE
dialog. This dialog allows
selection between English or
Hebrew. By default this dialog is
not displayed.
7-40
Installation 7
ShowWelcome Controls whether to display the ShowWelcome = FALSE
Welcome dialog. By default the
dialog is displayed.
ShowDestPath Controls whether to display the ShowDestPath = FALSE

Ask Destination Path dialog. By
default the dialog is displayed and
destination path is: <Program
Files>\ARL\CryptoKit or a
different value from Destination
Path parameter in [AutoSettings]
section.
ShowTree Controls whether to display the ShowTree = FALSE

Features Tree dialog. By default
the dialog is displayed.
ShowMaint Controls whether to display the ShowMaint = FALSE

Maintenance dialog. By default
the dialog is displayed and
enables users to modify, repair or
uninstall CryptoKit. If you select
not to display the maintenance
dialog the user is asked whether
to uninstall CryptoKit or not and
the repair and modify options are
disabled.
WelcomeLogo Change the image at the left of WelcomeLogo =

the Welcome dialog. The image welcome.bmp
has to be of type bmp, width 176
and height of 300 pixels. It should
be included in the installation
files. The path to the new image
has to be relative to the
installation directory.
7-41
TitleLogo Change the small image at the top TitleLogo =

right corner of most of the small.bmp
dialogs. The image has to be of
type bmp, width 80 and height of
60 pixels. It should be included in
the installation files. The path to
the new image has to be relative
to the installation directory.
FinishLogo Change the image at the left of FinishLogo =

the Finish dialog. The image has finish.bmp
to be of type bmp, width 176 and
height of 300 pixels. It should be
included in the installation files.
The path to the new image has to
be relative to the installation
directory.
ForceReboot Controls whether the CryptoKit ForceReboot = 1

installation will perform reboot at
the end of installation. By default
this is determined by the
installation program. If the
parameter does not exist or its
value is 0, reboot will be
performed only if required. Value
of 1 will always force reboot after
installation and value of 2 will
disable reboot after installation.
NoPCSC Disable PC/SC usage NoPCSC = TRUE
FinalizeMode Allows setting the ARCSP FinalizeMode = 0

parameter FinalizeLibraryUse.
For more information, refer to
explanation about ARCSP
component later in this chapter.
7-42
Installation 7
StoreMode Allows setting the ARCSP StoreMode = 2
parameter StoreMode. For more
information, refer to explanation
about ARCSP component later in
this chapter.
ShowProgramMe Disable installation of the ShowProgramMenu =

nu CryptoKit menu entry in the FALSE
Programs menu.
UseMsReaders Allows setting the SmartAdaptor UseMsReaders = TRUE

parameter UseMsReaders. For
more information, refer to
explanation about SmartAdaptor
component later in this chapter.
Note: It is also possible to replace the image that appears when the installation
is loaded by replacing the file setup.bmp with a new image.
[AutoSettings]
The AutoSettings section allows setting default values for the following
parameters:

Destination Path Change the default target directory Destination Path =
to install CryptoKit. <PROGRAMFILES>\Compa
ny Name\Project
Software Path Change the path of software token Software Path =

directory. The default is: <INSTALLDIR>\softwar
<INSTALLDIR>\sft_tok e
MaxRSAPrivate Set the maximum number of MaxRSAPrivate = 10

private keys that can be stored on
hardware token (smart card /
MiniKey). The default value is 6.
7-43
EntrustVersion Set the Entrust version. This EntrustVersion = 5

parameter overrides the value
which is set automatically by
CryptoKit setup.
[Hidden]
The Hidden section allows selecting the components of CryptoKit that will be
displayed or hidden in the component selection window.

Any full feature A value of TRUE will hide the Readers_And_Tokens\M
name component and a value of FALSE inikey = TRUE
will display it. The full list of
components is listed above.
[ComponentSelect]
The ComponentSelect section allows selecting the features of CryptoKit that
will be selected for installation or not selected.

Any full feature A value of TRUE will select the Readers_And_Tokens\M
name feature for installation and a value inikey = TRUE
of FALSE will deselect it. The full
list of features is listed above.
[EntrustPaths]
The CryptoKit setup program automatically searches for Entrust INI files, but it
is also possible to specifically direct the setup to the location of these files by
registering them in this section.
7-44
Installation 7
Any legal Specify list of directories which C:\
directory contain entrust.ini or entmgr.ini
files. You can use string constants
from the list above.
[CopyFiles]
The CopyFiles section, allows copying additional files as part of the CryptoKit
installation. The files should be added to the installation directory and can be
copied to any location on the target system.

Any legal file List of additional files to copy to <SRCDIR>\hello.txt =
name target machine at the end of <INSTALLDIR>\hello.t
CryptoKit setup. The key name xt
holds the source full file name and
the value is the full name of
destination. You can use string
constants from the list above.
[RegFiles]
The RegFiles section, allows importing additional registry files at the end of
CryptoKit installation. The files should be added to the installation directory. It
is recommended to copy these registry files to the CryptoKit target directory to
allow importing them again at the end of repair operation.

Any legal List of additional registry files to <SRCDIR>\importme.re
registry file import to the target machine at the g =
name end of CryptoKit setup. The key
name holds the registry file name.
The value is ignored. You can use
string constants from the list above.
7-45
[Applications], [AppUninst], [AppOnReboot]

These sections allow specifying a list of external applications that will be
executed at different points in the installation process. The Applications section
is executed at the end of successful installation or repair operation. The
AppUninst is executed immediately before uninstallation of CryptoKit takes
place. The AppOnReboot is executed after reboot or at the end of installation if
no reboot was needed. The external application files should be added to the
installation directory. It is recommended to copy them to the CryptoKit target
directory to allow their execution at the end of repair operation. Use quotes to
support long file names.

Any legal List of application names and "<INSTALLDIR>\ShowHT
executable file arguments to be executed. The key ML.exe" =
name name should contain the application "<INSTALLDIR>\main.h
path and the value a list of tm"
arguments. You can use string
constants from the list above.
[Language]
The CryptoKit installation can be translated to any language. All the text that is
displayed during the setup process is retrieved from an external file name
CK_LANG.INI file, which is in the CryptoKit’s installation package. This file
can contain text in several languages. Each language should be placed in a
different section.
This section in the CK_SETUP.INI file enables setting the default installation
language. Specify in the LANG parameter the three-letter language code that
should be used by the installation program to retrieve the text from the
CK_SETUP.INI file.

LANG Three letters indicating the setup’s LANG = ENG
language.
7-46
Installation 7
CK_LANG.INI
The CK_LANG.INI provides the setup program all the text that appears during
installation. The name of each section in that file is the name of the language.
Each section should contain parameters with text for all installation dialogs.
Adding a New Language

To add a new language perform the following steps:
♦ Choose a three-letter combination that will represent the new language,
for example [SPA] for Spanish.
♦ Edit the CK_LANG.INI file. Copy all the text under the English ([ENG])
section, and paste it under the new section you created.
♦ Translate the text of every field to your preferred language according
their position in the screen shots below.
♦ Change the selected language in the CK_SETUP.INI file to the new
language (For example LANG = SPA under the [Language] section).
7-47
Changing the Setup Language

Welcome Dialog
(1) Msg_Welcome1
(2) Msg_Welcome2
(3) Msg_Welcome3
(4) Msg_Welcome4
(5) Msg_Welcome5
(6) Msg_Back,
Msg_Next,
Msg_Cancel
License Dialog
(1) Msg_License1
(2) Msg_License2
(3) Msg_License3
(4) Msg_License4
(5) Msg_License5
(6) Msg_Back,
Msg_Next,
Msg_Cancel
7-48
Installation 7
Destination Dialog
(1) Msg_Destination1
(6) Msg_Browse
(7) Msg_Back,
Msg_Next,
Msg_Cancel
Features Dialog
(1) Msg_Components1
(2) Msg_Components2
(3) Msg_Components3
(4) Msg_Components4
(5) Msg_Components5
(6) Msg_Back,
Msg_Next,
Msg_Cancel
7-49
Start Copy Message Box

(1) Msg_StartCopy1
(2) Msg_StartCopy2
Finish Dialog
Finish Installation:
(1) Msg_Finish_Inst1
Finish Maintenance:
(1) Msg_Finish_Maint1
Finish Upgrade:
(1) Msg_FinishUpgrade1
Finish Uninstall:
(1) Msg_Finish_Uninst1
All Modes:
(3) Msg_Finish_All1
(4) Msg_Finish_All3
(Only if MiniKey5
was installed)
(5) Msg_Back,
Msg_Finish,
Msg_Cancel
7-50
Installation 7
Finish Reboot Dialog
Finish Installation:
(2) Msg_Reboot_Inst2
Finish Maintenance:
(2) Msg_Reboot_Maint2
Finish Upgrade:
Finish Uninstall:
(2) Msg_Reboot_Uninst2
All Modes:
(3) Msg_Reboot1
(4) Msg_Reboot2
(5) Msg_Reboot_All1
(6) Msg_Reboot_All2
(7) Msg_Finish_All3
(Only if MiniKey5
was installed)
(8) Msg_Back,
Msg_Finish,
Msg_Cancel
7-51
Maintenance Dialog
(1) Msg_Maint1
(2) Msg_Maint2
(3) Msg_Maint3
(4) Msg_Maint4
(5) Msg_Maint5
(6) Msg_Maint6
(7) Msg_Maint7
(8) Msg_Maint8
(9) Msg_Maint9
(10) Msg_Back,
Msg_Next,
Msg_Cancel
Upgrade Dialog
(1) Msg_Upgrade1
(2) Msg_Upgrade2
(3) Msg_Upgrade3
(4) Msg_Back,
Msg_Next,
Msg_Cancel
7-52
Installation 7
Select Language Dialog
(1) Msg_Language1
(2) Msg_Language2
(3) Msg_Language3
(4) Msg_Language4
(5) Msg_Back,
Msg_Next,
Msg_Cancel
Abort Dialog
(1) Msg_Abort1
(2) Msg_Abort2
Confirm Uninstalling
(1) Msg_ConfirmUninst1
(2) Msg_ConfirmUninst2
7-53
Additional Messages
(1) Msg_AD_AlreadyInstalled
(2) Msg_AD_Only
(3) Msg_Minikey4_5Problem
(4) Msg_InsertMinikey
(5) Msg_EnterDisk
(6) Msg_UnsupportedOS
(7) Msg_UserNotAdministrator
(8) Msg_OldCkitBlock
(9) Msg_FileCopyError
(10) Msg_Downgrade
7-54
Installation 7
CryptoKit Files and Registry Entries
CryptoKit installation includes many components, it updates different registry

entries, copies files to different locations and installs different devices.
The following section describes how each CryptoKit component is installed.
General Guidelines
CryptoKit setup must run in administrator rights.
CryptoKit requires Windows smart card base component. Therefore, the

CryptoKit installation installs this component on Windows 98, NT and ME,
which do not include it.
The tables in this section refer to the following directories:
<INSTALLDIR> The target directory that was selected by the user
<INSTALLDIR>\Installation Temporary directory for files needed by the

installation
<WinDir> Windows directory
<SystemFolder> Windows system directory
<ProgramFiles> Program files directory
<AllUsersProfile> The All Users directory on Windows 2000, Windows

XP and Windows 2003. The value of environment
variable with the same name.
7-55
SmartAdaptor
The SmartAdaptor component is always installed. It includes the basic

CryptoKit files.
Files
OS File Name Target Description
All Sadaptor.dll <SystemFolder> SmartAdaptor
All Cypkcs11.Dll <SystemFolder> Crypto Provider for

Obj_Ids.Dll software and hardware
tokens of Algorithmic
Research
All Ckx50932.dll <SystemFolder> X.509 support dll
All Argui.dll <SystemFolder> User interface support dlls

Argenie.dll
All Ckpkcs12.dll <SystemFolder> PKCS#12 support dll
All Ar_jpk11.dll <SystemFolder> Java client support dll

(JNI)
All Anonymous.sft <INSTALLDIR> Read only software token

for CryptoKit internal use.
This file MUST have read
permissions to all users.
All Killproc.exe <INSTALLDIR>\Installation Utility programs needed

for the installation
Registry
The SmartAdaptor registry entries include general parameters and the basic
entries of AR Core provider and AR Smart Card provider. The SmartAdaptor
parameters are placed in the subfolder:
7-56
Installation 7
HKEY_LOCAL_MACHINE\Software\Arl\SmartAdaptor\Main
The keys included in the subfolder:
Key name Key Type Description
CkitDir String Path to installation directory of CryptoKit

Default: "<INSTALLDIR>"
StartPlace String Path to currently used sadaptor.dll file

Default:
"<SystemFolder>\sadaptor.dll"
The Main subfolder contains two additional subfolders: Logging and

Parameters.
The contents of the Logging subfolder are:

LogFileName String Path to the log file of SmartAdaptor
Default: "<INSTALLDIR>\CKit.log"
LogLevel DWORD Controls the how detailed the log file would be.
Each level includes all other less detailed levels:
0 – Errors only
1 – In/Out function parameters
2 – Information
3 – Most detailed Information
Default: dword:00000003
7-57
LogGroup DWORD The SmartAdaptor component whose log should

be activated. Each bit controls a different
functionality:
0x0001 Exceptions
0x0002 Get state functions
0x0004 In/Out functions parameters
0x0008 Extended API functions
0x0010 Reserved
0x0020 Providers functions
0x0040 Internal functions
0x0080 Reader functions
Note: To activate the log without printing the

service monitoring use LogGroup value of:
dword:0x000000FD
The contents of the Parameters subfolder are by default empty. Additional

values may be added when installing specific components or devices. The
following optional values may be added if needed:

PcscWait DWORD Enable or disable working with PC/SC
devices that are installed on the machine.
0 – Disable PC/SC slots
1 – Enable PC/SC slots
Default: This entry does not exist by default to
allow working with all available PC/SC slots.
7-58
Installation 7
UseMsReaders DWORD Instruct SmartAdaptor to add into the list of
slots, PC/SC readers that exist in the registry
but not physically connected. In the event of
connecting such a reader, it is recognized
immediately and the current applications can
access it without reboot.
0 – List of slots will include only
connected PC/SC readers
1 – List of slots will include both
connected and registered PC/SC readers.
Default: This entry does not exist. The list of
PC/SC readers will not be read from registry
and will include only the connected readers.
ParallelSlots DWORD Controls CryptoKit multi slot behavior. In

most environments it is enough to allow only
one PKCS#11 operation at a specific time.
This provides high performance since only
one global mutex has to be locked. In other
situations, where it is important to allow
multiple slots to work simultaneously, it is
possible to set a different mode of operation,
which allows performing PKCS#11
operations on different slots at the same time.
0 – Allow only one operation at a time
1 – Allow multiple slots to work
simultaneously
Default: This entry does not exist so only one
operation is performed at a time. However,
when CryptoKit is installed on a Citrix or
Terminal server, the value of this entry is set
to 1.
7-59
Pentium4RSAMode DWORD Control the behavior of CryptoKit’s fast RSA

library for Pentium 4 machines.
0 – Use the fast RSA library if
CryptoKit is running on Pentium 4
machine (default behavior)
1 – Always disable the fast RSA
library for Pentium 4
2 – Always enable the fast RSA
library. This value should be used
carefully.
Default: This entry does not exist and the fast
RSA library is automatically enabled when
CryptoKit is running on Pentium 4 machines.
The SmartAdapter registry includes also parameters of other CryptoKit

components such as AR Genie. These are placed in:
HKEY_LOCAL_MACHINE\Software\Arl\SmartAdaptor\
Components
This subfolder contains two additional subfolders: Logging and

Parameters.
The Logging subfolder includes the parameters:

LogFileName String Log file name of additional SmartAdaptor
components
Default: "<INSTALLDIR>\comp.log"
0 – Errors only
2 – Information
7-60
Installation 7
LogGroup DWORD The CryptoKit component whose log should be
activated. Each bit controls a different
component:
0x0001 ARDaemon.exe
0x0002 ARGenie.exe
0x0004 ARGenie.dll
0x0008 ARGUI.dll
0x0010 SSO.dll
0x0020 ARcltsrv.exe
The Parameters subfolder includes parameters that are used by AR Genie, AR

client service and other CryptoKit components. You can find explanation about
each entry in the explanation about the component it belongs to.
The SmartAdaptor registry places each of the three types of providers in a

different subfolder. All subfolders have the same structure and each one contains
a key named _ProvidersCounter and several subfolders named
Provider_0, Provider_1, etc. The _ProvidersCounter key contains
the number of providers of the current type registered in SmartAdaptor.
Core providers are registered in the subfolder:

PKCS#11_PROVIDERS
By default one Core provider is installed – AR Core provider.

_ProvidersCounter DWORD One Core provider is installed – AR Core provider.
Each Core provider subfolder includes two subordinate subfolders, Info and
VendorDefined, as well as four keys. The default Core provider is in the
subfolder Provider_0 and contains the following keys:
7-61

Module String Path and name of the PKCS11 DLL of the provider
Default: "<SystemFolder>\cypkcs11.dll"
Entry String Name of the Entry function

Default: "SoftwareProviderEntry"
LogFileName String Log file name of the provider

Default: "<INSTALLDIR>\pkcs1132.log"
LogGroup DWORD The cypkcs11 component whose log should be activated.

Each bit controls a different component:
0x0001 Exceptions
0x0002 API functions
0x0004 Initialize/Finalize and dll
attach/detach functions
0x0008 Internal functions
0x0010 Reserved
0x0020 Slot classes functions
0x0040 Token classes functions
0x0080 Object classes functions
Note: To activate a full log enter the value of:

dword:0x000000FF
LogLevel DWORD Controls the how detailed the log file would be. Each
level includes all other less detailed levels:
0 – Errors only
2 – Information
The contents of the Info subfolder:
7-62
Installation 7
API_Version DWORD Version of API
High word – major version
Low word – minor version
IMPL_Version DWORD Implementation version

ProviderName String String that holds the provider name (max 64 letters)
Default:
"UMB PKCS#11 non-US Extended Ver "
VendorName String String that holds the vendor name (max 64 letters)
Default:
"Algorithmic Research Ltd. "
The contents of the VendorDefined subfolder:

_IdsMap Binary Internal SmartAdaptor information with the
encoding of the attributes
Default: hex:01,00,00,80,02,00,00,80,
03,00,00,80,04,00,00,80,
65,00,00,80,66,00,00,80,
67,00,00,80,68,00,00,80,
69,00,00,80,c9,00,00,80,
ca,00,00,80,cb,00,00,80,
cc,00,00,80,cd,00,00,80,
2e,01,00,80,2f,01,00,80
Attribute_1 Binary Mutex timeout in milliseconds

Default: hex:ff,ff,ff,ff
Attribute_101 Binary Total number of software slots (static + dynamic)

Default: hex:00,00,00,00
7-63
Attribute_102 Binary Number of dynamic software slots (Attribute_102

should not be bigger then Attribute_101)
Attribute_103 Binary Path to directory of static software slots

Attribute_104 Binary Maximum size of software token (in bytes)

Default: hex:c0,90,00,00
Attribute_105 Binary Maximum PIN length for software token

Attribute_2 Binary Internal configuration information

Default: hex:e8,03,00,00
Attribute_201 Binary Maximum size of pools on smart card

Attribute_202 Binary Maximum size of file on smart card



Attribute_205 Binary PIN expiration time in days for software token

0 – Unlimited, PIN never expires or
1 to 889 – number of days the PIN will be valid
Attribute_3 Binary Minimum PIN length of software token

Attribute_302 Binary Number of attempts for presenting user PIN of

software token. 0 – Unlimited or 3-12.
7-64
Installation 7
Attribute_303 Binary Number of attempts for presenting SO PIN of
software token. 0 – Unlimited or 3-12.

Smart card providers are registered in the subfolder:

SC_PROVIDERS
By default one Smart card provider is installed.

_ProvidersCounter DWORD AR Smart card provider is installed
Each Smart card provider subfolder includes three subfolders: ATRs, Info and
VendorDefined and these include several keys. The default Smart card
provider is in the subfolder Provider_0 and contains the following keys:

Module String Path and name to the DLL of the provider
Default: "<SystemFolder>\cypkcs11.dll"

Default: "SmartcardProviderEntry"

Default: "<INSTALLDIR>\sc_pkcs11.log"
LogLevel DWORD Logging level (0 – disabled, 3 – maximum)

The contents of the Info subfolder:
7-65

API_Version DWORD Version of API (High word – major version, Low
word – minor version)
IMPL_Version DWORD Implementation version (High word – major version,

Low word – minor version)
Default: "PrivateCard"
Default:
"Algorithmic Research Ltd. "
The contents of the VendorDefined subfolder:

_IdsMap Binary Internal SmartAdaptor information with the encoding
of the attributes
Default: hex:03,00,00,80,69,00,00,80,
CD,00,00,80,2D,01,00,80,
2E,01,00,80,2F,01,00,80,
30,01,00,80,31,01,00,80
Attribute_105 Binary Maximum PIN length for smart card or MiniKey

Attribute_205 Binary PIN expiration time in days for smart card or

MiniKey
0 – Unlimited, PIN never expires or
1 to 889 – number of days the PIN will be valid
Attribute_3 Binary Minimum PIN length for smart card or MiniKey

7-66
Installation 7
Attribute_301 Binary Maximum number of RSA key pairs on the smart
card or MiniKey
Attribute_302 Binary Number of attempts for presenting user PIN to the

smart card or MiniKey. 3-12
Default: hex:0c,00,00,00
Attribute_303 Binary Number of attempts for presenting SO PIN to the

smart card or MiniKey. 3-12
Attribute_304 Binary Number of PIN generations. This is the number of

old PINs that will be stored on the smart card or
MiniKey, not including the current PIN. This option
is available only from smart card operating system
2.34 and higher. Valid values are: 0-12. A value of 0
will not allow changing the PIN to the current value.
Attribute_305 Binary Control whether the SO will be able to unblock the

smart card and set a new user PIN. This option is
available only from smart card operating system 2.34
and higher. Valid values are: 0-Disable, 1-Enable.
The contents of the ATRs subfolder:

_Total_ATRs DWORD Number of ATR and ATR mask pairs
dword:00000004
ATR_0_len DWORD Length of ATR

dword:00000008
7-67
ATR_0_atr Binary Value of ATR

hex:3b,25,00,80,53,41,52,01,00,00,
00,00,00,00,00,00,00,00,00,00,00,
00,00,00,00,00,00,00,00,00,00,00
ATR_0_atr_mask Binary Mask of ATR

hex:ff,ff,ff,ff,ff,ff,ff,ff,ff,ff,
ff,ff,ff,ff,ff,ff,ff,ff,ff,ff,ff,
ff,ff,ff,ff,ff,ff,ff,ff,ff,ff,ff
ATR_1_len DWORD dword:00000008
ATR_1_atr Binary hex:3b,15,13,80,53,41,52,02,00,00,

00,00,00,00,00,00,00,00,00,00,00,
00,00,00,00,00,00,00,00,00,00,00
ATR_1_atr_mask Binary hex:ff,ff,e0,ff,ff,ff,ff,f0,ff,ff,


00,00,00,00,00,00,00,00,00,00,00,
00,00,00,00,00,00,00,00,00,00,00
ATR_2_atr_mask Binary hex:ff,ff,ff,ff,ff,ff,ff,ff,ff,ff,


00,00,00,00,00,00,00,00,00,00,00,
00,00,00,00,00,00,00,00,00,00,00
ATR_3_atr_mask Binary hex:ff,ff,e8,ff,ff,ff,ff,ff,f0,ff,

Reader providers are registered in the subfolder:
7-68
Installation 7
READER_PROVIDERS
The above entry includes subordinate Provider_x folders with reader

provider’s information and an additional EXCLUDE_PCSC subfolder, which
contains information about PC/SC readers that should not be enumerated by
SmartAdaptor.
Note that there is no need to register standard PC/SC readers. These readers are
enumerated automatically by calling standard PC/SC windows functions.
The following table lists the keys in this subfolder:

_ProvidersCounter DWORD Number of PC/SC readers to be ignored by
SmartAdaptor
Flag_x DWORD Type of search
ReaderName_x String Name of reader to be excluded
By default the _ProvidersCounter is zero and no Flag and

ReaderName entries are created. When installing specific devices (such as
PrivateSafe), these registry entries are updated.
The Flag parameter specifies one of the three types of search:

♦ Full comparison
♦ Partial comparison from start (similar to “name*” in file search)
♦ Partial comparison at middle (similar to “*name*” in file search)
Each Reader provider subfolder includes an Info subfolder containing the keys
listed in the following table:
7-69

Module String Path and name to the DLL of the provider
LogLevel DWORD Logging level (0 – disabled, 3 – maximum)
ReaderType DWORD The type of the reader provider

(CTAPI/PROPRIETARY)
The contents of the Info subdirectory:

Low word minor – version

AR Client Service and Daemon
AR client service is used to improve performance, and to provide better support

for PC/SC readers. It is started immediately after installation and afterwards
every time when the machine reboots. This service has dependency with the
smart card service ScardSvr.
Files
7-70
Installation 7
All Arcltsrv.exe <INSTALLDIR>\utils The service is run for each
terminal session. It operates in
a machine context
All Ardaemon.exe <INSTALLDIR>\utils The daemon is run in a user

context
Registry
On Windows 98, ME and NT, the client service and daemon are activated with
the following registry entries, which are placed in the subfolder:
HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\
CurrentVersion\Run
AAARCLTSRV String "<INSTALLDIR>\Utils\arcltsrv.exe"
ZZZARDAEMON String "<INSTALLDIR>\Utils\ardaemon.exe"
On Windows 2000, XP and 2003 the daemon is not installed and the client service is installed as a
service with the following parameters:
Service Parameter Name Value
DisplayName Arcltsrv
Description Algorithmic Research Client Service
Dependencies ScardSvr
StartType Automatic
InteractWithDesktop No
Command Line <INSTALLDIR>\Utils\Arcltsrv.exe /T=installer
7-71
In some cases there is need to disable the automatic open session which is done
by the service when a token is inserted. To do that, add the following registry
entry:
HKEY_LOCAL_MACHINE\Software\Arl\SmartAdaptor\Main\
Parameters

disableHos DWORD dword:00000001
Default: This entry does not exist to allow the
service to open sessions with inserted tokens.
The service can be used to lock the workstation after a certain delay from smart
card removal. This option is only active if the user used smart card to logon to
the station on Windows 2000, XP and 2003. This option can be used to allow the
user to remove the token that was used to login, but without automatically
locking the station.
Components\Parameters

ServiceLockDelay DWORD Number of seconds, after which the station will
be locked, if the smart card that was used to
login has been removed.
Default: This entry does not exist to allow
normal behavior of Windows smart card
removal action.
ARCSP
The CSP is one of the adapters supported by CryptoKit (see Chapter 4).
Algorithmic Research’s CSP includes an RSA cryptographic provider for all
operating systems and an additional SChannel provider for Windows 2003.
Files
7-72
Installation 7
All Arcsp.dll <SystemFolder> CSP dll, signed by Microsoft
Arstore.dll
All Arcsp.sig <INSTALLDIR>\Installation Binary file with signature of

the CSP
Registry
The ARCSP registry entries are placed in the subfolder:

HKEY_LOCAL_MACHINE\Software\Arl\
Cryptoki CSP\Parameters
This subfolder contains two additional subfolders: Logging and

Parameters.
The contents of the Logging subfolder are:

LogFileName String Path to the log file of ARCSP
Default: "<INSTALLDIR>\csp.log"
0 – Errors only
2 – Information
LogGroup DWORD Control if log will be activated:

0 – Disabled
255 – Enabled (0xFF)
7-73
The keys in the Parameters subfolder are:

ExceptProcess MultiString List of processes for which only Microsoft
CSP is accepted. The default is WinLogon and
LSASS processes only but when windows
smart card logon is required this registry entry
should be empty.
Default:
"lsass.exe[~]winlogon.exe"
StoreMode DWORD Controls the store behavior. Each bit controls

a different component:
0x0001 – Load certificates also into
Microsoft store
0x0002 – Do not allow one user to
access the store of another user
0x0004 – Delete the certificate from
the token if it has been deleted from the
certificate store. This bit is active only on
Windows 2000, XP and 2003.
7-74
Installation 7
FinalizeLibraryUse DWORD Controls the mode of operation of ARCSP
when all processes released their context:
0 – No action will take place. The
PKCS#11 will stay initialized and all
sessions will stay open.
1 – The PKCS#11 library will be
closed with C_Finalize function
2 – All open sessions will be closed
but the PKCS#11 library will stay
initialized.
3 – Re-initialize the PKCS#11 library
if the list of PC/SC readers has
changed. This mode will
automatically identify and work with
new smart card readers, which were
inserted. It is also required for correct
operation in Terminal Server
environment.
The CSP requires additional information to be written in the Windows operating

system. This information is placed in several places:
HKEY_LOCAL_MACHINE\Software\Microsoft\Cryptography\
Defaults\Provider\AR Base Cryptographic Provider

Image Path String "arcsp.dll"
SigInFile DWORD dword:00000000
Type DWORD dword:00000001
Signature Binary 136 bytes read from the binary file ARCSP.SIG
When installed on Windows 2003 server an SChannel CSP is also registered:
7-75
Defaults\Provider\
AR RSA SChannel Cryptographic Provider
Image Path String "arcsp.dll"
SigInFile DWORD dword:00000000
Type DWORD dword:00000012
In all operating systems AR’s PrivateCard smart card is registered:

Calais\SmartCards\PrivateCard
Crypto Provider String "AR Base Cryptographic Provider"
ATR Binary hex:3b,25,00,80,53,41,52,01
ATRMask Binary hex:ff,ff,ff,ff,ff,ff,ff,ff
Calais\SmartCards\PrivateCardEx
Crypto Provider String "AR Base Cryptographic Provider"
ATR Binary hex:3b,15,00,80,53,41,52,00
ATRMask Binary hex:ff,ff,e0,ff,ff,ff,ff,f0
OID\EncodingType0\CertDllOpenStoreProv\arPhysicalOpen
7-76
Installation 7
Dll String "ARstore.dll"
FuncName String "arOpenStore"
On Windows 2000 and higher, the AR client service automatically registers

CryptoKit in order to dynamically load the certificates from the tokens into the
user certificate store. For each new user, the following registry entries are
created:
HKEY_CURRENT_USER\Software\Microsoft\
SystemCertificates\My\PhysicalStores\ArStore
Flags DWORD dword:00000001
OpenEncodingType DWORD dword:00065537
OpenFlags DWORD dword:00000000
OpenParameters Binary User GUID information
OpenStoreProvider String ArPhysicalOpen
Priority DWORD dword:00000002
It is also possible to instruct CryptoKit to dynamically load the certificates into

the machine certificate store by creating similar entries in:
SystemCertificates\My\PhysicalStores\ArStore

Flags DWORD dword:00000001
OpenEncodingType DWORD dword:00065537
7-77
OpenFlags DWORD dword:00000000
OpenParameters Binary "ArComp"

Default: hex:61,72,43,6F,6D,70,00
OpenStoreProvider String ArPhysicalOpen
Priority DWORD dword:00000002
CryptoKit stores in the user context the default CAPI slot. This entry is created
by AR Genie utility, when the user sets a default CAPI slot and deleted when the
user clears the default slot.
HKEY_CURRENT_USER\Software\ARL\Cryptoki CSP\Parameters
DefaultSlotId DWORD Number of default slot to be used by CAPI

applications.
Default: This entry does not exist. When
ARCSP has to select a slot for key generation or
import a dialog appears and ask the user to
select the slot to be used.
Software Token
The software token is an optional component. CryptoKit supports two types of

software tokens: static and dynamic.
Files
All Token1.sft <INSTALLDIR>\sft_tok Empty software token file.
This file must have read
permissions to all users.
Registry
7-78
Installation 7
The registry entries of software token are placed in the subfolder:
HKEY_LOCAL_MACHINE\Software\ARL\SmartAdaptor\
PKCS#11_Providers\Provider_0\VendorDefined
To add software slots update the following keys:

Attribute_101 Binary Total number of software slots (static + dynamic)
Attribute_102 Binary Number of dynamic software slots (Attribute_102

should not be bigger then Attribute_101)
Attribute_103 Binary Null terminated string with the path to directory of

static software slots. When software token is
installed, CryptoKit sets this parameter by default to:
<INSTALLDIR>\sft_tok
Single Sign On (SSO)
The Single Sign On (SSO) mechanism is an optional component. It requires the

user to enter the PIN only once. Other processes use the cached PIN and do not
require additional PIN entries. The SSO can be activated also on unattended
machines and in that case it uses a PIN stored in the registry.
Files
All Arcksso.dll <INSTALLDIR> Single Sign On dll
Registry
The following registry entry is required to activate the SSO mechanism:

HKEY_LOCAL_MACHINE\Software\ARL\SmartAdaptor\Main\
Parameters
7-79

SSO DWORD Value of 1 enables SSO. Value of 0 disables SSO.
dword:00000001
On Windows 2K and XP the stored password should cleared from memory

when the user logs off or locks the computer. To hook on these events the
following registry entries are also required.
HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\
CurrentVersion\Winlogon\Notify\ArCryptoKit
Asynchronous DWORD dword:00000000
Impersonate DWORD dword:00000001
DllName String "arcksso.dll"
LogOff String "Logoff"
LogOn String "Logon"
Lock String "Logoff"
For unattended machines add the following registry entries:

Parameters
UnAttendedSlotsList MultiString List of slot names for which the PIN should be
taken from the corresponding UnAttendedPin
list
UnAttendedPin MultiString List of PINs that corresponds to the unattended

slot list
7-80
Installation 7
PrivateSafe Reader
The PrivateSafe files are copied during the installation to a temporary directory.
Then, an installation program is executed to install the driver.
Files
98, ME INSTH98.exe <INSTALLDIR>\Installation Installation files for 98

PRinst98.exe and ME
Prsafe.inf
Prsafe.sys
NT INSTN4SH.exe <INSTALLDIR>\Installation Installation files for NT

PSAFENT4.sys
2K, XP Prclass.inf <INSTALLDIR>\Installation Installation files for 2K

Prclass.sys and XP
PRSAFEup.inf
PRSAFEup.sys
Prinsth2KXP.exe
All CSAFE32.dll <SystemFolder> PrivateSafe drivers

CSDRV32.exe
All DLMLOAD.exe <INSTALLDIR>\Installation DLM loader

FIX252B.dlm DLM file for PrivateSafe
FIX262B.dlm v2.5
DLM file for PrivateSafe
v2.6
Registry
When the driver installation is finished, the PrivateSafe is registered in the

PC/SC device list:
Calais\Readers\Algorithmic Research PrivateSafe 0
7-81
Additional PrivateSafe parameters are registered in:

HKEY_LOCAL_MACHINE\Software\ARL\ARcryptoSafe\Settings
Number_Of_Protocols String "1"
ShowDriverIcon String "No"
ShowMultipleInst String "No"
HKEY_LOCAL_MACHINE\Software\ARL\ARcryptoSafe\Settings\
Protocol1
The PrivateSafe is installed by default with Algorithmic Research proprietary

driver which supports secure password entry. However, it is possible to change
the driver to behave as a standard PC/SC reader with the following registry
entry:
On Windows 98 and ME this entry is located in:
HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\
Class\SmartcardReader\0000\Parameters
Note: The value 0000 in Windows 98 may be different depending on the number
of readers you have installed and the order of installation.
On Windows 2000 and XP this entry is located in:

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\
PrClass\Parameters
InterfaceDeviceType DWORD Type of driver:

3 –AR Proprietary with secure PIN entry
7 – Standard PC/SC
7-82
Installation 7
When the PrivateSafe is installed as a proprietary driver, additional registry
entries must exist. A reader provider has to be registered in SmartAdaptor:
Reader_Providers\Provider 0
And the reader has to be registered in the EXCLUDE_PCSC list in:
Reader_Providers\EXCLUDE_PCSC
It is possible to define processes that should not have access to the PrivateSafe reader.
This can be done, by entering the list of process names in:
Main\Parameters

PsafeExceptProcesses MultiString List of processes that should not access the
PrivateSafe reader
Driver Types
Different versions of PrivateSafe driver were released in different versions of

CryptoKit. The following table describes the difference between them:
CryptoKit 1.63 CryptoKit From Version

Versions 3.6.0
3.2 – 3.5.X
Description Works directly with Uses Windows Replaces the

keyboard controller 2000 keyboard standard
hook mechanism Microsoft
keyboard driver
7-83
Operating NT, 2000, XP 2000, XP 2000, XP

Systems
SMS 2000 Yes No – SMS driver No
conflicts with
PrivateSafe
driver
SMS 2003 No No Yes
MiniKey5
The MiniKey5 files are copied during the installation to a temporary directory.
Then, installation functions in euci5in.dll are called to install the driver.
Files
All euci5.cat <INSTALLDIR>\Installati Signature of driver
on\Crypto5
All euci5in.dll <INSTALLDIR>\Installati File which installs the

on\Crypto5 MiniKey5 driver
All euci5.inf <INSTALLDIR>\Installati Driver files

euci5.sys on\Crypto5
euci5d.inf
euci5inx.exe
euci5nt.inf
euci5nt.sys
euci5r.inf
euci5r.sys
euci5s.inf
usbdrv.inf
usbdrv.sys
Registry
7-84
Installation 7
When the driver installation is finished, the MiniKey is registered as a PC/SC
device in:
Calais\Readers\Algorithmic Research Minikey 0
And
Calais\Readers\Algorithmic Research Minikey 1
Siemens PKCS#11 Provider
The Siemens PKCS#11 provider enables working with Siemens MiniKey and is
registered in SmartAdaptor as a PKCS#11 core provider.
Files
All ApiAsn1.dll <SystemFolder>
ApiCore.dll
ApiCrypto.dll
ApiSCCom.dll
CardOS_CSP.dll
CardOS_PKCS11.dll
CSP_Module.dll
ErrMngr.dll
SiCertificateViewer.dll
SiCertViewer.dll
All PinManager.exe <INSTALLDIR>\Utils
Registry
The PKCS#11 core provider is registered in:

PKCS#11_PROVIDERS\Provider_x
7-85

Module String Path and name of the PKCS11 DLL of the provider
Default:
"<SystemFolder>\CardOS_PKCS11.dll"
PKCS#11_PROVIDERS\Provider_x\Info


ProviderName String The provider name

Default: "Siemens"
VendorName String The vendor name

Default: "Siemens"
Additional information of the Siemens provider is registered in:

HKEY_LOCAL_MACHINE\Software\Siemens Informatica
Ifdh Driver for Siemens MiniKey
Some models of Siemens MiniKey use the Ifdh a USB driver. The driver
installation files are copied during the installation to a temporary directory and
then the registration dll is called to install the driver.
Files
7-86
Installation 7
All eTCoreReg.dll <SystemFolder> Registration dll which installs
and uninstalls the driver
98, ME aksup.inf <WindowsFolder>\Inf

aksifdh.inf
98, ME aksifdh.sys <SystemFolder>\Drivers

aksup.sys
NT UsbHub.sys <SystemFolder>\Drivers
aksup.sys
adfrt.sys
UsbDrv.sys
aksifdh.sys
2K, XP aksifdh.sys <SystemFolder>\Setup\Al This is a temporary directory.

aksifdh.inf addin\eToken The installation program calls
aksup.sys a function in eTCoreReg.dll
aksup.cat that installs the driver and
aksup.inf copies these files to their final
aksifdh.cat destination
Registry
When the driver installation is finished, the Ifdh driver is registered as a PC/SC
device in:
Calais\Readers\Algorithmic Research AKS ifdh 0
Additional entry is placed in:

HKEY_LOCAL_MACHINE\Software\Aladdin\eToken\Core
Cache DWORD dword:00000000
7-87
Terminal Services
CryptoKit can be installed on Windows 2003 terminal server.
Registry
Only one registry entry is needed to activate the terminal services support:
Parameters
ServerMode DWORD Value of 1 enables terminal services support.
dword:00000001
Citrix Server
CryptoKit can be installed on Citrix server running on Windows 2000 server or

Windows 2003 server. CryptoKit has to be installed only after the Citrix server
was installed.
Registry
The following registry entries are needed to activate CryptoKit on the Citrix
server:
Parameters
ServerMode DWORD On Windows 2000 server:
dword:00000027
On Windows 2003 server:

dword:00000003
In addition to that, the arcsp.dll has to be registered in:
7-88
Installation 7
HKEY_LOCAL_MACHINE\Software\Citrix\CtxHook\
AppInit_Dlls\Smart Card Hook

SpecialDllSearch String Add the value:
;arcsp.dll sadaptor.dll
at the end of the existing string
In addition, a special Citrix utility scconfig.exe, is used to register

CryptoKit executables arcltsrv.exe, ardaemon.exe, phl.exe and
argenie.exe to allow them access the smart card on the client machine.
Utility Programs
The CryptoKit includes the following utilities and support files:
Files
All ARgenie.exe <INSTALLDIR>\utils AR Genie utility program
All ARgenie.htm <INSTALLDIR>\utils\htm AR Genie help files

image001.jpg
image001.gif
image002.gif
image003.gif
All Pkcs12util.exe <INSTALLDIR>\utils PKCS#12 sample utility

program
All PHL.exe <INSTALLDIR>\utils PKCS#11 sample utility

program
Registry
There are some registry entries that control the behavior of the AR Genie utility
program. They are placed in:
7-89

GenieDisableAdmin DWORD Controls whether running AR Genie in
administrator mode is disabled.
0 – Administrator mode is enabled
1 – Administrator mode is disabled
GenieFormat DWORD Controls whether the Format Token option will

be available in the AR Genie utility, when run in
user mode. The Format Token option is always
available when running in administrator mode
(/BR option).
0 – Format option is not available
1 – Format option is available
GenieStandardize DWORD Controls whether the Standardize Token option

will be available in the AR Genie utility, when
run in user mode. The Standardize option is
always available when running in administrator
mode (/BR option).
0 – Standardize option is not available
1 – Standardize option is available
GenieDeleteMode DWORD Controls the behavior of the Delete Object option

when AR Genie utility is run in administrator
mode (/BR option).
0 – Deletion of objects is allowed
1 – Deletion of objects is not allowed
2 – Deletion of objects is allowed only
if the user is logged in
7-90
Installation 7
SOPinMode DWORD When equal to 0, the AR Genie utility will always
attempt to use the default SO PIN of ‘11111111’
and only if it fails, it would present the SO PIN
entry dialog. When equal to 1, the SO PIN entry
dialog is always presented when SO
authentication is needed.
Additional entries are stored for each user and placed in:
HKEY_CURRENT_USER\Software\ARL\SmartAdaptor\
GenieParams DWORD The AR Genie utility stores in each bit of this
parameter the user settings. It is updated from the
Program setting dialog in the Options menu:
0x0001 Automatically login when the user
wants to view the token objects
0x0002 Allow the user to enter the token
label during format token operation
GenieHideDynamic DWORD Specify whether to display dynamic CoSign slots

or not:
0 – Display dynamic slots
1 – Hide dynamic slots
SDK Files
When the CryptoKit SDK component is installed, the following additional files
are also copied:
Target Description
<INSTALLDIR>\include Developer include files
<INSTALLDIR>\lib Developer libraries
7-91
<INSTALLDIR>\doc CryptoKit documents
<INSTALLDIR>\javaCKit AR Java and JCA adapters

(CAB, JAR, configuration and documentation)
<INSTALLDIR>\samples Sample programs (PKCS#10/#7, PKCS#11, PKCS#12,

X.509 etc.)
Entrust Plug-in in the Registry
The SmartAdaptor Entrust adapter enables an application to plug-in to Entrust

Desktop Solutions.
Files
All CyCpten5.dll <SystemFolder> Entrust 5 adapter
Registry
The SmartAdaptor Entrust registry entries include. It is placed in the registry in

the subfolder:
Entrust
which includes several keys described in following table:
CallbackFlags DWORD Boolean value that controls the secure password

entry for the PrivateSafe reader:
0 – Disable
1 – Enable
LogFileV5 String Path to the log file of Entrust adapter
7-92
Installation 7
LogLevelV5 DWORD Level of logging of Entrust adapter for version 5.x
(0 – disabled; 4 – max)
The SmartAdaptor Entrust adapter is registered in the Entrust system by the

Entrust.ini file, which is usually placed in the Windows directory. The
following parameter in the INI file, defines SmartAdaptor as a security module
of Entrust:
CryptokiLibrary95(NT) = windows system
directory\Cycpten5.dll
Shortcuts
The CryptoKit menu is placed in a different place, depending on the operating

system:
Shortcuts
OS File Name
98, ME <WinDir>\Start Menu\Programs\CryptoKit
NT <WinDir>\Profiles\All Users\Start Menu\Programs\CryptoKit
2K, XP <AllUsersProfile>\Start Menu\Programs\CryptoKit
Package Information
The installation program stores additional package information.
Registry
The Windows control panel information is stored in two registry entries:

CurrentVersion\Uninstall\
{EE046602-85F3-4B87-A734-148C17748848}
7-93
And
CurrentVersion\Uninstall\CryptoKit
Files
Temporary InstallShield files are placed in the hidden folder:
OS Folder Name
All <ProgramFiles>\InstallShield Installation Information\{EE046602-
85F3-4B87-A734-148C17748848}
7-94
Index
C_PKCS7_CreateCRP, 5-97
A C_UI_GetMessage, 3-81
Active Directory Installation, 7-11 C_UI_GetPassword, 3-76
Advanced capabilities, 2-17 C_UI_SetMessage, 3-78
Algorithms, 1-1 C_X509_copy, 5-35
AR Genie C_X509_Copy, 5-76
Administrator Mode, 6-4 C_X509_Decode, 5-22, 5-73
Command Line, 6-19 C_X509_Encode, 5-28, 5-74
Registry, 7-89 C_X509_EncodeSign, 5-28, 5-79
User Mode, 6-2 C_X509_FindInCrl, 5-32, 5-83
ARCSP Provider, 4-6 C_X509_GetField, 5-24, 5-75
Algorithms, 4-10 C_X509_Sign, 5-28, 5-78
Functions, 4-12 C_X509_Verify, 5-25, 5-27, 5-81
Installation, 7-72 CA, 5-17
RSA, 4-9, 4-10 cert_list, 5-92
SChannel, 4-9, 4-12 Certificate Authorities, 5-17
Type, 4-6, 4-9 Certificate reply, 5-86, 5-102, 5-106
Asymmetric schemes, 1-3 Certificate request, 5-86, 5-98, 5-106
Authentication of data, 1-7 Certificate Store, 4-16
Certificate/CRL fields, 5-39
C Certificates, 5-17
C_EXT_Bind, 3-69 Building, 5-37
C_EXT_ChangeTokenLabel, 3-74 Decoding, 5-22
C_EXT_GetProviderContext, 3-62 Object identifiers, 5-37
C_EXT_GetProviderInfo, 3-62 Validating, 5-27
C_EXT_GetProviderList, 3-61 certs_and_crls, 5-91
C_EXT_GetProviderSlotList, 3-63 Challenge-Response protocol, 1-6
C_EXT_GetSlotProvider, 3-64 Checking for revoked certificates, 5-32
C_EXT_PassToProvider, 3-66 Citrix Server, 7-26, 7-88
C_EXT_Unbind, 3-70 CK_ASN_ID, 5-53
C_EXT_WaitForSingleSlotEvent, 3-71 CK_CALLBACK_FUNCTION, 3-27
C_EXT_WaitForSlotEvent, 3-72 CK_DATA, 5-53
C_PKCS10_AcceptCRQ, 5-95 CK_DECLARE_FUNCTION, 3-26
C_PKCS10_CreateCRQ, 5-93, 5-116, 5-117 CK_DECLARE_FUNCTION_POINTER, 3-27
C_PKCS10_SimpleCreateCRQ, 5-94 CK_LANG.INI, 7-47
C_PKCS7_AcceptCRP, 5-96 CK_PTR, 3-26
I-1
I CryptoKit Developer's Guide
CK_SETUP.INI, 7-40 CryptoSafe, 2-12, 2-15

AutoSettings, 7-43 CryptSetProvParam, 4-13
ComponentSelect, 7-44 CSP, 4-2
FinalizeMode, 7-42 CTAPI Readers, 3-49
FinishLogo, 7-42
ForceReboot, 7-42 D
Hidden, 7-44 Data
NoPCSC, 7-42 Authentication, 1-1, 1-7
ShowDestPath, 7-41 Secrecy, 1-1
ShowMaint, 7-41 Decoding Certificates and CRLs, 5-22
ShowSelectLang, 7-40 Decryption, fast, 1-7
ShowTree, 7-41 DES Stream, 3-13
ShowWelcome, 7-41 DES2, 3-13
StoreMode, 7-43 DES3, 3-13
TitleLogo, 7-42 Digital signatures, 1-4
WelcomeLogo, 7-41 DlmLoad, 6-26
CK_TIME_T, 5-53
CK_X509_CERT_FIELD, 5-53 E
CK_X509_CRL_FIELD, 5-53 Encoding and signing certificate/CRLs, 5-28
CK_X509_FIELD, 5-53 Encryption,fast, 1-7
Classical schemes, 1-2 Entrust Adapter, 5-14
Clock, internal, 2-12
date and time, 3-24 F
Compiler-dependency, 3-25 Fast encryption/decryption, 1-7
Constants Fields, Certificate/CRL, 5-39
Certificate/CRL fields, 5-39 FinalizeLibraryUse, 7-42, 7-75
Object Identifiers, 5-45 Functions
Types of General Names, 5-44 X.509 Toolkit, 5-73
X.509 Toolkit constants, 5-38
Core providers, 3-4
H
HSM, 2-10
CoSign, 2-11
Hybrid symmetric/asymmetric schemes, 1-5
CRL
Decoding, 5-22 I
CRP_FORMAT, 5-88
Ifdh driver, 2-9, 7-86
CRQ_FORMAT, 5-88
Independence
CryptAcquireContext, 4-13
Platform, 2-16
CryptGenRandom, 4-14
Installation, 7-1
CryptGetProvParam, 4-13
Active Directory, 7-11
Cryptographic algorithms, 1-1
CD, 7-2
I-2
Index I
Citrix, 7-26 N
CK_LANG.INI, 7-47 Netscape, 3-5
CK_SETUP.INI, 7-40 Non-repudiation transaction, 1-8
Customizing, 7-37
Files, 7-55 O
Package files, 7-35 Object Identifiers, 5-37, 5-45
Registry, 7-55 Algorithm Identifiers, 5-45
Silent, 7-9 Attribute Types, 5-38, 5-47
SMS Server, 7-20 Extensions, 5-48
Terminal Server, 7-31 Key Purposes, 5-49
Uninstallation, 7-7 PKCS, 5-46
Upgrade, 7-8 Qualifier Types, 5-49
Objects, 3-5
J
Java Adapter, 5-2 P
Java PKCS, 5-10 ParallelSlots, 7-59
JCA, 5-2 PC/SC Readers, 3-49
PCMCIA, 2-14
K Pentium4RSAMode, 7-60
Key Container, 4-5 Performance, 2-17
Key Media PIN
CoSign, 2-11 Default parameters, 3-20
MiniKey, 2-8 functionality, 3-19
Overview, 2-2 passing NULL, 3-19
PrivateCard, 2-2 Secure PIN entry, 3-19
PrivateServer, 2-10 Single Sign On, 3-20
Software, 2-5 Unattended mode, 3-20
PKCS#10, 5-86
M PKCS#11
Macros
Data objects, 3-18
AR_PLATFORM, 3-25
Mechanisms, 3-5
CK_CALLBACK_FUNCTION, 3-27
Objects, 3-5
CK_DECLARE_FUNCTION, 3-26
Protected authentication path, 3-5
CK_DECLARE_FUNCTION_POINTER,
Slots, 3-5
3-27
Tokens, 3-5
CK_PTR, 3-26
PKCS#11 standard, 3-5
Mechanisms, 3-5, 3-7. See list, pp. 1-3 to 1-6
PKCS#12
Message Authentication Codes (MACs), 1-2
ExportPKCS12, 5-117
MiniKey, 2-8, 2-12, 7-84
ImportPKCS12, 5-116
I-3
Toolkit, 5-116 Smart card providers, 3-4

PKCS#7, 5-86 Smart Cards, 2-2
pkcs10_cr, 5-89 SMS Server, 7-20
pkcs10_cri, 5-89 Software key media, 2-5, 7-63
Platform independence, 2-16 Bind, 3-69, 6-6
Platform-dependency, 3-25 Dynamic slot, 2-7, 7-64
Platform-specific macros, 3-26 Installation, 7-78
Primary issues, 1-1 Registry, 7-63
PrivateCard, 2-3, 2-5, 2-12 Static slot, 2-7, 7-64
PrivateSafe, 2-12, 2-13, 7-81 Unbind, 3-70, 6-7
Driver Types, 7-83 SSO, 7-79
PrivateSafe PCMCIA, 2-12 Store
PrivateServer, 2-10 Certificate, 4-16
Proprietary Readers, 3-50 Physical, 4-17
Protected authentication path, 3-5, 3-19 Registration, 7-77
Public Key Cryptography, 5-16 StoreMode, 7-43, 7-74
Symmetric
R Schemes, 1-2
Reader Provider API, 3-51
Reader providers, 3-4 T
Reference material, 1-1 Terminal Server, 7-31, 7-88
Registration API, 3-29 Thread safety
Remote Desktop Connection, 7-32 serialization of requests, 3-24
RSA, 1-3 Tokens, 3-5, 3-17
Initializing, 3-7
S PrivateCard, 2-12
SChannel CSP, 4-9, 4-12 Transaction non-repudiation, 1-8
Scheme Two-way authentication, 1-1, 1-6
Hybrid, 1-5 Types of General Names, 5-44
Symmetric, 1-2
Secure key transfer, 1-6 U
Siemens MiniKey, 2-9, 7-85 UMB_ATR_DESCRIPTION, 3-33
Signatures, digital, 1-4 UMB_CONTEXT, 3-30
simple_dname, 5-91 UMB_CreatePKCS11ProviderContext, 3-34
Simplicity of use, 2-17 UMB_CTAPI_PORT_DESCR, 3-32
Single sign on, 3-20, 7-79 UMB_CTAPI_PORTS, 3-33
Slots, 3-5, 3-17 UMB_ENTRY, 3-51
CryptoSafe, 2-12 UMB_PCSC_EXCLUDE_STRUCT, 3-31
PrivateSafe, 2-12 UMB_PROVIDER_INFO, 3-31
PrivateSafe PCMCIA, 2-12 UMB_READER_CLOSE, 3-57
I-4
Index I
UMB_READER_GET_NATIVE_RESULT_ Working with, 5-22
VALUE, 3-57 X509, 5-72
UMB_READER_GET_STATE, 3-54 X509_alg_params_dh, 5-58
UMB_READER_I_AM_CLOSED, 3-58 X509_alg_params_key, 5-57
UMB_READER_POWER_OFF, 3-55 X509_alg_params_key_iv, 5-57
UMB_READER_POWER_ON, 3-54 X509_alg_struct, 5-56
UMB_READER_TRANSMIT, 3-56 X509_ATAV, 5-59
UMB_RV, 3-30 X509_attr_value, 5-91
UMBAPI X509_attribute, 5-90
UMB_AddATRToList, 3-40 X509_attributes, 5-90
UMB_AddFindContext, 3-43 X509_certificate, 5-53
UMB_CreateFindContext, 3-43 X509_crl, 5-55
UMB_CreatePKCS11SmartcardProvider X509_crl_tbs, 5-55
Context, 3-35 X509_def_key_info, 5-61
UMB_CreateSmartcardReaderContext, X509_distribution_point, 5-69
3-36 X509_Dname, 5-59
UMB_FreeContext, 3-47 X509_DPN, 5-69
UMB_GetProviderData, 3-41 X509_DSA_params, 5-57
UMB_GetProviderType, 3-47 X509_ext, 5-63
UMB_ListProviders, 3-46 X509_ext_0000 / X509_ext_unknown, 5-63
UMB_RegisterProvider, 3-42 X509_ext_2914, 5-64
UMB_SetProviderData, 3-38 X509_ext_2914 /
UMB_UnregisterProvider, 3-45 X509_ext_SubjectKeyIdentifier, 5-64
Unattended login, 3-20, 7-80 X509_ext_2915, 5-64
Uninstallation, 7-7 X509_ext_2916, 5-64
Utility X509_ext_2916 /
AR Genie, 6-1 X509_ext_PrivateKeyUsagePeriod,
DlmLoad, 6-26 5-64
PKCS#12, 6-24 X509_ext_2917_8, 5-65
X509_ext_2919, 5-65
V X509_ext_2919 / X509_ext_BasicConstraints,
Validating certificates, 5-27 5-65
Version X509_ext_2920, 5-66
information on current, 3-16 X509_ext_2921, 5-66
X509_ext_2921 / X509_ext_CRLreason, 5-66
X X509_ext_2923,X509_ext_HoldInstructionCo
X.509, 5-18 de, 5-66
X.509 Toolkit, 5-16 X509_ext_2924,X509_ext_InvalidityDate,
Constants, 5-38 5-67
Overview, 5-16
I-5
X509_ext_2927,X509_ext_DeltaCRLIndicator X509_ext_BasicConstraints, 5-65

, 5-67 X509_ext_CertificatePolicies, 5-70
X509_ext_2928,X509_ext_IssuingDistribution X509_ext_CRLDistributionPoint, 5-69
Point, 5-67 X509_ext_CRLNumber, 5-66
X509_ext_2929,X509_ext_CertificateIssuer, X509_ext_CRLreason, 5-66
5-68 X509_ext_NameConstraints, 5-68
X509_ext_2930, 5-68 X509_ext_PolicyConstraints, 5-71
X509_ext_2930 / X509_ext_NameConstraints, X509_ext_PolicyMappings, 5-70, 5-71
5-68 X509_ext_PrivateKeyUsagePeriod, 5-64
X509_ext_2931, 5-69 X509_ext_SubjectKeyIdentifier, 5-64
X509_ext_2931 / X509_ext_unknown, 5-63
X509_ext_CRLDistributionPoint, X509_extensions, 5-62
5-69 X509_general_name, 5-65
X509_ext_2932, 5-70 X509_general_names, 5-70
X509_ext_2932 / X509_general_subtree, 5-68
X509_ext_CertificatePolicies, 5-70 X509_key_info, 5-60
X509_ext_2933, 5-70 X509_obj_id, 5-56
X509_ext_2933 / X509_ext_PolicyMappings, X509_rev_list, 5-62
5-70, 5-71 X509_revoked, 5-62
X509_ext_2935, 5-71 X509_RSA_key_info, 5-61
X509_ext_2936, 5-71 X509_signature, 5-55
X509_ext_2936 / X509_tbs, 5-54
X509_ext_PolicyConstraints, 5-71 X509_unique_id, 5-61
X509_ext_2937, 5-72 X509_validation_params, 5-58
X509_ext_Altname, 5-65 X509_validity, 5-60
I-6

CryptoKit Developers Guide

Transféré par

Informations du document

Description originale:

Copyright

Formats disponibles

Partager ce document

Partager ou intégrer le document

Options de partage

Avez-vous trouvé ce document utile ?

Ce contenu est-il inapproprié ?

Droits d'auteur :

Formats disponibles

CryptoKit Developers Guide

Transféré par

Droits d'auteur :

Formats disponibles

CryptoKit

© Copyright 2005 ARX (Algorithmic Research). CryptoKit Developer’s Guide

Chapter 1: Introduction to Cryptography .......................................................................... 1-1

Chapter 2: Component-Related Technologies................................................................. 2-1

Chapter 3 SmartAdaptor Technology ................................................................................ 3-1

CryptoKit PKCS#11 Architecture .................................................................................................3-6

Chapter 4: AR Cryptographic Service Provider.................................................................4-1

Supported Functions ............................................................................................................ 4-12

Chapter 5: SmartAdaptor Add-On Adapters...................................................................... 5-1

Chapter 6: SmartAdaptor Utilities ...................................................................................... 6-1

Chapter 7: Installation ......................................................................................................... 7-1

Modifying or Removing an Existing Installation....................................................................7-7

In Symmetric schemes, authentication is often performed with Message

Asymmetric schemes provide authentication by using Digital Signatures in the

Generate Digital Verify

Digital signatures are applied to authentication of both participants and data.

Hybrid Symmetric/Asymmetric Schemes

Hybrid Symmetric/Asymmetric schemes (e.g., DES + RSA), combine the best

We will now review the above points.

Suppose, for example, that we have a Host and a Client.

Secure Key Transfer

Generate Digital Verify

Several basic elements contribute to CryptoKit’s architecture:

One of the most important aspects of public key cryptography systems is

CryptoKit enables integration of smart cards in any PKCS#11-standard or CAPI

PrivateCard, developed by AR, has the following advantages and features:

CryptoKit supports different PrivateCard models that run Algorithmic Research

Smartcard Chip Memory RSA Communication Operating

Siemens* 8K 1024 bit 9600 1.2

Atmel 32K 1024 bit 9600 1.13

Atmel 64K 2048 bit 38400 2.21-2.22

Atmel 144K 2048 bit 115200 3.01

* This model is supported for backward compatibility and is not available

Software Key Media

Static Software Slots

Dynamic Software Slots

MiniKey, AR’s portable, personal token, allows users to conveniently manage

With AR’s advanced ISO standard smart card

Unlike most other solutions, including memory-based tokens or password

MiniKey performs cryptographic functions in a secure, isolated environment,

Powerful, Convenient and Affordable

Today’s technology has produced new, more powerful processing chips.

With its cutting-edge cryptographic performance, MiniKey can replace both

Universal Serial Bus (USB)

MiniKey* 32K 1024 bit Atmel AR Proprietary No

MiniKey5 32K 1024 bit Atmel AR - PC/SC No

Model Memory RSA Smartcard Operating Driver ITSEC

MiniKey5 64K 2048 bit Atmel AR - PC/SC No

Siemens 32K 1024 bit Siemens Siemens - PC/SC Yes

Siemens 32K 1024 bit Siemens Siemens - PC/SC Yes

* This model is supported for backward compatibility and is not available

Hardware Security Module – PrivateServer

CryptoKit enables PKI applications to use AR’s hardware security module

CoSign is a non-forgeable, simple-to-use digital-signature appliance. It delivers

CoSign is connected to the organization network and user-management system.

Smart Card Readers

In order to enable smart cards to communicate with PCs, workstations, laptops,

PrivateSafe® CryptoSafe PrivateSafe MiniKey

Tokens Supports any ISO Supports Supports any MiniKey is also a

Date Uses date Includes an Uses date Uses date supplied by

PrivateSafe advantages include:

♦ Secure communications and PIN entry Prevents exposure of sensitive

♦ Does not occupy a serial communication port Unlike conventional