CryptoKit Developers Guide

377
CryptoKit Developer’s Guide --------------------------------- Version 3.9

Transcript of CryptoKit Developers Guide

Page 1: CryptoKit Developers Guide

CryptoKit Developer’s Guide

--------------------------------- Version 3.9

Page 2: CryptoKit Developers Guide

NoticeThis 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.

TrademarksCryptoKit, 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 identi�cation 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). All rights reserved.

CryptoKit Developer’s Guide Pub. Date 18.07.05 Pub. No. CK .V3.00601

Page 3: CryptoKit Developers Guide

i

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

Page 4: CryptoKit Developers Guide

CryptoKit Developer's Guide

ii

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

Page 5: CryptoKit Developers Guide

Table of Contents

iii

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

Page 6: CryptoKit Developers Guide

CryptoKit Developer's Guide

iv

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

Page 7: CryptoKit Developers Guide

1-1

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.

Page 8: CryptoKit Developers Guide

1 CryptoKit Developer's Guide

1-2

Symmetric Schemes

Classical (Symmetric) schemes, such as DES, are based on a common secret key for both encryption and decryption:

Ciphertext

User A User B

CleartextCleartext

Key KeyDecryptEncrypt

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.

Page 9: CryptoKit Developers Guide

Introduction to Cryptography 1

1-3

MAC

Cleartext +Initial Vector

Key Key

Cleartext +Initial Vector

User A User B

Compute MAC Verify MAC

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:

Page 10: CryptoKit Developers Guide

1 CryptoKit Developer's Guide

1-4

Encrypt DecryptCiphertext

User A User B

Public Key Private Key

CleartextCleartext

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:

Signature

User A User B

DigitalGenerateDigitalSignature

VerifyDigitalSignature

User APrivate Key

User APublic Key

Cleartext +Date & Time

Cleartext +Date & Time

Digital signatures are applied to authentication of both participants and data. They also ensure non-repudiation.

Page 11: CryptoKit Developers Guide

Introduction to Cryptography 1

1-5

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.

Page 12: CryptoKit Developers Guide

1 CryptoKit Developer's Guide

1-6

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).

Page 13: CryptoKit Developers Guide

Introduction to Cryptography 1

1-7

Fast Encryption/Decryption

Fast Encryption/Decryption of actual data is DES-based:

DecryptCiphertext

Key Key

User A User B

Encrypt

Cleartext Cleartext

Data Authentication

As for data authentication, this is done with MACs:

MACKey Key

User A User B

Compute MAC Verify MAC

Cleartext +Initial Vector

Cleartext +Initial Vector

Page 14: CryptoKit Developers Guide

1 CryptoKit Developer's Guide

1-8

Transaction Non-Repudiation

Transactions that involve payments are authenticated with a Digital Signature, which also ensures non-repudiation.

Signature

User A User B

DigitalGenerateDigitalSignature

VerifyDigitalSignature

Cleartext +Date & Time

Cleartext +Date & Time

User APrivate Key

User APublic Key

Page 15: CryptoKit Developers Guide

2-1

] 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

Page 16: CryptoKit Developers Guide

2 CryptoKit Developer's Guide

2-2

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

Page 17: CryptoKit Developers Guide

Component-Related Technologies 2

2-3

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.

Page 18: CryptoKit Developers Guide

2 CryptoKit Developer's Guide

2-4

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).

Page 19: CryptoKit Developers Guide

Component-Related Technologies 2

2-5

♦ 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 Size

RSA Capability

Communication Speed (baud)

Operating System Version

Siemens* 8K 1024 bit 9600 1.2

Atmel AT90SC3232C*

32K 1024 bit 9600 38400

1.13 1.14-1.17

Atmel AT90SC6464C

64K 2048 bit 38400 115200

2.21-2.22 2.30-2.34

Atmel AT90SC144144CT

144K 2048 bit 115200 3.01

* 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.

Page 20: CryptoKit Developers Guide

2 CryptoKit Developer's Guide

2-6

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.

Page 21: CryptoKit Developers Guide

Component-Related Technologies 2

2-7

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.

Page 22: CryptoKit Developers Guide

2 CryptoKit Developer's Guide

2-8

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.

Page 23: CryptoKit Developers Guide

Component-Related Technologies 2

2-9

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 Size

RSA Capability

Smartcard Chip

Operating System Version

Driver ITSEC Cert.

MiniKey* 32K 1024 bit Atmel AT90SC3232C

AR 1.12-1.14

Proprietary No

MiniKey5 32K 1024 bit Atmel AT90SC3232C

AR 1.14-1.16

- PC/SC - Signed - CryptoIdentity device - Linux

No

Page 24: CryptoKit Developers Guide

2 CryptoKit Developer's Guide

2-10

Model Memory Size

RSA Capability

Smartcard Chip

Operating System Version

Driver ITSEC Cert.

MiniKey5 64K 2048 bit Atmel AT90SC6464C

AR 2.21-2.22

- PC/SC - Signed - CryptoIdentity device - Linux

No

Siemens MiniKey

32K 1024 bit Siemens SLE66CX320P

Siemens CardOS M4.01

- PC/SC - Signed - CryptoIdentity or IFDH device

Yes

Siemens MiniKey

32K 1024 bit Siemens SLE66CX322P

Siemens CardOS M4.01a

- PC/SC - Signed - CryptoIdentity device

Yes

* 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.

Page 25: CryptoKit Developers Guide

Component-Related Technologies 2

2-11

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.

Page 26: CryptoKit Developers Guide

2 CryptoKit Developer's Guide

2-12

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 PCMCIA Reader

MiniKey

Tokens Supports any ISO 7816-compliant smart card.

Supports PrivateCard.

Requires loading the appropriate DLM.

Supports any ISO 7816-compliant smart card.

MiniKey is also a token.

Protected Authentication Path (Secure Keypad Password Entry)

Supports Supports Does not support

Does not support

Date Uses date supplied by the host computer.

Includes an internal clock.

Uses date supplied by the host computer.

Uses date supplied by the host computer.

Connection to Host Computer

Keyboard connection only.

Designed for use with desktop computers.

Can be connected to the PC in various ways. CryptoKit supports only the keyboard connection type.

Designed for use with desktop computers.

Recommended for use with laptop computers

Recommended for any PC/laptop with a USB port

Plug&Play Does not support Does not support Supports Supports

Page 27: CryptoKit Developers Guide

Component-Related Technologies 2

2-13

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.

Page 28: CryptoKit Developers Guide

2 CryptoKit Developer's Guide

2-14

♦ 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.

Page 29: CryptoKit Developers Guide

Component-Related Technologies 2

2-15

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.

Page 30: CryptoKit Developers Guide

2 CryptoKit Developer's Guide

2-16

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.

Page 31: CryptoKit Developers Guide

Component-Related Technologies 2

2-17

Advanced Capabilities

CryptoKit supports a wide variety of cryptographic algorithms and functions:

Symmetric Algorithms DES 2DES 3DES AES RC2 RC4

Hash Algoritms MD5 SHA-1 SHA256 SHA384 SHA512 RIPEMD160

Asymmetric Algorithms RSA DSA Diffie-Hellman

Other SSL TLS 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.

Page 32: CryptoKit Developers Guide

2 CryptoKit Developer's Guide

2-18

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.

Page 33: CryptoKit Developers Guide

3-1

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 PKCS#11 plug-in

Serves as plug-in for Netscape Navigator, Baltimore

X.509 extension

PKCS#10,PKCS#7 extension

These extensions provide functionality for working with X.509 certificates (request, response, parsing)

PKCS#12 extension This extension provides import and export functionality of PKCS#12 files (PFX)

Page 34: CryptoKit Developers Guide

3 CryptoKit Developer's Guide

3-2

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.

Page 35: CryptoKit Developers Guide

SmartAdaptor Technology 3

3-3

JavaApplications

MS CAPIApplications

e.g.,IE/Outlook

PKCS#11-based Applicationse.g., Entrust, Baltimore, NetscapeU

ser

App

licat

ions

Ada

pter

s

Ext

ensi

ons

Sm

artA

dap

tor

JavaAdapter

CAPIAdapter

EntrustAdapter

X.509 PKCS#10,7

RegistrationAPI *

PKCS#11Extension

User Interface

SmartAdaptor Engine forMulti-thread, Multi-process,

Multi-slot, Multi-provider

SmartcardProvider API

ReaderProvider

API

Core PKCS#11Providers

AR PrivateCardProvider

CT-APIReaders

PCSCReaders

ProprietaryInterfaceReaders

Pro

vide

rs

PKCS#11

API

PKCS#12

* 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.

Page 36: CryptoKit Developers Guide

3 CryptoKit Developer's Guide

3-4

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.

Page 37: CryptoKit Developers Guide

SmartAdaptor Technology 3

3-5

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 Authentication Path

PIN entry from protected keypad, finger-print reader, and other devices

Page 38: CryptoKit Developers Guide

3 CryptoKit Developer's Guide

3-6

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.

Tokens

MiniKey ISO Smartcard – Private Card

Application Programming Interface (API)

Standard PKCS#11

AR or 3 rd Party Applications

AR CryptoKit PKCS#11

PIN Key Key Encryption/ Signatures/ PK-User Certificate Management Management Exchange Decryption Verification Authentication Processing (policies)

PrivateServer CoSign

Page 39: CryptoKit Developers Guide

SmartAdaptor Technology 3

3-7

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

Page 40: CryptoKit Developers Guide

3 CryptoKit Developer's Guide

3-8

Mechanisms Functions

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_SHA256_RSA_PKCS Sign/Verify

CKM_SHA384_RSA_PKCS Sign/Verify

CKM_SHA512_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

Page 41: CryptoKit Developers Guide

SmartAdaptor Technology 3

3-9

Mechanisms Functions

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

Page 42: CryptoKit Developers Guide

3 CryptoKit Developer's Guide

3-10

Mechanisms Functions

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_256_HMAC_GENERAL Sign/Verify

CKM_SHA_256_HMAC Sign/Verify

CKM_SHA_384 Digest

CKM_SHA_384_HMAC_GENERAL Sign/Verify

CKM_SHA_384_HMAC Sign/Verify

Page 43: CryptoKit Developers Guide

SmartAdaptor Technology 3

3-11

Mechanisms Functions

CKM_SHA_512 Digest

CKM_SHA_512_HMAC_GENERAL Sign/Verify

CKM_SHA_512_HMAC Sign/Verify

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_SHA256_KEY_DERIVATION Derive

CKM_SHA384_KEY_DERIVATION Derive

CKM_SHA512_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

Page 44: CryptoKit Developers Guide

3 CryptoKit Developer's Guide

3-12

Mechanisms Functions

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

Page 45: CryptoKit Developers Guide

SmartAdaptor Technology 3

3-13

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

Page 46: CryptoKit Developers Guide

3 CryptoKit Developer's Guide

3-14

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

Page 47: CryptoKit Developers Guide

SmartAdaptor Technology 3

3-15

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.

Page 48: CryptoKit Developers Guide

3 CryptoKit Developer's Guide

3-16

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.

Page 49: CryptoKit Developers Guide

SmartAdaptor Technology 3

3-17

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

Page 50: CryptoKit Developers Guide

3 CryptoKit Developer's Guide

3-18

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).

Page 51: CryptoKit Developers Guide

SmartAdaptor Technology 3

3-19

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.

Page 52: CryptoKit Developers Guide

3 CryptoKit Developer's Guide

3-20

♦ 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

Page 53: CryptoKit Developers Guide

SmartAdaptor Technology 3

3-21

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.

Page 54: CryptoKit Developers Guide

3 CryptoKit Developer's Guide

3-22

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.

Page 55: CryptoKit Developers Guide

SmartAdaptor Technology 3

3-23

Parameter Default Values for MiniKey and PrivateCard

Default Values for Software token

Explanation & Valid Values

Minimum period for PIN change

0 0 0 – PIN can be changed at any time 1-7 – Minimum number of days between PIN changes

Period of validity 889 days (which are 127weeks, approx. 2.5 years)

0

0 – PIN never expires 1-889 – Maximum number of days until the PIN will expire

Minimum PIN length

6 alphanumeric characters

5 alphanumeric characters

Maximum number of PIN retries for user

12

0 0 – Unlimited 3-12 – Number of allowed presentations. PIN locked afterwards

Maximum number of PIN retries for SO

6 0 0 – Unlimited 3-12 – Number of 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.

Page 56: CryptoKit Developers Guide

3 CryptoKit Developer's Guide

3-24

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.

Page 57: CryptoKit Developers Guide

SmartAdaptor Technology 3

3-25

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)

Page 58: CryptoKit Developers Guide

3 CryptoKit Developer's Guide

3-26

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

Page 59: CryptoKit Developers Guide

SmartAdaptor Technology 3

3-27

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;

Page 60: CryptoKit Developers Guide

3 CryptoKit Developer's Guide

3-28

For the Windows 32bit platform the following definition was used:

#define CK_CALLBACK_FUNCTION( returnType, name ) \ returnType( *name )

Page 61: CryptoKit Developers Guide

SmartAdaptor Technology 3

3-29

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.

Page 62: CryptoKit Developers Guide

3 CryptoKit Developer's Guide

3-30

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:

Page 63: CryptoKit Developers Guide

SmartAdaptor Technology 3

3-31

♦ 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

Page 64: CryptoKit Developers Guide

3 CryptoKit Developer's Guide

3-32

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.

Page 65: CryptoKit Developers Guide

SmartAdaptor Technology 3

3-33

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.

Page 66: CryptoKit Developers Guide

3 CryptoKit Developer's Guide

3-34

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.

Page 67: CryptoKit Developers Guide

SmartAdaptor Technology 3

3-35

� 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 UMB_PROVIDER_INFO * info,

const char * module,

const char * entry,

const UMB_ATR_DESCRIPTION * atr,

UMB_CONTEXT * context);

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.

Page 68: CryptoKit Developers Guide

3 CryptoKit Developer's Guide

3-36

♦ 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.

♦ context [out] – receives a pointer to the created context, upon successful termination of the function.

Note: Since all of these parameters are mandatory, they cannot be NULL.

Return Values

� UMB_RV_OK – context successfully created.

� 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_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 UMB_PROVIDER_INFO * info,

const char * module,

const char * entry,

Page 69: CryptoKit Developers Guide

SmartAdaptor Technology 3

3-37

UMB_CONTEXT * context);

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.

♦ context [out] – receives a pointer to the created context, upon successful termination of the function.

Note: Since all of these parameters are mandatory, they cannot be NULL.

Page 70: CryptoKit Developers Guide

3 CryptoKit Developer's Guide

3-38

Return Values

� UMB_RV_OK – context successfully created.

� 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_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.

Page 71: CryptoKit Developers Guide

SmartAdaptor Technology 3

3-39

� 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.

Page 72: CryptoKit Developers Guide

3 CryptoKit Developer's Guide

3-40

� 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.

� UMB_RV_INVALID_PARAMETERS – invalid parameter detected, a pointer is probably NULL.

� UMB_RV_MEMORY – insufficient memory.

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_CONTEXT * context,

UMB_ATR_DESCRIPTION * atr);

Parameters

♦ context [in] – the context of the provider for which to set the data.

♦ atr [in] – the description of the ATR to add to the context.

Return Values

� UMB_RV_OK – data successfully written to the context.

� UMB_RV_INVALID_PARAMETERS – invalid parameter detected, a pointer is probably NULL.

Page 73: CryptoKit Developers Guide

SmartAdaptor Technology 3

3-41

� UMB_RV_MEMORY – insufficient memory.

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.

Page 74: CryptoKit Developers Guide

3 CryptoKit Developer's Guide

3-42

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(

UMB_CONTEXT * context);

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.

Page 75: CryptoKit Developers Guide

SmartAdaptor Technology 3

3-43

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(

UMB_CONTEXT * context);

Parameter

♦ context [out] – the created context.

Return Values

� UMB_RV_OK – data successfully read.

� UMB_RV_MEMORY – insufficient memory.

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 (

UMB_CONTEXT * context,

Page 76: CryptoKit Developers Guide

3 CryptoKit Developer's Guide

3-44

UMB_COMPARE_STYLE flag,

int fieldTag,

int len,

const void * data);

Parameters

♦ context [in] – the context of the provider for which to set the data.

♦ 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.

Page 77: CryptoKit Developers Guide

SmartAdaptor Technology 3

3-45

� 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_RV_INVALID_PARAMETERS – invalid parameter detected.

� UMB_RV_MEMORY – insufficient memory.

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(

UMB_CONTEXT * context);

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.

Page 78: CryptoKit Developers Guide

3 CryptoKit Developer's Guide

3-46

� UMB_RV_INVALID_PARAMETERS – invalid parameter detected.

� UMB_RV_MEMORY – insufficient memory.

� UMB_RV_INTERNAL_ERROR – an internal error occurred.

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.

� UMB_RV_INVALID_PARAMETERS – invalid parameter detected.

� UMB_RV_MEMORY – insufficient memory.

Page 79: CryptoKit Developers Guide

SmartAdaptor Technology 3

3-47

� UMB_RV_INTERNAL_ERROR – an internal error occurred.

UMB_FreeContext

This function frees the memory associated with previously allocated context.

Syntax

UMB_RV UMBAPI UMB_FreeContext(

UMB_CONTEXT * context);

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);

Page 80: CryptoKit Developers Guide

3 CryptoKit Developer's Guide

3-48

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.

Page 81: CryptoKit Developers Guide

SmartAdaptor Technology 3

3-49

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.)

Page 82: CryptoKit Developers Guide

3 CryptoKit Developer's Guide

3-50

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.

Page 83: CryptoKit Developers Guide

SmartAdaptor Technology 3

3-51

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.

Page 84: CryptoKit Developers Guide

3 CryptoKit Developer's Guide

3-52

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;

UMB_READER_GET_NATIVE_RESULT_VALUE native_res_val ue;

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.

Page 85: CryptoKit Developers Guide

SmartAdaptor Technology 3

3-53

� 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_INTERNAL_ERROR – general error occured.

� 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.

Page 86: CryptoKit Developers Guide

3 CryptoKit Developer's Guide

3-54

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

♦ slotID [in] – number of the slot.

♦ 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

� UMB_RV_INTERNAL_ERROR – general error occured.

� UMB_RV_INVALID_PARAMETERS – when the slot number is invalid or when the pointer to slotState is NULL.

� UMB_RV_OK – operation successful.

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,

Page 87: CryptoKit Developers Guide

SmartAdaptor Technology 3

3-55

char * ATRBuf,

UINT32 * ATRlen);

Parameters

♦ slotID [in] – number of the slot.

♦ 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_INTERNAL_ERROR – general error occured.

� UMB_RV_INSUFFICIENT_BUFFER – when ATRBuf is too small.

� UMB_RV_INVALID_PARAMETERS – when the slot number is invalid or another parameter is NULL.

� UMB_RV_OK – operation successful.

UMB_READER_POWER_OFF

This function should power-off the smart card.

Syntax

typedef UMB_RV (UMBAPI * UMB_READER_POWER_OFF)

(UINT32 slotID);

Parameters

♦ slotID [in] – number of the slot.

Return Values

� UMB_RV_INTERNAL_ERROR – general error occured.

Page 88: CryptoKit Developers Guide

3 CryptoKit Developer's Guide

3-56

� UMB_RV_INVALID_PARAMETERS – when the slot number is invalid.

� UMB_RV_OK – operation successful.

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

♦ slotID [in] – number of the slot.

♦ 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_INTERNAL_ERROR – general error occured.

� UMB_RV_INSUFFICIENT_BUFFER – when ATRBuf is too small.

Page 89: CryptoKit Developers Guide

SmartAdaptor Technology 3

3-57

� UMB_RV_INVALID_PARAMETERS – when the slot number is invalid or another parameter is NULL.

� UMB_RV_OK – operation successful.

UMB_READER_GET_NATIVE_RESULT_VALUE

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_RV_INTERNAL_ERROR – general error occured.

� UMB_RV_INVALID_PARAMETERS – when the slot number is invalid or another parameter is NULL.

� UMB_RV_OK – operation successful.

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)

Page 90: CryptoKit Developers Guide

3 CryptoKit Developer's Guide

3-58

(void);

Parameters

None.

Return Values

� UMB_RV_INTERNAL_ERROR – general error occured.

� UMB_RV_OK – operation successful.

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.

� UMB_RV_OK – operation successful.

Page 91: CryptoKit Developers Guide

SmartAdaptor Technology 3

3-59

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

Page 92: CryptoKit Developers Guide

3 CryptoKit Developer's Guide

3-60

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.

Page 93: CryptoKit Developers Guide

SmartAdaptor Technology 3

3-61

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.

Page 94: CryptoKit Developers Guide

3 CryptoKit Developer's Guide

3-62

� 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

� CKR_OK – operation successful.

� CKR_CRYPTOKI_NOT_INITIALIZED – the Cryptoki has not been 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.

Page 95: CryptoKit Developers Guide

SmartAdaptor Technology 3

3-63

Syntax

CK_RV C_EXT_GetProviderContext(

CK_PROVIDER_ID provider_id,

UMB_CONTEXT * pContext);

Parameters

♦ provider_id [in] – the ID of the provider.

♦ pContext [in/out] – pointer to a buffer, which receives the provider’s context.

Return Values

� CKR_OK – operation successful.

� CKR_CRYPTOKI_NOT_INITIALIZED – the Cryptoki has not been 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_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_PROVIDER_ID provider_id,

CK_SLOT_ID_PTR pSlotList,

CK_ULONG_PTR pulCount);

Page 96: CryptoKit Developers Guide

3 CryptoKit Developer's Guide

3-64

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

♦ provider_id [in] – the ID of the provider.

♦ 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

� CKR_OK – operation successful.

� CKR_CRYPTOKI_NOT_INITIALIZED – the Cryptoki has not been 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_BUFFER_TOO_SMALL – the size of the slot list array is too small.

� CKR_FUNCTION_FAILED – incorrect parameters.

C_EXT_GetSlotProvider

This function returns the provider associated with a specific slot.

Syntax

CK_RV C_EXT_GetSlotProvider(

Page 97: CryptoKit Developers Guide

SmartAdaptor Technology 3

3-65

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

� CKR_OK – operation successful.

� CKR_CRYPTOKI_NOT_INITIALIZED – the Cryptoki has not been 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.

Page 98: CryptoKit Developers Guide

3 CryptoKit Developer's Guide

3-66

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_PROVIDER_ID provider_id,

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_SESSION_HANDLE hSession,

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);

Page 99: CryptoKit Developers Guide

SmartAdaptor Technology 3

3-67

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

� CKR_CRYPTOKI_NOT_INITIALIZED – the Cryptoki has not been 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).

Page 100: CryptoKit Developers Guide

3 CryptoKit Developer's Guide

3-68

� 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.

Page 101: CryptoKit Developers Guide

SmartAdaptor Technology 3

3-69

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_OK – operation successful.

� 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.

Page 102: CryptoKit Developers Guide

3 CryptoKit Developer's Guide

3-70

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_OK – operation successful.

� CKR_CRYPTOKI_NOT_INITIALIZED – the Cryptoki library has not been initialized.

� CKR_GENERAL_ERROR – the slot is not a bound dynamic slot.

Page 103: CryptoKit Developers Guide

SmartAdaptor Technology 3

3-71

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.

Page 104: CryptoKit Developers Guide

3 CryptoKit Developer's Guide

3-72

Return Values

� CKR_OK – event occurred.

� CKR_FUNCTION_FAILED – one of the arguments or a combination of arguments was invalid.

� CKR_CRYPTOKI_NOT_INITIALIZED – the Cryptoki has not been 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.

Page 105: CryptoKit Developers Guide

SmartAdaptor Technology 3

3-73

♦ 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.

� CKR_CRYPTOKI_NOT_INITIALIZED – the Cryptoki has not been initialized.

� CKR_NO_EVENT – no event occurred before the timeout expired.

Page 106: CryptoKit Developers Guide

3 CryptoKit Developer's Guide

3-74

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_SESSION_HANDLE hSession,

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

Page 107: CryptoKit Developers Guide

SmartAdaptor Technology 3

3-75

� CKR_TOKEN_NOT_PRESENT – token not present or was removed

� CKR_TOKEN_NOT_RECOGNIZED – token is not AR proprietary token or not proprietary formatted

Page 108: CryptoKit Developers Guide

3 CryptoKit Developer's Guide

3-76

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

Page 109: CryptoKit Developers Guide

SmartAdaptor Technology 3

3-77

♦ 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_OK – operation successful

� 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.

Page 110: CryptoKit Developers Guide

3 CryptoKit Developer's Guide

3-78

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

Page 111: CryptoKit Developers Guide

SmartAdaptor Technology 3

3-79

Init PIN Dialog

Change PIN Dialog

Page 112: CryptoKit Developers Guide

3 CryptoKit Developer's Guide

3-80

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_OK – operation successful

� CKR_CRYPTOKI_NOT_INITIALIZED – Cryptoki library not initialized with C_Initialize.

� CKR_GENERAL_ERROR – function failed

Page 113: CryptoKit Developers Guide

SmartAdaptor Technology 3

3-81

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_OK – operation successful

� CKR_CRYPTOKI_NOT_INITIALIZED – Cryptoki library not initialized with C_Initialize.

CKR_GENERAL_ERROR – function failed

Page 114: CryptoKit Developers Guide

3 CryptoKit Developer's Guide

3-82

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.

Page 115: CryptoKit Developers Guide

4-1

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 …

Page 116: CryptoKit Developers Guide

4 CryptoKit Developer's Guide

4-2

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

Page 117: CryptoKit Developers Guide

AR Cryptographic Service Provider 4

4-3

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.

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.

Crypto API

Crypto SPI

Application B Application A Application Layer

“Crypt…” API

ARCSP

Microsoft Base Crypto Provider

Service Provider

Operating System

CSP #1 CSP #2

Other Vendors CSP

CSP #…

“Cert…” API

System certificate store

Physical Store #1

Physical Store …

Page 118: CryptoKit Developers Guide

4 CryptoKit Developer's Guide

4-4

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 Property

Description

Key exchange algorithm

Each provider type specifies only one key exchange 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 signature algorithm

Each provider type specifies only one digital signature algorithm and every CSP of that type must implement the same algorithm. Applications specify the digital signature algorithm by selecting a CSP of the appropriate provider type.

Key BLOB formats

The provider type determines the format of the key BLOB used to export keys from the CSP and to import keys into a CSP.

Digital signature format

The provider type determines the digital signature format. This ensures that a signature produced by a CSP of a given provider type can be verified by any CSP of the same type.

Session key derivation scheme

The provider type determines the method used to derive a session key from a hash.

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

Page 119: CryptoKit Developers Guide

AR Cryptographic Service Provider 4

4-5

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.

Page 120: CryptoKit Developers Guide

4 CryptoKit Developer's Guide

4-6

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.

Page 121: CryptoKit Developers Guide

AR Cryptographic Service Provider 4

4-7

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.

Page 122: CryptoKit Developers Guide

4 CryptoKit Developer's Guide

4-8

♦ 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.

Page 123: CryptoKit Developers Guide

AR Cryptographic Service Provider 4

4-9

♦ 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.

Page 124: CryptoKit Developers Guide

4 CryptoKit Developer's Guide

4-10

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

CALG_SHA_384 SHA-384 hash algorithm

CALG_SHA_512 SHA-512 hash algorithm

Page 125: CryptoKit Developers Guide

AR Cryptographic Service Provider 4

4-11

Algorithm ID Description Comments

CALG_SSL3_SHAMD5

SHA & MD5 hash algorithm

CALG_MAC MAC keyed-hash algorithm

Block cipher MAC

CALG_HMAC MAC keyed-hash algorithm

HMAC computation

CALG_RSA_SIGN RSA public-key signature algorithm

Key length: adjustable, 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 algorithm

Same as CALG_RSA_SIGN

CALG_RC2 RC2 block encryption algorithm

Default key length: 128 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 algorithm

Default key length: 128 bits Salt not supported

CALG_DES DES block encryption algorithm

Key length: 56 bits Default mode: Cipher block chaining (CBC) padding

Page 126: CryptoKit Developers Guide

4 CryptoKit Developer's Guide

4-12

Algorithm ID Description Comments

CALG_3DES_112 2DES block encryption algorithm

Key length: 112 bits Default mode: Cipher block chaining (CBC) padding

CALG_3DES 3DES block encryption algorithm

Key length: 168 bits Default mode: Cipher block chaining (CBC) 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

CALG_SCHANNEL_MASTER_HASH

CALG_SCHANNEL_MAC_KEY

CALG_SCHANNEL_ENC_KEY

All these algorithms are used by the SChannel system to derive SSL3 and TLS session keys

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.

Page 127: CryptoKit Developers Guide

AR Cryptographic Service Provider 4

4-13

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.

Page 128: CryptoKit Developers Guide

4 CryptoKit Developer's Guide

4-14

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

Page 129: CryptoKit Developers Guide

AR Cryptographic Service Provider 4

4-15

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

Page 130: CryptoKit Developers Guide

4 CryptoKit Developer's Guide

4-16

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.

Page 131: CryptoKit Developers Guide

AR Cryptographic Service Provider 4

4-17

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.

Page 132: CryptoKit Developers Guide

4 CryptoKit Developer's Guide

4-18

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.

Page 133: CryptoKit Developers Guide

5-1

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.

Page 134: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-2

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.

Page 135: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-3

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/ CryptoSpec.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

Page 136: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-4

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

Page 137: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-5

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

Page 138: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-6

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.

Page 139: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-7

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();

Page 140: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-8

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.toCharA rray(), null); return true; } catch (Exception ex){ exc_abort(ex); } return false; } public boolean RSAverify(byte[] buffer, byte[] signature, KeyPair RSAk eys) { System.out.println("Verifying.."); try { PublicKey pub = RSAkeys.getPublic(); Signature sig=Signature.getInstance("SHA1w ithRSA", "ARJCA "); sig.initVerify(pub); sig.update(buffer); return sig.verify(signature); } catch (Exception e) {

Page 141: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-9

exc_abort(e); return false; } } public byte[] RSAsign(byte[] buffer, KeyPair RSA keys) { System.out.println("Signing.."); try { PrivateKey priv = RSAkeys.getPrivate(); Signature sig=Signature.getInstance("SHA1w ithRSA", "ARJCA "); sig.initSign(priv); sig.update(buffer); System.out.println("Sign OK"); return sig.sign(); } catch (Exception e) { 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; } catch (Exception e) { exc_abort(e); } return null; } }

Page 142: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-10

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.

Page 143: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-11

♦ 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

Page 144: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-12

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_SESSI ON | AR_JPKCS11SessionInfo.AR_JPKCS11_FLG_SERIAL_S ESSION, null, null); } else { return; } // Create the templates for RSA key pair generat ion 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)0 x1}; // Public key template attr_pub[0] = new AR_JPKCS11ObjectAttribute( AR_JPKCS11Object.AR_JPKCS11_CLASS, AR_JPKCS11Object.AR_JPKCS11_CLASS_PUBLI C_KEY); attr_pub[1] = new AR_JPKCS11ObjectAttribute( AR_JPKCS11Object.AR_JPKCS11_KEY_TYPE, AR_JPKCS11Object.AR_JPKCS11_KEY_TYPE_RS A); attr_pub[2] = new AR_JPKCS11ObjectAttribute( AR_JPKCS11Object.AR_JPKCS11_MODULUS_BIT S, new Integer(1024));

Page 145: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-13

attr_pub[3] = new AR_JPKCS11ObjectAttribute( AR_JPKCS11Object.AR_JPKCS11_PUBLIC_EXPO NENT, new BigInteger(Exponent)); // Private key template attr_priv[0] = new AR_JPKCS11ObjectAttribute( AR_JPKCS11Object.AR_JPKCS11_CLASS, AR_JPKCS11Object.AR_JPKCS11_CLASS_PRIVA TE_KEY); attr_priv[1] = new AR_JPKCS11ObjectAttribute( AR_JPKCS11Object.AR_JPKCS11_KEY_TYPE, AR_JPKCS11Object.AR_JPKCS11_KEY_TYPE_RS A); // 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] pr ivate AR_JPKCS11Object keys[] = sess.generateKeyPair(m ech_gen, attr_pub, attr_priv); AR_JPKCS11Mechanism mech_sign = new AR_NativePKCS11Mechanism( AR_JPKCS11Mechanism.AR_JPKCS11_MECH_MD5_R SA_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); }

Page 146: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-14

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 v5.1, v6.0

Works with Entrust/Authority to automate key 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.

Page 147: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-15

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.

Page 148: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-16

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.

Page 149: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-17

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.

Page 150: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-18

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.

Page 151: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-19

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 Info

Information about the enclosed public key, including the key itself, its size, and the algorithm it should be used for.

Issuer Unique Identifier

The CA’s unique identifier (added in version 2). This field is optional, and is not recommended for use.

Subject Unique Identifier

The user’s unique identifier (added in version 2). This 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.

Page 152: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-20

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 Certificates

List of the revoked certificates’ serial numbers, when they 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.

Page 153: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-21

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

ITU-T Recommendation X.500 (1997) | “Information Technology – Open Systems Interconnection – The Directory: Overview of concepts, models and services.”

ITU-T Recommendation X.501 (1997) | “Information Technology – Open Systems Interconnection – The Directory: Models.”

ITU-T Recommendation X.520 (1997) | “Information Technology – Open 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.

Page 154: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-22

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];

Page 155: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-23

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.versio n); 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);

Page 156: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-24

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 "ck_x509.h" #include <stdio.h> int main(int argc, char **argv) {

FILE * f; CK_BYTE encCert[5000];

CK_ULONG encCertLen; CK_RV rc; CK_ULONG version; CK_ULONG verLen; f = fopen(argv[1],"rb"); encCertLen = fread(encCert,1,5000,f); fclose(f); verLen = sizeof(version); rc = C_X509_GetField(CK_X509_ID_CERT, encCert,encCertLen,(CK_VOID_PTR)&versio n, &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

Page 157: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-25

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_VOID_PTR pEncoded,

CK_ULONG ulEncodedLen,

CK_VOID_PTR pDecoded,

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 "ck_x509.h" #include <stdio.h> int main(int argc, char **argv)

Page 158: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-26

{ FILE * f;

CK_BYTE encCert[5000]; CK_ULONG encCertLen; CK_RV rc; CK_SLOT_ID pSlotList[10]; CK_ULONG ulCount = 10; CK_SESSION_HANDLE hSession; f = fopen(argv[1],"rb"); encCertLen = fread(encCert,1,5000,f); 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,&hSe ssion); rc = C_X509_Verify(hSession,CK_INVALID_HANDLE, CK_X509_ID_CERT,encCert,encCertLen,NULL_P TR,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.

Page 159: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-27

♦ 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.

Page 160: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-28

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_SLOT_ID pSlotList[10]; CK_ULONG ulCount = 10; CK_SESSION_HANDLE hSession; CK_CHAR_PTR pin = "12345678"; CK_ULONG attribPrivateKey = CKO_PRIVATE_KEY;

Page 161: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-29

CK_ULONG attribRSA = CKK_RSA; CK_ATTRIBUTE findRSAPrivateKey[] = { {CKA_CLASS,&attribPrivateKey, sizeof(attribPrivat eKey)}, {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; } rc = C_Initialize(NULL_PTR); if (rc != CKR_OK) { printf("*** Error in C_Initialize – %x\n",rc); return rc; } rc = C_GetSlotList(FALSE,pSlotList,&ulCount); if (rc != CKR_OK) { printf("*** Error in C_GetSlotList – %x\n",rc); C_Finalize(NULL_PTR); return rc; } rc = C_OpenSession(pSlotList[0],CKF_RW_SESSION | CKF_SERIAL_SESSION,NULL_PTR,NULL_PTR,&hSe ssion); if (rc != CKR_OK) { printf("*** Error in C_OpenSession – %x\n",rc); C_Finalize(NULL_PTR);

Page 162: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-30

return rc; } rc = C_Login(hSession,CKU_USER,pin,8); if (rc != CKR_OK) { printf("*** Error in C_Login – %x\n",rc); C_Finalize(NULL_PTR); return rc; } rc = C_FindObjectsInit(hSession,findRSAPrivateKey, 2); if (rc != CKR_OK) { printf("*** Error in C_FindObjectsInit – %x\n",rc ); C_Finalize(NULL_PTR); return rc; } rc = C_FindObjects(hSession,&hPrivateKey,1, &ulObj ectsFound); if ((rc != CKR_OK) || (ulObjectsFound != 1)) { printf("*** Error in C_FindObjects – %x, ulObjectsFound=%d\n",rc,ulObjectsFound) ; C_Finalize(NULL_PTR); return rc; } rc = C_FindObjectsFinal(hSession); if (rc != CKR_OK) { printf("*** Error in C_FindObjectsFinal – %x\n",r c); C_Finalize(NULL_PTR); return rc; } rc = C_X509_Sign(hSession,hPrivateKey,type,pCertBu f, encTbsLen,encoded,encodedLen); if (rc != CKR_OK) { printf("*** Error signing – %x\n",rc); C_Finalize(NULL_PTR); return rc; } rc = C_Logout(hSession); if (rc != CKR_OK) { printf("*** Error in C_Logout - %x\n",rc); C_Finalize(NULL_PTR); return rc; } C_Finalize(NULL_PTR);

Page 163: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-31

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_VOID_PTR pDecoded,

CK_ULONG ulDecodedLen,

CK_VOID_PTR pEncoded,

CK_ULONG_PTR pulEncodedLen);

Page 164: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-32

The formal declaration of C_X509_Sign is:

int C_X509_Sign(CK_SESSION_HANDLE hSess,

CK_OBJECT_HANDLE hKey,

CK_ASN_ID Type,

CK_VOID_PTR pObject,

CK_ULONG ulObjectLen,

CK_VOID_PTR pSignedObject,

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 "ck_x509.h" #include <stdio.h> int main(int argc, char **argv) {

FILE * f; CK_BYTE encCert[5000];

CK_ULONG encCertLen; CK_BYTE encCrl[5000]; CK_ULONG encCrlLen; CK_RV rc; CK_ULONG result; f = fopen(argv[1],"rb"); encCertLen = fread(encCert,1,5000,f);

Page 165: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-33

fclose(f); f = fopen(argv[2],"rb"); encCrlLen = fread(encCrl,1,5000,f); fclose(f); rc = C_X509_FindInCRL(encCert,encCertLen,encCrl, encCrlLen,CK_X509_ID_CERT,NULL,N ULL,&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_X50 9_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.

Page 166: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-34

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,encCr l, 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.

Page 167: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-35

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 "ck_x509.h" #include <stdio.h> #include <stdlib.h> int main(int argc, char **argv) {

FILE * f; X509_certificate * certificate;

CK_BYTE encCert[5000]; CK_BYTE decCert[5000]; CK_ULONG encCertLen; CK_ULONG decCertLen = sizeof(decCert); CK_BYTE dnameBuf[1000]; CK_ULONG dnameBufLen = sizeof(dnameBuf); X509_Dname * issuerDname; 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,&decCertL en); certificate = (X509_certificate *)decCert; rc = C_X509_Copy(CK_X509_ID_DNAME, &(certificate-> tbs.issuer), 1000,dnameBuf,&dnameBufLen);

Page 168: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-36

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);

Page 169: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-37

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.

Page 170: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-38

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

Page 171: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-39

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.

Certificate/CRL Fields

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 CK_X509_CRL_FIELD_EXT_CRL_NUMBER

The CRL_number (X509_ext_2920) extension.

CK_X509_CRL_FIELD_EXT_2921 CK_X509_CRL_FIELD_EXT_REASON_CODE

The CRL_reason (X509_ext_2921) extension.

CK_X509_CRL_FIELD_EXT_2923 CK_X509_CRL_FIELD_EXT_INSTRUCTION_CODE

The HoldInstructionCode (X509_ext_2923) extension.

CK_X509_CRL_FIELD_EXT_2924 CK_X509_CRL_FIELD_EXT_INVALIDITY_DATE

The InvalidityDate (X509_ext_2924) extension.

CK_X509_CRL_FIELD_EXT_2927 CK_X509_CRL_FIELD_EXT_DELTA_CRL_INDICATOR

The DeltaCRLIndicator (X509_ext_2927) extension.

CK_X509_CRL_FIELD_EXT_2928 CK_X509_CRL_FIELD_EXT_ISSUING_DIST_POINT

The IssuingDistributionPoint (X509_ext_2928) extension.

Page 172: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-40

Certificate/CRL Fields

CK_X509_CRL_FIELD_EXT_2929 CK_X509_CRL_FIELD_EXT_CERT_ISSUER

The CertificateIssuer (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 certificate to be signed.

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 certificate to be signed.

Page 173: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-41

Certificate/CRL Fields

CK_X509_CERT_FIELD_ISSUER_ID The issuer_id field of the certificate to be signed.

CK_X509_CERT_FIELD_SUBJECT_ID The subject_id field of the certificate to be signed.

CK_X509_CERT_FIELD_EXTENSIONS The extensions field of the certificate to be signed.

CK_X509_CERT_FIELD_EXT_2914 CK_X509_CERT_FIELD_EXT_SUBJECT_KEY_ID

The X509_ext_2914 extensions field (if it exists).

CK_X509_CERT_FIELD_EXT_2915 CK_X509_CERT_FIELD_EXT_KEY_USAGE

The X509_ext_2915 extension field (if it exists).

CK_X509_CERT_FIELD_EXT_2916 CK_X509_CERT_FIELD_EXT_PRIV_USAGE_PERIOD

The X509_ext_2916 extension field (if it exists).

CK_X509_CERT_FIELD_EXT_2917 CK_X509_CERT_FIELD_EXT_SUBJECT_ALT_NAME

The subject_alt_name extension field (X509_ext_2917_8) (if it exists).

CK_X509_CERT_FIELD_EXT_2918 CK_X509_CERT_FIELD_EXT_ISSUER_ALT_NAME

The issuer_alt_name extension field (X509_ext_2917_8) (if it exists).

CK_X509_CERT_FIELD_EXT_2919 CK_X509_CERT_FIELD_EXT_BASIC_CONSTRAINTS

The X509_ext_2919 extension field (if it exists).

CK_X509_CERT_FIELD_EXT_2930 CK_X509_CERT_FIELD_EXT_NAME_CONSTRAINTS

The X509_ext_2930 extension field (if it exists).

CK_X509_CERT_FIELD_EXT_2931 CK_X509_CERT_FIELD_EXT_CRL_DIST_POINT

The X509_ext_2931 extension field (if it exists).

CK_X509_CERT_FIELD_EXT_2932 CK_X509_CERT_FIELD_EXT_CERTIFICATE_POLICIES

The X509_ext_2932 extension field (if it exists).

CK_X509_CERT_FIELD_EXT_2933 CK_X509_CERT_FIELD_EXT_POLICY_MAPPING

The X509_ext_2933 extension field (if it exists).

Page 174: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-42

Certificate/CRL Fields

CK_X509_CERT_FIELD_EXT_2935 CK_X509_CERT_FIELD_EXT_AUTH_KEY_ID

The X509_ext_2935 extension field (if it exists).

CK_X509_CERT_FIELD_EXT_2936 CK_X509_CERT_FIELD_EXT_POLICY_CONSTRAINTS

The X509_ext_2936 extension field (if it exists).

CK_X509_CERT_FIELD_EXT_2937 CK_X509_CERT_FIELD_EXT_EXTENDED_KEY_USAGE

The X509_ext_2937 extension field (if it exists).

Page 175: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-43

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.

Page 176: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-44

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 *.

Page 177: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-45

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 ASN1_OI_MD4_RSA ASN1_OI_MD5_RSA ASN1_OI_SHA1_RSA ASN1_OI_RIPEMD128_RSA ASN1_OI_RIPEMD160_RSA

Hash algorithms with RSA signature

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 ASN1_OI_MD4_HASH ASN1_OI_MD5_HASH ASN1_OI_SHA1_HASH ASN1_OI_RIPEMD128_HASH ASN1_OI_RIPEMD160_HASH

Hash algorithms

ASN1_OI_DH Diffie-Hellman key exchange

Page 178: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-46

Object Identifiers: Algorithm Identifiers

ASN1_OI_RC2_CBC 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

Symmetric encryption algorithms in different modes

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

Page 179: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-47

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 Distinguis hed 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

Page 180: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-48

Object Identifiers: Attribute Types (for Distinguis hed 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

Page 181: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-49

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

Page 182: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-50

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

Page 183: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-51

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.

Page 184: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-52

Page 185: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-53

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.

Page 186: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-54

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;

Page 187: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-55

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

X509_signature signature; // 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

X509_extensions extensions; // 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.

Page 188: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-56

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;

Page 189: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-57

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;

Page 190: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-58

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;

Page 191: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-59

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.

Page 192: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-60

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

Page 193: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-61

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;

Page 194: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-62

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

X509_extensions extensions; // 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;

Page 195: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-63

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;

Page 196: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-64

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

Page 197: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-65

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 {

Page 198: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-66

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

Page 199: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-67

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;

Page 200: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-68

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;

Page 201: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-69

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

Page 202: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-70

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;

Page 203: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-71

} 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;

Page 204: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-72

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;

Page 205: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-73

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_VOID_PTR pEncoded,

CK_ULONG ulEncodedLen,

CK_VOID_PTR pDecoded,

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.

Page 206: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-74

♦ 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_VOID_PTR pDecoded,

CK_ULONG ulDecodedLen,

CK_VOID_PTR pEncoded,

CK_ULONG_PTR pulEncodedLen);

Parameters

♦ Type [in] – the internal type of the structure (Certificate, CRL).

♦ pDecoded [in] – the decoded data structure.

Page 207: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-75

♦ 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

� 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 pulEncodedLen.

� CKR_X509_BAD_STRUCTURE – a bad data structure was given to the function.

� CKR_ARGUMENTS_BAD – one of the function parameters is invalid.

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_VOID_PTR pEncoded,

CK_ULONG ulEncodedLen,

CK_VOID_PTR pDecoded,

CK_ULONG_PTR pulDecodedLen,

Page 208: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-76

CK_X509_FIELD Field);

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 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

� 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_Copy

C_X509_Copy copies a complex structure into a duplicate in a continuous memory block.

Page 209: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-77

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

� 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 pulDstLen.

� CKR_ARGUMENTS_BAD – one of the function parameters is invalid.

� CKR_BADLY_FORMATTED_INPUT – a bad structure was given to the function.

Page 210: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-78

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_OBJECT_HANDLE hKey,

CK_ASN_ID Type,

CK_VOID_PTR pObject,

CK_ULONG ulObjectLen,

CK_VOID_PTR pSignedObject,

CK_ULONG_PTR pulSignedObjectLen);

Parameters

♦ hSess [in] – handle to a cryptographic session.

♦ hKey [in] – handle to the private key object of the signer.

♦ Type [in] – the internal type of the structure (Certificate, CRL).

♦ 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.

Page 211: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-79

♦ 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

� 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 pulSignedObjectLen.

� CKR_BADLY_FORMATTED_INPUT – pObject is not a valid BER encoded structure of type Type.

� CKR_ARGUMENTS_BAD – one of the function parameters is invalid.

� 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.

Page 212: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-80

Syntax

int C_X509_EncodeSign(

CK_SESSION_HANDLE hSess,

CK_OBJECT_HANDLE hKey,

CK_ASN_ID Type,

CK_VOID_PTR pDecoded,

CK_ULONG ulDecodedLen,

CK_VOID_PTR pSignedObject,

CK_ULONG_PTR pulSignedObjectLen);

Parameters

♦ hSess [in] – handle to a cryptographic session.

♦ hKey [in] – handle to the private key object of the signer.

♦ Type [in] – the internal type of the structure (Certificate, CRL).

♦ 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

� CKR_OK – function was completed successfully.

Page 213: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-81

� CKR_BUFFER_TOO_SMALL – the buffer supplied was too small. The amount of memory required (beyond what was supplied) is returned in pulSignedObjectLen.

� CKR_X509_BAD_STRUCTURE – pDecoded is not a valid data structure of type Type.

� CKR_ARGUMENTS_BAD – one of the function parameters is invalid.

� 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 – 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(

CK_SESSION_HANDLE hSess,

CK_OBJECT_HANDLE hKey,

Page 214: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-82

CK_ASN_ID Type,

CK_VOID_PTR pSignedObject,

CK_ULONG ulSignedObjectLen,

CK_VOID_PTR pCACert,

CK_ULONG ulCACertLen);

Parameters

♦ hSess [in] – handle to a cryptographic session.

♦ hKey [in] – handle to the public key object of the signer.

♦ Type [in] – the internal type of the structure (Certificate, CRL).

♦ 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_OK – function was completed successfully.

� 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.

Page 215: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-83

� CKR_BADLY_FORMATTED_INPUT – pSignedObject is not a valid BER encoded structure of type Type.

� CKR_ARGUMENTS_BAD – one of the function parameters is invalid.

� 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 – 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

Page 216: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-84

♦ 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.

Page 217: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-85

� 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_OK – function was completed successfully.

� CKR_BADLY_FORMATTED_INPUT – pEncodedObj or pEncodedCrl is not a valid BER encoded structure.

� CKR_ARGUMENTS_BAD – one of the function parameters is invalid.

� CKR_X509_BAD_STRUCTURE- a bad structure was given to the function (when X509_tbs is given as input).

Page 218: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-86

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.

Page 219: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-87

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.

Page 220: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-88

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.

Page 221: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-89

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;

X509_signature signature;

} 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).

Page 222: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-90

♦ 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.

Page 223: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-91

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 {

Page 224: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-92

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.

Page 225: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-93

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(

CK_SESSION_HANDLE hSess,

CK_OBJECT_HANDLE hKey,

CRQ_FORMAT crqFormat,

pkcs10_cr CK_PTR pCR,

CK_BYTE_PTR pEncodedCrq,

CK_ULONG_PTR pulEncodedCrqLen);

Parameters

♦ hSess [in] – handle to a cryptographic session.

♦ hKey [in] – handle to the user’s private key.

♦ crqFormat [in] – the format of the output certificate request.

Page 226: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-94

♦ 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(

CK_SESSION_HANDLE hSess,

CK_OBJECT_HANDLE hKey,

CRQ_FORMAT crqFormat,

simple_dname CK_PTR pDname,

CK_ULONG ulNumOfRDNs,

CK_BYTE_PTR pEncodedCrq,

CK_ULONG_PTR pulEncodedCrqLen);

Parameters

♦ hSess [in] – handle to a cryptographic session.

♦ 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.

Page 227: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-95

♦ 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 encoded data, or the required size, if the buffer is not large enough.

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_SESSION_HANDLE hSess,

CRQ_FORMAT crqFormat,

CK_BYTE_PTR pEncodedCrq,

CK_ULONG ulEncodedCrqLen,

CK_BYTE_PTR pDecodedCrq,

CK_ULONG_PTR pulDecodedCrqLen);

Parameters

♦ hSess [in] – handle to a cryptographic session.

♦ 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.

Page 228: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-96

♦ 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(

CK_SESSION_HANDLE hSess,

CRP_FORMAT crpFormat,

CK_BYTE_PTR pEncodedCrp,

CK_ULONG ulEncodedCrpLen,

CK_BYTE_PTR pDecodedCrp,

CK_ULONG_PTR pulDecodedCrpLen,

cert_list CK_PTR pCACerts);

Parameters

♦ hSess [in] – handle to a cryptographic session.

♦ 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.

Page 229: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-97

♦ 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 encoded data, or the required size, if the buffer is not large enough.

Page 230: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-98

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; CK_SLOT_ID pSlotList[10]; CK_ULONG ulCount = 10; CK_SESSION_HANDLE hSession; // Attributes for finding the private key object CK_ULONG attribPrivateKey = CKO_PRIVATE_KEY; CK_ULONG attribRSA = CKK_RSA; CK_ULONG attribDSA = CKK_DSA; CK_ATTRIBUTE findRSAPrivateKey[] = { {CKA_CLASS,&attribPrivateKey,sizeof(attribPrivate Key)}, {CKA_KEY_TYPE,&attribRSA,sizeof(attribRSA)},}; CK_ATTRIBUTE findDSAPrivateKey[] = { {CKA_CLASS,&attribPrivateKey,sizeof(attribPrivate Key)}, {CKA_KEY_TYPE,&attribDSA,sizeof(attribDSA)},};

Page 231: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-99

CK_ULONG ulObjectsFound; 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 forma ts, 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 rc = C_Initialize(NULL_PTR); if (rc != CKR_OK) { printf("*** Error in C_Initialize – %x\n",rc); exit(0); } rc = C_GetSlotList(FALSE,pSlotList,&ulCount); if (rc != CKR_OK) { printf("*** Error in C_GetSlotList – %x\n",rc); exit(0); } rc = C_OpenSession(pSlotList[0],CKF_RW_SESSION |CKF_SERIAL_SESSION,NULL_PTR,NULL_PTR, &hSession); if (rc != CKR_OK) { printf("*** Error in C_OpenSession – %x\n",rc); exit(0); } rc = C_Login(hSession,CKU_USER,NULL_PTR,0); if (rc != CKR_OK) {

Page 232: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-100

printf("*** Error in C_Login – %x\n",rc); C_Finalize(NULL_PTR); exit(0); } // Find private key object if (keyType == ASN1_OI_DSA) rc = C_FindObjectsInit(hSession,findDSAPrivateKey ,2); else rc = C_FindObjectsInit(hSession,findRSAPrivateKey ,2); if (rc != CKR_OK) { printf("*** Error in C_FindObjectsInit – %x\n",rc ); C_Finalize(NULL_PTR); exit(0); } rc = C_FindObjects(hSession,&hPrivateKey,1,&ulObje ctsFound); if ((rc != CKR_OK) || (ulObjectsFound != 1)) { printf("*** Error in C_FindObjects – %x, ulObjectsFound=%d\n",rc,u lObjectsFound); C_Finalize(NULL_PTR); exit(0); } rc = C_FindObjectsFinal(hSession); if (rc != CKR_OK) { printf("*** Error in C_FindObjectsFinal – %x\n",r c); C_Finalize(NULL_PTR); exit(0); } // Create the PKCS#10 CRQ rc = C_PKCS10_SimpleCreateCRQ(hSession,hPrivateKey , crqFormat,dnames,3, encodedCrq,&en codedCrqLen); if (rc != CKR_OK) { printf("*** Error %x in SimpleCreatePKCS10CRQ\n", rc); C_Finalize(NULL_PTR); exit(0); } // Save CRQ to file f = fopen(fname,"wb"); if (f) {

Page 233: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-101

fwrite(encodedCrq,1,encodedCrqLen,f); fclose(f); printf("CRQ created successfully and saved in fil e % 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); C_Finalize(NULL_PTR); 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.

Page 234: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-102

♦ 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 "ck_pk107.h" #include "pkcs11.h" int main(int argc, char **argv) { FILE * f; char fname[32]; CK_SLOT_ID pSlotList[10]; CK_ULONG ulCount = 10; CK_SESSION_HANDLE hSess; CK_CHAR_PTR pin = "12345678";

Page 235: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-103

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 f = fopen(argv[1],"rb"); 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 rc = C_Initialize(NULL_PTR); if (rc != CKR_OK) { printf("*** Error in C_Initialize – %x\n",rc); exit(0); } rc = C_GetSlotList(FALSE,pSlotList,&ulCount); if (rc != CKR_OK) { printf("*** Error in C_GetSlotList – %x\n",rc); exit(0); }

Page 236: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-104

rc = C_OpenSession(pSlotList[0],CKF_RW_SESSION | CKF_SERIAL_SESSION,NULL_PTR,NUL L_PTR,&hSess); if (rc != CKR_OK) { printf("*** Error in C_OpenSession – %x\n",rc); exit(0); } // The value of crpFormat doesn't really matter si nce the // function determines the format according to the input rc = C_PKCS7_AcceptCRP(hSess,crpFormat,encodedCr p,encodedCrpLen, decodedCrp,&deco dedCrpLen,NULL); if (rc != CKR_OK) { printf("*** Error in C_PKCS7_AcceptCRP – %x\n",rc ); C_Finalize(NULL_PTR); 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); f = fopen(fname,"wb"); if (f) { fwrite(CertsAndCrls ->certs>certs[i],1,Certs AndCrls ->certs->certLen[i],f); printf("Certificate written to file %s\n",fname); } else printf("*** Error – Failed to open file %s for ou tput\n",fname); } } // Write CRLs to files

Page 237: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-105

if (CertsAndCrls->crls) { for (i=0;i<CertsAndCrls->crls->numOfCerts;i++) { sprintf(fname,"crl%d.crl",i+1); f = fopen(fname,"wb"); if (f) { fwrite(CertsAndCrls->crls ->certs[i],1,CertsAndCrl s ->crls->certLen[i],f); printf("Certificate written to file %s\n",fname); } else printf("*** Error – Failed to open file %s for ou tput\n",fname); } } // End crypto C_Finalize(NULL_PTR); 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.

Page 238: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-106

♦ 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 "ck_pk107.h" #include "pkcs11.h" #include "ck_x509.h" CK_RV GetKeyHandle(CK_SESSION_HANDLE hSession, CK_OBJECT_HANDLE CK_PTR hKey, int alg_id);

Page 239: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-107

int main(int argc, char **argv) { FILE * f; CK_SLOT_ID pSlotList[10]; CK_ULONG ulCount = 10; 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 for mat> <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)Ver iSign csr\n"); printf("\t<SN> = Serial number to be given to the new cert ificate\n\n"); exit(0);

Page 240: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-108

} // Read the CA certificate from file f = fopen(argv[1],"rb"); 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 f = fopen(argv[2],"rb"); 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;

Page 241: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-109

// Start crypto rc = C_Initialize(NULL_PTR); if (rc != CKR_OK) { printf("*** Error in C_Initialize – %x\n",rc); exit(0); } rc = C_GetSlotList(FALSE,pSlotList,&ulCount); if (rc != CKR_OK) { printf("*** Error in C_GetSlotList – %x\n",rc); exit(0); } rc = C_OpenSession(pSlotList[0],CKF_RW_SESSION| CKF_SERIAL_SESSION, NULL_PTR,NULL _PTR,&hSess); if (rc != CKR_OK) { printf("*** Error in C_OpenSession – %x\n",rc); exit(0); } // Verify and parse certificate request rc = C_PKCS10_AcceptCRQ(hSess,crqFormat,encodedCr q,encodedCrqLen, decodedCrq,&d ecodedCrqLen); if (rc != CKR_OK) { printf("*** Error %x in C_PKCS10_AcceptCRQ\n",rc) ; C_Finalize(NULL_PTR); exit(0); } pCr = (pkcs10_cr *)decodedCrq; // Decode CA certificate rc = C_X509_Decode(CK_X509_ID_CERT,encodedCrt,enco dedCrtLen, decodedCrt,&d ecodedCrtLen); if (rc != CKR_OK) { printf("*** Error in C_X509_Decode – %x\n",rc); C_Finalize(NULL_PTR); exit(0); } pCert = (X509_certificate *)decodedCrt;

Page 242: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-110

// Create new certificate using CA certificate dat a 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.in t_id = pCr->cri.subject_key_info.algorithm_id.alg_id.int _id; pCert->tbs.subject_key_info.algorithm_id.alg_id.ch ar_id = pCr->cri.subject_key_info.algorithm_id.alg_id.cha r_id; pCert->tbs.subject_key_info.algorithm_id.params.pt r = pCr->cri.subject_key_info.algorithm_id.params.ptr ; pCert->tbs.subject_key_info.algorithm_id.params.si ze = pCr->cri.subject_key_info.algorithm_id.params.siz e; 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.validit y.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) { printf("*** Error in C_Login – %x\n",rc); C_Finalize(NULL_PTR); exit(0); } // Find the signing key

Page 243: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-111

rc = GetKeyHandle(hSess,&hKey,pCert ->signature.sign_alg.al g_id.int_id); if (rc != CKR_OK) { C_Finalize(NULL_PTR); 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,pCer t,decodedCrtLen, encodedCrt,&en codedCrtLen); 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); C_Finalize(NULL_PTR); exit(0); } C_Finalize(NULL_PTR); // Prepare certs_and_crls structure for PKCS#7 cer t 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); }

Page 244: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-112

// Save crp to file f = fopen(outFile[crpFormat-1], "wb"); if (!f) { printf("*** Error opening file %s for output\n",outFile[c rpFormat-1]); exit(0); } fwrite(encodedCrp,1,encodedCrpLen,f); fclose(f); printf("Certificate reply saved to file %s\n",outFile[c rpFormat-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 attribPrivateKey = CKO_PRIVATE_KEY; CK_ULONG attribRSA = CKK_RSA; CK_ULONG attribDSA = CKK_DSA; CK_ATTRIBUTE findRSAPrivateKey[] = { {CKA_CLASS,&attribPrivateKey,sizeof(attribPriv ateKey)}, {CKA_KEY_TYPE,&attribRSA,sizeof(attribRSA)},}; CK_ATTRIBUTE findDSAPrivateKey[] = { {CKA_CLASS,&attribPrivateKey,sizeof(attribPriv ateKey)}, {CKA_KEY_TYPE,&attribDSA,sizeof(attribDSA)},}; CK_ULONG ulObjectsFound; if ((alg_id == ASN1_OI_DSA) || (alg_id == ASN1_OI_ SHA1_DSA)) rc = C_FindObjectsInit(hSession,findDSAPrivateKey ,2); else rc = C_FindObjectsInit(hSession,findRSAPrivateKey ,2); if (rc != CKR_OK) { printf("*** Error in C_FindObjectsInit – %x\n",rc ); return rc; } rc = C_FindObjects(hSession,hKey,1,&ulObjectsFound );

Page 245: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-113

if ((rc != CKR_OK) || (ulObjectsFound != 1)) { printf("*** Error in C_FindObjects – %x, ulObjectsFound=%d\n",rc,ulO bjectsFound); return rc; } rc = C_FindObjectsFinal(hSession); if (rc != CKR_OK) { printf("*** Error in C_FindObjectsFinal – %x\n",r c); 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.

Page 246: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-114

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

Page 247: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-115

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.

Page 248: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-116

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(

CK_SESSION_HANDLE hSession,

char * pfxfile,

char * password,

char errmsg[128]);

Parameters

Page 249: CryptoKit Developers Guide

SmartAdaptor Add-On Adapters 5

5-117

♦ 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_OK – function was completed successfully.

� 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_SESSION_HANDLE hSession,

CK_OBJECT_HANDLE hPrivKey,

char * outfile,

char * password,

CK_MECHANISM_TYPE mech,

char errmsg[128]);

Parameters

Page 250: CryptoKit Developers Guide

5 CryptoKit Developer's Guide

5-118

♦ 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

Page 251: CryptoKit Developers Guide

6-1

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

Page 252: CryptoKit Developers Guide

6 CryptoKit Developer's Guide

6-2

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

Page 253: CryptoKit Developers Guide

SmartAdaptor Utilities 6

6-3

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.

Page 254: CryptoKit Developers Guide

6 CryptoKit Developer's Guide

6-4

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.

Note: It is possible to hide this option by setting an entry in the registry. Please 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:

Page 255: CryptoKit Developers Guide

SmartAdaptor Utilities 6

6-5

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.

Page 256: CryptoKit Developers Guide

6 CryptoKit Developer's Guide

6-6

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.

Page 257: CryptoKit Developers Guide

SmartAdaptor Utilities 6

6-7

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.

Page 258: CryptoKit Developers Guide

6 CryptoKit Developer's Guide

6-8

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.

Page 259: CryptoKit Developers Guide

SmartAdaptor Utilities 6

6-9

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:

Page 260: CryptoKit Developers Guide

6 CryptoKit Developer's Guide

6-10

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.

Page 261: CryptoKit Developers Guide

SmartAdaptor Utilities 6

6-11

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.

Page 262: CryptoKit Developers Guide

6 CryptoKit Developer's Guide

6-12

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.

Page 263: CryptoKit Developers Guide

SmartAdaptor Utilities 6

6-13

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.

Page 264: CryptoKit Developers Guide

6 CryptoKit Developer's Guide

6-14

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.

Page 265: CryptoKit Developers Guide

SmartAdaptor Utilities 6

6-15

When a certificate object is selected, the following window is displayed:

Page 266: CryptoKit Developers Guide

6 CryptoKit Developer's Guide

6-16

Click the View certificate button to view the contents of the certificate:

Page 267: CryptoKit Developers Guide

SmartAdaptor Utilities 6

6-17

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.

Page 268: CryptoKit Developers Guide

6 CryptoKit Developer's Guide

6-18

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.

Note: It is possible to hide this option by setting an entry in the registry. Please refer to explanation about GenieDeleteMode parameter in Chapter 7.

Page 269: CryptoKit Developers Guide

SmartAdaptor Utilities 6

6-19

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.

Page 270: CryptoKit Developers Guide

6 CryptoKit Developer's Guide

6-20

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"]

Page 271: CryptoKit Developers Guide

SmartAdaptor Utilities 6

6-21

Parameters: slotId – The number of the slot you want to change the user PIN. If omitted, the default is slot 1. 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.

Page 272: CryptoKit Developers Guide

6 CryptoKit Developer's Guide

6-22

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, the default is slot 1. filename – The output filename. If omitted it will be "DumpToken.txt". oldPin – The current user PIN. If omitted the PIN dialog will be displayed.

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. oldPin – The current user PIN. If omitted the PIN dialog will be displayed. filePin – The PFX file password. May be omitted if the PFX is not protected by a password.

Page 273: CryptoKit Developers Guide

SmartAdaptor Utilities 6

6-23

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. oldPin – The current user PIN. If omitted the PIN dialog will be displayed.

Page 274: CryptoKit Developers Guide

6 CryptoKit Developer's Guide

6-24

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.

Page 275: CryptoKit Developers Guide

SmartAdaptor Utilities 6

6-25

♦ 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.

Page 276: CryptoKit Developers Guide

6 CryptoKit Developer's Guide

6-26

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:

Page 277: CryptoKit Developers Guide

SmartAdaptor Utilities 6

6-27

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.

Page 278: CryptoKit Developers Guide

7-1

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.

Page 279: CryptoKit Developers Guide

7 CryptoKit Developer's Guide

7-2

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.

Page 280: CryptoKit Developers Guide

Installation 7

7-3

In the License Agreement screen, click I accept the license agreement and then click the Next button.

Page 281: CryptoKit Developers Guide

7 CryptoKit Developer's Guide

7-4

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.

Page 282: CryptoKit Developers Guide

Installation 7

7-5

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.

Page 283: CryptoKit Developers Guide

7 CryptoKit Developer's Guide

7-6

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.

Page 284: CryptoKit Developers Guide

Installation 7

7-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:

Page 285: CryptoKit Developers Guide

7 CryptoKit Developer's Guide

7-8

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.

Page 286: CryptoKit Developers Guide

Installation 7

7-9

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.

Page 287: CryptoKit Developers Guide

7 CryptoKit Developer's Guide

7-10

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.

Page 288: CryptoKit Developers Guide

Installation 7

7-11

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 t he 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.

Page 289: CryptoKit Developers Guide

7 CryptoKit Developer's Guide

7-12

♦ 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 Micros oft SMS server '================================================== ============= '-------------------------------------------------- ------------- ' Variables declaration '-------------------------------------------------- ------------- Dim objFileSystem, objShell, objProvEnv Dim strTmpDir, strRegistry, strSourceDir, strDestDi r '-------------------------------------------------- ------------- ' !!! Change strSourceDir to the name of a shared d irectory !!! ' !!! where the CryptoKit setup files are located !!! '-------------------------------------------------- ------------- strSourceDir = "\\Server_Name\Share_Name" '-------------------------------------------------- ------------- ' Initialize Variables '-------------------------------------------------- -------------

Page 290: CryptoKit Developers Guide

Installation 7

7-13

On Error Resume Next Set objShell = CreateObject("Wscript.Shell") Set objFileSystem = CreateObject("Scripting.FileSys temObject") Set objProvEnv = objShell.Environment("Process") '-------------------------------------------------- ------------- ' Read from registry and quit if CryptoKit is alrea dy installed '-------------------------------------------------- ------------- strRegistry = objShell.RegRead("HKLM\Software\ARL\SmartAdaptor\Ma in\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(s trTmpDir)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""" & s trdestDir & "\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

Page 291: CryptoKit Developers Guide

7 CryptoKit Developer's Guide

7-14

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.

Page 292: CryptoKit Developers Guide

Installation 7

7-15

♦ 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.

Page 293: CryptoKit Developers Guide

7 CryptoKit Developer's Guide

7-16

♦ Click Computer Configuration, Administrative Templates, System, Logon.

♦ Change the parameter Run startup scripts asynchronously to Enable.

Page 294: CryptoKit Developers Guide

Installation 7

7-17

♦ Click Computer Configuration, Windows Setting, Scripts (Startup/Shutdown)

Page 295: CryptoKit Developers Guide

7 CryptoKit Developer's Guide

7-18

♦ 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.

Page 296: CryptoKit Developers Guide

Installation 7

7-19

♦ 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.

Page 297: CryptoKit Developers Guide

7 CryptoKit Developer's Guide

7-20

The startup script will be executed when the machines in the container will reboot.

Centralized Installation Using Microsoft SMS 2003 S erver

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.

Page 298: CryptoKit Developers Guide

Installation 7

7-21

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.

Page 299: CryptoKit Developers Guide

7 CryptoKit Developer's Guide

7-22

♦ 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

Page 300: CryptoKit Developers Guide

Installation 7

7-23

♦ In the Environment tab, allow program to run Whether or not a user is logged on.

Page 301: CryptoKit Developers Guide

7 CryptoKit Developer's Guide

7-24

♦ 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

Page 302: CryptoKit Developers Guide

Installation 7

7-25

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.

Page 303: CryptoKit Developers Guide

7 CryptoKit Developer's Guide

7-26

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"

Page 304: CryptoKit Developers Guide

Installation 7

7-27

♦ 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

Page 305: CryptoKit Developers Guide

7 CryptoKit Developer's Guide

7-28

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.

Page 306: CryptoKit Developers Guide

Installation 7

7-29

♦ To configure the ICA client to use smart cards, right click the Citrix client icon and select Properties.

Page 307: CryptoKit Developers Guide

7 CryptoKit Developer's Guide

7-30

♦ 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.

Page 308: CryptoKit Developers Guide

Installation 7

7-31

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.

Page 309: CryptoKit Developers Guide

7 CryptoKit Developer's Guide

7-32

♦ 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.

Page 310: CryptoKit Developers Guide

Installation 7

7-33

♦ 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 required to client machine

Smart card logon to client machine also is required

Use AR PrivateCard and a standard PC/SC reader

If the client is running Windows 2000 then install CryptoKit with no feature selected (*).

If the client is running Windows XP, no installation is required.

Install CryptoKit with: CAPI and Logon features selected.

Use AR MiniKey5 USB token

Install CryptoKit with MiniKey5 feature selected.

Install CryptoKit with: 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 HKEY_LOCAL_MACHINE\Software\Microsoft\ Cryptography\Calais\SmartCards\PrivateCardEx For more information about the values in these entries see later in this chapter.

Page 311: CryptoKit Developers Guide

7 CryptoKit Developer's Guide

7-34

♦ To connect to the terminal server run the Remote Desktop Connection application.

♦ Insert the smart card and enter PIN to login to the server.

Page 312: CryptoKit Developers Guide

Installation 7

7-35

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

Page 313: CryptoKit Developers Guide

7 CryptoKit Developer's Guide

7-36

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

Page 314: CryptoKit Developers Guide

Installation 7

7-37

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.

Page 315: CryptoKit Developers Guide

7 CryptoKit Developer's Guide

7-38

String Constants

The following string constants can be used in different sections of CK_SETUP.INI file:

Key Description

<TARGETDIR> or <INSTALLDIR>

The full path of the directory where CryptoKit is installed

<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 provider

���� ����(1)

Readers_And_Tokens\Minikey MiniKey4 USB token

Readers_And_Tokens\Minikey5 MiniKey5 USB token ���� ����

Readers_And_Tokens\PrivateSafe PrivateSafe reader ����

Page 316: CryptoKit Developers Guide

Installation 7

7-39

Feature Name Description Visible Selected

Readers_And_Tokens\PrivateSafe_PCMCIA

PrivateSafe PCMCIA reader ����

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 support for terminal server and Citrix environments

����(3)

Plugins\Citrix Citrix MetaFrame Server support

����(2)

Plugins\Utils CryptoKit utilities ����

Plugins\Utils\Argenie AR Genie utility ����

Plugins\Utils\pkcs12util PKCS#12 utility ����

Plugins\Utils\PHL PHL utility ����

SDK SDK files and sample programs for developers

����(5) ����

(5)

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 and PHL)

����(5) ����

(5)

SDK\Java_API JCA provider and Java adaptor ����(5) ����

(5)

Page 317: CryptoKit Developers Guide

7 CryptoKit Developer's Guide

7-40

Feature Name Description Visible Selected

SDK\X509 X509 sample programs ����(5) ����

(5)

SDK\PKCS7_10 PKCS#7, #10 certificate request and reply sample programs

����(5) ����

(5)

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 Installation language selection dialog. This dialog allows selection between English or Hebrew. By default this dialog is not displayed.

ShowSelectLang = TRUE

Page 318: CryptoKit Developers Guide

Installation 7

7-41

ShowWelcome Controls whether to display the Welcome dialog. By default the dialog is displayed.

ShowWelcome = FALSE

ShowDestPath Controls whether to display the 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.

ShowDestPath = FALSE

ShowTree Controls whether to display the Features Tree dialog. By default the dialog is displayed.

ShowTree = FALSE

ShowMaint Controls whether to display the 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.

ShowMaint = FALSE

WelcomeLogo Change the image at the left of the Welcome dialog. The image 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.

WelcomeLogo = welcome.bmp

Page 319: CryptoKit Developers Guide

7 CryptoKit Developer's Guide

7-42

TitleLogo Change the small image at the top right corner of most of the 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.

TitleLogo = small.bmp

FinishLogo Change the image at the left of the Finish dialog. The image 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.

FinishLogo = finish.bmp

ForceReboot Controls whether the CryptoKit 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.

ForceReboot = 1

NoPCSC Disable PC/SC usage NoPCSC = TRUE

FinalizeMode Allows setting the ARCSP parameter FinalizeLibraryUse. For more information, refer to explanation about ARCSP component later in this chapter.

FinalizeMode = 0

Page 320: CryptoKit Developers Guide

Installation 7

7-43

StoreMode Allows setting the ARCSP parameter StoreMode. For more information, refer to explanation about ARCSP component later in this chapter.

StoreMode = 2

ShowProgramMenu

Disable installation of the CryptoKit menu entry in the Programs menu.

ShowProgramMenu = FALSE

UseMsReaders Allows setting the SmartAdaptor parameter UseMsReaders. For more information, refer to explanation about SmartAdaptor component later in this chapter.

UseMsReaders = TRUE

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:

Key Description Example

Destination Path Change the default target directory to install CryptoKit.

Destination Path = <PROGRAMFILES>\Company Name\Project

Software Path Change the path of software token directory. The default is: <INSTALLDIR>\sft_tok

Software Path = <INSTALLDIR>\software

MaxRSAPrivate Set the maximum number of private keys that can be stored on hardware token (smart card / MiniKey). The default value is 6.

MaxRSAPrivate = 10

Page 321: CryptoKit Developers Guide

7 CryptoKit Developer's Guide

7-44

EntrustVersion Set the Entrust version. This parameter overrides the value which is set automatically by CryptoKit setup.

EntrustVersion = 5

[Hidden]

The Hidden section allows selecting the components of CryptoKit that will be displayed or hidden in the component selection window.

Key Description Example

Any full feature name

A value of TRUE will hide the component and a value of FALSE will display it. The full list of components is listed above.

Readers_And_Tokens\Minikey = TRUE

[ComponentSelect]

The ComponentSelect section allows selecting the features of CryptoKit that will be selected for installation or not selected.

Key Description Example

Any full feature name

A value of TRUE will select the feature for installation and a value of FALSE will deselect it. The full list of features is listed above.

Readers_And_Tokens\Minikey = TRUE

[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.

Page 322: CryptoKit Developers Guide

Installation 7

7-45

Key Description Example

Any legal directory

Specify list of directories which contain entrust.ini or entmgr.ini files. You can use string constants from the list above.

C:\

[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.

Key Description Example

Any legal file name

List of additional files to copy to target machine at the end of CryptoKit setup. The key name holds the source full file name and the value is the full name of destination. You can use string constants from the list above.

<SRCDIR>\hello.txt = <INSTALLDIR>\hello.txt

[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.

Key Description Example

Any legal registry file name

List of additional registry files to import to the target machine at the 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.

<SRCDIR>\importme.reg =

Page 323: CryptoKit Developers Guide

7 CryptoKit Developer's Guide

7-46

[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.

Key Description Example

Any legal executable file name

List of application names and arguments to be executed. The key name should contain the application path and the value a list of arguments. You can use string constants from the list above.

"<INSTALLDIR>\ShowHTML.exe" = "<INSTALLDIR>\main.htm"

[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.

Key Description Example

LANG Three letters indicating the setup’s language.

LANG = ENG

Page 324: CryptoKit Developers Guide

Installation 7

7-47

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).

Page 325: CryptoKit Developers Guide

7 CryptoKit Developer's Guide

7-48

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

Page 326: CryptoKit Developers Guide

Installation 7

7-49

Destination Dialog

(1) Msg_Destination1

(2) Msg_Destination2

(3) Msg_Destination3

(4) Msg_Destination4

(5) Msg_Destination5

(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

Page 327: CryptoKit Developers Guide

7 CryptoKit Developer's Guide

7-50

Start Copy Message Box

(1) Msg_StartCopy1

(2) Msg_StartCopy2

Finish Dialog

Finish Installation:

(1) Msg_Finish_Inst1

(2) Msg_Finish_Inst2

Finish Maintenance:

(1) Msg_Finish_Maint1

(2) Msg_Finish_Maint2

Finish Upgrade:

(1) Msg_FinishUpgrade1

(2) Msg_FinishUpgrade2

Finish Uninstall:

(1) Msg_Finish_Uninst1

(2) Msg_Finish_Uninst2

All Modes:

(3) Msg_Finish_All1

(4) Msg_Finish_All3 (Only if MiniKey5 was installed)

(5) Msg_Back, Msg_Finish, Msg_Cancel

Page 328: CryptoKit Developers Guide

Installation 7

7-51

Finish Reboot Dialog

Finish Installation:

(1) Msg_Finish_Inst1

(2) Msg_Reboot_Inst2

Finish Maintenance:

(1) Msg_Finish_Maint1

(2) Msg_Reboot_Maint2

Finish Upgrade:

(1) Msg_FinishUpgrade1

(2) Msg_FinishUpgrade2

Finish Uninstall:

(1) Msg_Finish_Uninst1

(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

Page 329: CryptoKit Developers Guide

7 CryptoKit Developer's Guide

7-52

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

Page 330: CryptoKit Developers Guide

Installation 7

7-53

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

Page 331: CryptoKit Developers Guide

7 CryptoKit Developer's Guide

7-54

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

Page 332: CryptoKit Developers Guide

Installation 7

7-55

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.

Page 333: CryptoKit Developers Guide

7 CryptoKit Developer's Guide

7-56

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 Obj_Ids.Dll

<SystemFolder> Crypto Provider for software and hardware tokens of Algorithmic Research

All Ckx50932.dll <SystemFolder> X.509 support dll

All Argui.dll Argenie.dll

<SystemFolder> User interface support dlls

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:

Page 334: CryptoKit Developers Guide

Installation 7

7-57

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:

Key name Key Type Description

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

Page 335: CryptoKit Developers Guide

7 CryptoKit Developer's Guide

7-58

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 Default: dword:00000000

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:

Key name Key Type Description

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.

Page 336: CryptoKit Developers Guide

Installation 7

7-59

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.

Page 337: CryptoKit Developers Guide

7 CryptoKit Developer's Guide

7-60

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:

Key name Key Type Description

LogFileName String Log file name of additional SmartAdaptor components Default: "<INSTALLDIR>\comp.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

Page 338: CryptoKit Developers Guide

Installation 7

7-61

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 Default: dword:00000000

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:

HKEY_LOCAL_MACHINE\Software\Arl\SmartAdaptor\ PKCS#11_PROVIDERS

By default one Core provider is installed – AR Core provider.

Key name Key Type Description

_ProvidersCounter DWORD One Core provider is installed – AR Core provider. Default: dword:00000001

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:

Page 339: CryptoKit Developers Guide

7 CryptoKit Developer's Guide

7-62

Key name Key Type Description

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 Default: dword:00000000 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 1 – In/Out function parameters 2 – Information 3 – Most detailed Information Default: dword:00000003

The contents of the Info subfolder:

Page 340: CryptoKit Developers Guide

Installation 7

7-63

Key name Key Type Description

API_Version DWORD Version of API High word – major version Low word – minor version Default: dword:00020001

IMPL_Version DWORD Implementation version High word – major version Low word – minor version Default: dword:00030000

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:

Key name Key Type Description

_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

Page 341: CryptoKit Developers Guide

7 CryptoKit Developer's Guide

7-64

Attribute_102 Binary Number of dynamic software slots (Attribute_102 should not be bigger then Attribute_101) Default: hex:00,00,00,00

Attribute_103 Binary Path to directory of static software slots Default: hex:00,00,00,00

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 Default: hex:36,00,00,00

Attribute_2 Binary Internal configuration information Default: hex:e8,03,00,00

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

Attribute_202 Binary Maximum size of file on smart card Default: hex:00,04,00,00

Attribute_203 Binary Internal configuration information Default: hex:01,00,00,00

Attribute_204 Binary Internal configuration information Default: hex:03,00,00,00

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 Default: hex:00,00,00,00

Attribute_3 Binary Minimum PIN length of software token Default: hex:05,00,00,00

Attribute_302 Binary Number of attempts for presenting user PIN of software token. 0 – Unlimited or 3-12. Default: hex:00,00,00,00

Page 342: CryptoKit Developers Guide

Installation 7

7-65

Attribute_303 Binary Number of attempts for presenting SO PIN of software token. 0 – Unlimited or 3-12. Default: hex:00,00,00,00

Attribute_4 Binary Internal configuration information Default: hex:00,00,00,00

Smart card providers are registered in the subfolder:

HKEY_LOCAL_MACHINE\Software\Arl\SmartAdaptor\ SC_PROVIDERS

By default one Smart card provider is installed.

Key name Key Type Description

_ProvidersCounter DWORD AR Smart card provider is installed Default: dword:00000001

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:

Key name Key Type Description

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

Entry String Name of the Entry function Default: "SmartcardProviderEntry"

LogFileName String Log file name of the provider Default: "<INSTALLDIR>\sc_pkcs11.log"

LogLevel DWORD Logging level (0 – disabled, 3 – maximum) Default: dword:00000000

The contents of the Info subfolder:

Page 343: CryptoKit Developers Guide

7 CryptoKit Developer's Guide

7-66

Key name Key Type Description

API_Version DWORD Version of API (High word – major version, Low word – minor version) Default: dword:00020001

IMPL_Version DWORD Implementation version (High word – major version, Low word – minor version) Default: dword:00030000

ProviderName String String that holds the provider name (max 64 letters) Default: "PrivateCard"

VendorName String String that holds the vendor name (max 64 letters) Default: "Algorithmic Research Ltd. "

The contents of the VendorDefined subfolder:

Key name Key Type Description

_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 Default: hex:36,00,00,00

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 Default: hex:79,03,00,00

Attribute_3 Binary Minimum PIN length for smart card or MiniKey Default: hex:06,00,00,00

Page 344: CryptoKit Developers Guide

Installation 7

7-67

Attribute_301 Binary Maximum number of RSA key pairs on the smart card or MiniKey Default: hex:06,00,00,00

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 Default: hex:06,00,00,00

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. Default: hex:00,00,00,00

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. Default: hex:00,00,00,00

The contents of the ATRs subfolder:

Key name Key Type Description

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

ATR_0_len DWORD Length of ATR dword:00000008

Page 345: CryptoKit Developers Guide

7 CryptoKit Developer's Guide

7-68

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, ff,ff,ff,ff,ff,ff,ff,ff,ff,ff,ff, ff,ff,ff,ff,ff,ff,ff,ff,ff,ff,ff

ATR_2_len DWORD dword:00000009

ATR_2_atr Binary hex:3b,25,00,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

ATR_2_atr_mask Binary 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_3_len DWORD dword:00000009

ATR_3_atr Binary hex:3b,15,13,00,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

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

Reader providers are registered in the subfolder:

Page 346: CryptoKit Developers Guide

Installation 7

7-69

HKEY_LOCAL_MACHINE\Software\Arl\SmartAdaptor\ 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:

Key name Key Type Description

_ProvidersCounter DWORD Number of PC/SC readers to be ignored by SmartAdaptor Default: dword:00000000

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:

Page 347: CryptoKit Developers Guide

7 CryptoKit Developer's Guide

7-70

Key name Key Type Description

Module String Path and name to the DLL of the provider

Entry String Name of the Entry function

LogFileName String Log file name 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:

Key name Key Type Description

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

ProviderName String String that holds the provider name (max 64 letters)

VendorName String String that holds the vendor name (max 64 letters)

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

Page 348: CryptoKit Developers Guide

Installation 7

7-71

OS File Name Target Description

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

Key name Key Type Description

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

Page 349: CryptoKit Developers Guide

7 CryptoKit Developer's Guide

7-72

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

Key name Key Type Description

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.

HKEY_LOCAL_MACHINE\Software\Arl\SmartAdaptor\ Components\Parameters

Key name Key Type Description

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

Page 350: CryptoKit Developers Guide

Installation 7

7-73

OS File Name Target Description

All Arcsp.dll Arstore.dll

<SystemFolder> CSP dll, signed by Microsoft

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:

Key name Key Type Description

LogFileName String Path to the log file of ARCSP Default: "<INSTALLDIR>\csp.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

LogGroup DWORD Control if log will be activated: 0 – Disabled 255 – Enabled (0xFF) Default: dword:00000000

Page 351: CryptoKit Developers Guide

7 CryptoKit Developer's Guide

7-74

The keys in the Parameters subfolder are:

Key name Key Type Description

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. Default: dword:00000002

Page 352: CryptoKit Developers Guide

Installation 7

7-75

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. Default: dword:00000003

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

Key name Key Type Description

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:

Page 353: CryptoKit Developers Guide

7 CryptoKit Developer's Guide

7-76

HKEY_LOCAL_MACHINE\Software\Microsoft\Cryptography\ Defaults\Provider\ AR RSA SChannel Cryptographic Provider

Key name Key Type Description

Image Path String "arcsp.dll"

SigInFile DWORD dword:00000000

Type DWORD dword:00000012

In all operating systems AR’s PrivateCard smart card is registered:

HKEY_LOCAL_MACHINE\Software\Microsoft\Cryptography\ Calais\SmartCards\PrivateCard

Key name Key Type Description

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

HKEY_LOCAL_MACHINE\Software\Microsoft\Cryptography\ Calais\SmartCards\PrivateCardEx

Key name Key Type Description

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

HKEY_LOCAL_MACHINE\Software\Microsoft\Cryptography\ OID\EncodingType0\CertDllOpenStoreProv\arPhysicalOpen

Page 354: CryptoKit Developers Guide

Installation 7

7-77

Key name Key Type Description

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

Key name Key Type Description

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:

HKEY_LOCAL_MACHINE\Software\Microsoft\ SystemCertificates\My\PhysicalStores\ArStore

Key name Key Type Description

Flags DWORD dword:00000001

OpenEncodingType DWORD dword:00065537

Page 355: CryptoKit Developers Guide

7 CryptoKit Developer's Guide

7-78

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

Key name Key Type Description

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

OS File Name Target Description

All Token1.sft <INSTALLDIR>\sft_tok Empty software token file. This file must have read permissions to all users.

Registry

Page 356: CryptoKit Developers Guide

Installation 7

7-79

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:

Key name Key Type Description

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

OS File Name Target Description

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

Page 357: CryptoKit Developers Guide

7 CryptoKit Developer's Guide

7-80

Key name Key Type Description

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

Key name Key Type Description

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:

HKEY_LOCAL_MACHINE\Software\ARL\SmartAdaptor\Main\ Parameters

Key name Key Type Description

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

Page 358: CryptoKit Developers Guide

Installation 7

7-81

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

OS File Name Target Description

98, ME INSTH98.exe PRinst98.exe Prsafe.inf Prsafe.sys

<INSTALLDIR>\Installation Installation files for 98 and ME

NT INSTN4SH.exe PSAFENT4.sys

<INSTALLDIR>\Installation Installation files for NT

2K, XP Prclass.inf Prclass.sys PRSAFEup.inf PRSAFEup.sys Prinsth2KXP.exe

<INSTALLDIR>\Installation Installation files for 2K and XP

All CSAFE32.dll CSDRV32.exe

<SystemFolder> PrivateSafe drivers

All DLMLOAD.exe FIX252B.dlm FIX262B.dlm

<INSTALLDIR>\Installation DLM loader DLM file for PrivateSafe 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:

HKEY_LOCAL_MACHINE\Software\Microsoft\Cryptography\ Calais\Readers\Algorithmic Research PrivateSafe 0

Page 359: CryptoKit Developers Guide

7 CryptoKit Developer's Guide

7-82

Additional PrivateSafe parameters are registered in:

HKEY_LOCAL_MACHINE\Software\ARL\ARcryptoSafe\Settings

Key name Key Type Description

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

Key name Key Type Description

InterfaceDeviceType DWORD Type of driver: 3 –AR Proprietary with secure PIN entry 7 – Standard PC/SC

Page 360: CryptoKit Developers Guide

Installation 7

7-83

When the PrivateSafe is installed as a proprietary driver, additional registry entries must exist. A reader provider has to be registered in SmartAdaptor:

HKEY_LOCAL_MACHINE\Software\ARL\SmartAdaptor\ Reader_Providers\Provider 0

And the reader has to be registered in the EXCLUDE_PCSC list in:

HKEY_LOCAL_MACHINE\Software\ARL\SmartAdaptor\ 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:

HKEY_LOCAL_MACHINE\Software\ARL\SmartAdaptor\ Main\Parameters

Key name Key Type Description

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 Versions 3.2 – 3.5.X

From Version 3.6.0

Description Works directly with keyboard controller

Uses Windows 2000 keyboard hook mechanism

Replaces the standard Microsoft keyboard driver

Page 361: CryptoKit Developers Guide

7 CryptoKit Developer's Guide

7-84

Operating Systems

NT, 2000, XP 2000, XP 2000, XP

SMS 2000 Yes No – SMS driver conflicts with PrivateSafe driver

No

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

OS File Name Target Description

All euci5.cat <INSTALLDIR>\Installation\Crypto5

Signature of driver

All euci5in.dll <INSTALLDIR>\Installation\Crypto5

File which installs the MiniKey5 driver

All euci5.inf euci5.sys euci5d.inf euci5inx.exe euci5nt.inf euci5nt.sys euci5r.inf euci5r.sys euci5s.inf usbdrv.inf usbdrv.sys

<INSTALLDIR>\Installation\Crypto5

Driver files

Registry

Page 362: CryptoKit Developers Guide

Installation 7

7-85

When the driver installation is finished, the MiniKey is registered as a PC/SC device in:

HKEY_LOCAL_MACHINE\Software\Microsoft\Cryptography\ Calais\Readers\Algorithmic Research Minikey 0

And

HKEY_LOCAL_MACHINE\Software\Microsoft\Cryptography\ 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

OS File Name Target Description

All ApiAsn1.dll ApiCore.dll ApiCrypto.dll ApiSCCom.dll CardOS_CSP.dll CardOS_PKCS11.dll CSP_Module.dll ErrMngr.dll SiCertificateViewer.dll SiCertViewer.dll

<SystemFolder>

All PinManager.exe <INSTALLDIR>\Utils

Registry

The PKCS#11 core provider is registered in:

HKEY_LOCAL_MACHINE\Software\ARL\SmartAdaptor\ PKCS#11_PROVIDERS\Provider_x

Page 363: CryptoKit Developers Guide

7 CryptoKit Developer's Guide

7-86

Key name Key Type Description

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

HKEY_LOCAL_MACHINE\Software\ARL\SmartAdaptor\ PKCS#11_PROVIDERS\Provider_x\Info

Key name Key Type Description

API_Version DWORD Version of API Default: dword:00000000

IMPL_Version DWORD Implementation version Default: dword:00000000

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

Page 364: CryptoKit Developers Guide

Installation 7

7-87

OS File Name Target Description

All eTCoreReg.dll <SystemFolder> Registration dll which installs and uninstalls the driver

98, ME aksup.inf aksifdh.inf

<WindowsFolder>\Inf

98, ME aksifdh.sys aksup.sys

<SystemFolder>\Drivers

NT UsbHub.sys aksup.sys adfrt.sys UsbDrv.sys aksifdh.sys

<SystemFolder>\Drivers

2K, XP aksifdh.sys aksifdh.inf aksup.sys aksup.cat aksup.inf aksifdh.cat

<SystemFolder>\Setup\Aladdin\eToken

This is a temporary directory. The installation program calls a function in eTCoreReg.dll that installs the driver and copies these files to their final destination

Registry

When the driver installation is finished, the Ifdh driver is registered as a PC/SC device in:

HKEY_LOCAL_MACHINE\Software\Microsoft\Cryptography\ Calais\Readers\Algorithmic Research AKS ifdh 0

Additional entry is placed in:

HKEY_LOCAL_MACHINE\Software\Aladdin\eToken\Core

Key name Key Type Description

Cache DWORD dword:00000000

Page 365: CryptoKit Developers Guide

7 CryptoKit Developer's Guide

7-88

Terminal Services

CryptoKit can be installed on Windows 2003 terminal server.

Registry

Only one registry entry is needed to activate the terminal services support:

HKEY_LOCAL_MACHINE\Software\ARL\SmartAdaptor\Main\ Parameters

Key name Key Type Description

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:

HKEY_LOCAL_MACHINE\Software\ARL\SmartAdaptor\Main\ Parameters

Key name Key Type Description

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:

Page 366: CryptoKit Developers Guide

Installation 7

7-89

HKEY_LOCAL_MACHINE\Software\Citrix\CtxHook\ AppInit_Dlls\Smart Card Hook

Key name Key Type Description

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

OS File Name Target Description

All ARgenie.exe <INSTALLDIR>\utils AR Genie utility program

All ARgenie.htm image001.jpg image001.gif image002.gif image003.gif

<INSTALLDIR>\utils\htm AR Genie help files

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:

Page 367: CryptoKit Developers Guide

7 CryptoKit Developer's Guide

7-90

HKEY_LOCAL_MACHINE\Software\ARL\SmartAdaptor\ Components\Parameters

Key name Key Type Description

GenieDisableAdmin DWORD Controls whether running AR Genie in administrator mode is disabled. 0 – Administrator mode is enabled 1 – Administrator mode is disabled Default: dword:00000000

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 Default: dword:00000001

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 Default: dword:00000000

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 Default: dword:00000000

Page 368: CryptoKit Developers Guide

Installation 7

7-91

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. Default: dword:00000000

Additional entries are stored for each user and placed in:

HKEY_CURRENT_USER\Software\ARL\SmartAdaptor\ Components\Parameters

Key name Key Type Description

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

Page 369: CryptoKit Developers Guide

7 CryptoKit Developer's Guide

7-92

<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

OS File Name Target Description

All CyCpten5.dll <SystemFolder> Entrust 5 adapter

Registry

The SmartAdaptor Entrust registry entries include. It is placed in the registry in the subfolder:

HKEY_LOCAL_MACHINE\Software\ARL\SmartAdaptor\Main\ Entrust

which includes several keys described in following table:

Key name Key Type Description

CallbackFlags DWORD Boolean value that controls the secure password entry for the PrivateSafe reader: 0 – Disable 1 – Enable Default: dword:00000000

LogFileV5 String Path to the log file of Entrust adapter

Page 370: CryptoKit Developers Guide

Installation 7

7-93

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:

HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\ CurrentVersion\Uninstall\ {EE046602-85F3-4B87-A734-148C17748848}

Page 371: CryptoKit Developers Guide

7 CryptoKit Developer's Guide

7-94

And

HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\ 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}

Page 372: CryptoKit Developers Guide

I-1

Index A Active Directory Installation, 7-11 Advanced capabilities, 2-17 Algorithms, 1-1 AR Genie

Administrator Mode, 6-4 Command Line, 6-19 Registry, 7-89 User Mode, 6-2

ARCSP Provider, 4-6 Algorithms, 4-10 Functions, 4-12 Installation, 7-72 RSA, 4-9, 4-10 SChannel, 4-9, 4-12 Type, 4-6, 4-9

Asymmetric schemes, 1-3 Authentication of data, 1-7

C C_EXT_Bind, 3-69 C_EXT_ChangeTokenLabel, 3-74 C_EXT_GetProviderContext, 3-62 C_EXT_GetProviderInfo, 3-62 C_EXT_GetProviderList, 3-61 C_EXT_GetProviderSlotList, 3-63 C_EXT_GetSlotProvider, 3-64 C_EXT_PassToProvider, 3-66 C_EXT_Unbind, 3-70 C_EXT_WaitForSingleSlotEvent, 3-71 C_EXT_WaitForSlotEvent, 3-72 C_PKCS10_AcceptCRQ, 5-95 C_PKCS10_CreateCRQ, 5-93, 5-116, 5-117 C_PKCS10_SimpleCreateCRQ, 5-94 C_PKCS7_AcceptCRP, 5-96

C_PKCS7_CreateCRP, 5-97 C_UI_GetMessage, 3-81 C_UI_GetPassword, 3-76 C_UI_SetMessage, 3-78 C_X509_copy, 5-35 C_X509_Copy, 5-76 C_X509_Decode, 5-22, 5-73 C_X509_Encode, 5-28, 5-74 C_X509_EncodeSign, 5-28, 5-79 C_X509_FindInCrl, 5-32, 5-83 C_X509_GetField, 5-24, 5-75 C_X509_Sign, 5-28, 5-78 C_X509_Verify, 5-25, 5-27, 5-81 CA, 5-17 cert_list, 5-92 Certificate Authorities, 5-17 Certificate reply, 5-86, 5-102, 5-106 Certificate request, 5-86, 5-98, 5-106 Certificate Store, 4-16 Certificate/CRL fields, 5-39 Certificates, 5-17

Building, 5-37 Decoding, 5-22 Object identifiers, 5-37 Validating, 5-27

certs_and_crls, 5-91 Challenge-Response protocol, 1-6 Checking for revoked certificates, 5-32 Citrix Server, 7-26, 7-88 CK_ASN_ID, 5-53 CK_CALLBACK_FUNCTION, 3-27 CK_DATA, 5-53 CK_DECLARE_FUNCTION, 3-26 CK_DECLARE_FUNCTION_POINTER, 3-27 CK_LANG.INI, 7-47 CK_PTR, 3-26

Page 373: CryptoKit Developers Guide

I CryptoKit Developer's Guide

I-2

CK_SETUP.INI, 7-40 AutoSettings, 7-43 ComponentSelect, 7-44 FinalizeMode, 7-42 FinishLogo, 7-42 ForceReboot, 7-42 Hidden, 7-44 NoPCSC, 7-42 ShowDestPath, 7-41 ShowMaint, 7-41 ShowSelectLang, 7-40 ShowTree, 7-41 ShowWelcome, 7-41 StoreMode, 7-43 TitleLogo, 7-42 WelcomeLogo, 7-41

CK_TIME_T, 5-53 CK_X509_CERT_FIELD, 5-53 CK_X509_CRL_FIELD, 5-53 CK_X509_FIELD, 5-53 Classical schemes, 1-2 Clock, internal, 2-12

date and time, 3-24 Compiler-dependency, 3-25 Constants

Certificate/CRL fields, 5-39 Object Identifiers, 5-45 Types of General Names, 5-44 X.509 Toolkit constants, 5-38

Core providers, 3-4 CoSign, 2-11 CRL

Decoding, 5-22 CRP_FORMAT, 5-88 CRQ_FORMAT, 5-88 CryptAcquireContext, 4-13 CryptGenRandom, 4-14 CryptGetProvParam, 4-13 Cryptographic algorithms, 1-1

CryptoSafe, 2-12, 2-15 CryptSetProvParam, 4-13 CSP, 4-2 CTAPI Readers, 3-49

D Data

Authentication, 1-1, 1-7 Secrecy, 1-1

Decoding Certificates and CRLs, 5-22 Decryption, fast, 1-7 DES Stream, 3-13 DES2, 3-13 DES3, 3-13 Digital signatures, 1-4 DlmLoad, 6-26

E Encoding and signing certificate/CRLs, 5-28 Encryption,fast, 1-7 Entrust Adapter, 5-14

F Fast encryption/decryption, 1-7 Fields, Certificate/CRL, 5-39 FinalizeLibraryUse, 7-42, 7-75 Functions

X.509 Toolkit, 5-73

H HSM, 2-10 Hybrid symmetric/asymmetric schemes, 1-5

I Ifdh driver, 2-9, 7-86 Independence

Platform, 2-16 Installation, 7-1

Active Directory, 7-11 CD, 7-2

Page 374: CryptoKit Developers Guide

Index I

I-3

Citrix, 7-26 CK_LANG.INI, 7-47 CK_SETUP.INI, 7-40 Customizing, 7-37 Files, 7-55 Package files, 7-35 Registry, 7-55 Silent, 7-9 SMS Server, 7-20 Terminal Server, 7-31 Uninstallation, 7-7 Upgrade, 7-8

J Java Adapter, 5-2

Java PKCS, 5-10 JCA, 5-2

K Key Container, 4-5 Key Media

CoSign, 2-11 MiniKey, 2-8 Overview, 2-2 PrivateCard, 2-2 PrivateServer, 2-10 Software, 2-5

M Macros

AR_PLATFORM, 3-25 CK_CALLBACK_FUNCTION, 3-27 CK_DECLARE_FUNCTION, 3-26 CK_DECLARE_FUNCTION_POINTER,

3-27 CK_PTR, 3-26

Mechanisms, 3-5, 3-7. See list, pp. 1-3 to 1-6 Message Authentication Codes (MACs), 1-2 MiniKey, 2-8, 2-12, 7-84

N Netscape, 3-5 Non-repudiation transaction, 1-8

O Object Identifiers, 5-37, 5-45

Algorithm Identifiers, 5-45 Attribute Types, 5-38, 5-47 Extensions, 5-48 Key Purposes, 5-49 PKCS, 5-46 Qualifier Types, 5-49

Objects, 3-5

P ParallelSlots, 7-59 PC/SC Readers, 3-49 PCMCIA, 2-14 Pentium4RSAMode, 7-60 Performance, 2-17 PIN

Default parameters, 3-20 functionality, 3-19 passing NULL, 3-19 Secure PIN entry, 3-19 Single Sign On, 3-20 Unattended mode, 3-20

PKCS#10, 5-86 PKCS#11

Data objects, 3-18 Mechanisms, 3-5 Objects, 3-5 Protected authentication path, 3-5 Slots, 3-5 Tokens, 3-5

PKCS#11 standard, 3-5 PKCS#12

ExportPKCS12, 5-117 ImportPKCS12, 5-116

Page 375: CryptoKit Developers Guide

I CryptoKit Developer's Guide

I-4

Toolkit, 5-116 PKCS#7, 5-86 pkcs10_cr, 5-89 pkcs10_cri, 5-89 Platform independence, 2-16 Platform-dependency, 3-25 Platform-specific macros, 3-26 Primary issues, 1-1 PrivateCard, 2-3, 2-5, 2-12 PrivateSafe, 2-12, 2-13, 7-81

Driver Types, 7-83 PrivateSafe PCMCIA, 2-12 PrivateServer, 2-10 Proprietary Readers, 3-50 Protected authentication path, 3-5, 3-19 Public Key Cryptography, 5-16

R Reader Provider API, 3-51 Reader providers, 3-4 Reference material, 1-1 Registration API, 3-29 Remote Desktop Connection, 7-32 RSA, 1-3

S SChannel CSP, 4-9, 4-12 Scheme

Hybrid, 1-5 Symmetric, 1-2

Secure key transfer, 1-6 Siemens MiniKey, 2-9, 7-85 Signatures, digital, 1-4 simple_dname, 5-91 Simplicity of use, 2-17 Single sign on, 3-20, 7-79 Slots, 3-5, 3-17

CryptoSafe, 2-12 PrivateSafe, 2-12 PrivateSafe PCMCIA, 2-12

Smart card providers, 3-4 Smart Cards, 2-2 SMS Server, 7-20 Software key media, 2-5, 7-63

Bind, 3-69, 6-6 Dynamic slot, 2-7, 7-64 Installation, 7-78 Registry, 7-63 Static slot, 2-7, 7-64 Unbind, 3-70, 6-7

SSO, 7-79 Store

Certificate, 4-16 Physical, 4-17 Registration, 7-77

StoreMode, 7-43, 7-74 Symmetric

Schemes, 1-2

T Terminal Server, 7-31, 7-88 Thread safety

serialization of requests, 3-24 Tokens, 3-5, 3-17

Initializing, 3-7 PrivateCard, 2-12

Transaction non-repudiation, 1-8 Two-way authentication, 1-1, 1-6 Types of General Names, 5-44

U UMB_ATR_DESCRIPTION, 3-33 UMB_CONTEXT, 3-30 UMB_CreatePKCS11ProviderContext, 3-34 UMB_CTAPI_PORT_DESCR, 3-32 UMB_CTAPI_PORTS, 3-33 UMB_ENTRY, 3-51 UMB_PCSC_EXCLUDE_STRUCT, 3-31 UMB_PROVIDER_INFO, 3-31 UMB_READER_CLOSE, 3-57

Page 376: CryptoKit Developers Guide

Index I

I-5

UMB_READER_GET_NATIVE_RESULT_VALUE, 3-57

UMB_READER_GET_STATE, 3-54 UMB_READER_I_AM_CLOSED, 3-58 UMB_READER_POWER_OFF, 3-55 UMB_READER_POWER_ON, 3-54 UMB_READER_TRANSMIT, 3-56 UMB_RV, 3-30 UMBAPI

UMB_AddATRToList, 3-40 UMB_AddFindContext, 3-43 UMB_CreateFindContext, 3-43 UMB_CreatePKCS11SmartcardProvider

Context, 3-35 UMB_CreateSmartcardReaderContext,

3-36 UMB_FreeContext, 3-47 UMB_GetProviderData, 3-41 UMB_GetProviderType, 3-47 UMB_ListProviders, 3-46 UMB_RegisterProvider, 3-42 UMB_SetProviderData, 3-38 UMB_UnregisterProvider, 3-45

Unattended login, 3-20, 7-80 Uninstallation, 7-7 Utility

AR Genie, 6-1 DlmLoad, 6-26 PKCS#12, 6-24

V Validating certificates, 5-27 Version

information on current, 3-16

X X.509, 5-18 X.509 Toolkit, 5-16

Constants, 5-38 Overview, 5-16

Working with, 5-22 X509, 5-72 X509_alg_params_dh, 5-58 X509_alg_params_key, 5-57 X509_alg_params_key_iv, 5-57 X509_alg_struct, 5-56 X509_ATAV, 5-59 X509_attr_value, 5-91 X509_attribute, 5-90 X509_attributes, 5-90 X509_certificate, 5-53 X509_crl, 5-55 X509_crl_tbs, 5-55 X509_def_key_info, 5-61 X509_distribution_point, 5-69 X509_Dname, 5-59 X509_DPN, 5-69 X509_DSA_params, 5-57 X509_ext, 5-63 X509_ext_0000 / X509_ext_unknown, 5-63 X509_ext_2914, 5-64 X509_ext_2914 /

X509_ext_SubjectKeyIdentifier, 5-64 X509_ext_2915, 5-64 X509_ext_2916, 5-64 X509_ext_2916 /

X509_ext_PrivateKeyUsagePeriod, 5-64

X509_ext_2917_8, 5-65 X509_ext_2919, 5-65 X509_ext_2919 / X509_ext_BasicConstraints,

5-65 X509_ext_2920, 5-66 X509_ext_2921, 5-66 X509_ext_2921 / X509_ext_CRLreason, 5-66 X509_ext_2923,X509_ext_HoldInstructionCo

de, 5-66 X509_ext_2924,X509_ext_InvalidityDate,

5-67

Page 377: CryptoKit Developers Guide

I CryptoKit Developer's Guide

I-6

X509_ext_2927,X509_ext_DeltaCRLIndicator, 5-67

X509_ext_2928,X509_ext_IssuingDistributionPoint, 5-67

X509_ext_2929,X509_ext_CertificateIssuer, 5-68

X509_ext_2930, 5-68 X509_ext_2930 / X509_ext_NameConstraints,

5-68 X509_ext_2931, 5-69 X509_ext_2931 /

X509_ext_CRLDistributionPoint, 5-69

X509_ext_2932, 5-70 X509_ext_2932 /

X509_ext_CertificatePolicies, 5-70 X509_ext_2933, 5-70 X509_ext_2933 / X509_ext_PolicyMappings,

5-70, 5-71 X509_ext_2935, 5-71 X509_ext_2936, 5-71 X509_ext_2936 /

X509_ext_PolicyConstraints, 5-71 X509_ext_2937, 5-72 X509_ext_Altname, 5-65

X509_ext_BasicConstraints, 5-65 X509_ext_CertificatePolicies, 5-70 X509_ext_CRLDistributionPoint, 5-69 X509_ext_CRLNumber, 5-66 X509_ext_CRLreason, 5-66 X509_ext_NameConstraints, 5-68 X509_ext_PolicyConstraints, 5-71 X509_ext_PolicyMappings, 5-70, 5-71 X509_ext_PrivateKeyUsagePeriod, 5-64 X509_ext_SubjectKeyIdentifier, 5-64 X509_ext_unknown, 5-63 X509_extensions, 5-62 X509_general_name, 5-65 X509_general_names, 5-70 X509_general_subtree, 5-68 X509_key_info, 5-60 X509_obj_id, 5-56 X509_rev_list, 5-62 X509_revoked, 5-62 X509_RSA_key_info, 5-61 X509_signature, 5-55 X509_tbs, 5-54 X509_unique_id, 5-61 X509_validation_params, 5-58 X509_validity, 5-60