CryptoKit Developers Guide

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

Notice This manual contains information that is proprietary to ARX (Algorithmic Research) No part of this manual may be reproduced in any form whatsoever without prior written approval by ARX. ARX reserves the right to revise this publication and make any changes without obligation to notify any person of such revisions and changes. For further information, contact ARX at the address below, or contact your local distributor.

Trademarks CryptoKit, MiniKey, PrivateCard, CryptoSafe, PrivateSafe, and PrivateSafe PCMCIA are trademarks of ARX. Other names are trademarks or registered trademarks of respective owners and are used solely for identification purposes.

ARX (Algorithmic Research) 855 Folsom St. Suite 939, San Francisco, CA 94107 Tel: (415) 839 8161 Fax: (415) 723 7110 www.arx.com

© Copyright 2005 ARX (Algorithmic Research). All rights reserved.

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

Table of Contents Chapter 1: Introduction to Cryptography .......................................................................... 1-1 Security Issues ....................................................................................................................... 1-1 Cryptographic Algorithms ..................................................................................................... 1-1 Symmetric Schemes ............................................................................................................... 1-2 Asymmetric Schemes............................................................................................................. 1-3 Hybrid Symmetric/Asymmetric Schemes .............................................................................. 1-5 Chapter 2: Component-Related Technologies................................................................. 2-1 Key Media..................................................................................................................................... 2-2 Smart Cards ........................................................................................................................... 2-2 Software Key Media .............................................................................................................. 2-5 MiniKey Token...................................................................................................................... 2-8 Hardware Security Module – PrivateServer ........................................................................ 2-10 CoSign – Digital Signatures Appliance ............................................................................... 2-11 Smart Card Readers ............................................................................................................. 2-11 PrivateSafe........................................................................................................................... 2-13 PrivateSafe PCMCIA........................................................................................................... 2-14 CryptoSafe ........................................................................................................................... 2-15 Media Independence ................................................................................................................... 2-16 Platform Independence ............................................................................................................... 2-16 Advanced Capabilities ................................................................................................................ 2-17 Simplicity of Use ........................................................................................................................ 2-17 Performance ................................................................................................................................ 2-17 Stability and Exception Handling ............................................................................................... 2-18 Compliance with Industry Standards........................................................................................... 2-18 Chapter 3 SmartAdaptor Technology ................................................................................ 3-1 General Concepts .......................................................................................................................... 3-2 CryptoKit Architecture ................................................................................................................. 3-2 SmartAdaptor General Concepts ........................................................................................... 3-4 Main SmartAdaptor Cryptographic API ....................................................................................... 3-5 PKCS#11 General Terminology ................................................................................................... 3-5

i

CryptoKit Developer's Guide

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

ii

Table of Contents

Supported Functions ............................................................................................................ 4-12 Certificate Store .......................................................................................................................... 4-16 Store Functionality on Win 98, ME and NT ........................................................................ 4-16 Physical Certificate Store on Windows 2000, XP and 2003................................................ 4-17 Export/Import Functionality........................................................................................................ 4-18 Chapter 5: SmartAdaptor Add-On Adapters...................................................................... 5-1 Java Adapter ................................................................................................................................. 5-2 ARJCA................................................................................................................................... 5-2 AR Java PKCS..................................................................................................................... 5-10 Entrust Adapter ........................................................................................................................... 5-14 X.509 Toolkit.............................................................................................................................. 5-16 Overview.............................................................................................................................. 5-16 Additional Reading .............................................................................................................. 5-21 Working with the X.509 Toolkit.......................................................................................... 5-22 Constants.............................................................................................................................. 5-38 General Data Types ............................................................................................................. 5-51 Functions.............................................................................................................................. 5-73 PKCS#10,#7 Certificate Request and Reply............................................................................... 5-86 General Data Types ............................................................................................................. 5-87 Functions.............................................................................................................................. 5-93 Programming Samples ......................................................................................................... 5-98 PKCS#12 Import and Export .................................................................................................... 5-116 Functions............................................................................................................................ 5-116 Chapter 6: SmartAdaptor Utilities ...................................................................................... 6-1 AR Genie Utility ........................................................................................................................... 6-1 User Mode Token Operations................................................................................................ 6-2 Administrative Token Operations .......................................................................................... 6-4 Running AR Genie From Command Line............................................................................ 6-19 PKCS#12 Import/Export Utility ................................................................................................. 6-24 Import Operation ................................................................................................................. 6-24 Export Operation ................................................................................................................. 6-24 DlmLoad Utility.......................................................................................................................... 6-26 Chapter 7: Installation ......................................................................................................... 7-1 Installation Packages..................................................................................................................... 7-1 Installation From CD .................................................................................................................... 7-2 Installing On a Clean Machine............................................................................................... 7-2

iii


Modifying or Removing an Existing Installation....................................................................7-7 Upgrading an Existing Installation .........................................................................................7-8 Silent Installation ...........................................................................................................................7-9 Centralized Installation from Active Directory............................................................................7-11 Step 1 – Create CryptoKit Installation Package on the Server .............................................7-11 Step 2 – Create the Startup Script.........................................................................................7-12 Step 3 – Assign the Startup Script ........................................................................................7-14 Centralized Installation Using Microsoft SMS 2003 Server........................................................7-20 Step 3 – Assign CryptoKit Package to SMS Collection .......................................................7-20 Installation in Citrix Environment ...............................................................................................7-26 Citrix Server Configuration ..................................................................................................7-26 Citrix Client Configuration...................................................................................................7-28 Installation in Terminal Server Environment...............................................................................7-31 Terminal Server Configuration.............................................................................................7-31 Client Configuration .............................................................................................................7-32 CryptoKit Installation Package ....................................................................................................7-35 Customizing the Installation ........................................................................................................7-37 String Constants....................................................................................................................7-38 Feature Names ......................................................................................................................7-38 CK_SETUP.INI....................................................................................................................7-40 CK_LANG.INI.....................................................................................................................7-47 CryptoKit Files and Registry Entries ..........................................................................................7-55 General Guidelines ...............................................................................................................7-55 SmartAdaptor .......................................................................................................................7-56 AR Client Service and Daemon............................................................................................7-70 ARCSP .................................................................................................................................7-72 Software Token ....................................................................................................................7-78 Single Sign On (SSO)...........................................................................................................7-79 PrivateSafe Reader ...............................................................................................................7-81 MiniKey5..............................................................................................................................7-84 Siemens PKCS#11 Provider.................................................................................................7-85 Ifdh Driver for Siemens MiniKey.........................................................................................7-86 Terminal Services.................................................................................................................7-88 Citrix Server .........................................................................................................................7-88 Utility Programs ...................................................................................................................7-89 SDK Files .............................................................................................................................7-91 Entrust Plug-in in the Registry..............................................................................................7-92 Shortcuts...............................................................................................................................7-93 Package Information.............................................................................................................7-93

iv

Chapter 1: Introduction to Cryptography In this chapter we review some of the concepts and terms of modern cryptography. If you are new to this field, it might be worthwhile to consult introductory reference material. Three sources worth referencing are: Applied Cryptography, Second Edition, Bruce Schneier, John Wiley & Sons, 1996. Contemporary Cryptology, Edited by Gustavus J. Simmons, IEEE press, 1992. Security for Computer Networks, Second Edition, D.W. Davies and W. L. Price, John Wiley & Sons, 1989.

Security Issues Cryptographic-Strength Data Security deals with four primary issues: ♦ Two-way participant authentication – During data exchange, each side wants to be sure of the identity of the other. ♦ Data authentication (integrity) – This is a general term that roughly means the data is reliable and was not tampered with. ♦ Data secrecy – This is needed when sensitive data is transferred. ♦ Non-repudiation – Provides a mechanism for the recipient to prove that the information was generated by a particular sender.

Cryptographic Algorithms Data security as described above is maintained through the use of cryptographic algorithms. A cryptographic algorithm is a method, usually based on some mathematical function, used for authentication and/or secrecy. Some applications require only secrecy or only authentication; others require both. The security of a cryptographic scheme resides entirely in the secret key, and not in the secrecy of the algorithm. Cryptographic schemes are classified as either Symmetric or Asymmetric. 1-1

1


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

User A Key

Encrypt

Cleartext

User B Ciphertext

Decrypt

Key

Cleartext

In Symmetric schemes, authentication is often performed with Message Authentication Codes (MACs) in the following way: 1. The initial vector (which may include date & time) is encrypted and joined (i.e., XORed) with the first block of data. 2. The result is encrypted and joined with next block of data. 3. The final block is MAC - clearly a function of the initial vector and the entire message.

1-2

1

Introduction to Cryptography

User A Key

Compute MAC

Cleartext + Initial Vector

User B MAC

Verify MAC

Key


Symmetric schemes have both strengths and weaknesses. Their strengths include fast encryption/decryption and participant/data authentication using MACs. However, their weaknesses include the need for a separate (secure) channel for key transfer, and the need for very complex key management.

Asymmetric Schemes Asymmetric cryptographic schemes are based on principles that differ to those governing Symmetric schemes in the following ways: ♦ The encryption key is different than the decryption key. ♦ The decryption key cannot be calculated from the encryption key (i.e. it is a one-way function). Such a scheme is also called a Public Key System, because the encryption key is made public. This way, a complete stranger can use the encryption key to encrypt a message, but only someone with the corresponding decryption key can decrypt the message. The encryption key is called the Public Key, and the decryption key is called the Private Key. The best-known Asymmetric scheme is RSA. Asymmetric schemes provide secrecy by having the sender use the receiver's public key to encrypt the data, while only the intended receiver, using his private key, can decrypt the data and use it:

1-3

1


User A Public Key

Encrypt

User B Ciphertext

Decrypt

Private Key

Cleartext

Cleartext

Asymmetric schemes provide authentication by using Digital Signatures in the following way: ♦ A hash function generates a result that reflects an entire message (including date & time). ♦ The result is signed with the sender’s private key. ♦ The signature is verified by the receiver using the sender’s public key:

User A User A Private Key

Generate Digital Signature

Cleartext + Date & Time

User B Digital Signature

Verify Digital Signature

User A Public Key


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

1-4


1

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

Hybrid Symmetric/Asymmetric Schemes Hybrid Symmetric/Asymmetric schemes (e.g., DES + RSA), combine the best of both worlds: ♦ Strong RSA two-way authentication of participants. ♦ Simple RSA key management (N users => N public keys). ♦ Secure RSA transfer of DES keys (per session). ♦ Fast DES encryption/decryption. ♦ RSA/DES data authentication (digital signatures/MACs). ♦ Transaction non-repudiation using RSA digital signatures. We will now review the above points.

1-5

1


Two-way Authentication Two-way authentication is achieved with an RSA-based Challenge-Response protocol performed in both directions at the beginning of each session. Suppose, for example, that we have a Host and a Client. ♦ Host sends Client a random string (“challenge”). ♦ Client signs string with Client’s private key and sends it back (“response”) to Host, along with Client’s identity. ♦ Host finds Client’s public key in the database that stores all of the public keys, and reads the response by using that key. ♦ If "response" matches "challenge" that Host sent to Client initially, then Host knows that Client is indeed who it claims to be, i.e. host has verified that the Client is a legitimate receiver of secret data. ♦ A similar protocol is performed in the other direction, so that the Client will not log on to an illegitimate host.

Secure Key Transfer Secure key transfer is achieved by an RSA-based exchange of session-specific encryption DES keys at the beginning of each Client-Host session: ♦ After both sides authenticate each other, they exchange DES encryption keys, “packaged” within RSA-encrypted messages. ♦ The session key is the result of joining the two keys. ♦ DES used for encryption/decryption of any further data throughout that session. ♦ DES keys are per session (new session => new DES keys are exchanged).

1-6

1


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

User A

Key

Encrypt

User B Ciphertext

Decrypt

Cleartext

Key

Cleartext

Data Authentication As for data authentication, this is done with MACs: User A

Key

Compute MAC


User B MAC

Verify MAC

Key


1-7

1


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

User A User A Private Key

Generate Digital Signature


1-8

User B Digital Signature

Verify Digital Signature


User A Public Key

]

Chapter 2: Component-Related Technologies CryptoKit enables the use of several types of smart card solutions including smart cards, readers and USB smart card tokens, such as MiniKey, which enhances security, allows storage of sensitive data and the use of secure PINs. CryptoKit also enables the full emulation of smart card tokens in software, providing virtual (software-only based) tokens. Several basic elements contribute to CryptoKit’s architecture: ♦ Key media (smart cards, tokens, virtual tokens) ♦ Media independence ♦ Platform independence ♦ Advanced cryptographic capabilities ♦ Simplicity ♦ High performance ♦ Stability and exception handling ♦ Compliance with industry standards

2-1

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

Component-Related Technologies

2

prevent the type of attack that presents a large number of password attempts in succession, a smart card operating system can lock the smart card from further password presentations after a small number of unsuccessful attempts. Cryptographic Operations Since encryption keys are kept on the smart card and are not exposed to the outside world, the algorithms that use them must also reside on the card. Most smart cards contain symmetric encryption algorithms (such as DES) as part of the operating system. More advanced smart cards implement asymmetric algorithms, or public key cryptography, such as RSA, utilizing a special arithmetic processor that is optimized for performing fast modular arithmetic. Applications With the features described above, smart card chips can be used for a wide range of applications, including: Network login, personal identification, authentication, digital signatures, e-commerce and more. Smart cards are the most flexible solution available for enforcing controlled access to Web pages, Internet services, databases and applications. They empower organizations to distribute sensitive information over the Net by implementing user authentication, digital signatures and data encryption. CryptoKit enables integration of smart cards in any PKCS#11-standard or CAPI application. It enables integration with applications from vendors such as Microsoft, Netscape, Baltimore, Entrust, CheckPoint and many more. Removal/Insertion Smart cards can be changed during application execution. When the smart card is removed from the reader, applications automatically log off. When the new smart card is inserted, CryptoKit detects the smart card type and, if supported, works with it.

2-3

2


PrivateCard, developed by AR, has the following advantages and features: ♦ RSA functionality Supports generation of RSA private and public keys up to 2048-bits. ♦ Hardware-based random number generation Approaching pure randomness. ♦ Support for multi-application and multiple key storage Multiple keys may be stored on the token and keys may be accessed by several applications. ♦ Access control and PIN verification PrivateCard provides a sophisticated mechanism offering Challenge/Response PIN presentation to prevent replay, ensuring that only authorized users can access data stored on the chip. ♦ Authorization masks PrivateCard provides a secure file-store and hierarchical-directory structure that allows authorization/access rules to be established for each file and directory on the card. ♦ Support for industry standard algorithms such as

DES (FIPS PUB 46) SHA-1 (FIPS PUB 180-1) used for verification of PINs and access control RSA algorithm is used for digital identity ISO 7816 smart card communication protocol

♦ Key generation RSA private keys are generated and used on the smart card itself. RSA private keys are never moved from the smart card, and thus cannot be compromised by any other code. ♦ Password policy PrivateCard smart card has a built-in password-related policy handling (such as password validity period, minimal password length, minimal password change period). ♦ Objective time servers PrivateCard smart card can work with secure time servers (although this feature is not used by CryptoKit).

2-4

2


♦ 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 Siemens*

Memory Size

RSA Capability

Communication Speed (baud)

Operating System Version

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

144K

2048 bit

115200

3.01

Atmel AT90SC144144CT

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

Software Key Media CryptoKit supports the use of virtual tokens, which store all PKCS#11 objects in a specially formatted file that can be created on the hard disk or on a diskette. Since all cryptographic operations are performed in software, no additional drivers need to be installed.

2-5

2


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

2-6


2

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

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

2-7

2


MiniKey Token MiniKey, AR’s portable, personal token, allows users to conveniently manage their keys and authenticate their identity when connecting to enterprise, ecommerce or other secure applications as well as to store data securely on token. With AR’s advanced ISO standard smart card chip operating system, MiniKey has its own secure file storage and RSA functionality, enabling a full range of cryptographic services and secure connection.

PKI-Ready Unlike most other solutions, including memory-based tokens or password generators that do not support secure PKI features such as on-token key generation, MiniKey is suitable for a wide range of security applications including PKI based applications. MiniKey performs cryptographic functions in a secure, isolated environment, just like a smart card. Private information cannot be retrieved or changed even if the token is tampered with. Powerful, Convenient and Affordable Today’s technology has produced new, more powerful processing chips. Algorithmic Research has taken advantage of this potential and has developed an advanced chip operating system that enables MiniKey to perform cryptographic functionality on the chip itself. Thanks to its standard interface and USB Plug &Play capability, MiniKey is easy to use and does not require any additional hardware. MiniKey is an overall low-cost solution, since the token itself is inexpensive and it eliminates the need for a reader, making MiniKey the most attractive, high security PKI token available.

2-8

2


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

MiniKey*

32K

MiniKey5

32K

ITSEC

Smartcard Chip


Driver

1024 bit

Atmel AT90SC3232C

AR 1.12-1.14

Proprietary

No

1024 bit

Atmel AT90SC3232C

AR 1.14-1.16

- PC/SC - Signed - CryptoIdentity device - Linux

No

Cert.

2-9

2


Model

Memory Size

RSA Capability

MiniKey5

64K

Siemens MiniKey

Siemens MiniKey


Driver

2048 bit

Atmel AT90SC6464C

AR 2.21-2.22

- PC/SC - Signed - CryptoIdentity device - Linux

No

32K

1024 bit

Siemens SLE66CX320P

Siemens CardOS M4.01

- PC/SC - Signed - CryptoIdentity or IFDH device

Yes

32K

1024 bit

Siemens SLE66CX322P

Siemens CardOS M4.01a

- PC/SC - Signed - CryptoIdentity device

Yes

Cert.

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

Hardware Security Module – PrivateServer CryptoKit enables PKI applications to use AR’s hardware security module (HSM) called PrivateServer. The PrivateServer enables organizations to perform all their PKI based activities such as digital signatures in a centralized and secure way (the PrivateServer is FIPS 140-1 level 3 certified). It is connected to the organization network and performs the requested cryptographic operations. It supports many hash and symmetric algorithms as well as RSA of up to 4096 bit. For more information about the functionality and operation of the PrivateServer, refer to the PrivateServer installation manual and to PrivateServer API guide.

2-10

ITSEC

Smartcard Chip


2

CoSign – Digital Signatures Appliance CoSign is a non-forgeable, simple-to-use digital-signature appliance. It delivers an innovative way to electronically sign documents, forms and, messages within major applications such as MS-Word, Adobe-Acrobat, ERP and Content Management systems. CoSign creates digital signatures, based on PKI technology and ensures the data integrity of the transactions and documents.

CoSign is connected to the organization network and user-management system. Through CryptoKit, CoSign supports the three most commonly used cryptographic APIs available: Microsoft CAPI, PKCS#11, and JCA/JCE. In addition, CoSign comes with AR’s Signature API (AR-SAPI), which provides an easy way to integrate with digital signature applications by providing all the functionality needed to handle PKI based operations and graphical signatures. For more information about the functionality and operation of the CoSign, refer to the CoSign manual.

Smart Card Readers In order to enable smart cards to communicate with PCs, workstations, laptops, etc., users must attach smart card reader devices. AR’s CryptoKit supports all PC/SC and CT-API compliant readers, as well as those developed by AR: PrivateSafe®, CryptoSafe, and PrivateSafe PCMCIA readers and the MiniKey USB token.

2-11

2


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®

Tokens

CryptoSafe

Supports any ISO Supports 7816-compliant PrivateCard. smart card. Requires loading the appropriate DLM.

Supports Protected Authentication Path (Secure Keypad Password Entry)

PrivateSafe PCMCIA Reader

MiniKey

Supports any MiniKey is also a ISO 7816token. compliant smart card.

Supports

Does not support

Does not support

Date

Uses date supplied by the host computer.

Includes an internal clock.



Connection to Host Computer

Keyboard connection only.

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

Recommended for use with laptop computers

Recommended for any PC/laptop with a USB port

Designed for use with desktop computers.

Designed for use with desktop computers. Plug&Play

2-12

Does not support Does not support Supports

Supports

2


PrivateSafe PrivateSafe advantages include: ♦ AR’s patented keyboard connectivity Ensures full control for all communications between the keyboard and PC. PrivateSafe disables keyboard communications to and from the computer when sensitive information is entered. During regular operation, the keyboard communicates transparently with the PC.

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

2-13

2


♦ Does not occupy a serial communication port Unlike conventional smart card readers, PrivateSafe connects through the keyboard port. ♦ Supports Windows 98, ME, NT, 2000, XP and 2003. ♦ PrivateSafe specifications:

Complies with ISO 7816 standard smart cards Multiple mode light indication Physical dimensions: 73x78x16 mm Weight: 60 g (net) Power consumption: Idle- 30 mA, Operating-60 mA maximum Power supply: 5 volts. Communication to host via keyboard interface Keyboard management support Programmable interface from 9600 baud to 69 Kbaud Connector cable length: 150 cm Adapter for a standard PC or PS/2 keyboard connector

PrivateSafe PCMCIA The PrivateSafe PCMCIA reader is a standard PCMCIA device for use with laptop computers. It has a standard PC/SC driver, which can be installed by the CryptoKit installation.

2-14


2

CryptoSafe CryptoSafe is a smart card reader for the PC and workstation. CryptoSafe provides the same isolated environment as PrivateSafe for performing sensitive data-security functions with both PrivateCard. CryptoKit supports only the keyboard model of CryptoSafe. CryptoSafe features include: ♦ Broad range of security functions performed internally ♦ Secure PIN verification ♦ Mutual smart card/reader authentication Note: If you use AR’s CryptoSafe reader, you have to load into it an appropriate DLM. The DLM is program that is digitally signed by AR special private key and the signature is verified once the program is loaded into the reader, so that no information (passwords or private keys) can be compromised.

2-15

2


Media Independence The CryptoKit API is media independent – it can be used for various types of key media with minimal or no change. For example, an application written to use key files can make use of smart cards or MiniKeys with minimal or no change at all.

Platform Independence CryptoKit has an ANSI standard, C-like API that is the same for all supported platforms. An application using CryptoKit can be smoothly ported to any supported platform. Currently, CryptoKit is available for the following platforms: ♦ Windows (98, ME, NT, 2000, XP and 2003) ♦ Linux (RedHat, SUSE and Debian) CryptoKit may be used from C/C++ programs or any other development environment that can access C API, such as Visual Basic, Delphi, or PowerBuilder. CryptoKit has a Java interface that allows Java applications to utilize all supported devices. It includes two Java libraries: a proprietary Java adapter that provides PKCS#11 style API to Java applications and a standard Java Cryptography Architecture (JCA) provider. For more information refer to chapter 5. The file format used by CryptoKit to store a virtual token is identical for all platforms. This guaranties that key files can be created and used across different platforms.

2-16

2


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.

2-17

2


Stability and Exception Handling CryptoKit is fully designed for server side applications. It has full exception handling mechanism for stability and recovery from unexpected errors. In addition, it includes a sophisticated logging mechanism that allows collection of data to be used for investigation of such problems if they occur.

Compliance with Industry Standards CryptoKit supports the most common cryptographic standards used by the software industry. CryptoKit provides a full implementation of PKCS#11 V2.20 standard as well as Microsoft’s CSP provider for RSA and Schannel cryptographic operations. Algorithmic Research’s implementation includes most of the functionalities defined by these standards. In addition to that, CryptoKit includes a PKCS#11 like Java library and a standard Java Cryptography Architecture (JCA) provider. Algorithmic Research is comitted to maintaining compatibility with upgrades to these standards in the future.

2-18

Chapter 3 SmartAdaptor Technology CryptoKit is a powerful cryptographic platform that includes the main Software Development Kit (SDK), as well as several plug-ins, adapters and extensions. The following list summarizes the overall CryptoKit environment: CryptoKit Component

Description

SmartAdaptor

Supplies core cryptographic functionality through PKCS#11 API

CSP adapter

Supplies Microsoft CAPI functionality for CAPI based applications such as Internet Explorer, Outlook, smart card logon, Microsoft Office, Microsoft VPN, IIS and more. The CSP adapter is based on the PKCS#11 provider.

Entrust adapter

Serves as plug-in for Entrust products

Java adapter

Includes two libraries: •

A standard Java Cryptography Architecture (JCA) provider.

•

A proprietary adapter that provides PKCS#11 style API to Java applications.

Standard applications PKCS#11 plug-in

Serves as plug-in for Netscape Navigator, Baltimore

X.509 extension

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

PKCS#10,PKCS#7 extension PKCS#12 extension

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

3-1

3


General Concepts SmartAdaptor, providing the main CryptoKit functionality, contains an independent library that adapts PrivateCard smart cards, MiniKey tokens, PrivateServer HSM, CoSign, PrivateSafe reader and readers from a range of vendors to enable them to secure a large variety of applications. SmartAdaptor also serves as the base for building high security adapters, plug-ins and extensions.

CryptoKit Architecture CryptoKit’s main component, SmartAdaptor, is a library that transforms the PKCS#11API, into multifunctional smart card architecture. SmartAdaptor creates a connection between several PKCS#11 providers and enables smart card and reader independence from implementations.

3-2

3

MS CAPI Applications Java e.g., Applications IE/Outlook

Java Adapter

CAPI Adapter

PKCS#11-based Applications e.g., Entrust, Baltimore, Netscape

Entrust Adapter

Extensions

Adapters

User Applications

SmartAdaptor Technology

X.509

PKCS #10,7

PKCS#11 Extension User Interface

SmartAdaptor

Registration API *

11 S# I C P PK A

SmartAdaptor Engine for Multi-thread, Multi-process, Multi-slot, Multi-provider

Reader Provider API

Providers

Smartcard Provider API

Core PKCS#11 Providers

PKCS #12

AR PrivateCard Provider

CT-API Readers

PCSC Readers

Proprietary Interface Readers

* The Registration API can be used by all applications built on SmartAdaptor and must be used by any provider that operates under SmartAdaptor, except for PCSC readers.

3-3

3


SmartAdaptor General Concepts SmartAdaptor supports three different types of providers: Core, Reader and Smart card. Core providers are stand-alone PKCS#11 providers requiring no change to their existing structure. SmartAdaptor enables various PKCS#11 providers to work together in a way that is transparent to the user, with no configurational changes needed. A Reader provider, written for each smart card reader, supplies the reader’s operational functionality. SmartAdaptor supports three kinds of readers: PCSC, CT-API and proprietary readers. PCSC readers do not need to be registered by SmartAdaptor since they are already registered in the Windows operating system, allowing SmartAdaptor to detect them automatically. When a reader has two (or more) supported interfaces, and one of them is PCSC, SmartAdaptor may display the reader twice on the slot list. In order to prevent a multiple listing of the same reader, SmartAdaptor provides an option in the API to block the display of a particular reader as a PCSC device. In this case, it is listed as a proprietary device only. In order to register a CT-API or proprietary reader, the reader’s dll (module) must be supported. The module should contain the functions used to access the reader as well as an entry function, which is used to retrieve the pointers to reader functions. SmartAdaptor only supports AR PrivateCard Smart card provider. The smart card provider translates the high level PKCS#11 API into a sequence of smart card ISO 7816 commands, which in turn, are transmitted through the Reader provider. Third party smart cards can only be supported using their given PKCS#11 core provider dll. SmartAdaptor supports multi-slot, multi-provider, multi-process, and multi-thread environments for applications. Since the PKCS#11 standard does not support multi-provider architectures, SmartAdaptor converts its multi-provider architecture to the PKCS#11 multi-slot architecture and enumerates Reader slot providers in addition to Core slot providers.

3-4

3


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

3-5

3


CryptoKit PKCS#11 Architecture CryptoKit PKCS#11 includes a high-level Application Programming Interface (API) together with supporting cryptographic modules. The following diagram illustrates the security services and tokens supported by CryptoKit PKCS#11 as well as its relationship to applications.

AR or 3 rd Party Applications

AR CryptoKit PKCS#11

Application Programming Interface (API) Standard PKCS#11 PIN Management (policies)

Key Management

Key Exchange

Encryption/ Decryption

Signatures/ Verification

PK-User Authentication

Certificate Processing

Tokens MiniKey

ISO Smartcard – Private Card PrivateServer

3-6

CoSign

3


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

Functions

CKM_RSA_PKCS_KEY_PAIR_GEN

GenerateKeyPair

CKM_RSA_PKCS

Encrypt/Decrypt, Sign/Verify, SignRecover/VerifyRecover, Wrap/Unwrap

CKM_RSA_PKCS_OAEP

Encrypt/Decrypt, Wrap/Unwrap

3-7

3

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


3


Mechanisms

Functions

CKM_RC2_CBC


CKM_RC2_CBC_PAD


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


CKM_DES_CBC


CKM_DES_CBC_PAD


CKM_DES_MAC_GENERAL

Sign/Verify

CKM_DES_MAC

Sign/Verify

CKM_DES2_KEY_GEN

GenerateKey

CKM_DES3_KEY_GEN

GenerateKey

CKM_DES3_ECB


CKM_DES3_CBC


CKM_DES3_CBC_PAD


CKM_DES3_MAC_GENERAL

Sign/Verify

CKM_DES3_MAC

Sign/Verify

CKM_AES_KEY_GEN

GenerateKey

3-9

3

3-10


Mechanisms

Functions

CKM_AES_ECB


CKM_AES_CBC


CKM_AES_CBC_PAD


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


Sign/Verify

CKM_SHA_256_HMAC

Sign/Verify

CKM_SHA_384

Digest


Sign/Verify

CKM_SHA_384_HMAC

Sign/Verify

3


Mechanisms

Functions

CKM_SHA_512

Digest


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


Derive


Derive


Derive

CKM_CONCATENATE_BASE_AND_KEY

Derive

CKM_CONCATENATE_BASE_AND_DATA

Derive

CKM_CONCATENATE_DATA_AND_BASE

Derive

CKM_XOR_BASE_AND_DATA

Derive

CKM_EXTRACT_KEY_FROM_KEY

Derive

CKM_SSL3_PRE_MASTER_KEY_GEN

GenerateKey

CKM_SSL3_MASTER_KEY_DERIVE

Derive

CKM_SSL3_KEY_AND_MAC_DERIVE

Derive

3-11

3


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

3-12

CKM_ARDFP1

Digest

CKM_ARDFP2

Digest

CKM_ARDFP3

Digest

CKM_ARDFP4

Digest

CKM_DES_STREAM

Encrypt/Decrypt

CKM_DES3_STREAM

Encrypt/Decrypt

CKM_DES3EEE_ECB

Encrypt/Decrypt

CKM_DES3EEE_CBC

Encrypt/Decrypt

3


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

DES Stream mechanisms Algorithmic Research’s PKCS#11 includes proprietary DES stream algorithms for backward compatibility with older versions of CryptoKit (Ver 1.63). These algorithms can be used with single-DES keys, Double length DES (DES2) and Triple-DES (DES3) keys to achieve full compatibility. The following table describes how the old algorithms are mapped into CryptoKit: CryptoKit Version 1.63

CryptoKit 3.5 and above

Algorithm

Mode

Mechanism

Key Type

HL_ALG_DES

HL_MODE_CBC

CKM_DES_CBC

DES

HL_ALG_DES

HL_MODE_ECB

CKM_DES_ECB

DES

3-13

3


CryptoKit Version 1.63

3-14

CryptoKit 3.5 and above

Algorithm

Mode

Mechanism

Key Type

HL_ALG_DES

HL_MODE_STREAM

CKM_DES_STREAM

DES

HL_ALG_DES3_EDE

HL_MODE_CBC

CKM_DES3_CBC

DES2

HL_ALG_DES3_EDE

HL_MODE_ECB

CKM_DES3_ECB

DES2

HL_ALG_DES3_EDE

HL_MODE_STREAM

CKM_DES3_STREAM

DES2

HL_ALG_DES3_EEE

HL_MODE_CBC

CKM_DES3EEE_CBC

DES3

HL_ALG_DES3_EEE

HL_MODE_ECB

CKM_DES3EEE_ECB

DES3

HL_ALG_DES3_EEE

HL_MODE_STREAM

CKM_DES3_STREAM

DES3

3


Users, Administrators and Sessions The PKCS#11standard specifies two types of token users: Security Officers (SO), and normal users. In most cases, SO administers the users in an organization (in PKCS#11 implementations for Windows NT4 or UNIX, for example, the system Administrator could be the SO). The first session using a token must be in “Public mode” in PKCS#11 terminology. At this stage, an application can access all public data that does not require user authentication. Only authenticated users, however, can access “private” data. To enable user authentication, an application should call the C_Login function. When the function succeeds, the current session (and all other sessions that were initiated with a token) switches to the “Private mode”. This grants the application full access to all data on the token: Both public and private. The SO must initialize the token (by calling the C_InitToken function) and set the user’s initial PIN before a normal user can log in. In order to initialize the user’s PIN, the SO must log into the public session (it is assumed that the SO PIN was already initialized on each token, and call the C_InitPIN function. Though the SO can manipulate certain public data, PKCS#11 does not allow the SO to gain access to private data. However, since PKCS#11 does not impose a distinction between the SO and users, the SO may also be a user, and gain access to private data by logging on as a normal user.

3-15

3


CryptoKit PKCS#11 Versions Based on licensing approval, the Algorithmic Research PKCS#11 library is shipped in three versions: ♦ Extended – a supports DES, Triple-DES, Double-length DES, AES, RC2 (key length up to 1024 bits), and RC4 (key length up to 2048 bits). This version includes the CryptoKit SDK with include, lib and sample files. ♦ Runtime – supports the same algorithms as the Extended version but does not include the SDK files. ♦ Basic – only supports DES with effective key length of 40 bits. RSA keys in this version are generated for Demo purposes only. This version does not include the SDK files too. These versions support the same RSA (key length up to 4096, DSS and Diffie-Hellman key lengths (up to 1024 bits) and the same hash and key derivation algorithms.

Algorithmic Research CryptoKit PKCS#11 Releases An application can check the library version currently in use by calling the C_GetInfo function. The resulting libraryDescription and libraryVersion fields contain version information.

3-16

3


Tokens and Slots In PKCS#11 terminology, cryptographic “tokens” are cryptographic devices, e.g., smart cards that provide a highly secure form of sensitive information storage, offering PIN (password) protection. Algorithmic Research’s PrivateCard smart card, MiniKey PKI USB token, CoSign and PrivateServer HSM serve as tokens in the CryptoKit PKCS#11 context. “Slots” are smart card readers or other device interfaces connected to the application computer enabling use of the smart card token as storage for cryptographic objects and for performing cryptographic functions. CryptoKit supports many types of smart card readers. It supports readers manufactured by Algorithmic Research such as: PrivateSafe®, CryptoSafe and PrivateSafe PCMCIA as well as any standard PCSC or CT-API compliant reader, manufactured by other vendor. Refer to the Token and Slot section in Chapter 2 for more information about these readers and their facilities. PrivateCard is one of the most intelligent and high performance smart cards available, performing all operations with the RSA private key located internally on the smart card chip. MiniKey is Algorithmic Research’s cryptographic device that functions as both the "Token" and the "Slot". It can be viewed as a smart card reader with PrivateCard built in, and it is plugged into a computer's USB port. MiniKey allows users to conveniently manage their keys and authenticate their identity when connecting to enterprise, e-commerce or other secure applications. CoSign, which provides digital signature services, acts as a network attached smart card. The PKCS#11 interface can be used to access the data stored on the CoSign and to perform digital signatures with the keys stored on the device. For more information refer to the CoSign manual. Algorithmic Research’s PrivateServer may also serve as a high performance network attached smart card device. It can be used by applications that need

3-17

3


PKCS#11 interface to perform cryptographic operations in a large scale for example with CA server, Web server etc. For more information refer to the PrivateServer manual.

Data Stored as Objects Cryptographic tokens (PrivateCard, MiniKey) store data as objects (in addition to performing cryptographic operations). The PKCS#11 standard specifies three types of data objects: Raw data, Certificates and Keys. ♦ Raw data is not defined as an object by its content—the PKCS#11 provider and the application set the data object definition for the data. ♦ Certificate objects store public-key certificates or attribute certificates. ♦ Key objects store cryptographic keys. The PKCS#11 standard identifies three types of key objects: Public keys, Private keys and Secret keys. Each type has subtypes that can be used in relevant mechanisms. For example, PKCS#11 recognizes the following Private key object subtypes: RSA, DSS, etc. Similarly, Secret key objects include DES, DES3, RC2, etc. Objects are classified by token and by session. While token objects remain on the token even after all sessions using the token are closed, and even after the token has been removed from the slot, session objects are temporary. The lifetime of session objects is limited by the duration of the session during which they were created. After closing a session, (by calling the C_CloseSession function or by removing the token from the slot), all objects created in that session as session objects, are automatically deleted. Objects are also classified as Public or Private. To view or use Public objects, there is no need for applications to log into the token. However, authentication is necessary to gain access to Private objects (see the Users, Administrators and Sessions section above).

3-18


3

Tokens can generate, destroy, manipulate, and search for objects—they can also use them (e.g., key objects) to perform cryptographic operations.

PIN Functionality Private objects can be accessed only after a user has successfully presented his PIN to the token, authenticating himself as the owner of the key media. The following explanation of PIN presentation is valid for C_Login, C_InitToken, C_InitPIN and C_SetPIN functions (all functions that contain PIN as a parameter). An application can implement PIN presentation by passing either of the following to all the functions mentioned above: ♦ The PIN as a parameter, causing CryptoKit to present it to the token without presenting the user any dialog. ♦ NULL instead of the PIN, causing the library to prompt the user for PIN entry. In that case, if the token supports secure PIN entry then it will be used; otherwise a regular PIN entry dialog is displayed. CryptoKit has three special modes for presenting the PIN to the token: ♦ Secure PIN entry mode, which is activated when NULL is passed as parameter to the login functions. As documented in the Cryptoki 2.11 standard, this option can be used with tokens that have a protected authentication path (i.e., protected keypad entry). Algorithmic Research’s PrivateCard enables this form of authentication when used with PrivateSafe and CryptoSafe readers, but not with the PrivateSafe PCMCIA reader or MiniKey. During PIN entry, the reader disconnects the keyboard from the computer thus disables exposure of sensitive data. An application can check whether secure PIN entry is enabled on a specific token by calling C_GetTokenInfo and checking the value of protected authentication path flag in the CK_TOKEN_INFO structure.

3-19

3


♦ SSO mode, in which the user is required to present the PIN only once. The PIN is stored in memory and afterwards it is automatically retrieved by CyptoKit everytime logon to the token is required. The SSO functionality is able to store both the user and SO PINs for each slot. When the token is removed or when the user logs off from the workstation, the stored PIN’s are cleared from memory. ♦ Unattended mode, which enables automatic presentation of a PIN that was previously stored in the registry. This mode can be used to automatically authenticate to tokens in unattended machines.

Note: Some applications do not enable implementation of the protected authentication path. They display their own dialog box, prompting MiniKey and PrivateCard users to enter the password (they do not pass NULL instead of the PIN to the C_Login function).

PIN Default Parameters The PKCS#11 standard does not enable additional PIN-related functionality (e.g., setting the expiration period, maximum number of presentation attempts, minimum PIN length, etc.). On the other hand, MiniKey and PrivateCard require setting such parameters for PINs. The application, based on the Cryptoki PKCS#11 API, is not able to set these values Algorithmic Research’s CryptoKit provides a solution by assigning initial default values to user PINs parameters during token initialization. For example, a PIN becomes “expired” if it has not been replaced within the default period of time. Subsequent attempts to use it will return the CKR_PIN_EXPIRED result code and the user should change the PIN by calling the C_SetPIN function. The expiration date is automatically re-computed after replacing the PIN. Due to inconsistencies, the Cryptoki PKCS#11 API does not grant PIN update functionality to its applications when a PIN has expired. As a result, if a user

3-20


3

tries to login after his PIN has expired, he will be locked out of the application since he can use C_Set PIN functionality only after logging in. The current version of Algorithmic Research’s CryptoKit PKCS#11 provides a workaround to this problem in the following way: ♦ If during C_Login, an expired PIN is entered using a protected keypad, the library prompts the user to change his PIN immediately, without exiting from C_Login ♦ If during C_Login, an expired PIN is supplied as a parameter, the library allows the application to call C_SetPIN immediately in order to change his PIN (normally, this function is called in the login state only). If another function is after C_Login then C_SetPIN will fail. CryptoKit offers the exceptional remedies described above, to handle PIN inconsistencies in Cryptoki PKCS#11 API. Algorithmic Research reserves the right to modify this special PIN functionality in the future without prior notification. CryptoKit provides also additional functionality when calling functions that require PIN entry (C_Login, C_InitToken, C_InitPIN and C_SetPIN), with NULL parameter as the password. In this case an appropriate PIN entry dialog box is automatically opened. During a call to C_SetPIN, if the old PIN was entered by protected keypad, the replacement PIN must be entered the same way (i.e., if the old PIN was passed as NULL to the C_SetPIN function, the new PIN must be also passed as NULL). Another security feature provided by the CryptoKit: A new PIN must be different than the one it replaces. Whenever an application needs to be authenticated to the MiniKey or PrivateCard token, it has a restricted number of attempts to present the correct PIN. After exceeding this number, the user PIN is locked and the application may never access sensitive information on the token (though public objects remain accessible). In this event, every C_Login function call will fail with a return code of CKR_PIN_LOCKED.

3-21

3


In the case of successful PIN presentation, the unsuccessful-attempts counter on the MiniKey or PrivateCard token is set to zero again. The C_GetTokenInfo function can supply additional information about the state of the PIN presentations on the token. This state is reported in the following flags in the CK_TOKEN_INFO structure: ♦ CKF_USER_PIN_COUNT_LOW – TRUE if an incorrect user login PIN has been entered at least once since the last successful authentication. ♦ CKF_USER_PIN_FINAL_TRY – TRUE if supplying an incorrect user PIN will it to become locked. ♦ CKF_USER_PIN_LOCKED – TRUE if the user PIN has been locked. User login to the token is not possible. ♦ CKF_SO_PIN_COUNT_LOW – TRUE if an incorrect SO login PIN has been entered at least once since the last successful authentication. ♦ CKF_SO_PIN_FINAL_TRY – TRUE if supplying an incorrect SO PIN will it to become locked. ♦ CKF_SO_PIN_LOCKED – TRUE if the SO PIN has been locked. User login to the token is not possible. The following table describes the default PIN parameters that are set by the CryptoKit installation program for MiniKey, PrivateCard and software tokens. For details how to change these default settings, refer to the CryptoKit Files and Registry Entries section in Chapter 7.

3-22

3


Parameter

Default Values for MiniKey and PrivateCard

Default Values for Explanation & Software token 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 0 (which are 127weeks, approx. 2.5 years)

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

0

0 – Unlimited 3-12 – Number of allowed presentations. If the SO PIN is locked, the token cannot be used anymore

Maximum number 6 of PIN retries for SO

Note: CoSign and PrivateServer devices have their own authentication mechanism, which obsolete the required PIN for the login operation. MiniKey and PrivateCard tokens are supplied to customers with an initial SO (Security Officer) PIN value of 11111111. To change this value, an application can call to C_SetPIN when SO is logged in. Users can also use the AR Genie utility program to change the SO PIN.

3-23

3


Thread Safety The Algorithmic Research implementation of the PKCS#11 standard is thread safe and fully compatible with all PKCS#11 requirements for accessing from multiple threads. If two threads attempt to access the same library simultaneously, the second thread is blocked until the first thread’s request is processed. An application that possesses the parameters to the C_Initialize function can disable this safeguard (in full accordance with PKCS#11specifications). The CryptoKit will serialize requests when several processes share a library. Additionally, according to PKCS#11 specifications, token objects are visible to all applications (possessing sufficient permissions) connected to the token.

Date and Time When the CryptoSafe reader is used, the library acquires the current date and time for PIN presentation and PIN replacement from the reader’s internal clock. For all other cases, CryptoKit uses the computer’s time and date and attempts to factor in the time zone. However, there may be some variation in dates and times due to differences in operating systems, sometimes even on the same computer.

3-24

3


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 compilerdependent (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 platformdependent 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 AR_SOLARIS AR_AIX AR_LINUX

(3) (8) (10) (12)

3-25

3


Refer to your C or C++ compiler reference guide for information on how to set preprocessor symbols. The Cryptoki standard states that on Windows 32bit platform, any structure should be packed with 1-byte alignment. However, CryptoKit is compiled in such a way that any program that uses this library will be able to work properly, regardles of its byte alignment. (The 1-byte packing convention that was required by older versions of CryptoKit is no longer needed).

Platform-Specific Macros The following four platform-specific macros are defined in platform.h file: CK_PTR The indirection string, for making a pointer into an object, can be used as follows: typedef CK_BYTE CK_PTR CK_BYTE_PTR;

For the Windows 32bit platform the following definition was used: #define CK_PTR

*

CK_DECLARE_FUNCTION(returnType, name) This macro creates an importable Cryptoki library function declaration out of a return type and a function name. It is used as follows: extern CK_DECLARE_FUNCTION( CK_RV, C_Initialize ) ( CK_VOID_PTR pReserved );

For the Windows 32bit platform the following definition was used to declare a function in a DLL: #define CK_DECLARE_FUNCTION( returnType, name ) \ returnType __declspec( dllimport ) name

3-26

3


CK_DECLARE_FUNCTION_POINTER(returnType, name) This macro creates a Cryptoki API function pointer declaration or function pointer type declaration out of a return type and a function name. It isused as follows: CK_DECLARE_FUNCTION_POINTER( CK_RV, funcPtr ) ( args );

This macro defines funcPtr as a pointer to a Cryptoki API function taking arguments args and returning CK_RV. You can also use it as follows: typedef CK_DECLARE_FUNCTION_POINTER ( CK_RV, funcPtrType )( args ); funcPtrType funcPtr;

Here it defines funcPtrType to be the type of pointer to a Cryptoki API function that takes arguments args and returns CK_RV, and then defines funcPtr to be a variable of type funcPtrType. For the Windows 32 bit platform the following definition was used to access functions in a DLL: #define CK_DECLARE_FUNCTION_POINTER ( returnType, name ) \ returnType __declspec( dllimport ) ( *name )

CK_CALLBACK_FUNCTION(returnType, name) This macro creates a function pointer type for an application callback using both a return type for the callback and a name for the callback: CK_CALLBACK_FUNCTION( CK_RV, myCallback )( args );

This macro can be used to declare a function pointer, myCallback, to a callback, which takes arguments args and returns CK_RV. You can also use it as follows: typedef CK_CALLBACK_FUNCTION ( CK_RV, myCallbackType )( args ); myCallbackType myCallback;

3-27

3


For the Windows 32bit platform the following definition was used: #define CK_CALLBACK_FUNCTION( returnType, name ) \ returnType( *name )

3-28


3

Registration API The SmartAdaptor Registration API provides developers with tools to manage the various types of providers supported by SmartAdaptor. The API contains functions to register, unregister, list and retrieve specific information about the providers. The following is a list of SmartAdaptor Registration API functions that are defined in the first part of the sadaptor.h file: UMB_CreatePKCS11ProviderContext UMB_CreatePKCS11SmartcardProviderContext UMB_CreateSmartcardReaderContext UMB_CreateFindContext UMB_SetProviderData UMB_AddATRToList UMB_GetProviderData UMB_RegisterProvider UMB_UnregisterProvider UMB_AddFindContext UMB_ListProviders UMB_FreeContext UMB_GetProviderType

See the Registration API functions section below for a description of each function.

Registration API Data Types The data structures listed below are in C-notation and are defined in the sadaptor.h file.

3-29

3


UMB_RV typedef UINT32 UMB_RV;

Retrieves return code types that are returned by all the Registration API functions: ♦ UMB_RV_OK

Operation successful

♦ UMB_RV_END

Reached end of database in a multi-step operation (e.g., Find)

♦ UMB_RV_MEMORY

Insufficient memory

♦ UMB_RV_INVALID_PARAMETERS

Invalid parameters detected

♦ UMB_RV_INSUFFICIENT_BUFFER

Allocated buffer too small

♦ UMB_RV_NOT_FOUND

Object not found in database

♦ UMB_RV_HARDWARE

Hardware error

♦ UMB_RV_CARD_NOT_POWERED

Card inserted but not powered up

♦ UMB_RV_CARD_NOT_PRESENTED

Card not inserted

♦ UMB_RV_COMMUNICATION

Communication problem occurred

♦ UMB_RV_TIMEOUT

Operation took too much time, interrupted by with timeout state

♦ UMB_RV_SHARING_VIOLATION

Smart card or reader temporary inaccessible (locked by another application)

♦ UMB_RV_INTERNAL_ERROR

Internal error occurred

UMB_CONTEXT typedef void * UMB_CONTEXT;

The UMB_CONTEXT is used as a handle to a specific provider that may or may not be registered yet. This structure is created and returned by one of the following functions:

3-30

3


♦ 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]; } UMB_PCSC_EXCLUDE_STRUCT;

// NULL terminated string

This structure is used for readers with a PC/SC interface that are nonetheless registered as a CT-API or proprietary reader and therefore should be excluded

3-31

3


from the enumeration of PC/SC readers. The flag field defines how the reader name should be matched. This attribute can only be assigned to a Reader provider type context with Reader type set to UMB_SC_READER_TYPE_PCSC. Parameters ♦ UMB_COMPARE_ALL – compares readerName to the exact reader name received from PC/SC. ♦ UMB_COMPARE_START – looks for readerName in the PC/SC reader name at the start (similar to file compare “name*”). ♦ UMB_COMPARE_PART – looks for readerName somewhere inside the PC/SC reader name (similar to file compare “*name*”).

UMB_CTAPI_PORT_DESCR typedef struct { short phys_number; short ICC_mask; } UMB_CTAPI_PORT_DESCR;

This structure describes a CT-API reader port. It can only be assigned to a Reader provider type context with Reader type set to UMB_SC_READER_TYPE_CTAPI. For more information, refer to documentation on CT-API specifications. Parameters ♦ phys_number – number of the port to which the reader is connected. This number is passed to the CT_Init function as pn parameter. ♦ ICC_mask – bit mask of the slots available for use in a reader. The lowest bit accords to the first slot, which must be available.

3-32

3


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; char atr[32]; char

atr_mask[32];

// length of the ATR // ATR // // // //

indicates which bits in the ATR read from the smart card should be compared with this ATR

} UMB_ATR_DESCRIPTION;

This structure can only be assigned to a Smart card provider type context and it describes one ATR of a smart card supported by this provider. One Smart card provider can have a number of ATR descriptions (if it supports many smart cards) but at least one must be provided.

3-33

3


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

3-34

UMB_RV_OK – context created successfully.

3


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.

3-35

3


♦ 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_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,

3-36

const char

* module,

const char

* entry,

3


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.

3-37

3


Return Values

UMB_RV_OK – context successfully created.




UMB_SetProviderData After creating the context for a provider using one of the functions described above, you can use this function to assign additional attributes to the provider before registering it in the system. The fieldTag parameter indicates the assigned attribute, len contains its size and data denotes its value. Syntax UMB_RV UMBAPI UMB_SetProviderData( UMB_CONTEXT * context, int

fieldTag,

int

len,

const void

* data);

Parameters ♦ context [in] – the context of the provider for which to set the data. ♦ len [in] – the length of the data passed in the data pointer. ♦ data [in] – the pointer to the attribute to be written in the context. ♦ fieldTag [in] – the following tags may be appended (defined in the sadaptor.h file)

3-38

UMB_PROVIDER_FIELD_INFO – general information about the provider based on the UMB_PROVIDER_INFO structure.


3 UMB_PROVIDER_FIELD_MODULE – NULL terminated string. The full path to the module’s dll. UMB_PROVIDER_FIELD_ENTRY – NULL terminated string. The name of the entry function. UMB_PROVIDER_FIELD_FLAGS – DWORD – has no special significance for SmartAdaptor and can be used for the needs of the provider. UMB_PROVIDER_FIELD_EXCLUDE_FROM_PCSC – derived from UMB_PCSC_EXCLUDE_STRUCT structure, this flag marks a PC/SC reader as excluded from the readers list. It requires that reader context was already created and registered using UMB_CreateSmartcardReaderContext, with type set to UMB_SC_READER_TYPE_PCSC, followed by UMB_RegisterProvider. UMB_PROVIDER_FIELD_CTAPI_PORTS – derived from UMB_CTAPI_PORTS structure, this parameter can only be added to a CT-API type Reader provider. This parameter is mandatory and must be updated for each CT_API reader provider. UMB_PROVIDER_FIELD_ATR_LIST – derived from UMB_ATR_DESCRIPTION structure, this parameter can only be added to a Smart card provider and indicates the ATRs supported by this provider. One Smart card provider can support a number of ATRs. UMB_PROVIDER_FIELD_READER_TYPE – DWORD – this tag, which can only be assigned to Reader providers, may be one of following: UMB_SC_READER_TYPE_CTAPI UMB_SC_READER_TYPE_PROPRIETARY UMB_SC_READER_TYPE_PCSC UMB_PROVIDER_FIELD_DESCRIPTION – NULL terminated string with the provider’s description. UMB_PROVIDER_FIELD_LOG_FILE_NAME – NULL terminated string with a path to the file used for logging the provider.

3-39

3


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

3-40

UMB_RV_OK – data successfully written to the context.

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

3



UMB_GetProviderData This function can be used to retrieve information from the context. The tags are the same as those used with UMB_SetProviderData. If the value for len is too small, it is adjusted to the correct length and the UMB_RV_INSUFFICIENT_BUFFER is returned. If the context does not contain the record, UMB_RV_NOT_FOUND is returned – otherwise UMB_RV_OK is returned and the data field is filled with the appropriate value. When there are multiple occurrences of the requested record in the context (UMB_PROVIDER_FIELD_ATR_LIST and UMB_PROVIDER_FIELD_EXCLUDE_FROM_PCSC tags only), SmartAdaptor treats the len parameter as the size of an array and the data parameter as the array of the appropriate type of records. Syntax UMB_RV UMBAPI UMB_GetProviderData( UMB_CONTEXT context, int

fieldTag,

int

* len,

void

* data);

Parameters ♦ context [in] – the context to read from. ♦ fieldTag [in] – the tag of the field to extract from the context. See the section on UMB_SetProviderData for a description of this parameter. ♦ len [in/out] – on entry to the function should contain the size of the buffer pointed by data. Upon return, len contains the actual size of the data returned. This parameter cannot be NULL. ♦ data [out] – the data marked by fieldTag. Can be NULL – in which case only the size of the data is returned.

3-41

3


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

3-42

UMB_RV_OK – data read successfully.

UMB_RV_INTERNAL_ERROR – unable to store context.

3


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

3-43

3


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:

3-44

UMB_PROVIDER_FIELD_PROVIDER_TYPE – DWORD – uses one of the following (defined in sadaptor.h) – UMB_PROVIDER_TYPE_PKCS11 UMB_PROVIDER_TYPE_READER UMB_PROVIDER_TYPE_PKCS11_SCARD UMB_PROVIDER_FIELD_API_VER – DWORD – part of the provider info structure, it specifies the API version of the provider. UMB_PROVIDER_FIELD_IMPL_VER – DWORD – part of the provider info structure, it specifies the implementation version of the provider. UMB_PROVIDER_FIELD_VENDOR_NAME – NULL terminated string. Part of the provider info structure, it specifies the vendor name of the provider.

3


UMB_PROVIDER_FIELD_PROVIDER_NAME – NULL terminated string. Part of the provider info structure, it specifies the provider name of the provider. UMB_PROVIDER_FIELD_ATR_BUFFER – binary buffer. The length of the ATR is set by the len parameter – may not exceed 32 bytes. Use to set ATR only, without the ATR mask.

Return Values

UMB_RV_OK – data successfully read.



UMB_UnregisterProvider This function removes a provider from the system. If the context parameter is NULL, all registered providers are removed. The context may be of any type. If the type is find, it must include both the provider type and module attributes, otherwise UMB_E_PARAMS is returned. Any provider that matches the context attributes is removed from the system and UMB_RV_OK is returned, otherwise UMB_RV_NOT_FOUND is returned. Syntax UMB_RV UMBAPI UMB_UnregisterProvider( 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.

3-45

3





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

3-46

UMB_RV_OK – data was successfully read.



3



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

3-47

3


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

3-48

UMB_RV_OK – successful result.


3

Reader Provider Development SmartAdaptor supports the PC/SC and CT-API standard reader APIs. SmartAdaptor provides an additional API that enables the system to integrate proprietary readers (not supported by either of the standard APIs). While each reader provider usually has one slot, there is no restriction on the number of slots possible. From the user’s perspective, each slot of a multi-slot reader displays as one independent PKCS#11 slot. PC/SC Readers No additional development is necessary for PC/SC readers since they are registered in the Windows operating system – SmartAdaptor recognizes them automatically. SmartAdaptor also enables you to exclude PC/SC readers from the registry, when, for example, users do not wish to use a specific reader. Also, when a reader supports both the PC/SC API and an additional API (CT-API or proprietary) the reader is listed both in the Windows registry and in SmartAdaptor. Since this double listing causes the same reader to display twice in the Slot list, you can exclude the PC/SC reader from the registry in order to limit the display of the reader in the Slot list to just one time. Use the SmartAdaptor Registration API (or directly edit the registry) to exclude PC/SC readers from the registry – this cannot be accomplished during runtime (see the Registration API section for details). CTAPI Readers Since SmartAdaptor can use the standard CT-API interface, it is not necessary to develop a specific library for CT-API readers. However, you must register CT-API readers in SmartAdaptor since operating systems do not automatically recognize CT-API readers. (For more stable performance in stress situations, vendors can supply a dll with additional functionality, for example, an entry function and an i_am_closed function. For more details see below.)

3-49

3


Proprietary Readers In order to work with a proprietary reader provider, a special dll has to be developed and registered by SmartAdaptor registration API. The dll should include implementation of several functions and an additional special entry function. SmartAdaptor loads the dll and retrieves pointers to the provider’s functions using the entry function. Then, SmartAdaptor mediates between the reader and the Smart card provider by giving the Smart card provider the functions that operate with the reader. As a result, Smart card providers can operate with any reader registered in the SmartAdaptor system. Refer to the following section for a list of the functions that each proprietary reader provider should supply in order to operate correctly.

3-50

3


Reader Provider API Each proprietary Reader provider must contain an implementation of all the functions listed below: UMB_ENTRY UMB_READER_GET_NAME UMB_READER_GET_STATE UMB_READER_POWER_ON UMB_READER_POWER_OFF UMB_READER_TRANSMIT UMB_READER_GET_NATIVE_RESULT_VALUE UMB_READER_CLOSE

UMB_ENTRY The entry function is the first function that SmartAdaptor calls. It is used to initialize the provider and to load pointers to all other functions of the provider. The entry function is also used to provide SmartAdaptor with the number of slots that are supported by the Reader provider. By convention, the slots are counted from zero. Syntax typedef UMB_RV (UMBAPI * UMB_ENTRY) (UMB_ENV

* env,

UMB_PROVIDER_READER

* reader);

Since the entry function is not pre-named, you can assign it any name. This name must be provided (in the entry parameter) when the provider is registered. For more information, refer to function UMB_CreateSmartcardReaderContext in the section SmartAdaptor Registration API Functions. The pointers to all of the Reader provider’s functions are supplied in the output UMB_PROVIDER_READER structure.

3-51

3


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_value; UMB_READER_CLOSE

close;

} UMB_PROVIDER_READER;

Parameters ♦ env [in] – pointer to UMB_ENV structure, which contains only one member that is relevant for the Reader provider – the i_am_closed function. The provider should call this function during the DLL_DETACH process, although this is not mandatory. ♦ reader [out] – pointer to the output UMB_PROVIDER_READER structure. Return Values

3-52

UMB_RV_INTERNAL_ERROR – general error occured.

3


UMB_RV_INVALID_PARAMETERS – if the value of a parameter is NULL.

UMB_RV_OK – successful result.

UMB_READER_GET_NAME This function should return the reader name to SmartAdaptor according to the slot number. Syntax typedef UMB_RV (UMBAPI * UMB_READER_GET_NAME) (UINT32

slotID,

char

* nameBuf,

UINT32

* nameLen);

Parameters ♦ slotID [in] – number of the slot. ♦ nameBuf [out] – pointer to buffer, which receives the NULL terminated name. If this parameter is NULL, it returns needed buffer size in the nameLen parameter and UMB_RV_INSUFFICIENT_BUFFER in return value. ♦ nameLen [in/out] – on entry to the function should contain the maximum length of nameBuf buffer. Upon return, nameLen contains the actual length of the reader name, not including the NULL terminator. Return Values


UMB_RV_INSUFFICIENT_BUFFER – when nameBuf is too small.

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

UMB_RV_OK – operation successful.

3-53

3


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_INVALID_PARAMETERS – when the slot number is invalid or when the pointer to slotState is NULL.


UMB_READER_POWER_ON This function should power-on the smart card and return it’s ATR. Syntax typedef UMB_RV (UMBAPI * UMB_READER_POWER_ON) (UINT32

3-54

slotID,

3


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_INSUFFICIENT_BUFFER – when ATRBuf is too small.

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


UMB_READER_POWER_OFF This function should power-off the smart card. Syntax typedef UMB_RV (UMBAPI * UMB_READER_POWER_OFF) (UINT32 slotID);

Parameters ♦ slotID [in] – number of the slot. Return Values


3-55

3


UMB_RV_INVALID_PARAMETERS – when the slot number is invalid.


UMB_READER_TRANSMIT This function should send command to smart card and return the answer. Syntax typedef UMB_RV (UMBAPI * UMB_READER_TRANSMIT) (UINT32

slotID,

char

* sendBuf,

UINT32

sendLen,

char

* recvBuf,

UINT32

* recvLen);

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

3-56


UMB_RV_INSUFFICIENT_BUFFER – when ATRBuf is too small.

3




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_READER_CLOSE This function should finalize the operation with the reader. It is called only once by SmartAdaptor in the event of DLL_DETACH. Syntax typedef UMB_RV (UMBAPI * UMB_READER_CLOSE)

3-57

3


(void);

Parameters None. Return Values



UMB_READER_I_AM_CLOSED When the entry function is called, SmartAdaptor provides to the Reader provider a pointer to the function UMB_READER_I_AM_CLOSED. The reader provider can call this function during the DLL_DETACH process to notify SmartAdaptor that the reader is no longer available. Calling this function is not mandatory and it is mainly used for handling abnormal termination of the program. Syntax typedef UMB_RV (UMBAPI * UMB_READER_I_AM_CLOSED) (UMB_ENV * env);

Parameters ♦ env [in] – environment variable passed in entry function. Return Values

3-58

UMB_RV_INTERNAL_ERROR – general error occurred.



3

PKCS#11 API Extensions SmartAdaptor supports the full PKCS#11 API functionality. In addition, SmartAdaptor supports functions that enhance the standard PKCS#11 API. These functions are defined in the files pkcsgext.h and pkcs_ui.h. The list below summarizes the SmartAdaptor PKCS#11 enhancements, followed by a more detailed description of the functions. ♦

Functions that provide information about the providers that are registered in the SmartAdaptor system: C_EXT_GetProviderList C_EXT_GetProviderInfo C_EXT_GetProviderContext C_EXT_GetProviderSlotList C_EXT_GetSlotProvider C_EXT_PassToProvider

♦ Functions that support software tokens extensions: C_EXT_Bind C_EXT_Unbind

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

The standard PKCS#11 WaitForSlotEvent function is very limited: It is not possible to specify a group of slots for event waiting, it doesn't return the exact slot on which the event occurred nor does it provide a timeout

3-59

3


option. SmartAdaptor provides these two functions to overcome these limitations. ♦ Functions that provide additional token and object handling: C_EXT_ChangeTokenLabel

This function provides additional token management capability by enabling changing the token label. ♦ Functions that extend the user interface functionality and are defined in p pkcs_ui.h file: C_UI_GetPassword C_UI_SetMessage C_UI_GetMessage

SmartAdaptor can display a window for password entry. The window pops up when users call a PKCS#11 function that requires a password with NULL_PTR. A SmartAdaptor extension mechanism enables users to pop this window and to replace the standard SmartAdaptor messages with customized messages.

3-60

3


Provider Architecture Functionality C_EXT_GetProviderList This function returns the list of providers that are registered in the SmartAdaptor system. Syntax CK_RV C_EXT_GetProviderList( CK_PROVIDER_ID_PTR

pProviderList,

CK_ULONG_PTR

pulCount);

The calling convention of this function is the same as for all PKCS#11 functions that return an array. If the pProviderList pointer is NULL, pulCount returns the size of the needed array and CKR_OK is returned. If pProviderList is not NULL and the pulCount array size is too small, CKR_BUFFER_TOO_SMALL is returned. Otherwise, the array is filled with CK_PROVIDER_IDs and pulCount is updated with the actual number of providers returned. Each CK_PROVIDER_ID is a unique handle that represents a provider. This handle can be used to retrieve additional information about the provider. For additional information, see the functions below. Parameters ♦ pProviderList (output) – receives array of IDs. ♦ pulCount [in/out] – on entry to the function should contain the maximum size of the pProviderList array. Upon return, pulCount contains the actual number of providers read. Return Values

CKR_OK – operation successful.

CKR_FUNCTION_FAILED – erroneous parameters.

3-61

3


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_PROVIDER_ID_INVALID - the provider ID is incorrect. This return code is not a standard PKCS#11 return code. It is defined in the pkcsgext.h file.

CKR_FUNCTION_FAILED – incorrect parameters.

C_EXT_GetProviderContext This function returns the context of the provider, read from the registry. For PC/SC readers, SmartAdaptor itself creates and fills the context.

3-62

3


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


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

3-63

3


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


C_EXT_GetSlotProvider This function returns the provider associated with a specific slot. Syntax CK_RV C_EXT_GetSlotProvider(

3-64

3


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_SLOT_ID_INVALID – the slot parameter is not a valid slot number.

CKR_ARGUMENTS_BAD – the type parameter is not one of the three listed above.

3-65

3


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

3-66

3


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_SLOT_ID_INVALID - the slot parameter is not a valid slot number (if slotID is not 0).

CKR_SESSION_HANDLE_INVALID – the session handle is not valid (if hSession is not 0).

3-67

3


CKR_OBJECT_HANDLE_INVALID – one of the object handles specified is not valid.

Note: In the event of success (C_EXT_PassToProvider calls the relevant function in the provider), the resulting code returned by C_EXT_PassToProvider is according to the code returned by the specific function.

3-68

3


Software Tokens Extensions C_EXT_Bind This function binds a specific file to a dynamic software slot. If no free (unbound) dynamic slot is available, CKR_DEVICE_MEMORY is returned. When one process binds a file to a specific slot, if another process binds the same file, it is assigned the same slot. When two processes share the same dynamic slot (using the same file), if one unbinds the file, the other can still use the slot, until it unbinds the file as well. Syntax CK_RV C_EXT_Bind( const CK_CHAR_PTR name, CK_SLOT_ID_PTR

slot);

Parameters ♦ name [in] – the name of the file to associate with a slot. ♦ slot [out] – the ID of the slot to which the file is assigned. Return Values


CKR_CRYPTOKI_NOT_INITIALIZED – the Cryptoki library has not been initialized.

CKR_DEVICE_MEMORY – there are no more free dynamic slots for this file.

CKR_ARGUMENTS_BAD – the slot parameter is NULL. Note that the function does not check whether the specified file exists.

3-69

3


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

3-70


CKR_CRYPTOKI_NOT_INITIALIZED – the Cryptoki library has not been initialized.

CKR_GENERAL_ERROR – the slot is not a bound dynamic slot.


3

Token Event Extensions C_EXT_WaitForSingleSlotEvent This function waits for an event on a specific slot for a limited period of time. It has two modes of operation: blocking and non-blocking. Syntax CK_RV C_EXT_WaitForSingleSlotEvent( CK_SLOT_ID slot, CK_FLAGS flags, CK_ULONG timeout, CK_VOID_PTR pReserved);

When the flags parameter is equal to zero the function operates in blocking mode. It returns CKR_OK if a slot event had occurred or CKR_NO_EVENT when the timeout has expired. When the flags parameter is equal to CKF_DONT_BLOCK, the function operates in non-blocking mode. It checks if the status of the smart card has changed since the last call to this function and returns immediately to the calling application. The return codes in this case are CKR_OK if a change had occurred or since the last call to the function and CKR_NO_EVENT if no change was detected. Parameters ♦ slot [in] – ID of slot on which an event is monitored. ♦ flags [in] – mode of operation. 0= blocking mode, CKF_DONT_BLOCK=non-blocking mode. ♦ timeout [in] – timeout in milliseconds. ♦ pReserved [in] – reserved. Should be NULL_PTR.

3-71

3


Return Values

CKR_OK – event occurred.

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


CKR_NO_EVENT – no event occurred before the timeout expired.

C_EXT_WaitForSlotEvent This function is similar to C_EXT_WaitForSingleSlotEvent, but it can handle a group of slots. The function receives an array of CK_SLOT_EVENT structures (defined in the pkcsgext.h file). These structures consist of two fields: slot – indicates the slot on which to check for an event, bEvent – a boolean flag, which is TRUE if an event occurred on the slot The function exits upon the first occurrence of an event on one of the slots in the array, or when timeout expires. Syntax CK_RV C_EXT_WaitForSlotEvent( CK_SLOT_EVENT_PTR pSlots, CK_ULONG

number,

CK_FLAGS

flags,

CK_ULONG

timeout,

CK_VOID_PTR

pReserved);

Parameters ♦ pSlots [in/out] – on entry to the function should contain an array of structures with the list of slots to be checked. Upon return, bEvent field of the slots is set to TRUE if an event occurred.

3-72

3


♦ 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_NO_EVENT – no event occurred before the timeout expired.

3-73

3


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

3-74

CKR_OK – operation successful

CKR_FUNCTION_FAILED – pLabel parameter is NULL; Token is not AR proprietary token (PrivateCard or file) or is not formatted properly.

CKR_SESSION_HANDLE_INVALID – the session handle is invalid.

CKR_USER_NOT_LOGGED_IN – user is not logged on.

CKR_FUNCTION_NOT_SUPPORTED – function not supported by provider correspondent to current session

CKR_GENERAL_ERROR – unexpected error in provider dll

3


CKR_TOKEN_NOT_PRESENT – token not present or was removed

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

3-75

3


User Interface Extensions C_UI_GetPassword Note: SmartAdaptor supports this function only for backward compatibility with previous versions. The functionality is now supported by the standard PKCS#11 functions as described below. This function is used to pop up password entry dialog boxes that get the current password and/or get a new password from the user for tokens that do not support “Protected Authentication Path”. The returned passwords, could then be used in standard PKCS#11 functions: C_Login, C_InitToken, C_InitPIN and C_SetPIN as parameters in plain text. In old versions SmartAdaptor disabled execution of these functions with NULL parameters for this type of tokens. From CryptoKit version 3.6.0, this function is not needed anymore. When calling functions that require password entry (C_Login, C_InitToken, C_InitPIN and C_SetPIN) with NULL parameter as the password, an appropriate PIN entry dialog box is opened. Syntax CK_RV C_UI_GetPassword( CK_SLOT_ID

slotID,

CK_ULONG

reason,

AR_CB_PWD_DESCR_PTR

pwdDescr,

CK_CHAR_PTR

password,

CK_CHAR_PTR

newPassword

CK_USER_TYPE

userType);

Parameters ♦ slotID [in] – slot number

3-76

3


♦ reason [in] – reason for the call. May be one of the following values: ARCB_REASON_LOGIN – open login dialog box and get password for C_Login or C_InitToken. ARCB_REASON_NEW_PWD – open init PIN dialog box and get password for C_InitPIN. ARCB_REASON_CNG_PWD – open change password dialog box and get passwords for C_SetPIN ♦ pwdDescr [in] – password parameters structure ♦ password [out] – the current password ♦ newPassword [out] – the new password. NULL if the reason is ARCB_REASON_LOGIN. ♦ userType [in] – type of the user: CKU_SO or CKU_USER Return Values


CKR_CRYPTOKI_NOT_INITIALIZED – Cryptoki library not initialized with C_Initialize.

CKR_SLOT_ID_INVALID – slot number is invalid.

CKR_CANCEL – the user canceled the password entry.

CKR_GENERAL_ERROR – the function was called for a token with Protected Authentication Path; the returned password is NULL or does not match the password parameters in pwdDescr structure.

3-77

3


C_UI_SetMessage The C_UI_SetMessage function enables users to replace the standard SmartAdaptor messages with customized messages. Syntax CK_RV C_UI_SetMessage( CK_SLOT_ID

slotID,

CK_ULONG

ulMsgCode,

CK_CHAR_PTR

message);

It is possible to dynamically set the messages that appear in the following PIN entry dialog boxes: Login Dialog

3-78


3

Init PIN Dialog

Change PIN Dialog

3-79

3


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

3-80



CKR_GENERAL_ERROR – function failed

3


C_UI_GetMessage The C_UI_GetMessage function enables users to get the current values of the messages that appear in the different PIN entry dialog boxes. The returned value is the default message or the last customized message value that was set with C_UI_SetMessage. Syntax CK_RV C_UI_GetMessage( CK_SLOT_ID

slotID,

CK_ULONG

ulMsgCode,

CK_CHAR_PTR

message);

Parameters ♦ slotID [in] – the slot number. ♦ ulMsgCode [in] – the code of message to get. For a complete list see values of this parameter in C_UI_SetMessage above. ♦ message [out] – the current value of the message Return Values



CKR_GENERAL_ERROR – function failed

3-81

3


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 = \arusrgui.dll This command will copy the new user interface dll to your client’s machines during the installation.

3-82

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

4-1

4


Microsoft CryptoAPI and Crypto Service Providers Microsoft provides an API called Crypto API (CAPI) to support cryptographic and PKI (Public Key Infrastructure) operations. The API includes support for general cryptographic operations such as hash, encryption with symmetric keys as well as operations on certificates, public keys and private keys. Microsoft CryptoAPI can work with a number of Cryptographic Service Providers (CSPs) that perform the actual cryptographic functions. Each CSP may be from a different vendor and may have different cryptographic capabilities. By default the Microsoft CSP is installed on any Windows operating system. Applications do not communicate directly with a CSP. Instead, they call CryptoAPI functions (with a "Crypt" prefix) exposed by the operating system's Advapi32.dll and Crypt32.dll files. Applications specify which CSP will be used to perform the required operation. The operating system communicates with CSPs through the cryptographic service provider interface (CSPI). It filters the function-calls and passes them to the appropriate CSP functions through CryptoSPI. A CSP consists of a dynamic-link library (DLL) that implements the functions in CryptoSPI. The CSP must be signed by Microsoft to ensure its authenticity and validity and has to be registered in the operating system before applications can use it. As mentioned above, the CryptoAPI also provides support for handling PKI applications and specifically functions for handling certificates, which are kept in certificate stores. The CryptoAPI provides functions that manage certificate stores, and work with the certificates within those stores. These functions (with a "Cert" prefix) provide tools to store, retrieve, delete, list (enumerate), and verify certificates. Certificates in a certificate store are normally kept in some kind of permanent storage. Each user has a personal store called MY. The store contains all the 4-2

4

AR Cryptographic Service Provider

user's certificates. The MY store can be at any one of many physical locations, including the registry on a local or remote computer, a file, data base, directory, a smart card, or other location. While any certificate can be stored in the MY store, this store should be reserved for user's personal certificates which are used for performing cryptographic operations such as signing and decrypting that user's messages. The following illustration shows these concepts.

Application A

Application B

Application

Layer

Crypto API “Crypt…” API

Operating System

“Cert…” API System certificate store

Crypto SPI CSP #1

CSP #2

CSP #…

Microsoft Base Crypto Provider

ARCSP

Other Vendors CSP

Physical Store #1

Physical Store …

Service Provider

CSP Types Cryptographic standards are organized into groups known as families. Each family includes a set of data formats and protocols. Even if they use the same algorithm, two families will often use different cipher modes, key lengths, and default modes. In CryptoAPI, each CSP type represents a distinct family.

4-3

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 Each provider type specifies only one key exchange algorithm algorithm and every CSP of that type must implement the same algorithm. Applications specify the key exchange algorithm by selecting a CSP of the appropriate provider type. Digital 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

4-4

4


many sample programs that demonstrate how to perform cryptographic operations using the CryptoAPI.

CAPI Data Objects CAPI Applications use handles to refer to data objects in the CSP such as key containers, hash objects, session key objects, and public/private key pair objects.

Context A context is a temporary object that contains key objects, hash objects, and a handle to a specific key container. It enables applications to query and set info of the specific CSP it uses.

Key Objects Key objects may be symmetric keys (DES, RC4, etc.) or asymmetric public keys. They are created only for temporary use and each is associated with a specific context. A key object is destroyed when the context is released. The only case when key objects are stored on the token is when importing private asymmetric keys (RSA key).

Hash Objects Hash objects are temporary objects that are used to hash data. They are associated with a specific context and destroyed when the context is released.

Key Containers Key containers are not temporary objects. They are stored on the smart card and contain up to two pairs of public and private keys. The signature key pair is used to create digital signatures and the exchange key pair is used to both encrypt session keys and create digital signatures. A specific key container is available for the application only when the cryptographic token on which it is stored is available.

4-5

4


A key container may be empty i.e. without any keys. It is possible to create the key container at a specific time and to generate the keys later. Each key container must have a unique name to distinguish it from other key containers. When an application wants to use a specific key container, it can acquire a context to it, by specifying its name.

ARCSP Provider ARCSP Provider Types Algorithmic Research provides two types of CSPs.

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

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

Architecture ARCSP provides cryptographic support for applications that use Microsoft CAPI. It serves as an interface between the CryptoAPI and the PKCS#11-compliant SmartAdaptor. Therefore, it benefits all the special advantages of SmartAdaptor.

4-6


4

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

4-7

4


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

4


♦ If you install a new reader, it will not be available to existing applications until you reset the application. However, it is possible to configure ARCSP to load the list of the available readers when the application releases all open contexts. For more information refer to explanation about the parameter FinalizeLibraryUse in Chapter 7.

Provider Registration When installing CAPI feature in the CryptoKit installation program, the following provider is added to the list of registered CSPs: CSP Provider Name

AR Base Cryptographic Provider

Provider Type

PROV_RSA_FULL (1)

Image Path

Arcsp.dll

ARCSP indicates that it supports hardware, software and removable devices. On Windows 2003 server, an additional cryptographic service provider is registered: CSP Provider Name

AR RSA SChannel Cryptographic Provider

Provider Type

PROV_RSA_SCHANNEL (12)

Image Path

Arcsp.dll

Signature ARCSP is digitally signed by Microsoft and can be used with the released versions of Windows 2003 server, Windows XP, Windows 2000, Windows NT(SP6), Windows 98(+SE) and Windows ME.

4-9

4


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:

4-10

Algorithm ID

Description

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


CALG_SHA_512


Comments

4


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 Same as algorithm 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

4-11

4


Algorithm ID

Description

Comments

CALG_3DES_112

2DES block encryption algorithm


CALG_3DES

3DES block encryption algorithm


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

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

CALG_SCHANNEL_MAC_KEY CALG_SCHANNEL_ENC_KEY

Supported Functions ARCSP supports most of the functions that are required from a CSP by Microsoft. However, there are a few differences in AR’s implementation: some functions and flags are not supported; there are few proprietary parameters and finally, there are cases where the standard is not binding and may be interpreted in different ways.

4-12

4


The following table describes the functions that are supported by AR cryptographic service providers and highlights only the specific differences in AR’s implementation: Function

Comments

CryptAcquireContext

In addition to the regular use, it is possible to enumerate the containers or get information on a specific smart card. To do that, set the CRYPT_VERIFYCONTEXT flag and specify the name of the specific reader in the container name in a fully qualified container name format (\\.\” readername”). Then call CryptGetProvParam to enumerate the containers with that context. If CRYPT_VERIFYCONTEXT flag is set, the container name must be NULL or empty string (except for the case described above). CRYPT_MACHINE_KEYSET is ignored.

CryptReleaseContext CryptSetProvParam

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

CryptGetProvParam

PP_KEYSET_SEC_DESCR – not relevant for smart card CSP PP_UNIQUE_CONTAINER – returns the unique container name of the current key. The behavior of the CSP, though, is unpredicted if you insert two tokens which both have a container with same name. PP_USE_HARDWARE_RNG – ARCSP always returns FALSE in this flag because it can’t guaranty that a hardware token will be selected. However, if that is the case, the random will be from the hardware source.

4-13

4


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

4-14

SYMMETRICWRAPKEYBLOB – not supported PLAINTEXTKEYBLOB – not supported CRYPT_OAEP – not supported

4


Function

Comments

CryptImportKey

SYMMETRICWRAPKEYBLOB – not supported PLAINTEXTKEYBLOB – not supported CRYPT_OAEP – not supported

CryptGetUserKey CryptSignHash

SDescription parameter is not supported. It must be NULL, as recommended by Microsoft.

CryptVerifySignature CryptDuplicateHash

Supported only by the SChannel provider

CryptDuplicateKey

Function not supported

4-15

4


Certificate Store Certificates are kept and maintained in certificate stores. Certificates can be issued to users, computers, services or any other entity that has to be identified. Each entity has certificate store to maintain its own certificates (MY store), root certificates, intermediate certificates and others. The MY store can be implemented by any one of many physical locations. While any certificate can be stored in the MY store, this store should be reserved for a user's personal certificates which are used for performing cryptographic operations. The matching keys for these certificates are expected to be available. In order to make the keys stored in AR’s tokens available for use, ARCSP has to make sure that the certificates of these keys are placed into MY store of the user. When the token is not available the certificate has to be removed from the store. This mechanism is implemented in two ways, depending on the operating system.

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

4-16


4

Physical Certificate Store on Windows 2000, XP and 2003 On Windows 2000, Windows XP and Windows 2003, Microsoft developed a new mechanism called physical certificate store that allows better handling of certificate stores. Each certificate store has two layers: logical layer and physical layer. The logical layer is called system store and does not contain any certificates. Rather, it contains several physical certificate stores. Each operation on the system store activates one or more of its physical certificate store members. Each system store has at least one member, which is the Microsoft default physical certificate store. AR physical store implementation hooks some of the store operations. When called, it performs the required operation on the available tokens. AR hooks to the following store functions: ♦ Open – This store event results from an application calling the functions CertOpenSystemStore or CertOpenStore. The application wants to receive all the available certificates. This triggers ARCSP to enumerate all key containers on the currently available tokens. ♦ Add – This store event results from an application calling the function CertAddCertificateContextToStore in an attempt to add a certificate to the system store. If the certificate being added has it’s matching keys on one of AR’s available tokens, it is written into it. If not, AR’s physical store will report the system store that it did not handle it and the certificate will be placed at a different physical store, probably the Microsoft default store. ♦ Delete – This store event results from an application calling the function CertDeleteCertificateFromStore in an attempt to delete a certificate from the store. If the certificate has a matching key pair on one of AR’s available tokens it should be deleted from the token. Currently, AR’s implementation does not physically remove the certificate from the token. ♦ Close – This store event results from an application calling the function CertCloseStore to close the store. No specific operation is done in that event.

4-17

4


Export/Import Functionality ARCSP offers Export/Import capabilities of keys and certificates: ♦ Export – this operation can be performed on both hardware and software tokens but only on extractable keys. Keys that are not extractable or that are sensitive cannot be exported. ♦ Import – though supported for all kind of tokens, Microsoft applications (IE and Outlook) permit import operations only in the case of objects that were exported using the same provider. As a result, when working with ARCSP, Export/Import operations can only be performed from AR’s tokens to any of AR’s (hardware or software) tokens. CryptoKit offers another method for importing and exporting keys using the PKCS#12 Import/Export utility. This utility can export any extractable key from AR tokens and to import it to any other token. For more information about this utility refer to PKCS#12 Import/Export utility in Chapter 6.

4-18

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

5-1

5


Java Adapter The CryptoKit package includes two Java libraries: ♦ ARJCA – standard Java Cryptography Architecture (JCA) provider. ♦ AR Java PKCS – AR proprietary Java adapter that provides PKCS#11 style API to Java applications.

ARJCA The Java Security API is a core API of the Java programming language, built around the java.security package and its sub-packages. This API is designed to allow developers to incorporate both low-level and high-level security functionality into their programs. The first release of Security API in JDK 1.1 introduced the Java Cryptography Architecture (JCA), a framework for accessing and developing cryptographic functionality for the Java platform. In JDK 1.1, the JCA included APIs for digital signatures and message digests. In subsequent releases, the Java 2 SDK significantly extended the Java Cryptography Architecture. It also upgraded the certificate management infrastructure to support X.509 v3 certificates, and introduced a new Java Security Architecture for fine-grain, highly configurable, flexible, and extensible access control. The JCA encompasses the parts of the Java 2 SDK Security API related to cryptography, as well as a set of conventions and specifications provided in this document. It includes a provider architecture that allows for multiple and interoperable cryptography implementations.

5-2

SmartAdaptor Add-On Adapters

5

The detailed explanation about JCA and numerous samples can be found on the Sun Java home page at: http://java.sun.com/j2se/1.4.2/docs/guide/security/Cry ptoSpec.html

AR implementation The ARJCA implements the following JCA interfaces: ♦ KeyPairGenerator methods for the generation of RSA keys. ♦ Signature methods for RSA signatures. Supported algorithms are SHA1withRSA and MD5withRSA. ♦ KeyFactory methods for creating a key from a specification or returning a key specification of a key. ARJCA supports creation of objects from the following specifications:

Private keys can be created from PKCS8EncodedKeySpec or RSAPrivateCrtKeySpec. Public keys can be created from X509EncodedKeySpec or RSAPublicKeySpec.

ARJCA returns key specification in the following formats:

RSAPrivateKeySpec or RSAPrivateCrtKeySpec for RSA private keys. RSAPublicKeySpec for RSA public key.

The KeyFactory also enables to translate Sun RSA keys into AR RSA keys. ♦ KeyStore methods are used for saving keys into the key store (token). Supported functionalities are:

Storing of RSA public/private keys generated or created using ARJCA KeyPairGenerator or KeyFactory. Storing of RSA public/private keys generated or created by any other JCA provider. This operation will succeed only if the

5-3

5


provider can supply the necessary data for creation of the key objects. Storing of X.509 certificates.

Installation ARJCA has to be installed on a computer with CryptoKit and Java Runtime Environment. Follow the steps below: ♦ Copy arjca.jar and ckit.jar files to: ...\JAVA_DIR\jre\lib\ext where JAVA_DIR is the directory where Java is installed on the computer. ♦ Edit the Java security file java.security in the ...\JAVA_DIR\jre\lib\security directory.

Find the place in the file where the list of installed providers is declared. It should look as follows: security.provider.1=sun.security.provider.Sun security.provider.2=...

If you want the AR provider to be the default provider, for the functionalities it supports, put it first in the list and adjust the priorities for others, so the list will look as follows: security.provider.1=COM.arx.jca.ARJCA security.provider.2=sun.security.provider.Sun security.provider.3=... Otherwise, put it at the end of the list and set it's priority

accordingly. Since many applications access only the default provider, it is recommended to set the ARJCA as such. ♦ Copy the arjca.conf file into user home directory. For example on Windows 2000: C:\Documents and Settings\UserName.DomainName

5-4


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

5-5

5


of the RSA key using the initialize method of the KeyPairGenerator class. The default value for this parameter is 1024 ♦ Extractable – this parameter controls whether ARJCA will generate or create extractable keys. The default of this parameter is 0, i.e. ARJCA normally generates non-extractable keys.

5-6


5

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

java.io.*; java.util.*; java.security.*; java.security.cert.*; java.security.spec.*; java.security.interfaces.*;

public class JHL { private byte[] data = new byte[100]; private byte[] sig = null; String passw = "12345678"; public new } public for

static void main(String[] args) { JHL(); JHL() { (int i = 0; i < data.length; i++) { data[i] = (byte) i;

} basic_test(); } public void abort(String error) { System.out.println(error); System.exit(1); } public void exc_abort(Exception e) { e.printStackTrace(System.out); System.exit(1); } private void basic_test() { KeyPair k_pair = GenerateRSAKeys();

5-7

5


sig = RSAsign(data, k_pair); if (RSAverify(data, sig, k_pair)) { System.out.println("Verify OK"); } else { abort("Verify NOT OK"); } StorePublic("pub key1", k_pair); System.out.println("Test OK!"); } public boolean StorePublic(String pubName, KeyPair RSAkeys) { System.out.println("Storing RSA public key.."); try { KeyStore ks = KeyStore.getInstance("JKS", "ARJCA"); ks.load(null, null); Key pub = RSAkeys.getPublic(); ks.setKeyEntry(pubName, pub, passw.toCharArray(), null); return true; } catch (Exception ex){ exc_abort(ex); } return false; } public boolean RSAverify(byte[] buffer, byte[] signature, KeyPair RSAkeys) { System.out.println("Verifying.."); try { PublicKey pub = RSAkeys.getPublic(); Signature sig=Signature.getInstance("SHA1withRSA", "ARJCA"); sig.initVerify(pub); sig.update(buffer); return sig.verify(signature); } catch (Exception e) {

5-8


5

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

5-9

5


AR Java PKCS The AR Java package (ckit.jar) provides PKCS#11 style API access to Java applications. The Java adapter is implemented through a JNI interface (Java Native Interface) over a C-based PKCS#11 SmartAdaptor interface, providing a set of Java classes for use by developers. While these classes present PKCS#11 functionality in proprietary manner, it remains very similar to the native PKCS#11 architecture, structures and functions, enabling developers already familiar with the PKCS#11 standard to start using these Java classes without a significant learning curve. The detailed information about these Java classes is provided in the JavaDoc files, which is archived in the JavaCKit folder of the CryptoKit installation.

Main Packages The ckit.jar contains two packages: COM.arx.jpkcs11 and COM.arx.jpkcs11.Native. The COM.arx.jpkcs11 package defines classes that are very similar to PKCS#11 standard. It uses the JNI to communicate with the AR native Java dll (ar_jpk11.dll), which calls the underlying PKCS#11 provider supplied by SmartAdaptor (sadaptor.dll). The COM.arx.jpkcs11.Native package contains the classes that extend the classes in the COM.arx.jpkcs11 package and communicate directly with the ar_jpk11.dll using JNI.

Main Classes Following is a list of some of the main classes in ckit.jar. These classes belong to the COM.arx.jpkcs11 package and are extended by the corresponding classes in the COM.arx.jpkcs11.Native package. For a complete list refer to the JavaDoc files in CryptoKit installation. ♦ AR_JPKCS11 This class initializes the PKCS#11 library through the getInstance method. It returns the slot list and provides additional general functions.

5-10

5


♦ AR_JPKCS11Slot This class implements all the PKCS#11 slot functionality. All PKCS#11 functions, which relate to a slot, are mapped into a corresponding method in this class with the same functionality. Some of the methods in this class are: openSession, getMechanismList, initToken, waitForSlotEvent etc. ♦ AR_JPKCS11Session This class implements all the PKCS#11 session related functionality, such as login, creation of objects, generation of keys and performing cryptographic operations like hash, sign, encrypt, decrypt etc. A session object is created by openSession method of the AR_JPKCS11Slot class. ♦ AR_JPKCS11Object This class implements all the PKCS#11 object related functionality, such as setting and getting object attributes, destroying objects etc. It includes the object template constants such as class, token, sensitive, extractable etc. An object of this class can be created by several methods for example by generateKeyPair method of the AR_JPKCS11Session class. ♦ AR_JPKCS11Mechanism This is an abstract class that defines the PKCS#11 mechanisms and returns the mechanism info object through the getInfo method. ♦ AR_JPKCS11Exception This is an extension of Java Exception class. All the PKCS#11 errors are thrown through it. It is possible to get a text explanation about each error by using the errorMessage method.

Sample Program The following sample program shows how to use AR Java PKCS provider to generate an RSA key pair and then sign a buffer with the private key. import java.io.*; import COM.arx.jpkcs11.*; import COM.arx.jpkcs11.Native.*; try { // Initialize

5-11

5


AR = (AR_NativePKCS11) (AR_JPKCS11.getInstance("Sadaptor", null, 0)); AR_JPKCS11Slot[] slots; // Get slot list slots = AR.getSlotList(true); AR_JPKCS11Session sess; if (slots.length > 0) { sess = slots[0].openSession( AR_JPKCS11SessionInfo.AR_JPKCS11_FLG_RW_SESSION | AR_JPKCS11SessionInfo.AR_JPKCS11_FLG_SERIAL_SESSION, null, null); } else { return; } // Create the templates for RSA key pair generation AR_JPKCS11ObjectAttribute[] attr_pub = new AR_JPKCS11ObjectAttribute[4]; AR_JPKCS11ObjectAttribute[] attr_priv = new AR_JPKCS11ObjectAttribute[2]; byte[] Exponent = {(byte)0x0,(byte)0x1,(byte)0x0,(byte)0x1}; // Public key template attr_pub[0] = new AR_JPKCS11ObjectAttribute( AR_JPKCS11Object.AR_JPKCS11_CLASS, AR_JPKCS11Object.AR_JPKCS11_CLASS_PUBLIC_KEY); attr_pub[1] = new AR_JPKCS11ObjectAttribute( AR_JPKCS11Object.AR_JPKCS11_KEY_TYPE, AR_JPKCS11Object.AR_JPKCS11_KEY_TYPE_RSA); attr_pub[2] = new AR_JPKCS11ObjectAttribute( AR_JPKCS11Object.AR_JPKCS11_MODULUS_BITS, new Integer(1024));

5-12


5

attr_pub[3] = new AR_JPKCS11ObjectAttribute( AR_JPKCS11Object.AR_JPKCS11_PUBLIC_EXPONENT, new BigInteger(Exponent)); // Private key template attr_priv[0] = new AR_JPKCS11ObjectAttribute( AR_JPKCS11Object.AR_JPKCS11_CLASS, AR_JPKCS11Object.AR_JPKCS11_CLASS_PRIVATE_KEY); attr_priv[1] = new AR_JPKCS11ObjectAttribute( AR_JPKCS11Object.AR_JPKCS11_KEY_TYPE, AR_JPKCS11Object.AR_JPKCS11_KEY_TYPE_RSA); // Create mechanism object AR_JPKCS11Mechanism mech_gen = new AR_NativePKCS11Mechanism( AR_JPKCS11Mechanism.AR_JPKCS11_MECH_RSA_PKCS_KEY_PAIR_GEN, sess.getSlot(), null); // Generate key pair: keys[0] public, keys[1] private AR_JPKCS11Object keys[] = sess.generateKeyPair(mech_gen, attr_pub, attr_priv); AR_JPKCS11Mechanism mech_sign = new AR_NativePKCS11Mechanism( AR_JPKCS11Mechanism.AR_JPKCS11_MECH_MD5_RSA_PKCS, sess.getSlot(), null); // Perform sign operation sess.signInit(mech_sign, keys[1]); byte [] buffer = "To be signed".getBytes(); byte [] signature = new byte[128]; sess.sign(buffer, 0, buffer.length, signature, 0); } catch (Exception ex) { System.out.println(“Exception!”); ex.printStackTrace(System.out); System.exit(1); }

5-13

5


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

5-14

Entrust/Express

Fully featured e-mail application that provides key and certificate management. It enables users to encrypt, decrypt, digitally sign and verify e-mails.

Entrust/TrueDelete

Works in the background to delete files from disk according U.S. Department of Defense standards. It protects the swap file, locates hidden temporary files, and deletes files so that they cannot be retrieved by disk recovery utility.

Entrust ICE

Protects sensitive information by encrypting files in a specified folder.

5


Entrust Desktop Solution applications v5.1, v6.0 Entrust/Direct

Provides permanent records of user transactions. Works with standard browsers and Web servers to provide strong encryption and centralized control over security policy.

Entrust/SingOn

Allows user to login once to the Windows operating system and all Entrust-Ready applications.

Entrust 6 CA enables using the keys and certificates with CAPI based applications. When this option is selected in the Entrust CA, the user certificates are written on the public area of the token. In order for ARCSP to be able to use these keys there is an additional step that has to be done. A special procedure called “standardize” which can be activated from AR Genie utility program creates a corresponding public key and verifies that all objects have the same ID value. In that way ARCSP is capable of identifying the containers on the token and makes them available for CAPI applications. For more information refer to explanation about the AR Genie utility in chapter 6.

5-15

5


X.509 Toolkit With the addition of the X.509 Toolkit, The PKCS#11 CryptoKit now supports the X.509 v.3 certificate standard. The X.509 Toolkit provides a set of programming tools for compliance with ITU-T Recommendation X.509, and the IETF-PKIX's RFC 2459. This library enables parsing and encoding of X.509 certificates and Certificate Revocation Lists (CRLs), while using the cryptographic power of CryptoKit for signing and verifying signatures. The functions and data types in the X.509 Toolkit are very straightforward, extracted directly from the X.509 definition, and are therefore easy to understand and use. The X.509 Toolkit does not supply a CA (Certificate Authority) or any functions for communicating with one; application programmers should obtain the certificates and CRLs independently.

Overview Using the X.509 Toolkit assumes a good working knowledge of public key cryptography and PKI (Public Key Infrastructure), including the X.509 recommendation. The following section provides a short overview of these topics, and while useful as background material, it does not replace extensive study of these subjects.

Public Key Cryptography A cryptographic algorithm is a method, usually based on some mathematical function, used for authentication and/or secrecy. Some applications demand only secrecy or only authentication; others demand both. The security of a cryptographic scheme resides entirely in the secret key, and not in the secrecy of the algorithm.

5-16


5

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

Certificates and Certificate Authorities (CAs) A problem still exists with this method: when Bob asks Alice for her public key, Mallory can intercept Bob’s request and pretend to be Alice. Mallory can then send Bob his (Mallory’s) own public key. Bob, believing he was in communication with Alice, would send his secret messages encrypted with Mallory’s public key, and only Mallory would be able to read them! How can Bob be fully confident that the public key he receives is truly Alice’s? This is accomplished via a trusted third party – a Certification Authority (CA). Let’s assume that Bob wants Alice’s public key. He sends a request for Alice’s public key to the CA. The CA sends Alice’s public key to Bob, digitally signed by the CA. By using the CA’s public key (assuming he possesses it), Bob can verify that it was indeed Alice’s public key that he received.

5-17

5


The CA has a list of users and their public keys. Each user must give the CA his own public key, and receive the CA’s public key in a secure way. Then the user can securely obtain any other user’s public key from the CA. The CA stores a user’s public key in a data structure known as a Certificate, which also includes other relevant data concerning the public key: the cryptographic algorithm it is used with, and its period of validity, amongst other important details.

X.509 The following is an excerpt from the X.509 standard that was formulated by the ITU-T: “This Recommendation – International Standard defines a framework for the provision of authentication services by Directory to its users. It describes… strong authentication, involving credentials formed using cryptographic techniques… only strong authentication should be used as the basis for providing secure services.”

X.509 defines a common methodology for working with certificates. X.509 includes definitions of a standard certificate, as well as a Certificate Revocation List (CRL). A CRL lists certificates that have been invalidated for some reason before their date of expiration. The certificate, CRL, and their components are defined using ASN.11 The X.509 certificate has evolved through several versions. Version 1 included seven fields. This was extended to nine fields in version 2. Version 3 introduced a tenth field (extensions), which enables the addition of any number of fields, and makes the standard more robust. The Internet Engineering Task Force's Public Key Infrastructure working group (IETF-PKIX) defines in RFC 2459 some more extensions, and the correct procedures for using X.509 certificates and extensions. Some extension types are standard, and others may be added to customize certificates for specific applications.

1

Abstract Syntax Notation One, as defined in ITU-T Recommendation X.680.

5-18

5


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.

5-19

5


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.

5-20

5


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.

5-21

5


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 int main(int argc, char **argv) { FILE

* f; X509_certificate * cert; CK_BYTE encCert[5000]; CK_BYTE decCert[5000];

5-22

5


CK_ULONG CK_ULONG CK_RV

encCertLen; decCertLen = sizeof(decCert); rc;

f = fopen(argv[1],"rb"); encCertLen = fread(encCert,1,5000,f); fclose(f); rc = C_X509_Decode(CK_X509_ID_CERT, encCert, encCertLen,decCert,&decCertLen); cert = (X509_certificate *)decCert; printf("Certificate version %d\n",cert->tbs.version); return 0; }

The program first reads the encoded certificate from a file. The memory block needed for decoding the certificate into is provided by an array. The buffer is decoded. At the end the program prints the certificate version number. C_X509_Decode is called with the following parameters: ♦ CK_X509_ID_CERT – the input buffer is a certificate. When decoding a CRL the value of this parameter should be CK_X509_ID_CRL. ♦ encCert – the input encoded certificate. ♦ encCertLen – the size in bytes, of the encoded certificate. ♦ decCert – a buffer for putting the decoded certificate into. ♦ decCertLen – the size, in bytes, of the decCert buffer. The formal declaration of hl_x509_decode is: int C_X509_Decode(CK_ASN_ID

Type,

CK_VOID_PTR

pEncoded,

CK_ULONG

ulEncodedLen,

CK_VOID_PTR

pDecoded,

CK_ULONG_PTR

pulDecodedLen);

5-23

5


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 int main(int argc, char **argv) { FILE CK_BYTE CK_ULONG CK_RV CK_ULONG CK_ULONG

* f; encCert[5000]; encCertLen; rc; version; 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)&version, &verLen,CK_X509_CERT_FIELD_VERSION); printf("Certificate version %d\n",version); return 0; }

In this example, C_X509_GetField is used for decoding only the version field of the encoded certificate, by specifying the CK_X509_CERT_FIELD_VERSION constant as the last parameter. This is possible for all fields; refer to the Constants section of this chapter for a 5-24

5


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 int main(int argc, char **argv)

5-25

5 { FILE


* f; CK_BYTE CK_ULONG CK_RV CK_SLOT_ID CK_ULONG CK_SESSION_HANDLE

encCert[5000]; encCertLen; rc; pSlotList[10]; ulCount = 10; 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,&hSession); rc = C_X509_Verify(hSession,CK_INVALID_HANDLE, CK_X509_ID_CERT,encCert,encCertLen,NULL_PTR,0); if (rc != CKR_OK) printf("*** error verifying – %x\n",rc); else printf("Verification successful!\n"); rc = C_CloseSession(hSession); rc = C_Finalize(NULL_PTR); return 0; }

After reading the input file and opening a cryptographic session, C_X509_Verify is called with the following parameters: ♦ hSession – handle to an open session.

5-26

5


♦ CK_INVALID_HANDLE – No external key is needed for verification. ♦ CK_X509_ID_CERT – the input buffer is a certificate. When decoding a CRL the value of this parameter should be CK_X509_ID_CRL. ♦ encCert – the input encoded certificate. ♦ encCertLen – the size, in bytes, of the encoded certificate. ♦ NULL_PTR – no external CA certificate is needed for verification. ♦ 0 – the size of the CA certificate, if present. The return code CKR_OK indicates that the signature is valid. Usually the pCACert parameter would be the certificate of the CA, which signed the certificate that is now being verified. The formal declaration of C_X509_Verify is: int C_X509_Verify(CK_SESSION_HANDLE hSess, CK_OBJECT_HANDLE

hKey,

CK_ASN_ID

Type,

CK_VOID_PTR

pSignedObject,

CK_ULONG

ulSignedObjectLen,

CK_VOID_PTR

pCACert,

CK_ULONG

ulCACertLen);

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

5


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 void CK_ULONG CK_BYTE CK_ULONG

type, * structuredData, structuredDataLen, * encoded, * encodedLen)

{ CK_RV CK_BYTE_PTR CK_ULONG CK_ULONG CK_SLOT_ID CK_ULONG CK_SESSION_HANDLE CK_CHAR_PTR CK_ULONG

5-28

rc; pCertBuf; certBufLen = 0; encTbsLen; pSlotList[10]; ulCount = 10; hSession; pin = "12345678"; attribPrivateKey = CKO_PRIVATE_KEY;


5

CK_ULONG attribRSA = CKK_RSA; CK_ATTRIBUTE findRSAPrivateKey[] = { {CKA_CLASS,&attribPrivateKey, sizeof(attribPrivateKey)}, {CKA_KEY_TYPE, &attribRSA, sizeof(attribRSA)}, }; CK_ULONG ulObjectsFound; CK_OBJECT_HANDLE hPrivateKey; rc = C_X509_Encode(type,structuredData, structuredDataLen,NULL,&certBufLen); if (rc == CKR_BUFFER_TOO_SMALL) pCertBuf = malloc(certBufLen); else if (rc != CKR_OK) { printf("*** error in encode – %x\n",rc); return rc; } encTbsLen = certBufLen; rc = C_X509_Encode(type,structuredData, structuredDataLen,pCertBuf,&certBufLen); if (rc != CKR_OK) { printf("*** error encoding – %x\n",rc); return rc; } 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,&hSession); if (rc != CKR_OK) { printf("*** Error in C_OpenSession – %x\n",rc); C_Finalize(NULL_PTR);

5-29

5


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, &ulObjectsFound); 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",rc); C_Finalize(NULL_PTR); return rc; } rc = C_X509_Sign(hSession,hPrivateKey,type,pCertBuf, 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);

5-30

5


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

5-31

5


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 int main(int argc, char **argv) { FILE CK_BYTE CK_ULONG CK_BYTE CK_ULONG CK_RV CK_ULONG

* f; encCert[5000]; encCertLen; encCrl[5000]; encCrlLen; rc; result;

f = fopen(argv[1],"rb"); encCertLen = fread(encCert,1,5000,f);

5-32


5

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,NULL,&result); if (rc == CKR_OK) { if (result == CKR_X509_DIFFERENT_ISSUERS) printf("Certificate and crl are from different issuers\n"); else if ((result >= CKR_X509_FOUND) && (result < CKR_X509_NOT_FOUND)) printf("Certificate has been revoked!\n"); else if (result == CKR_X509_NOT_FOUND) printf("certificate has not been revoked\n"); } else printf("*** Error in C_X509_FindInCRL – %x\n",rc); return 0; }

In this example, C_X509_FindInCrl is given the full certificate and CRL as input. The function finds the certificate’s serial number and issuer, checks that the CRL and certificate are from the same issuer, and then looks for the serial number in the revocation list.

5-33

5


The formal declaration of C_X509_FindInCrl is: int C_X509_FindInCRL(CK_VOID_PTR

pEncodedObj,

CK_ULONG

ulEncodedObjLen,

CK_VOID_PTR

pEncodedCRL,

CK_ULONG

ulEncodedCRLLen,

CK_ASN_ID

Type,

CK_VOID_PTR

pRevoked,

CK_ULONG_PTR pulRevokedLen, CK_ULONG_PTR pulResult);

Each revoked item in the CRL has a serial number, revocation time, and some optional extensions. If you want C_X509_FindInCrl to return the complete structure associated with the serial number, send a memory buffer in pRevoked. This will provide all the relevant data in X509_Revoked structure pointed to by pRevoked. A revoked certificate’s extensions field may include a reasons extension. In this case, the pulResult value returned from C_X509_FindInCrl is not CKR_X509_FOUND, but rather includes the reason for revocation, such as CKR_X509_FOUND_KEY_COMPROMISE. An alternative way to use C_X509_FindInCrl is to send it an X509_tbs structure, or just the serial number of the certificate. For example, you could use C_X509_GetField to retrieve the serial number of the certificate, and then call C_X509_FindInCrl. This call may appear as follows: rc = C_X509_FindInCRL(serialNum,serialNumLen,encCrl, encCrlLen,CK_X509_ID_SER_NUM,NULL,NULL,&result);

Using this technique, C_X509_FindInCrl cannot check if the issuer is the same for both certificate and CRL; the application programmer must do this.

5-34

5


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 #include int main(int argc, char **argv) { FILE X509_certificate CK_BYTE CK_BYTE CK_ULONG CK_ULONG CK_BYTE CK_ULONG X509_Dname CK_RV

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

5-35

5


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

5-36

Type,

CK_VOID_PTR

pSrc,

CK_ULONG

ulSrcLen,

CK_VOID_PTR

pDst,

CK_ULONG_PTR

pulDstLen);

5


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-isoccitt(2) ds(5) ce(29) 15 }

Object identifiers are used in X.509 for various applications: identifying encryption and hash algorithms, extension types, distinguished names and more. In the X.509 Toolkit, the object identifiers are stored in a data structure of type X509_obj_id. The object identifiers that are known to the X.509 Toolkit are given an internal constant integer value for easier manipulation, and are stored as integers in X509_obj_id's int_id field; for the key usage extension, this constant is ASN1_EXT_KEY_USAGE. 5-37

5


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:

5-38

Algorithm Identifiers PKCS (#7, #9 and #12) Attribute Types (for Distinguished Names) Extensions Qualifier Types Key Purposes Hold Instructions Attribute Certificates

5


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.

5-39

5


Certificate/CRL Fields

5-40

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.

5


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


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


CK_X509_CERT_FIELD_EXT_2930 CK_X509_CERT_FIELD_EXT_NAME_CONSTRAINTS


CK_X509_CERT_FIELD_EXT_2931 CK_X509_CERT_FIELD_EXT_CRL_DIST_POINT


CK_X509_CERT_FIELD_EXT_2932 CK_X509_CERT_FIELD_EXT_CERTIFICATE_POLICIES


CK_X509_CERT_FIELD_EXT_2933 CK_X509_CERT_FIELD_EXT_POLICY_MAPPING


5-41

5


Certificate/CRL Fields

5-42

CK_X509_CERT_FIELD_EXT_2935 CK_X509_CERT_FIELD_EXT_AUTH_KEY_ID


CK_X509_CERT_FIELD_EXT_2936 CK_X509_CERT_FIELD_EXT_POLICY_CONSTRAINTS


CK_X509_CERT_FIELD_EXT_2937 CK_X509_CERT_FIELD_EXT_EXTENDED_KEY_USAGE


5


Object Types The following are internal object types used as the Type variable in the X.509 functions. Object Types

4

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

A printable hex representation of the serial number.

5-43

5


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

5-44

X509_GN_OTHER_NAME

General name type is OTHER NAME; data is the original unparsed encoded data.

X509_GN_RFC822_NAME

General name is an e-mail address; data is cast to char *.

X509_GN_DNS_NAME

General name is a Domain Name Server (DNS); data is cast to char *.

X509_GN_X400_ADDR

General name is an X400 Address; data is the original unparsed encoded data.

X509_GN_DNAME

General name is a distinguished name; data is cast to X509_Dname *.

X509_GN_EDI_NAME

General name is an EDI Party name; data is the original unparsed encoded data.

X509_GN_URL

General name is a Universal Resource Identifier; data is cast to char *.

X509_GN_IP_ADDR

General name is an IP address, which is an array of bytes; data is cast to unsigned char *.

X509_GN_REG_ID

General name is a registered Identifier; data is cast to X509_obj_id *.

5


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

5-45

5


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

5-46

ASN1_OI_PKCS7_1

PKCS#7 data

ASN1_OI_PKCS7_2

PKCS#7 Signed data

ASN1_OI_PKCS7_3

PKCS#7 Enveloped data

ASN1_OI_PKCS7_4

PKCS#7 Signed and Enveloped data

ASN1_OI_PKCS7_5

PKCS#7 Digested Data

ASN1_OI_PKCS7_6

PKCS#7 Encrypted Data

ASN1_OI_PKCS9_1

PKCS#9 E-mail Address

ASN1_OI_PKCS9_2

PKCS#9 Unstructured Name

5


Object Identifiers: PKCS ASN1_OI_PKCS9_3

PKCS#9 Content Type

ASN1_OI_PKCS9_4

PKCS#9 Message Digest

ASN1_OI_PKCS9_5

PKCS#9 Signing Time

ASN1_OI_PKCS9_6

PKCS#9 Counter Signature

ASN1_OI_PKCS9_7

PKCS#9 Challenge Password

ASN1_OI_PKCS9_8

PKCS#9 Unstructured Address

ASN1_OI_PKCS9_9

PKCS#9 Extended Certificate attribute

Object Identifiers: Attribute Types (for Distinguished Names) ASN1_OI_COMMON_NAME

Common name

ASN1_OI_COUNTRY

Country

ASN1_OI_ORG

Organization

ASN1_OI_ORG_UNIT

Organizational Unit

ASN1_OI_SURNAME

Surname

ASN1_OI_SERIAL_NUM

Serial Number

ASN1_OI_LOCALITY

Locality

ASN1_OI_STATE

State

ASN1_OI_STREET

Street

ASN1_OI_POSTAL_ADDR

Postal Address

ASN1_OI_POSTAL_CODE

Postal Code

ASN1_OI_POB

Post Office Box

5-47

5


Object Identifiers: Attribute Types (for Distinguished Names) ASN1_OI_PHONE_NUM

Phone Number

ASN1_OI_TELEX_NUM

Telex Number

ASN1_OI_FAX_NUM

FAX Number

ASN1_OI_USER_PASSWD

User Password

ASN1_OI_USER_CERT

User Certificate

ASN1_OI_CA_CERT

CA Certificate

ASN1_OI_IP_ADDR

IP Address

ASN1_OI_TELEX_TERM_ID

Telex Terminal Number

ASN1_OI_TITLE

Title

Object Identifiers: Extensions

5-48

ASN1_EXT_SUBJECT_KEY_ID

Subject Key Identifier extension

ASN1_EXT_KEY_USAGE

Key Usage extension

ASN1_EXT_PRIV_USAGE_PERIOD

Private Key Usage Period extension

ASN1_EXT_SUBJECT_ALT_NAME

Subject Alternative Name extension

ASN1_EXT_ISSUER_ALT_NAME

Issuer Alternative Name extension

ASN1_EXT_BASIC_CONSTRAINTS

Basic Constraints extension

ASN1_EXT_CRL_NUMBER

CRL Number extension

ASN1_EXT_REASON_CODE

CRL Reason Code extension

ASN1_EXT_INSTRUCTION_CODE

Instruction Code extension

ASN1_EXT_INVALIDITY_DATE

Invalidity Date extension

5


Object Identifiers: Extensions ASN1_EXT_DELTA_CRL_INDICATOR

Delta CRL Indicator extension

ASN1_EXT_ISSUING_DIST_POINT

Issuing Distribution Point extension

ASN1_EXT_CERT_ISSUER

Certificate Issuer extension

ASN1_EXT_NAME_CONSTRAINTS

Name Constraints extension

ASN1_EXT_CRL_DIST_POINT

CRL Distribution Point extension

ASN1_EXT_CERTIFICATE_POLICIES

Certificate Policies extension

ASN1_EXT_POLICY_MAPPING

Policy Mapping extension

ASN1_EXT_AUTH_KEY_ID

Authority Key Identifier extension

ASN1_EXT_POLICY_CONSTRAINTS

Policy Constraints extension

ASN1_EXT_EXTENDED_KEY_USAGE

Extended Key Usage extension

Object Identifiers: Qualifier Types ASN1_OI_QT_CPS

Certification Practice Statement

ASN1_OI_QT_UNOTICE

User Notice

Object Identifiers: Key Purposes ASN1_OI_KP_SERVER_AUTH

Web Server Authentication

ASN1_OI_KP_CLIENT_AUTH

Web Client Authentication

ASN1_OI_KP_CODE_SIGNING

Signing of Downloadable Executable Code

ASN1_OI_KP_EMAIL_PROT

E-mail Protection

5-49

5


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

5-50

ASN1_OI_HI_NONE

None

ASN1_OI_HI_CALL_ISSUER

Call Issuer

ASN1_OI_HI_REJECT

Reject


5

General Data Types The following are the application-specific data definitions for the X.509 Toolkit, as defined in cx509def.h. Note that the X.509 Toolkit also uses some data types defined in PKCS#11. These data types are used to represent the ASN.1 structures of X.509 certificates and CRLs. The following figure shows the hierarchical relationship between the different structures that are defined in the X.509 Toolkit. The right tree structure shows the X509_certificate structure while the left tree shows X509_crl. The different data structures are explained below.

5-51

5

5-52


5


Basic Data Types The following are basic data types, as defined in the X.509 Toolkit: IDs of the various data types: #define

CK_ASN_ID

int

Fields to be decoded: #define

CK_X509_FIELD

int

#define

CK_X509_CERT_FIELD

int

#define

CK_X509_CRL_FIELD

int

CK_DATA CK_DATA is a general data structure for holding any kind of data and its size in bytes. typedef struct { CK_VOID_PTR ptr; CK_ULONG

size;

} CK_DATA;

CK_TIME_T CK_TIME_T is the time (in seconds) that has elapsed since midnight, 1/1/1970. For dates until the year 2038, this value is identical to time_t (long integer). CK_TIME_T (unsigned long) can represent all subsequent dates until the year 2106. #define

CK_TIME_T

unsigned long

X509_certificate X509_certificate is the main certificate data structure. It consists of two parts: the information to be signed (tbs), and the signature. The C_X509_Decode function returns data in this format, when applied on a certificate.

5-53

5


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;

X509_unique_id

subject_id; // subject unique id

X509_extensions

extensions; // certificate extensions

} X509_tbs;

5-54

// issuer unique id

5


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.

5-55

5


typedef struct { X509_alg_struct

sign_alg; // algorithm of the signature

int

sig_len;

CK_BYTE_PTR

signature; // binary signature

// signature length

} X509_signature;

X509_alg_struct The X509_alg_struct contains data about a cryptographic algorithm: the algorithm object identifier, and algorithm parameters such as key_size and initialization vector (iv). For example, for DSA, params is cast to X509_DSA_params. typedef struct { X509_obj_id

alg_id; // algorithm id

CK_DATA

params; // additional parameters

} X509_alg_struct;

X509_obj_id TheX509_obj_id structure contains information about an object identifier. When the X.509 Toolkit recognizes the object identifier, its stores its internal code in int_id. When the object identifier is not recognized, the whole object identifier is stored in char_id as a sequence of numbers separated by dots (for example, 2.5.29.15 for the key usage extension). typedef struct { int

int_id;

char CK_PR

char_id;

} X509_obj_id;

5-56

5


X509_alg_params_key_iv The params field of X509_alg_struct is cast to the X509_alg_params_key_iv data type if the algorithm parameters include both key size and initialization vector. Note that this is irrelevant for public key algorithms. typedef struct { int

key_size;

CK_BYTE_PTR

iv;

} X509_alg_params_key_iv;

X509_alg_params_key The params field of X509_alg_struct is cast to the X509_alg_params_key data type if the algorithm parameters include only key size. typedef struct { int

key_size;

} X509_alg_params_key;

X509_DSA_params The params field of X509_alg_struct is cast to the X509_DSA_params data type for the DSA signature algorithm. typedef struct{

}

int

key_size; // length of p in bytes

BYTE

p[128]; // prime number of length key_size

BYTE

q[20]; // 160-bit prime factor of p-1

BYTE

g[128]; // h^((p-1)/q) mod p for // smallest h s.t. g>1

X509_DSA_params;

5-57

5


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

glen; // length of g in bytes

CK_BYTE_PTR g; int

// generator

qlen; // length of q in bytes

CK_BYTE_PTR q; int

// prime number

// prime factor of p-1

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 DiffieHellman key exchange algorithm. typedef struct { int

seed_len;

CK_BYTE_PTR seed; int

// seed length in bytes // seed

pgen_len; // length of pgenCounter in bytes

CK_BYTE_PTR pgenCounter; } X509_validation_params;

5-58

5


X509_Dname The X509_Dname contains the main structure for Distinguished Names, as defined in X.500. The Distinguished name is constructed of Relative Distinguished Names (RDNs). RDNs is an array of num_of_RDNs pointers. For example, to access the third RDN of a distinguished name use dname.RDNs[2]. typedef struct { int

num_of_RDNs;

X509_RDN CK_PTR

RDNs;

} X509_Dname;

// Distinguished name

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

num_of_ATAVs;

X509_ATAV CK_PTR

ATAVs;

} X509_RDN;

// Relative Distinguished Name

X509_ATAV The X509_ATAV structure is used to store an Attribute Type and Value. Available types are listed in the Constants section above.

5-59

5


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;

CK_BYTE_PTR value; } X509_ATAV;

// length of value // value itself

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

5-60

algorithm_id; // algorithm id of the key

5


CK_DATA

public_key; // public key data

} X509_key_info;

X509_def_key_info X509_def_key_info structure contains public key data for algorithms, whose information consists of the key length and the key itself (such as DSA). typedef struct { int

key_length;

// key length

CK_BYTE_PTR public_key;

// public key

} X509_def_key_info;

X509_RSA_key_info X509_RSA_key_info structure contains public key data, when the algorithm is RSA, and both the key and the exponent are required. typedef struct { int

key_length; // key length

CK_BYTE_PTR public_key; // public key int

exp_length; // exponent length

CK_BYTE_PTR exp;

// exponent

} X509_RSA_key_info;

X509_unique_id X509_unique_id structure contains in the data field a unique id (unparsed) and its length in the length field. typedef struct { int

length;

// length of data

CK_BYTE_PTR data; // unique id as was in the cert } X509_unique_id;

5-61

5


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;

5-62

5


X509_ext The X509_ext is a general structure for one extension. It contains data about the type of extension, and how critical it is. The data pointer is cast to a structure according to the type of extension. For example, if ext_id = 2915, you could use the following line: X509_ext_2915 KeyUsage= (X509_ext_2915*)cert_exts.extensions[3].data; Note that extension structures can be named interchangeably with a full name, or a shorter extension number (see Certificate/CRL fields in the section on Constants). When the extension is unknown (understood = = FALSE), data will be cast to X509_ext_0000. typedef struct _Ext { X509_obj_id ext_id;

// obj id of extension type

CK_BBOOL

critical;// is the extension critical

CK_BBOOL

understood; // is the extension understood

int

ext_length; // extension length

CK_VOID_PTR data;

// the extension itself

} X509_ext;

X509_ext_0000, X509_ext_unknown This structure is used when the X.509 Toolkit is unable to parse an extension. The extension is then copied unparsed into ext_data, and the data’s length is put in ext_length. typedef struct { int

ext_length;

CK_BYTE_PTR ext_data; } X509_ext_0000, X509_ext_unknown;

5-63

5


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

5-64

not_before; // private key not valid before

5


CK_TIME_T

not_after; // private key not valid after

} X509_ext_2916, X509_ext_PrivateKeyUsagePeriod;

X509_ ext_2917_8, X509_ext_AltName X509_ext_2917 structure is used to store subject and issuer alternative names. This estension is a linked list of general names. typedef struct _Ext_2917_8 { X509_general_name CK_PTR

general_name;

struct _Ext_2917_8 CK_PTR

next_name;

} X509_ext_2917_8, X509_ext_AltName;

X509_general_name The X509_general_name structure contains a general name. The possible types of general names are listed in the Constants section above. The general name is parsed into the data field and should be cast according to its type (string, distinguished name, etc.). When the general name is unparsed (parsed = = FALSE), the full-unparsed general name is stored in the data field. typedef struct { int

type;

CK_BBOOL

parsed;

int

len;

CK_VOID_PTR data; } X509_general_name;

X509_ext_2919, X509_ext_BasicConstraints The X509_ext_2919 structure contains the basic constraints extension. If ca field is TRUE, the subject is certified to act as a CA. The pathLenConstraint field indicates the number of CA-certificates that may follow this one (if ca is TRUE). The value –1 means that no value was specified for this field. typedef struct {

5-65

5


CK_BBOOL

ca;

int

pathLenConstraint;

} X509_ext_2919, X509_ext_BasicConstraints;

X509_ext_2920, X509_ext_CRLNumber The X509_ext_2920 structure contains the CRL number extension. It enables a CRL user to detect when a particular CRL supersedes another CRL. typedef struct { int

CRLnumber;

} X509_ext_2920, X509_ext_CRLNumber;

X509_ext_2921, X509_ext_CRLreason X509_ext_2921 structure is usually used as an extension to a revoked item in a CRL. It specifies the reason for the revocation. The data structure is also used as part of the X509_distribution_point structure for specifying the types of revocation reasons that may be distributed through the CRL distribution point. typedef struct { CK_BBOOL

unspecified;

CK_BBOOL

keyCompromise;

CK_BBOOL

cACompromise;

CK_BBOOL

affiliationChanged;

CK_BBOOL

superseded;

CK_BBOOL

cessationOfOperation;

CK_BBOOL

certificateHold;

CK_BBOOL

removeFromCRL;

} X509_ext_2921, X509_ext_CRLreason;

X509_ext_2923, X509_ext_HoldInstructionCode The X509_ext_2923 structure contains the hold Instruction Code CRL extension. It is used to prove a registered instruction identifier, which indicates

5-66

5


the action to be taken after encountering a certificate that has been placed on hold. typedef struct { X509_obj_id holdInstructionCode; } X509_ext_2923, X509_ext_HoldInstructionCode;

X509_ext_2924, X509_ext_InvalidityDate The X509_ext_2924 structure contains the CRL invalidity date extension. It provides the date on which it is known or suspected that the private key was compromised or that the certificate otherwise became invalid. typedef struct { CK_TIME_T invalidityDate; } X509_ext_2924, X509_ext_InvalidityDate;

X509_ext_2927, X509_ext_DeltaCRLIndicator The X509_ext_2927 structure contains the CRL delta Indicator extension. It identifies the CRL as a delta CRL. The baseCRLNumber is the number of the CRL that this Delta CRL is based on. typedef struct { int baseCRLNumber; } X509_ext_2927, X509_ext_DeltaCRLIndicator;

X509_ext_2928, X509_ext_IssuingDistributionPoint The X509_ext_2928 structure contains the CRL Issuing Distribution Point extension. It identifies the CRL distribution point for a particular CRL, and indicates certain restrictions on the contents of the CRL. typedef struct { X509_DPN CK_PTR

DP;

CK_BBOOL

onlyContainsUserCerts;

CK_BBOOL

onlyContainsCACerts;

X509_ext_CRLreason CK_PTR onlySomeReasons;

5-67

5


CK_BBOOL

indirectCRL;

} X509_ext_2928, X509_ext_IssuingDistributionPoint;

X509_ext_2929, X509_ext_CertificateIssuer The X509_ext_2929 structure contains CRL Certificate Issuer extension. It identifies the certificate issuer associated with an entry in an indirect CRL. typedef struct { X509_general_names certificateIssuer; } X509_ext_2929, X509_ext_CertificateIssuer;

X509_ext_2930, X509_ext_NameConstraints The X509_ext_2930 structure contains the name constraints extension. It is built of two general subtrees: permitted and excluded. typedef struct { X509_general_subtree CK_PTR

permitted;

X509_general_subtree CK_PTR

excluded;

} X509_ext_2930, X509_ext_NameConstraints;

X509_general_subtree The X509_general_subtree structure represents a single general subtree within a connected list of general subtrees. The base field is the general name of the base of the subtree, and min and max are the upper and lower bounds in the tree. The next_subtree field is a pointer to the next subtree. typedef struct _General_subtree { X509_general_name CK_PTR

base;

int

min;

int

max;

struct _General_subtree CK_PTR

next_subtree;

} X509_general_subtree;

5-68

5


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 X509_RDN CK_PTR } X509_DPN;

full_name;

name_relative_to_CRL_issuer;

// Distribution Point Name

5-69

5


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 {

5-70

int

num_of_policies;

X509_obj_id CK_PTR

issuer_domain_policy;

X509_obj_id CK_PTR

subject_domain_policy;

5


} X509_ext_2933, X509_ext_PolicyMappings;

X509_ext_2935, X509_ext_AuthorityKeyIdentifier X509_ext_2935 structure contains the authority key identifier extension data. The key may be identified in two different ways: ♦ As key_id – an octet string identifying the key. The octet string and its length are stored in CK_DATA data structure. ♦ By identifying the certificate associated with the key. As auth_cert_issuer, the issuer of the certificate, and cert_ser_num, the certificate’s serial number. typedef struct { CK_DATA

key_id;

X509_general_names CK_PTR

auth_cert_issuer;

char CK_PTR

cert_ser_num;

} X509_ext_2935, X509_ext_AuthorityKeyIdentifier;

X509_ext_2936, X509_ext_PolicyConstraints X509_ext_2936 structure specifies constraints, which may require explicit certificate policy identification or inhibit policy mapping for the remainder of the certification path. The RequireExplicitPolicy and inhibitPolicyMapping fields specify the number of certificates in the path to skip before starting with these constraints. A value of (–1) for any of these fields means that no value was specified. typedef struct { int

requireExplicitPolicy;

int

inhibitPolicyMapping;

} X509_ext_2936, X509_ext_PolicyConstraints;

5-71

5


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

num_of_ids;

X509_obj_id CK_PTR

key_purpose_id;

} X509_ext_2937, X509_ext_ExtendedKeyUsage;

5-72

5


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.

5-73

5


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

5-74

5


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


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,

5-75

5


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


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

5


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_BUFFER_TOO_SMALL – the buffer supplied was too small. The amount of memory required (beyond what was supplied) is returned in pulDstLen.


CKR_BADLY_FORMATTED_INPUT – a bad structure was given to the function.

5-77

5


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


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.

5-78

5


♦ 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_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_UNSUPPORTED_ENC_ALG – X.509 Toolkit does not support the encryption algorithm.

CKR_UNSUPPORTED_HASH_ALG – X.509 Toolkit does not support the hash algorithm.

CKR_KEY_SIZE_RANGE – key size not supported by the X.509 Toolkit for this algorithm.

C_X509_EncodeSign C_X509_EncodeSign receives an X509_certificate or X509_crl data struture, DER encodes it, and signs it with the user’s private key, thereby constructing a fully signed X.509 certificate or CRL object. C_X509_EncodeSign requires that a cryptographic session be opened before it is called. C_X509_EncodeSign uses the signature_alg field of the input to know which hash and signature algorithm to use. Note that a DSA signature incorporates random data, which results in different lengths of ASN.1 encoding. When the function is not given enough memory, the return size may be a few bytes more than actually required for the signing.

5-79

5


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


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

5-80


5


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

5-81

5


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 selfsigned certificate. ♦ ulCACertLen [in] – the size in bytes of pCACert. Return codes

5-82


CKR_SIGNATURE_INVALID – signature is invalid.

CKR_X509_KEY_NOT_VALID_YET – validity period has not begun.

CKR_X509_KEY_NOT_VALID_ANYMORE – validity period has ended.

CKR_X509_UNKNOWN_CRITICAL_EXTENSION – certificate/CRL has an unknown extension, which is marked critical.

5


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




CKR_KEY_SIZE_RANGE – X.509 Toolkit does not support the required key size for this algorithm.

C_X509_FindInCrl C_X509_FindInCrl checks if a certificate is listed in a CRL. This is accomplished by checking that the issuer (if a complete certificate or X509_tbs is supplied) is the same, and then comparing the certificate's serial number to the serial numbers specified in the revocation list. Syntax int C_X509_FindInCRL( CK_VOID_PTR

pEncodedObj,

CK_ULONG

ulEncodedObjLen,

CK_VOID_PTR

pEncodedCRL,

CK_ULONG

ulEncodedCRLLen,

CK_ASN_ID

Type,

CK_VOID_PTR

pRevoked,

CK_ULONG_PTR

pulRevokedLen,

CK_ULONG_PTR

pulResult);

Parameters

5-83

5


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

5-84

CKR_X509_DIFFERENT_ISSUERS – the certificate and CRL are from different issuers. CKR_X509_NOT_FOUND – the certificate was not found in the CRL. CKR_X509_FOUND – the certificate was found in the CRL, but no reason for revocation was specified. CKR_X509_FOUND_KEY_COMPROMISE – the certificate was revoked because the key was compromised. CKR_X509_FOUND_CA_COMPROMISE – the certificate was revoked because the CA was compromised. CKR_X509_FOUND_AFFILIATION_CHANGED – the certificate was revoked because of a change in the subject’s name or other information.


5

CKR_X509_FOUND_SUPERSEDED – the certificate was revoked because it was superseded. CKR_X509_FOUND_CESSATION_OF_OPERATION – the certificate was revoked because it is no longer required for the purpose it was issued for. CKR_X509_FOUND_CERTIFICATE_HOLD – the certificate was placed on hold. CKR_X509_FOUND_REMOVE_FROM_CRL – the certificate should be removed from the CRL (used only with delta-CRLs).

Return codes


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


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

5-85

5


PKCS#10,#7 Certificate Request and Reply The building blocks for any application based on PKI (Public Key Infrastructure) are public key certificates. These serve as a digital ID for the End Entity, which can be a person, a software application or a hardware device. A public key certificate is issued to the End Entity by a trusted third party called a CA (Certificate Authority), which must first receive a certificate request message from the End Entity. The CA verifies that the request is valid and was indeed sent by the End Entity, and then creates a certificate reply message, which includes the End Entity's certificate. Currently, some standard and legacy message protocols are used for processing certificate requests and issuing certificates. Applications implemented around the world use protocols such as PKIX, CMP/CRMF, PEM, VeriSign's CRS and Cisco's SCEP. One of the simplest and most popular methods for certification messages uses PKCS#10 certificate requests, and PKCS#7 certificate replies (also known as a "certificates only SignedData PKCS#7 message"). The PKCS#10,#7 Toolkit is an add-on to PKCS#11 for handling certificate requests and replies through PKCS#10 and PKCS#7 formatted messages. This library includes functions for encoding and decoding both PKCS#10 certificate requests and PKCS#7 certificate replies, including signing and signature verification where needed. The PKCS#10,#7 Toolkit uses Algorithmic Research's X.509 Toolkit library to process certificate operations, such as signature verification.

5-86


5

General Data Types The PKCS#10,#7 Toolkit defines specific data types in ck_pk107.h. It also uses generic data types as defined in PKCS#11 and in Algorithmic Research's X.509 Toolkit. These data types are used to represent the ASN.1 structure of a PKCS#10 certificate request. The following figure shows the hierarchical relationship between the different structures described later in this section.

5-87

5


CRQ_FORMAT DER encoding is used to encode PKCS#10 certificate requests. It creates a binary message from the stream of data. Some applications though, require that the binary certificate request be converted to a text message, possibly with a header and footer. CRQ_FORMAT defines the exact format of the PKCS#10 certificate request. #define CRQ_FORMAT int

Possible Values ♦ BASIC_PKCS10 – DER encoded binary data. ♦ BASE64_PKCS10 – Base64 encoding of the DER data, results in a text message. ♦ VERISIGN_CSR – Base64 encoding of the DER data with header and footer as defined for VeriSign's CSR message.

CRP_FORMAT Similarly to the PKCS#10 certificate request, the PKCS#7 certificate reply can be encoded as a binay stream of data in DER format. Some applications though, require that the binary certificate reply be converted to a text message, possibly with a header and footer. CRP_FORMAT defines the exact format of the PKCS#7 certificate reply. #define CRP_FORMAT int

Possible Values ♦ BASIC_PKCS7 – DER encoded binary data. ♦ BASE64_PKCS7 – Base64 encoding of the DER data, results in a text message. ♦ VERISIGN_PKCS7 – Base64 encoding of the DER data with header and footer as defined by VeriSign for replies to CSR messages.

5-88

5


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

5-89

5


♦ subject_key_info – public key of the subject (must be the public key paired with the private key used to sign the message). ♦ attributes – additional attributes.

X509_attributes The X509_attributes structure contains a set of attributes that provide additional information about the requesting entity and its keys. typedef struct { int

num_of_attributes;

X509_attribute CK_PTR

attributes;

} X509_attributes;

♦ num_of_attributes – number of attributes in this set. ♦ attributes – array of num_of_attributes attributes.

X509_attribute The X509_attribute contains one attribute consisting of its type and its value(s). typedef struct { X509_obj_id

type;

int

num_of_values;

X509_attr_value }

CK_PTR

values;

X509_attribute;

♦ type – object Identifier defining the attribute type. ♦ num_of_values – number of different values defined for this attribute. ♦ values – array of num_of_values values.

5-90

5


X509_attr_value The X509_attr_value structure contains the value of an attribute. typedef struct {

}

CK_BYTE

value_type;

int

value_len;

CK_BYTE_PTR

value;

X509_attr_value;

♦ value_type – ASN.1 value type (e.g., Printable String – 0x13). ♦ value_len – length of the value, in bytes. ♦ value – actual value.

simple_dname The simple_dname structure is a simplified version of a certificate request. It can be used as input for creating a PKCS#10 certificate request, with the C_PKCS10_SimpleCreateCRQ function. typedef struct { CK_ASN_ID

RDN_type;

char

value[64];

} simple_dname;

♦ RDN_type – type of the RDN (Relative Distinguished Name) value. ♦ value – actual value (a null terminated string).

certs_and_crls The certs_and_crls structure contains a list of certificates and CRLs. This structure is used as input or output to different PKCS#7 functions. typedef struct {

5-91

5


cert_list

CK_PTR certs;

cert_list

CK_PTR crls;

} certs_and_crls;

♦ certs – list of certificates. ♦ crls – list of CRLs.

cert_list The cert_list data structure contains a list of certificates or CRLs. typedef struct { CK_BYTE_PTR

}

CK_PTR

certs;

CK_ULONG_PTR

certLen;

CK_ULONG

numOfCerts;

cert_list;

♦ certs – an array of numOfCerts binary (DER encoded) certificates/CRLs. ♦ certLen – array featuring the size, in bytes, of each corresponding certificate/CRL – array size is defined by numOfCerts. ♦ numOfCerts – the number of certificates/CRLs in the list.

5-92

5


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.

5-93

5


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

5-94

5


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

5-95

5


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

5-96

5


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

5-97

5


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

"ck_pk107.h" "pkcs11.h"

int main() { CK_RV CK_SLOT_ID CK_ULONG CK_SESSION_HANDLE

rc; pSlotList[10]; ulCount = 10; 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(attribPrivateKey)}, {CKA_KEY_TYPE,&attribRSA,sizeof(attribRSA)},}; CK_ATTRIBUTE findDSAPrivateKey[] = { {CKA_CLASS,&attribPrivateKey,sizeof(attribPrivateKey)}, {CKA_KEY_TYPE,&attribDSA,sizeof(attribDSA)},};

5-98

5


CK_ULONG CK_OBJECT_HANDLE

ulObjectsFound; hPrivateKey;

FILE simple_dname BYTE CK_ULONG

* f; dnames[10]; encodedCrq[2048]; encodedCrqLen = sizeof(encodedCrq);

// Change these for different key types, crq formats, or // output file names int keyType = ASN1_OI_RSA; CRQ_FORMAT crqFormat = BASE64_PKCS10; char fname[32] = {"out.crq"}; // Setup distinguished name values sprintf(dnames[0].value,"IL"); dnames[0].RDN_type = ASN1_OI_COUNTRY; sprintf(dnames[1].value,"Algorithmic Research Ltd."); dnames[1].RDN_type = ASN1_OI_ORG; sprintf(dnames[2].value,"PKCS#10 Sample"); dnames[2].RDN_type = ASN1_OI_COMMON_NAME; // Open cryptographic session 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) {

5-99

5


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,&ulObjectsFound); if ((rc != CKR_OK) || (ulObjectsFound != 1)) { printf("*** Error in C_FindObjects – %x, ulObjectsFound=%d\n",rc,ulObjectsFound); C_Finalize(NULL_PTR); exit(0); } rc = C_FindObjectsFinal(hSession); if (rc != CKR_OK) { printf("*** Error in C_FindObjectsFinal – %x\n",rc); C_Finalize(NULL_PTR); exit(0); } // Create the PKCS#10 CRQ rc = C_PKCS10_SimpleCreateCRQ(hSession,hPrivateKey, crqFormat,dnames,3, encodedCrq,&encodedCrqLen); if (rc != CKR_OK) { printf("*** Error %x in SimpleCreatePKCS10CRQ\n",rc); C_Finalize(NULL_PTR); exit(0); } // Save CRQ to file f = fopen(fname,"wb"); if (f) {

5-100


5

fwrite(encodedCrq,1,encodedCrqLen,f); fclose(f); printf("CRQ created successfully and saved in file %s\n",fname); } else printf("*** Error – Unable to open output file %s\n",fname); // Close crypto rc = C_Logout(hSession); if (rc != CKR_OK) printf("*** Error in C_Logout – %x\n",rc); 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.

5-101

5


♦ 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 #include #include #include

"ck_pk107.h" "pkcs11.h"

int main(int argc, char **argv) { FILE char CK_SLOT_ID CK_ULONG CK_SESSION_HANDLE CK_CHAR_PTR

5-102

* f; fname[32]; pSlotList[10]; ulCount = 10; hSess; pin = "12345678";

5


CK_RV BYTE CK_ULONG BYTE CK_ULONG CK_ULONG certs_and_crls CRP_FORMAT CK_ULONG

rc; encodedCrp[4096]; encodedCrpLen = sizeof(encodedCrp); decodedCrp[4096]; decodedCrpLen = sizeof(decodedCrp); tmpLen; * CertsAndCrls; crpFormat = BASE64_PKCS7; 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); }

5-103

5


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); } // The value of crpFormat doesn't really matter since the // function determines the format according to the input rc = C_PKCS7_AcceptCRP(hSess,crpFormat,encodedCrp,encodedCrpLen, decodedCrp,&decodedCrpLen,NULL); if (rc != CKR_OK) { printf("*** Error in C_PKCS7_AcceptCRP – %x\n",rc); 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;icerts->numOfCerts;i++) { sprintf(fname,"cert%d.crt",i+1); f = fopen(fname,"wb"); if (f) { fwrite(CertsAndCrls ->certs>certs[i],1,CertsAndCrls ->certs->certLen[i],f); printf("Certificate written to file %s\n",fname); } else printf("*** Error – Failed to open file %s for output\n",fname); } } // Write CRLs to files

5-104

5


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

5-105

5


♦ 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 #include #include #include #include #include

"ck_pk107.h" "pkcs11.h" "ck_x509.h"

CK_RV GetKeyHandle(CK_SESSION_HANDLE CK_OBJECT_HANDLE int

5-106

hSession, CK_PTR hKey, alg_id);

5


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 \n"); printf("\t = CA certificate file\n"); printf("\t = file with crq\n"); printf("\t = (1)basic der, (2)basic base64, (3)VeriSign csr\n"); printf("\t = Serial number to be given to the new certificate\n\n"); exit(0);

5-107

5


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

5-108

5


// 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,encodedCrq,encodedCrqLen, decodedCrq,&decodedCrqLen); 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,encodedCrtLen, decodedCrt,&decodedCrtLen); if (rc != CKR_OK) { printf("*** Error in C_X509_Decode – %x\n",rc); C_Finalize(NULL_PTR); exit(0); } pCert = (X509_certificate *)decodedCrt;

5-109

5


// Create new certificate using CA certificate data as a basis // Set Serial Number pCert->tbs.serial_number = argv[4]; // Subject distinguished name pCert->tbs.subject.num_of_RDNs = pCr->cri.subject.num_of_RDNs; pCert->tbs.subject.RDNs = pCr->cri.subject.RDNs; // Subject public key info pCert->tbs.subject_key_info.algorithm_id.alg_id.int_id = pCr->cri.subject_key_info.algorithm_id.alg_id.int_id; pCert->tbs.subject_key_info.algorithm_id.alg_id.char_id = pCr->cri.subject_key_info.algorithm_id.alg_id.char_id; pCert->tbs.subject_key_info.algorithm_id.params.ptr = pCr->cri.subject_key_info.algorithm_id.params.ptr; pCert->tbs.subject_key_info.algorithm_id.params.size = pCr->cri.subject_key_info.algorithm_id.params.size; pCert->tbs.subject_key_info.public_key.ptr = pCr->cri.subject_key_info.public_key.ptr; pCert->tbs.subject_key_info.public_key.size = pCr->cri.subject_key_info.public_key.size; // Set validity period for one year time(&(pCert->tbs.validity.not_before)); pCert->tbs.validity.not_after = pCert->tbs.validity.not_before + 3600*24*365; // For this example we will not use any extensions pCert->tbs.extensions.extensions = NULL; pCert->tbs.extensions.num_of_ext = 0; // Logon to media rc = C_Login(hSess,CKU_USER,NULL_PTR,0); if (rc != CKR_OK) { printf("*** Error in C_Login – %x\n",rc); C_Finalize(NULL_PTR); exit(0); } // Find the signing key

5-110


5

rc = GetKeyHandle(hSess,&hKey,pCert ->signature.sign_alg.alg_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,pCert,decodedCrtLen, encodedCrt,&encodedCrtLen); encodedCrtLen = sizeof(encodedCrt) – encodedCrtLen; /* Close crypto, not needed anymore rc = C_Logout(hSess); if (rc != CKR_OK) { printf("*** Error in C_Logout – %x\n",rc); C_Finalize(NULL_PTR); exit(0); } C_Finalize(NULL_PTR); // Prepare certs_and_crls structure for PKCS#7 cert reply pCerts[0] = encodedCrt; CertsLen[0] = encodedCrtLen; CertList.certs = pCerts; CertList.certLen = CertsLen; CertList.numOfCerts = 1; CertsAndCrls.certs = &CertList; CertsAndCrls.crls = NULL_PTR; // Encode crp rc = C_PKCS7_CreateCRP(crpFormat,&CertsAndCrls, encodedCrp,&encodedCrpLen); if (rc != CKR_OK) { printf("*** Error in C_PKCS7_CreateCRP – %x\n",rc); exit(0); }

5-111

5


// Save crp to file f = fopen(outFile[crpFormat-1], "wb"); if (!f) { printf("*** Error opening file %s for output\n",outFile[crpFormat-1]); exit(0); } fwrite(encodedCrp,1,encodedCrpLen,f); fclose(f); printf("Certificate reply saved to file %s\n",outFile[crpFormat-1]); return(0); } // Get a handle to the private key object CK_RV GetKeyHandle( CK_SESSION_HANDLE hSession, CK_OBJECT_HANDLE CK_PTR hKey, int alg_id) { CK_RV rc; CK_ULONG attribPrivateKey = CKO_PRIVATE_KEY; CK_ULONG attribRSA = CKK_RSA; CK_ULONG attribDSA = CKK_DSA; CK_ATTRIBUTE findRSAPrivateKey[] = { {CKA_CLASS,&attribPrivateKey,sizeof(attribPrivateKey)}, {CKA_KEY_TYPE,&attribRSA,sizeof(attribRSA)},}; CK_ATTRIBUTE findDSAPrivateKey[] = { {CKA_CLASS,&attribPrivateKey,sizeof(attribPrivateKey)}, {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);

5-112


5

if ((rc != CKR_OK) || (ulObjectsFound != 1)) { printf("*** Error in C_FindObjects – %x, ulObjectsFound=%d\n",rc,ulObjectsFound); return rc; } rc = C_FindObjectsFinal(hSession); if (rc != CKR_OK) { printf("*** Error in C_FindObjectsFinal – %x\n",rc); return rc; } return CKR_OK; }

The input parameters of this application are: ♦ CA_file – the name of the CA certificate file, which is used for extracting the CA's Distinguished Name. ♦ crq_file – the name of the certificate request file. ♦ crq/p format – the format of the certificate request. The same format is used for the certificate reply. ♦ SN – the serial number for the newly created certificate. Other data needed for creating the certificate: ♦ Signature algorithm – same signature algorithm as the one used on the CA certificate. ♦ Validity period – the application uses the PC clock to define the start of the validity period, and adds one year to set the end of the validity period. ♦ Subject Distinguished Name – copied from the certificate request. ♦ Subject key info – copied from the certificate request. ♦ Extensions – no extensions are used.

5-113

5


See the X.509 Toolkit section for more information about decoding of the CA certificate, and encoding and signing of the End Entity certificate. The program processes certificate requests and replies in three stages: 1. First, it reads the certificate request and the CA certificate from the input files. Then, it opens a cryptographic session, and calls C_PKCS10_AcceptCRQ for parsing and verifying the certificate request: rc = C_PKCS10_AcceptCRQ(hSess,crqFormat,encodedCrq, encodedCrqLen, decodedCrq,&decodedCrqLen);

The input parameters are: ♦ hSess – handle to cryptographic session. ♦ crqFormat – the format of the certificate request, as indicated by the third program parameter. ♦ encodedCrq – the buffer into which the certificate request was loaded. ♦ encodedCrqLen – the length of the certificate request. ♦ decodedCrq – the buffer for the output pkcs10_cr structure. ♦ decodedCrqLen – the length of the decodedCrq buffer. Note: This application does not check whether the certificate request actually originated from the entity written in the Distinguished Name section of the certificate request, nor whether this entity is approved to get a certificate from this CA. 2. Then, the program parses the CA certificate and builds the End Entity's certificate with the data described above. In this case the End Entity's certificate is built directly on top of the CA certificate because it contains many of the same fields. This changes the parsed version of the CA certificate only, but does not affect either the encoded CA certificate, or the original CA certificate from the disk. 3. Finally, it logs on to the key media and retrieves a handle to the CA's private key for signing the End Entity's certificate. It calls the X.509

5-114


5

Toolkit function C_X509_EncodeSign to encode and sign the certificate. The certificate is placed in a certs_and_crls structure which is used as a parameter for C_PKCS7_CreateCRP: rc = C_PKCS7_CreateCRP(crpFormat,&CertsAndCrls, encodedCrp,&encodedCrpLen);

♦ crpFormat – same format as the certificate request. ♦ CertsAndCrls – a structure that includes the newly created End Entity certificate. ♦ encodedCrp – buffer for the encoded certificate reply. ♦ encodedCrpLen – the size of the encodedCrp buffer. The certificate reply is saved into a file that can be sent to the End Entity.

5-115

5


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(

Parameters

5-116

CK_SESSION_HANDLE

hSession,

char *

pfxfile,

char *

password,

char

errmsg[128]);

5


♦ hSession [in] – handle to a cryptographic session with the token into which the keys and certificate will be imported to. The user must be already logged on. ♦ pfxfile [in] – the name of the PKCS#12 file with the keys and certificates to be imported.. ♦ password [in] – password of the PKCS#12 file. ♦ errMsg [out] – buffer to which a message will be copied upon completion of the function. Return codes


CKR_GENERAL_ERROR – open or read file operation failed

CKR_MECHANISM_INVALID – unsupported mechanism is needed to import the file.

ExportPKCS12 This function exports a private key and certificate from the token into a standard PKCS#12 file. The private key must be extractable. Syntax CK_RV ExportPKCS12( CK_SESSION_HANDLE

hSession,

CK_OBJECT_HANDLE

hPrivKey,

char *

outfile,

char *

password,

CK_MECHANISM_TYPE

mech,

char

errmsg[128]);

Parameters

5-117

5


♦ 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

5-118

CKR_OK – function was completed successfully

CKR_GENERAL_ERROR – open or write file operation failed

Chapter 6: SmartAdaptor Utilities This chapter describes the utilities available with SmartAdaptor to manage tokens: format, change PIN, view contents, import and export keys and certificates, prepare for use with other applications and more.

AR Genie Utility The AR Genie utility application enables the user to perform routine operations on tokens. The operations include password maintenance, token formatting, default setting, token standardization and more. The utility has two modes of operation: ♦ User mode, in which only a limited set of operations, is available. This is the default mode of operation and it was designed specifically for the simple user who needs to perform only basic token operations such as changing the token password. This mode displays only the available slots i.e. slots where the token is inserted. ♦ Administrator mode, in which an extended set of operations, can be performed on the tokens. In this mode all slots installed are displayed. The user can see the list of objects on each slot and view their contents. To run in this mode enter the following command: argenie /br

6-1

6


User Mode Token Operations Following is a description of the different menu options and their uses.

Change Password Use this option to change the user password (PIN) that protects the token. The password should be changed periodically. In order to change the password, you must present the current password. Note: The initial password of AR tokens is "12345678" .It is recommended that you change it before using the token.

Login This option is used to login into the token. It can be used with the Single Sign On (SSO) mechanism to set the password for a specific token. Then it is possible to run an application that does not have any user interface but still be

6-2

SmartAdaptor Utilities

6

able to access the private keys that are stored on that token. Selection of this option opens the PIN entry dialog box.

Format Token Use this option to format the token and prepare it for work. This operation erases all objects stored on a token (keys, certificates and data objects) and should be performed only once. To format the token: 1. Select the token from the list. 2. Shut down any CryptoKit applications that may be running or using the token. 3. Click Action menu and then select Format. 4. In the PIN entry dialog box, enter the new token password (minimum 6, to maximum 54 alphanumeric characters) and confirm it. 5. Wait until the operation is finished. Now the token is initialized and ready for operation. Note: By initializing a token, you overwrite any information contained on the device. Therefore, special care must be taken before performing this option. Note: It is possible to hide this option by setting an entry in the registry. Please refer to explanation about GenieFormat parameter in Chapter 7.

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

6-3

6


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:

6-4


6

Viewing List of Slots In administrator mode all the slots that are installed are displayed. Non-inserted slots are insensitive.

Slot Information To view the slot information: 1. Select the desired slot. 2. Click Slot menu and then select Get Information.

6-5

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.

6-6


6

Unbind This option allows the user to unbind a dynamic software slot. This option is displayed in the menu only if CryptoKit was installed with software token feature. To unbind to a software token: 1. Select the software slot that was previously bound. 2. Click Slot menu and then select Unbind option. 3. The slot should appear as if the token was removed.

Token Menu The Token menu includes operations that can be performed on the available tokens, such as: Get Information, Change User and SO PIN, View Objects, Login, Standardize, Format, Change Label, Dump and Import Key. The options in the Token menu that are available only in administrator mode are:

Token Information To view the token information: 1. Select the slot where the token is inserted. 2. Click Token menu and then select Get Information.

6-7

6


The window displays the token information as returned by the PKCS#11 C_GetTokenInfo function. For specific explanation about the parameters displayed please refer to the PKCS#11 standard.

Change SO Password Use this option to change the SO password (PIN) that protects the token. In order to change the password, you must present the current password.

6-8


6

Note: The initial SO password of AR tokens is "11111111" and we recommend that you change it before using the token.

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

CryptoKit provides two additional methods to change the token label. ♦ Execute the Change Label command by running AR Genie utility from the command prompt. For more information refer to the next section. ♦ Call CryptoKit’s extension API function C_EXT_ChangeTokenLabel from your application. For more information refer to Chapter 3.

Dump Use this option to print the whole token contents into a text file:

6-9

6


1. Select the token you want to dump its contents. 2. Click Token menu and then select Dump. 3. Enter the name and location of the text file that will be created. 4. If you are logged in, the file will contain both public and private objects information. If you are not logged in, you will be asked whether you want to login or not. If you select not to login, the file will contain only the public objects information. Note: You can dump the contents of a specific object from the Objects window.

Import Key Use this option to import a PKCS#12 file (*.pfx, *.p12) into the token. These files are used to transfer private, public and certificate objects from one token to another. The PFX file may be protected by a password. To import a PFX file contents into the token do the following: 1. Select the token you want to import the PFX file to. 2. Click Token menu and then select Import Key. 3. Enter the name and location of a valid PKCS#12 file (*.pfx or *.p12) or click Browse button to search for the file to import. 4. Enter the password that protects the PFX file. You may leave the password empty if the PFX file is not protected by password. 5. Click OK to import the file. 6. If you are not logged in, you will be requested to enter the token PIN. 7. The file contents will be imported into the token. You can view the new objects in the Objects window. Note: You can import PFX files also by using the PKCS#12 import/export utility as explained later in this chapter.

6-10


6

View Objects Use this option to view the objects that are stored on the token: data objects, keys and certificates. Use the Login option to login into the token and to view the private objects as well. Press the title of the table to sort the objects by: Type, Label, Size, Private/Public or their ID. Double click an object to view its details. Right click an object or click Object in the menu to perform additional operations on the selected object.

6-11

6


View Object Attributes For each object type there is an additional window that presets its attributes. To view the object attributes: 1. Open the object list window. 2. Select the object you want to view from the list. 3. Click Object menu and then select View, right-click the object and select View from the pull down menu or simply double click the object.

6-12


6

The following window shows the details of RSA public key object. Please refer to the PKCS#11 standard for specific explanation about the meaning of the parameters displayed in this window.

6-13

6


When viewing a data object, you can see its contents in binary or hex format. You can copy the value of the object into the clipboard.

Similar windows are displayed also for private RSA keys and secret keys.

6-14


6

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

6-15

6


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

6-16


6

Refresh List This option will refresh the displayed list of objects.

Dump Object Use this option to print the object content into a text file: 1. Select the object you want to dump its contents. 2. Click Object menu and then select Dump or right-click the object and select Dump from the pull down menu. 3. Enter the name and location of the text file that will be created and then click Save button. 4. The object contents and attributes will be written into the file.

Export Object Use this option to export private and public RSA keys and their corresponding certificate into a PKCS#12 file (*.pfx). You must be logged in for this option to be available. The operation will fail if the RSA private key is not extractable. To export a PFX file do the following: 1. Select an RSA public or private key object that you want to export into a PFX file. 2. Click Object menu and then select Export or right-click the object and select Export from the pull down menu. 3. The Export Key File dialog will open. 4. Enter the name and location of the PFX file that will be created or click Browse button. 5. Enter the password that will protect the PFX file 6. From the Encryption Mechanism list, select the algorithm that will be used to encrypt the objects inside the PFX file: RC2 or 3DES.

6-17

6


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.

6-18

6


Running AR Genie From Command Line All operations that AR Genie provides are available from the command line, without any user interface. Note: The parameters are not case sensitive. Parameters in [ ] are optional. If a parameter is omitted a default value will be used or an appropriate dialog box will appear. The default slotId is 1. Following is a list of the commands and their parameters.

Usage Display the list of all available command line parameters. Syntax: ARgenie /?

User Mode Run AR Genie in user mode. Syntax: ARgenie

Administrator Mode Run AR Genie in administrator mode. Syntax: ARgenie /BR

Format Format the token and set the user PIN.

6-19

6


Syntax: ARgenie /cmd=Format [/slotId=XX] [/label="abc"] [/oldSOPin="abc"] [/newPin="abc"]

Parameters: slotId – The number of the slot to format. If omitted, the default is slot 1. label – The label of the token. If omitted, the label will be CryptoKit’s default. oldSOPin – The SO PIN, which is needed to format the token. If omitted, the default "11111111" is used. If the default PIN fails, the PIN entry dialog box will open, requesting the user to enter the SO PIN. newPin – The new user PIN. If omitted, the default is "12345678".

Change User PIN Change the user PIN. Syntax: ARgenie /cmd=ChangePIN [/slotId=XX] [/oldPin="abc"] [/newPin="abc"]

Parameters: slotId – The number of the slot you want to change the user PIN. If omitted, the default is slot 1. oldPin – The current user PIN. If omitted, then the user will be prompted to login and then to change the PIN. Two dialogs will be displayed: the first is the login dialog and then the change PIN dialog. newPin – The new user PIN. If omitted, and oldPin is also omitted then the user will be prompted to login and then to change the PIN. If omitted and oldPin is not empty, the operation will fail.

Change SO PIN Change the SO PIN. Syntax: ARgenie /cmd=ChangePIN [/slotId=XX] [/oldSOPin="abc"] [/newSOPin="abc"]

6-20


6

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.

6-21

6


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.

6-22

6


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.

6-23

6


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 ♦ -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 ♦ -e – export keys and certificates stored in a token into a PFX file. ♦ password – the password that will protect the PFX file.

6-24

6


♦ filename – the name of PFX file to be created. If not specified, the default output file name is out.pfx. ♦ id – the id of the key and certificate to export. The default is the first key found on the token. ♦ label – the label of the key and certificate to export. The default is the first key found on the token. ♦ slot – the slot number of the token. The default is the first slot with token inserted. ♦ 3des – the algorithm that will be used to encrypt the objects inside the PFX file. The default is RC2. If this parameter is specified, 3DES is used.

6-25

6


DlmLoad Utility The DlmLoad.exe utility program is a command line utility that can be used to load DLMs into the PrivateSafe reader. A DLM is a special program that is loaded into the reader and provides additional functionality. CryptoKit installs this utility when the PrivateSafe reader feature is selected. After the driver is installed the user has to reboot the machine and then the DlmLoad utility is automatically executed to install the latest DLM into the PrivateSafe reader. When this utility is loading a DLM into the reader, the user keyboard is disabled because the PrivateSafe is connected to the keyboard. The utility can also be used to view which version of DLM is loaded and it can erase the loaded DLM. The command line parameters of this utility are:

Usage Display the list of all available command line parameters. Syntax: Dlmload /?

Status Display the PrivateSafe version and DLM version. Syntax: Dlmload

Description: Running the utility without any parameter will display a message box:

6-26


6

The PrivateSafe version may be 2.5 or 2.6.

Load DLM Load a DLM file into the PrivateSafe reader. You can specify up to three DLM files. Only DLMs that match the PrivateSafe reader you have will be loaded. Syntax: Dlmload DlmFile1 [DlmFile2] [DlmFile3] [/Replace] [/Silent]

Parameters: DlmFile1 – The name of the DLM file you want to load DlmFile2 – Optional additional DLM file to load DlmFile3 – Optional additional DLM file to load Replace – By default the utility will replace an existing DLM only if the new one has a higher version number. Use this flag if you want to suppress the version check and force DLM load. Silent – Use this parameter to disable any dialog box during the execution of this utility.

Kill DLM Delete the existing DLM from the PrivateSafe reader. Syntax: Dlmload /Kill

Note: Some applications will not function correctly if no DLM is loaded in the PrivateSafe reader. Use this option with care.

6-27

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

Installation Packages CryptoKit installation package is an InstallShield based setup program. The installation program is using the high capabilities of InstallShield scripting language as well as Microsoft’s installer technology (MSI), which is part of Windows operating system. There are two types of installation packages: ♦ Extended – includes all CryptoKit components and SDK files. ♦ Runtime – includes all components except the SDK.

7-1

7


Installation From CD To install CryptoKit, simply insert the installation CD. CryptoKit has an AUTORUN option, which runs the setup automatically. If this option is disabled on the user’s computer, run the setup program (setup.exe) from the root directory of the installation CD. Important Note: In order to be able to install CryptoKit, you must have administrator rights.

Installing On a Clean Machine In the Welcome screen, click the Next button.

7-2

Installation

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

7-3

7


In the Destination directory screen, enter the installation directory and then click the Next button. You can change the default folder by entering a different directory name in the Destination Folder edit box or by clicking the Browse button and selecting an existing directory.

7-4

Installation

7 In the Features tree screen, select the features you want to install, and then click the Next button.

In the confirmation screen, click Yes button to start the CryptoKit installation.

7-5

7


When the installation is complete, the Finish screen will appear. Click the Finish button to exit the installation program and if requested, reboot the machine.

The CryptoKit installation requires reboot only in cases when it is needed for example, when installing hardware drivers that need reboot to operate or when the installation needs to replace a file, which is currently locked. If no reboot is required, the Finish screen will allow you to exit the installation program and immediately start working with CryptoKit. Note: When the Netscape plug-in is selected, the setup program runs the Netscape Navigator with an installation applet.

7-6

7

Installation

Modifying or Removing an Existing Installation It is possible to add or remove any CryptoKit component from an existing installation by running the setup program again. You can either: • • •

Enter the control panel, Add/remove programs and select CryptoKit Select Add Remove CryptoKit components from the CryptoKit Menu. Insert the CryptoKit installation CD and wait for the installation to start.

In any case, the following window is displayed:

7-7

7


Select the Modify option to add or remove components. Select Repair to reinstall again the currently selected components. Select Remove to uninstall CryptoKit. Note: I f you do not want to allow users to modify or repair the installation, you can hide this window by setting the parameter showMaint to FALSE. In this case, the user will be prompted to confirm uninstalling CryptoKit. For more information, please refer to explanation how to customize the installation, later in this chapter.

Upgrading an Existing Installation The CryptoKit installation is designed to automatically upgrade from older versions. When you run the setup program on a computer with an older version of CryptoKit installed, an automatic upgrade is performed and all the currently installed features are upgraded. Press Yes to confirm CryptoKit upgrade.

Note: Due to changes in the installation program, this feature is supported only when upgrading from version 3.5.x. When upgrading from older versions, such as 3.2 and 3.4, you must first uninstall the old version.

7-8

7

Installation

In the Welcome screen, click the Next button to upgrade existing installed features to the newer version of CryptoKit.

Silent Installation CryptoKit can be installed in unattended and silent mode. This means that no user interaction is needed and no indication of the progress of installation is displayed. This feature is supported by the InstallShield program, which is used to install CryptoKit.

7-9

7


In order to create a silent installation you need to perform the following steps: •

On a test system, run the installation in record mode, which generates a response file.

•

On an end user's system, run the installation in silent mode, using the data in the response file in place of user input.

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

7-10

7

Installation

Centralized Installation from Active Directory CryptoKit installation package is an InstallShield based setup program. Since the installation is very complex it uses the high capabilities of InstallShield scripting language. Even though the package contains an MSI file, this file cannot be assigned to install the software through active directory group policy mechanism, as you would assign a basic MSI package. However, it is possible to install CryptoKit by assigning a startup script to a group policy object. The startup script is executed when a machine that belongs to the group policy object is rebooted. The script is run with administrator privileges. To use group policies to centrally install CryptoKit, you need to perform three steps: 1. Create CryptoKit installation package on the server 2. Create the startup script 3. Assign the startup script Following is a detailed explanation of each step:

Step 1 – Create CryptoKit Installation Package on the Server The first step will be to create a silent CryptoKit installation with the features you want to install in your network: ♦ Copy the CryptoKit installation package files to a clean machine. ♦ Modify the CK_SETUP.INI file and customize the installation according to your needs. Modify the [ComponentSelect] section to select or deselect the CryptoKit features you want to install. Modify the [General] section to disable the user dialogs by setting to FALSE the parameters: ShowWelcome, ShowDestPath and ShowTree.

7-11

7


♦ Prepare an InstallShield response file for silent installation (as explained in previous section), by entering the command. setup /r /f1"c:\install.iss" ♦ Now, create a new directory on the server and share it. Grant this directory with read access permissions to all domain users. ♦ Copy the CryptoKit installation package files and the InstallShield response file to the shared directory.

Step 2 – Create the Startup Script The following VBscript sample copies the installation files from the server into a temporary directory on the client machine. Then it runs a silent installation. The script file has to be saved with .vbs extension. Note: You need to change the variable strSourceDir to the name of the shared directory, where the CryptoKit setup files are located. '=============================================================== ' Script Name: CryptoKit.vbs ' ' Install CryptoKit from active directory or Microsoft SMS server '=============================================================== '--------------------------------------------------------------' Variables declaration '--------------------------------------------------------------Dim objFileSystem, objShell, objProvEnv Dim strTmpDir, strRegistry, strSourceDir, strDestDir '--------------------------------------------------------------' !!! Change strSourceDir to the name of a shared directory !!! ' !!! where the CryptoKit setup files are located !!! '--------------------------------------------------------------strSourceDir = "\\Server_Name\Share_Name" '--------------------------------------------------------------' Initialize Variables '---------------------------------------------------------------

7-12

7

Installation

On Error Resume Next Set objShell = CreateObject("Wscript.Shell") Set objFileSystem = CreateObject("Scripting.FileSystemObject") Set objProvEnv = objShell.Environment("Process") '--------------------------------------------------------------' Read from registry and quit if CryptoKit is already installed '--------------------------------------------------------------strRegistry = objShell.RegRead("HKLM\Software\ARL\SmartAdaptor\Main\CkitDir") If Err.number = vbEmpty and strRegistry <> "" then Wscript.Quit End If '--------------------------------------------------------------' Find TEMP directory on local computer '--------------------------------------------------------------strTmpDir = objProvEnv("TEMP") If strTmpDir <> "" And objFileSystem.FolderExists(strTmpDir)Then strDestDir = strTmpDir Else strDestDir = "C:\Temp" End If If Right(strDestDir, 1) <> "\" then strDestDir = strDestDir & "\" End If strDestDir = strDestDir & "CryptoKit" '--------------------------------------------------------------' Copy installation files to local computer and run silent setup '--------------------------------------------------------------objFileSystem.CopyFolder strSourceDir, strDestDir, True objShell.run strDestDir & "\setup.exe /s /f1""" & strdestDir & "\install.iss""", 1, True WSCript.Quit

The script can be used not only to install CryptoKit on a clean machine, but it can be easily changed to handle CryptoKit upgrade. The CryptoKit installation

7-13

7


program automatically handles upgrade from an older version so you need to record an appropriate response file for upgrade situation. The script can check in the registry which version of CryptoKit is installed and then run the installation with the upgrade response file. The script runs with administrator privileges and is executed as if the administrator visited the client machine, logged in and then launched the setup locally. If a specific station needs additional CryptoKit components, the administrator can easily run the setup locally from the control panel and modify the installation.

Step 3 – Assign the Startup Script The final step is to assign the startup script to a group of computers in the domain: ♦ From a Windows 2000-based computer in the domain, log on as a domain administrator, and start the Active Directory Users and Computers snap-in. ♦ Click the container you want to have the Group Policy Object (GPO) linked to. Right-click that container, click Properties, and then click the Group Policy tab.

7-14

7

Installation

♦ Create a new GPO for installing the CryptoKit package, and give it a descriptive name. ♦ While the GPO is selected, click Edit to start the Group Policy snap-in and edit this GPO.

7-15

7


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

♦ Change the parameter Run startup scripts asynchronously to Enable.

7-16

7

Installation

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

7-17

7


♦ 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\\Policies\\ MACHINE\scripts\Startup The contents of this folder are automatically replicated to all domain controllers in the domain. 7-18

7

Installation

♦ Using Windows Explorer copy into this folder the startup VBscript script that was created in the previous step.

♦ Close the folder window and return to the Logon Properties screen and click Add button to open the Add a Script dialog box.

♦ In the Script Name field, type the name of the startup script file you want to assign and press OK. ♦ In the Logon Properties dialog press the Apply button or press OK button twice to assign the new startup script. 7-19

7


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

Centralized Installation Using Microsoft SMS 2003 Server It is possible to install CryptoKit from Microsoft SMS 2003 Server. The steps are very similar to installation from active directory. However, the assignment to groups of computers has to be done in a different way. To use Microsoft SMS 2003 Server to centrally install CryptoKit, you need to perform three steps: 1. Create CryptoKit installation package on the server 2. Create the startup script 3. Assign CryptoKit package to SMS collection The first two steps are exactly the same as when centrally installing CryptoKit using active directory group policies mechanism. Please refer to the previous section for a detailed explanation. The third step however, has to be done from the SMS Management console.

Step 3 – Assign CryptoKit Package to SMS Collection The following section assumes that you have an SMS 2003 server working in your network environment and that you have some minimal knowledge in using this software. It assumes that you are familiar with the basic concepts of SMS server such as collections, packages, advertisements etc. This section shows only the minimal operations you have to do in order to install CryptoKit using SMS 2003 server. You may need to modify other SMS parameters according to your needs, for example: creating collections or changing the schedule of the installation and more.

7-20

7

Installation

For more information about using SMS 2003 server, please refer to Microsoft’s documentation and manuals. To install CryptoKit, run the SMS Management console and perform the following operations: ♦ Right click Packages and select New | Package

♦ In the Package Properties dialog, enter package Name, Version and Publisher. Press the Apply button to create the package. ♦ Expand the new package to view its Access Accounts, Distribution Points and Programs. ♦ Right click the Distribution Points and select New | Distribution Points.

7-21

7


♦ In the New Distribution Points Wizard, select the checkbox next to the distribution point and click Finish.

♦ Right click Programs and select New | Program. ♦ In the General tab of the Program Properties dialog, enter "CryptoKit" in the name of program. In the Command line enter the path to VBscript that installs CryptoKit which should be in the shared directory with all other installation files: wscript \\Server\Share\Cryptokit.vbs

7-22

Installation

7

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

7-23

7


♦ Right click Advertisments, and select New | Advertisment.

♦ In the General tab of the Advertisement Properties dialog, enter the Name of the advertisement, in the Package select the newly created package, in the Program select the newly created program and in the

7-24

7

Installation

Collection click Browse and select a collection of computers you want to install to.

♦ For testing purposes click the button in the Schedule tab, and assign the advertisement As soon as possible and click Apply. ♦ The advertisement should now be active and will begin pushing the CryptoKit package to the systems in the collection. You can view the advertisement status in the System Status, Advertisement Status screen. 7-25

7


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

Citrix Server Configuration Perform the following on a Windows 2000 or Windows 2003 server running Citrix MetaFrame XP Server or Citrix Presentation Server 3: ♦ Login as administrator and copy the CryptoKit installation package from the CD to the server. ♦ If you want to use a standard PC/SC reader then install the drivers of the reader on the server. ♦ If you want to use Algorithmic Research MiniKey5 then you need to install only one virtual driver. Edit the SETUP.INI file in the CryptoKit installation package and change the setup command line to: CmdLine=ZZN_READER="1"

7-26

7

Installation

♦ Open Control Panel, Add Remove Software and click the Install Software from CD button. ♦ Run Setup.exe from the CryptoKit installation package. ♦ The CryptoKit installation program should automatically detect it is being installed on a Citrix server and display the Citrix feature in the features tree screen. Select the features: Citrix, CAPI, Logon and optionally the MiniKey5. Note: The terminal Server feature is automatically selected when the Citrix feature is selected. ♦ Complete the installation and then reboot the server. ♦ Load the root CA certificate into the local machine store of the server. ♦ Use the Citrix SCCONFIG.EXE utility to register any additional applications that run on the server and need access the smart card on the client's computer. The utility has to be run from the command line. For example, to register Microsoft Internet Explorer enter the command: SCCONFIG /ENABLE_PROCESS:iexplore.exe /FARM To view the list of registered applications, enter the command: SCCONFIG /QUERY The CryptoKit installation automatically registers: Arcltsrv.exe, Ardaemon.exe, Argenie.exe and the utility program PHL.exe. ♦ If you use the Citrix Web client or want to work with other CAPI applications then you would need to register: iexplore.exe, rundll32.exe and explorer.exe. For more information about the SCCONFIG.EXE utility, please refer to the Citrix documentation. Note: You can use smart card to logon to the Citrix server. However, you should not lock the machine if the smart card is removed. Defining this policy will

7-27

7


cause clients that are connected to the server to be disconnected when the user removes his smart card.

Citrix Client Configuration The Citrix client machine can be configured with or without local smart card logon. In each case you may want to work with a standard PC/SC reader or with MiniKey5 USB token. For each one of these cases there is a slightly different installation procedure. Perform the following on a Citrix client machine: ♦ If you want to use a standard PC/SC reader then connect it to the client machine and install the drivers of the reader. ♦ If you want to use Algorithmic Research MiniKey5 then you need to install only one virtual driver. Edit the SETUP.INI file in the CryptoKit installation package and change the setup command line to: CmdLine=ZZN_READER="1" Note: If you install more than one MiniKey5 device then the Citrix client will fail to initialize and you will get an error message: "ICA Client Error 1043: Invalid Parameter" immediately after it is opened. ♦ If you want the client to perform smart card logon locally then you need to install CryptoKit and select CAPI and Logon features in the features tree screen. If you want to use MiniKey5 for smart card logon, then you need to install also the MiniKey5 drivers by selecting this feature too. ♦ If you want to use MiniKey5 without smart card logon on the client machine, then you need to install only the MiniKey5 drivers. Install CryptoKit and select only MiinKey5 feature in the features tree screen.

7-28

7

Installation

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

7-29

7


♦ In the Logon Information, select Smart Card and click OK.

♦ Open the ICA client and then insert the smart card with appropriate public, private and certificate. Enter the PIN and login to the Citrix server.

7-30

7

Installation

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

Terminal Server Configuration Perform the following on a Windows 2003 server or Windows XP with terminal services installed and enabled: ♦ Login as administrator and copy the CryptoKit installation package from the CD to the server. ♦ If you want to use a standard PC/SC reader then install the drivers of the reader on the server. ♦ Open Control Panel, Add Remove Software and click the Install Software from CD button. ♦ Run Setup.exe from the CryptoKit installation package.

7-31

7


♦ The CryptoKit installation program should automatically detect it is being installed on a terminal server machine and display the Terminal Services feature in the features tree screen. Select the features: CAPI, Terminal Services and Logon. If you want to use Algorithmic Research MiniKey5 then select the MiniKey5 feature too. ♦ Complete the installation and then reboot the server. ♦ Load the root CA certificate into the local machine store of the server.

Client Configuration The client machine connects to the server using Microsoft’s Remote Desktop Connection application. This application is part of the Windows XP operating system. On windows 2000 machines, it has to be separately installed. The client machine can be configured with or without local smart card logon. In each case you may want to work with a standard PC/SC reader or with MiniKey5 USB token. For each one of these cases there is a slightly different installation procedure. Perform the following on the client machine: ♦ If you want to use a standard PC/SC reader then connect it to the client machine and install the drivers of the reader.

7-32

7

Installation

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

Use AR PrivateCard and a standard PC/SC reader

No smart card logon is required to client machine

Smart card logon to client machine also is required

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

Install CryptoKit with: CAPI and Logon features selected.

If the client is running Windows XP, no installation is required. Use AR MiniKey5 USB Install CryptoKit with token 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.

7-33

7


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

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

7-34

7

Installation

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

Description

Setup.exe

Main setup program that activates the CryptoKit installation

instmsia.exe

Microsoft installer program for Windows 98 and ME. This file is automatically installed by setup.exe, if msiexec.exe file is too old or missing.

instmsiw.exe

Microsoft installer program for Windows NT, 2000 and XP. This file is automatically installed by setup.exe, if msiexec.exe file is too old or missing. Note: The default version on Windows 2000 and XP platforms is sufficient enough.

CK_SETUP.INI

CryptoKit customization file. Read how to customize the setup using this file, later in this chapter.

CK_LANG.INI

A file that contains all the text that is displayed during the setup process. This text can be translated to different languages. Read how to customize the setup text using this file, later in this chapter.

Setup.ini

InstallShield INI file

Autorun.inf

This file runs the installation program automatically when the CD is inserted

License.txt

CryptoKit license agreement file

7-35

7


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

7-36

0x0409.ini

InstallShield internal file

Setup.bmp

Image that is displayed in the background when the installation is run from CD

*.cab

Cab files that contain the files of the different CryptoKit features. Each feature is contained in a different Cab file

7

Installation

Customizing the Installation The CryptoKit installation program is very flexible and can be customized according to the organization needs. It is possible to externally set different parameters by modifying configuration files, which are part of the installation. It is possible to customize the user interface by: ♦ Changing the language of the messages and dialog boxes. ♦ Selecting which dialog boxes will be presented to the user during installation. ♦ Changing the images of the dialog boxes. ♦ Defining which features will be displayed in the features tree. It is also possible to customize the logic of the installation by: ♦ Selecting which components will be selected and installed. ♦ Setting different default parameters. ♦ Adding files and registry entries to the installation. ♦ Executing external applications at the end of the installation or after reboot. The CK_SETUP.INI file, which is included in the CryptoKit installation has several sections, each controls a different aspect of the installation.

7-37

7


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

Description

or

The full path of the directory where CryptoKit is installed

The full path of the Windows directory

The full path of the Windows System directory

The location of the setup program

The disk on which CryptoKit is installed

The disk with the Windows directory

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.

7-38

Feature Name

Description

Readers_And_Tokens

CryptoKit’s core PKCS#11 provider

Readers_And_Tokens\Minikey

MiniKey4 USB token

Readers_And_Tokens\Minikey5 Readers_And_Tokens\PrivateSafe

Visible Selected

(1)

MiniKey5 USB token

PrivateSafe reader

7

Installation

Feature Name

Description

Visible Selected

Readers_And_Tokens\PrivateSafe_ PrivateSafe PCMCIA reader PCMCIA

Readers_And_Tokens\Software

Software token

Readers_And_Tokens\Siemens

Siemens USB token

Plugins\CAPI

AR CAPI provider

Plugins\SSO

Single Sign On

Plugins\Netscape

Netscape plugin

(2)

Plugins\IPSEC

Microsoft IPSEC support

(3)

Plugins\Entrust

Entrust plugin

(2)

Plugins\Logon

Smart Card logon

(3)

Plugins\Terminal_Services

Terminal Services support

(4)

Plugins\Logical_Channels

Smart card logical channels 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

(5)

SDK

SDK files and sample programs for developers

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

7-39

7


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:

7-40

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

7

Installation

ShowWelcome = FALSE

ShowWelcome

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

ShowDestPath

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

ShowTree

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

ShowMaint

ShowMaint = FALSE 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.

WelcomeLogo

WelcomeLogo = Change the image at the left of welcome.bmp 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.

ShowTree = FALSE

7-41

7

7-42


TitleLogo

Change the small image at the top TitleLogo = small.bmp 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.

FinishLogo

FinishLogo = Change the image at the left of the Finish dialog. The image has finish.bmp to be of type bmp, width 176 and height of 300 pixels. It should be included in the installation files. The path to the new image has to be relative to the installation directory.

ForceReboot

ForceReboot = 1 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.

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

7

Installation

StoreMode

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

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

ShowProgramMenu = FALSE

UseMsReaders

UseMsReaders = TRUE

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

Note: It is also possible to replace the image that appears when the installation is loaded by replacing the file setup.bmp with a new image.

[AutoSettings] The AutoSettings section allows setting default values for the following parameters: Key

Description

Example

Destination Path Change the default target directory Destination Path = \Compa to install CryptoKit. ny Name\Project Software Path

Change the path of software token directory. The default is: \sft_tok

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

Software Path = \softwar e MaxRSAPrivate = 10

7-43

7


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

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

Example Readers_And_Tokens\M inikey = TRUE

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

Description

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

Example Readers_And_Tokens\M inikey = 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.

7-44

7

Installation

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.

\hello.txt = \hello.t xt

[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

\importme.re List of additional registry files to import to the target machine at the g = end of CryptoKit setup. The key name holds the registry file name. The value is ignored. You can use string constants from the list above.

7-45

7


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

"\ShowHT ML.exe" = "\main.h tm"

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

7-46

Key

Description

Example

LANG

Three letters indicating the setup’s language.

LANG = ENG

7

Installation

CK_LANG.INI The CK_LANG.INI provides the setup program all the text that appears during installation. The name of each section in that file is the name of the language. Each section should contain parameters with text for all installation dialogs.

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

7-47

7


Changing the Setup Language Welcome Dialog (1) Msg_Welcome1 (2) Msg_Welcome2 (3) Msg_Welcome3 (4) Msg_Welcome4 (5) Msg_Welcome5 (6) Msg_Back, Msg_Next, Msg_Cancel

License Dialog (1) Msg_License1 (2) Msg_License2 (3) Msg_License3 (4) Msg_License4 (5) Msg_License5 (6) Msg_Back, Msg_Next, Msg_Cancel

7-48

7

Installation

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

7-49

7


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

7-50

7

Installation

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

7-51

7


Maintenance Dialog (1) Msg_Maint1 (2) Msg_Maint2 (3) Msg_Maint3 (4) Msg_Maint4 (5) Msg_Maint5 (6) Msg_Maint6 (7) Msg_Maint7 (8) Msg_Maint8 (9) Msg_Maint9 (10) Msg_Back, Msg_Next, Msg_Cancel Upgrade Dialog (1) Msg_Upgrade1 (2) Msg_Upgrade2 (3) Msg_Upgrade3 (4) Msg_Back, Msg_Next, Msg_Cancel

7-52

7

Installation

Select Language Dialog (1) Msg_Language1 (2) Msg_Language2 (3) Msg_Language3 (4) Msg_Language4 (5) Msg_Back, Msg_Next, Msg_Cancel

Abort Dialog (1) Msg_Abort1 (2) Msg_Abort2 Confirm Uninstalling (1) Msg_ConfirmUninst1 (2) Msg_ConfirmUninst2

7-53

7


Additional Messages (1) Msg_AD_AlreadyInstalled (2) Msg_AD_Only (3) Msg_Minikey4_5Problem (4) Msg_InsertMinikey (5) Msg_EnterDisk (6) Msg_UnsupportedOS (7) Msg_UserNotAdministrator (8) Msg_OldCkitBlock (9) Msg_FileCopyError (10) Msg_Downgrade

7-54

7

Installation

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:

The target directory that was selected by the user

\Installation

Temporary directory for files needed by the installation

Windows directory

Windows system directory

Program files directory

The All Users directory on Windows 2000, Windows XP and Windows 2003. The value of environment variable with the same name.

7-55

7


SmartAdaptor The SmartAdaptor component is always installed. It includes the basic CryptoKit files.

Files OS

File Name

Target

Description

All

Sadaptor.dll

SmartAdaptor

All

Cypkcs11.Dll Obj_Ids.Dll

Crypto Provider for software and hardware tokens of Algorithmic Research

All

Ckx50932.dll

X.509 support dll

All

Argui.dll Argenie.dll

User interface support dlls

All

Ckpkcs12.dll

PKCS#12 support dll

All

Ar_jpk11.dll

Java client support dll (JNI)

All

Anonymous.sft

Read only software token for CryptoKit internal use. This file MUST have read permissions to all users.

All

Killproc.exe

\Installation

Utility programs needed for the installation

Registry The SmartAdaptor registry entries include general parameters and the basic entries of AR Core provider and AR Smart Card provider. The SmartAdaptor parameters are placed in the subfolder:

7-56

7

Installation

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

StartPlace

String

Path to currently used sadaptor.dll file Default: "\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: "\CKit.log"

LogLevel

DWORD

Controls the how detailed the log file would be. Each level includes all other less detailed levels: 0 – Errors only 1 – In/Out function parameters 2 – Information 3 – Most detailed Information Default: dword:00000003

7-57

7


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:

7-58

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.

7

Installation

UseMsReaders

DWORD

Instruct SmartAdaptor to add into the list of slots, PC/SC readers that exist in the registry but not physically connected. In the event of connecting such a reader, it is recognized immediately and the current applications can access it without reboot. 0 – List of slots will include only connected PC/SC readers 1 – List of slots will include both connected and registered PC/SC readers. Default: This entry does not exist. The list of PC/SC readers will not be read from registry and will include only the connected readers.

ParallelSlots

DWORD

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

7-59

7


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:

7-60

Key name

Key Type

Description

LogFileName

String

Log file name of additional SmartAdaptor components Default: "\comp.log"

LogLevel

DWORD


7

Installation

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


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

7-61

7


Key name

Key Type

Description

Module

String

Path and name of the PKCS11 DLL of the provider Default: "\cypkcs11.dll"

Entry

String

Name of the Entry function Default: "SoftwareProviderEntry"

LogFileName

String

Log file name of the provider Default: "\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


The contents of the Info subfolder:

7-62

7

Installation

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

7-63

7

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


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

7

Installation

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


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



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: "\cypkcs11.dll"

Entry

String

Name of the Entry function Default: "SmartcardProviderEntry"

LogFileName

String

Log file name of the provider Default: "\sc_pkcs11.log"

LogLevel

DWORD

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

The contents of the Info subfolder:

7-65

7


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:

7-66

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

7

Installation

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

7-67

7


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


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


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


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:

7-68

7

Installation

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


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:

7-69

7


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


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

7-70

7

Installation

OS

File Name

Target

Description

All

Arcltsrv.exe

\utils

The service is run for each terminal session. It operates in a machine context

All

Ardaemon.exe

\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

"\Utils\arcltsrv.exe"

ZZZARDAEMON

String

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

\Utils\Arcltsrv.exe /T=installer

7-71

7


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


ServiceLockDelay

DWORD

Number of seconds, after which the station will be locked, if the smart card that was used to login has been removed. Default: This entry does not exist to allow normal behavior of Windows smart card removal action.

ARCSP The CSP is one of the adapters supported by CryptoKit (see Chapter 4). Algorithmic Research’s CSP includes an RSA cryptographic provider for all operating systems and an additional SChannel provider for Windows 2003.

Files

7-72

7

Installation

OS

File Name

Target

Description

All

Arcsp.dll Arstore.dll

CSP dll, signed by Microsoft

All

Arcsp.sig

\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: "\csp.log"

LogLevel

DWORD


LogGroup

DWORD

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

7-73

7


The keys in the Parameters subfolder are:

7-74

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

7

Installation

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:

7-75

7


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

7-76

7

Installation

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


Flags

DWORD

dword:00000001

OpenEncodingType DWORD

dword:00065537

OpenFlags

DWORD

dword:00000000

OpenParameters

Binary

User GUID information

OpenStoreProvider String

ArPhysicalOpen

Priority

dword:00000002

DWORD

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


Flags

DWORD

dword:00000001

OpenEncodingType DWORD

dword:00065537

7-77

7


OpenFlags

DWORD

dword:00000000

OpenParameters

Binary

"ArComp" Default: hex:61,72,43,6F,6D,70,00

OpenStoreProvider String

ArPhysicalOpen

Priority

dword:00000002

DWORD

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


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

\sft_tok

Empty software token file. This file must have read permissions to all users.

Registry

7-78

7

Installation

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

Single Sign On dll

Registry The following registry entry is required to activate the SSO mechanism: HKEY_LOCAL_MACHINE\Software\ARL\SmartAdaptor\Main\ Parameters

7-79

7


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

7-80

Key Type

Description

UnAttendedSlotsList MultiString

List of slot names for which the PIN should be taken from the corresponding UnAttendedPin list

UnAttendedPin

List of PINs that corresponds to the unattended slot list

MultiString

7

Installation

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

\Installation

Installation files for 98 and ME

NT

\Installation

Installation files for NT

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

Installation files for 2K and XP

All

CSAFE32.dll CSDRV32.exe

PrivateSafe drivers

All

DLMLOAD.exe FIX252B.dlm FIX262B.dlm

\Installation

DLM loader DLM file for PrivateSafe v2.5 DLM file for PrivateSafe v2.6

INSTN4SH.exe PSAFENT4.sys

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

7-81

7


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


InterfaceDeviceType DWORD

7-82

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

7

Installation

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:

Description

CryptoKit 1.63

CryptoKit Versions 3.2 – 3.5.X

From Version 3.6.0

Works directly with keyboard controller

Uses Windows 2000 keyboard hook mechanism

Replaces the standard Microsoft keyboard driver

7-83

7


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

All

euci5.cat

\Installati Signature of driver on\Crypto5

All

euci5in.dll

\Installati File which installs the on\Crypto5 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

\Installati Driver files on\Crypto5

Registry

7-84

Description

7

Installation

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

All

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

All

PinManager.exe

Description

\Utils

Registry The PKCS#11 core provider is registered in: HKEY_LOCAL_MACHINE\Software\ARL\SmartAdaptor\ PKCS#11_PROVIDERS\Provider_x

7-85

7


Key name

Key Type

Description

Module

String

Path and name of the PKCS11 DLL of the provider Default: "\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

7-86

7

Installation

OS

File Name

Target

Description

All

eTCoreReg.dll

Registration dll which installs and uninstalls the driver

98, ME aksup.inf aksifdh.inf

\Inf

98, ME aksifdh.sys aksup.sys

\Drivers

NT

\Drivers

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

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

\Setup\Al This is a temporary directory. addin\eToken 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

7-87

7


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:

7-88

7

Installation

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


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

\utils

AR Genie utility program

All

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

\utils\htm AR Genie help files

All

Pkcs12util.exe

\utils

PKCS#12 sample utility program

All

PHL.exe

\utils

PKCS#11 sample utility program

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

7-89

7


HKEY_LOCAL_MACHINE\Software\ARL\SmartAdaptor\ Components\Parameters

7-90

Key name


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

7

Installation

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


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

\include

Developer include files

\lib

Developer libraries

7-91

7


\doc

CryptoKit documents

\javaCKit AR Java and JCA adapters (CAB, JAR, configuration and documentation) \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

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:

7-92

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

7

Installation

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 \Start Menu\Programs\CryptoKit NT

\Profiles\All Users\Start Menu\Programs\CryptoKit

2K, XP \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}

7-93

7


And HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\ CurrentVersion\Uninstall\CryptoKit

Files Temporary InstallShield files are placed in the hidden folder:

7-94

OS

Folder Name

All

\InstallShield Installation Information\{EE04660285F3-4B87-A734-148C17748848}

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

I 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

I-2


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

I

Index

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

I-3

I 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

I-4


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

Index

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

I 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

I-5

I X509_ext_2927,X509_ext_DeltaCRLIndicator , 5-67 X509_ext_2928,X509_ext_IssuingDistribution Point, 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

I-6


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

CryptoKit Developers Guide

Recommend Documents