eToken Software Developer`s Guide

Transcription

eToken Software Developer’s
Guide
July 2005
i
Contact Information
Support
If you have any questions regarding this package, its
documentation and content or how to obtain a valid software
license you may contact your local reseller or Aladdin's technical
support team:
Country / Region
Telephone
USA
1-212-329-6658
1-800-223-4277
EUROPE:
Austria, Belgium, France,
Germany, Netherlands,
Spain, Switzerland, UK
00800-22523346
Ireland
0011800-22523346
Rest of the World
+972-3-6362266 ext 2
If you want to write to the eToken Technical Support department,
please go to the following web page:
http://www.Aladdin.com/forms/eToken_question/form.asp
Website
http://www.Aladdin.com/eToken
ii
COPYRIGHTS AND TRADEMARKS
The eToken
system and its documentation are copyrighted © 1985 to present, by
Aladdin Knowledge Systems Ltd.
™
All rights reserved.
eToken is a trademark and ALADDIN KNOWLEDGE SYSTEMS LTD is a registered trademark of
Aladdin Knowledge Systems Ltd.
™
All other trademarks, brands, and product names used in this guide are trademarks of their
respective owners.
This manual and the information contained herein are confidential and proprietary to Aladdin
Knowledge Systems Ltd. (hereinafter “Aladdin”). All intellectual property rights (including,
without limitation, copyrights, trade secrets, trademarks, etc.) evidenced by or embodied in
and/or attached/connected/related to this manual, information contained herein and the
Product, are and shall be owned solely by Aladdin. Aladdin does not convey to you an interest
in or to this manual, information contained herein and the Product, but only a limited right of
use. Any unauthorized use, disclosure or reproduction is a violation of the licenses and/or
Aladdin's proprietary rights and will be prosecuted to the full extent of the Law.
DISCLAIMER
NEITHER ALADDIN NOR ANY OF ITS WORLDWIDE SUBSIDIARIES AND DISTRIBUTORS SHALL
BE OBLIGATED IN ANY MANNER IN RESPECT OF BODILY INJURY AND/OR PROPERTY DAMAGE
ARISING FROM THIS PRODUCT OR THE USE THEREOF. EXCEPT AS STATED IN THE ETOKEN
END USER LICENSE AGREEMENT, THERE ARE NO OTHER WARRANTIES, EXPRESSED OR
IMPLIED, REGARDING ALADDIN'S PRODUCTS, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. The product
must be used and maintained in strict compliance with instructions and safety precautions
contained herein, in all supplements hereto and according to all terms of its End User License
Agreement. This product must not be modified or changed without the written permission of the
copyright holder.
All attempts have been made to make the information in this document complete and accurate.
Aladdin is not responsible for any direct or indirect damages or loss of business resulting from
inaccuracies or omissions. The specifications in this document are subject to change without
notice.
iii
ALADDIN KNOWLEDGE SYSTEMS LTD.
DEVELOPER'S LICENSE AGREEMENT
IMPORTANT INFORMATION - PLEASE READ THIS AGREEMENT CAREFULLY BEFORE OPENING
THE PACKAGE AND/OR USING THE CONTENTS THEREOF AND/OR BEFORE DOWNLOADING OR
INSTALLING THE SOFTWARE PROGRAM. ALL ORDERS FOR AND USE OF THE ETOKEN
PRODUCTS (including without limitation, the Developer’s Kit, libraries, utilities, diskettes,
CD-ROM, eToken® keys and the Developer’s Guides) (hereinafter “Product”) SUPPLIED BY
ALADDIN KNOWLEDGE SYSTEMS LTD. (or any of its affiliates - either of them referred to as
“ALADDIN”) ARE AND SHALL BE, SUBJECT TO THE TERMS AND CONDITIONS SET FORTH IN
THIS AGREEMENT. BY OPENING THE PACKAGE CONTAINING THE PRODUCTS AND/OR BY
DOWNLOADING THE SOFTWARE (as defined hereunder) AND/OR BY INSTALLING THE
SOFTWARE ON YOUR COMPUTER AND/OR BY USING THE PRODUCT, YOU ARE ACCEPTING THIS
AGREEMENT AND AGREEING TO BE BOUND BY ITS TERMS AND CONDITIONS.
IF YOU DO NOT AGREE TO THIS AGREEMENT DO NOT OPEN THE PACKAGE AND/OR
DOWNLOAD AND/OR INSTALL THE SOFTWARE AND PROMPTLY (at least within 7 days from the
date you received this package) RETURN THE PRODUCTS TO ALADDIN, ERASE THE SOFTWARE,
AND ANY PART THEREOF, FROM YOUR COMPUTER AND DO NOT USE IT IN ANY MANNER
WHATSOEVER.
1. Title & Ownership
THIS IS A LICENSE AGREEMENT AND NOT AN AGREEMENT FOR SALE. The software component
of Aladdin’s eToken Software Development Kit, including any revisions, corrections,
modifications, enhancements, updates and/or upgrades thereto, (hereinafter in whole or any
part thereof defined as: "Software"), and the related documentation, ARE NOT FOR SALE and
are and shall remain in Aladdin’s sole property. All intellectual property rights (including,
without limitation, copyrights, trade secrets, trademarks, etc.) evidenced by or embodied in
and/or attached/connected/related to the Product, are and shall be owned solely by Aladdin.
This License Agreement does not convey to you an interest in or to the Software, but only a
limited right of use revocable in accordance with the terms of this License Agreement. Nothing
in this Agreement constitutes a waiver of Aladdin’s intellectual property rights under any law.
2. License
Subject to payment of applicable license fees, Aladdin hereby grants to you, and you accept, a
personal, nonexclusive and fully revocable limited License to use the Software, in executable
form only, as described in the Software accompanying user documentation and only according
to the terms of this Agreement:
2.1 You may install the Software and use it on computers located in your place of business, as
described in Aladdin’s related documentation.
2.2 You may merge and link the Software into your computer programs for the sole purpose
described in the Developer’s Guide; however, any portion of the Software merged into
another computer program shall be deemed as derivative work and will continue to be
subject to the terms of this Agreement. The Software shall not be used for any other
purposes.
3. Sub-Licensing
After merging the Software in your computer program(s) according to section 2, you may sublicense, pursuant to the terms of this Agreement, the merged Software and resell the hardware
components of the eToken® keys which you purchased from Aladdin, to distributors and/or
users. Preceding such a sale and sub-licensing, you shall incorporate by reference in your
contracts with such distributors and/or users, and otherwise provide for all distributors and/or
users to be bound by, the warranties, disclaimers, and license terms specified by Aladdin in this
Agreement.
iv
4. Prohibited Uses
Except as specifically permitted in Sections 1, 2 and 3 above, you agree not to:
4.1 Use, modify, merge or sub-license the Software or any other of Aladdin’s Products, except
as expressly authorized in this Agreement and in the Developer’s Guide.
4.2 Sell, license (or sub-license), lease, assign, transfer, pledge, or share your rights under this
License with/to anyone else.
4.3 Modify, disassemble, decompile, reverse engineer, revise or enhance the Software or
attempt to discover the Software’s source code.
4.4 Place the Software onto a server so that it is accessible via a public network.
4.5 Use any back-up or archival copies of the Software (or allow someone else to use such
copies) for any purpose other that to replace an original copy if it is destroyed or becomes
defective. If you are a member of the European Union, this agreement does not affect your
rights under any legislation implementing the EC Council Directive on the Legal Protection
of Computer Programs. If you seek any information within the meaning of that Directive
you should initially approach Aladdin.
5. Limited Warranty
Aladdin warrants, for your benefit alone, that:
5.1 The Software, when and as delivered to you, and for a period of three (3) months after the
date of delivery to you, will perform in substantial compliance with the Developer’s Guide,
provided that it is used on the computer hardware and with the operating system for which
it was designed.
5.2 The eToken® key, for a period of twelve (12) months after the date of delivery to you, will
be substantially free from significant defects in materials and workmanship.
6. Warranty Disclaimer
ALADDIN DOES NOT WARRANT THAT ANY OF ITS PRODUCT(S) WILL MEET YOUR
REQUIREMENTS OR THAT ITS OPERATION WILL BE UNINTERRUPTED OR ERROR-FREE. TO THE
EXTENT ALLOWED BY LAW, ALADDIN EXPRESSLY DISCLAIMS ALL EXPRESS WARRANTIES NOT
STATED HERE AND ALL IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. NO
ALADDIN’S DEALER, DISTRIBUTOR, RESELLER, AGENT OR EMPLOYEE IS AUTHORIZED TO
MAKE ANY MODIFICATIONS, EXTENSIONS, OR ADDITIONS TO THIS WARRANTY. If any
modifications are made to the Software or to any other part of the Product by you during the
warranty period; if the media and the eToken® key is subjected to accident, abuse, or
improper use; or if you violate any of the terms of this Agreement, then the warranty in Section
5 above, shall immediately be terminated. The warranty shall not apply if the Software is used
on or in conjunction with hardware or program other than the unmodified version of hardware
and program with which the Software was designed to be used as described in the Developer’s
Guide.
7. Limitation of Remedies
In the event of a breach of the warranty set forth above, Aladdin's sole obligation shall be, at
Aladdin's sole discretion:
7.1 To replace or repair the Product, or component thereof, that does not meet the foregoing
limited warranty, free of charge.
7.2 To refund the price paid by you for the Product, or component thereof. Any replacement or
repaired component will be warranted for the remainder of the original warranty period or
30 days, whichever is longer. Warranty claims must be made in writing during the warranty
period and within seven (7) days of the observation of the defect accompanied by evidence
satisfactory to Aladdin. All Products should be returned to the distributor from which they
were purchased (if not purchased directly from Aladdin) and shall be shipped by the
returning party with freight and insurance paid. The Product or component thereof must be
returned with a copy of your receipt.
v
8. Exclusion of Consequential Damages
The parties acknowledge that Product is inherently complex and may not be completely free of
errors. ALADDIN SHALL NOT BE LIABLE (WHETHER UNDER CONTRACT, TORT (INCLUDING
NEGLIGENCE) OR OTHERWISE) TO YOU, OR ANY THIRD PARTY FOR ANY LOSS OR DAMAGE
(INCLUDING INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES), INCLUDING, WITHOUT
LIMITATION, ANY LOSS OR DAMAGE TO BUSINESS EARNINGS, LOST PROFITS OR GOODWILL
AND LOST OR DAMAGED DATA OR DOCUMENTATION, SUFFERED BY ANY PERSON, ARISING
FROM AND/OR RELATED WITH AND/OR CONNECTED TO ANY USE OF THE SOFTWARE AND/OR
ANY COMPONENT OF THE PRODUCT, EVEN IF ALADDIN IS ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES.
9. Limitation of Liability
IN THE EVENT THAT, NOTWITHSTANDING THE TERMS OF THIS AGREEMENT, ALADDIN IS
FOUND LIABLE FOR DAMAGES BASED ON ANY DEFECT OR NONCONFORMITY OF ITS
PRODUCT(S), ITS TOTAL LIABILITY FOR EACH DEFECTIVE PRODUCT SHALL NOT EXCEED THE
PRICE PAID TO ALADDIN FOR SUCH DEFECTIVE PRODUCT.
10. Termination
Your failure to comply with the terms of this Agreement shall terminate your license and this
Agreement. Upon termination of this License Agreement by Aladdin:
10.1 The License granted to you in this Agreement shall expire and you, upon termination, shall
discontinue all further use of the Software and other licensed Product(s);
10.2 You shall promptly return to Aladdin all tangible property representing Aladdin’s intellectual
property rights and all copies thereof and/or shall erase/delete any such information held
by it in electronic form. Sections 1, 4, 6, 7, 8, 9, 10 and 11 shall survive any termination
of this Agreement.
11. Governing Law & Jurisdiction
This Agreement shall be construed and governed in accordance with the laws of Israel (except
for conflict of law provisions) and only the courts in Israel shall have jurisdiction in any conflict
or dispute arising out of this Agreement. The application of the United Nations Convention of
Contracts for the International Sale of Goods is expressly excluded. The failure of either party
to enforce any rights granted hereunder or to take action against the other party in the event of
any breach hereunder shall not be deemed a waiver by that party as to subsequent
enforcement of rights or subsequent actions in the event of future breaches.
12. Government Regulation and Export Control
You agree that the Product will not be shipped, transferred, or exported into any country or
used in any manner prohibited by applicable law. It is stipulated that the Product is subject to
certain export control laws, rules, and/or regulations, including, without limiting the foregoing,
to the United States and/or Israeli export control laws, rules, and/or regulations. You undertake
to comply in all respects with the export and reexport restriction as set forth herein and any
update made thereto from time to time.
13. Third Party Software
If the Product contains any software provided by third parties, such third party’s software is
provided “As Is” without any warranty of any kind and Sections 2, 3, 4, 6, 8, 9-12 of this
Agreement shall apply to all such third party software providers and third party software as if
they were Aladdin and the Product respectively.
14. Miscellaneous
This Agreement represents the complete agreement concerning this License and may be
amended only by a written agreement executed by both parties. If any provision of this
Agreement is held to be unenforceable, such provision shall be reformed only to the extent
necessary to make it enforceable.
I HAVE READ AND UNDERSTOOD THIS LICENSE AGREEMENT AND AGREE TO BE BOUND BY ALL
OF THE TERMS.
vi
FCC Compliance
eToken USB has been tested and found to comply with the limits for a Class B digital device,
pursuant to Part 15 of the FCC rules. These limits are designed to provide reasonable protection
against harmful interference in a residential installation.
This equipment generates, uses and can radiate radio frequency energy and, if not installed and
used in accordance with the instructions, may cause harmful interference to radio
communications. However, there is no guarantee that interference will not occur in a particular
installation.
If this equipment does cause harmful interference to radio or television reception, which can be
determined by turning the equipment off and on, the user is encouraged to try to correct the
interference by one of the following measures:
a.Reorient or relocate the receiving antenna.
b.Increase the separation between the equipment and receiver.
c. Connect the equipment to an outlet on a circuit different from that to which the receiver is
connected.
d.Consult the dealer or an experienced radio/TV technician.
FCC Warning
Modifications not expressly approved by the manufacturer could void the user authority to
operate the equipment under FCC rules.
All of the above applies also to the eToken USB.
FCC authorities have determined that the rest of the eToken product line does not contain a
Class B Computing Device Peripheral and therefore does not require FCC regulation.
CE Compliance
The eToken product line complies with the CE EMC Directive and related
standards*. eToken products are marked with the CE logo and an eToken CE
conformity card is included in every shipment or upon demand.
*EMC directive 89/336/EEC and related standards EN 55022, EN 50082-1.
UL Certification
The eToken product line successfully completed UL 94 Tests for Flammability of Plastic Materials
for Parts in Devices and Appliances. eToken products comply with UL 1950 Safety of
Information Technology Equipment regulations.
ISO 9002 Certification
The eToken product line is designed and manufactured by Aladdin Knowledge
Systems, an ISO 9002-certified company. Aladdin's quality assurance system is
approved by the International Organization for Standardization (ISO), ensuring
that Aladdin products and customer service standards consistently meet
specifications in order to provide outstanding customer satisfaction.
Certificate of Compliance
Upon request, Aladdin Knowledge Systems will supply a Certificate of Compliance to any
software developer who wishes to demonstrate that the eToken product line conforms to the
specifications stated. Software developers can distribute this certificate to the end user along
with their programs.
vii
Table of Contents
Introduction ................................................................................... 1
What is eToken...........................................................................................................2
The eToken RTE......................................................................................................3
eToken SDK.............................................................................................................4
Who should read this Guide ....................................................................................4
Structure of this Guide ..............................................................................................5
What’s New in eToken SDK? ....................................................................................6
Developing Applications with the eToken SDK 3.60 ................. 7
eToken SDK ................................................................................................................8
eToken SDK for Windows Architecture ...................................................................9
Using the SDK .......................................................................................................11
eToken Software Developer’s Kit ..........................................................................12
Programming for eToken ........................................................................................15
Choosing the Correct API ......................................................................................15
Obsolete APIs ........................................................................................................17
Redistribution .........................................................................................................17
Dealing with Non-Standard Features.....................................................................18
A Note on Cryptography ........................................................................................19
Developing in non-C/C++ Environments ...............................................................21
Calling External Functions .....................................................................................21
Using Sun’s PKCS#11 Provider in Java................................................................22
Writing Wrapper Objects........................................................................................22
Additional Cryptography Information Sources.....................................................23
eToken SDK Reference............................................................... 25
eToken Models .........................................................................................................26
RSA Private Keys ..................................................................................................27
Password presentation ..........................................................................................28
PKCS#11 ...................................................................................................................29
PKCS#11 Implementation for eToken RTE 3.60...................................................29
CAPI...........................................................................................................................37
viii
CAPI vs. CertStore................................................................................................ 38
eToken Provider.................................................................................................... 39
Working with Multiple eTokens ............................................................................. 40
Explicitly Passing the Reader Name..................................................................... 41
Performing login/logout ......................................................................................... 42
Default and Auxiliary Key Containers ................................................................... 42
Suppressing Standard Behavior of eToken CSP.................................................. 44
CAPI Limitations.................................................................................................... 45
CAPI & PKCS#11 Interoperability .......................................................................... 46
Using PKCS#11 Objects from CAPI ..................................................................... 46
Using CAPI Objects from PKCS#11 ..................................................................... 46
eToken Supplementary API........................................................ 48
Compatibility with eToken RTE Versions ............................................................. 50
Overview of SAPI Functionality ............................................................................. 51
OTP Functionality.................................................................................................. 51
Battery Indication Functionality ............................................................................. 53
Miscellaneous Functionality .................................................................................. 55
Common Principles................................................................................................. 56
Data Types ............................................................................................................... 58
Error Codes.............................................................................................................. 61
New Object Classes ................................................................................................ 62
Slot Object............................................................................................................. 62
Token Object......................................................................................................... 63
OTP Object ........................................................................................................... 71
Battery Feature Object .......................................................................................... 73
Common Functionality ........................................................................................... 76
SAPI_GetLibraryInfo ............................................................................................. 76
Slot/Token Functionality ........................................................................................ 77
SAPI_GetSlotInfo .................................................................................................. 77
SAPI_GetTokenInfo .............................................................................................. 78
SAPI_SetTokenName ........................................................................................... 78
SAPI_InitToken ..................................................................................................... 79
SAPI_FindTokens ................................................................................................. 80
ix
SAPI_LocateToken ................................................................................................81
SAPI_UnblockPIN..................................................................................................81
OTP Functionality ....................................................................................................83
SAPI_OTP_GetMechanismList .............................................................................83
SAPI_OTP_GetMechanismInfo .............................................................................84
SAPI_OTP_Create.................................................................................................85
SAPI_OTP_GetAttributeValue...............................................................................86
SAPI_OTP_SetAttributeValue ...............................................................................86
SAPI_OTP_Destroy...............................................................................................87
SAPI_OTP_Execute ..............................................................................................87
Battery Indication Functionality .............................................................................89
SAPI_BI_Create.....................................................................................................89
SAPI_BI_GetAttributeValue...................................................................................90
SAPI_BI_SetAttributeValue ...................................................................................91
SAPI_BI_Destroy ...................................................................................................92
SAPI_BI_Recalibrate .............................................................................................92
SAPI_BI_Save .......................................................................................................93
SAPI_BI_Restore...................................................................................................93
SAPI_BI_GetConfig ...............................................................................................94
SAPI_BI_Check .....................................................................................................96
Server Side Functionality........................................................................................97
SAPI_Server_OTP_Calculate................................................................................97
SAPI_Server_BI_EstimateValue ...........................................................................98
SAPI_Server_BI_EstimateRetainDays ..................................................................99
SAPI_Server_Unblock .........................................................................................102
eToken Samples ........................................................................ 103
Overview .................................................................................................................104
Seal/Unseal Samples ..........................................................................................104
PKCS#11 Samples .................................................................................................107
Info Sample..........................................................................................................107
InitToken Sample .................................................................................................108
Seal/Unseal Sample ............................................................................................109
CAPI Samples.........................................................................................................111
x
CreateSelfCertificate Sample.............................................................................. 111
EnumTokens Sample.......................................................................................... 112
Seal/Unseal Sample............................................................................................ 113
ImportPFX Sample.............................................................................................. 114
SAPI Samples ........................................................................................................ 115
TokenInfo Sample ............................................................................................... 115
InitToken Sample ................................................................................................ 115
InitOTP Sample................................................................................................... 115
Battery Estimation Sample.................................................................................. 116
FixBattery Sample............................................................................................... 117
Samples for non-C/C++ Developers .................................................................... 118
Using CAPI from .NET ........................................................................................ 118
Using PKCS#11 from .NET................................................................................. 119
Java Seal/Unseal Sample................................................................................... 119
Other COM Samples ............................................................................................. 120
TokenList COM Object Sample .......................................................................... 120
eTCapiCom VB Sample ...................................................................................... 122
UseCapiFunc VB Sample ................................................................................... 122
VBScript/JScript Sample ..................................................................................... 122
WebDemo Sample .............................................................................................. 123
eToken Explorer ........................................................................ 125
Overview ................................................................................................................ 126
The eToken Explorer Main Window..................................................................... 127
The Tokens and Objects Window ....................................................................... 130
The Details Window ............................................................................................ 131
Modifying Attributes............................................................................................. 132
Managing PKCS#11 Objects ................................................................................ 134
eToken Explorer Other Functions ....................................................................... 140
Appendix .................................................................................... 143
eToken SDK Installation ....................................................................................... 144
xi
List of Tables
Figure 2-1: eToken SDK for Windows Architecture ....................................... 9
Table 2-1: eToken SDK 3.60 Contents........................................................ 13
Figure 2-2: Files Installed by eToken SDK 3.60 .......................................... 14
Table 3-1: RSA Private Keys Specifications................................................ 27
Table 3-2: Object Types Supported by eToken ........................................... 31
Table 3-3: Supported Mechanisms.............................................................. 32
Table 4-1: General PKCS#11 Error Codes.................................................. 61
Table 4-2: SAPI Specific Error Codes ......................................................... 61
Table 6-1: Exported File Types.................................................................. 136
Introduction
CHAPTER 1
Chapter 1
Introduction
About This Chapter
This Developer’s Guide introduces Aladdin’s eToken Software
Developer’s Kit (SDK) for Windows version 3.60. It is intended
primarily for use by developers and project managers, and
explains in detail how to use the SDK for developing applications
that customize (or integrate) the use of eToken for specific
organization or client requirements.
This introductory chapter includes the following sections:
♦ What is eToken, page 2, describes what an eToken is and
what it is used for.
♦ Structure of this Guide, page 5, shows where to find the
information you need in this Software Developer’s Guide.
♦ What’s New in eToken SDK?, page 6, details the new
additions to the SDK.
1
2
eToken Software Developer's Guide
CHAPTER 1
What is eToken
eToken is a powerful and secure hardware device that enhances
the security of data on public and private networks. The size of a
normal house key, eToken enables generation and secure
storage of passwords and digital certificates, strong
authentication, digital signing and encryption, and more.
eToken can be used to hold secret information, certificates and
private keys for use in authentication solutions for LANs, WANs,
VPNs, e-commerce and mobile computing.
A single eToken can store a number of private keys, certificates
and passwords concurrently, for use in a wide variety of
applications.
eToken can also generate keys and perform sensitive encryption
operations on-chip, ensuring that users’ keys are never exposed
to the PC environment.
eToken provides strong authentication and password
management solutions that offer:
♦ Enhanced security and ensured safe information access
Introduction
CHAPTER 1
♦ Cost-effective password management
♦ The ability to carry your personal digital credentials with you,
wherever you go
eToken is an easy to use and highly portable USB-based
smartcard device. It enables both users and IT/security
administrators to more effectively manage the authentication
process by securely storing passwords, PKI keys and digital
certificates and other personal credentials onboard the eToken.
The eToken RTE
The eToken Run Time Environment (RTE) installs all the
necessary files and eToken drivers to support eToken integration
with various security applications. It enables Windows operating
systems and third party applications to access the eToken.
Installing the RTE allows communication with all available eToken
devices and forms the basis for Aladdin’s various security
solutions. These include eToken PKI solutions using either
PKCS#11 or CAPI, proprietary eToken applications such as WSO
(Web Sign ON), SSO (Simple Sign ON), eToken for Network
Logon and management solutions like eToken TMS – a Token
Management System that is a complete framework for managing
all aspects of token assignment, deployment and personalization
within an organization.
Aladdin’s eToken PKI Solutions enable the implementation of
strong two-factor authentication using standard certificates.
Generic integration with both Microsoft CAPI and PKCS#11
security interfaces enables interoperability with a variety of
security application such As Web Access, VPN Access, Network
Logon, PC Protection and Secure eMail. PKI keys and certificates
can be securely created, stored and used from within the eToken.
When used with eToken PRO / Smartcard or eToken NG-OTP
the PKI Private keys can be generated and operated on board
the secure chip.
3
4
CHAPTER 1
eToken RTE supports the various types of eToken devices in
both form factors. This means that only a single RTE installation
is required to enable operations of either a traditional Smartcard
or a USB Token (PRO/ NG-OTP or R2), and results in easy
deployment and cost effective installation in use of eToken
products and solutions.
eToken RTE can be deployed and updated using any standard
software distribution system such as SMS. In addition, the
eToken Management System (TMS) supports software
distribution using the Microsoft GPO system.
eToken SDK
The eToken SDK is a set of industry standard APIs and
supporting documentation that enables seamless integration with
third party applications. The eToken SDK uses standard security
interfaces in all its elements and supports the entire suite of
eToken devices and form factors.
In addition, the entire eToken suite of security applications can be
integrated into any third party solution developed with the SDK.
Its main features are:
♦ SDK based on PKCS#11 interfaces
♦ Support for all eToken devices, including CardOS 4.20 based
devices (eToken 64K and NG-OTP)
♦ Supports RSA 2048 bit keys
♦ Includes samples for C++, .NET, Java, and more
Who should read this Guide
This guide is primarily intended to be used by program
developers. It is expected that the user is familiar with MS
Windows programming.
Introduction
CHAPTER 1
Structure of this Guide
The structure of this Software Developer’s Guide is designed to
be easily understood and of immediate use to developers. The
information is organized i as follows:
♦ Chapter 2, “Developing Applications with the eToken SDK
3.60”, provides an overview of the SDK architecture and
explains the use of various programming interfaces.
♦ Chapter 3, “eToken SDK Reference”, Presents information on
the eToken models and how eToken works with the PKCS#11
and CAPI standards.”
♦ Chapter 4, “eToken Supplementary API”, explains the new
additional API introduced to enhance the functionality of
working outside the PKCS#11 standard with eToken.
♦ Chapter 5, ”eToken Samples”, describes the code samples
provided with the SDK, and demonstrates the usage of the
various APIs in each sample.
♦ Chapter 6, “eToken Explorer”, Details how to use this new tool
to manage PKCS#11 objects and work with them as stored
objects.
♦ Chapter 7, “eToken SDK Installation”, shows how to install the
SDK.
5
6
CHAPTER 1
What’s New in eToken SDK?
Previous eToken SDK versions concentrated on the low-level
aspects of eToken programming.
eToken development activity has migrated to using high-level
APIs. Consequently, the eToken SDK 3.60 orients developers to
use these high-level APIs.
As a result of this change, the eToken SDK 3.60:
♦ Provides more detailed documentation about eToken
programming using high-level APIs (CAPI and PKCS#11).
♦ Provides a new Supplementary API (SAPI).
♦ Provides a new application: eToken Explorer. This application
allows the creation, viewing, editing and deletion of PKCS#11
objects on the eToken.
♦ Provides many new samples.
Developing Applications with the eToken SDK 3.60
CHAPTER 2
Chapter 2
Developing Applications with the
eToken SDK 3.60
About This Chapter
This chapter describes the eToken SDK and provides necessary
information for developers. It contains the following sections:
♦ eToken SDK, on page 8
♦ Programming for eToken, on page 15
♦ Developing in non-C/C++ Environments on page 21
♦ Additional Cryptography Information, on page 23
7
8
CHAPTER 2
eToken SDK
The eToken SDK can be used with a variety of applications that
require secure user identification and authentication, as well as
digital signatures and encryption of private information. These
include:
♦ User identification and authentication to a PC or to a local area
network.
♦ Remote-access security clients
♦ Web authentication (i.e. for subscription services).
♦ E-banking.
♦ Digital signatures and document signing.
♦ Secure email for applications that utilize S/MIME, including
Microsoft Outlook/Outlook Express and Netscape Messenger.
♦ PC boot protection and laptop theft protection.
♦ File and desktop access control.
♦ Single sign-on reinforcement.
♦ Holder of personal credentials and information, including ewallet.
♦ Extranet and web access, including SSL and HTTP
♦ Virtual Private Network (VPN)
CHAPTER 2
eToken SDK for Windows Architecture
Knowledge of the full eToken RTE internal structure is not
relevant for the SDK and application developers. No attempt has
been made to provide this information within this guide.
What is relevant to the developer is how the applications being
developed see the eToken RTE so that the necessary interfaces /
communication requirements can be created. This information is
presented in Figure 2-1.
Figure 2-1: eToken SDK for Windows Architecture
Hardware Layer
The hardware layer comprises the tokens and smartcards. There
are two types of tokens in use, the eToken R2 and eToken
CardOS/M4. The eToken CardOS/M4 can be used in a variety of
ways. Currently it is available in the token form factor as an
eToken PRO or an eToken NG-OTP and is also available in a
Smartcard form factor. The hardware layer also includes
smartcard readers and smartcards.
9
10
CHAPTER 2
eToken Drivers
eToken Run Time Environment (RTE) installs all the necessary
files and eToken drivers to support eToken integration. The
eToken drivers create a USB pipe to the eToken device when it is
inserted, exposing the eToken to the Microsoft Smartcard
Resource Manager.
The Microsoft Smartcard Resource Manager manages the
access to readers and to smartcards. To manage these
resources, it performs the following three functions:
♦ Identifies and tracks resources
♦ Allocates readers and resources across multiple applications
♦ Supports transaction primitives for accessing services
available on a given card
The Microsoft Smartcard Resource Manager is operating system
specific, and is installed by default on Windows 2000 and
Windows XP and as part of the RTE installation on
Windows 98/Me/NT. For further details about the eToken RTE,
refer to the eToken RTE Guides.
The Microsoft Smartcard Resource Manager operates with
smartcard readers and cards. Therefore the eToken is
represented as such within the system:
♦ When the RTE is installed, one or more smartcard readers are
introduced to the system. The first reader is named “AKS ifdh
0”, the subsequent reader “AKS ifdh 1” and so on in
consecutive order. The number of readers can be changed via
the eToken Properties application (refer to the eToken User
Guide for details).
♦ When an eToken is inserted, it is recognized as a smartcard
inserted into the arbitrarily chosen and unoccupied reader.
CHAPTER 2
Using the SDK
The application developer requires the following elements when
installing the eToken SDK for Windows 3.60, developing and
testing applications and reviewing the sample source code.
Development Environment
♦ Microsoft Visual Studio 6.0 or Microsoft Visual Studio .NET
♦ MS Platform SDK November 2001 or later
♦ In addition, when working with particular samples, the following
tools may be needed:
• Microsoft Visual Basic
• Microsoft VB Script
• JScript
• Delphi 5
Hardware Supported
♦ UHCI Host Controllers.
♦ OHCI Host Controllers.
♦ EHCI Host Controllers (If working with Windows NT 4.0, the
eToken should be connected directly to the EHCI Host
Controller and not via a hub)
♦ eToken Models and Memory sizes:
• eToken NG-OTP – 32K, 64K
• eToken PRO – 16K, 32K, 64K
• eToken R2 – 16K, 32K
11
12
CHAPTER 2
eToken Software Developer’s Kit
The eToken Software Developer’s Kit (SDK) contains everything
you need to evaluate and start using eToken, and to develop your
own eToken applications.
eToken SDK 3.60 Prerequisites
Before you install the eToken SDK, ensure that you have the
following:
♦ PC with at least 10 Mb available disk space.
♦ Windows 2000, Windows XP, Windows 2000 Server or
Windows Server 2003.
♦ At least one USB port.
♦ At least one eToken security key (either eToken R2, eToken
PRO or eToken NG-OTP).
♦ USB extension cable. This cable is optional, and is included for
your convenience. It enables you to easily insert and remove
the eToken if the USB ports on your PC are not readily
accessible.
Default Password (PIN)
All eTokens are shipped from our factory with the default
password (PIN) 1234567890. You will need to input this default
password the first time you log on to the eToken and then change
it to secret and secure personal password of your own choosing.
CHAPTER 2
eToken SDK 3.60 Contents
Table 2-1 lists the components contained in the eToken SDK
3.60.
Table 2-1: eToken SDK 3.60 Contents
Component
Description
Redistribution
eTOTPlg.dll
Upgraded version of corresponding
module in RTE. It should be installed
if the application is to use SAPI
functionality.
eTSAPI.dll
Additional module providing SAPI
functionality.
Tools
eToken Explorer
eToken Explorer is a tool that works
with stored PKCS#11 data objects.
With it, these objects can be
generated, stored, and read from an
eToken (imported and exported).
Other
Samples
Revised set of samples covering
many APIs.
Documentation
This guide and other documentation
in electronic format (PDF).
What’s Included in the Kit?
The eToken SDK 3.60 includes the following items:
♦ eToken SDK software CD
♦ eToken Enterprise CD containing RTE software
♦ This eToken Software Developer’s Guide
♦ eToken RTE Overview Guide, User Guide,
and Administrator Guide
♦ Four eToken PRO tokens, each with 32 KB memory
♦ Four eToken shells
13
14
CHAPTER 2
♦ USB deluxe extension cable
♦ USB retractable extension cable
♦ USB flex connector
♦ Retractable belt clip
Installation Technology
The eToken SDK 3.60 uses a single MSI package to install the
entire SDK. The installation is a per-machine install.
The eToken SDK will show up in the Control Panel Add/Remove
Programs applet and requires administrative privileges to install.
The SDK 3.60 CD image contains an autorun executable that
installs:
♦ The MSI component (if not present).
♦ RTE 3.60 (rte_3.60.msi)
♦ SDK 3.60 (sdk_3.60.msi)
The eToken SDK 3.60 creates the following registry key:
HKEY_LOCAL_MACHINE\Software\Aladdin\eToken
Table 1.2 shows the files that are directly installed by the SDK.
Note that all files are installed in various locations under the
Windows directory.
Figure 2-2: Files Installed by eToken SDK 3.60
Component
Installed in Directory
RTE 3.60
Redistribution
files
%etokenfolder%\SDK\redistribution
Include files
%etokenfolder%\SDK\include
eToken Explorer
Samples
%etokenfolder%\SDK\Samples
PDF
documentation
%etokenfolder%\SDK\Doc
CHAPTER 2
Programming for eToken
Choosing the Correct API
Developers have two main options when deciding what
methodology to use when programming applications that will
utilize the eToken. The developer can choose to use either:
♦ PKCS#11
♦ CAPI
PKCS#11 is a Public-Key Cryptography Standard (Hence PKCS)
for public-key cryptography, developed by RSA Laboratories and
includes both algorithm-specific and algorithm-independent
implementation standards. It is an industry standard that defines
a technology-independent programming interface for
cryptographic devices such as smartcards and PCMCIA cards.
This standard specifies an application program interface (API),
called Cryptoki (short for CRYPTOgraphic Token Interface), to
devices, either physical or virtual which hold cryptographic
information (keys and other data) and perform cryptographic
functions.
This API is used across many platforms and is powerful enough
for most security-related applications. Aladdin considers
PKCS#11 as the main API for eToken programming.
CAPI (CryptoAPI) is an API developed by Microsoft as part of
Microsoft Windows. It is intended for use by developers of
applications for MS Windows platforms. CAPI allows multiple
cryptographic service providers (CSP) to coexist on the same
computer and to be used in the same application.
It is also possible to associate a CSP with a particular smartcard,
so that smartcard-enabled Windows applications will call the
proper CSP. MS Windows contains many helper functions that
application developers may use to simplify code when working
with cryptographic functions or with complicated data structures
(such as certificates).
15
16
CHAPTER 2
The choice of which API to use when developing applications is
up to the programmer and is dependent on that particular
application’s needs. Provided here are a number of tips to help
decide which API should be used:
♦ PKCS#11 allows for the management of multiple eTokens
easily. CAPI (as an API) has no concept of physical tokens. If
several eToken devices are to be connected to the same
computer, special techniques, described in Working with
Multiple eTokens on page 40 and Explicitly Passing the
Reader Name on page 41 should be used.
♦ PKCS#11 possesses an API (C_WaitForSlotEvent function)
that waits for token insertion/removal notifications. CAPI does
not have such an API (although this action can be performed
via a Win32 API).
♦ PKCS#11 allows both RSA keys, certificates and data objects
to be stored on the eToken itself while CAPI allows storing
only RSA keys and their corresponding certificates.
♦ PKCS#11 has no helper functions to work with certificates.
Parsing and the examination of X.509 certificate may be a
really complicated task. However if working in MS Windows, it
is possible to use many of the Win32 helper functions even
working with PKCS#11 (as shown in the samples).
♦ PKCS#11 is an API and not architecture. If an application
needs to work with multiple providers, the application itself
determines how to work (choose, manage, etc) with them.
CAPI is part of MS Windows and once a new provider is
installed (as is done during the eToken RTE installation), this
provider becomes automatically available for all applications.
♦ CAPI has multiple helper functions. These may allow the
application programmer to concentrate on application logic and
avoid the need to deal with low level details.
CHAPTER 2
Having discussed differences between PKCS#11 and CAPI, it
must be noted that all CAPI objects are visible using PKCS#11
functions as are PKCS#11 objects while using CAPI functions.
Nonetheless, there are certain restrictions on the interoperability
of the two APIs and it is strongly recommended that only one
API is used in an application. Developers should avoid using
both APIs in the same application.
Obsolete APIs
The eToken SDK 3.51 described several low-level APIs, such as:
♦ eToken API that provided low-level access to an eToken
♦ A partly documented APDU-level APDU that allowed sending a
separate APDU to the eToken
♦ eTOCX COM-API for low-level token functionality.
All low-level APIs are considered obsolete and are not
documented in eToken SDK 3.60.
eToken RTE 3.60 still supports these discontinued (deprecated)
APIs so legacy applications will continue to work. However there
is no guarantee that future RTE versions will continue to support
them and they may not work in the future.
Developers are kindly encouraged to migrate to high-level
APIs.
Redistribution
eToken SDK contains several modules for redistribution. If the
developer is using PKCS#11 or CAPI there is no need to
redistribute these modules. Only if SAPI is being used will it be
necessary to use the following DLLs.
eToken SDK 3.60 contains 2 DLLs:
♦ eTSAPI.DLL which provides SAPI functionality.
♦ eTOTPlg.DLL is an updated version of the corresponding
eToken RTE 3.60 module. Its functionality has been extended
to support SAPI.
17
18
CHAPTER 2
These two modules should be redistributed to the customer
machine. During installation eToken SDK 3.60 copies the
corresponding MSM-files to the target directory.
Note:
Several SAPI functions do not require the eToken RTE to be installed.
These are server-side functions that may be used by server
applications. If your application uses only these functions it is
sufficient to redistribute eTSAPI.DLL
Dealing with Non-Standard Features
It is possible that the developer may want to use an eToken
feature that is not covered by a corresponding API. This situation
may especially occur when working in CAPI as this API was not
designed to manage hardware tokens. For instance the
application may need to explicitly select a particular eToken or
need to choose which certificate is to be used for Smartcard
Logon.
Vendor-specific extensions are not part of the “standard”. They
are always subject to change and may vary between RTE
versions. This guide describes vendor-specific extensions as they
are implemented in the eToken RTE 3.60. Usually applications
are written so that they work correctly with future versions of the
RTE as well. The eToken development team will always do its
best to support these solutions, but there is always the possibility
that vendor-specific extensions may change in the future.
If a situation arises where certain programming needs cannot be
met by a standard API:
♦ Determine the real need of the application instead of
necessarily just following the previous solution. As an
example, perhaps knowing the exact eToken model in use is
not the real need, but rather whether or not it supports a
specific feature such as working with 2048 bit RSA keys.
CHAPTER 2
♦ Consider whether the missing feature is really important.
In many cases, a large amount of proprietary code needs to be
written to support a feature that has limited importance. For
example, it is not possible to obtain information about the
eToken color via a high level API (in eToken SDK 3.60).
However, the question that should be asked is if all eTokens
delivered in a single order are automatically of the same color,
then is this functionality worth developing a non-standard
solution?
♦ It is possible that there is an alternate but still standard,
way in which to obtain the required result. For example,
information about eToken insertion/removal events cannot be
obtained via CAPI. Instead, this can be achieved by using
other Win32 API functions and does not need a proprietary
solution. See CAPI Samples for more information.
♦ Supplemetary API may address your needs. It provides high
level access to various eToken capabilities such as OTP,
eToken initialization etc.
♦ If you really need to use eToken-specific features, try to
separate them from device-independent code. This way
your future changes (as result of changing the eToken RTE or
extending the existing standards) may require less work.
♦ If developers cannot find ways to fulfill their requirements
without special customized solutions, contact the eToken
technical support team for assistance.
A Note on Cryptography
Application developers use eToken for one or both of two main
purposes:
♦ adding strong cryptographic capabilities to the application
♦ as a secure data repository
Using eToken for secure data storage is simple and obvious, but
cryptography is a complicated subject and requires a few
comments.
19
20
CHAPTER 2
Cryptography itself is not too complicated to understand, but it
can be very complicated to use in the correct manner. There are
a number of good references to learn about cryptography (See
Additional Cryptography Information Sources on page 23) but the
first rule is “Do not reinvent the wheel! In most cases it will not
work correctly”
There are many good cryptographic algorithms available in the
world today, but they need to be used properly. Many of the real
world security attacks are the result of improper use of
cryptography rather than the use of weak algorithms. As in many
other situations, certain tasks need the correct algorithm to be
used and other tasks may require a different algorithm to be
used.
Wherever possible, try to remain with and use standard solutions!
Where something proprietary is really needed, obtain the
assistance of a cryptography specialist before developing the
application and ensure that the process being followed is
appropriate for the purpose.
CHAPTER 2
Developing in non-C/C++
Environments
Both CAPI and PKCS#11 are C-style APIs. It is easy to use them
from C/C++ programs. However there are many other
programming technologies available for MS Windows developers,
such as:
♦ .NET.
♦ Visual Basic.
♦ Java.
♦ Scripting languages used in Web-programming.
Several possible solutions may be proposed in such cases.
Calling External Functions
Many programming environments in MS Windows have
mechanisms for calling external functions that have a C-style
interface. The eToken SDK contains samples that demonstrate
how this can be done from C# using Platform Invocation Services
(PInvoke) and also from Visual Basic.
This mechanism is mainly recommended when using CAPI, since
PKCS#11 functions possess very complicated parameters (arrays
of structures that contain pointers).
Note:
Be extremely careful when defining functions since parameter
conversion is not trivial and may be very complicated to complete
correctly.
21
22
CHAPTER 2
Using Sun’s PKCS#11 Provider in Java
The Java platform defines a set of programming interfaces for
performing cryptographic operations. These interfaces are
collectively known as Java Cryptography Architecture (JCA) and
Java Cryptography Extension (JCE). For more information,
please refer to:
http://java.sun.com/j2se/1.5.0/docs/guide/security/index.html
The Sun PKCS#11 provider acts as a bridge between JCA and
JCE interfaces and the native PKCS#11 provider. eToken SDK
provides a sample that demonstrates how to work with eToken
from within Java (See Java Seal/Unseal Sample on page 119).
However working in this manner does not provide full access to
all the functionality of PKCS#11. For instance, it is only possible
to work with keys and certificates.
This functionality is supported since Java 2 Platform Standard
Edition 5 (J2SE 5.0).
Writing Wrapper Objects
The alternate solution (for either programming environment) is to
write a wrapper object that answers the particular needs of the
application. Depending on these needs, the wrapper object may
be a .NET assembly object, an ActiveX object or anything else.
eToken SDK provides samples of such objects. These samples
may either be used as is or they can be applied to the specific
need. However it must be remembered that these are only
samples and not part of the eToken API that is supported by
Aladdin.
CHAPTER 2
Additional Cryptography
Information Sources
There are a number of places where information on cryptography
can be found. To start this process, it is suggested that the reader
view some or all of the following for more information:
Books:
Applied Cryptography by Bruce Schneier
Applied Cryptography: Protocols, Algorithms, and Source Code in
C, Second Edition
by Bruce Scneier
Practical Cryptography
by Niels Ferguson, Bruce Schneier
Sources on the Web:
http://theory.lcs.mit.edu/~rivest/crypto-security.html
http://www.cryptovb.com/links/links.html
Microsoft sources:
http://msdn.microsoft.com/library/default.asp?url=/library/enus/seccrypto/security/cryptography_portal.asp
http://msdn.microsoft.com/library/default.asp?url=/library/enus/seccrypto/security/about_cryptography.asp
http://msdn.microsoft.com/library/default.asp?url=/library/enus/seccrypto/security/cryptography_reference.asp
http://msdn.microsoft.com/library/default.asp?url=/library/enus/seccrypto/security/using_cryptography.asp
23
24
CHAPTER 2
eToken SDK Reference
CHAPTER 3
Chapter 3
About This Chapter
This chapter contains the following sections:
♦ eToken Models on page 26,
♦ PKCS#11, on page 29,
♦ CAPI, on page 37,
♦ CAPI & PKCS#11 Interoperability, on page 46,
25
26
CHAPTER 3
eToken Models
There are a number of different eToken models available. Each
has specific functionality and the correct model should be
carefully chosen for the required purpose.
♦ eToken PRO (USB)
eToken PRO is a USB token for data security. It is a low-cost
readerless smartcard device that enables strong, two-factor
authentication and is easy to deploy. eToken PRO's secure,
on-board RSA 1024-bit and 2048-bit key operations enable
seamless integration into any PKI or other security
architectures.
eToken NG-OTP
eToken NG-OTP is a hybrid USB and One Time Password
(OTP) token, offering all of the functionality of eToken PRO
USB with the addition of OTP technology for strong
authentication in detached mode. eToken NG-OTP integrates
multiple strong authentication methods and enables a wide
variety of security related solutions, all in one device.
♦ eToken PRO (Smartcard)
eToken PRO Smartcard offers the same functionality as
eToken PRO USB, but with a traditional credit card form factor.
The eToken PRO Smartcard is operable with a standard
smartcard reader.
♦ eToken R2
eToken R2 is a USB token that is ideal for secure storage of
users’ private keys and access credentials featuring a secure
EEPROM chip.
CHAPTER 3
27
RSA Private Keys
The following table summarizes the specifications for working
with RSA private keys on eToken:
Table 3-1: RSA Private Keys Specifications
eToken
Type
Generated
RSA
May be
on-token Operation Exported
Min Max Default
on-token
R2
512
2048
1024
No
No
Yes
PRO 32K
384
1024
1024
Yes
Yes
No
512
PRO
(FIPScompliant)
1024
1024
No
Yes
No
384
2048
1024
Yes
Yes
No
PRO 64K,
NG-OTP
Length
NOTES:
♦ On the eToken, even if the RSA private key is still created as
a public object the application has to be logged in to perform
cryptographic operations with it.
♦ On the eToken PRO and eToken NG-OTP the RSA private key
is never extracted (exported) from the token. All private key
cryptographic operations are performed on the token itself.
Unlike the eToken PRO and NG-OTP, the eToken R2 keeps
RSA private keys as secure files. The key is actually generated
by the software and is read by the computer for the required
operation. Therefore, it is recommended that the eToken
PRO or eToken NG-OTP is used for PKI applications.
♦ In order to use 2048-bit RSA keys on an eToken PRO 64K or
eToken NG-OTP, you must enable support for 2048 bit keys
during token initialization.
♦ If the RSA key pair is generated on eToken PRO or eToken –
NG-OTP, there is no way the application itself can set the
public exponent.
28
CHAPTER 3
♦ If an eToken PRO is initialized to be FIPS-compliant, the RSA
keys will be generated by the software. Therefore it is
recommended to perform key generation on a secured
computer. After generation this key is stored on the eToken
and will never, in the future, leave the eToken. As a result the
eToken will be as secure as a non-FIPS eToken.
♦ Using 2048 bit RSA keys via CAPI requires that Microsoft
Strong Cryptographic Provider is installed.
Password presentation
Most applications, irrespective of the selected API need to give
the password to the eToken. Using non-ASCII characters in the
password may result in serious compatibility problems with other
applications. This is due to the fact that different applications
represent such a password differently. For instance:
♦ Windows Logon converts passwords according to the current
code page. All characters that cannot be represented in this
way are replaced with the ‘?’ character.
♦ Microsoft VPN provides the password in UTF-8 encoding.
♦ Some PKCS#11 applications just convert the password to
ASCII form so that national characters from different code
pages may receive the same encoding.
eToken RTE/SDK tools convert the password to the current code
page to keep compatibility with older eToken RTE/SDK versions.
In order to avoid compatibility problems it is recommended
that the password includes only printable ASCII characters.
CHAPTER 3
PKCS#11
This section contains information about eToken RTE
implementation of the PKCS#11 standard. For full specifications
on the PKCS#11 standard, please refer to:
http://www.rsasecurity.com/rsalabs/node.asp?id=2133
PKCS#11 Implementation for eToken RTE
3.60
eToken RTE 3.60 implements PKCS#11 v2.01.
Using eTpkcs11
eTpkcs11 is a dynamic link library (eTpkcs11.dll) with __stdcall
calling semantics that are installed in the system32 directory on
the computer by the RTE installation.
It is strongly recommended that you:
♦ Use only explicit dynamic linking when linking with eTpkcs11,
and use the full path to load the DLL in order to minimize load
times.
♦ Use the GetProcAddress() to obtain the address of
C_GetFuncList(). However to obtain the table of other function
pointers in the DLL you should use C_GetFuncList() and not
use GetProcAddress().
♦ eTpkcs11 maps a PKCS #11 Slot to any reader that is on the
system when the PKCS #11 library is first loaded. A token is
present in this slot whenever an eToken is inserted into that
reader.
29
30
CHAPTER 3
User Login Semantics
eToken without Administrator Password
PKCS #11 mandates two entities that can log on to a eToken: the
user and the security officer. Since the eToken R2 and eToken
CardOS/M4 (without an administrator) has a single legitimate
user that can be authenticated to the eToken, it was decided that
the eToken’s legitimate user is also the security officer for that
eToken.
Whenever an application wishes to log on to the eToken as the
security officer or to initialize the eToken, eTpkcs11 pops up a
dialog box informing the user that an application is attempting to
gain security officer rights to the eToken and requests the user
confirm by entering his/her eToken password.
eToken CardOS/M4 with Administrator Password
Commencing with RTE 3.51, eTpkcs11 uses the eToken
CardOS/M4’s administrator password whenever it exists (the
eToken CardOS/M4 was formatted with an administrator’s
password) and a security object is required.
eToken CardOS/M4 with Uninitialized Format Type
Commencing with RTE 3.51, eTpkcs11 can initialize an eToken
CardOS/M4 that does not have the AKS AID (0x6666). In this
particular case, eTpkcs11 builds the AKS AID with a default user
password and an administrator password, as set using
C_InitToken, C_InitPIN or C_SetPIN (after dummy C_Login as
security object).
See the InitToken Sample on page 108.
Note:
Commencing with RTE 3.51 the eTPKCS11 state is set to “Pin not
Initialize” before C_InitPin has been called. In RTE 3.00 the eTPKCS11
state is “Pin Initialize” regardless of the C_InitPin call.
CHAPTER 3
Object types
eToken supports a number of object types as detailed in Table
3-2
Table 3-2: Object Types Supported by eToken
Object
Type
PKCS#11 Object Attributes
Data object
CKA_CLASS=CKO_DATA
Certificate
CKA_CLASS=CKO_CERTIFICATE,
CKA_CERTIFICATE_TYPE=CKC_X_509
RSA
private key
CKA_CLASS=CKO_PRIVATE_KEY,
RSA public
key
CKA_CLASS=CKO_PUBLIC_KEY,
CKA_KEY_TYPE=CKK_RSA
CKA_KEY_TYPE=CKK_RSA
DES/Triple- CKA_CLASS=CKO_SECRET_KEY,
DES secret
CKA_KEY_TYPE=CKK_DES or
keys
CKK_DES2 or CKK_DES3
Comments
Only X.509
certificates are
supported
See specifications
of RSA private
keys for different
tokens (Page 27)
Operations with
RSA public keys
are performed in
software
DES operations
are performed in
software
Public Object Write Access
PKCS #11 mandates that even when no one is logged in to the
eToken, public token objects can be created or modified. Since
the eToken permits only the legitimate user to modify eToken
contents, it is not possible to implement this feature as specified.
It was decided to apply the same solution as for the security
officer logon described in eToken CardOS/M4 with Administrator
Password, page 30.
31
32
CHAPTER 3
Mechanisms
eTpkcs11 supports a subset of the entire PKCS #11 mechanism
set. This subset is enough to enable eTpkcs11 to integrate
seamlessly into PKI environments like Entrust PKITM.
eToken RTE does not support the CKM_SHA1_RSA_PKCS
mechanism currently. If the application needs to use it (to achieve
interoperability with standards or with other applications) some
work-around needs to be made in the application code. The
PKCS#11Seal/Unseal Sample on page 109 demonstrates this
technique.
The full list of mechanisms supported is detailed in Table 3-3.
Table 3-3: Supported Mechanisms
PKCS #11 Mechanisms
CKM_RSA_PKCS_KEY_PAIR_GEN
CKM_RSA_PKCS
CKM_RSA_X_509
CKM_DES_KEY_GEN
CKM_DES_ECB
CKM_DES_CBC
CKM_DES_CBC_PAD
CKM_DES3_KEY_GEN
CKM_DES3_ECB
CKM_DES3_CBC
CKM_DES3_CBC_PAD
CKM_MD5
CKM_SHA_1
CKM_PBE_SHA1_DES3_EDE_CBC
On the eToken CardOS/M4, RSA key generation and operations
are implemented on-token.
CHAPTER 3
On the eToken R2, none of the algorithms supported by the
above mechanisms are implemented on-token. However, RSA
key and certificate objects created with the TOKEN attribute set
to TRUE are stored on the eToken. The PRIVATE attribute
determines whether they are stored in public or private files on
the eToken.
eToken CardOS/M4 and PKCS #11 Functions
The following PKCS #11 functions cannot be used with the
eToken CardOS/M4:
♦ Export RSA private key.
♦ Wrap RSA private key.
♦ Get RSA private key attribute values.
♦ Copy RSA private key object.
These functions can be used with the eToken R2.
Functions
This section discusses behavior specifics of various PKCS#11
functions used in eToken implementation. Please note that:
♦ <>
are used to indicate that the particular field will be
initialized with actual information.
♦ []
are used for flags that may or may not be set
depending on the actual state.
C_GetInfo
The following fields of the returned structure will be set as shown:
cryptokiVersion
= 2.1
manufacturerID
= Aladdin Ltd.
flags
= none (0)
libraryDescription
= eToken PKCS#11
C_GetSlotInfo
33
34
CHAPTER 3
slotDescription
= <reader name>
manufacturerID
= Aladdin Ltd.
flags
= CKF_REMOVABLE_DEVICE |
CKF_HW_SLOT |
[CKF_TOKEN_PRESENT]
hardwareVersion
= 0.0
firmwareVersion
= 0.0
C_GetTokenInfo
label
= <token name>
manufacturerID
= Aladdin Ltd.
model
= "eToken R2" or "eToken
CardOS/M4"
flags
= CKF_LOGIN_REQUIRED |
CKF_RNG |
[CKF_USER_PIN_INITIALIZED]
ulMaxSessionCount
= CK_EFFECTIVELY_INFINITE
ulMaxRwSessionCount
= CK_EFFECTIVELY_INFINITE
ulMaxPinLen
= MAX_PIN_SIZE
ulMinPinLen
= MIN_PIN_SIZE
hardwareVersion
= "2.0" for R2 or "3.0" for PRO
and NG-OTP
firmwareVersion
= <token formware version>
CHAPTER 3
C_InitToken
This function should initialize the eToken. According to PKCS#11
v2.01, the password it receives as a parameter should serve as
the new Security Officer (SO) password. However there is no way
to present credentials needed to re-initialize the eToken (later
versions of the PKCS#11 standard changed the meaning of this
parameter).
If the application issues a C_InitToken call for the eToken that
has already been initialized, the eToken RTE will open a dialog
box that asks for a password to be entered. This occurs because
the C_InitToken parameter is treated as the new SO password,
not as the current one. In order to eliminate user interaction in this
situation, the program should perform the following calls
sequence:
♦ Open the session with the eToken. The eToken RTE will
allow the session to be opened, even with a non-initialized
eToken in order to work around this problem.
♦ Login as the SO. As previously described, if the eToken has
an administrator password this should be used. If not, then the
user password should be used. For a non-initialized eToken
this call will be ignored.
♦ Close the session. The session must be closed since it is
prohibited to perform C_InitToken if at least one session with
the eToken is open. The eToken will be logged out, but
eToken RTE will keep the password for a while (for the next
step).
♦ Perform C_InitToken. The same formatting password is
passed as a parameter.
It is still necessary to initialize the user password. The
InitToken Sample on page 108 demonstrates this technique.
C_InitPIN
This function behaves exactly as it is defined in the PKCS#11
specification. It may need to be issued for an eToken that has just
been initialized.
35
36
CHAPTER 3
If the eToken was initialized by the eToken Properties
management tool in eToken RTE 3.60, the PIN may or may not
have been initialized. This would depend on what initialization
parameters were set (default behavior is to initialize the PIN)
C_Login
For details, refer to User Login Semantics on page 30.
C_GetObjectSize
According to the PKCS#11 specifications, the C_GetObjectSize
function returns an approximate object size and may be slightly
inaccurate. As a result, when deleting or creating an object (for
example using C_CopyObject), the reported number of bytes may
not be completely accurate and should be monitored.
C_DeriveKey
No mechanisms for key derivation are currently implemented.
CHAPTER 3
CAPI
All Microsoft Windows operating systems support a cryptographic
API. Microsoft applications such as Microsoft Internet Explorer
and Microsoft Outlook employ this API for PKI operations, such
as digitally signed and/or encrypted mail. The operating system
itself uses this API for secure logon, device driver signing, EFS
and more.
Microsoft's cryptographic API has two main branches of
functionality:
♦ Encryption engine and key storage facility (CAPI).
♦ Certificate handling (CertStore).
Microsoft designed CAPI as a two-tier system where the Win32
API calls are delegated to a cryptographic service provider (CSP)
for the actual cryptographic operations. Microsoft supplies several
cryptographic providers in the distribution of each operating
system.
Microsoft also provides extensions to CertStore where third
parties can register custom certificate stores that are accessible
through the Win32 Certificate API.
For more information about Microsoft's Cryptographic API please
refer to the MSDN website at www.msdn.microsoft.com.
Aladdin has implemented eTCAPI, an eToken-oriented CSP of
type PROV_RSA_FULL, and an eToken physical certificate store.
These two components function as a single unit and may not be
separated.
Note:
For further information on integrating eTCAPI with Microsoft
Applications, see the eToken Enterprise page on the Aladdin
website http://www.aladdin.com/eToken.
37
38
CHAPTER 3
A CSP of type PROV_RSA_FULL has two main tasks:
♦ Provide a secure container for persistent RSA keys.
♦ Provide a symmetric encryption and hashing engine for a
variety of symmetric and hash algorithms.
eTCAPI currently supports both the eToken R2 and the eToken
CardOS/M4. eTCAPI uses the eToken R2 for secure RSA key
storage only and uses the eToken CardOS/M4 for RSA key
generation, key use and key storage. All other operations
(symmetric key operations and hashes) are delegated to the most
capable Microsoft CSP found on the machine. eTCAPI supports
multiple key containers on a single eToken.
eTCAPI implements all the required functionality of a CSP of type
PROV_RSA_FULL, and all of the optional functionality except for
the OffloadModExpo() function. The properties and limits on RSA
keys are detailed in Table 3-1: RSA Private Keys Specifications
on page 27.
CAPI vs. CertStore
Microsoft provides an API to enumerate certificates that are
known to the system. Once an eToken is inserted, all certificates
located on it will be automatically available for applications.
Certificates that come from eToken will have “eToken Base
Cryptographic Provider” set in the provider property. However,
when the eToken is removed, its certificates may NOT
automatically disappear. This depends on a number of factors:
♦ Propagation Mode vs. Token View Mode (see eToken RTE
3.60 documentation for more information). In Propagation
Mode (default) certificates are not removed from the computer.
♦ The kind of certificate that is being used. A Smartcard Logon
certificate is propagated by MS Windows itself regardless of
the Propagation Mode setting.
♦ The Operating System being used. Windows XP SP 2
propagates all certificates to the computer regardless of the
Propagation Mode setting.
CHAPTER 3
eToken RTE registers the physical store My\eToken for
backward compatibility purposes only. The certificates are
available via this store only in Token View mode. This feature is
considered to be obsolete and is supported only for backward
compatibility purposes and may be removed in the future
versions.
It is strongly recommended that new application
development does not handle certificates on eTokens via
this API.
If the application needs to take decisions based on the physical
presence of eTokens with particular keys/certificates, CAPI
mechanisms should be used. One of the eToken SDK samples
demonstrates this technique. (See Chapter 5 eToken Samples on
page 143).
eToken Provider
eToken RTE 3.60 installs a provider named “eToken Base
Cryptographic Provider” of the type PROV_RSA_FULL.
eToken CSP uses the Microsoft CSP internally. It will use one of
the Microsoft providers available on the computer, trying them in
the following order:
♦ "Microsoft Enhanced Cryptographic Provider v1.0", if it is
installed.
♦ Otherwise "Microsoft Base Cryptographic Provider v1.0" will be
used.
The set of cryptographic algorithms supported by the eToken
CSP are similar to those supplied by the corresponding Microsoft
CSP. They can be enumerated by using the CryptGetProvParam
function (with PP_ENUMALGS_EX parameter).
39
40
CHAPTER 3
Working with Multiple eTokens
The Cryptographic API (CAPI) does not include the concept of
multiple physical devices. This means that when starting to work
with the provider the container name must be supplied and not
some kind of eToken identification. This section explains the logic
of how the eToken CSP allows applications to deal with multiple
eTokens.
When the CryptAcquireContext call is issued, 3 factors affect the
operation. These are:
♦ Container name.
This is passed as a parameter to CryptAcquireContext.
♦ Flags.
These are passed to CryptAcquireContext.
♦ Current reader.
The Current Reader is the reader with the eToken that was
selected successfully by the last CryptAcquireContext
operation. The Current Reader will be used in all subsequent
calls to CyrptAcquireContext, unless the reader name is
passed explicitly or until the eToken is removed.
The logic of eToken selection is detailed as follows:
♦ If the application explicitly passes a reader name (as is
described in Explicitly Passing the Reader Name ), this reader
will be used.
♦ Otherwise, if the current reader has already been set by
previous operations, it will be used.
♦ Otherwise, if there is only one eToken currently inserted, it will
be used.
♦ Otherwise, the operation depends on flags passed to
CryptAcquireContext:
• If the CRYPT_VERIFYCONTEXT flag was passed, no
eToken will be selected. This operation allows for
enumerating all containers on all eTokens.
• If CRYPT_SILENT flag was set, the operation will fail
(since there is no way to choose a particular eToken).
• If neither of these flags is set, the eToken RTE will pop up
a dialog box asking the user to select the eToken.
CHAPTER 3
Explicitly Passing the Reader Name
The application may explicitly pass the reader name to the
CryptAcquireContext function in one of the following forms:
♦ Reader name may be encoded as: “\\.\reader-name\“. This is
the form used by Smartcard Logon. If you issue the
CryptAcquireContext call without the
CRYPT_VERIFYCONTEXT flag, the default key container (see
Default Key Container on page 42) will be opened. If there is
no such container, the function will fail. If you issue
CryptAcquireContext with the CRYPT_VERIFYCONTEXT flag,
the function will succeed even if there are no key containers on
the eToken. This may be used to enumerate key containers on
a particular eToken (See the EnumTokens Sample on page
112).
Note:
The backslash character should be doubled when encoding
string constants in a C-language.
♦ Reader name and container may be encoded as:
”\\.\reader-name\key-container-name”. This form may be
used to open the specified container on the particular eToken.
♦ Reader name, container and password may be encoded in the
key-container parameter as:
”[reader-name{{password}}]=key-container-name”.
Both the password and/or key container name may be omitted,
for example:
Reader name
=
Password
=
Key container name =
AKS ifdh 0
1234567890
MyKeyContainer
The string will look as follows:
[AKS ifdh 0{{1234567890}}]=MyKeyContainer
This implies that “[x] =” is an invalid key container name for all
bit strings x.
This method is supported for backward compatibility.
41
42
CHAPTER 3
Performing login/logout
Some operations with the eToken (such as performing
computations with the RSA private key, creation/deletion of key
containers) require the user to be logged in. If the user is not
logged in before such an operation, a pop-up window will appear.
This window asks the user to log in or the operation will fail (in
CRYPT_SILENT mode).
It is possible to log in programmatically by issuing a
CryptSetProvParam call:
CryptSetProvParam (hProv, PP_EXCHANGE_PIN, “password”);
Passing NULL actually performs the logout operation.
It is also possible to pass the password during a
CryptAcquireContext call (as previously described). This method
is supported for backward compatibility, but it is not
recommended for new development.
Default and Auxiliary Key Containers
The eToken RTE distinguishes between default and auxiliary key
containers. This separation is made because some applications
(such as Windows Logon) pass the Reader Name as a parameter
to the CryptAcquireContext function, while other applications
(such as Microsoft VPN) pass NULL. It is up to the customer
whether the same key and certificate are to be used in both
cases.
Default Key Container
If the application passes a reader name as a parameter (i.e. in
the form “\\.\reader-name\” – see Explicitly Passing the Reader
Name on page 41), the default key container will be opened. The
last certificate with Smartcard Logon key usage written to the
eToken will define the default container. If there is no such
container, the operation will fail.
CHAPTER 3
In order to explore which container acts as the default key
container, the application may pass the reader name to the
function CryptAcquireContext (as described previously) and get
the container name by issuing CryptGetProvParam with
PP_CONTAINER or PP_UNIQUE_CONTAINER.
In order to set the currently opened container as the default, the
application may use a proprietary parameter for
CryptGetProvParam as follows:
DWORD val = 1;
CryptSetProvParam (hProv, 0x10004, (BYTE *)&val, 0);
Note:
The eToken CSP will not check whether the corresponding container
really contains the certificate suitable for Smartcard Logon.
Auxiliary container
If the application passed NULL instead of the key container
name, the following will occur:
♦ If the auxiliary container was set for the eToken, it will be used.
♦ Otherwise, if there is a default container on the eToken, it will
be used.
♦ Otherwise, an arbitrary key container will be used.
In order to explore which container serves as the auxiliary
container, the application may pass NULL to the function
CryptAcquireContext and obtain the container name by issuing
CryptGetProvParam with PP_CONTAINER or
PP_UNIQUE_CONTAINER.
In order to set the currently opened container as an auxiliary
container, the application may use the following proprietary
parameter to CryptGetProvParam:
DWORD val = 1;
CryptSetProvParam (hProv, 0x10001, (BYTE *)&val, 0);
Use 0 instead of 1 if you want to remove any explicit reference to
the auxiliary container name.
43
44
CHAPTER 3
Suppressing Standard Behavior of eToken
CSP
In certain situations, the application has to suppress some
aspects of the standard eToken CSP behavior. This can be
performed by using CryptSetProvParam as follows:
DWORD val=flags;
CryptSetProvParam (hProv, 0x10003, &val, 0);
The following flags are defined:
♦ Bits 0..1 define UI behavior. They are interpreted as a 2-bit
number that may be set to one of the following:
• 0: regular behavior. In ambiguous situations, eToken CSP
may ask the user for a proper choice.
• 1: only prompts for the user password may appear. In
ambiguous situations, eToken CSP makes a default
decision.
• 2: no UI appears. In ambiguous situations, eToken CSP
makes a default decision. If a user password is needed,
the function will fail.
♦ Bit 31 (when set) suppresses Propagation mode for a
particular application.
♦ Other bits are reserved for internal purposes and should not be
used by the application.
The application can read the current value with
CryptGetProvParam if it needs to restore it later.
The newly set mode, irrespective of which container and eToken
is being used, affects the entire application until it is changed or
until the eToken CSPis unloaded from the process memory.
CHAPTER 3
CAPI Limitations
The following operations cannot be performed using CAPI:
♦ Obtain a list of currently inserted eTokens. Use the
Smartcard Resource Manager API for this purpose (see
EnumTokens Sample on page 112).
♦ Receive notification about eToken insertion/removal. In
many cases the application does not really need to be notified
about eToken removal. It may be enough to know that the
eToken has been removed before an operation is performed.
In this case, it is enough to keep one opened context to some
container on the eToken. Any operation with this container will
fail if the eToken has been removed, even if there is no need
to physically access the eToken. However, if there is a need
for insertion/removal notifications, use the Smartcard Resource
Manager API for these purposes.
♦ Change a user password.
♦ Logon as an administrator, change administrator
password or reset a user password.
♦ Use eToken for secure storage.
If any of these operations are needed, PKCS#11 would be a
better methodology to use and is recommended for this purpose.
45
46
CHAPTER 3
CAPI & PKCS#11 Interoperability
eToken RTE 3.60 provides some interoperability between CAPI
and PKCS#11. The CAPI CSP can use keys created via
PKCS#11 and vice versa, but there are certain restrictions to this
as detailed in this section.
Note:
Avoid mixing PKCS#11 and CAPI calls in a single application.
Using PKCS#11 Objects from CAPI
When an application enumerates a key container on the eToken
(by calling CryptGetProvParam), all PKCS#11 keys are
represented by virtual key containers with names like:
PKCS11-8FD0F577-0D1B-4ac0-9567-37BD7FDACB4E:n, where
n is the eToken internal key ID.
The following restrictions apply when working from CAPI with
PKCS#11 objects:
♦ Certificates cannot be read by using CryptGetKeyParam. Nor
can they be deleted by using CryptSetKeyParam. They will still
be seen when enumerating certificates via Certificate Store.
♦ Since key containers associated with PKCS#11 keys do not
really exist on the eToken, such a key container cannot be set
as the default or auxiliary container.
Using CAPI Objects from PKCS#11
When enumerating objects in PKCS#11, application objects
created by CAPI are given predefined labels:
♦ Private keys are labeled “eTCAPI Private Key”
♦ Public keys are labeled “eTCAPI Public Key”
♦ Certificates are labeled “(eTCAPI) + < issued to >”
The following restrictions apply when working from PKCS#11 with
CAPI objects:
CHAPTER 3
♦ All CAPI objects are not modifiable.
♦ In CAPI, you cannot delete the key separately. You may only
delete the entire key container. Therefore, attempts to delete
the private key will result in deletion of the public key and
certificate (if any) as well. Moreover, if 2 RSA private keys
were located in a single key container, both of them would be
deleted (in practice, applications rarely put two keys in a single
container).
47
48
CHAPTER 4
Chapter 4
eToken Supplementary API
About This Chapter
♦ Compatibility with eToken RTE Versions on page 50
♦ Overview of SAPI Functionality on page 51
♦ Common Principles on page 56
♦ Data Types on page 58
♦ Error Codes on page 61
♦ New Object Classes on page 62
♦ Common Functionality on page 76
♦ Slot/Token Functionality on page 77
♦ OTP Functionality on page 82
♦ Battery Indication Functionality on page 89
♦ Server Side Functionality on page 97
CHAPTER 4
PKCS#11 API is considered as the primary interface to the
eToken. However some functionality that may be essential for
application developers is outside the scope of the PKCS#11
standard. Examples of such functions are:
♦ Obtaining extended information about the version and
capabilities of a particular eToken device.
♦ Initializing of eToken in a more flexible manner than provided
by the C_InitToken PKCS#11function.
♦ Secure unblocking of a user PIN.
♦ Managing the OTP (one-time password) functionality of
eToken devices supporting OTP.
♦ Managing the battery-indication functionality of eToken devices
that contain a battery.
Future eToken RTE versions may provide this functionality as
vendor-specific extensions to PKCS#11. Currently, the eToken
SDK provides an alternate Supplementary API (SAPI) to
address developers’ needs.
49
50
CHAPTER 4
Compatibility with eToken RTE
Versions
Using SAPI requires that eToken RTE 3.60 is installed (unless
the application uses only server-side functionality). If an incorrect
eToken RTE version is installed, the results may be
unpredictable.
Future eToken RTE versions may install later versions of
SAPI.
It is expected that in the future, SAPI functionality will be provided
via eToken PKCS#11; so that SAPI will be deprecated. The API
will still be supported for some time to ensure backward
compatibility. However new functionality will not be included in
SAPI.
CHAPTER 4
Overview of SAPI Functionality
OTP Functionality
Some eToken devices (specifically - eToken NG-OTP) may
support one-time password (OTP) functionality. OTP-capable
eTokens should be initialized with some OTP secret. The user
may then generate a new OTP value by pressing the button
without even connecting the eToken to the computer and use the
eToken in various password-protection schemes (certainly,
proper back end support is needed). The eToken may also allow
computing of the new OTP value in the online mode (i.e. when
the eToken is connected).
When creating a new OTP object, certain parameters are
customizable. The ability to customize parameters is dependant
on the particular eToken FW version.
Generally speaking the eToken may be able to support multiple
OTP secrets and support multiple OTP algorithms. But since
currently only one OTP secret per eToken is supported (it would
be hardly usable to keep multiple secrets, since eToken NG-OTP
has only one button), it is referenced indirectly by all OTP
functions.
Similarly, currently only one OTP algorithm is supported. This is
an HMAC-SHA1 based HOTP algorithm. For more information,
please refer to:
http://www.ietf.org/internet-drafts/draft-mraihi-oath-hmac-otp04.txt
The eToken should be initialized with HMAC-SHA1 support to
use HOTP functionality.
The application may use:
51
52
CHAPTER 4
♦ SAPI_OTP_GetMechanismList and
SAPI_OTP_GetMechanismInfo to examine the eToken’s OTP
capabilities.
♦ SAPI_OTP_Create to create instances of the OTP object.
♦ SAPI_OTP_Destroy to delete it (the OTP object).
♦ SAPI_OTP_GetAttributeValue to examine attributes of the
existing OTP object.
♦ SAPI_OTP_SetAttributeValue to change the presentation
duration of the OTP object on the eToken.
♦ SAPI_OTP_Execute to perform OTP calculations on the
eToken.
♦ SAPI_Server_OTP_Calculate to perform OTP calculations
without the eToken, passing the OTP secret as a parameter.
This function is used by the server application to validate user
authentication.
See OTP Functionality on page 83 for detailed information.
CHAPTER 4
Battery Indication Functionality
Some eToken devices (specifically eToken NG-OTP) have a
battery. The battery is used for OTP calculations in the offline
mode (i.e. when the eToken is not connected to the computer and
therefore needs an internal power supply).
It is essential to be able to approximate the battery lifetime to
avoid a situation where the battery expires while the eToken
owner is on the road and cannot authenticate or replace the
eToken.
This estimate may be needed:
♦ On the user side - To warn the eToken owner.
♦ On the server side - To report to the administrator about
eTokens that are near the end of their battery life.
The correct operation of the battery indication functionality
requires careful cooperation from eToken firmware, middleware
(i.e. eToken RTE and SAPI) and data management on the server.
This is necessary as the computation of power consumption is a
complicated process since the power consumption itself depends
on many factors such as:
♦ The hardware of the particular eToken (since any modification
to the hardware may affect the power consumption).
♦ The firmware version (since changes in the firmware code
affect the time it takes to complete the OTP computation).
♦ EToken usage for OTP purposes.
♦ Battery lifetime.
The correct operation of the battery indication functionality
therefore requires that the middleware knows the details of the
battery consumption computation for the particular eToken model
and version. These details are encoded as part of the battery
indication subsystem stored on the eToken.
53
54
CHAPTER 4
♦ SAPI_BI_Create to initialize the battery indication subsystem
on the eToken. This subsystem will later be used by the
eToken to compute power consumption during OTP
calculations.
♦ SAPI_BI_Check to check the integrity of the battery indication
subsystem.
♦ SAPI_BI_Destroy to erase the battery indication subsystem
on the eToken. This function is provided only for
completeness of the API.
♦ SAPI_BI_GetAttributeValue to examine the current state of
the battery indication system (such as current power
consumption).
♦ SAPI_BI_SetAttributeValue to change the state of the battery
indication system (such as level of battery consumption when
the eToken owner should be warned about low battery state).
♦ SAPI_BI_Save and SAPI_BI_Restore to save and later
restore the content of the battery indication system. This
functionality may be used by administrative applications.
♦ SAPI_BI_Recalibrate to recalibrate the battery consumption
information on the eToken taking into account the eToken
lifetime. This is necessary since the eToken may not have a
real-time clock so it cannot compute the passed time without
middleware assistance.
♦ SAPI_BI_Get_Config to construct data needed for proper
computation of battery consumption for a particular eToken
model.
♦ SAPI_Server_BI_EstimateValue and
SAPI_Server_BI_EstimateRetainDays in the server
application to estimate the eToken power consumption based
on the passed time and eToken usage. These functions are
used when the application needs to supply the administrator
with some reasonable eToken lifetime estimation.
See Battery Indication Functionality on page 89 for detailed
information.
CHAPTER 4
Miscellaneous Functionality
Supplementary API provides application developers with
additional functionality that may be usable for some applications.
♦ SAPI_GetLibraryInfo to obtain information about the library
version.
♦ SAPI_GeSlotInfo to obtain information about the particular slot.
♦ SAPI_GetTokenInfo to obtain full information about the eToken
model, version and capability. The function returns the
required information in the template of attributes that describes
“token object”.
♦ SAPI_InitToken to initialize the eToken. The function gets the
initialization parameters in the template of attributes that
describe “token object” (many of these attributes are common
with the SAPI_GetTokenInfo function).
♦ SAPI_FindTokens or SAPI_LocateToken to find the needed
eToken between all eTokens currently inserted in the
computer.
♦ SAPI_UnblockPIN and SAPI_Server_Unblock to unblock the
user PIN remotely. Unlike the C_InitPIN function of PKCS#11,
it allows unblocking of the user PIN without the Security Officer
PIN (SO PIN) being known by the client application by using a
challenge-response mechanism. The function
SAPI_UnblockPIN is run on the client machine (where the
eToken is inserted), while the function SAPI_Server_Unblock
cooperates on the server side, computing the proper
cryptographic response.
See Slot/Token Functionality on page 77 for detailed information.
55
56
CHAPTER 4
Common Principles
When working with SAPI functions:
♦ The application may call SAPI functions by one of two ways:
• Statically linking eTSAPI.DLL by using the import library
supplied with the SDK.
• Dynamically loading eTSAPI.DLL by using the LoadLibrary
function and then locating API functions by using
GetProcAddress.
♦ The application should call the PKCS#11 C_Initialize function
prior to any usage of SAPI functions.
♦ The application should not call the C_Finalize function as long
as it continues to use SAPI functions.
This section contains a brief description of the proposed SAPI
functions. For each function, the following applies:
♦ Function returns CK_RV as the return value just like all
PKCS#11 functions. Several vendor specific return codes are
defined by SAPI and are described in the Error Codes on page
61.
♦ If the function operates with a particular slot, it gets either a
slot ID or session handle as a parameter. A session handle is
used if it is expected that the eToken must be properly
initialized before the function call.
♦ Whenever possible data types and structures defined in
PKCS#11 are used. SAPI defines several more data types that
are described later.
♦ Parameter template means CK_ATTRIBUTE_PTR which
points to the attributes array and CK_ULONG containing the
array size. The handling of this parameter is similar to other
PKCS#11 functions.
CHAPTER 4
♦ This section defines new object classes (such as token, battery
indicator etc.). Note, that the API does not really use
PKCS#11object-related functions (such as C_FindObjects).
Currently these object classes are used only to group the
relevant attributes, while separate API functions are used to
operate with each feature. Future RTE versions may define
new object classes for these purposes.
The new API is defined in the eTSAPI.h header file.
57
58
CHAPTER 4
Data Types
SAPI uses data types as defined in PKCS#11 and in addition
defines several more. These are described here:
CK_INIT_CALLBACK
typedef CK_CALLBACK_FUNCTION (CK_RV,
CK_INIT_CALLBACK) (CK_VOID_PTR pContext, CK_ULONG
progress);
This callback function is used with the SAPI_InitToken function to
let the application show its progress in percentage term. The
parameters are:
♦ pContext – the context that has been passed to
SAPI_InitToken
♦ progress – the formatting progress in percentage.
This function should return CKR_OK to continue the initialization
or any other return value to stop it.
CK_UNBLOCK_CALLBACK
typedef CK_CALLBACK_FUNCTION (CK_RV,
CK_UNBLOCK_CALLBACK) (CK_SESSION_HANDLE
hSession, CK_VOID_PTR pChallenge, CK_VOID_PTR
pResponse);
This callback function is for the SAPI_UnblockPIN function and is
used to complete the challenge-response calculation. The
parameters are:
♦ hSession – the session handle that has been passed to the
SAPI_UnblockPIN function
CHAPTER 4
♦ pChallenge – the cryptographic challenge as created by the
eToken
♦ pResponse – the response to the challenge
CK_SAPI_OTP_MECHANISM_INFO
typedef struct tagCK_SAPI_OTP_MECHANISM_INFO
{
CK_ULONG mechanism; // CK_OTP_HMAC_SHA1_DEC6
CK_ULONG minKeyLen;
CK_ULONG maxKeyLen;
CK_ULONG OTPLen;
// 6
CK_ULONG defDuration;
CK_ULONG flags;
} CK_SAPI_OTP_MECHANISM_INFO,
*CK_SAPI_OTP_MECHANISM_INFO_PTR;
This structure describes information about the OTP mechanism
as returned from the function SAPI_OTP_GetMechanismInfo.
The fields of the structure are:
♦ mechanism – OTP mechanism
(only the CK_OTP_HMAC_SHA1_DEC6
mechanism is currently supported
♦ minKeyLen – the minimum key length of the OTP secret
♦ maxKeyLen – the maximum key length of the OTP secret
♦ OTPLen – the size of the produced OTP value (excluding the
final zero-character)
♦ defDuration – the duration of the OTP presentation in seconds
♦ flags – this can be a combination of one or more flags that
describe the mechanism’s capabilities. They can be
• CK_SAPI_OTP_CURRENT_SUPPORTED – the eToken
supports retrieving the current OTP value. See the
SAPI_OTP_Execute function.
• CK_SAPI_OTP_ZERO_SUPPORTED – the eToken
supports retrieving the “zero” OTP value. See the
SAPI_OTP_Execute function.
59
60
CHAPTER 4
•
•
•
CK_SAPI_OTP_CUSTOM_DURATION – the eToken
supports customization of the OTP display duration
CK_SAPI_OTP_CTL_DURATION – the ability to change
the OTP display duration can be restricted at the time of
OTP object creation
CK_SAPI_OTP_BUTTON SUPPORTED – eToken
supports the use of an OTP button when the eToken is
connected to the computer
CHAPTER 4
Error Codes
In general and for most occasions, SAPI functions return the
standard PKCS#11 error codes. Table 4-1 shows some of the
more common error codes likely to be returned. In addition to
these, please refer to the PKCS#11 documentation for a
complete list of the error codes.
See http://www.rsasecurity.com/rsalabs/node.asp?id=2133
Table 4-1: General PKCS#11 Error Codes
Name
Meaning
CKR_TEMPLATE_INCOMPLETE
A mandatory attribute is not passed.
CKR_TEMPLATE_INCONSISTENT
Certain passed attributes make no sense
together.
CKR_ARGUMENTS_BAD
The required operation cannot be performed
with the passed parameters.
CKR_USER_NOT_LOGGED_IN
The user is required to be logged in.
CKR_DEVICE_ERROR
An object is damaged.
SAPI functionality allows for certain actions that are not covered
by PKCS#11 error codes and for these actions SAPI specific
codes are required. The instances of this are limited and Table
4-2 shows ALL the SAPI specific error codes.
Table 4-2: SAPI Specific Error Codes
Name
Meaning
CKR_SAPI_OBJECT_DOES_NOT_EXIST
The object asked about in the operation
does not exist.
CKR_SAPI_OBJECT_ALREADY_EXISTS
An object already exists. This may be
returned from functions like SAPI_BI_Create
and SAPI_OTP_Create
CKR_SAPI_NOT_SUPPORTED_BY_TOKEN
The eToken does not support the requested
feature.
61
62
CHAPTER 4
New Object Classes
This section provides information about new objects available to
applications. In future versions, PKCS#11 will support these or
similar objects via regular PKCS#11 functions. Currently, these
object classes are sets of attributes that may appear in various
functions of SAPI.
Slot Object
The slot object is used to represent the eToken characteristics
that are not available via the C_GetSlotInfo function. Future
eToken RTE versions will allow the opening of a special session
with any slot, even if there is no eToken in it (PKCS#11
specification allows opening session only if the slot contains a
properly initialized eToken).
Attributes
CKA_SAPI_SLOT_NAME
CK_CHAR_PTR
This attribute is a null terminated string. For smartcard readers
(and virtual slots belonging to smartcard readers) it contains the full
reader name while for software eTokens it contains the file name.
See PKCS#11 documentation for more details.
CKA_SAPI_SLOT_TYPE
CK_ULONG and may be:
CK_SAPI_SLOT_SC_READER
CK_SAPI_SLOT_SC_VIRTUAL
CK_SAPI_SLOT_FILE (future)
This attribute contains a constant that defines the slot type
thereby distinguishing virtual slots from real slots, eTokens from
smartcards etc.
CHAPTER 4
Token Object
This object is used to:
♦ Represent token characteristics not available via the
C_GetTokenInfo function.
♦ Learn whether the token has some special capabilities (like
OTP).
♦ Perform token initialization.
Note:
Some token attributes may not be allowed during initialization,
while others are allowed only during initialization.
Attributes
CKA_SAPI_CARD_ID
CK_BYTE_PTR
This is the smartcard’s unique ID. It is unique for cards from a
particular OS vendor (i.e. in conjunction with
CKA_SAPI_CARD_TYPE). Cardless tokens (such as the eToken
R2) return an empty byte array as the smartcard ID. This is a
read only attribute.
CKA_SAPI_CARD_TYPE
CK_ULONG and may be:
CK_SAPI_CARD_NONE
CK_SAPI_CARD_OS
This distinguishes cards from different vendors with
CK_SAPI_CARD_NONE meaning No Smartcard and
CK_SAPI_CARD_OS meaning Siemens CardOS. This is a read
only attribute.
CKA_SAPI_CARD_VERSION
CK_VERSION
This is the OS version of the smartcard. This is a read only
attribute.
63
64
CHAPTER 4
CKA_SAPI_CASE_MODEL
CK_ULONG
This refers to constants that state how the casing looks:
Constant
Casing
CK_SAPI_CASE_NONE
Smartcard
CK_SAPI_CASE_CLASSIC
Classic shape (R2 and PRO)
CK_SAPI_CASE_NG1
“NG1” shape (eToken NG-OTP)
CK_SAPI_CASE_NG2
“NG2” shape (eToken NG-OTP)
This is a read only attribute.
CKA_SAPI_COLOR
CK_ULONG
This provides information on the eToken color where it has been
burnt in or on a smartcard. It may be set for initializing only if
CKA_SAPI_REAL_COLOR=FALSE. It is recommended that it is
NOT used.
CKA_SAPI_FIPS
CK_BBOOL
When used in the SAPI_GetTokenInfo function, this attribute
states whether the eToken is currently initialized as FIPScompliant or not. When passed to the SAPI_InitToken function,
this attribute defines whether the eToken should be initialized as
FIPS-compliant or not.
CKA_SAPI_FIPS_SUPPORTED
CK_BBOOL
This attribute states whether the eToken can be initialized as a
FIPS token. This is a read only attribute.
CHAPTER 4
CKA_SAPI_HAS_BATTERY
CK_BBOOL
This indicates whether or not the eToken has a battery by means
of a true or false answer. This is a read only attribute.
CKA_SAPI_HAS_LCD
CK_BBOOL
This indicates whether or not the eToken has an LCD display by
means of a true or false answer. This is a read only attribute.
CKA_SAPI_HAS_SO
CK_BBOOL
This indicates whether or not the eToken has a Security Officer
by means of a true or false answer. This is a read only attribute.
CKA_SAPI_HAS_USER
CK_BBOOL
This attributes determines whether the eToken is initialized or
empty. This is a read only attribute.
CKA_SAPI_HMAC_SHA1
CK_BBOOL
states whether the eToken currently supports the HMAC SHA1
algorithm or not. When passed to the SAPI_InitToken function,
this attribute defines whether you need the eToken to support the
HMAC SHA1 algorithm.
CKA_SAPI_HMAC_SHA1_SUPPORTED
CK_BBOOL
This attribute states whether the eToken can be initialized with
HMAC SHA1 algorithm support. This is a read only attribute.
65
66
CHAPTER 4
CKA_SAPI_INIT_PIN_REQ
CK_BBOOL
This attribute states whether the CKA_SAPI_PIN_CURRENT
attribute is required for eToken initialization. This is a read only
attribute.
CKA_SAPI_MAY_INIT
CK_BBOOL
This attribute states whether or not it is possible to initialize the
eToken at all (if FALSE – the eToken is an R2, if TRUE – any
other eToken). This is a read only attribute.
CKA_SAPI_MODEL
CK_CHAR_PTR
This produces a character string describing the product and
includes information on the hardware version. This attribute is
read only. It has 2 usages:
• It is used by some BI-functions to address a particular
eToken in the configuration information database.
• It may be displayed by an application to get some eToken
description. This description is not informative for user
applications, but may be helpful for support reasons
including troubleshooting.
The content of this attribute may change as a result of a eToken
FW upgrade.
CKA_SAPI_NEW_KEY
CK_BYTE_PTR
This attribute defines the secret key that will be set on the eToken
for further initialization. Absence of this attribute means that the
default key will be used. This attribute may be used only when
calling SAPI_InitToken.
CHAPTER 4
CKA_SAPI_OLD_KEY
CK_BYTE_PTR
This attribute defines the secret key used for eToken initialization.
Absence of this attribute means that the default key will be used.
This attribute may be used only when calling SAPI_InitToken.
CKA_SAPI_PIN_CURRENT
CK_CHAR_PTR
This is the current password of the user or SO. This is supplied
only if the eToken is reinitialized after having been initialized in
FIPS mode. This attribute may be used only when calling
SAPI_InitToken.
CKA_SAPI_PIN_SO
CK_CHAR_PTR
This is used only for eToken initialization and the administrator
password is provided to the eToken. If no password is supplied,
the eToken will not have an administrator. This attribute may be
used only when calling SAPI_InitToken.
CKA_SAPI_PIN_USER
CK_CHAR_PTR
This is used only for eToken initialization and the user password
is provided to the eToken. If no password is supplied, the eToken
is initialized as empty. This attribute may be used only when
calling SAPI_InitToken.
CKA_SAPI_PRODUCT_NAME
CK_CHAR_PTR
This is a product name like eToken PRO or eToken NG-OTP and
contains the token type encoded as a string. This is a read only
attribute.
67
68
CHAPTER 4
CKA_SAPI_PRODUCTION_DATE
CK_DATE
This is the date on which the eToken was produced. This attribute
may be zeroed for eTokens that do not store the production date.
This is a read only attribute.
CKA_SAPI_REAL_COLOR
CK_BBOOL
This indicates whether the color information returned by the
CKA_SAPI_COLOR attribute is burned onto the eToken during
production or is supplied by an application during eToken
initialization and in this case may be arbitrary. This is a read only
attribute.
CKA_SAPI_RETRY_SO
CK_ULONG
This is the current number of log in failure attempts still allowed
before the Security Officer (SO) PIN is locked. It should be noted
that when log in is successful, the counter automatically reverts to
the maximum for future attempts. This is a read only attribute.
CKA_SAPI_RETRY_SO_MAX
CK_ULONG
This attribute defines the maximum number of log in attempts a
user can make with incorrect passwords before the SO PIN has
been locked. When initializing the eToken, this attribute applies
only if a SO PIN (CKA_SAPI_SO_PIN) is also supplied.
CKA_SAPI_RETRY_USER
CK_ULONG
This is the current number of log in failure attempts still allowed
before the user PIN is locked. It should be noted that when log in
is successful, the counter automatically reverts to the maximum
for future attempts. This is a read only attribute.
CHAPTER 4
CKA_SAPI_RETRY_USER_MAX
CK_ULONG
This attribute defines the maximum number of log in attempts a
user can make with incorrect passwords before the user PIN has
been locked. When initializing the eToken, this attribute applies
only if a user PIN (CKA_SAPI_USER_PIN) is also supplied.
CKA_SAPI_RSA_KEYS
CK_ULONG
This attribute is used only in the SAPI_InitToken function to
define the amount of space reserved for RSA keys during eToken
initialization. It is defined in terms of the number of 1024-bit RSA
keys that may be created. If this parameter is omitted, the default
value will be used. If 0 is passed, no place will be allocated for
RSA keys.
CKA_SAPI_RSA_2048
CK_BBOOL
states whether the eToken currently supports RSA 2048 keys or
not. When passed to the SAPI_InitToken function, this attribute
defines whether you need the eToken to support RSA 2048 keys.
CKA_SAPI_RSA_2048_SUPPORTED
CK_BBOOL
This attribute states whether the token can be initialized with RSA
2048 key support. This is a read only attribute.
CKA_SAPI_SERIAL
CK_CHAR_PTR
This is a unique eToken identifier. This field should be used by
applications to refer to the particular eToken. It is guaranteed to
be unique and compatible with the corresponding field in the
CK_TOKEN_INFO structure in PKCS#11. This is a read only
attribute.
69
70
CHAPTER 4
CKA_SAPI_TOKEN_ID
CK_BYTE_PTR
This is a unique ID for each USB eToken. Smartcards return an
empty byte array as the eToken ID. This is a read only attribute.
CKA_SAPI_USER_PIN_INITIALIZED
CK_BBOOL
This attribute defines the user PIN as being initialized. The default
value for this attribute is TRUE. This attribute may be used only
when calling SAPI_InitToken.
CHAPTER 4
OTP Object
The OTP object represents the OTP secret and corresponding
data (such as counter), stored and operated by the eToken.
Generally speaking, the eToken may support multiple OTP
algorithms as well as multiple objects implementing the same
OTP algorithm. Only one OTP object per eToken is currently
supported by SAPI.
Attributes
When the eToken is initialized, these attributes control how the
eToken will behave. When the attributes are simply being read,
they inform the application about how the eToken behaves.
These attributes cannot be changed.
CKA_SAPI_OTP_COUNTER
CK_ULONG
This determines the current value of the moving factor. If not
supplied to the function SAPI_OTP_Create, 0 will be used as the
default value. This attribute may not be changed by an application
after creation.
CKA_SAPI_OTP_CURRENT_ALLOWED
CK_BBOOL
This attribute defines whether the last OTP value may be
received by using the SAPI_OTP_Execute function. This attribute
is TRUE for all currently supported eTokens. This is a read only
attribute.
CKA_SAPI_OTP_CUSTOM_DURATION_ALLOWED
CK_BBOOL
This indicates whether, after the object was created, the duration
can be changed.
71
72
CHAPTER 4
CKA_SAPI_OTP_DURATION
CK_ULONG
This determines for how long (in seconds) the OTP value appears
on the eToken when the button is pressed.
CKA_SAPI_OTP_MECHANISM
CK_MECHANISM_TYPE
This identifies the particular OTP mechanism.
CKA_SAPI_OTP_VALUE
CK_BYTE_PTR
This attribute contains the value of the OTP secret that should be
passed to the SAPI_OTP_Create function. This is a sensitive
attribute in PKCS#11 terms.
CKA_SAPI_OTP_ZERO_ALLOWED
CK_BBOOL
This attribute defines whether the OTP computation based on a
zero-counter is allowed. Refer to the SAPI_OTP_Execute
function for more information.
CHAPTER 4
Battery Feature Object
The battery feature object represents battery measurement and
indication functionality. It exists for all eTokens that have a
battery.
The battery functionality may be used only if the
CKA_SAPI_HAS_BATTERY attribute is TRUE.
Attributes
CKA_SAPI_BI _ASSEMBLY_DATE
CK_DATE
This shows the date on which the battery was inserted into the
eToken. It can only be set during creation of the object. This is
important for replacement of batteries but is only of interest for
servers.
CKA_SAPI_BI_CAPACITY
CK_ULONG
This shows the initial capacity of the battery in µkA (micro
Amperes) seconds and can only be set during creation of the
object. If this parameter is absent, it means using the default for
this eToken.
CKA_ SAPI_BI_CONFIG
CK_BYTE_PTR
This attribute contains eToken-specific information needed for the
proper computation of power consumption. It should be supplied
by the application during creation of the battery indication
subsystem (which is usually done during eToken production) and
used later by the middleware.
73
74
CHAPTER 4
In order to perform server-side estimations of the power
consumption, the application should get this attribute from the
eToken and store it in the server application for future use. Since
power consumption depends on the exact eToken hardware and
firmware version, it may vary between eTokens. The application
also should be aware that the value of this attribute may change
as a result of downloading a new FW version.
CKA_SAPI_BI_FIRST_WARN
CK_ULONG
This represents a percentage indication of available battery
capacity (e.g. 50 %) at which point the first warning indicator is
shown on the LCD display. If this attribute is absent on creation,
the default will be used.
CKA_SAPI_BI_HW_MEASURING
CK_BBOOL
This indicates whether the battery can be measured. This is a
read only attribute.
CKA_ SAPI_BI_RECALIBRATION_DATE
CK_DATE
This attribute tells the date on which the latest recalibration was
performed. It can only be set during creation of the object. If this
attribute is absent, it means no calibration was done.
CKA_SAPI_BI_REPLACEABLE
CK_BBOOL
This indicates whether the battery is replaceable. At present it
returns FALSE for all batteries. This is a read only attribute.
CHAPTER 4
CKA_SAPI_BI_SECOND_WARN
CK_ULONG
This represents a percentage indication of available battery
capacity at which point the second warning indicator is shown on
the LCD display. If this attribute is absent on creation, the default
will be used.
CKA_ SAPI_BI_VALUE
CK_ULONG
This shows the remaining capacity of the battery in µkA seconds.
Absence of this value means 0 as the system is being created.
It may be set by the application during creation of the object. At a
later stage, it can be changed by the eToken FW or during
recalibration.
75
76
CHAPTER 4
Common Functionality
SAPI_GetLibraryInfo
This function returns version information about the currently
installed SAPI and underlying eToken RTE.
CK_RV SAPI_GetLibraryInfo (
CK_VERSION_PTR pSapiVersion,
CK_VERSION_PTR pRteVersion
);
Parameters
pSapiVersion
[out] Pointer to the structure that receives the current SAPI API
version number. The current version number is 1.0
pRTEVersion
[out] Pointer to the structure that receives the current installed
RTE version number. It must be 3.60 or later.
Note:
If pRteVersion is zeroed upon return, no eToken RTE is currently
installed. Only server-side SAPI functionality is available in this case.
CHAPTER 4
Slot/Token Functionality
SAPI_GetSlotInfo
This function returns information about a particular slot. The
template may include any attributes defined for the slot object
(see Slot Object on page 62).
CK_RV SAPI_GetSlotInfo (
CK_SLOT_ID slotId,
CK_ATTRIBUTE_PTR pTemplate,
CK_ULONG ulCount
);
Parameters
slotId
[in] Slot identifier for which information is requested.
pTemplate
[in/out] Pointer to the attributes array that receives the requested
information.
ulCount
[in] Count of attributes in the pTemplate array.
77
78
CHAPTER 4
SAPI_GetTokenInfo
This function returns information about a particular eToken. The
template may contain any attributes defined for the eToken object
(see Token Object on page 63).
CK_RV SAPI_GetTokenInfo (
CK_SLOT_ID slotId,
CK_ULONG ulCount
);
Parameters
slotId
[in] identifier of the slot where the eToken is located
pTemplate
information.
ulCount
SAPI_SetTokenName
This function is used to set the eToken name without reinitializing it. Since it is currently the only function that sets a
eToken property and since this property is available via the
C_GetTokenInfo structure, it does not use the template as a
parameter.
CK_RV SAPI_SetTokenName (
CK_SESSION_HANDLE hSession,
CK_CHAR_PTR label
);
CHAPTER 4
Parameters
hSession
[in] Session handle opened for given eToken.
label
[in] Zero terminated string of the new eToken name that will be
set.
Remarks
The application should pass proper authentication to use this
function. The label is subject to size restriction as defined in
CK_TOKEN_INFO structure (see PKCS#11 specification).
SAPI_InitToken
This function is used to initialize the eToken. eToken attributes
are passed to customize the initialization. The callback function
may be used to report the status of initialization.
CK_RV SAPI_InitToken (
CK_SLOT_ID slotId,
CK_ULONG ulCount,
CK_VOID_PTR pContext,
CK_INIT_CALLBACK_pCallback
);
Parameters
slotId
pTemplate
[in] Pointer to the attributes array that contains the initialization
parameters.
79
80
CHAPTER 4
ulCount
pContext
[in] User provided parameter to be passed to pCallback function.
pCallback
[in] Callback function that lets the application show the progress
of the eToken initialization process.
Remarks
The pCallback parameter is optional (NULL may be passed).
SAPI_FindTokens
This function returns a list of slots containing eTokens that
comply with search criteria. The search criteria may contain any
eToken attributes except those that may be used only for
initialization.
CK_RV SAPI_FindTokens (
CK_SLOT_ID_PTR pSlots,
CK_ULONG_PTR pSlotCount,
CK_ULONG ulCount
);
Parameters
pSlots
[out] Pointer to the array that will be filled by found slot identifiers.
pSlotCount
[in/out] Pointer to the variable that:
• on input defines the size of the pSlots array
• on output receives the actual number of found slots
CHAPTER 4
pTemplate
[in] Pointer to the attributes array containing the parameters of the
requested eTokens.
ulCount
SAPI_LocateToken
This function finds the slot where a particular eToken is located.
CK_RV SAPI_LocateToken (
CK_VOID_PTR unique,
CK_ULONG size,
CK_SLOT_ID_PTR pSlotId
);
Parameters
unique
[in] Pointer to the buffer containing the unique identifier of the
located eToken.
size
[in] Size of the unique buffer.
pSlotId
[out] Pointer to the variable that receives the located eToken’s
slot identifier.
SAPI_UnblockPIN
This function is used to unblock the user PIN (using a challengeresponse mechanism). The eToken should have an SO PIN, but
the SO should not be logged on.
81
82
CHAPTER 4
PKCS#11 has the function C_InitPIN that may be used by the
Security Officer (SO) to unblock the user password. However,
it requires the application to log in firstly with the SO
password. This approach may not be applicable for some
real-world applications when the eToken is located on the
user’s site because the administrator will not be ready to
reveal the SO password to the user.
The function SAPI_UnblockPIN uses a challenge-response
mechanism instead of the password to authenticate the
administrator. The cryptographic challenge is received from
the eToken and passed to the pCallback function provided by
the application. The application has to compute a response in
order to complete authentication to the eToken. The
SAPI_Server_Unblock function may be used for this purpose.
Since this function does not require a eToken presence it may
be performed on the server site.
CK_RV SAPI_UnblockPIN (
CK_CHAR_PTR pNewPin,
CK_ULONG ulNewPinLen,
CK_UNBLOCK_CALLBACK pCallback
);
Parameters
hSession
[in] Session handle opened for the given eToken.
pNewPin
[in] Pointer to the new user PIN.
pNewPinLen
[in] Size of pNewPin.
pCallback
[in] Callback function that is expected to compute the response
for the given challenge.
CHAPTER 4
OTP Functionality
Theoretically a single eToken may support multiple OTP
algorithms and keep more than one OTP object.
This version of SAPI makes following assumptions:
♦ Only one OTP object currently exists on the eToken. Therefore
no special mechanism is proposed to address the particular
OTP object instance on the eToken.
♦ The supported OTP algorithms are counter-based. It is not
mentioned explicitly across the API, but is implied from the set
of attributes defined for the OTP object.
♦ The eToken is properly initialized in order to operate with OTP
(to ensure session handle is used for eToken addressing
rather than slot ID).
SAPI_OTP_GetMechanismList
This function returns a list of available OTP mechanisms.
CK_RV SAPI_OTP_GetMechanismList (
CK_SLOT_ID slotId,
CK_ULONG_PTR pMechanismList,
CK_ULONG_PTR pCount
);
Parameters
slotId
83
84
CHAPTER 4
pMechanismList
[out] Pointer to the array that will be filled by OTP mechanism
identifiers.
pCount
• on input defines the size of the pMechanismList array
• on output receives the actual number of found
mechanisms
SAPI_OTP_GetMechanismInfo
This function returns information about a specific OTP
mechanism.
CK_RV SAPI_OTP_GetMechanismInfo (
CK_SLOT_ID slotId,
CK_ULONG mechanism,
CK_SAPI_OTP_MECHANISM_INFO_PTR pMechanismInfo
);
Parameters
slotId
mechanism
[in] OTP mechanism identifier for which information is requested.
pMechanismInfo
[out] Pointer to the structure that receives the OTP mechanism
information.
CHAPTER 4
SAPI_OTP_Create
This function creates an OTP object. User login should be
performed prior to this operation.
CK_RV SAPI_OTP_Create (
CK_ULONG ulCount
);
Parameters
hSession
pTemplate
created OTP object.
ulCount
Remarks
Mandatory attributes to be provided are
CKA_SAPI_OTP_MECHANISM and CKA_SAPI_OTP_VALUE.
If no specific attribute is provided, then zero will be used as the
default value for these attributes.
85
86
CHAPTER 4
SAPI_OTP_GetAttributeValue
This function returns the characteristics of an existing OTP object.
The key value is sensitive and will not be returned.
CK_RV SAPI_OTP_GetAttributeValue (
CK_ULONG ulCount
);
Parameters
hSession
pTemplate
information.
ulCount
SAPI_OTP_SetAttributeValue
This function is used to change the OTP object parameters. Only
the display duration may be changed, but the function follows the
common logic.
CK_RV SAPI_OTP_SetAttributeValue (
CK_ULONG ulCount
);
CHAPTER 4
Parameters
hSession
pTemplate
[in] Pointer to the attributes array containing the new parameters
of the OTP object.
ulCount
SAPI_OTP_Destroy
This function deletes an existing OTP object. User login should
be performed prior to this operation.
CK_RV SAPI_OTP_Destroy (
CK_SESSION_HANDLE hSession
);
Parameters
hSession
SAPI_OTP_Execute
This function computes an OTP value.
CK_RV SAPI_OTP_Execute (
CK_ULONG mode,
CK_CHAR_PTR pResult,
CK_ULONG_PTR pSize
);
87
88
CHAPTER 4
Parameters
hSession
mode
[in] Execution mode. (See Remarks)
pResult
[out] Pointer to the buffer which receives the executed value.
pSize
• on input defines the size of the pResult array
• on output receives the actual length of the pResult array.
Remarks
♦ Mode CK_OTP_CURRENT returns the last OTP computation
without moving the counter.
♦ Mode CK_OTP_RELEASE operates like CK_OTP_CURRENT.
The application should call the SAPI_OTP_Execute function
with (in) this mode after getting a new OTP value in order to
release the eToken for future OTP operations. See the InitOTP
Sample on page 115 for more details.
♦ Mode CK_OTP_ZERO performs an OTP computation for the
zero-counter. This mode may be used when the eToken and
the server are unsynchronized in order to resynchronize them.
CHAPTER 4
Battery Indication Functionality
All dates that appear in the battery indication functions and
attributes are based on Greenwich Mean Time.
SAPI_BI_Create
This function creates the BI system on the eToken. The user
should be logged on.
CK_RV SAPI_BI_Create (
CK_ULONG ulCount
);
Parameters
hSession
pTemplate
created battery indicator object.
ulCount
Remarks
The following attributes are mandatory:
♦ CKA_SAPI_BI_CONFIG – (ideally it is taken from the old
object, but if the old object is damaged, use the
SAPI_BI_GetConfig function to get it).
♦ CKA_SAPI_BI_CAPACITY – (ideally it is taken from the old
object, but if the old object is damaged, use the
SAPI_BI_GetConfig function to get it).
89
90
CHAPTER 4
♦ CKA_SAPI_BI_ASSEMBLY_DATE
The default values for the remaining attributes are:
♦ CKA_SAPI_BI_VALUE – same as CKA_SAPI_BI_CAPACITY
♦ CKA_SAPI_BI_FIRST_WARN and
CKA_SAPI_BI_SECOND_WARN – 0 (no warning).
♦ CKA_SAPI_BI_RECALIBRATION_DATE – today.
If there is a damaged BI object (i.e. some files exist) it will be
removed as a part of creation.
SAPI_BI_GetAttributeValue
This function returns the required attributes of the battery feature
object.
CK_RV SAPI_BI_GetAttributeValue (
CK_ULONG ulCount
);
Parameters
hSession
pTemplate
information.
ulCount
CHAPTER 4
SAPI_BI_SetAttributeValue
This function changes the BI information on the eToken.
CK_RV SAPI_BI_SetAttributeValue (
CK_ULONG ulCount
);
Parameters
hSession
pTemplate
[in] Pointer to the attributes array containing the new parameters
of the battery indicator object.
ulCount
Remarks
The only attributes that may be set by this function are
CKA_SAPI_BI_FIRST_WARN and
CKA_SAPI_BI_SECOND_WARN.
Some of the attributes are changed internally by the eToken or by
the SAPI_BI_Recalibrate function.
91
92
CHAPTER 4
SAPI_BI_Destroy
This function destroys the BI system on the eToken. The user
should be logged on. It is possible to destroy a partially damaged
object.
CK_RV SAPI_BI_Destroy (
);
Parameters
hSession
SAPI_BI_Recalibrate
This function is used to recalibrate the BI information stored on
the eToken, based on time passed. The function will modify the
current battery capacity (CKA_SAPI_BI_VALUE attribute) as well
as the last recalibration date on the eToken.
CK_RV SAPI_BI_Recalibrate (
CK_DATE* pCurrentDate
);
Parameters
hSession
pCurrentDate
[in] Pointer to the structure containing the current date. If this
parameter is NULL, the current system date will be used.
CHAPTER 4
SAPI_BI_Save
This function saves the current state of the BI object to be
restored later. It is valid to call this function in the absence of the
BI object and to pass the returned buffer to the function
SAPI_BI_Restore at a later stage.
CK_RV SAPI_BI_Save (
CK_VOID_PTR pBuffer,
CK_ULONG_PTR pulSize
);
Parameters
hSession
pBuffer
[out] Pointer to the buffer that receives the battery indicator state.
pulSize
• on input defines the size of pBuffer
• on output receives the actual length of pBuffer
SAPI_BI_Restore
This function restores the BI object. The user should be logged
on. If the object already exists, it will be rewritten.
CK_RV SAPI_BI_Restore (
CK_VOID_PTR pBuffer,
CK_ULONG size
);
93
94
CHAPTER 4
Parameters
hSession
pBuffer
[in] Pointer to the buffer that contains the battery indicator state.
This information was previously received from the SAPI_BI_Save
function.
size
[in] Size of pBuffer.
SAPI_BI_GetConfig
Correct working of the battery indication functionality requires
preliminary knowledge of the initial battery capacity
(CKA_SAPI_BI_CAPACITY) and various eToken-dependent
parameters (encoded together in the CKA_SAPI_BI_CONFIG
attribute).
Normally, this information is stored on the eToken during
production. An application may get this information from the
eToken and use it later (for computations on the server side,
reconstruction of the battery indication information if damaged
and so on).
If for some reason this information is not available (for instance,
the eToken was occasionally re-initialized via the eEToken
Properties utility), the function SAPI_BI_GetConfig provides an
alternate way to obtain this information. The function extracts it
from the externally supplied configuration file based on the exact
eToken model information.
CK_RV SAPI_BI_GetConfig (
CK_CHAR_PTR pInf,
CK_ULONG
ulInfLen,
CK_CHAR_PTR pModel,
CHAPTER 4
CK_ULONG_PTR pCapacity,
CK_VOID_PTR pConfig,
CK_ULONG_PTR pulConfigLen
);
Parameters
pInf
[in] Pointer to the buffer where the configuration file content is
placed.
ulInfLen
[in] Size of pInf buffer.
pModel
[in] Pointer to the character string describing the product model. It
should contain the CKA_SAPI_MODEL attribute as returned from
the SAPI_GetTokenInfo function.
pCapacity
[out] Pointer to the variable that receives the battery capacity
value.
pConfig
[out] Pointer to the buffer that receives battery configuration data.
pulConfigLen
• on input defines the size of pConfig
• on output receives the actual length of pConfig
Remarks
If the configuration file does not contain information about the
particular eToken model in use, the function will fail.
The file is not part of the delivered eToken SDK. Contact the
eToken technical support in order to get the most updated file.
95
96
CHAPTER 4
SAPI_BI_Check
This function checks the validity of the BI object on the eToken.
CK_RV SAPI_BI_Check (
);
Parameters
hSession
Remarks
If the BI object on the eToken is damaged
CKR_DEVICE_ERROR will be returned.
This is the only function that guarantees to return this error code if
the object is damaged. Other functions may access only the
information they require. Therefore if the object is partially
damaged, these functions may succeed or may fail with an
arbitrary error code.
CHAPTER 4
Server Side Functionality
Functions presented in this section may be used on the server,
when no eToken is connected. These functions should work
without eToken RTE installed (but if eToken RTE is installed, its
version should be compatible).
SAPI_Server_OTP_Calculate
This function calculates the OTP value on the server for a given
mechanism, key and counter.
CK_RV_SAPI_Server_OTP_Calculate (
CK_ULONG ulCount,
CK_CHAR_PTR pResult,
CK_ULONG_PTR pSize
);
Parameters
pTemplate
[in] Pointer to the attributes array containing the OTP object
parameters.
ulCount
pResult
[out] Pointer to the buffer which receives the calculated value.
pSize
• on input defines the size of the pResult array
97
98
CHAPTER 4
•
on output receives the actual length of the pResult array.
Remarks
The template should contain the following attributes:
♦ CKA_MECHANISM
♦ CKA_COUNTER
♦ CKA_VALUE
SAPI_Server_BI_EstimateValue
This function estimates the battery state based on information
about eToken usage within a particular time period.
CK_RV SAPI_Server_BI_EstimateValue (
CK_ULONG ulCount,
CK_MECHANISM_TYPE mechanism,
CK_ULONG duration,
CK_ULONG clicks,
CK_DATE* pCurrentDate,
CK_ULONG_PTR pNewValue
);
Parameters
pTemplate
battery indicator object.
ulCount
mechanism
[in] OTP mechanism identifier
CHAPTER 4
duration
[in] Assumed OTP display duration in seconds
clicks
[in] Number of OTP button clicks since
CKA_SAPI_BI_RECALIBRATION_DATE.
pCurrentDate
[in] Pointer to the structure containing the current date. It should
not be earlier than CKA_SAPI_BI_RECALIBRATION_DATE. If
this parameter is NULL, the current system date will be used.
pNewValue
[out] Pointer to the variable that receives the estimated remaining
capacity of the battery in µkA seconds.
Remarks
The template is built from data stored previously on the server
(during eToken enrollment or last recalibration). The following
attributes should be passed:
♦ CKA_SAPI_BI_CAPACITY
♦ CKA_SAPI_BI_VALUE
♦ CKA_SAPI_BI_RECALIBRATION_DATE
♦ CKA_SAPI_BI_CONFIG
Other attributes may be passed but will be ignored.
SAPI_Server_BI_EstimateRetainDays
This function estimates the remaining life time of the battery
based on the battery information, usage and passed time.
CK_RV SAPI_Server_BI_EstimateRetainDays (
CK_DATE *pStartUsageDate,
CK_ULONG StartValue,
99
100
CHAPTER 4
CK_ULONG ulCount,
CK_MECHANISM_TYPE mechanism,
CK_ULONG duration,
CK_ULONG clicks,
CK_DATE *pCurrentDate,
CK_ULONG_PTR pEstimatedDays
);
Parameters
pStartUsageDate
[in] Pointer to the variable that contains the starting usage date of
the eToken battery. See Remarks for more information.
StartValue
[in] The actual battery capacity on the starting usage date in µkA
seconds. See Remarks for more information.
pTemplate
battery indicator object.
ulCount
mechanism
[in] OTP mechanism identifier
duration
[in] Assumed OTP display duration in seconds
clicks
[in] Number of OTP button clicks since
CKA_SAPI_BI_RECALIBRATION_DATE.
pCurrentDate
[in] Pointer to the structure containing the current date. It should
not be earlier than CKA_SAPI_BI_RECALIBRATION_DATE. If
this parameter is NULL, the current system date will be used.
CHAPTER 4
pEstimatedDays
[out] Pointer to the variable that receives the estimated number of
days before the battery expires.
Remarks
The template is built from data stored previously on the server
(during eToken enrollment or last recalibration). The following
attributes should be passed:
♦ CKA_SAPI_BI_CAPACITY
♦ CKA_SAPI_BI_VALUE
♦ CKA_SAPI_BI_RECALIBRATION_DATE
♦ CKA_SAPI_BI_CONIG
♦ CKA_SAPI_BI_ASSEMBLY_DATE
Other attributes may be passed but will be ignored.
pStartUsageDate and StartValue are correspondingly the date
when the eToken was introduced to the system (i.e. passed to the
client for usage) and battery state on the same day. It is assumed
that before this moment the eToken was not in use so only
leakage has occurred (no OTP usage). If NULL is passed as the
pStartUsageDate, default values are used: pStartUsageDate is
taken to equal CKA_SAPI_BI_ASSEMBLY_DATE, and
StartValue is taken to equal CKA_SAPI_BI_CAPACITY.
101
102
CHAPTER 4
SAPI_Server_Unblock
This function computes the proper response for the challengeresponse mechanism used during user PIN unblocking. See
SAPI_UnblockPIN for more information.
CK_RV SAPI_Server_Unblock (
CK_CHAR_PTR pPin,
CK_ULONG ulPinLen,
CK_VOID_PTR pChallenge,
CK_VOID_PTR pResponse
);
Parameters
pPin
[in] Pointer to the Security Officer (SO) PIN string.
ulPinLen
[in] Length of SO PIN.
pChallenge
[in] Pointer to the 8 byte length challenge buffer received from the
eToken.
pResponse
[out] Pointer to the 8 byte length response buffer provided to
unblock the user PIN.
eToken Samples
CHAPTER 5
Chapter 5
eToken Samples
About This Chapter
♦ Overview on page 104
♦ PKCS#11 Samples on page 107
♦ CAPI Samples on page 111
♦ SAPI Samples on page 115
♦ Samples for non-C/C++ Developers on page 118
♦ Other COM Samples on page 120
103
104
CHAPTER 5
Overview
This chapter contains a brief overview of samples provided as
part of the SDK. The samples provided are based on the
questions mostly frequently asked by eToken customers.
The samples are not fully functional applications in all cases.
Certain details, such as error handling, may be omitted for the
sake of brevity.
These samples cover different programming techniques in an
attempt to show the multiple options available to be used. The
result is different samples achieve similar results, but via a
different methodology. For example, one CAPI sample may
demonstrate how to pass the user password from the application
while another one simply allows the eToken CSP to pop up the
password prompt dialog box.
Seal/Unseal Samples
There are several samples – one each for CAPI, PKCS#11 and
Java – that demonstrate how to use eToken for cryptographic
purposes. These samples demonstrate signing and encryption of
a file. Due to the nature of the specific APIs, there are some
differences between the samples, but the common flow is the
same for each one:
¾ For Seal (Protect) operation:
1. Choose the encryption certificate (i.e. recipient’s certificate).
The certificate may or may not be on the eToken. In different
samples there may be different techniques.
2. Choose signing certificate (i.e. certificate of sender). You
should have the corresponding private key.
3. Generate a random symmetric key. The samples use TripleDES encryption in CBC mode.
4. Export the symmetric key, encrypted with the recipient’s RSA
public key. The recipient’s public key is extracted from the
certificate.
eToken Samples
CHAPTER 5
5. Generate a random IV (initialization vector).
6. Encrypt the data with the symmetric key.
7. Hash the data (plain data) and sign the hash with the sender’s
RSA private key.
¾ For Unseal operation:
1. Obtain the sender and receiver certificates from the sealed
file.
2. Use the receiver certificate to find the corresponding private
key on the eToken.
3. Extract the symmetric key that was used to encrypt the data.
This symmetric key was encrypted with the recipient’s RSA
private key.
4. Using the symmetric key and IV, decrypt the data.
5. Hash the plain data and verify the signature using the
sender’s RSA public key, extracted from the sender
certificate.
All the samples use the same file format, so that you can seal a
data file with one sample and unseal it with another one. The
main requirement is the availability of appropriate RSA private
keys and certificates.
The sealed file contains the following information:
♦ Receiver certificate.
♦ Sender certificate.
♦ Initialization vector (IV).
♦ Triple-DES key in the form of a PKCS#1 block encrypted with
the recipient’s certificate.
♦ Data encrypted by the Triple-DES key in CBC mode.
♦ Plain data signature (SHA-1 is used as a hashing algorithm).
The cryptography mechanisms used in the sample are similar to
those used in S/MIME. They are suitable for the protection of a
data file. They may not be suitable for other tasks (such as
authentication, transaction exchange etc.).
105
106
CHAPTER 5
There are many good cryptographic algorithms available in the
world today, but they need to be used properly. Many of the real
world security attacks are the result of improper use of
cryptography rather than the use of weak algorithms. As in many
other situations, certain tasks need the correct algorithm to be
used and other tasks may require a different algorithm to be
used. It is also a good idea to obtain the assistance of a
cryptography expert to ensure that the correct algorithm is being
used.
Some things to be mentioned about cryptographic techniques
used in the Seal/Unseal sample:
♦ The Triple-DES algorithm is used for encryption. It is generally
preferable to use block ciphers (like Triple-DES) rather than
stream ciphers (like RC4). It is not recommended to work with
smaller key sizes than Triple-DES.
♦ It should be noted that when working with block ciphers, the
input and output data sizes may differ.
♦ The IV must be random. There is no need to keep it secret. Do
not use the same IV twice with the same key.
♦ Most cryptographic providers support two hashing algorithms,
MD5 and SHA-1. There are some known weaknesses in SHA1, but it is still considered much safer than MD5. There are
other known algorithms (like SHA-256), but they are not widely
used yet.
♦ Since the input file may be bigger than your memory
limitations, the sample demonstrates how to deal with this
problem (i.e. how to handle the input file by chunks).
eToken Samples
CHAPTER 5
PKCS#11 Samples
This section describes the PKCS#11 samples provided with the
eToken SDK. The samples provided are:
♦ Info Sample, on page 107
♦ InitToken Sample, on page 108
♦ Seal/Unseal Sample, on page 109
The following introductory remarks need to be noted before
attempting to work with these samples:
♦ Aladdin recommends loading the library dynamically.
♦ Do not use hard-coded function names. According to the
standard you should call the function C_GetFunctionList to
reach the addresses of other functions. This is the only
function name that is guaranteed to you.
♦ Some samples may use similar techniques. In this guide, these
techniques are mentioned only once.
♦ In many cryptographic applications you have to deal with
X.509 certificates. X.509 certificate has a pretty complicated
data structure encoded in a very special way (DER-encoding
of ASN.1). There is no simple way for applications to deal with
this data structure. eToken SDK does not provide any special
helper functions for this purpose. However, you may use
Microsoft helper functions described in MSDN. They are, in
fact, used widely across the samples.
Info Sample
This sample prints general information about the PKCS#11 library
and waits for any slot events (i.e. for eToken insertion/removal).
Upon eToken insertion, it prints information about the eToken and
enumerates certificates on this eToken. The sample continues
this operation in an endless loop. It can be stopped by ending the
process. No parameters are passed to this sample.
This sample demonstrates the following techniques:
107
108
CHAPTER 5
♦ Dynamic loading and initialization of the PKCS#11 library (all
other samples follow the same technique) and reaching
addresses of functions via C_GetFunctionList.
♦ Obtaining useful information about the library, slots and
eTokens via functions C_Info, C_GetSlotInfo, C_GetTokenInfo.
♦ Obtaining the supported RSA key size with the function
C_GetMechanismInfo.
♦ Finding objects that satisfy a particular pattern (set of
attributes), the sample show how to find a X.509 certificate
object.
♦ Retrieving object attributes.
♦ Using Microsoft helper functions to extract useful information
from the certificate.
InitToken Sample
Initialization of the eToken is a non-trivial task, since some
important issues (such as the possible need for authentication to
perform it) are intentionally kept out of the scope of the PKCS#11
standard. This sample demonstrates how to initialize the eToken
by using PKCS#11.
The sample has the following command line parameters:
♦ Reader name
♦ eToken formatting password:
• For a non-initialized eToken – use the SO password that is
set after initialization (as described in C_InitToken on
page 35)
• For an eToken initialized with an administrator password –
use the administrator password.
• For an eToken initialized without an administrator
password – use the current user password.
♦ User password to be set after initialization
This sample demonstrates a flow that will not require a UI for any
kind of eToken (not initialized, initialized with/without
administrator password).
eToken Samples
CHAPTER 5
The proposed flow is:
♦ Map the reader name to the slot ID
♦ Open the session with the eToken. eToken RTE will allow
opening the session even with a non-initialized eToken.
♦ Login as the SO with the eToken formatting password.
♦ Close the session. You should close the session since it is
prohibited to perform C_InitToken if at least one session with
the eToken is opened. Your eToken will be logged out, but
eToken RTE will keep the password for a while and it prevents
login UI (for the next step).
♦ Perform C_InitEToken. The same formatting password is
passed as the parameter.
♦ Open a new session.
♦ Login as SO with the formatting password.
♦ Perform C_InitPin to initialize the user password.
♦ Perform C_Logout. Your eToken is initialized now.
♦ In order to demonstrate successful eToken initialization, the
sample then logs in as the user and generates an RSA key
pair.
Note
Treatment of the C_InitToken parameter varies between versions of
PKCS#11. Later versions (v2.11, v2.20) define it as:
For an empty eToken
New SO password
For already initialized eToken
Current SO password
Such a definition is much more useful. When future versions of the
eToken RTE will support later versions of PKCS#11, this approach will
be applied.
Seal/Unseal Sample
The Seal/Unseal sample was described previously (See page
104 for details). Only specifics of PKCS#11 implementation of this
sample are detailed here:
♦ The function gets the following parameters:
• Operation (seal or unseal).
109
110
CHAPTER 5
•
•
•
Password.
Input file.
Output file.
♦ No reader name is passed. The sample uses the first eToken it
finds.
♦ Recipient certificate is selected from one of the certificates
located on the eToken. Generally speaking, applications
usually do not work this way: your eToken contains your
objects (keys, certificates etc.), not recipients’ certificates. The
real location of the recipient certificate is application
dependent.
♦ The sample adds an algorithm ID to the hash value before
signature computation or verification. This could be avoided by
choosing another mechanism (CKM_SHA1_RSA_PKCS
instead of CKM_RSA_PKCS), but this mechanism is currently
not supported by eToken RTE.
♦ In the Seal operation, both recipient and sender certificates are
searched for on the eToken.
♦ In the UnSeal operation, both certificates read from the seal
output file.
eToken Samples
CHAPTER 5
CAPI Samples
This section describes the CAPI samples provided with the
♦ CreateSelfCertificate Sample on page 111
♦ EnumTokens Sample on page 112
♦ Seal/Unseal Sample on page 113
♦ ImportPFX Sample on page 114
CreateSelfCertificate Sample
This sample demonstrates how to create self-signed certificates
on the eToken.
It must be remembered that the created certificate is NOT signed
by any CA certificate and therefore will not be accepted by most
real-world applications.
The sample passes user password, reader name and key
container name to prevent any GUI appearing.
The sample has the following two command line parameters:
♦ Reader name
♦ Password
In addition, the sample demonstrates how to work via CAPI with a
particular eToken and how to pass a password to the eToken via
CAPI.
111
112
CHAPTER 5
EnumTokens Sample
This sample demonstrates two important techniques:
1. How to pass over all currently inserted eTokens.
Since CAPI initially was not invented to work with physical
devices, there is no way to enumerate available eTokens in
CAPI. But by combining CAPI with functions of Smartcard
Resource Manager functions, this can be achieved.
2. How to enumerate certificates located on the eToken.
If the application makes some decisions based on the presence
of a particular certificate on the eToken, this cannot be
performed via the Certificate Store API for several reasons:
• In Propagation mode (default mode), certificates are
copied from the eTokens to the computer. Therefore, after
eToken removal, these certificates are still visible. There is
no security problem though since the RSA private key
becomes unavailable, but it may affect the application
logic.
• Normally, the certificate store does not keep two copies of
the same certificate. Therefore, even in Token View mode,
if there was a particular certificate on the computer, from
the certificate store’s point of view nothing will change
when the eToken is inserted. For the same reason it is
impossible to reveal the situation when you have 2
eTokens inserted with the same certificate.
The sample does the following:
♦ Gets a list of currently inserted smartcards
♦ For each card/token handled by eToken Base Cryptographic
Provider:
• Selects the corresponding eToken as the current one.
• Enumerates all containers on the selected eToken.
• For each container attempts to obtain the certificate for
both AT_KEYEXCHANGE and AT_SIGNATURE keys.
eToken Samples
CHAPTER 5
Seal/Unseal Sample
The Seal/Unseal sample was described previously (See page
104 for details). Only specifics about CAPI implementation of this
sample are detailed here:
♦ No token selection (i.e. reader name) or password is passed.
Therefore, an eToken RTE pop-up window may appear if more
than one eToken is currently inserted. If the application needs
to eliminate any additional GUI, it may adopt the proper logic of
choosing a eToken and passing the password from other
samples. For instance, enumeration of eTokens is
demonstrated in the EnumTokens sample (page 112) and
passing the password via CAPI is demonstrated in the
CreateSelfCertificate sample (page 111).
♦ In order to select a recipient certificate, the program
enumerates certificates in the certificate store. This is because,
in the general case, recipients’ certificates are not located on
the user eToken.
♦ The sample uses the Personal Store of the current user. This
is not totally applicable for a real application since certificates
for other people are usually located in a different store.
Nonetheless, this shortcut simplifies use of this sample.
♦ In order to select a sender certificate, the program enumerates
certificates on the eToken. In this manner, both techniques are
demonstrated.
♦ CAPI uses a low-endian format for some data types (such as
an encrypted symmetric key or a digital signature). It is not a
standard in the PKI world, but rather is CAPI specific. If the
interoperability is not required by the application, it can be
ignored. Otherwise you will have to reverse the byte order in
these data types. The sample reverses them to demonstrate
interoperability with the corresponding PKCS#11 and Java
samples.
The sample has the following command-line parameters:
♦ Operation (seal/unseal)
♦ Input file
♦ Output file
113
114
CHAPTER 5
ImportPFX Sample
This sample demonstrates how to import a certificate from a PFX
file to an eToken. It performs the following operations:
♦ Imports a PFX BLOB and returns the handle of a temporary
store that contains certificates from the PFX file.
♦ Enumerates certificates in the store until the end of the store is
reached or a certificate corresponding to the RSA private key
from the PFX file is found.
♦ Certificates that do not have the
CERT_KEY_PROV_INFO_PROP_ID property (i.e. CA
certificates) are not imported to the eToken.
♦ Exports the RSA key pair from a CSP.
♦ Imports a wrapped key pair blob to the eToken CSP.
♦ Stores the certificate on the eToken by using the
CryptSetKeyParam function.
♦ Deletes RSA keys from Microsoft CSP.
♦ Input PFX file
♦ PFX password
eToken Samples
CHAPTER 5
SAPI Samples
This section describes the SAPI samples provided with the
♦ TokenInfo Sample, on page 115
♦ InitToken Sample on page 115
♦ InitOTP Sample on page 115
♦ Battery Estimation Sample on page 116
♦ FixBattery Sample on page 117
TokenInfo Sample
This sample demonstrates how to use SAPI to obtain more
detailed information about a particular eToken device.
Note:
This and other samples use dynamic loading of eTSAPI.DLL.
InitToken Sample
This sample demonstrates how to initialize the eToken using
SAPI.
InitOTP Sample
This sample demonstrates the OTP functionality of the eToken. It
is assumed that eToken has OTP capabilities (currently only the
eToken NG OTP) and that the eToken firmware supports the
OTP calculation in the online mode (i.e. when the eToken is
connected). This information is received from the
SAPI_OTP_GetMechanismInfo function.
The sample:
♦ opens the session with the eToken
♦ logs in the user (it is necessary to create an OTP object)
115
116
CHAPTER 5
♦ destroys old OTP objects (if any)
♦ creates a new OTP object (In a real application, the same key
should be stored on the server as well);
♦ demonstrates an online OTP calculation (it is rarely used in
real applications);
♦ demonstrates a server-side calculation;
Battery Estimation Sample
This sample demonstrates how the server application estimates
the lifetime of the eToken’s battery. A real application will be
much more complicated and should include careful management
of eTokens.
The sample is based on the use of the single function
SAPI_Server_BI_EstimateRetainDays.It is important to pass the
parameters properly. In the real application:
♦ Attributes CKA_SAPI_BI_CONFIG,
CKA_SAPI_BI_ASSEMBLY_DATE and
CKA_SAPI_BI_CAPACITY have to be taken from the eToken
during eToken enrollment and stored on the server on a pertoken basis. Note that CKA_SAPI_BI_CONFIG may change as
a result of a FW upgrade.
♦ Attributes CKA_SAPI_BI_RECALIBRATION_DATE and
CKA_SAPI_BI_VALUE should be kept up-to-date during the
eToken recalibration process.
♦ The function computes the battery lifetime based on some
hard coded parameters. A real application should pass the
number of OTP usages since the last recalibration.
♦ In reality, the eToken may be unused for some time before it is
introduced to the system. If this idle time is of a significant
length, it should be taken into account by passing pStartDate.
♦ The function demonstrates a computation for a particular date.
A real application will rather use the current date.
eToken Samples
CHAPTER 5
FixBattery Sample
This sample demonstrates how to fix the battery indication
system. eTokens that support battery indication are usually
shipped with correctly initialized information. However, this
information could be damaged for example, if the user
occasionally initialized the eToken. Note that the precision of
future calculations will be ultimately defined by the application’s
knowledge of the current battery status.
So, if the application has some information about the remaining
battery capacity (for instance from recalibration information stored
on the server or as some kind of estimation done on the server),
CKA_SAPI_BI_VALUE may be passed.
Similarly, if the eToken was already enrolled in the system, the
server should have CKA_SAPI_BI_CONFIG stored. This value
should be used.
The sample demonstrates what to do if such information was not
preserved (i.e. eToken was not enrolled yet), but this is
considered a less preferable option. Note also that the .INF-file
supplied with this sample is for demonstration purposes only and
does not necessarily represent the characteristics of real
eTokens.
Contact Aladdin if you need real information in your applications.
117
118
CHAPTER 5
Samples for non-C/C++
Developers
This group of samples shows how to use an eToken when
programming in non-C/C++ environments and include:
♦ Using CAPI from .NET on page 118
♦ Using PKCS#11 from .NET on page 119
♦ Java Seal/Unseal Sample on page 119
Using CAPI from .NET
The .NET Framework contains some classes that allow for the
performance of cryptographic operations using a particular CAPI
provider (See MSDN for appropriate samples). If the supplied
functionality is not sufficient enough for the application (for
instance, you cannot pass the user password from the
application) it is possible to call CAPI functions directly from the
.NET application by using the PInvoke function.
This C# sample demonstrates how to do this. A full description of
PInvoke mechanisms is outside the scope of this guide (refer to
MSDN for more information). However, there are several issues
that need to be mentioned:
♦ When working with unmanaged resources (such as a context
handle) it is the responsibility of the application to release
these resources.
♦ When using functions that may serve several needs and have
different parameter types as a result of it (such as
CryptGetProvParam) it may be preferable to define several
extern functions that will map to the same CAPI function but
use different parameter marshalling.
♦ Some CAPI functions operate with UNICODE strings, while
others require ASCII strings. The CharSet attribute can control
the correct conversion process.
eToken Samples
CHAPTER 5
Using PKCS#11 from .NET
This sample demonstrates how to use PKCS#11 from a .NET
application. Due to the fact that the interface of many PKCS#11
functions is hard to define via PInvoke, we recommend to write a
C++ helper class that will wrap the PKCS#11 functionality
relevant to your application. If this helper class is written in
managed C++, the application may use it from other .NET
languages (such as C#).
Java Seal/Unseal Sample
This sample demonstrates how to use PKCS#11 from a Java
application.
The Seal/Unseal sample was described previously. Only specifics
about Java implementation of this sample are detailed here:
♦ As in the C++ sample for PKCS#11, both sender and recipient
certificates are taken from the token.
♦ Most of the cryptographic details are hidden by the JSSE Sun
provider.
♦ Even though the eToken PKCS#11 provider does not support
the CKM_SHA1_RSA_PKCS mechanism, there is no need to
concatenate the hashing algorithm ID with the hash value
manually: The Sun provider is sophisticated enough to
examine the supported mechanisms and to use them properly.
♦ Operation (seal/unseal)
♦ Password
♦ Source file
♦ Destination file
119
120
CHAPTER 5
Other COM Samples
This section describes the other COM samples provided with the
♦ TokenList COM Object Sample on page 120
♦ eTCapiCom VB Sample on page 122
♦ UseCapiFunc VB Sample on page 122
♦ VBScript/JScript Sample on page 122
♦ WebDemo Sample on page 123.
TokenList COM Object Sample
TokenList is sample code of a simple com object project. This
code gets information and notification from the Microsoft
Resource Manager.
After compiling and registering the COM object, the user can
obtain a list of present tokens/cards and has the option to wait on
the remove token/card event for a specific reader.
The object includes the ITokenSnapshotEvents and the
ITokenSnapshot interfaces.
TokenList: ITokenSnapshotEvents
cardRemoved
HRESULT cardRemoved([in] BSTR readerName);
By implementing this function, you can receive an event fire when
the token is removed from the specified reader.
eToken Samples
CHAPTER 5
TokenList Class: ITokenSnapshot
getReadersList
HRESULT getReadersList([out,retval] VARIANT* pReadersList);
This function returns a list of readers with the connected
token/card using the pReadersList VARIANT variable as a BSTR
safe array.
getCardInReader
HRESULT getCardInReader([in] BSTR readerName, [out,retval]
BSTR* pCardName);
This function uses the given reader name to return the card
name/type that is inserted into that specific reader.
startWaitOnRemove
HRESULT startWaitOnRemove([in] BSTR readerName);
By calling this function and implementing the cardRemoved event
function, you can get an event when a token/card is removed
from a specific reader.
The function implementation uses an internal thread that waits for
a Smartcard Resource Manager “remove card” status change in
the specific reader. The thread ends when the token is removed.
121
122
CHAPTER 5
eTCapiCom VB Sample
CapiCom version 2.0.0.3 is installed and registered by the
eToken RTE msi.
This sample demonstrates how to enumerate certificates with a
CapiCom certificate object and filter them by provider name and
existence of private key (which means the eToken is connected).
After getting the certificate, there are options to Sign/Verify and
Encrypt/Decrypt a text message.
Note:
To work with Capicom functions, the certificate has to be trusted by
a CA certificate. Please ensure that the selected certificate status is
valid.
UseCapiFunc VB Sample
To use this sample, it is necessary to compile and register the
TokenList object first.
This sample demonstrates the use of the CAPI function from VB
by trying to find a smartcard key container certificate
(SmartCardKC) on the eToken.
♦ Use TokenSnapshot class to getReaderList (variant array).
♦ For each reader name in the list, try to GetSCardKCCert by
calling the CAPI function.
♦ Key Container with SmartCardKC includes a certificate for
SmartCard Logon.
♦ WaitOnRemove for each reader where the eToken is present.
VBScript/JScript Sample
The sample demonstrates the use of the TokenList Com object to
enumerate a reader list for a connected eToken/Card. The
sample provided comes in two script languages:
♦ VBScript - VBS_ListReader.htm
♦ JScript - J_ListReader.htm
eToken Samples
CHAPTER 5
WebDemo Sample
The sample demonstrates how to install and use eToken RTE
over the web.
The WebDemo cab project allows the user to create a .cab file
that can be downloaded from a Web server to a Web browser.
The browser extracts this cab file, uses the .inf file and installs the
eToken RTE that is written as a system hook instruction.
Create and Sign CAB file
The Cab file must include the following files:
♦ RTE_3.60.ini – The file includes the URL for the eToken RTE
msi installation file. This URL can be changed if desired.
♦ RTE_3_60.inf –Internet Explorer parses this file when the cab
is downloaded and extracted. It then runs the system hook
instruction. This instruction can be changed if desired.
♦ RTE_3.60.exe – The setup file that uses the .ini file to
download and run the RTE over the web.
♦ TokenList.dll – com object to verify if the eToken is present.
To get this file, first compile the TokenList com object sample.
Note:
Cabarc.exe and Signcode.exe are Microsoft SDK tools.
The call to Cabarc is shown below as a command line example:
Cabarc.exe -s 6144 N RTE_3_60.cab /
TokenList.dll /
RTE_3.60.exe /
RTE_3.60.ini /
RTE_3_60.inf
123
124
CHAPTER 5
After generating the CAB file, it must be signed with a valid
certificate. The Signcode.exe can be used either as a GUI
application (See Microsoft documentation) or as a command line
operation as shown in the example below:
SignCode.exe -spc mycredentials.spc -v myprivatekey.pvk /
-t http://timestamp.verisign.com/scripts/timstamp.dll
RTE_3_60.cab
Note:
In this example, you need to use your own *.spc and *.pvk certificate
files.
Important Html files
These files show how to deploy and use the eToken RTE over
the web.
♦ CheckRTE.html – manages the RTE version by using the
eTverifer object.
(eTverifer is an RTE component that has been shipped since
RTE 3.52.)
By checking the component version, the CheckRTE.html page
decides whether to download the cab file or not.
♦ CheckToken.html – this page uses the Tokenlist com object
that is packaged inside the cab file, and verifies if a eToken is
inserted.
♦ SearchCert.html – uses Capicom (registered by the RTE
installation) to view certificates on the eToken.
eToken Explorer
CHAPTER 6
Chapter 6
eToken Explorer
About This Chapter
♦ Overview on page 126
♦ The eToken Explorer on page 127
♦ Managing PKCS#11 Objects on page 134
125
126
CHAPTER 6
Overview
PKCS#11 is a standard for public key cryptography API that has
two main functions:
a) Storage of cryptographic and simple data objects
b) Use of these objects for encryption, signatures and other
cryptographic functions.
eToken Explorer is a tool that works with these stored objects. It
helps generate objects such as keys and certificates, stores them
and reads them from an eToken (i.e. export and import).
eToken Explorer does not use these objects for any
cryptographic purposes. It is a tool that only deals with storage
tasks.
eToken Explorer manages PKCS#11 objects and can generate,
delete, import and export these objects from/to specified files.
The content of objects can be viewed and edited (where
appropriate). Each object has a set of attributes and these can be
modified (edited and / or updated) by the user through eToken
Explorer. It also automatically tracks insertions and removals of
the eToken and shows the cryptographic objects of each eToken
inserted.
eToken Explorer
CHAPTER 6
The eToken Explorer Main Window
The eToken Explorer window consists of two separate boxes:
♦ Upper – Tokens and Objects window
♦ Lower – Details window
The eToken Explorer dialog box without an eToken is displayed:
The Tokens and Objects window provides information on the
slots and any objects on the inserted eToken.
The Details window shows details of the selected item that
appears in the Tokens and Objects window.
If the slot is empty, the Details window shows slot properties only.
If the selected item is an eToken, the Details window shows slot
and token details as displayed:
127
128
CHAPTER 6
If the selected item is an eToken’s object (a data object, a key or
a certificate), the Details window shows the object’s properties as
displayed:
Certificate Object
eToken Explorer
CHAPTER 6
Data Object
Note:
All PUBLIC objects can be seen even when the user is not logged in
to the eToken.
However PRIVATE objects can only be seen when the user is logged
into the eToken.
129
130
CHAPTER 6
The Tokens and Objects Window
The Tokens and Objects Window is divided into four columns as
detailed:
a) Slot/Object
b) Handle
c) Name
d) Modifiable.
Title
Slot/Object
Description
Slot: Slot name
Object: Object Class:
1.
2.
3.
4.
5.
Data
Certificate
Public Key
Private Key
Secret Key
Handle
Provided for Objects only.
It is the unique identifier for the object (used by
programmer) as defined in the PKCS#11
standard.
Name
For Slot: Slot name
For Token: Token Name
For Object: The CKA_LABEL attribute value
Modifiable
For Objects only.
The CKA_Modifiable attribute value
eToken Explorer
CHAPTER 6
The Details Window
The details window provides information on the selected object
from the Tokens and Objects window. These are:
♦ Slot Properties
♦ Token Properties
♦ Object Properties
Slot Properties
The slot properties provide information on the SMARTCARD
READER (or “SLOT” in PKCS#11 terms). These are:
♦ Slot Description
♦ Manufacturer ID
♦ Flags
♦ Hardware version
♦ Firmware version
Token Properties
The token properties provide details on all aspects of the eToken
and consist of three categories:
♦ Slot Properties (as above)
♦ Token Properties which provides information on the eToken
itself
♦ Token Mechanisms (CKM_xxx).
The token mechanism names are defined in the PKCS#11
standard and detail a list of cryptographic mechanisms provided
by the eToken. For each mechanism, the value shows three
parameters:
• Minimum key size (MinKeySize)
• Maximum key size (MaxKeySize)
• Additional options as defined in the standard (Flags)
131
132
CHAPTER 6
Object Properties
When selected, each object displays all the properties associated
with it. Double clicking on the property allows users to view and
(in some cases) to modify the attributes.
Modifying Attributes
Under certain conditions, the attributes cannot be modified.
These are:
a) The user is not logged in.
b) The selected object itself is not modifiable. As a result none
of its attributes can be modified by the user.
c) The selected attribute has been specified by PKCS#11 as not
modifiable, e.g. CKA_CLASS.
There are three types of attributes supported in eToken Explorer.
Each type can be modified in its specific dialog box.
¾ To modify an attribute
1. Double-click the attribute and the Edit Attribute dialog box
opens.
For a Boolean attribute:
Users can change the value for TRUE or FALSE only.
eToken Explorer
CHAPTER 6
For a date attribute:
Users can enter the day, month and year information only.
For all other attributes:
All remaining attributes include both Hexadecimal and ASCII
forms for the attribute value and the user has full editing
functionality including cutting/pasting and changing.
133
134
CHAPTER 6
Managing PKCS#11 Objects
eToken Explorer allows the user to manage PKCS#11 objects by
generating, deleting, importing and exporting these objects
from/to specified files.
From the File menu, select the required item from the dropdown
menu as displayed:
New Data Object
A new data object can be created by the user. This object is used
as a container for storing any data on the eToken. As any
PKCS#11 object, this one can be either private or public.
¾ To create a new data object:
1. From the File menu, select New Data Object... and the
following dialog box opens.
2. Select True if the object is to be private or False if it is to be
public.
3. Click OK to close the dialog box. The new object appears in
the Tokens and Objects window.
eToken Explorer
CHAPTER 6
Generate
Users can generate certain types of keys and certificates.
The Key parameters allow the user to set the Type - RSA, DES
or DES-3.
For DES and DES-3 type keys, eToken Explorer generates one
secret key object of the class CKO_SECRET_KEY.
If RSA is selected, the Size can also be set - 512 bits, 1024 bits
or 2048 bits (if the eToken supports this RSA key size). In this
case an RSA key pair is generated. These objects are of the
class CKO_PUBLIC_KEY and CKO_PRIVATE_KEY.
Additionally a corresponding self-signed certificate can be created
for an RSA key pair.
The Certificate parameters enable the user to create a self
signed certificate, name it and determine its period of validity.
¾ To generate a PKCS#11 key/key pair and certificate:
1. From the File menu, select Generate... and the following
dialog box opens
2. In the Key parameters section, select the Type and for RSA
keys the Size.
3. For an RSA key pair, the user has the option to create a
certificate in the Certificate parameters section. Select the
Create a self-signed certificate option and complete the
other parameters if the certificate is required.
135
136
CHAPTER 6
4. Click OK and the requested object(s) is generated.
5. On completion, a confirmation message is displayed:
6. Click OK to export the object or Cancel to keep the object
without exporting it.
For information on exporting certificates, see Export and Import
below.
Export and Import
Various data objects can be exported and imported through
eToken Explorer. The objects and their file types are detailed in
Table 6-1.
Table 6-1: Exported File Types
Object Type
File Formats
Secret Key
.ini
.blo
Public Key
.ini
.blo
Private Key
.ini
.blo
Certificate
.ini
Data Object
.ini
.cer
.pfx/.p12
.bin
Supported File Formats:
♦ Object description file
*.ini
♦ Microsoft BLOB format
*.blo
♦ DER Encoded Binary X.509
*.cer
♦ PKCS#12
*.pfx or *.p12
♦ Binary Unformatted data
*.bin
eToken Explorer
CHAPTER 6
Before the first logout after private keys and certificates have
been generated, an asterisk is seen next to these objects. This
means the object can be exported in any file format as per Table
6-1. It should be remembered that, in reality, the RSA private
keys cannot be physically exported from the eToken itself.
However, eToken Explorer can export the cached key(s) until a
Refresh/Logout/Token removal occurs.
After a Refresh or Logout and reinsertion of the eToken, the
asterisk no longer appears.
In this case for a Private Key only the matching public key can
be exported and the following dialog box opens:
In this case a Certificate can only be exported in either .ini or .cer
format.
¾ To export an object to a file:
1. From the Tools menu, click Export and select where the
exported file is to be saved.
2. The Save As dialog box opens and the object can be saved
in one of the formats from Table 6-1
3. If the *.pfx or *.p12 format is selected, the Certificate Export
dialog box opens as displayed:
137
138
CHAPTER 6
4. If desired the user may enter a password to increase security
of the private key on future usage occasions. Click OK and
the file is saved.
5. A confirmation message that the export was successful is
displayed:
¾ To import a file to the eToken:
1. From the Tools menu, click Import.
If you want to import a specific data object value attribute,
select the data object and then click Import. A dialog box
opens:
Clicking YES updates the current data object with information
from the file and overwrites all previous data on the object.
Clicking NO creates a new data object and copies the
information from the file.
2. The Open dialog box opens. Select the file to be imported
and click Open.
If a .pfx/p12 file is selected for import, the Certificate Import
dialog box opens as displayed:
eToken Explorer
CHAPTER 6
Enter the password for the certificate and click OK.
3. The Import is successful and a confirmation message is
displayed:
139
140
CHAPTER 6
eToken Explorer Other Functions
A number of different eToken related functions can be performed
from eToken Explorer. These include logging in and out,
changing the password and refreshing as well as confirming the
library information for eToken Explorer.
From the Tools menu, select the required item from the
dropdown menu as displayed:
Login and Logout
Before being able to manipulate data etc. on an eToken, the user
must first log in to the eToken.
Click Login and the PKCS#11 Login dialog box is displayed:
Enter the eToken password and click OK. The user is logged in
and the menu items and icons are enabled.
Logout is performed by one of the following:
• Removing the eToken
• Clicking Logout
• Using the Refresh function
eToken Explorer
CHAPTER 6
Change Password
The eToken password can be changed from within eToken
Explorer.
¾ To change the eToken password:
1. On the Tools menu, click Change Password... and the
Change PKCS#11 Password dialog box opens:
2. Enter the Current eToken password, the New eToken
password, confirm it and click OK. The eToken password is
changed.
Refresh
Actions are performed on the eToken from different applications.
These actions and subsequent changes on the eToken are not
automatically visible by eToken Explorer. In order to see these
changes, the Refresh functions needs to be used.
The Refesh function updates eToken Explorer with any changes
made including removing the asterisk from newly generated keys
and certificates.
The Refresh function also automatically logs the user out of the
eToken. To see private data on the eToken, the user must log in
again.
141
142
CHAPTER 6
Library Information
The Library Information details information about the PKCS#11
version as displayed:
Appendix
CHAPTER 7
Chapter 7
Appendix
About This Appendix
This appendix describes the SDK 3.60 installation.
143
144
CHAPTER 7
eToken SDK Installation
The eToken SDK 3.60 uses a single MSI package
(SDK_3.60.msi) to install the entire SDK.
The eToken SDK 3.60 includes the necessary files to develop
eToken applications. The installation procedure creates a
subdirectory for the SDK components (Documentation, Include
file, Redistribution, Samples and Tools) and copies them into the
subdirectory.
After the installation, the eToken SDK appears in the Control
Panel Add/Remove Programs applet.
Note:
Unless you specify otherwise the files are installed in the directory
\Program Files\Aladdin\eToken\SDK.
¾ To install the eToken SDK 3.60:
1. Double-click the SDK_3.60.msi file. The eToken SDK 3.60
Setup Wizard is displayed:
Note:
Once the installation is completed, double-click the SDK_3.60.msi file
to modify, repair or remove the installation of the SDK 3.60.
Appendix
CHAPTER 7
2. Click Next. The License Agreement is displayed:
3. Read the license agreement, select I accept....and click Next.
The Select Installation Type window is displayed:
4. Select a Typical or Custom installation and click Next.
The Typical installation includes all SDK components by
default. If a component is not required (See Table 2-1:
eToken SDK 3.60 Contents on page 13), then select Custom
installation.
145
146
CHAPTER 7
5. If a Typical installation is selected, proceed to Step 7.
If a Custom installation is selected, the Select Features
window is displayed:
6. Select the component(s) to be disabled by right-clicking it and
selecting the disable option.
7. Click Next and the Ready to Install window is displayed:
8. Click Next. The Updating System window is displayed while
new files are copied onto the system.
Appendix
CHAPTER 7
9. When the installation process is complete, the eToken SDK
3.60 successfully installed window is displayed:
10. Click Finish to exit the installation.
147

eToken Software Developer`s Guide

Transcription

Similar documents

Log on to www.onlinesbi.com

NorthCenter Food Expo - PERFORMANCE Foodservice

5th September 2013

vTuner Internet Radio Rapid Prototyping SDK USB

Directions - Jericho School District

Monarch - User Forum 2016

Complete Details - Shrewsbury High School Alumni Association

STS APP GUIDE – IOS DEVICE