Developer’s Guide - pudn.comread.pudn.com/downloads128/ebook/549477/eToken_SDK_3_50[1].pdf ·...

Developer’sGuide

Version 3.50

December 2003

i

Contact Information

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

Websitehttp://www.ealaddin.com/etoken

Country / Region Support Email TelephoneUSA [email protected] 1-212-329-6658

1-800-223-4277

EUROPE: Austria, Belgium, France, Germany, Netherlands, Switzerland, UK

[email protected] 0800-22523346

Ireland [email protected] 0011800-22523346

Rest of the World [email protected] +972-3-6362266 ext 2

Table of ContentsChapter 1 - Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Structure of this Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2eToken SDK for Windows Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Using the SDK. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7eToken Software Developer’s Kit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Chapter 2 - Developing Applications for eToken . . . . . . . 13Important Notice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Recommendations for eToken Programming. . . . . . . . . . . . . . . . . . . . . . . . . . 15PKCS #11. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16CAPI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Using eToken.dll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28eToken API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31eTocx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Chapter 3 - eToken API Reference . . . . . . . . . . . . . . . . . . . . . . . 65General API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Talker Functions API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Reader List and Listener Functions API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80eToken R2 APDU Functions API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91eToken CardOS/M4 APDU Functions API . . . . . . . . . . . . . . . . . . . . . . . . . . 114High Level Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186eToken R2 High Level General Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . 187eToken R2 High Level File System Functions API . . . . . . . . . . . . . . . . . . . . 204eToken R2 High Level Encryption Storage Functions API . . . . . . . . . . . . . 225eToken CardOS/M4 High Level General Functions API . . . . . . . . . . . . . . . 234eToken CardOS/M4 High Level File System Functions API . . . . . . . . . . . . 248eToken CardOS/M4 High Level RSA Keys Functions API . . . . . . . . . . . . . . 270eToken CardOS/M4 High Level DES Keys Functions API. . . . . . . . . . . . . . 282eToken CardOS/M4 High Level Certificate Functions . . . . . . . . . . . . . . . . . 290eToken Error Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300

iii

Chapter 4 - eToken eTocx API Reference . . . . . . . . . . . . . . 305eTocx Enumerators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306eTocx Interfaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308eTocx Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324

Chapter 5 - Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327eToken APDU Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328eToken Application Aid (eTAID) Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347CAPI Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352PKCS #11 Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353eTocx Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354

Appendix A - eToken Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355Using the eToken Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356Using the eToken Editor with eToken R2 . . . . . . . . . . . . . . . . . . . . . . . . . . . 361Using the eToken Editor with eToken CardOS/M4. . . . . . . . . . . . . . . . . . . . 366

Appendix B - eToken Cryptoki Viewer . . . . . . . . . . . . . . . . . . . . . . . . . . 373Using the eToken Cryptoki Viewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374

Appendix C - eToken Capi Viewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379Using the eToken Capi Viewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380

Appendix D - Redistributing eToken Applications . . . . . . . . . . . . . . . . 383Redistributing Applications for eToken . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384

Appendix E - eToken SDK Installation . . . . . . . . . . . . . . . . . . . . . . . . . . 389Installing the eToken SDK Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389

Appendix F - Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397

iv

COPYRIGHTS AND TRADEMARKS

The eTokenTM system and its documentation are copyrighted (C) 1985 to present, by Aladdin Knowledge Systems Ltd.

All rights reserved.eTokenTM 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 toAladdin Knowledge Systems Ltd. (hereinafter "Aladdin"). All intellectual property rights(including, without limitation, copyrights, trade secrets, trademarks, etc.) evidenced by orembodied in and/or attached/connected/related to this manual, information contained hereinand the Product, are and shall be owned solely by Aladdin. Aladdin does not convey to you aninterest in or to the this manual, information contained herein and the Product, but only alimited right of use. Any unauthorized use, disclosure or reproduction is a violation of thelicenses 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 ANDDISTRIBUTORS SHALL BE OBLIGATED IN ANY MANNER IN RESPECT OF BODILYINJURY AND/OR PROPERTY DAMAGE ARISING FROM THIS PRODUCT OR THE USETHEREOF. EXCEPT AS STATED IN THE eToken DEVELOPER'S LICENSE AGREEMENT,THERE ARE NO OTHER WARRANTIES, EXPRESSED OR IMPLIED, REGARDINGALADDIN'S PRODUCTS, INCLUDING BUT NOT LIMITED TO, THE IMPLIEDWARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.The product must be used and maintained in strict compliance with instructions and safetyprecautions contained herein, in all supplements hereto and according to all terms of itsDeveloper's License Agreement. This product must not be modified or changed without thewritten permission of the copyright holder.All attempts have been made to make the information in this document complete andaccurate. Aladdin is not responsible for any direct or indirect damages or loss of businessresulting from inaccuracies or omissions. The specifications in this document are subject tochange without notice.

v

ALADDIN KNOWLEDGE SYSTEMS LTD.

DEVELOPER'S LICENSE AGREEMENT

IMPORTANT INFORMATION - PLEASE READ THIS AGREEMENT CAREFULLY BEFOREOPENING THE PACKAGE AND/OR USING THE CONTENTS THEREOF AND/OR BEFOREDOWNLOADING OR INSTALLING THE SOFTWARE PROGRAM. ALL ORDERS FOR AND USEOF THE ETOKEN PRODUCTS (including without limitation, the Developer’s Kit, libraries,utilities, diskettes, CD_ROM, eTokenTM 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 TERMSAND CONDITIONS SET FORTH IN THIS AGREEMENT. BY OPENING THE PACKAGECONTAINING THE PRODUCTS AND/OR BY DOWNLOADING THE SOFTWARE (as definedhereunder) AND/OR BY INSTALLING THE SOFTWARE ON YOUR COMPUTER AND/OR BYUSING THE PRODUCT, YOU ARE ACCEPTING THIS AGREEMENT AND AGREEING TO BEBOUND BY ITS TERMS AND CONDITIONS.

IF YOU DO NOT AGREE TO THIS AGREEMENT DO NOT OPEN THE PACKAGE AND/ORDOWNLOAD AND/OR INSTALL THE SOFTWARE AND PROMPTLY (at least within 7 daysfrom the date you received this package) RETURN THE PRODUCTS TO ALADDIN, ERASETHE SOFTWARE, AND ANY PART THEREOF, FROM YOUR COMPUTER AND DO NOTUSE IT IN ANY MANNER WHATSOEVER.

1. Title & Ownership.THIS IS A LICENSE AGREEMENT AND NOT AN AGREEMENT FOR SALE. The softwarecomponent of Aladdin’s eToken Software Development Kit, including any revisions, corrections,modifications, enhancements, updates and/or upgrades thereto, (hereinafter in whole or any partthereof defined as: "Software"), and the related documentation, ARE NOT FOR SALE and are andshall 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 notconvey to you an interest in or to the Software, but only a limited right of use revocable in accordancewith the terms of this License Agreement. Nothing in this Agreement constitutes a waiver of Aladdin’sintellectual 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, asdescribed in the Software accompanying user documentation and only according to the terms of thisAgreement: (i) you may install the Software and use it on computers located in your place of business,as described in Aladdin’s related documentation; and (ii) you may merge and link the Software intoyour computer programs for the sole purpose described in the Developer’s Guide; however, any portionof the Software merged into another computer program shall be deemed as derivative work and willcontinue to be subject to the terms of this Agreement. The Software shall not be used for any otherpurposes.

vi

3. Sub-Licensing.After merging the Software in your computer program(s) according to section 2, you may sub-license,pursuant to the terms of this Agreement, the merged Software and resell the hardware components ofthe eTokenTM keys which you purchased from Aladdin, to distributors and/or users. Preceding such asale 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.

4. Prohibited Uses.Except as specifically permitted in Sections 1, 2 and 3 above, you agree not to (i) use, modify, merge orsub-license the Software or any other of Aladdin’s Products, except as expressly authorized in thisAgreement and in the Developer’s Guide; and (ii) sell, license (or sub-license), lease, assign, transfer,pledge, or share your rights under this License with/to anyone else; and (iii) modify, disassemble,decompile, reverse engineer, revise or enhance the Software or attempt to discover the Software’ssource code; and (iv) place the Software onto a server so that it is accessible via a public network; and(v) use any back-up or archival copies of the Software (or allow someone else to use such copies) for anypurpose other that to replace an original copy if it is destroyed or becomes defective. If you are amember of the European Union, this agreement does not affect your rights under any legislationimplementing the EC Council Directive on the Legal Protection of Computer Programs. If you seekany information within the meaning of that Directive you should initially approach Aladdin.

5. Limited Warranty. Aladdin warrants, for your benefit alone, that (i) the Software, when and as delivered to you, and for aperiod of three (3) months after the date of delivery to you, will perform in substantial compliance withthe Developer’s Guide, provided that it is used on the computer hardware and with the operatingsystem for which it was designed; and (ii) that the eTokenTM key, for a period of twelve (12) monthsafter the date of delivery to you, will be substantially free from significant defects in materials andworkmanship.

6. Warranty Disclaimer. ALADDIN DOES NOT WARRANT THAT ANY OF ITS PRODUCT(S) WILL MEET YOURREQUIRMENTS OR THAT ITS OPERATION WILL BE UNINTERRUPTED OR ERROR-FREE. TOTHE EXTENT ALLOWED BY LAW, ALADDIN EXPRESSLY DISCLAIMS ALL EXPRESSWARRANTIES NOT STATED HERE AND ALL IMPLIED WARRANTIES, INCLUDING, BUT NOTLIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR APARTICULAR PURPOSE. NO ALADDIN’S DEALER, DISTRIBUTOR, RESELLER, AGENT OREMPLOYEE IS AUTHORIZED TO MAKE ANY MODIFICATIONS, EXTENSIONS, OR ADDITIONSTO THIS WARRANTY. If any modifications are made to the Software or to any other part of theProduct by you during the warranty period; if the media and the eTokenTM key is subjected to accident,abuse, or improper use; or if you violate any of the terms of this Agreement, then the warranty inSection 5 above, shall immediately be terminated. The warranty shall not apply if the Software is usedon or in conjunction with hardware or program other than the unmodified version of hardware andprogram with which the Software was designed to be used as described in the Developer’s Guide.

vii

7. Limitation of Remedies. In the event of a breach of the warranty set forth above, Aladdin's sole obligation shall be, at Aladdin'ssole discretion: (i) to replace or repair the Product, or component thereof, that does not meet theforegoing limited warranty, free of charge; (ii) to refund the price paid by you for the Product, orcomponent thereof. Any replacement or repaired component will be warranted for the remainder of theoriginal warranty period or 30 days, whichever is longer. Warranty claims must be made in writingduring the warranty period and within seven (7) days of the observation of the defect accompanied byevidence satisfactory to Aladdin. All Products should be returned to the distributor from which theywere purchased (if not purchased directly from Aladdin) and shall be shipped by the returning partywith freight and insurance paid. The Product or component thereof must be returned with a copy ofyour receipt.

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 (INCLUDINGNEGLIGENCE) OR OTHERWISE) TO YOU, OR ANY THIRD PARTY FOR ANY LOSS OR DAMAGE(INCLUDING INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES), INCLUDING, WITHOUTLIMITATION, ANY LOSS OR DAMAGE TO BUSINESS EARNINGS, LOST PROFITS ORGOODWILL AND LOST OR DAMAGED DATA OR DOCUMENTATION, SUFFERED BY ANYPERSON, ARISING FROM AND/OR RELATED WITH AND/OR CONNECTED TO ANY USE OFTHE SOFTWARE AND/OR ANY COMPONENT OF THE PRODUCT, EVEN IF ALADDIN ISADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

9. Limitation Of Liability.IN THE EVENT THAT, NOTWITHSTANDING THE TERMS OF THIS AGREEMENT, ALADDIN ISFOUND LIABLE FOR DAMAGES BASED ON ANY DEFECT OR NONCONFORMITY OF ITSPRODUCT(S), ITS TOTAL LIABILITY FOR EACH DEFECTIVE PRODUCT SHALL NOT EXCEEDTHE 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 thisAgreement. Upon termination of this License Agreement by Aladdin: (i) the License granted to you inthis Agreement shall expire and you, upon termination, shall discontinue all further use of theSoftware and other licensed Product(s); and (ii) you shall promptly return to Aladdin all tangibleproperty 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 shallsurvive any termination of this Agreement.

11. Governing Law & Jurisdiction. This Agreement shall be construed and governed in accordance with the laws of Israel (except forconflict of law provisions) and only the courts in Israel shall have jurisdiction in any conflict or disputearising out of this Agreement. The application of the United Nations Convention of Contracts for theInternational Sale of Goods is expressly excluded. The failure of either party to enforce any rightsgranted hereunder or to take action against the other party in the event of any breach hereunder shallnot be deemed a waiver by that party as to subsequent enforcement of rights or subsequent actions inthe event of future breaches.

viii

12. Government Regulation and Export Control.You agree that the Product will not be shipped, transferred, or exported into any country or used inany manner prohibited by applicable law. It is stipulated that the Product is subject to certain exportcontrol laws, rules, and/or regulations, including, without limiting the foregoing, to the United Statesand/or Israeli export control laws, rules, and/or regulations. You undertake to comply in all respectswith the export and reexport restriction as set forth herein and any update made thereto from time totime.

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 applyto all such third party software providers and third party software as if they were Aladdin and theProduct respectively.

14. Miscellaneous.This Agreement represents the complete agreement concerning this License and may be amended onlyby a written agreement executed by both parties. If any provision of this Agreement is held to beunenforceable, 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 BOUNDBY ALL OF THE TERMS.

FCC Compliance

eToken USB has been tested and found to comply with the limits for a Class B digital device, pursuantto Part 15 of the FCC rules. These limits are designed to provide reasonable protection againstharmful interference in a residential installation. This equipment generates, uses and can radiate radio frequency energy and, if not installed and usedin 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 bedetermined by turning the equipment off and on, the user is encouraged to try to correct theinterference 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 WarningModifications not expressly approved by the manufacturer could void the user authority to operate theequipment 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 BComputing Device Peripheral and therefore does not require FCC regulation.

ix

CE Compliance

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

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.

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.

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.

x

List of TablesTable 1.1: eToken SDK 3.50 Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Table 1.2: Files Installed by eToken SDK 3.50 . . . . . . . . . . . . . . . . . . . . . . . 11Table 1.3: eToken SDK 3.50 - New Features . . . . . . . . . . . . . . . . . . . . . . . . . 11Table 2.1: PKCS #11 Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Table 2.2: Supported Mechanisms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Table 2.3: eTCAPI RSA Key Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Table 2.4: General Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Table 2.5: Talker Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Table 2.6: Reader List and Listener Functions . . . . . . . . . . . . . . . . . . . . . . . 34Table 2.7: Reserved Application IDs on eToken. . . . . . . . . . . . . . . . . . . . . . . 36Table 2.8: eToken R2 General Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Table 2.9: eToken R2 File System Functions . . . . . . . . . . . . . . . . . . . . . . . . . 38Table 2.10: eToken R2 Encryption Storage Functions. . . . . . . . . . . . . . . . . . . 40Table 2.11: eToken CardOS/M4 General Functions. . . . . . . . . . . . . . . . . . . . . 46Table 2.12: eToken CardOS/M4 File System Functions . . . . . . . . . . . . . . . . . 49Table 2.13: eToken CardOS/M4 RSA Keys Functions . . . . . . . . . . . . . . . . . . . 51Table 2.14: eToken CardOS/M4 DES Keys Functions . . . . . . . . . . . . . . . . . . . 52Table 2.15: File Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Table 2.16: eToken CardOS/M4 Certificate Functions . . . . . . . . . . . . . . . . . . 55Table 2.17: eToken R2 APDU Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Table 2.18: eToken CardOS/M4 APDU Functions . . . . . . . . . . . . . . . . . . . . . . 57Table 2.19: eTocx Interfaces & Implementing COM Objects. . . . . . . . . . . . . . 62Table 3.1: etCreateTalker Error Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Table 3.2: etDestroyTalker Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72Table 3.3: etGetReaderName Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . 73

xi

Table 3.4: etGetTokenUnique Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . 74Table 3.5: etLockReader Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Table 3.6: etUnlockReader Error Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76Table 3.7: etTransmit Error Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78Table 3.8: dwToken Parameter Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81Table 3.9: etGetReaderInfo Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82Table 3.10: dwFlags Parameter Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84Table 3.11: etListReaders Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84Table 3.12: dwType Parameter Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86Table 3.13: etStartListen Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87Table 3.14: etStopListen Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88Table 3.15: etGetReaderChanged Error Codes . . . . . . . . . . . . . . . . . . . . . . . . 90Table 3.16: r2ApduVerify Error Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92Table 3.17: r2ApduChangeCode Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . 94Table 3.18: r2ApduResetSecState Error Codes . . . . . . . . . . . . . . . . . . . . . . . . 96Table 3.19: nType Parameter Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97Table 3.20: nAccess Parameter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98Table 3.21: r2ApduCreateFile Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . 98Table 3.22: r2ApduDeleteFile Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . 99Table 3.23: nType Parameter Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100Table 3.24: r2ApduDirectory Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . 101Table 3.25: nRefType Parameter Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102Table 3.26: r2ApduSelectFile Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . 103Table 3.27: r2ApduReadBinaryFile Error Codes. . . . . . . . . . . . . . . . . . . . . . 104Table 3.28: r2ApduWriteBinaryFile Error Codes . . . . . . . . . . . . . . . . . . . . . 106Table 3.29: r2ApduWriteKey Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . 108Table 3.30: nOperation Parameter Bit Values . . . . . . . . . . . . . . . . . . . . . . . 109Table 3.31: r2ApduDesxOperation Error Codes . . . . . . . . . . . . . . . . . . . . . . 110Table 3.32: r2ApduGetConfig Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . 112Table 3.33: eToken R2 Version Code Format . . . . . . . . . . . . . . . . . . . . . . . . . 112Table 3.34: eToken R2 Color Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112Table 3.35: r2ApduGetConfig2 Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . 113Table 3.36: os4ApduSend Error Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116Table 3.37: os4ApduResetSecState Error Codes . . . . . . . . . . . . . . . . . . . . . . 117

xii

Table 3.38: os4ApduPhaseControl Error Codes . . . . . . . . . . . . . . . . . . . . . . 118Table 3.39: os4ApduFileActivation Error Codes . . . . . . . . . . . . . . . . . . . . . . 119Table 3.40: os4ApduExtAuthenticate Error Codes . . . . . . . . . . . . . . . . . . . . 120Table 3.41: os4ApduVerify Error Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122Table 3.42: os4ApduVerifySM Error Codes. . . . . . . . . . . . . . . . . . . . . . . . . . 125Table 3.43: nType Parameter Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127Table 3.44: os4ApduGetData Error Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . 128Table 3.45: os4ApduWriteBinary Error Codes . . . . . . . . . . . . . . . . . . . . . . . 129Table 3.46: os4ApduWriteBinarySM Error Codes . . . . . . . . . . . . . . . . . . . . 130Table 3.47: os4ApduReadBinary Error Codes. . . . . . . . . . . . . . . . . . . . . . . . 132Table 3.48: os4ApduReadBinarySM Error Codes . . . . . . . . . . . . . . . . . . . . . 133Table 3.49: os4ApduIncreaseRecord Error Codes . . . . . . . . . . . . . . . . . . . . . 136Table 3.50: os4ApduDecreaseRecord Error Codes . . . . . . . . . . . . . . . . . . . . 138Table 3.51: os4ApduAppendRecord Error Codes. . . . . . . . . . . . . . . . . . . . . . 139Table 3.52: os4ApduAppendTLV Error Codes. . . . . . . . . . . . . . . . . . . . . . . . 140Table 3.53: os4ApduWriteTLV Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . 142Table 3.54: os4ApduReadTLV Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . 145Table 3.55: os4ApduWriteRecord Error Codes . . . . . . . . . . . . . . . . . . . . . . . 146Table 3.56: os4ApduReadRecord Error Codes. . . . . . . . . . . . . . . . . . . . . . . . 149Table 3.57: os4ApduGetChallenge Error Codes . . . . . . . . . . . . . . . . . . . . . . 150Table 3.58: os4ApduGiveChallenge Error Codes . . . . . . . . . . . . . . . . . . . . . 151Table 3.59: os4ApduSelectFile Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . 153Table 3.60: nType Parameter Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154Table 3.61: os4ApduCreateFile Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . 156Table 3.62: os4ApduDeleteFile Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . 157Table 3.63: os4ApduAdminFile Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . 158Table 3.64: nType Parameter Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160Table 3.65: os4ApduDirectory Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . 161Table 3.66: os4ApduMSERestore Error Codes . . . . . . . . . . . . . . . . . . . . . . . 162Table 3.67: os4ApduCSESet Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . 163Table 3.68: os4ApduGenKeyPair Error Codes . . . . . . . . . . . . . . . . . . . . . . . 164Table 3.69: os4ApduPSOVerifyChecksum Error Codes . . . . . . . . . . . . . . . . 165Table 3.70: os4ApduPSOComputeChecksum Error Codes. . . . . . . . . . . . . . 167Table 3.71: os4ApduChangeRefData Error Codes . . . . . . . . . . . . . . . . . . . . 170

xiii

Table 3.72: os4ApduCreateBS Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . 172Table 3.73: os4ApduCreateSE Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . 174Table 3.74: os4ApduPSOEnc Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . 176Table 3.75: os4ApduPSODec Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . 178Table 3.76: os4ApduPSOHash Error Codes. . . . . . . . . . . . . . . . . . . . . . . . . . 180Table 3.77: os4ApduPSOSigne Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . 182Table 3.78: os4ApduPSOVerify Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . 183Table 3.79: os4ApduPSOVerifyHash Error Codes. . . . . . . . . . . . . . . . . . . . . 185Table 3.80: dwFlags Parameter Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189Table 3.81: r2GetTokenInfoh Error Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . 189Table 3.82: dwFlags Parameter of the R2INFO Structure . . . . . . . . . . . . . . 189Table 3.83: dwFlags Parameter Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191Table 3.84: r2SetTokenInfo Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192Table 3.85: r2GetTokenName Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . 193Table 3.86: r2SetTokenName Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . 194Table 3.87: r2AppGetPath Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196Table 3.88: DF and Application Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196Table 3.89: r2AppDelete Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198Table 3.90: r2Login Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199Table 3.91: r2Logout Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201Table 3.92: r2ChangePassword Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . 202Table 3.93: r2GetFileInfo Error Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206Table 3.94: ET_R2_APDU_FILE_TYPE_xxx Values . . . . . . . . . . . . . . . . . . 207Table 3.95: ET_DIRECTORY_LITE Flag Values . . . . . . . . . . . . . . . . . . . . . 208Table 3.96: r2Directory Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208Table 3.97: r2CreateDirectory Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . 209Table 3.98: r2CreateFile Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212Table 3.99: r2CreateKey Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213Table 3.100: r2Delete Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215Table 3.101: r2ReadFile Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218Table 3.102: r2WriteFile Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220Table 3.103: r2WriteKey Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221Table 3.104: r2Desx Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224Table 3.105: r2EncGetFileInfo Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . 226

xiv

Table 3.106: r2EncStore Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228Table 3.107: r2EncLoad Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231Table 3.108: r2EncDelete Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232Table 3.109: lpBuffer Sizes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235Table 3.110: lpBuffer Size. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236Table 3.111: os4GetProperty Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237Table 3.112: eToken Color Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237Table 3.113: os4SetProperty Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238Table 3.114: os4Login Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240Table 3.115: os4LoginAdmin Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241Table 3.116: os4Logout Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242Table 3.117: os4ChangePassword Error Codes . . . . . . . . . . . . . . . . . . . . . . . . 243Table 3.118: os4ChangePassword Error Codes . . . . . . . . . . . . . . . . . . . . . . . . 245Table 3.119: os4ChangePasswordAdmin Error Codes . . . . . . . . . . . . . . . . . . 247Table 3.120: os4GetFileInfo Error Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250Table 3.121: os4SetFileAccess Error Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . 251Table 3.122: ET_OS4_APDU_DIR_xxx Values . . . . . . . . . . . . . . . . . . . . . . . . 252Table 3.123: ET_DIRECTORY_LITE Flag Values . . . . . . . . . . . . . . . . . . . . . 253Table 3.124: os4Directory Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253Table 3.125: os4CreateDirectory Error Codes. . . . . . . . . . . . . . . . . . . . . . . . . 255Table 3.126: os4CreateFile Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257Table 3.127: os4Delete Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259Table 3.128: os4ReadBinaryFile Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . 261Table 3.129: os4WriteBinaryFile Error Codes . . . . . . . . . . . . . . . . . . . . . . . . 263Table 3.130: os4ReadTLVFile Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . 265Table 3.131: os4WriteTLVFile Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . 267Table 3.132: os4AppendTLVFile Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . 269Table 3.133: dwFlag Parameter Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272Table 3.134: os4RSAGetKeyInfo Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . 272Table 3.135: os4RSAList Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273Table 3.136: os4RSAGenKeyPair Error Codes . . . . . . . . . . . . . . . . . . . . . . . . 274Table 3.137: os4RSARaise Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276Table 3.138: os4RSAExport Error Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278Table 3.139: os4RSAImport Error Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280

xv

Table 3.140: os4RSADelete Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281Table 3.141: os4DESGetKeyInfo Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . 283Table 3.142: os4DESGetKeyInfo Algorithms. . . . . . . . . . . . . . . . . . . . . . . . . . 284Table 3.143: os4DESGetKeyInfo Key Flags. . . . . . . . . . . . . . . . . . . . . . . . . . . 284Table 3.144: os4DESList Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285Table 3.145: os4DRSImport Error Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286Table 3.146: os4DESOperation Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . 288Table 3.147: os4DESDelete Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289Table 3.148: os4CertGetInfo Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292Table 3.149: os4CertList Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293Table 3.150: os4CertCreate Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294Table 3.151: os4CertWrite Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295Table 3.152: os4CertRead Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298Table 3.153: os4CertDelete Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299Table 3.154: Error Codes Defined in eToken.h. . . . . . . . . . . . . . . . . . . . . . . . . 300Table 3.155: APDU Operation Status Codes . . . . . . . . . . . . . . . . . . . . . . . . . . 301Table 4.1: eTocx Enumerator. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306Table 4.2: IByteArray. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308Table 4.3: IBstrEnum. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309Table 4.4: IeTokenHS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309Table 4.5: IeTokenHS2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313Table 4.6: IeTokenHSConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314Table 4.7: IeTokenHSFileInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315Table 4.8: IeTokenPro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315Table 4.9: IeTokenPro2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318Table 4.10: IeTokenPro3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318Table 4.11: IeTokenProConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320Table 4.12: IeTokenProConfig2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321Table 4.13: IProFileInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321Table 4.14: ITracker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322Table 4.15: ITrackerEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323Table 4.16: Return Values for all Interface Methods . . . . . . . . . . . . . . . . . . . 324Table 5.1: eToken R2 APDU Samples Overview . . . . . . . . . . . . . . . . . . . . . 328Table 5.2: Binary File Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330

xvi

Table 5.3: Directory Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330Table 5.4: File Concatenation Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331Table 5.5: Get Configuration Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331Table 5.6: KeyFile Sample. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332Table 5.7: Login-Logout Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332Table 5.8: Time Measurement Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333Table 5.9: Tree Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333Table 5.10: eToken CardOS/M4 APDU Samples Overview. . . . . . . . . . . . . . 334Table 5.11: Access Conditions Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336Table 5.12: Binary File Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337Table 5.13: DES-CBC/3DES-CBC Samples . . . . . . . . . . . . . . . . . . . . . . . . . . 337Table 5.14: Digital Signature Sample. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338Table 5.15: Directory Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339Table 5.16: Get Configuration Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339Table 5.17: MAC Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340Table 5.18: Pin Test SM Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341Table 5.19: Record File Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342Table 5.20: RSA Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343Table 5.21: Secure Messaging Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344Table 5.22: Time Measurement Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345Table 5.23: TLV File Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346Table 5.24: Tree Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346Table 5.25: eToken eTAID Samples Overview . . . . . . . . . . . . . . . . . . . . . . . . 347Table D.1: RTE 3.51 Installed Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385Table F.1: Glossary of Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397

xvii

Chapter1Introduction

This Developer’s Guide introduces Aladdin’s eToken Software Developer’s Kit (SDK) for Windows Version 3.50. 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 the use of eToken for specific organization or client requirements.This introductory chapter includes the following sections:• Structure of this Guide, page 2, shows where to find the

information you need in this Software Developer’s Guide. • eToken SDK for Windows Architecture, page 3, summarizes

the major features and layers in the eToken architecture• Using the SDK, page 7, details the prerequisites required to

develop and implement an eToken solution using the SDK for Windows.

• eToken Software Developer’s Kit, page 8, describes the components and features contained in this SDK, and lists the changes introduced into the latest version of the SDK and the eToken Run Time Environment (RTE).

1

1

Structure of this Guide

The structure of this Software Developer’s Guide is designed to be easily understood and immediately of use to developers. The guide includes the following:• Chapter 2, “Developing Applications for eToken” describes how to

develop applications using the SDK.• Chapter 3, “eToken API Reference” describes the various eToken

APIs in detail and their error codes.• Chapter 4, “eToken eTocx API Reference”, describes the eTocx API

in detail.• Chapter 5, “Samples” illustrates how to develop applications using

the code samples provided with the SDK.Several tools are provided with the SDK, and are explained in this guide as follows:• Appendix A describes the eToken Editor tool, which enables you to

view and edit eToken data structure and content.• Appendix B describes the eToken Cryptoki Viewer tool, which

provides a PKCS #11 object view of the eToken contents.• Appendix C describes the eToken Capi Viewer tool, which provides

a Capi view of the eToken contents.• Appendix D provides guidelines for the redistribution of eToken

applications.• Appendix E describes the installation of the eToken SDK.

2 Introduction

eToken SDK for Windows Architecture

The architecture of the eToken SDK for Windows can be summarized as consisting of the following:• Hardware layer• eToken drivers• eToken.dll• eTocx.dll• eTCAPI/eTCertStore API• eTpkcs11 APIFigure 1-1 is a graphical representation of this eToken architecture.

Figure 1-1: eToken SDK for Windows Architecture

eToken SDK for Windows Architecture 3

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 hardware layer also includes smartcard readers and smartcards.For detailed hardware specifications, refer to the eToken APDU Reference Guide.

Note: The eToken CardOS/M4 is commonly referred to as the eToken PRO.

eToken Drivers

eToken Run Time Environment (RTE) installs all the necessary files and eToken drivers to support eToken integration, including aksifdh.sys (manages eToken reader devices) and aksup.sys (manages eTokens). 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 95/98/Me/NT. For further details about the eToken RTE, refer to the eToken Reference Guide.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 Reference Guide for details).

• When an eToken is inserted, it is recognized as a smartcard inserted into the arbitrarily chosen and unoccupied reader.

4 Introduction

The eToken drivers translate Application Protocol Data Units (APDU) commands to VSRs (USB commands), and vice-versa. For further details about APDU’s, refer to the APDU Reference Guide.

eToken.dll

The eToken.dll resides above the Microsoft Smartcard Resource Manager and is a PC\SC wrapper that enables:• Easy development of applications for the eToken R2 and eToken

CardOS/M4.• Working with the eToken file system and security infrastructure.The eToken.dll API can be divided into the following categories:• General eToken API functions• Talker API functions• Reader List and Listener functions• APDU API Low Level functions specific to the eToken R2 and

eToken CardOS/M4• eToken R2 High Level functions• eToken CardOS/M4 High Level functions

It is also important to note that the new eToken.dll is supported from RTE 3.51 and later RTE versions. This means that while this file can be distributed and work with RTE 3.00, only partial functionality of RTE 3.51 will be available.For further details on using the eToken.dll refer to Chapter 2, "Developing Applications for eToken" and Chapter 3, "eToken API Reference".

eTocx.dll

The eTocx.dll is a Microsoft Component Object Model (COM) dll that enables the rapid development of applications using the following languages: Delphi, JScript, Visual Basic and VB Script. or further details on using the eTocx.dll refer to Chapter 4, "eToken eTocx API Reference".

eToken SDK for Windows Architecture 5

eTCAPI/eTCertStore & eTpkcs11 APIs

The eTCAPI.dll supports the Microsoft CAPI and Certificate Storage APIs. eTpkcs11.dll supports the PKCS #11 industry standard API. For more information about these components, see Chapter 2, “Developing Applications for eToken”.

6 Introduction

Using the SDK

The application developer requires the following when installing the eToken SDK for Windows 3.50, developing and testing applications, as well as reviewing the sample source code.

Installation Requirements• Microsoft Windows.• Microsoft Windows Installer (MSI) 1.1 or later.

Development Environment• Microsoft Visual Studio 6.0• Microsoft Visual Studio .NET• Microsoft Visual Basic• Microsoft VB Script• JScript• Delphi 5• MS Platform SDK November 2001 or later

Hardware Requirements• 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)

• Current eToken’s Firmware supported, are as follows:• eToken R2, Firmware version 2.2.4.2, 16K.• eToken R2, Firmware version 2.3.4.2, 8K.• eToken R2, Firmware version 2.4.4.2, 32K.• eToken CardOS/M4, Firmware 4.1.5.3, 16K (UHCI only).• eToken CardOS/M4, Firmware 4.2.5.3, 32K (UHCI only).• eToken CardOS/M4, Firmware 4.1.5.4.• eToken CardOS/M4, Firmware 4.2.5.4.

Using the SDK 7

eToken Software Developer’s KitThe 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.50 Prerequisites

Before you install the eToken SDK, ensure that you have thefollowing:• PC with at least 10 Mb available disk space.• Windows 95, Windows 98, Windows Me, Windows NT 4.0 (with

Service Pack 6 or above installed) , Windows 2000 or Windows XP.• Internet Explorer 5.0 or later installed.• At least one USB port.• For Windows NT, the RTE requires USB support enabled in the

BIOS. Please contact your system administrator or technical support services supplier for further information.

• At least one eToken security key (either the eToken R2 or the eToken PRO (CardOS/M4).

Note: The SDK is compatible only with Aladdin Knowledge Systems' eTokenPRO (CardOS/M4) and eToken R2 (DESX). Previous eTokens basedon the MD5 hashing algorithm (January 1999-May 2000) are nolonger supported and should be replaced.

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

8 Introduction

eToken SDK 3.50 Contents

Table 1.1 lists the components contained in the eToken SDK 3.50.Table 1.1: eToken SDK 3.50 Contents

Component Description

DLLs

eToken.dll The eToken.dll API includes:General eToken API functionsTalker API functionsReader List and Listener functionsAPDU functions specific to the eToken R2 and eToken CardOS/M4AID functions specific to the eToken R2 and eToken CardOS/M4

eTocx.dll ActiveX component, fully automation compatible, usable from all scripting environments.

Redistribution

RTE 3.51 eToken Run Time Environment redistributable, which includes:eTCAPI.dll: Provides encryption engine and key storage facility (CAPI) and certificate handling (CertStore).eTpkcs11.dll: Provides PKCS #11 support.

eToken and eTocx Merge Modules

Merge modules for redistributing the latest versions of the DLLs.

Tools

eTEditor eToken Editor tool: enables viewing and editing of eToken data. Supports both eToken R2 and eToken CardOS/M4.

ckView eToken Cryptoki Viewer tool: provides a PKCS #11 object view of eToken contents. Supports both eToken CardOS/M4 and eToken R2.

capiView eToken Capi Viewer tool: provides a Capi view of eToken contents. Supports both eToken CardOS/M4 and eToken R2.

Other

Samples Revised set of samples covering many APIs.

eToken Software Developer’s Kit 9

What’s Included in the Kit?

The eToken SDK 3.50 includes the following items:• This eToken Developer’s Guide.• The eToken APDU Reference Guide.• The eToken Utilities Guide.• Two eToken R2 security keys, each with 16 KB memory.• Two eToken CardOS/M4 security keys, each with 32 KB memory.• Four shells.• USB deluxe extension cable for convenient access to the USB port

on desktop computers.• Four RTE PKI software client licenses• One eToken Management Utilities license• CD containing:

• SDK installation msi• RTE installation msi• Utilities installation msi

Installation Technology

The eToken SDK 3.50 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.50 CD image contains an autorun executable that installs:• The MSI component (if not present).• RTE 3.51 (rte_3.51.msi)

eToken Utilities Optional set of eToken utilities. See the eToken Utilities Guide for details.

Documentation This guide and other documentation in electronic format (PDF).

Table 1.1: eToken SDK 3.50 Contents


10 Introduction

• SDK 3.50 (sdk_3.50.msi)• Utilities 2.10 (utilities_2.10.msi)The eToken SDK 3.50 creates the following registry key:• HKEY_LOCAL_MACHINE\Software\Aladdin\eTokenTable 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.

What’s New in eToken SDK 3.50?

The eToken SDK 3.50 is an upgrade of the SDK 2.6. The new features included in this version are shown in Table 1.3.

Table 1.2: Files Installed by eToken SDK 3.50

Component Installed in Directory

RTE 3.51 See Appendix D, "Redistributing eToken Applications".

Redistribution files %etokenfolder%\SDK\redistribution

Include files %etokenfolder%\SDK\include

eTEditor, ckView, capiView

%etokenfolder%\SDK\Tools

DLL Library files %win%\system or system32

eTocx %win%\system or system32

Samples %etokenfolder%\SDK\Samples

PDF documentation %etokenfolder%\SDK\Doc

Table 1.3: eToken SDK 3.50 - New Features


capiView eToken CAPI Viewer tool: provides a CAPI view of eToken contents. Supports both eToken CardOS/M4 and eToken R2.

eToken.dll New API.

Samples Several new samples.

eTocx.dll Extended eTOCX API.

eToken Software Developer’s Kit 11

eToken Support for 32K eToken CardOS/4.

FIPS The eToken CardOS/4 can be enabled in FIPS (Federal Information Processing Standards) mode. The eToken CardOS/4 is compliant with the rules and procedures needed in order to meet FIPS #140-1 levels 2 and 3 requirements.

Table 1.3: eToken SDK 3.50 - New Features


12 Introduction

Chapter2Developing Applications

for eToken

This chapter includes the following sections:• Important Notice, page 14 explains the new development aspects

of the SDK 3.50• Recommendations for eToken Programming, page 15,

describes how to use the eToken.DLL. • PKCS #11, page 16, describes PKCS #11.• CAPI, page 23, describes CAPI.• eToken API, page 31, describes the key concepts required to work

with the eToken API and lists the functions. • eTocx, page 62, describes eTocx.

13

13

Important Notice

Please be advised that the next eToken SDK version will be implemented using PKCS#11 API commands augmented with vendor specific add-ons.To ensure backwards compatibility and smooth migration of your application to newer SDK versions, Aladdin strongly recommends that developers working with the current SDK 3.50 should use PKCS#11 functions whenever possible and not native commands.It is anticipated that in the long term, the SDK architecture will require the use of PKCS#11 also for implementing native commands which may result in a lack of backwards compatibility.

For Developers using RTE 3.00

eToken API is implemented in the eToken.DLL which is an integral part of the eToken RTE since RTE version 3.51.If you plan to use this API, you should redistribute the eToken.DLL with your project. It must still be remembered however, that this does not provide you with the full functionality of RTE 3.51.

14 Developing Applications for eToken

Recommendations for eToken Programming

The application developer has multiple options for choosing the correct APIs to work with eToken. eToken recommends that whenever possible, the developer use standard APIs such as CAPI or PKCS#11. Using these APIs provides the following advantages:• Your application will be less dependant on a particular token type

and more flexible than with a standard API.• the higher abstraction layer that is used with CAPI and PKCS#11

allows the developer to ignore token-specific issues and thereby focus only on the application domain.

• Adaptation of future tokens will be easier and less complicated.It should be noted though that if your application requires more fine-grained access to token capabilities than the standard APIs (CAPI and PKCS#11) are able to provide, you should consider using the eToken API. It is strongly recommended that you DO NOT USE different layers of API (i.e. CAPI/PKCS#11 and eToken API) in the same application.

Recommendations for eToken Programming 15

PKCS #11

PKCS #11 is a C-language API proposed by RSA Labs, which enables applications to access any security tokens that provide an implementation of the API, without having to know any details about the underlying hardware. PKCS #11 presents a “virtual token” for applications and management functions to locate and manipulate such tokens.For more information about PKCS #11, please refer to the RSA Labs website at www.rsalabs.com.

eTpkcs11

eTpkcs11 is an implementation of PKCS #11 ver 2.01 that supports both the eToken R2 and the eToken CardOS/M4. The supported functions are specified in the header files found in ...\Include:• pkcs11.h: primary PKCS #11 header file.• pkcs11t.h: details the various Cryptoki types and defined values.• pkcs11f.h: includes information about the Cryptoki function

prototypes.Table 2.1 lists the PKCS #11 functions that are supported. Table 2.1: PKCS #11 Functions

Functions DescriptionC_Initialize Initializes the Cryptoki library.

C_Finalize Indicates that an application is done with the Cryptoki library.

C_GetInfo Returns general information about Cryptoki.

C_GetFunctionList Returns the function list.

C_GetSlotList Obtains a list of slots in the system.

C_GetSlotInfo Obtains information about a particular slot in the system.

C_GetTokenInfo Obtains information about a particular token in the system.

C_GetMechanismList Obtains a list of mechanism types supported by a token.


C_GetMechanismInfo Obtains information about a particular mechanism possibly supported by a token.

C_InitToken Initializes a token.

C_InitPIN Initializes the normal user's PIN.

C_SetPIN Modifies the PIN of the user who is logged in.

C_OpenSession Opens a session between an application and a token.

C_CloseSession Closes a session between an application and a token.

C_CloseAllSessions Closes all sessions with a token.

C_GetSessionInfo Obtains information about the session.

C_GetOperationState Obtains the state of the cryptographic operation in a session.

C_SetOperationState Restores the state of the cryptographic operation in a session.

C_Login Logs a user into a token.

C_Logout Logs a user out from a token

C_CreateObject Creates a new object

C_CopyObject Copies an object, creating a new object for the copy.

C_DestroyObject Destroys an object.

C_GetObjectSize Gets the size of an object in bytes.

C_GetAttributeValue Obtains the value of one or more object attributes.

C_SetAttributeValue Modifies the value of one or more object attributes

C_FindObjectsInit Initializes a search for token and session objects that match a template.

C_FindObjects Continues a search for token and session objects that match a template, obtaining additional object handles.

Table 2.1: PKCS #11 Functions

Functions Description

PKCS #11 17

C_FindObjectsFinal Finishes a search for token and session objects.

C_EncryptInit Initializes an encryption operation.

C_Encrypt Encrypts single-part data.

C_EncryptUpdate Continues a multiple-part encryption operation.

C_EncryptFinal Finishes a multiple-part encryption operation.

C_DecryptInit Initializes a decryption operation.

C_Decrypt Decrypts encrypted data in a single part.

C_DecryptUpdate Continues a multiple-part decryption operation.

C_DecryptFinal Finishes a multiple-part decryption operation.

C_DigestInit Initializes a message-digesting operation.

C_Digest Digests data in a single part.

C_DigestUpdate Continues a multiple-part message-digesting operation.

C_DigestKey Continues a multi-part message-digesting operation, by digesting the value of a secret key as part of the data already digested.

C_DigestFinal Finishes a multiple-part message-digesting operation.

C_SignInit Initializes a signature (private key encryption) operation, where the signature is (will be) an appendix to the data, and plaintext cannot be recovered from the signature.

C_Sign Signs (encrypts with private key) data in a single part, where the signature is (will be) an appendix to the data, and plaintext cannot be recovered from the signature.

C_SignUpdate Continues a multiple-part signature operation, where the signature is (will be) an appendix to the data, and plaintext cannot be recovered from the signature.

C_SignFinal Finishes a multiple-part signature operation, returning the signature.




C_SignRecoverInit Initializes a signature operation, where the data can be recovered from the signature.

C_SignRecover Signs data in a single operation, where the data can be recovered from the signature.

C_VerifyInit Initializes a verification operation, where the signature is an appendix to the data, and plaintext cannot cannot be recovered from the signature (e.g. DSA).

C_Verify Verifies a signature in a single-part operation, where the signature is an appendix to the data, and plaintext cannot be recovered from the signature.

C_VerifyUpdate Continues a multiple-part verification operation, where the signature is an appendix to the data, and plaintext cannot be recovered from the signature.

C_VerifyFinal Finishes a multiple-part verification operation, checking the signature.

C_VerifyRecoverInit Initializes a signature verification operation, where the data is recovered from the signature.

C_VerifyRecover Verifies a signature in a single-part operation, where the data is recovered from the signature.

C_DigestEncryptUpdate Continues a multiple-part digesting and encryption operation.

C_DecryptDigestUpdate Continues a multiple-part decryption and digesting operation.

C_SignEncryptUpdate Continues a multiple-part signing and encryption operation.

C_DecryptVerifyUpdate Continues a multiple-part decryption and verify operation.

C_GenerateKey Generates a secret key, creating a new key object.

C_GenerateKeyPair Generates a public-key/private-key pair, creating new key objects.

C_WrapKey Wraps (i.e., encrypts) a key.



PKCS #11 19

User Login SemanticseToken without Adminstrator Password

PKCS #11 mandates two entities that can log on to a token: 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 token, it was decided that the eToken’s legitimate user is also the security officer for that token.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 Unitialized 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).

C_UnwrapKey Unwraps (decrypts) a wrapped key, creating a new key object.

C_DeriveKey Derives a key from a base key, creating a new key object.

C_SeedRandom Mixes additional seed material into the token's random number generator.

C_GenerateRandom Generates random data.

C_GetFunctionStatus Obtains an updated status of a function running in parallel with an application.

C_CancelFunction Cancels a function running in parallel.

C_WaitForSlotEvent Waits for a slot event (token insertion, removal, etc.) to occur.




Public Object Write AccessPKCS #11 mandates that even when no one is logged in to the token, public token objects can be created or modified. Since the eToken permits only the legitimate user to modify token 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 20.

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.

MechanismseTpkcs11 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 and Baltimore UniCertTM. The full list of mechanisms supported is detailed in Table 2.2.Table 2.2: 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

PKCS #11 21

On the eToken CardOS/M4, RSA key generation and operations are implemented on-token.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 FunctionsThe 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.

Using eTpkcs11eTpkcs11 is a dynamic link library (eTpkcs11.dll) with __stdcall calling semantics that are installed in the system32 directory on the machine 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.


CAPI

All Microsoft Windows operating systems support a cryptographic API through the Win32 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 a default CSP (Microsoft Base Cryptographic Provider) in the distribution of each operating system, and provides an enhanced version (Microsoft Enhanced Cryptographic Provider), currently available for download from Microsoft's website. 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 eTCertStore, 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 www.eAladdin.com.

CAPI 23

eTCAPI and eTCertStore

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

Using eTCAPIA CSP other than the default one is chosen when an application acquires a context to a provider, supplying its name as a parameter to the CryptAcquireContext() function. eTCAPI is named “eToken Base Cryptographic Provider”. This is demonstrated below:

CryptAcquireContext(&hProv,

"My key container name","eToken Base Cryptographic Provider",

PROV_RSA_FULL,dwFlags);

Table 2.3: eTCAPI RSA Key Properties

eToken Type Minimum Length

Maximum Length

Generated on-token

RSA Operations on-token

Default Key Size

eToken R2 512 2048 No No 1024

eToken CardOS/M4

384 1024 Yes Yes 1024


In order to function correctly, eTCAPI must know which eToken to reference (since several could be inserted into the host) and what is the eToken's password. Since eTCAPI cannot lock and login to the eToken for the entire duration of a cryptographic session, eTCAPI performs a lock-login-work-logout-unlock sequence when it needs to access the eToken. eTCAPI pops up a dialog during the first session prompting the user to select the eToken (if more than one eToken is present) and to enter the user password. eTCAPI stores the password in application memory address space, and this is valid until the eToken is removed. eTCAPI also remembers the eToken chosen as the “current token”.eTCAPI also provides for a silent mode (the dwFlags parameter has the CRYPT_SILENT bit set), where the calling application supplies the name of the reader the eToken is in and the eToken’s password. The reader name and optional password are prefixed to the key-container name parameter as follows:

[reader-name{{password}}]=Key container name

For example:Reader Name = AKS ifdh 0Password = 1234567890Key container name = MyKeyContainerThe 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. The password can also be supplied later by calling:

CryptSetProvParam(hProv, PP_EXCHANGE_PIN, "password");

eTCAPI and Secondary Authentication (2nd Auth)Commencing with RTE 3.51, the eToken CardOS/M4 RSA keys can have a separate password protecting their use. For information on how to enable this feature with a specific eToken and how to control its policy, refer to the RTE documentation. The 2nd password can be changed by calling:

CryptSetKeyParam(hKey, 0x10001, “new2ndpassword”, 0);

Check whether the RSA key has a 2nd password by calling:CryptGetKeyParam(hKey, 0x10001, &keyInfo, 0);

This function returns one byte, keyInfo, where:

CAPI 25

• keyInfo=1: Key has 2nd password• keyInfo=0: Key does not have 2nd password.An RSA key with 2nd Auth is not supported by RTE 3.00 and lower.

Default Key ContainerCommencing with RTE 3.51, the default key container can be set using CryptSetProvParam(). Prior to setting the default container, acquire a context to the container by using the CryptAcquireContext() function.The default key container can be set by calling:CryptSetProvParam(hProv, 0x10001, (BYTE*)&dwSet, 0);

Where dwSet is a DWORD variable:• dwSet=1: Set as default.• dwSet=0: Cancel the setting.To check which is the default key container first call the CryptAcquireContext() function with pszContainer set to NULL, and then call CryptGetProvParam() with PP_CONTAINER. If no key container was set as default the “SmartCardKC” key container (the key container used for smart card logon) will be the default one. If “SmartCardKC” does not exist an arbitrary key container located on the eToken will be the default one.

Selecting the Current eToken ReaderWhen GetProvParam is called in verify context, with either PP_ENUMCONTAINER or PP_ENUMALGS, eTCAPI needs to identify the current reader for the specific eToken.The policy used by eTCAPI in these cases is as follows:• If a reader has already been selected as the current reader, use this

reader.• If only one eToken is connected and the context is in silent mode,

use this eToken and make its reader the current reader.• If there is more than one reader and the context is NOT in silent

mode, the Select eToken dialog box pops up. The reader for the selected eToken becomes the current reader.

• If there is more than one reader and the context is in silent mode, select the first reader and make it the current one.

• If there is no eToken present and the context is NOT in silent mode, the Select eToken dialog box pops up.


eTCertStore

eTCertStore treats all the eTokens currently inserted into the host as a single physical store for the current logged-in user. Since Microsoft forbids a store to have duplicate certificates, it is not recommended to insert tokens with duplicate certificates into the host at the same time. Doing so will cause the OS to request the deletion of one of the certificates.A physical store is referenced by a name. The name of the eToken store is "My\eToken". It is possible to open the eToken store directly using the CertOpenStore() function:

CertOpenStore(CERT_STORE_PROV_PHYSICAL,X509_ASN_ENCODING | PKCS_7_ASN_ENCODING,NULL,CERT_SYSTEM_STORE_CURRENT_USER,L"MY\\eToken");

Opening the store does not require the user to select an eToken or to enter an eToken password, since eTCertStore stores certificates as “public” data on the eToken. When a certificate is added to the eToken store, eTCertStore might require the user to select an eToken and enter the eToken password. When a certificate is removed, eTCertStore always pops up a dialog box alerting the user to the fact that an application intends to remove a certificate and requesting the eToken password.

eTCAPI and eTpkcs11

RTE 3.51 provides interoperability between eTCAPI and eTpkcs11. eTCAPI can use eTpkcs11 keys and certificates, and eTpkcs11 can use eTCAPI keys and certificates.

Viewing PKCS #11 Key Container Names in CAPIWhen eTCAPI enumerates for key containers with CryptGetProvParam, it creates a virtual key container for each RSA PKCS #11 key and assigns to it the following key container name: PKCS11-8FD0F577-0D1B-4ac0-9567-37BD7FDACB4E:n, where n is the eToken internal key ID.

Viewing CAPI Certificates and RSA Keys in PKCS #11RSA key objects are given the default labels “eTCAPI Public Key” and “eTCAPI Private Key”. A certificate is given the label “(eTCAPI) + <issued to>”.

CAPI 27

Using eToken.dll

The eToken.dll is a PC\SC wrapper that enables rapid development of applications for the eToken R2 and eToken CardOS/M4.

eToken.dll Functions Overview

The eToken.DLL API can be divided into the following categories:• General eToken API functions

• Library initialization and finalization.• Talker API functions

• Manages the talker object and handle for a given smart card reader.

• Returns the eToken product ID.• Locks and unlocks the smart card in the reader.• Sends a service request to a smart card.

• Reader List and Listener functions• Returns a list of smart card readers.• Returns the current state of a smart card reader.• Registers and unregisters a user notification receiver for a smart

card listener.• APDU API Low Level functions specific to the eToken R2

and eToken CardOS/M4• Logs in to the eToken.• Changes the eToken password.• Resets the eToken’s security state.• Manages the directories and files.• Reads and writes to the eToken files.• Returns information about the eToken.• Sends a general APDU block (eToken CardOS/M4).

• eToken R2 High Level functions• eToken R2 General Functions• eToken R2 File System Functions• eToken R2 Encryption Storage Functions


• eToken CardOS/M4 High Level functions• eToken CardOS/M4 General Functions• eToken CardOS/M4 File System Functions• eToken CardOS/M4 RSA Keys Functions• eToken CardOS/M4 DES Keys Functions• eToken CardOS/M4 Certificate Functions

For further details on using the eToken.dll refer to Chapter 3, "eToken API Reference".

Low Level vs High Level Functions

The main differences between low-level and high-level functions are:• High-level functions provide the developer with the higher

abstraction layer with which to work. It allows for focusing on the application domain and not on the implementation details of needed functionality in terms of the exact APDUs to be issued.

• The low level function issues the single APDU. The high level function may issue multiple APDUs, the exact sequence of which depends on many factors. For instance, low-level functions operate with the current file, while the high-level functions get the file name as a parameter.

• The parameters may be passed in different forms. For example:• File name is passed as a numerical value in low-level functions

and as a textual string in high-level functions. • Returning error codes may differ (different facility code may be

returned).Provided below is an example of the difference as used between two different functions. For the sake of illustration we use the functions:

os4ApduCreateFile vs. os4CreateFile

DWORD os4ApduCreateFile (HTALKER hTalker,BYTE nType,WORD wId,const OS4_FOAccessCondition * ac,const OS4_FOSecureMessaging * sm,WORD cbLength,BYTE cbRecordLength

Using eToken.dll 29

);

DWORD os4CreateFile (HTALKER hTalker,LPCTSTR lpszPath,OS4FileInfo * pFileInfo);

The main differences between os4Create File and os4ApduCreateFile are:• To identify the file to be created, the low-level function uses a

numerical ID, while the high-level function uses a textual string.• To define access conditions for the newly created file, the

low-level function uses a byte array, where each byte defines access condition for a particular operation (see APDU Reference Guide for more details).The high-level function encodes access conditions in a single DWORD ( for a detailed description, please refer to “eToken CardOS/M4 High Level General Functions”, on page 42). This form is much simpler in use for most of applications as long as you operate with typical access conditions (such as public, private files and so on), but gives to the developer much less flexibility.

• The high-level function is useless for record files since it has no way to define record length.

• The high-level function does not allow for creating a file that requires secure messaging for some of its operations.

the exact sequence of APDUs issued by a high-level function may vary depending on a number of factors, for example RTE version, FIPS vs non-FIPS token etc. The developer should take this into account when mixing high-level and low-level functions.All high-level functions are fully described and explained in Chapter 3, "eToken API Reference". The low-level functions are mentioned briefly.For APDU and CardOS commands, there is a separate user guide. As a result,in this guide the parameters relevant for all these functions are only listed and not fully documented in this guide. To work with these functions, please contact eToken technical support at [email protected] to initiate the process of obtaining the necessary authorization and completion of the required NDA agreements before receiving the required documentation.


eToken API

The eToken.DLL contains several categories of functions. For further details on the functions, refer to Chapter 3, "eToken API Reference".• General Functions Overview, page 32• Talker Functions, page 33• Reader List and Listener Functions, page 34• eToken R2 High Level Functions, page 35• eToken CardOS/M4 High Level Functions, page 41• eToken R2 APDU Functions, page 56• eToken CardOS/M4 APDU Functions, page 57

eToken API 31

General Functions Overview

The table below provides an overview of the general functions and shows where you can find further details about each function. Table 2.4: General Functions

Functions Description PageetInitialize Initializes the eToken.DLL library. 67

etFinalize Finalizes the eToken.DLL library. This function is called when an application has finished using the eToken.DLL library.

68


Talker Functions

The eToken.DLL library includes the Talker functions. The table below provides an overview of the Talker functions and shows where you can find further details about each function.Table 2.5: Talker Functions

Functions Description PageetCreateTalker Creates a talker object for a given

smart card reader and returns its handle.

70

etDestroyTalker Deletes the talker handle. 72

etGetReaderName Retrieves the smart card reader name associated with a specified talker object.

73

etGetTokenUnique Retrieves the 16-byte sequence that uniquely identifies each eToken.

74

etLockReader Locks the smart card that has been inserted in the smart card reader. This prevents other threads and processes from accessing the smart card.

75

etUnlockReader Unlocks the smart card that is inserted in the smart card reader. Unlocking a smart card enables other threads and processes to once again access the smart card.

76

etTransmit Sends a service request to the smart card. The function expects to receive a reply from the card.

77

eToken API 33

Reader List and Listener Functions

The eToken.DLL library includes the Reader List and Listener functions. The table below provides an overview of the Reader List and Listener functions and shows where you can find further details about each function.Table 2.6: Reader List and Listener Functions

Functions Description PageetGetReaderInfo Retrieves current state information for

the specified smart card reader.81

etListReaders Retrieves or updates a list of smart card readers and their current states.

83

etStartListen Registers a user notification receiver for a system smart card listener provided in the eToken.DLL.

86

etStopListen Unregisters the user notification receiver that was registered when the etStartListen function was called.

88

etGetReader Changed Used in WinProc (window message handler procedure) when a listener notification is received. To start to receive these notifications, use etStartListen.

89


eToken R2 High Level Functions

The eToken R2 High Level functions are divided into several categories:• eToken R2 High Level General Functions, page 36• eToken R2 High Level File System Functions, page 38• eToken R2 High Level Encryption Storage Functions,

page 40

eToken API 35

eToken R2 High Level General Functions The eToken R2 High Level General functions are specified in the eTokenR2.h file and perform the following:Return or set the eToken's general information.• Retrieve or set the token name.• Log in or out.• Change the eToken R2 password.

Application Entry

Since the namespace for directories on the eToken R2 is limited to 216-1 possibilities, and because files cannot be created with a “never delete” attribute, there may be a need for a mechanism to map directories under the root directory (MF) to applications. This mechanism could be used to arbitrate between applications so that applications do not overwrite each other’s data. The mechanism chosen is a simple index file that maps an AID (DWORD application ID) to a DWORD Folder ID under the MF. A number of directory names on eToken are reserved for specific applications, as shown in Table 2.7. Table 2.7: Reserved Application IDs on eToken

Reserved DF Name Application

2000 Certificates and RSA Keys

5500 PKCS #11

6000 CAPI

7000 CertStore

8000 eToken Name


Functions

The table below provides an overview of the eToken R2 High Level General functions and shows where you can find further details about each function. Table 2.8: eToken R2 General Functions

Functions Description Pager2GetTokenInfo Returns the eToken's general

information.188

r2SetTokenInfo Sets the eToken's general information.

191

r2GetTokenName Retrieves the token name. 194

r2SetTokenName Sets the token name. 194

r2AppGetPath Initializes or retrieves the application directory name by utilizing the application ID.

195

r2AppDelete Removes the application ID definition from the eToken R2.

198

r2Login Performs login. 199

r2Logout Performs logout. 201

r2ChangePassword Changes eToken R2 password. 202

eToken API 37

eToken R2 High Level File System Functions The eToken R2 High Level File System functions are specified in the eTokenR2.h file and perform the following:• Retrieve the information about a file, directory or key.• Create a new directory, binary file or key file on the eToken R2.• Read data from a file or write data to a file.• Delete an existing file, directory or key.

Useful Info

Information about a file, directory or key is held in the R2FILEINFO structure defined in eTokenR2.h. For further details, see “r2GetFile Info”, page 205.A path is defined as a string of quartets, “X1 X2 …Xk”, where each Xi is a 4-digit hex string signifying the path components. Thus the path 3f00/6666/1000/2000 would be represented in the form “3f00666610002000”.The root directory (MF) of an eToken R2 is always 3f00. All functions accepting a path parameter assume that this path is absolute and sero-terminated.Functions

The table below provides an overview of the eToken R2 High Level File System functions and shows where you can find further details about each function.Table 2.9: eToken R2 File System Functions

Functions Description Pager2GetFileInfo Retrieves the information about a

file, directory or key.205

r2Directory Lists the directory entries and returns information about files, sub-directories and keys.

207

r2CreateDirectory Creates a new empty directory on the eToken R2.

209

r2CreateFile Creates a new binary file on the eToken R2.

211

r2CreateKey Creates a new key file on the eToken R2.

213

r2Delete Deletes an existing file, directory or key.

215


r2ReadFile Reads data from a file. 217

r2WriteFile Writes data to a binary file. 219

r2WriteKey Writes 16-byte key data to a key file. 221

r2Desx Performs a DESX computation with a key on the eToken R2.

223

Table 2.9: eToken R2 File System Functions

Functions Description Page

eToken API 39

eToken R2 High Level Encryption Storage Functions The eToken R2 High Level Encryption Storage API functions are specified in the eTokenR2.h file and perform the following:• Retrieve the information about an encrypted file.• Store data in the encrypted on-token file.• Load data from the encrypted on-token file.• Delete an existing encrypted file.

Useful Info

One of the strengths of the eToken R2 is that files can be created with the private security attribute. This ensures that all files are stored securely in the eToken’s physical memory and that their contents are also secured when in transit between token and host.The problem with this type of storage is that it is slow, and too slow when storing large files. A solution to the problem of storing large private files is to generate a small symmetric encryption key and store the key with the private security attribute, encrypt the big file on the host and save the encrypted blob as a public file. Public files are much faster to read/write.Short files are stored as-is in the storage directory with the private attribute. The algorithm used is the stream cipher RC4, with 128 bit-long keys.

Functions

The table below provides an overview of the eToken R2 High Level Encryption Storage functions and shows where you can find further details about each function.Table 2.10: eToken R2 Encryption Storage Functions

Functions Description Pager2EncGetFileInfo Retrieves the information about an

encrypted file.226

r2EncStore Stores data in the encrypted on-token file.

228

r2EncLoad Loads data from the encrypted on-token file.

230

r2EncDelete Deletes an existing encrypted file. 232


eToken CardOS/M4 High Level Functions

The eToken CardOS/M4 High Level functions are divided into several categories:• eToken CardOS/M4 High Level General Functions, page 42• eToken CardOS/M4 High Level File System Functions,

page 47• eToken CardOS/M4 High Level RSA Keys Functions, page 50• eToken CardOS/M4 High Level DES Keys Functions, page 52• eToken CardOS/M4 High Level Certificate Functions, page 54

eToken API 41

eToken CardOS/M4 High Level General Functions The eToken CardOS/M4 High Level File General functions are specified in the eTokenOS4.h file and perform the following:• Return or set the eToken's general information.• Log in or out.• Change the eToken CardOS/M4 user password.

Security Framework

A simple security framework is defined, similar to the eToken R2 security framework, which has proven to be secure and very successful.Some features/resources of the card are accessible without authenticating oneself with respect to the card. These are termed public features. There is only one legitimate user for the card, referred to simply as the user. The legitimate user for the card can perform/use all the public operations/features of the card plus a more extensive set that is defined as far as possible on the card. These are termed the private features. The user has to be authenticated with respect to the card before gaining access to those operations/features. This authentication test is termed TU. The user can change their password via the RTE eTProperties window.

Login Retry Counter

The login retry counter monitors the number of times the user attempts to log in to the eToken with an incorrect password. Logging in with the correct eToken password resets the retry counter to 0. If the number of incorrect login attempts reaches the specified maximum, then:• The login function for the eToken is locked.• Two-factor operations are not possible with this eToken. • It is not possible to log in to the eToken until it has been

reformatted or replaced. The default setting for the maximum number of incorrect login attempts is 15.


eToken Administrator

The eToken CardOS/M4 may be reformatted to include an administrator entity. The administrator is not considered a user for the card, and has limited privileges. The primary function of an administrator is to replace the user’s password, when the eToken is locked. For further information, see “Reformatting an eToken with the eTFormat Utility”, on page 45.

Access Conditions (AC)

Access conditions of the smartcard object (such as file or directory) define which conditions should be met in order to perform a particular operation on the corresponding object. On the token, the access condition for every operation is encoded with a single byte which may have one of the following values:• 0 stands for ALWAYS, i.e. the operation may always be performed.

For example, a public file may be read always, regardless of the current logon state.

• 0xFF stands for NEVER, i.e. the operation may never be performed. For example, if access conditions for a file were changed to read-only, it cannot be overwritten.

• Any other value stands for the ID of the particular security object.

The set of operations depends on the type of object. The following operations are defined for files:• READ - ability to read file.• APPEND - ability to append new record to the file (for record files).• UPDATE - ability to change file.• DEACTIVATE/REACTIVATE - ability to deactivate/reactivate file,

not used in RTE. It is recommended to set them to NEVER.• DELETE - ability to delete file.• ADMIN - ability to administer file, i.e. to change its access

conditions.

The following operations are defined for directories:• LCYCLE - not used in RTE. Set it to NEVER.• UPDATE - ability to re-write SO.• APPEND - ability to create SO.

eToken API 43

• DEACTIVATE/REACTIVATE - ability to deactivate/reactivate directory, not used in RTE. It is recommended to set them to NEVER.

• DELETE - ability to delete directory.• ADMIN - ability to administer, i.e. to change access conditions of

directory. • CREATE - ability to create files and subdirectories.

The high-level functions (such as os4GetFileInfo, os4SetFileAccess, os4CreateDirectory and os4CreateFile) use more restricted, but also a more comfortable scheme for encoding access conditions. The access conditions of an object are represented by the DWORD value, where each 4-bit group represents the particular access condition. There are macros to build access conditions:• OS4AC_EF (READ, UPDATE, APPEND, DEACTIVATE,

REACTIVATE, DELETE, ADMIN) - builds access conditions to access file. The particular access conditions may be examined by a set of macros:

• OS4AC_EFREAD(x)• OS4AC_EFUPDATE(x)• OS4AC_EFAPPEND(x)• OS4AC_EFDEACTIVATE(x)• OS4AC_EFREACTIVATE(x)• OS4AC_EFDELETE(x)• OS4AC_EFADMIN(x)

• OS4AC_DF (LCYCLE, UPDATE, APPEND, DEACTIVATE, REACTIVATE, DELETE, ADMIN, CREATE) - builds access conditions to access directory. The particular access conditions may be examined by a set of macros:

• OS4AC_DFLCYCLE(x)• OS4AC_DFUPDATE(x)• OS4AC_DFAPPEND(x)• OS4AC_DFDEACTIVATE(x)• OS4AC_DFREACTIVATE(x)• OS4AC_DFDELETE(x)• OS4AC_DFADMIN(x)• OS4AC_DFCREATE(x)


Every 4-bit value is encoded as one of the following:• ET_OS4_APDU_TEST_ALWAYS - stands for ALWAYS.• ET_OS4_APDU_TEST_USER - stands for user password.• ET_OS4_APDU_TEST_ADMIN - stands for administrator

password.• OS4AC_NEVER - stands for NEVER

(ET_OS4_APDU_TEST_NEVER may also be passed to macros that build the access conditions).

If access conditions of an existing object cannot be interpreted according to these rules, OS4AC_UNKNOWN is returned in the corresponding field by the function os4GetFileInfo.

For the convenience of users, the RTE defines several macros that represent the most useful combinations of access conditions:• OS4AC_FULLACCESS - all access conditions are set to ALWAYS.• OS4AC_EF_PUBLIC - public file, which may be read without any

pre-conditions. It may be modified or removed only after user logon.• OS4AC_EF_PRIVATE - private file, which may be read, written or

deleted only when user is logged on.• OS4AC_EF_READONLY - file that can be read freely, but cannot be

modified or removed. Note that it is meaningless to create a file with such access conditions: you will not be able even to enter the initial value. The application should create a file with other access conditions (such as OS4AC_FULLACCESS), write some data and modify the access conditions by using os4SetFileAccess.

• OS4AC_EF_NODELETE - file behaves similarly to OS4AC_EF_PUBLIC, but cannot be deleted.

• OS4AC_DF_PUBLIC - creation, administering and deleting objects in this directory is controlled by the user.

• OS4AC_DF_SYSTEM - similar to OS4AC_DF_PUBLIC, but directory cannot be administered or deleted.

Reformatting an eToken with the eTFormat Utility

An eToken can be reformatted with the eTFormat (eToken PRO Format) utility. This utility is part of the eToken Utilities set, which is included on the SDK 3.50 CD, and can be installed together with the SDK or separately. See the eToken Utilities Guide for full details.

eToken API 45

The eTFormat utility allows you to set the maximum number of retries to a lower number than 15, or to disable the retry counter, setting the maximum number of retries to infinity. Reformatting an eToken with eTFormat deletes all files stored on it since manufacture, clears all available memory, and resets the default eToken password.

Functions

The table below provides an overview of the eToken CardOS/M4 High Level General functions and shows where you can find further details about each function. Table 2.11: eToken CardOS/M4 General Functions

Functions Description Pageos4GetProperty Returns the eToken's general

information.235

os4SetProperty Sets the eToken's general information. Currently, it can be used to set an eToken name only.

238

os4Login Performs login, in user mode. 240

os4LoginAdmin Performs login, in administration mode.

241

os4Logout Performs logout. 242

os4ChangePassword Changes the eToken CardOS/M4 user password.

243

os4CreatePassword Creates a new eToken CardOS/M4 user password (only when password is not present).

245

os4ChangePasswordAdmin Changes the eToken CardOS/M4 administrator password.

247


eToken CardOS/M4 High Level File System Functions The eToken CardOS/M4 High Level File System functions are specified in the eTokenOS4.h file and perform the following:• Retrieve the information about a file or a directory.• Create a new empty directory or file on the eToken CardOS/M4.• Delete a file or a directory.• Read data from a binary or TLV file.

Useful Info

Information about a file, directory or key is held in the OS4FILEINFO structure defined in eTokenOS4.h. For further details, see “os4GetFileInfo”, page 249.A path is defined as a string of quartets, “X1 X2 …Xk”, where each Xi is a 4-digit hex string signifying the path components. Thus the path 3f00/1000/2000 would be represented in the form “3f0010002000”.

Security Infrastructure

The eToken CardOS/M4 High Level File System functions provide functionality for working under the Aladdin 0x6666 folder, according to the Aladdin security infrastructure. Figure 2-1 illustrates the eToken CardOS/M4 file system.

Note: It is preferable to use the eTCAPI/eTCertStore API or the eTpkcs11 API when managing keys and certificates. This eliminates the need for the application to manage the keys and certificates itself.

Aladdin has created the AID named 0x6666 under the root directory, for the following reasons:• It enables greater interoperability with existing smart card

applications that define their own security mechanisms in their own application directories.

• The OS vendor recommends separation by AID.• In order to prevent applications using the eToken CardOS/M4 from

constantly re-authenticating itself to the eToken after a select file command passes through the MF, the CardOS/M4 allows selection by AID name that does not reset any security state set in the MF.

eToken API 47

Figure 2-1: Example of eToken CardOS/M4 File System


Functions

The table below provides an overview of the eToken CardOS/M4 File System Functions and shows where you can find further details about each function. Table 2.12: eToken CardOS/M4 File System Functions

Functions Description Pageos4GetFileInfo Retrieves the information about a file

or a directory.249

os4SetFileAccess Sets file or directory access conditions.

251

os4Directory Lists the directory entries and returns information about files and sub-directories.

252

os4CreateDirectory Creates a new empty directory on the eToken CardOS/M4.

255

os4CreateFile Creates a new file on the eToken CardOS/M4.

257

os4Delete Deletes a file or a directory. 259

os4ReadBinaryFile Reads data from a binary file. 260

os4WriteBinaryFile Writes data to a binary file. 262

os4ReadTLVFile Reads data from a TLV file. 264

os4WriteTLVFile Writes data to a TLV file. 266

os4AppendTLVFile Appends a new record to a TLV file. 268

eToken API 49

eToken CardOS/M4 High Level RSA Keys Functions The eToken CardOS/M4 High Level RSA Keys functions are specified in the eTokenOS4.h file and perform the following:• Read the RSA key information about the existing on-token RSA key.• Generate an RSA key pair. • Export an RSA key from an eToken CardOS/M4.• Delete an RSA key pair and frees the memory on the eToken

CardOS/M4.

Useful Info

An RSA key is referenced by an integer in the range [0x00 ... 0x40] termed the key-ID. Thus there are 64 possible RSA keys. Information about an RSA key and flag values is held in the OS4RSAKEYINFO structure defined in eTokenOS4.h. For further details, see “os4RSAGetKeyInfo”, page 271.The RSA directory is implemented as a physical read-only public directory, with a well-known ID (0x1001) under the Aladdin AID directory, with a body size defined in the format process. A fixed-size binary file with the ID 0x1001 holds the mapping between RSA key-IDs and a condensed version of a KeyInfo structure. Assuming the key-ID of a key is n, the following files and objects might exist:• A BS object with object ID (n+1) * 2, containing <N, E> which is the

public part of the key.• A BS object with object ID (n + 1) * 2 + 1, containing <N, D> which

is the private part of the key.• An EF TLV file with file ID (n + 1) * 2 (the same as BS object ID of

public key), containing N, E in MS format.To facilitate actual encryption and decryption, the directory holds a public SE object with a well-known name (0xFE). This SE object is loaded and used for encryption and decryption.

Functions


The table below provides an overview of the eToken CardOS/M4 High Level RSA Keys Functions and shows where you can find further details about each function.Table 2.13: eToken CardOS/M4 RSA Keys Functions

Functions Description Pageos4RSAGetKeyInfo Reads the RSA key information

about the existing on-token RSA key.271

os4RSAList Reads the list of existing RSA keys. 273

os4RSAGenKeyPair Generates an RSA key pair. 274

os4RSARaise Performs an RSA operation. 275

os4RSAExport Exports an RSA key from an eToken CardOS/M4.

277

os4RSAImport Imports an RSA key into an eToken CardOS/M4.

279

os4RSADelete Deletes an RSA key pair and frees the memory on the eToken CardOS/M4.

281

eToken API 51

eToken CardOS/M4 High Level DES Keys Functions The eToken CardOS/M4 High Level DES Key functions are specified in the eTokenOS4.h file and perform the following:• Read the DES key information about the existing on-token DES

key.• Read the list of existing DES keys.• Import a DES key to the eToken CardOS/M4.• Delete a DES key and frees the memory on the eToken CardOS/M4.

Useful Info

The DES Key component is responsible for maintaining the DES directory and providing access to the DES keys. A DES key is referenced by an integer in the range [0x00 ... 0x40]. This is termed the key-ID. Thus there are 64 possible DES keys. The DES component supports both DES and 3DES keys in both CBC and ECB modes.All keys use ISO padding. This is a limitation of the CardOS/M4 system.The DES directory is implemented as a physical read-only public directory with a well-known ID (0x1003) under the Aladdin AID directory and with a body size of 512. A fixed-size binary file with the ID (0x1003) holds the mapping between DES key-IDs and a condensed version of a KeyInfo structure. For each key-ID n, a BS object with ID n exists.To facilitate actual encryption and decryption, the directory holds a public SE object with a well-known name (0xFE) that is loaded and used for encryption and decryption.

Functions

The table below provides an overview of the eToken CardOS/M4 High Level DES Keys Functions and shows where you can find further details about each function.Table 2.14: eToken CardOS/M4 DES Keys Functions

Functions Description Pageos4DESGetKeyInfo Reads the DES key information

about the existing on-token DES key.283

os4DESList Reads the list of existing DES keys. 285

os4DESImport Imports a DES key to the eToken CardOS/M4.

286


os4DESOperation Performs a DES operation. 287

os4DESDelete Deletes a DES key and frees the memory on the eToken CardOS/M4.

289

Table 2.14: eToken CardOS/M4 DES Keys Functions


eToken API 53

eToken CardOS/M4 High Level Certificate Functions The eToken CardOS/M4 High Level Certificate functions are specified in the eTokenOS4.h file, and perform the following:• Read the certificate information about an existing certificate.• Create a certificate. • Write data to a certificate.• Delete a certificate and frees the memory on the eToken CardOS/

M4.

Note: It is preferable to use the eTCAPI/eTCertStore API or the eTpkcs11 API when managing keys and certificates. This eliminates the need for the application to manage the keys and certificates itself.

Useful Info

The Certificate Storage component is a specification detailing how and where the actual binary data that makes a certificate is stored. A certificate is defined as the tuple <entity, version, blob, application-added-data>. A certificate is referenced by a 16-bit integer (which is actually a file ID) in the range [0x0000 ... 0x0040]. Thus there are 64 possible certificates. Aladdin reserves all entities in the range [0x01 ... 0x1F].Information about an certificate is held in the OS4CERTINFO structure defined in os4r2_aid.h. For further details, see “os4CertGetInfo”, page 291.The certificate directory is implemented as a physical read-only public directory with a well-known ID (0x1002) under the Aladdin AID directory. A fixed-size binary file with the ID (0x1002) holds the entity and version fields. The mapping between cert-IDs and the actual data files is implicit: for an entry at cert-ID K the actual blob file is K + 1.

Note: Aladdin’s CAPI and PKCS#11 CSPs use high level certificate functions internally for storing X.509 certificate objects.These details are for internal purposes and may vary between RTE versions. Use these functions only if you are not planning to use your certificate objects via CAPI or PKCS#11, otherwise use proper APIs.


The structure of this file is explained in Table 2.15.

Functions

The table below provides an overview of the eToken CardOS/M4 High Level Certificate Functions and shows where you can find further details about each function.

Table 2.15: File Structure

Tag Explanation

CertHeader Header that defines offsets for the blob and for the app-data.

Blob Actual certificate blob.

App-data Additional data the formatting entity wants to add to the blob.

Table 2.16: eToken CardOS/M4 Certificate Functions

Functions Description Pageos4CertGetInfo Reads the certificate information about an

existing certificate.291

os4CertList Reads the list of existing certificates. 293

os4CertCreate Creates a certificate. 294

os4CertWrite Writes data to a certificate. 295

os4CertRead Reads data from a certificate. 297

os4CertDelete Deletes a certificate and frees the memory on the eToken CardOS/M4.

299

eToken API 55

eToken R2 APDU Functions

The eToken R2 operates via a file system, which is a subset of the ISO 7816-4 file system. The table below provides an overview of the eToken R2 APDU functions and shows where you can find further details about each function.Table 2.17: eToken R2 APDU Functions

Functions Description Pager2ApduVerify Logs in. 92

r2ApduChangeCode Changes the eToken R2 password. 94

r2ApduResetSecState Resets the eToken's security state to 1-factor.

96

r2ApduCreateFile Creates a directory (DF), binary file (EF) or DESX key file (KF) under the current directory.

97

r2ApduDeleteFile Deletes a current directory, current binary file or current DESX key file.

99

r2ApduDirectory Lists the EFs, KFs and/or DFs directly below the current DF.

100

r2ApduSelect Sets a current DF, current EF or current KF.

102

r2ApduReadBinaryFile Reads data from the current EF. 104

r2ApduWriteBinaryFile Writes data to the current EF. 106

r2ApduWriteKey Writes DESX key data to the current KF.

108

r2ApduDesx Operation Performs a DESX operation on user data using the current KF.

109

r2ApduGetConfig Returns the eToken's configuration information.

111

r2ApduGetConfig2 Returns the largest free memory block size in the eToken R2.

113


eToken CardOS/M4 APDU Functions

The table below provides an overview of the eToken CardOS/M4 APDU functions and shows where you can find further details about each function.Table 2.18: eToken CardOS/M4 APDU Functions

Functions Description Pageos4ApduSend Sends a general APDU block to the

eToken CardOS/M4.115

os4ApduResetSecState Resets the security status of the current directory (DF).

117

os4ApduPhaseControl Toggles between the ADMINISTRATION and OPERATIONAL modes of the life cycle phase.

118

os4ApduFile Activation Activates or deactivates a file or file tree.

119

os4ApduExtAuthenticate Performs a challenge/response test. 120

os4ApduVerify Performs a CHV (card holder verification) PIN test.

122

os4ApduVerifySM Performs a CHV (card holder verification) PIN test. The pin transfer to the token is encrypted with a DES3 Secure Messaging Key.

124

os4ApduGetData Reads the eToken CardOS/M4 system information.

126

os4ApduWriteBinary Updates a binary file. 129

os4ApduWriteBinarySM Updates a binary file using secure messaging.

130

os4ApduReadBinary Reads a binary file. 132

os4ApduReadBinarySM Reads a binary file using secure messaging.

133

os4ApduIncreaseRecord Increases the record value. 135

os4ApduDecreaseRecord Decreases the record value. 137

eToken API 57

os4ApduAppendRecord Creates a new record in the current binary file (EF).

139

os4ApduAppendTLV Creates a new TLV record in the current EF.

140

os4ApduWriteTLV Writes a TLV record to the current EF.

142

os4ApduReadTLV Reads a TLV record from the current EF.

144

os4ApduWriteRecord Writes a record to the current EF. 146

os4ApduReadRecord Reads a record from the current EF. 148

os4ApduGetChallenge Generates a random number. 150

os4ApduGiveChallenge Transmits an external random number to the smart card.

151

os4ApduSelectFile Selects a file or directory to be designated as current and returns the information about it.

152

os4ApduCreateFile Creates a new file or directory on the eToken CardOS/M4.

155

os4ApduDeleteFile Deletes a file or directory on the eToken CardOS/M4.

157

os4ApduAdminFile Installs / administers files via FCIs. 158

os4ApduDirectory Lists EFs and/or DFs directly below the current DF.

160

os4ApduMSERestore Restores a security environment associated with the cryptographic operation.

162

os4ApduCSESet Sets a security environment associated with the cryptographic operation.

163

os4ApduGenKeyPair Generates an RSA key pair. 164

os4ApduPSOVerify Checksum

Performs the VERIFY CRYPTOGRAPHIC CHECKSUM operation.

165

Table 2.18: eToken CardOS/M4 APDU Functions



Password Quality aspects of Login and Change Password functions

RTE 3.51 possesses password quality functionality that is involved when an application works using a CAPI or PKCS#11 API. However this functionality is not involved when an application works through the eToken API interface (functions: os4Login/os4ChangePassword and r2Login/r2ChangePassword).It is planned to extend password quality control in future RTE versions so that this mechanism will work when using the eToken API as well. The following sections describe how to perform user login and password change in applications, so that the application will work correctly both with the current and later versions of the eToken RTE.

os4ApduPSOComputeChecksum

Performs the COMPUTE CRYPTOGRAPHIC CHECKSUM operation.

167

os4ApduChangeRef Data Changes the data of a BS object. 169

os4ApduCreateBS Installs / administers BS objects in the current DF.

171

os4ApduCreateSE Installs / administers SE objects. 174

os4ApduPSOEnc Performs the ENCIPHER operation. 175

os4ApduPSODec Performs the DECIPHER operation. 177

os4ApduPSOHash Performs the HASHING operation. 179

os4ApduPSOSign Performs the COMPUTE DIGITAL SIGNATURE operation.

181

os4ApduPSOVerify Performs the VERIFY DIGITAL SIGNATURE operation.

183

os4ApduPSOVerifyHash Performs the COMPUTE DIGITAL SIGNATURE operation.

185

Table 2.18: eToken CardOS/M4 APDU Functions


eToken API 59

Password ChangeFuture eToken RTE versions will introduce the functions os4ChangePasswordEx and r2ChangePasswordEx described as follows:DWORD ETOKENAPI os4ChangePasswordEx(HTALKER hTalker, LPCVOID lpOldPassword, DWORD cbOldPasswordLength, LPCVOID lpNewPassword, DWORD cbNewPasswordLength);

DWORD ETOKENAPI r2ChangePasswordEx(HTALKER hTalker, LPCVOID lpOldPassword, DWORD cbOldPasswordLength, LPCVOID lpNewPassword, DWORD cbNewPasswordLength);

Unlike os4ChangePassword/r2ChangePassword, these functions accept both the old and new password as parameters and therefore may be called without the user being logged on.The recommended way to change a password from within the application is the following:• Load the ETOKEN.DLL by using LoadLibrary()• Get the address of os4ChangePasswordEx/r2ChangePasswordEx

functions by using GetProcAddress(). For RTE 3.51, NULL will be returned, meaning that the new functions have not been provided yet.

• Whenever an application changes the user password (there is an example of such code in the eTAID sample):• If the new function os4ChangePasswordEx/r2ChangePasswordEx

was found, use it.• Otherwise, use subsequent calls to os4Login/r2Login and

os4ChangePassword/r2ChangePassword.


LoginIn future RTE versions, the functions r2Login/os4Login may fail even when the correct user password is provided due to certain reasons, such as:

• The password has expired.• The administrator forced the user to change the password for the

next logon.• The current password is the default one and should be changed.

The correct way to perform user login in an application is the following:

• Call function os4Login/r2Login.• If the function fails, check the returned code with the macro

ET_PASS_QUALITY_ERROR(). When this macro returns TRUE, the application should force the user to change the password (as decribed above). When the macro returns FALSE, some other error occurred.

Note: It is guaranteed that an RTE version that does not have the os4ChangePasswordEx function will never fail on an os4Logon as a result of password quality aspects.

Error Codes

The eToken.dll converts and presents APDU error codes in Windows error code format. For further details, refer to Chapter 3, “eToken Error Codes”, on page 300.

eToken API 61

eTocx

eTocx is an automation compliant ActiveX control, implemented as an in-process COM server, using the Apartment threading model. It exports several COM objects each implementing a single interface. All interfaces were specifically designed to meet strict automation criteria so as to be usable from a variety of scripting platforms. All interfaces are dual interfaces. The eTocx.dll must be registered in Windows using the Regsvr32 tool (Regsvr32.exe).

eTocx Interfaces and COM Objects

Table 2.19 lists the eTocx interfaces and the COM objects that implement them.

Note: HS is used as an abbreviation for an eToken R2 and Pro for an eToken CardOS/M4.

Table 2.19: eTocx Interfaces & Implementing COM Objects

Interface Object Description Page

IByteArray ByteArray Represents an array of bytes.

308

IBstrEnum BstrEnum Simple BSTR enumerator. 309

IeTokenHSIeTokenHS2 (default)

eTokenHS Represents an eToken R2. Provides access to file system, password, DESX and error string description functionality.

309313

IeTokenHSConfig eTokenHSConfig Represents an eToken R2 configuration properties.

314

IHSFileInfo HSFileInfo Represents eToken R2 file information properties.

315

IeTokenProIeTokenPro2IeTokenPro3 (default)

eTokenPro Represents an eToken CardOS/M4. Provides access to file system and password functionality.

315318318


IeTokenProConfigIeTokenProConfig2 (default)

eTokenProConfig Represents an eToken CardOS/M4 configuration.

320321

IProFileInfo ProFileInfo Represents eToken CardOS/M4 file information properties.

321

ITracker, _ITrackerEvents

Tracker Tracks eTokens and smart cards, by using notification and snapshot view.

322

Table 2.19: eTocx Interfaces & Implementing COM Objects

Interface Object Description Page

eTocx 63

Chapter3eToken API Reference

This chapter describes the eToken SDK 32-bit 3.00 API. It contains the following sections:• General API, page 66, details the general eToken API functions.• Talker Functions API, page 69, describes the Talker API

functions that manage the talker object and handle for a given smart card reader.

• Reader List and Listener Functions API, page 80, describes the API functions dealing with the smart card reader.

• eToken R2 APDU Functions API, page 91, details the specific eToken R2 APDU API functions.

• eToken CardOS/M4 APDU Functions API, page 114, details the specific eToken CardOS/M4 APDU API functions.

• High Level Functions, page 186, details the R2 and OS/4 High Level Functions.

65

65

General API

66 eToken API Reference

etInitialize

The etInitialize function initializes the eToken.DLL library.This function should be the first eToken.DLL call made by an application..

ParameterslpReserved[in] This parameter is not used in the current version of eToken.DLL and must be set to zero.

Return ValuesIf the function succeeds, the return value is NO_ERROR.If the function fails, the return value is a nonzero error code.

RemarksThe eToken.DLL maintains a reference counter for keeping track of the number of etInitialize or etFinalize calls. This reference counter value is incremented each time etInitialize is called and is decremented each time etFinalize is called. Only the first etInitialize call establishes smart card context and initializes internal data structures.

See AlsoetFinalize

DWORD etInitialize(LPCVOID lpReserved

);

General API 67

etFinalize

The etFinalize function is called when an application has finished using the eToken.DLL library. It should be the last eToken.DLL call made by an application..

ParametersNone.

Return ValuesIf the function succeeds, the return value is NO_ERROR.If the function fails, the return value is a nonzero error code. If the eToken.DLL library has not yet been initialized by a call to etInitialize, the return value is ET_ERROR_NOTINITIALIZED.

RemarksThe eToken.DLL maintains a reference counter for keeping track of the number of etInitialize or etFinalize calls. This reference counter value is incremented each time etInitialize is called and is decremented each time etFinalize is called. Only the last etFinalize call frees all the system resources that the eToken.DLL is utilizing. A given number of independent modules in the same application may use the eToken.DLL without affecting each other.

See AlsoetInitialize

DWORD etFinalize (VOID);


Talker Functions API

Talker Functions API 69

etCreateTalker

This function creates a talker object for a given smart card reader and returns its handle..

ParameterslpszReaderName[in] Pointer to a null-terminated string that specifies the name of the smart card reader.In the current RTE version, certain functions are case-sensitive. It is strongly recommended to pass the reader name exactly in the same form as it is received from the function etListReaders.phTalker[out] Buffer that receives the handle that identifies the talker for the designated smart card reader.dwFlags[in] Not used, must be set to 0.

Return ValuesIf the function succeeds, the return value is NO_ERROR.If the function fails, the return value is a nonzero error code, described in the table below:

DWORD etCreateTalker (LPCTSTR lpszReaderName, LPHTALKER phTalker, DWORD dwFlags

);

Table 3.1: etCreateTalker Error Codes

Error code Description

ERROR_INVALID_PARAMETER lpszReaderName or phTalker parameter is NULL.

SCARD_E_UNKNOWN_READER The specified reader name is not recognized.

SCARD_W_REMOVED_CARD The smart card has been removed, so that further communication is not possible.


RemarksThe etCreateTalker establishes connection with a smart card that has been inserted in a smart card reader. To delete the talker object use the etDestroyTalker function.

See AlsoetDestroyTalker, etTransmit


etDestroyTalker

The etDestroyTalker function deletes the talker handle.

ParametershTalker

[in] Talker handle that you wish to delete.


Table 3.2: etDestroyTalker Error Codes

Remarks:Once the etDestroyTalker function has been called, the talker handle is no longer valid and it cannot be used for any further smart card operations. The etFinalize function also closes all talkers previously opened.

See AlsoetCreateTalker, etFinalize

DWORD etDestroyTalker (HTALKER hTalker

);


ERROR_INVALID_ HANDLE The hTalker parameter is not recognized as a valid talker handle.


etGetReaderName

The etGetReaderName function retrieves the smart card reader name associated with a specified talker object.

ParametershTalker[in] Talker handle whose smart card reader name you wish to retrieve.lpszReaderName[out] Pointer to a buffer that receives the smart card reader name for the specified talker. The length of this buffer must be at least MAX_PATH.


Table 3.3: etGetReaderName Error Codes

RemarksNone.

See AlsoetCreateTalker

DWORD etGetReaderName (HTALKER hTalker, LPTSTR lpszReaderName

);


ERROR_INVALID_PARAMETER The lpszReaderName parameter is NULL.



etGetTokenUnique

The etGetTokenUnique function retrieves the 16-byte sequence that uniquely identifies each eToken.

ParametershTalker[in] Talker handle whose smart card reader name you wish to retrieve.lpbUnique[out] Pointer to a buffer that receives the unique eToken 16-byte sequence.


Table 3.4: etGetTokenUnique Error Codes

RemarksIf an eToken is not connected to the talker, the smart card error, SCARD_E_UNKNOWN_READER, is returned.

See AlsoetGetReaderInfo

DWORD etGetTokenUnique (HTALKER hTalker, LPBYTE lpUnique

);


ERROR_INVALID_PARAMETER The lpbUnique parameter is NULL.



etLockReader

The etLockReader function locks the smart card that has been inserted in the smart card reader. This prevents other threads and processes from accessing the smart card.

ParametershTalker[in] Talker handle whose smart card reader you wish to lock.


Table 3.5: etLockReader Error Codes

RemarksThe etLockReader/etUnlockReader functions are used to conduct a transaction with the smart card. The etLockReader call blocks the execution of another thread and its transactions until the present transaction is completed and the smart card is released. The etLockReader and the etUnlockReader functions enable recursive locking to prevent dead locks. The first lock call physically locks the smart card. The subsequent calls increment an internal reader lock counter.

See AlsoetUnlockReader

DWORD etLockReader (HTALKER hTalker

);





etUnlockReader

The etUnlockReader function unlocks the smart card that is inserted in the smart card reader. Unlocking a smart card enables other threads and processes to once again access the smart card.

ParametershTalker[in] Talker handle whose smart card reader you wish to unlock.


Table 3.6: etUnlockReader Error Codes

RemarksAn etUnlockReader function call must be made to unlock the smart card reader, each time the etLockReader function is successfully called.

See AlsoetLockReader

DWORD etUnlockReader (HTALKER hTalker

);


SCARD_E_NOT_TRANSACTED An attempt was made to end a non-existent transaction.



etTransmit

The etTransmit function sends a service request to the smart card. The function expects to receive a reply from the card.

ParametershTalker[in] Talker handle returned by etCreateTalker.lpSendBuffer[in] Pointer to the actual data to be written to the card.cbSendLength[in] Length (in bytes) of the lpSendBuffer parameterlpRecvBuffer[out] Pointer to any data returned from the card.lpcbRecvLength[in/out] Required length of the lpRecvBuffer parameter (in bytes), and the actual number of bytes received from the smart card.


DWORD etTransmit (HTALKER hTalker, LPCVOID lpSendBuffer, DWORD cbSendLength, LPVOID lpRecvBuffer, LPDWORD lpcbRecvLength

);


Table 3.7: etTransmit Error Codes

RemarksThe function is generally not used in applications since the eToken.DLL provides a full set of low-level and high-level functions to access eToken capabilities.

See AlsoetCreateTalker


ERROR_INVALID_PARAMETER The LpszSendBuffer, lpRecvBuffer or lpcbRecvLength parameter is NULL.




Reader List and Listener Functions API


etGetReaderInfo

The etGetReaderInfo function retrieves current state information for the specified smart card reader.

ParameterslpReader[in/out] Pointer to a READERSTATE structure that specifies the reader information to be received.typedef struct tagREADERSTATE{

} READERSTATE;

The dwToken parameter identifies an inserted eToken type. Possible return values for this variable are listed in the table below:

Table 3.8: dwToken Parameter Values

In this function, szReaderName is an input parameter and the other parameters are output.

DWORD etGetReaderInfo (READERSTATE* lpReader

);

DWORD dwToken; // smart card type inserted

DWORD dwState; // current smart card reader state

DWORD cbAtr; // smart card ATR size (in bytes)

BYTE rgbAtr[36]; // smart card ATR

TCHAR szReaderName[256]; // smart card reader name

Value Description

ET_UNKNOWN Unknown smart card found.

ET_NOTPRESENT Smart card is not present in this smart card reader.

ET_R2 eToken R2

ET_OS4 eToken CardOS/M4

Reader List and Listener Functions API 81

The dwState parameter receives a current smart card reader state. This state is the result of a combination of flags SCARD_STATE_xxx.


Table 3.9: etGetReaderInfo Error Codes

RemarksNone.

See AlsoetListReaders


ERROR_INVALID_PARAMETER The lpReader parameter is NULL.


etListReaders

The etListReaders function retrieves or updates a list of smart card readers and their current states.

ParameterslpReaders[in/out] Pointer to a SCARDREADERS structure that specifies the buffer to be received or updated. The SCARDREADERS structure contains a header and an array of READERSTATE items for each of the readers on the list.typedef struct tagSCARDREADERS{

} SCARDREADERS;

Refer to the etGetReaderInfo function for details of the READERSTATE structure.lpcbNewSize[out] Pointer to a variable that specifies the size, in bytes, of the buffer pointed to by the lpReaders parameter. If the buffer specified by the lpReaders parameter is not large enough to hold the data, the function returns ERROR_MORE_DATA, and stores the required buffer size, in bytes, in the variable pointed to by lpcbNewSize. In this case, the contents of the lpReaders buffer remain unchanged.

DWORD etListReaders (SCARDREADERS* lpReaders, LPDWORD lpcbNewSize, DWORD dwFlags

);

DWORD cbSize; // size, in bytes, of the buffer

DWORD dwCount; // number of readers

READERSTATE Info[0]; // array of READERSTATE structures


dwFlags[in] Additional function flags. dwFlags can consist of any combination of the values described in the following table:

Table 3.10: dwFlags Parameter Values


Table 3.11: etListReaders Error Codes

RemarksThe etListReaders function detects the changes that have occured since the previous function call and update it in the output buffer. The SCARD_STATE_CHANGED flag is received for smart card readers whose state has changed. To retrieve the reader list on the first call, set the dwCount member of the SCARDSREADERS structure to zero. The SCARDSREADERS structure contains a cbSize parameter that defines the size, in bytes, of the current buffer. The etListReaders function can detect new devices that have been added. The function returns ERROR_MORE_DATA, if the size of the output buffer is not large enough.

Value Description

0 Get full reader list.

ET_LISTEN_NONEWDEVICES No new smart card reader addition or removal will be detected.

ET_LISTEN_PRESENTSONLY Only a change of SCARD_STATE_PRESENT will be detected.


ERROR_MORE_DATA The lpReaders buffer is not big enough.


Three useful macros are provided for efficient use of the SCARDSREADERS structure:

6 ALLOCATE_SCARDREADERS (pReaders, nReaders)This macro allocates the memory of the reader list to accomodate a maximum of nReaders smart card readers. It stores the new buffer pointer in the pReaders variable.

7 REALLOCATE_SCARDREADERS (pReaders, newSize)This macro reallocates a new memory block to enable the reader list buffer to handle a new etListReaders function call. The newSize value was stored in the lpcbNewSize variable of previous etListReaders function calls that had returned ERROR_MORE_DATA. All previous data in the buffer is preserved.

8 FREE_SCARDREADERS (pReaders)This macro frees the reader list buffer allocation of ALLOCATE_SCARDREADERS or of REALLOCATE_SCARDREADERS.

See AlsoetGetReaderInfo


etStartListen

The etStartListen function registers a user notification receiver for a system smart card listener provided in eToken.DLL.

ParametershDest[in] Buffer containing the notification receiver. It can event handle, semaphore handle, thread id or window handle.dwType[in] Type of notification. Possible values of this parameter are described in the table below:

Table 3.12: dwType Parameter Values

lpExt[in/out] Pointer to an external parameter buffer. When the ET_LISTEN_THREAD or ET_LISTEN_WINDOW flags value is used, this buffer receives a window message code (DWORD value) which is posted into the message queue of the user thread.

DWORD etStartListen (LPVOID hDest, DWORD dwType, LPVOID lpExt, DWORD dwFlags

);

Value Description

ET_LISTEN_EVENT hDest is an automatic event object handle. Notification posted by the SetEvent function call.

ET_LISTEN_SEMAPHORE hDest is a semaphore object handle. Notification posted by the ReleaseSemaphore function call.

ET_LISTEN_THREAD hDest is the user thread id. Notification posted by the PostThreadMessage function call.

ET_LISTEN_WINDOW hDest is the window object handle. Notification posted by the PostMessage function call.


dwFlags[in] Additional function flags. Possible values of this parameter can consist of a combination of the flags defined for the etListReadersfunction.


Table 3.13: etStartListen Error Codes

RemarksThe first etStartListen call activates the internal listening mechanism in the eToken.DLL. To stop listening via this hDest object call etStopListen. Each time that the eToken.DLL posts a listening notification, it verifies that hDest presents the valid object. An invalid hDest object invokes an internal etStopListen call.

See AlsoetStopListen, etListReaders


ERROR_INVALID_PARAMETER The hDest parameter is NULL.


etStopListen

The etStopListen function unregisters the user notification receiver that was registered when the etStartListen function was called.

ParametershDest[in] Buffer containing the notification receiver. It can event handle, semaphore handle, thread id or window handle.dwType[in] Type of notification. Possible values of this parameter are listed in the etStartListen function description.


Table 3.14: etStopListen Error Codes

RemarksThe etFinalize function call unregisters all registered listening notification receivers.

See AlsoetStartListen

DWORD etStopListen (LPVOID hDest, DWORD dwType

);


ERROR_INVALID_PARAMETER The hDest parameter is NULL.

ERROR_INVALID_HANDLE The hDest parameter is not registered as a listening notification receiver.


etGetReaderChanged

The etGetReaderChanged function is used in WinProc (window message handler procedure) when a listener notification is received. To start to receive these notifications, use etStartListen.

ParameterswParam[in] First window message parameter.lParam[in] Second window message parameter.lpszReaderName[out] Pointer to a buffer that receives the name of the smart card reader that was changed . The length of this buffer must be at least MAX_PATH.lpdwState[out] Pointer to a variable that receives a current smart card reader state. This state is the result of a combination of flags SCARD_STATE_xxx.lpdwToken[out] Pointer to a variable that receives an inserted eToken type. Refer to etGetReaderInfo.


DWORD etGetReaderChanged (DWORD wParam, DWORD lParam, LPSTR lpszReaderName, LPDWORD lpdwState, LPDWORD lpdwToken

);


Table 3.15: etGetReaderChanged Error Codes

RemarksThis function can be used with a listener working in ET_LISTEN_WINDOW or in ET_LISTEN_THREAD modes only.

See AlsoetStartListen, etGetReaderInfo


ERROR_INVALID_PARAMETER The lpszReaderName, lpdwState or lpdwToken parameter is NULL.


eToken R2 APDU Functions API

eToken R2 APDU Functions API 91

r2ApduVerify

The r2ApduVerify function logs in. If the verification is successful, the security state of the eToken R2 is set to 2-factor.

ParametershTalker[in] Talker handle returned by etCreateTalker.lpPassword[in] Pointer to the buffer that contains the password.cbPasswordLength[in] Length, in bytes, of the lpPassword buffer.


Table 3.16: r2ApduVerify Error Codes

RemarksThe r2ApduVerify function call utilizes a full challenge response protocol.

DWORD r2ApduVerify (HTALKER hTalker, LPCVOID lpPassword, BYTE cbPasswordLength

);


ERROR_INVALID_HANDLE The hTalker parameter is not a valid talker handle.

ERROR_INVALID_PARAMETER The lpPassword parameter is NULL.

R2 error ET_APDU_RESP_BADPINSIZE

The password is too small (shorter than 4 bytes).

R2 error ET_APDU_RESP_BADSEC

Authentication failed because an invalid password was entered.


The password is transformed into a 16-byte DESX key using a hash function.

See Alsor2ApduChangeCode, r2ApduResetSecState


r2ApduChangeCode

The r2ApduChangeCode function changes the eToken R2 password.

ParametershTalker[in] Talker handle returned by etCreateTalker.lpPassword[in] Pointer to a buffer that contains the new eToken password.cbPasswordLength[in] Length, in bytes, of the lpPassword buffer.


Table 3.17: r2ApduChangeCode Error Codes

RemarksThis function requires the token to be logged in. Use the r2ApduVerify function to login. The new password will be transformed to a 16-byte value, encrypted with the login session key and sent to the eToken.

DWORD r2ApduChangeCode (HTALKER hTalker, LPCVOID lpPassword, BYTE cbPasswordLength

);





The password is too small (shorter than 4 bytes).


The eToken R2 is not logged in.


See Alsor2ApduVerify, r2ApduResetSecState


r2ApduResetSecState

The r2ApduResetSecState function resets the eToken's security state to 1-factor.

ParametershTalker[in] Talker handle returned by etCreateTalker.


Table 3.18: r2ApduResetSecState Error Codes

RemarksThe r2ApduResetSecState function call logs out of the eToken R2.

See Alsor2ApduVerify

DWORD r2ApduResetSecState (HTALKER hTalker

);




r2ApduCreateFile

The r2ApduCreateFile function creates a directory, binary file or DESX key file under the current directory.

ParametershTalker[in] Talker handle returned by etCreateTalker.nType[in] New file type. This parameter can have one of the values listed in the table below:

Table 3.19: nType Parameter Values

nAccess[in] New file access mode. This parameter can have one of the values listed in the table below:

DWORD r2ApduCreateFile (HTALKER hTalker,BYTE nType, BYTE nAccess, WORD cbLength, WORD wFileId);

Value Description

ET_R2_APDU_FILE_TYPE_EF Binary file (EF)

ET_R2_APDU_FILE_TYPE_DF Directory (DF)

ET_R2_APDU_FILE_TYPE_KF DESX key file (KF)


Table 3.20: nAccess Parameter

cbLength[in] New file length in bytes. For DF it must be zero, for KF it must be 24wFileId[in] New file ID.


Table 3.21: r2ApduCreateFile Error Codes

RemarksThe r2ApduCreateFile function call does not change the current DF, EF or KF in any way.

See Alsor2ApduSelectFile, r2ApduDeleteFile

Value Description

ET_R2_APDU_ACCESS_PUBLIC Public file

ET_R2_APDU_ACCESS_PRIVATE Private file

ET_R2_APDU_ACCESS_1_ FACTOR_SECRET

Public key

ET_R2_APDU_ACCESS_2_ FACTOR_SECRET

Private key





R2 error ET_APDU_RESP_BADFILEID

A file with this name already exists in the current directory.

R2 error ET_APDU_RESP_MEMFULL

There is not enough memory on the eToken to create the new file.


r2ApduDeleteFile

The r2ApduDeleteFile function deletes a current directory, current binary file or current DESX key file.

ParametershTalker[in] Talker handle returned by etCreateTalker.nType[in] New file type. See the r2ApduCreateFile description for a list of possible values.


Table 3.22: r2ApduDeleteFile Error Codes

RemarksDeleting the current EF sets the current EF to NULL.Deleting the current KF sets the current KF to NULL.Deleting the current DF resets the current DF to the MF and the current EF and current KF to NULL.

See Alsor2ApduSelectFile, r2ApduCreateFile

DWORD r2ApduDeleteFile (HTALKER hTalker,BYTE nType

);





R2 error ET_APDU_RESP_BADPATH

The file does not exist.


r2ApduDirectory

The r2ApduDirectory function lists the EFs, KFs and/or DFs directly below the current DF.

ParametershTalker[in] Talker handle returned by etCreateTalker.nType[in] Type of entries. This parameter can have one of the values listed in the table below:


ppFiles[out] Pointer to a received variable, which is a pointer to the array that receives the EF, KF and DF names. The application must never attempt to modify or to free this array. Furthermore, the application should copy this array data before issuing any other eToken.DLL function calls. Each entry in this array is WORD and its value represents the file, key or directory ID.lpdwCount[out] Pointer to a variable that receives the number of entries in the ppFiles buffer. This parameter is optional and can be NULL.

DWORD r2ApduDirectory (HTALKER hTalker,BYTE nType,LPWORD* ppFiles, LPDWORD lpdwCount

);

Value Description

ET_R2_APDU_FILE_TYPE_EF Binary files only

ET_R2_APDU_FILE_TYPE_DF Directories only

ET_R2_APDU_FILE_TYPE_KF Key files only

ET_R2_APDU_FILE_TYPE_ALL All entries



Table 3.24: r2ApduDirectory Error Codes

RemarksCall the r2ApduSelectFile function to select the DF to be handled, before calling the r2ApduDirectory function.

See Alsor2ApduSelectFile



ERROR_INVALID_PARAMETER The ppFiles parameter is NULL.


r2ApduSelectFile

The r2ApduSelect function sets a current DF, current EF or current KF.

ParametershTalker[in] Talker handle returned by etCreateTalker.nRefType[in] Absolute or relative selection. This parameter can have one of the values listed in the table below:

Table 3.25: nRefType Parameter Values

lpwPath[in] Array of components in the path. Each component is a WORD value of a directory or file ID.nPathLength[in] Number of components in the path.pReply[out] Pointer to the R2_SelectFileReply structure that receives the file information.

DWORD r2ApduSelectFile (HTALKER hTalker,BYTE nRefType, const WORD* lpwPath, BYTE nPathLength, R2_SelectFileReply* pReply

);

Value Description

ET_R2_APDU_ABSPATH Absolute path selection.

ET_R2_APDU_RELPATH Relative path selection.


typedef struct tagR2_SelectFileReply{

} R2_SelectFileReply;


Table 3.26: r2ApduSelectFile Error Codes

RemarksSelecting a directory alters the current DF. The current EF and current KF are set to NULL.Selecting an EF alters the current EF to be the given binary file and the current DF to be the directory of the new current EF. The current KF is set to NULL.Selecting a KF alters the current KF to be the given key file and the current DF to be the directory of the new current KF. The current EF is set to NULL.

See Alsor2ApduCreateFile, r2ApduDeleteFile

WORD id; // File ID

BYTE type; // One of ET_R2_APDU_FILE_TYPE_xxx (see r2ApduCreateFile)

BYTE access; // One of ET_R2_APDU_ACCESS_xxx (see r2ApduCreateFile)

WORD length; // Length of file

WORD address; // Address of first block of file (for internal use)



ERROR_INVALID_PARAMETER The lpwPath or pReply parameter is NULL.




r2ApduReadBinaryFile

The r2ApduReadBinaryFile function reads data from the current EF.

ParametershTalker[in] Talker handle returned by etCreateTalker.wOffset[in] Offset position in the binary file.lpBuffer[out] Pointer to the data received from the card.cbLength[in] Length, in bytes, of lpBuffer.


Table 3.27: r2ApduReadBinaryFile Error Codes

DWORD r2ApduReadBinaryFile (HTALKER hTalker, WORD wOffset, LPVOID lpBuffer, WORD cbLength

);



ERROR_INVALID_PARAMETER The lpBuffer parameter is NULL.


The eToken R2 is not logged in (for private files only).


RemarksIf the security attributes of the file being read are private, the data read between the eToken and the host will be encrypted using the login session key. Encryption and decryption operations will be performed automatically. The result data will be plain.

See Alsor2ApduWriteBinaryFile


r2ApduWriteBinaryFile

The r2ApduWriteBinaryFile function writes data to the current EF.

ParametershTalker[in] Talker handle returned by etCreateTalker.wOffset[in] Offset position in the binary file.lpBuffer[in] Pointer to the data to be stored on the card.cbLength[in] Length, in bytes, of lpBuffer.


Table 3.28: r2ApduWriteBinaryFile Error Codes

DWORD r2ApduWriteBinaryFile (HTALKER hTalker, WORD wOffset, LPCVOID lpBuffer, WORD cbLength

);







RemarksIf the security attributes of the file being written to are private, the data written by the host to the eToken will be encrypted using the login session key. Encryption and decryption operations will be performed automatically.

See Alsor2ApduReadBinaryFile


r2ApduWriteKey

The r2ApduWriteKey function writes DESX key data to the current KF.

ParametershTalker[in] Talker handle returned by etCreateTalker.lpBuffer[in] Pointer to key data to be stored on the card. The length of this buffer must be 16 bytes long.


Table 3.29: r2ApduWriteKey Error Codes

RemarksDue to security reasons, the system does not allow reading the key data that has been written using this function.

See Alsor2ApduDesxOperation

DWORD r2ApduWriteKey (HTALKER hTalker, LPCVOID lpBuffer

);







r2ApduDesxOperation

The r2ApduDesxOperation function performs a DESX operation on user data using the current KF.

ParametershTalker[in] Talker handle returned by etCreateTalker.nOperation[in] Operation code. This parameter can be any combination of the following bit values:

Table 3.30: nOperation Parameter Bit Values

lpInput[in] Pointer to the source data buffer. The length of this buffer must be 8 bytes long.lpOutput[out] Pointer to the destination data buffer. The length of this buffer must be 8 bytes long.

Return ValuesIf the function succeeds, the return value is NO_ERROR.

DWORD r2ApduDesxOperation (HTALKER hTalker, BYTE nOperation, LPCVOID lpInput, LPVOID lpOutput

);

Value On Off

ET_R2_APDU_DESX_OP_DIRECTION

Performs encrypt. Performs decrypt..

ET_R2_APDU_DESX_ ENCRYPT_TOKEN_TO_ HOST

Encrypts traffic from eToken to host.

Does not encrypt traffic from eToken to host.

ET_R2_APDU_DESX_ ENCRYPT_HOST_TO_ TOKEN

Encrypts traffic from host to eToken.

Does not encrypt traffic from host to eToken.


If the function fails, the return value is a nonzero error code, described in the table below:

Table 3.31: r2ApduDesxOperation Error Codes

RemarksIf the nOperation parameter specifies sensitive data and the current mode is 2-factor, the transaction conducted with the eToken will be encrypted using the login session key.

See Alsor2ApduWriteKey



ERROR_INVALID_PARAMETER The lpInput or lpOutput parameter is NULL.


The eToken R2 is not logged in (for 2-factor keys only).


r2ApduGetConfig

The r2ApduGetConfig function returns the eToken's configuration information.

ParametershTalker[in] Talker handle returned by etCreateTalker.pReply[out] Pointer to the R2_GetConfigReply structure that receives eToken R2 configuration parameters.

typedef struct tagR2_GetConfigReply

{

} R2_GetConfigReply;


DWORD r2ApduGetConfig (HTALKER hTalker, R2_GetConfigReply* pReply

);

DWORD tokenId; // eToken R2 unique ID

WORD version; // eToken R2 version code (see remarks)

WORD fsSize; // EE available for FAT and user data

WORD publicUsed; // memory used for public files

WORD privateUsed; // memory used for private files

WORD factor1Used; // memory used for public keys

WORD factor2Used; // memory used for private keys

WORD freeSpace; // free space left

BYTE color; // color enumeration (see remarks)


Table 3.32: r2ApduGetConfig Error Codes

RemarksThe eToken R2 version code format is presented in the table below:

Table 3.33: eToken R2 Version Code Format

The eToken color values are listed in the table below:

Table 3.34: eToken R2 Color Values

See Alsor2ApduGetConfig2



ERROR_INVALID_PARAMETER The pReply parameter is NULL.

Firmware code

Protocol code Platform code Product code

15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0

Name Value Description

ET_APDU_COLOR_RED 0x00 Red

ET_APDU_COLOR_BLUE 0x01 Blue

ET_APDU_COLOR_ GREEN 0x02 Green

ET_APDU_COLOR_ TANGERINE 0x03 Tangerine

ET_APDU_COLOR_ICE 0x04 Ice

ET_APDU_COLOR_ PURPLE 0x05 Purple

ET_APDU_COLOR_LIME 0x06 Lime

ET_APDU_COLOR_PINK 0x07 Pink

ET_APDU_COLOR_BLACK 0x08 Black


r2ApduGetConfig2

The r2ApduGetConfig2 function returns the largest free memory block size in the eToken R2.

ParametershTalker[in] Talker handle returned by etCreateTalker.pReply[out] Pointer to the R2_GetConfigReply2 structure that receives the largest free memory block size in the eToken R2.

typedef struct tagR2_GetConfigReply2

{

} R2_GetConfigReply2;


Table 3.35: r2ApduGetConfig2 Error Codes

RemarksNone.

See Alsor2ApduGetConfig

DWORD r2ApduGetConfig2 (HTALKER hTalker, R2_GetConfigReply2* pReply

);

WORD largestFreeBlock; // largest free memory block size



ERROR_INVALID_PARAMETER The pReply parameter is NULL.


eToken CardOS/M4 APDU Functions API


os4ApduSend

The os4ApduSend function is used to send a general APDU block to the eToken CardOS/M4.

ParametershTalker[in] Talker handle returned by etCreateTalker.cla[in] The 'cla' field of the APDU block.ins[in] The 'ins' field of the APDU block.p1[in] The 'p1' field of the APDU block.p2[in] The 'p2' field of the APDU block.lpRequest[in] Pointer to the request data of the APDU block. This can be NULL intially, if the cbRequest parameter is 0.cbRequest[in] The 'lc' field of the APDU block. This parameter represents the length (in bytes) of the lpRequest buffer. lpReply[out] Pointer to the reply buffer.

DWORD os4ApduSend (HTALKER hTalker, BYTE cla, BYTE ins, BYTE p1, BYTE p2, LPCVOID lpRequest, BYTE cbRequest, LPVOID lpReply, BYTE* lpcbReply

);

eToken CardOS/M4 APDU Functions API 115

lpcbReply[in/out] Pointer to the 'le' field of the APDU block. If this pointer is NULL, then no reply data can be received. If the input value of the 'le' field is 0, then the maximum possible reply data will be received.If this parameter is not NULL, then the user variable will be corrected to receive the actual value of reply data length (without status bytes).


Table 3.36: os4ApduSend Error Codes

Remarks




Status bytes with the error facility code will be returned as a return value. If the status is 0x9000 (success), then the return value will be converted to 0 (NO_ERROR).os4ApduResetSecState

The os4ApduResetSecState function resets the security state of the current directory (DF).

ParametershTalker[in] Talker handle returned by etCreateTalker.bRoot[in] This flag defines that the operation will affect the root directory (if TRUE) or the current directory (if FALSE).


Table 3.37: os4ApduResetSecState Error Codes

Remarks

This function implements the RESET_SECURITY_STATE operation of CardOS/M4.

See Alsoos4ApduVerify, os4ApduExtAuthenticate

DWORD os4ApduResetSecState (HTALKER hTalkerBOOL bRoot

);




os4ApduPhaseControl

The os4ApduPhaseControl function toggles between the ADMINISTRATION and OPERATIONAL modes of the life cycle phase.



Table 3.38: os4ApduPhaseControl Error Codes

RemarksThis function implements the PHASE_CONTROL operation of CardOS/M4.

DWORD os4ApduPhaseControl (HTALKER hTalker

);




os4ApduFileActivation

The os4ApduFileActivation function activates or deactivates a file or file tree.

ParametershTalker[in] Talker handle returned by etCreateTalker.bActivate[in] If TRUE, the function performs activation, otherwise - deactivation.


Table 3.39: os4ApduFileActivation Error Codes

RemarksThis function implements the ACTIVATE_FILE and DEACTIVATE_FILE operations of CardOS/M4.

DWORD os4ApduFileActivation (HTALKER hTalker, BOOL bActivate

);




os4ApduExtAuthenticate

The os4ApduExtAuthenticate function performs a challenge/response test.

ParametershTalker[in] Talker handle returned by etCreateTalker.nObjectId[in] Test object ID.bBackTrack[in] Switches the backtracking mechanism on/off.lpRequest[in] Pointer to a buffer containing test data.cbRequestLength[in] Length, in bytes, of the lpRequest buffer.


Table 3.40: os4ApduExtAuthenticate Error Codes

DWORD os4ApduExtAuthenticate (HTALKER hTalker, BYTE nObjectId, BOOL bBackTrack, LPCVOID lpRequest, BYTE cbRequestLength

);



ERROR_INVALID_PARAMETER The lpRequest parameter is NULL.


RemarksThis function implements the EXTERNAL_AUTHENTICATE operation of CardOS/M4.

See Alsoos4ApduVerify, Status bytes with the error facility code will be returned as a return value. If the status is 0x9000 (success), then the return value will be converted to 0 (NO_ERROR).os4ApduResetSecState


os4ApduVerify

The os4ApduVerify function performs a CHV (card holder verification) PIN test.

ParametershTalker[in] Talker handle returned by etCreateTalker.nObjectId[in] Test object ID.bBackTrack[in] Switches the backtracking mechanism on/off.lpRequest[in] Pointer to a buffer containing test data.cbRequestLength[in] Length, in bytes, of the lpRequest buffer.


Table 3.41: os4ApduVerify Error Codes

DWORD os4ApduVerify (HTALKER hTalker, BYTE nObjectId, BOOL bBackTrack, LPCVOID lpRequest,BYTE cbRequestLength

);





RemarksThis function implements the VERIFY operation of CardOS/M4.

See AlsoStatus bytes with the error facility code will be returned as a return value. If the status is 0x9000 (success), then the return value will be converted to 0 (NO_ERROR).os4ApduResetSecState, os4ApduExtAuthenticate


os4ApduVerifySM

The os4ApduVerifySM function performs a CHV (card holder verification) PIN test. The pin transfer to the token is encrypted with a DES3 Secure Messaging Key.

ParametershTalker[in] Talker handle returned by etCreateTalker.nObjectId[in] Test object ID.bBackTrack[in] Switches the backtracking mechanism on/off.lpRequest[in] Pointer to a buffer containing test data.cbRequestLength[in] Length, in bytes, of the lpRequest buffer.lpKey[in] Pointer to a key data buffer used for secure messaging (the DES3 key buffer is 24 bytes long).


DWORD os4ApduVerifySM (HTALKER hTalker, BYTE nObjectId, BOOL bBackTrack, LPCVOID lpRequest, BYTE cbRequestLength, LPCVOID lpKey

);


Table 3.42: os4ApduVerifySM Error Codes

RemarksThis function implements the VERIFY operation of CardOS/M4.

See Alsoos4ApduVerify, Status bytes with the error facility code will be returned as a return value. If the status is 0x9000 (success), then the return value will be converted to 0 (NO_ERROR).os4ApduResetSecState, os4ApduExtAuthenticate





os4ApduGetData

The os4ApduGetData function reads the eToken CardOS/M4 system information.

ParametershTalker[in] Talker handle returned by etCreateTalker.nType[in] System information type. The parameter may have one of the values listed in the table below:

DWORD os4ApduGetData (HTALKER hTalker, BYTE nType, LPVOID* ppReply, LPBYTE lpcbLength

);



Refer to OS/M4 card documentation for more information about the GET_DATA operation.ppReply[out] Pointer to a received variable, which serves as a pointer to a result buffer. The application must never attempt to modify or to free this buffer. Furthermore, the application should copy this buffer's data before issuing any other eToken.DLL function calls.lpcbLength[out] Pointer to a variable that receives the length, in bytes, of the ppReply buffer. This parameter is optional and can be NULL.


Name Value

ET_OS4_APDU_MODE_PRODINFO 0x80

ET_OS4_APDU_MODE_CHIPDATA 0x81

ET_OS4_APDU_MODE_OSVER 0x82

ET_OS4_APDU_MODE_DF_LCYCLE 0x83

ET_OS4_APDU_MODE_DF_CSE 0x84

ET_OS4_APDU_MODE_DF_FREE 0x85

ET_OS4_APDU_MODE_ATR_STAT 0x86

ET_OS4_APDU_MODE_DF_PATH 0x87

ET_OS4_APDU_MODE_PACKAGES 0x88

ET_OS4_APDU_MODE_HW 0x89

ET_OS4_APDU_MODE_FREE_EE 0x8A

ET_OS4_APDU_MODE_SYSKEY_RET 0x96


Table 3.44: os4ApduGetData Error Codes

RemarksThis function implements the GET_DATA operation of CardOS/M4.The os4ApduGetData function performs the endian swap needed for WORD output data (for ET_OS4_APDU_MODE_HW; ET_OS4_APDU_MODE_DF_FREE and ET_OS4_APDU_MODE_FREE_EE modes).



ERROR_INVALID_PARAMETER The ppReply parameter is NULL.


os4ApduWriteBinary

The os4ApduWriteBinary function updates a binary file.

ParametershTalker[in] Talker handle returned by etCreateTalker.wOffset[in] Position in the file to store data to.lpBuffer[in] Pointer to a buffer containing data to be stored.cbLength[in] Length, in bytes, of the lpBuffer.


Table 3.45: os4ApduWriteBinary Error Codes

RemarksThis function implements the UPDATE_BINARY operation of CardOS/M4.

See Alsoos4ApduWriteBinarySM, os4ApduReadBinary

DWORD os4ApduWriteBinary (HTALKER hTalker, WORD wOffset, LPCVOID lpBuffer, BYTE cbLength

);





os4ApduWriteBinarySM

The os4ApduWriteBinarySM function updates a binary file using secure messaging.

ParametershTalker[in] Talker handle returned by etCreateTalker.wOffset[in] Position in the file to store data to.lpBuffer[in] Pointer to a buffer containing data to be stored.cbLength[in] Length, in bytes, of the lpBuffer.lpKey[in] Pointer to a key data buffer used for secure messaging (The DES3 key buffer is 24 bytes long).


Table 3.46: os4ApduWriteBinarySM Error Codes

DWORD os4ApduWriteBinarySM (HTALKER hTalker, WORD wOffset, LPCVOID lpBuffer, BYTE cbLength, LPCVOID lpKey

);



ERROR_INVALID_PARAMETER The lpBuffer or lpKey parameter is NULL.


RemarksThis function implements the UPDATE_BINARY operation of CardOS/M4.

See Alsoos4ApduReadBinarySM, os4ApduWriteBinary


os4ApduReadBinary

The os4ApduReadBinary function reads a binary file.

ParametershTalker[in] Talker handle returned by etCreateTalker.wOffset[in] Position in the file to read data from.lpBuffer[out] Pointer to a buffer that has received data to be read.cbLength[in] Length, in bytes, of the lpBuffer.


Table 3.47: os4ApduReadBinary Error Codes

RemarksThis function implements the READ_BINARY operation of CardOS/M4.

See Alsoos4ApduWriteBinary, os4ApduReadBinarySM

DWORD os4ApduReadBinary (HTALKER hTalker, WORD wOffset, LPVOID lpBuffer, BYTE cbLength

);





os4ApduReadBinarySM

The os4ApduReadBinarySM function reads a binary file using secure messaging.

ParametershTalker[in] Talker handle returned by etCreateTalker.wOffset[in] Position in the file to read data from.lpBuffer[out] Pointer to a buffer that has received data to be read.cbLength[in] Length, in bytes, of the lpBuffer.lpKey[in] Pointer to a key data buffer used for secure messaging (The DES3 key buffer is 24 bytes long).


Table 3.48: os4ApduReadBinarySM Error Codes

DWORD os4ApduReadBinarySM (HTALKER hTalker, WORD wOffset, LPVOID lpBuffer, BYTE cbLength, LPCVOID lpKey

);





RemarksThis function implements the READ_BINARY operation of CardOS/M4.

See Alsoos4ApduWriteBinarySM, os4ApduReadBinary


os4ApduIncreaseRecord

The os4ApduIncreaseRecord function increases the record value.

ParametershTalker[in] Talker handle returned by etCreateTalker.lpIncBuffer[in] Pointer to a buffer that contains the value to add.cbIncBuffer[in] Length, in bytes, of the lpIncBuffer.ppResultBuffer[out] Pointer to a received variable, which serves as a pointer to a result buffer. The application must never attempt to modify or to free this buffer. Furthermore, the application should copy this buffer's data before issuing any other eToken.DLL function calls.lpcbResultBuffer[out] Pointer to a variable that receives the actual length, in bytes, of the ppResultBuffer. This parameter is optional and can be NULL.


DWORD os4ApduIncreaseRecord (HTALKER hTalker, LPCVOID lpIncBuffer, BYTE cbIncLength, LPVOID* ppResultBuffer, LPBYTE lpcbResultBuffer

);


Table 3.49: os4ApduIncreaseRecord Error Codes

RemarksThis function implements the INCREASE operation of CardOS/M4.

See Alsoos4ApduDecreaseRecord



ERROR_INVALID_PARAMETER The lpIncBuffer or ppResultBuffer parameter is NULL.


os4ApduDecreaseRecord

The os4ApduDecreaseRecord function decreases the record value.

ParametershTalker[in] Talker handle returned by etCreateTalker.lpDecBuffer[in] Pointer to a buffer that contains the value to substract.cbDecBuffer[in] Length, in bytes, of the lpDecBuffer.ppResultBuffer[out] Pointer to a received variable, which serves as a pointer to a result buffer. The application must never attempt to modify or to free this buffer. Furthermore, the application should copy this buffer's data before issuing any other eToken.DLL function calls.lpcbResultBuffer[out] Pointer to a variable that receives the actual length, in bytes, of the ppResultBuffer. This parameter is optional and can be NULL.


DWORD os4ApduDecreaseRecord (HTALKER hTalker, LPCVOID lpDecBuffer, BYTE cbDecLength, LPVOID* ppResultBuffer, LPBYTE lpcbResultBuffer

);


Table 3.50: os4ApduDecreaseRecord Error Codes

RemarksThis function implements the DECREASE operation of CardOS/M4.

See Alsoos4ApduIncreaseRecord



ERROR_INVALID_PARAMETER The lpDecBuffer or ppResultBuffer parameter is NULL.


os4ApduAppendRecord

The os4ApduAppendRecord function creates a new record in the current binary file (EF).

ParametershTalker[in] Talker handle returned by etCreateTalker.lpBuffer[in] Pointer to a buffer that contains the record data.cbLength[in] Length, in bytes, of the lpBuffer.


Table 3.51: os4ApduAppendRecord Error Codes

RemarksThis function implements the APPEND_RECORD operation of CardOS/M4.

See Alsoos4ApduAppendTLV

DWORD os4ApduAppendRecord (HTALKER hTalker, LPCVOID lpBuffer, BYTE cbLength

);





os4ApduAppendTLV

The os4ApduAppendTLV function creates a new TLV record in the

current EF.

ParametershTalker[in] Talker handle returned by etCreateTalker.nTag[in] Tag of TLV file.lpBuffer[in] Pointer to a buffer that contains the record data.cbLength[in] Length, in bytes, of the lpBuffer.


Table 3.52: os4ApduAppendTLV Error Codes

RemarksThis function implements the APPEND_RECORD operation of CardOS/M4.

DWORD os4ApduAppendTLV (HTALKER hTalker, BYTE nTag, LPCVOID lpBuffer, BYTE cbLength

);





See Alsoos4ApduWriteTLV, os4ApduAppendRecord


os4ApduWriteTLV

The os4ApduWriteTLV function writes a TLV record to the current

EF.

ParametershTalker[in] Talker handle returned by etCreateTalker.nTag[in] Tag of TLV file.nType[in] Mode, i.e. FIRST/LAST/NEXT/PREV. See the documentation for UPDATE_RECORD operation of theOS/M4 card.lpBuffer[in] Pointer to a buffer that contains the record data.cbLength[in] Length, in bytes, of the lpBuffer.


Table 3.53: os4ApduWriteTLV Error Codes

DWORD os4ApduWriteTLV (HTALKER hTalker, BYTE nTag, BYTE nType,LPCVOID lpBuffer, BYTE cbLength

);





RemarksThis function implements the UPDATE_RECORD operation of CardOS/M4.

See Alsoos4ApduReadTLV


os4ApduReadTLV

The os4ApduReadTLV function reads a TLV record from the current EF.

ParametershTalker[in] Talker handle returned by etCreateTalker.nTag[in] Tag of the TLV file.nType[in] Mode, i.e. FIRST/LAST/NEXT/PREV. See the documentation for the READ_RECORD operation of theOS/M4 card.ppBuffer[out] Pointer to a received variable, which serves as a pointer to a result buffer. The application must never attempt to modify or to free this buffer. Furthermore, the application should copy this buffer's data before issuing any other eToken.DLL function calls.lpcbLength[out] Pointer to a variable that receives the actual length, in bytes, of the ppBuffer. This parameter is optional and can be NULL.


DWORD os4ApduReadTLV (HTALKER hTalker, BYTE nTag, BYTE nType, LPVOID* ppBuffer, BYTE cbLength

);


Table 3.54: os4ApduReadTLV Error Codes

RemarksThis function implements the READ_RECORD operation of CardOS/M4.

See Alsoos4ApduWriteTLV



ERROR_INVALID_PARAMETER The ppBuffer parameter is NULL.


os4ApduWriteRecord

The os4ApduWriteRecord function writes a record to the current EF.

ParametershTalker[in] Talker handle returned by etCreateTalker.nIndex[in] Index of the record in the file.nType[in] Mode, i.e. FIRST/LAST/NEXT/PREV. See the documentation for the UPDATE_RECORD operation of CardOS/M4.lpBuffer[in] Pointer to a buffer that contains the record data.cbLength[in] Length, in bytes, of the lpBuffer.


Table 3.55: os4ApduWriteRecord Error Codes

DWORD os4ApduWriteRecord (HTALKER hTalker, BYTE nIndex, BYTE nType, LPCVOID lpBuffer, BYTE cbLength

);





RemarksThis function implements the UPDATE_RECORD operation of CardOS/M4.

See Alsoos4ApduReadRecord


os4ApduReadRecord

The os4ApduReadRecord function reads a record from the current EF.

ParametershTalker[in] Talker handle returned by etCreateTalker.nIndex[in] Index of the record in the file.nType[in] Mode, i.e. FIRST/LAST/NEXT/PREV. See the documentation for the READ_RECORD operation of CardOS/M4.ppBuffer[out] Pointer to a received variable, which serves as a pointer to a result buffer. The application must never attempt to modify or to free this buffer. Furthermore, the application should copy this buffer's data before issuing any other eToken.DLL function calls.lpcbLength[in] Pointer to a variable that receives the actual length, in bytes, of the ppBuffer. This parameter is optional and can be NULL.


DWORD os4ApduReadRecord (HTALKER hTalker, BYTE nIndex, BYTE nType, LPVOID lpBuffer, BYTE cbLength

);


Table 3.56: os4ApduReadRecord Error Codes

RemarksThis function implements the READ_RECORD operation of CardOS/M4.

See Alsoos4ApduWriteRecord



ERROR_INVALID_PARAMETER The ppBuffer parameter is NULL.


os4ApduGetChallenge

The os4ApduGetChallenge function generates a random number.

ParametershTalker[in] Talker handle returned by etCreateTalker.lpReply[out] Pointer to a buffer that receives the random data.cbLength[in] Length, in bytes, of the lpReply.


Table 3.57: os4ApduGetChallenge Error Codes

RemarksThis function implements the GET_CHALLENGE operation of CardOS/M4.

See Alsoos4ApduGiveChallenge

DWORD os4ApduGetChallenge (HTALKER hTalker, LPVOID lpReply, BYTE cbLength

);



ERROR_INVALID_PARAMETER The lpReply parameter is NULL.


os4ApduGiveChallenge

The os4ApduGiveChallenge function transmits an external random number to the smart card.

ParametershTalker[in] Talker handle returned by etCreateTalker.lpRequest[in] Pointer to a buffer that contains the random data.cbLength[in] Length, in bytes, of the lpRequest.


Table 3.58: os4ApduGiveChallenge Error Codes

RemarksThis function implements the GIVE_RANDOM operation of CardOS/M4.

See Alsoos4ApduGetChallenge

DWORD os4ApduGiveChallenge (HTALKER hTalker, LPCVOID lpRequest, BYTE cbLength

);





os4ApduSelectFile

The os4ApduSelectFile function selects a file or directory to be designated as current and returns the information about it.

ParametershTalker[in] Talker handle returned by etCreateTalker.dwFlags[in] Combination of one of the ETOS4_SELECT_xxx options and the ETOS4_SELECT_INFO flag. The ETOS4_SELECT_INFO flag enforces receiving information about a file in the pReply structure.lpwPath[in] Pointer to an array of files IDs or to a 16-byte symbolic file name, depending on the dwFlags value.cbPathLength[in] Length of lpwPath. It can be in WORDs or in bytes, depending on the dwFlags value.pReply[out] Pointer to an OS4_SelectFileReply structure that receives the file information.

DWORD os4ApduSelectFile (HTALKER hTalker, DWORD dwFlags,const WORD* lpwPath, WORD cbPathLength, OS4_SelectFileReply* pReply

);


typedef struct tagOS4_SelectFileReply

{

} OS4_SelectFileReply;


Table 3.59: os4ApduSelectFile Error Codes

RemarksThis function implements the SELECT_FILE operation of CardOS/M4.The cbSize member of the lpReply structure must be set to sizeof(OS4_SelectFileReply) before the function call.

DWORD cbSize; // size of this structure

WORD wId; // file ID

WORD cbLength; // file or directory body length

BYTE nType; // file type (see remarks)

BYTE cbRecordLength;

// record file length

WORD wRecordsCount;

// record file size

OS4_FOAccessCondition ac; // access conditions definitions

OS4_FOSecureMessaging sm; // secure messaging definitions



ERROR_INVALID_PARAMETER The lpReply parameter is NULL or the cbSize member of the lpReply structure is invalid.


The nType member of lpReply structure may have one of the values listed in the table below:


See Alsoos4ApduDirectory

Value Description

ET_OS4_APDU_FILE_TYPE_DF Directory

ET_OS4_APDU_FILE_TYPE_EF_ BINARY Binary file

ET_OS4_APDU_FILE_TYPE_EF_ LINEAR Linear file

ET_OS4_APDU_FILE_TYPE_EF_ TLV TLV file

ET_OS4_APDU_FILE_TYPE_EF_ CYCLIC Cyclic file

ET_OS4_APDU_FILE_TYPE_ CODE Code file


os4ApduCreateFile

The os4ApduCreateFile function creates a new file or directory on the eToken CardOS/M4.

ParametershTalker[in] Talker handle returned by etCreateTalker.nType[in] File type. Refer to os4ApduSelectFile for a list of allowed types.wId[in] New file ID.ac[in] Access conditions definitions.sm[in] Secure messaging definitions.cbLength[in] Length, in bytes, of the new file, or the body length of the new directory.cbRecordLength[in] Record length for the new record file.


DWORD os4ApduCreateFile (HTALKER hTalker, BYTE nType, WORD wId, const OS4_FOAccessCondition* ac, const OS4_FOSecureMessaging* sm, WORD cbLength, BYTE cbRecordLength

);


Table 3.61: os4ApduCreateFile Error Codes

RemarksThis function implements the CREATE_FILE operation of CardOS/M4.The new file can be deleted by the os4ApduDeleteFile function call.

See Alsoos4ApduDeleteFile



ERROR_INVALID_PARAMETER The ac or sm parameter is NULL.


os4ApduDeleteFile

The os4ApduDeleteFile function deletes a file or directory on the eToken CardOS/M4.

ParametershTalker[in] Talker handle returned by etCreateTalker.wId[in] File ID to be deleted.


Table 3.62: os4ApduDeleteFile Error Codes

RemarksThis function implements the DELETE_FILE operation of CardOS/M4.

See Alsoos4ApduCreateFile

DWORD os4ApduDeleteFile (HTALKER hTalker, WORD wId

);




os4ApduAdminFile

The os4ApduAdminFile function installs / administers files via FCIs.

ParametershTalker[in] Talker handle returned by etCreateTalker.nType[in] Type of operation: ET_OS4_APDU_TAG_AC or ET_OS4_APDU_TAG_SM.ac[in] Access conditions definitions.sm[in] Secure messaging definitions.


Table 3.63: os4ApduAdminFile Error Codes

RemarksThis function implements the PUT_DATA_FCI operation of CardOS/M4.

DWORD os4ApduAdminFile (HTALKER hTalker, BYTE nType, const OS4_FOAccessCondition* ac, const OS4_FOSecureMessaging* sm

);



ERROR_INVALID_PARAMETER The ac or sm parameter is NULL.


See Alsoos4GetFileInfo


os4CreateDirectory

The os4CreateDirectory function creates a new empty directory on the eToken CardOS/M4.

ParametershTalker[in] Talker handle returned by etCreateTalker.lpszPath[in] Zero-terminated path string.cbBodyLength[in] Body length of the new directory.This defines the total size of the security objects that are created in this directory. It does not restrict the size of files and subdirectories that are created.dwAccess[in] Access conditions definition. (One of OS4AC_xxx).


Table 3.125: os4CreateDirectory Error Codes

DWORD os4CreateDirectory (HTALKER hTalker, LPCTSTR lpszPath, DWORD cbBodyLength, DWORD dwAccess

);





RemarksNone.

See Alsoos4CreateFile



OS/4 error ET_APDU_RESP_BAD_DATA_ FIELD

The file already exists.


os4CreateFile

The os4CreateFile function creates a new file on the eToken CardOS/M4.

ParametershTalker[in] Talker handle returned by etCreateTalker.lpszPath[in] Zero-terminated path string.pFileInfo[in] OS4FILEINFO structure for the new file. See os4GetFileInfo for more information.


Table 3.126: os4CreateFile Error Codes

DWORD os4CreateFile (HTALKER hTalker, LPCTSTR lpszPath, OS4FILEINFO* pFileInfo

);






OS/4 error ET_APDU_RESP_BAD_DATA_ FIELD

The file already exists.


RemarksThe cbSize parameter of the OS4FILEINFO structure must be set to sizeof(OS4FILEINFO) before calling the os4CreateFile function.

See Alsoos4CreateDirectory


os4Delete

The os4Delete function deletes a file or a directory.

ParametershTalker[in] Talker handle returned by etCreateTalker.lpszPath[in] Zero-terminated path string.bRecursive[in] (For directories only) If this parameter is TRUE, then all the contents of the directory, including all sub-directories will be deleted.


Table 3.127: os4Delete Error Codes

RemarksThere is no way to restore the file or directory deleted.

DWORD os4Delete (HTALKER hTalker, LPCTSTR lpszPath, BOOL bRecursive

);



ERROR_INVALID_PARAMETER The lpszPath parameter is NULL.






os4ReadBinaryFile

The os4ReadBinaryFile function reads data from a binary file.

ParametershTalker[in] Talker handle returned by etCreateTalker.lpszPath[in] Zero-terminated path string.wOffset[in] Offset position in the binary file.lpBuffer[out] Pointer to the data received from the card.cbLength[in] Length, in bytes, of lpBuffer.


DWORD os4ReadBinaryFile (HTALKER hTalker, LPCTSTR lpszPath, DWORD dwOffset, LPVOID lpBuffer, DWORD cbLength

);


Table 3.128: os4ReadBinaryFile Error Codes

RemarksNone.

See Alsoos4WriteBinaryFile




OS/4 error ET_APDU_RESP_BADDATALEN

Trying to read at end of file.




os4WriteBinaryFile

The os4WriteBinaryFile function writes data to a binary file.

ParametershTalker[in] Talker handle returned by etCreateTalker.lpszPath[in] Zero-terminated path string.wOffset[in] Offset position in the binary file.lpBuffer[in] Pointer to the data to be stored on the card.cbLength[in] Length, in bytes, of lpBuffer.


DWORD os4WriteBinaryFile (HTALKER hTalker, LPCTSTR lpszPath, WORD wOffset, LPCVOID lpBuffer, WORD cbLength

);


Table 3.129: os4WriteBinaryFile Error Codes

RemarksNone.

See Alsoos4ReadBinaryFile








OS/4 error ET_APDU_RESP_FS_FULL

Trying to write at end of file.


os4ReadTLVFile

The os4ReadTLVFile function reads data from a TLV file.

ParametershTalker[in] Talker handle returned by etCreateTalker.lpszPath[in] Zero-terminated path string.ppBuffer[out] Pointer to a received variable, which serves as a pointer to a result buffer. The application must never attempt to modify or to free this buffer. Furthermore, the application should copy this buffer's data before issuing any other eToken.DLL function calls.lpcbLength[out] Pointer to a variable that receives the actual length, in bytes, of the ppBuffer. This parameter is optional and can be NULL.dwTag[in] Tag value of the TLV record.bFirst[in] If TRUE, handle the first. Otherwise, handle the next record.


DWORD os4ReadTLVFile (HTALKER hTalker, LPCTSTR lpszPath, LPVOID* ppBuffer, LPDWORD lpcbLength, DWORD dwTag, BOOL bFirst

);


Table 3.130: os4ReadTLVFile Error Codes

RemarksNone.

See Alsoos4WriteTLVFile



ERROR_INVALID_PARAMETER The lpszPath or ppBuffer parameter is NULL.




os4WriteTLVFile

The os4WriteTLVFile function writes data to a TLV file.

ParametershTalker[in] Talker handle returned by etCreateTalker.lpszPath[in] Zero-terminated path string.lpBuffer[out] Pointer to the data to be stored on the card.cbLength[in] Length, in bytes, of lpBuffer.dwTag[in] Tag value of the TLV record.bFirst[in] If TRUE, then handle the first. Otherwise, handle the next record.


DWORD os4WriteTLVFile (HTALKER hTalker, LPCTSTR lpszPath, LPVOID lpBuffer, LPDWORD lpcbLength, DWORD dwTag, BOOL bFirst

);


Table 3.131: os4WriteTLVFile Error Codes

RemarksNone.

See Alsoos4ReadTLVFile







os4AppendTLVFile

The os4AppendTLVFile function appends a new record to a TLV file.

ParametershTalker[in] Talker handle returned by etCreateTalker.lpszPath[in] Zero-terminated path string.lpBuffer[out] Pointer to the data to be stored on the card.cbLength[in] Length, in bytes, of lpBuffer.dwTag[in] Tag value of the new TLV record.


DWORD os4AppendTLVFile (HTALKER hTalker, LPCTSTR lpszPath, LPVOID lpBuffer, LPDWORD lpcbLength, DWORD dwTag

);


Table 3.132: os4AppendTLVFile Error Codes

RemarksNone.

See Alsoos4WriteTLVFile







eToken CardOS/M4 High Level RSA Keys Functions API


os4RSAGetKeyInfo

The os4RSAGetKeyInfo function reads the RSA key information about the existing on-token RSA key.

ParametershTalker[in] Talker handle returned by etCreateTalker.lpKeyInfo[in/out] Pointer to an OS4RSAKEYINFO structure, shown below:typedef struct tagOS4RSAKEYINFO

{

} OS4RSAKEYINFO;

DWORD os4RSAGetKeyInfo (HTALKER hTalker, OS4RSAKEYINFO* lpKeyInfo

);


DWORD dwId; // key ID

DWORD cbKeyLength; // modulus & private exponent length in bytes

DWORD dwFlags; // bit flags

DWORD dwReserved1;

DWORD dwReserved2;

LPCVOID

dwReserved

DWORD cbPassword

eToken CardOS/M4 High Level RSA Keys Functions API 271

The dwFlags can be a combination of bit flags, whose values are listed in the table below:

Table 3.133: dwFlag Parameter Values


Table 3.134: os4RSAGetKeyInfo Error Codes

RemarksThis function uses the dwId parameter of the lpKeyInfo structure to determine the RSA key, whose information is to be read.The cbSize parameter of the lpKeyInfo structure must be set to sizeof(OS4RSAKEYINFO) before calling the function.

Value Description

ETOS4_RSA_EXPORTABLE Key is exportable

ETOS4_RSA_REMOVABLE Key is removable

ETOS4_RSA_PUBKEY Key has public keypart

ETOS4_RSA_PRIVKEY Key has private keypart

ETOS4_RSA_USERKEY Key is for private use



ERROR_INVALID_PARAMETER The lpKeyInfo parameter is NULL, or the cbSize parameter of lpKeyInfo structure is invalid.


os4RSAList

The os4RSAList function reads the list of existing RSA keys.

ParametershTalker[in] Talker handle returned by etCreateTalker.ppKeyInfo[out] Pointer to a received variable, which serves as a pointer to the KeyInfo buffer.cbInfoSize[in] Size of each output struct. Must be sizeof(OS4RSAKEYINFO).lpdwCount[out] Pointer to a variable that receives the number of items returned in ppKeyInfo.


Table 3.135: os4RSAList Error Codes

RemarksNone.

DWORD os4RSAList (HTALKER hTalker, OS4RSAKEYINFO* ppKeyInfo, DWORD cbInfoSize,LPDWORD lpdwCount

);




os4RSAGenKeyPair

The os4RSAGenKeyPair function generates an RSA key pair.

ParametershTalker[in] Talker handle returned by etCreateTalker.lpKeyInfo[in/out] Pointer to the KeyInfo buffer.lpModulus[in/out] Pointer to the Modulus buffer.lpPublicExponent[in/out] Pointer to the PublicExponent buffer.


Table 3.136: os4RSAGenKeyPair Error Codes

RemarksThe lpPassword and cbPassword fields of the lpKeyInfo structure can be used for a secondary authentication.

DWORD os4RSAGenKeyPair (HTALKER hTalker, OS4RSAKEYINFO* lpKeyInfo, LPVOID lpModulus,LPVOID lpPublicExponent

);




os4RSARaise

The os4RSARaise function performs an RSA operation.

ParametershTalker[in] Talker handle returned by etCreateTalker.bPublic[in] If TRUE, the function performs…dwId[in] RSA key ID.lpSource[in] Pointer to the Source buffer.cbSourceLength[in] Length, in bytes, of the Source buffer.ppDest[out] Pointer to a received variable, which serves as a pointer to the Dest buffer.lpcbDestLength[out] Pointer to a variable that receives the actual length, in bytes, of the Dest buffer.


DWORD os4RSARaise (HTALKER hTalker, BOOL bPublic, DWORD dwId, LPCVOID lpSource,DWORD cbSourceLength, LPVOID* ppDest, LPDWORD lpcbDestLength

);


Table 3.137: os4RSARaise Error Codes

RemarksNone.




os4RSAExport

The os4RSAExport function exports a RSA public key from an eToken CardOS/M4.

ParametershTalker[in] Talker handle returned by etCreateTalker.dwId[in] RSA key IDppModulus[out] Pointer to a received variable, which serves as a pointer to the Modulus buffer.lpcbModulus[out] Pointer to a variable that receives the actual length, in bytes, of the Modulus buffer.ppPublicExponent[out] Pointer to a received variable, which serves as a pointer to the PublicExponentbuffer.lpcbPublicExponent[out] Pointer to a variable that receives the actual length, in bytes, of the PublicExponent buffer.


DWORD os4RSAExport (HTALKER hTalker, DWORD dwId, LPVOID* ppModulus, LPDWORD lpcbModulus, LPVOID* ppPublicExponent, LPDWORD lpcbPublicExponent

);


Table 3.138: os4RSAExport Error Codes

RemarksNone.




os4RSAImport

The os4RSAImport function imports an RSA key to the eToken CardOS/M4.

ParametershTalker[in] Talker handle returned by etCreateTalker.lpKeyInfo[in] Pointer to an RSA key information structure.lpPrivateExponent[in] Pointer to a new private exponent of the RSA key.lpModulus[in] Pointer to a new modulus of the RSA key.lpPublicExponent[in] Pointer to a new public exponent of the RSA key.cbPublicExponent[in] Length, in bytes, of the PublicExponent buffer.


DWORD os4RSAImport (HTALKER hTalker, OS4RSAKEYINFO* lpKeyInfo, LPCVOID lpPrivateExponent, LPCVOID lpModulus, LPCVOID lpPublicExponent, DWORD cbPublicExponent

);


Table 3.139: os4RSAImport Error Codes

RemarksIf the dwId parameter of the OS4RSAKEYINFO structure is zero, then the new RSA key is stored and dwId receives the new RSA key ID value. Otherwise, the existing RSA key will be imported.The cbSize member of the lpKeyInfo structure must be set to sizeof(OS4RSAKEYINFO) before calling the function.The lpPassword and cbPassword fields of the lpKeyInfo structure can be used for a secondary authentication.



ERROR_INVALID_PARAMETER The lpPrivateExponent, lpModulus, lpPublicExponent or lpKeyInfo parameter is NULL, or the cbSize parameter of the lpKeyInfo structure is invalid.


os4RSADelete

The os4RSADelete function deletes an RSA key pair and frees the memory on the eToken CardOS/M4.

ParametershTalker[in] Talker handle returned by etCreateTalker.dwId[in] RSA key ID to delete.


Table 3.140: os4RSADelete Error Codes

RemarksNone.

DWORD os4RSADelete (HTALKER hTalker, DWORD dwId

);




eToken CardOS/M4 High Level DES Keys Functions API


os4DESGetKeyInfo

The os4DESGetKeyInfo function reads the DES key information about the existing on-token DES key.

ParametershTalker[in] Talker handle returned by etCreateTalker.lpKeyInfo[in/out] Pointer to a DES key information structure. The information is stored in a structure, as shown below:typedef struct tagOS4DESKEYINFO

{

} OS4DESKEYINFO;


Table 3.141: os4DESGetKeyInfo Error Codes

RemarksThe cbSize member of the OS4DESKEYINFO structure must be set to the size of (OS4DESKEYINFO) before os4DESKeyInfo call.The dwFlags member of OS4DESKEYINFO is a combination of flags and algorithm type.

DWORD os4DESKeyInfo (HTALKER hTalker, OS4DESKEYINFO* lpKeyInfo

);


DWORD dwId; // key ID

DWORD dwFlags; // ET_OS4_DES_xxx (see remarks)



eToken CardOS/M4 High Level DES Keys Functions API 283

You can use algorithms as shown below:

Table 3.142: os4DESGetKeyInfo Algorithms

Other possible key flags are shown below:

Table 3.143: os4DESGetKeyInfo Key Flags

Constant Value Meaning

ETOS4_DES_ECB 0x00 Algorithm DES ECB

ETOS4_DES_CBC 0x01 Algorithm DES CBC

ETOS4_DES3_CBC 0x02 Algorithm Triple DES ECB

Constant Value Meaning

ETOS4_DES_REMOVABLE 0x08 This key can be removed

ETOS4_DES_USERKEY 0x10 Key is for private use (login needs)


os4DESList

The os4DESList function reads the list of existing DES keys.

ParametershTalker[in] Talker handle returned by etCreateTalker.ppKeyInfo[out] Pointer to a received variable, which serves as a pointer to the KeyInfo buffer.cbInfoSize[in] Size of each output struct. Must be sizeof(OS4DESKEYINFO).lpdwCount[out] Pointer to the output variable that receives the length of the DES key lists.


Table 3.144: os4DESList Error Codes

RemarksNone.

DWORD os4DESList (HTALKER hTalker, OS4DESKEYINFO** ppKeyInfo,DWORD cbInfoSize,LPDWORD lpdwCount

);




os4DESImport

The os4DESImport function imports a DES key to the eToken CardOS/M4.

ParametershTalker[in] Talker handle returned by etCreateTalker.lpKeyInfo[in] Pointer to a DES key information structure.lpKeyData[in] Pointer to a DES KeyData buffer.cbKeyData[in] Length, in bytes, of the lpKeyData buffer. The length must be divisible by 8.


Table 3.145: os4DRSImport Error Codes

RemarksNone.

DWORD os4DESImport (HTALKER hTalker, OS4DESKEYINFO* lpKeyInfo, LPVOID lpKeyData, DWORD cbKeyData

);




os4DESOperation

The os4DESOperation function….

ParametershTalker[in] Talker handle returned by etCreateTalker.bEncode[in] If TRUE, the function performs…dwId[in] DES key ID.lpSource[in] Pointer to the Source buffer.cbSourceLength[in] Length, in bytes, of the Source buffer.ppDest[out] Pointer to a received variable, which serves as a pointer to the Dest buffer.lpcbDestLength[out] Pointer to a variable that receives the actual length, in bytes, of the Dest buffer.


DWORD os4DESOperation (HTALKER hTalker, BOOL bEncode, DWORD dwId, LPCVOID lpSource, DWORD cbSourceLength, LPVOID* ppDest, LPDWORD lpcbDestLength

);


Table 3.146: os4DESOperation Error Codes

RemarkseToken OS4 uses ISO padding for DES encryption procedures and appends bytes to the input data before performing the encryption. Since the resulting encrypted message length must be divisible by 8, a minimum of 1 byte up to a maximum of 8 bytes is appended. For example, if the input length is 41 bytes, the output length will be 48 bytes (41 + 7 to make it divisible by 8). If the input length is 8 bytes, the output length will be 16 bytes (8 + 8 because at least one byte must be appended and the number must be divisible again by 8).The first appended byte is 0x80 and all the others are 0x00.The padding bytes are automatically removed from decrypted data.




os4DESDelete

The os4DESDelete function deletes a DES key and frees the memory on the eToken CardOS/M4.

ParametershTalker[in] Talker handle returned by etCreateTalker.dwId[in] DES key identifier (index).


Table 3.147: os4DESDelete Error Codes

RemarksNone.

DWORD os4DESDelete (HTALKER hTalker, DWORD dwId

);




eToken CardOS/M4 High Level Certificate Functions


os4CertGetInfo

The os4CertGetInfo function reads the certificate information about an existing certificate.

ParametershTalker[in] Talker handle returned by etCreateTalker.lpCertInfo[in/out] Pointer to the buffer that receives the certificate description.typedef struct tagOS4CERTINFO{

} OS4CERTINFO;

Note: The last two fields in the structure (dwReserved1 and dwReserved2) are reserved because they are used by CAPI and PKCS#11. If you want your certificate to be used by or be visible to CAPI and PKCS#11, we recommend that you work with CAPI and PKCS#11 and not with the eToken API.


DWORD os4CertGetInfo (HTALKER hTalker, OS4CERTINFO* lpCertInfo

);


DWORD dwId; // certificate id (0-63)

DWORD dwFileSize; // certificate file size

DWORD dwReserved1;

DWORD dwReserved2;

eToken CardOS/M4 High Level Certificate Functions 291

Table 3.148: os4CertGetInfo Error Codes

RemarksNone.




os4CertList

The os4CertList function reads the list of existing certificates.

ParametershTalker[in] Talker handle returned by etCreateTalker.ppCertInfo[out] Pointer to the output variable that receives the pointer to teh certificate list.cbInfoSize[in] Size of each output struct. Must be sizeof(OS4CERTINFO).lpdwCount[out] Pointer to the output variable that receives teh length of the certificate list.


Table 3.149: os4CertList Error Codes

RemarksNone.

DWORD os4DESCertList (HTALKER hTalker, OS4CERTINFO** ppCertInfo, DWORD cbInfoSizeLPDWORD lpdwCount

);




os4CertCreate

The os4CertCreate function creates a certificate.

ParametershTalker[in] Talker handle returned by etCreateTalker.lpCertInfo[in] Pointer to a certificate information structure.lpCertData[in] Pointer to a CertData buffer.lpAppData[in] Pointer to an AppData buffer.


Table 3.150: os4CertCreate Error Codes

RemarksNone.

DWORD os4DESCertCreate (HTALKER hTalker, OS4CERTINFO* lpCertInfo, LPCVOID lpCertData, LPCVOID lpAppData

);




os4CertWrite

The os4CertWrite function writes data to a certificate.

ParametershTalker[in] Talker handle returned by etCreateTalker.dwId[in] Certificate ID.lpCertData[in] Pointer to a CertData buffer.cbCertDataLength[in] Length, in bytes, of the CertData buffer.lpAppData[in] Pointer to an AppData buffer.cbAppDataLength[in] Length, in bytes, of the AppData buffer.


Table 3.151: os4CertWrite Error Codes

DWORD os4DESCertWrite (HTALKER hTalker, DWORD dwId, LPCVOID lpCertData, DWORD cbCertDataLength, LPCVOID lpAppData, DWORD cbAppDataLength

);




RemarksNone.


os4CertRead

The os4CertRead function reads the certificate content from the eToken CardOS/M4.

ParametershTalker[in] Talker handle returned by etCreateTalker.dwId[in] Certificate identifier (index).ppCertData[out] Pointer to the output parameter that receives the pointer to the certificate data.lpcbCertDataLength[out] Pointer to the output variable that receives the length, of the ppCertData buffer.ppAppData[out] Pointer to the output parameter that receives the pointer to the certificate extention data.lpcbAppDataLength[out] Pointer to the output variable that receives the length of the ppAppData buffer..


DWORD os4DESCertRead (HTALKER hTalker, DWORD dwId, LPCVOID* ppCertData, LPDWORD lpcbCertDataLength, LPCVOID* ppAppData, LPDWORD lpcbAppDataLength

);


Table 3.152: os4CertRead Error Codes

RemarksNone.




os4CertDelete

The os4CertDelete function deletes a certificate from the eToken CardOS/M4.

ParametershTalker[in] Talker handle returned by etCreateTalker.dwId[in] Certificate identifier (index).


Table 3.153: os4CertDelete Error Codes

RemarksNone.

DWORD os4DESCertDelete (HTALKER hTalker, DWORD dwId

);




eToken Error Codes

eToken functions may produce various error codes. Only error codes specific to the eToken API are listed in this Guide. Additionally, eToken API may return error codes that are listed in the MSDN library.In the descriptions of error codes, we itemise only those codes that are specific errors related to that function. However that function may return a wide variety of error codes. All codes are referenced either in this Guide or in MSDN Reference.Each eToken.dll function can return a nonzero-value error code. These are defined in the WINERROR.H and SCARDERR.H files. Additional error codes defined in eToken.h are listed in the table below:

eToken R2 and eToken CardOS/M4 smart card operations can return the status codes of APDU operations. The success status value (0x9000) is converted to NO_ERROR (0x0000). The eToken.dll converts and presents APDU error codes in Windows error format. The error facility of the eToken R2 and eToken CardOS/M4 is utilized by running the AKS_MAKE_ERROR macro. For example, if an eToken CardOS/M4 operation fails with the status code ET_APDU_RESP_BADSEC, the return code returned from the eToken DLL function will be AKS_MAKE_ERROR(AKS_FACILITY_ETOKEN_OS4, ET_APDU_RESP_BADSEC). This is done to avoid an intersection between eToken internal error codes (which are defined according to the ISO 7816-4 standard) with error codes of various Windows components.

Table 3.154: Error Codes Defined in eToken.h

Name Value DescriptionET_ERROR_NOTINITIALIZED

0xE0010001

eToken.DLL is not initialized yet. First call of eToken.DLL function must be etInitialize


The list of possible status codes are provided in the table below:Table 3.155: APDU Operation Status Codes

Name Value DescriptionET_APDU_RESP_SUCCESS 0x9000 The command was

executed correctly. Returns NO_ERROR.

ET_APDU_RESP_WEAK_ SUCCESS

0x9001 The command was executed correctly. An EEPROM weakness was detected.

ET_APDU_RESP_MEMFAIL 0x6581 EEPROM error. The command is aborted.

ET_APDU_RESP_UNSUPPORTED

0x6800 Unsupported command.

ET_APDU_RESP_BADP1ORP2

0x6a86 P1/P2 invalid.

ET_APDU_RESP_ BADDATALEN

0x6a87 LC does not fit P1/P2.

ET_APDU_RESP_BADSEC 0x6982 Required access right is not granted.

ET_APDU_RESP_FAIL 0x6400 The operation failed.

ET_APDU_RESP_FILEDEACTIVATED

0x6283 The file is deactivated.

ET_APDU_RESP_ AUTHFAILED

0x6300 Authentication failed.

ET_APDU_RESP_ LCINVALID

0x6700 LC invalid.

ET_APDU_RESP_CHANNELNOTSUPPORTED

0x6881 The logical channel is not supported.

ET_APDU_RESP_COMMANDSTRUCTUREBAD

0x6981 This command cannot be used for this structure.

ET_APDU_RESP_BS_ BLOCKED

0x6983 BS object blocked.

ET_APDU_RESP_BS_ BADFORMAT

0x6984 The BS object has an invalid format.

eToken Error Codes 301

ET_APDU_RESP_NORNG 0x6985 No random number is available.

ET_APDU_RESP_NO_EF_ SELECTED

0x6986 No current EF is selected.

ET_APDU_RESP_NO_KEY_FOR_SM

0x6987 Key object for SM not found.

ET_APDU_RESP_BAD_KEY_FOR_SM

0x6988 The key object used for SM has an invalid format.

ET_APDU_RESP_BAD_ DATA_FIELD

0x6a80 Invalid parameter in data field.

ET_APDU_RESP_FUNC_UNSUPPORTED

0x6a81 Function / mode not supported.

ET_APDU_RESP_FILE_NOT_FOUND

0x6a82 File not found.

ET_APDU_RESP_REC_NOT_FOUND

0x6a83 Record or object not found.

ET_APDU_RESP_FS_FULL 0x6a84 Not enough memory in the file or in the file system.

ET_APDU_RESP_TLV_LC_MISMATCH

0x6a85 LC does not fit the TLV structure of the data field.

ET_APDU_RESP_OBJ_NOT_FOUND

0x6a88 Object not found.

ET_APDU_RESP_LE_DATA_MISMATCH

0x6c00 LE does not fit the data to be sent.

ET_APDU_RESP_INVALID_ INS

0x6d00 INS invalid.

ET_APDU_RESP_INVALID_CLA

0x6e00 CLA invalid.

ET_APDU_RESP_TECH_ ERROR

0x6f00 Technical Error.

ET_APDU_RESP_BAD_ CHECKSUM

0x6f81 File is invalidated because of a checksum error.

Table 3.155: APDU Operation Status Codes



ET_APDU_RESP_RAM_ UNAVAILABLE

0x6f82 Not enough memory available in XRAM.

ET_APDU_RESP_BAD_ TRANSACTION

0x6f83 Transaction error.

ET_APDU_RESP_GPF 0x6f84 General protection fault.

ET_APDU_RESP_BAD_ CMSS_FORMAT

0x6f85 Internal failure of PK-API. Wrong CCMS format.

ET_APDU_RESP_KEY_NOT_FOUND

0x6f86 Key object not found.

ET_APDU_RESP_CHAINING_ERROR

0x6f87 Internal hardware attack required.

ET_APDU_RESP_ ASSERTION_FAILED

0x6fff Internal assertion.

ET_APDU_RESP_UFLOW_ OVFLOW

0x9850 Overflow using INCREASE or underflow using DECREASE.

ET_APDU_RESP_NOHOSTMEM

0x6401 Not enough memory on host machine.

ET_APDU_RESP_ INTERNAL

0x6402 Internal (implementation) error.

ET_APDU_RESP_ BADPARAMS

0x6403 The command received bad parameters.

ET_APDU_RESP_NOFILESELECTED

0x6404 No file was selected.

ET_APDU_RESP_BADFILE SELECTED

0x6405 A bad file was selected.

ET_APDU_RESP_FILENOTLEAF

0x6406 The file is not a leaf (It cannot be deleted).

ET_APDU_RESP_BADPATH 0x6407 Bad path (not found).

ET_APDU_RESP_ BADFILEID

0x6408 Illegal File ID.

ET_APDU_RESP_MEMFULL 0x6409 Not enough memory on the token.



eToken Error Codes 303

ET_APDU_RESP_SMALL OUTBUF

0x640a The given output buffer is too small.

ET_APDU_RESP_BADFILESIZE

0x640b File size incorrect.

ET_APDU_RESP_NO MOUNT

0x640c Token unmounted.

ET_APDU_RESP_BADGRANULARITY

0x640d Invalid granularity.

ET_APDU_RESP_BAD TOTALSIZE

0x640e Total of the areas does not equal the file system size.

ET_APDU_RESP_BAD WASTEDAREA

0x640f Total of the areas does not equal the file system size.

ET_APDU_RESP_BADNUM FATENTRIES

0x6410 Number of FAT entries not greater than or equal to 1.

ET_APDU_RESP_BAD SECRETAREASIZE

0x6411 Invalid secret area size.

ET_APDU_RESP_BAD PRIVATEAREASIZE

0x6412 Invalid private area size.

ET_APDU_RESP_BAD PUBLICAREASIZE

0x6413 Invalid public area size.

ET_APDU_RESP_MEM FRAGEMENTED

0x6414 Token memory too fragmented.

ET_APDU_RESP_NOKEY SELECTED

0x6415 No key selected.

ET_APDU_RESP_BADPIN SIZE

0x6416 Bad Pin size.




Chapter4eToken eTocx API

Reference

This chapter details the eToken SDK 32-bit 3.00 eTocx API. It contains the following sections:• eTocx Enumerators, page 306, details the eTocx.dll enumerators.• eTocx Interfaces, page 308, details the eTocx interfaces.• eTocx Error Handling, page 324, describes the eTocx error

handling.

305

305

eTocx Enumerators

Table 4.1 lists the eTocx enumerators.Table 4.1: eTocx Enumerator

Enumerator Values Description PageetHSType ftHSFile = 1

ftHSDir = 2ftHSKey = 3

eToken R2 file types enumeration.Use with HSFileInfo::type.

315

etHSAccess acHSPublic = 0acHSPrivate = 1acHS_1_FactorSecret = 2 (public secret file)acHS_2_FactorSecret = 3 (private secret file)

eToken R2 file access or security attributes enumeration.Use with HSFileInfo::access.

315

etOS4DesKeyFlags kfOS4AlgoMask = 3, (ALGO X MODE))kfOS4DesEcb = 0kfOS4DesCbc = 1kfOS4Des3Cbc = 2kfOS4Removable = 8kfOS4UserKey =16 (Key is for private use)

eToken CardOS/M4 Des Key Flags enumeration.Use with eTokenPro::createBinaryFile / ProFileInfo::access.

318321

etOS4Access acOS4Public = 0acOS4Private = 1acOS4PublicReadonly = 2acOS4PublicNodeltable = 3acOS4PublicReadonlyNoupdate = 4acOS4None = 5acOS4Unknown = ~0U (Not defined by Aladdin)

eToken CardOS/M4 File Access enumeration.Use with eTokenPro::createBinaryFile / ProFileInfo::access

318321

306 eToken eTocx API Reference

etOS4Type ftOS4_EF_BINARY =1ftOS4_EF_LINEAR = 2ftOS4_EF_TLV = 5ftOS4_EF_CYCLIC = 6ftOS4_CODE = 21ftOS4_DF = 38ftOS4_NONE = 255

eToken CardOS/M4 File types. Use with ProFileInfo::type.

321

etOS4PinType pinOS4_USER = 1pinOS4_ADMIN = 2,pinOS4_NOAKS = 4

eToken PRO pin flags (Admin, User, No AKS)Use with eTokenPro3::getPinFlag.

318

Table 4.1: eTocx Enumerator

Enumerator Values Description Page

eTocx Enumerators 307

eTocx Interfaces

This section details the various interfaces, their methods and events.

IByteArray

This a helper interface that is used for creating an array of bytes (either input or output) that is required for all functions. Table 4.2: IByteArray

Prototype Description

HRESULT create([in] long sz, [in] byte fillchar, [in] BOOL copy)

Creates byte array.

HRESULT length([out, retval] long *pVal)

Returns byte array size.

HRESULT get([in] long idx, [out, retval] byte* b)

Gets byte by index.

HRESULT set([in] long idx, [in] byte fc)

Sets byte by index.

HRESULT sLice([in] long begin, [in] long end, [out, retval] IByteArray** s)

Slices byte array from given byte array.

HRESULT create_bstr([in] BSTR str)

Creates a byte-array from a regular (non-serialized) string.

HRESULT create_serialized([in] BSTR data)

Creates a byte array from BSTR data.

HRESULT serialize([out, retval] BSTR* data)

Allows for the reconstruction of a byte-array object at a location other than at which it was created. (For example, web-client/web-server).


IBstrEnum

Simple BSTR enumerator that collects the directory (DF) and returns a list of names. Returned by eToken R2 or eToken CardOS/M4 directory functions.

IeTokenHS

COM wrapper that represents an eToken R2. Gives access to file system, password and DESX functionality. All directory paths used must be absolute.

Table 4.3: IBstrEnum


HRESULT next([out, retval] BSTR* s)

Gets or returns next BSTR enumerator element.

HRESULT skip([in] ULONG cell)

Skips on specific enumerator element.

HRESULT reset() Resets enumerator container for all BSTR elements.

Table 4.4: IeTokenHS


HRESULT attach([in] BSTR readerName)

Attaches the IeTokenHS object to a reader. (Before calling any functions that access an eToken, you must attach the IeTokenHS object to a reader.) The readerName parameter indicates the reader to be attached to.See “etStartListen”, page 86.

HRESULT detach() Detaches the IeTokenHS object from the reader it is attached to.See “etStopListen”, page 88.

HRESULT lock() Locks the eToken to prevent other applications from accessing the eToken while you work.lock() and unlock() calls must be made from the same thread. See “etLockReader”, page 75.

eTocx Interfaces 309

HRESULT unlock() Releases a locked eToken. See “etUnlockReader”, page 76.

HRESULT login([in] IByteArray* pPassword)

Logs in to eToken using the password. See “r2Login”, page 199.See “IByteArray”, page 308.

HRESULT logout() Logs out from the eToken. See “r2Logout”, page 201.

HRESULT changePassword([in] IByteArray *pPassword)

Changes the eToken password to a new password. Must be loggged in first. See “r2ChangePassword”, page 202.See “IByteArray”, page 308.

HRESULT getconf([out, retval] IeTokenHSConfig** ppcfg)

Retrieves an eToken R2 configuration struct. The ppcfg parameter represents the eToken R2 configuration interface. See “r2ApduGetConfig”, page 111.See “IeTokenHSConfig”, page 314.

HRESULT dir([in] BSTR path, [out,retval] IBstrEnum** ppEnum)

Reads the contents of the current DF. The ppEnum parameter retrieves contents by using a BSTR enumerator. See “r2Directory”, page 207.See “IBstrEnum”, page 309.

HRESULT getFileInfo([in] BSTR path, [out,retval] IHSFileInfo** ppinfo)

Selects a given file and returns the file’s information using the IHSFileInfo interface.See “r2GetFile Info”, page 205.See “IeTokenHSFileInfo”, page 315.




HRESULT isFileExist([in] BSTR path, [out, retval] BOOL* fileExist)

Returns TRUE if a given file exists. See “r2GetFile Info”, page 205.

HRESULT readFile([in] BSTR path, [in] long offset, [in] long length, [out, retval] IByteArray** ppdata)

Reads data, starting at the point indicated by the offset, from a given file. This enables data to be segmented.Returns data using the IByteArray interface. See “r2ReadFile”, page 217.See “IByteArray”, page 308.

HRESULT writeFile([in] BSTR path, [in] long offset, [in] IByteArray* data)

Writes data, starting at the point indicated by the offset, to a given file. This enables data to be segmented.Data is written using the IByteArray interface. See “r2WriteFile”, page 219.See “IByteArray”, page 308.

HRESULT writeKey([in]BSTR path, [in] IByteArray* data)

Writes 16-byte key data to a key file. Data is written using the IByteArray interface. See “r2WriteKey”, page 221.See “IByteArray”, page 308.

HRESULT createFile([in] BSTR path, [in] long size, [in] BOOL bprivate)

Creates a file (EF) under the current DF. The file size and type are inputs.bprivate indicates the access type of the new file (true = private, false = public).See “r2CreateFile”, page 211.




HRESULT createKey([in] BSTR path, [in] BOOL boneFactor)

Creates a key file(KF) under the current DF. The file size and type are inputs.If boneFactor is true = 1 factor, if false = 2 factor. If 2 factor is used, login to the eToken first.See “r2CreateKey”, page 213.

HRESULT createDirectory([in] BSTR path, [in] BOOL bprivate)

Creates a directory (DF) under the current DF.bprivate indicates the access type of the new directory (true = private, false = public). See “r2CreateDirectory”, page 209.

HRESULT del([in] BSTR path)

Deletes the current EF, KF or DF. The path is an absolute path.To delete a parent directory, first delete the child directories. See “r2Delete”, page 215.

HRESULT desx([in] BSTR path, [in] BOOL encrypt, [in] IByteArray* psrc, [out, retval] IByteArray** ppdata)

Implements DESX, using ECB cipher mode and PKCS #5 padding, and accepts variable length byte-buffers for encryption. See “r2Desx”, page 223.




IeTokenHS2

IeTokenHS2 interface inherits from the IeTokenHS interface.Table 4.5: IeTokenHS2


HRESULT errorString([in] long err, [out,retval] BSTR* pErrString)

Converts an error from a number to a string. For a list of the error numbers, see eToken.h.

HRESULT getTokenName([out, retval] IByteArray** ppdata)

Get eToken R2 name (Label)See “r2GetTokenName”, page 193

HRESULT setTokenName([in] IByteArray* pdata)

Set eToken R2 name (LabelSee “r2SetTokenName”, page 194


IeTokenHSConfig

Represents an eToken R2 configuration. All these methods are properties in property-supporting environments.

Note: For further info, see “r2GetTokenInfo”, page 188

Table 4.6: IeTokenHSConfig


HRESULT tokenId([out, retval] long *pVal)

Retrieves the unique 32 bit eToken ID.

HRESULT eTokenVersion([out, retval] short *pVal)

Retrieves the eToken FW version.

HRESULT fsSize([out, retval] short *pVal)

Retrieves the eToken file system size.

HRESULT publicUsed([out, retval] short *pVal)

Retrieves the amount of public memory used. .

HRESULT privateUsed([out, retval] short *pVal)

Retrieves the amount of private memory used.

HRESULT factor1Used([out, retval] short *pVal)

Retrieves the amount of 1 factor memory used.

HRESULT factor2Used([out, retval] short *pVal)

Retrieves the amount of 2 factor memory used.

HRESULT freeSpace([out, retval] short *pVal)

Retrieves the file system free space.

HRESULT color([out, retval] short *pVal)

Retrieves the R2 eToken color.


IeTokenHSFileInfo

Represents eToken R2 file information properties. All these methods are properties in property-supporting environments.

Note: For further information, see “r2GetFile Info”, page 205.

IeTokenPro

Represents an eToken CardOS/M4. Provides access to file-system and password functionality.

Table 4.7: IeTokenHSFileInfo


HRESULT access([out, retval] short *pVal)

Retrieves file access. Uses the etHSAccess enumerator. See “eTocx Enumerators”, page 306.

HRESULT type([out, retval] short *pVal)

Retrieves the file type. Uses the etHSType enumerator. See “eTocx Enumerators”, page 306

HRESULT length([out, retval] short *pVal)

Retrieves file size information.

Table 4.8: IeTokenPro


HRESULT attach([in] BSTR readerName)

Attaches the IeTokenPro object to a reader. (Before calling any methods that access an eToken, you must attach the IeTokenPro object to a reader.) The readerName parameter indicates the reader to be attached to.See “etStartListen”, page 86.

HRESULT detach() Detaches the IeTokenPro object from the reader it is attached to. See “etStopListen”, page 88.


HRESULT lock() Locks the eToken to prevent other applications from accessing the eToken while you work.lock() or unlock() calls must be made from the same thread. See “etLockReader”, page 75.

HRESULT unlock() Releases a locked eToken. See “etUnlockReader”, page 76.

HRESULT login([in] IByteArray* password)

Logs in to eToken using the password. See “os4Login”, page 240.See “IByteArray”, page 308.

HRESULT logout() Logs out from the eToken. See “os4Logout”, page 242.

HRESULT changePassword([in] IByteArray* password)

Changes the eToken password to a new password. Must be loggged in first. See “os4ChangePassword”, page 243.See “IByteArray”, page 308.

HRESULT getConf([out, retval] IeTokenProConfig** ppcfg)

Retrieves an eToken CardOS/M4 configuration struct.The ppcfg parameter represents the eToken CardOS/M4 configuration interface. See “os4GetProperty”, page 235.See “IeTokenProConfig”, page 320.

HRESULT dir([in] BSTR path, [out, retval] IBstrEnum** ppEnum)

Reads the contents of the current DF. The ppEnum parameter retrieves contents using a BSTR enumerator. See “os4Directory”, page 252.See “IBstrEnum”, page 309.




HRESULT del([in] BSTR path)

Deletes the current EF or DF. The path is an absolute path.To delete a parent directory, first delete the child directories.See “os4Delete”, page 259.

HRESULT createBinaryFile([in] BSTR path, [in] long size, [in] long ac)

Creates a file (EF) under the current DF. The absolute path, file size and access are inputs.The access type, ac, uses the etHSAccess enumerator.See “eTocx Enumerators”, page 306.See “os4CreateFile”, page 257.

HRESULT writeBinaryFile([in] BSTR path, [in] long offset, [in] IByteArray* pData)

Writes data, starting at the point indicated by the offset, to a given file. This enables data to be segmented.Data is written using the IByteArray interface. See “os4WriteBinaryFile”, page 262.See “IByteArray”, page 308.

HRESULT readBinaryFile([in] BSTR path, [in] long offset, [in] long length, [out, retval] IByteArray** ppdata)

Reads data, starting at the point indicated by the offset, from a given file. Returns data using the IByteArray interface. See “os4ReadBinaryFile”, page 260.See “IByteArray”, page 308.

HRESULT isFileExist( [in] BSTR path, [out, retval] BOOL* fileExist)

Returns TRUE if a given file exists. See “os4GetFileInfo”, on page 249.




IeTokenPro2

IeTokenPro2 interface inherits from the IeTokenPro interface.

IeTokenPro3

IeTokenPro3 interface inherits from the IeTokenPro2 interface.

Table 4.9: IeTokenPro2


HRESULT createDirectory([in] BSTR path, [in ] etOS4Access ac)

Creates a directory (DF) under the current DF.The access type, ac, uses the etHSAccess enumerator.See “eTocx Enumerators”, page 306.See “os4CreateDirectory”, page 255.



HRESULT listDesKeys([out] VARIANT* pVar)

Retrieves the Des key list using a VARIANT array. Each field is two bytes - the first byte is the key id and the second byte is a key flag (as specified in etOS4DesKeyFlags). See “eTocx Enumerators”, page 306.See “os4DESList”, page 285.

HRESULT importDesKey( [in] IByteArray* ppkey, [in] byte flags, [out,retval] byte* keyid)

Imports or creates a Des key. The data and key flags are inputs and the key id is retrieved.See “os4DESImport”, page 286.

HRESULT removeDesKey([in] byte keyid)

Deletes a given key identified by its id. See “os4DESDelete”, page 289.

HRESULT desEncrypt([in] byte keyid, [in] IByteArray* ppin, [out,retval] IByteArray** ppout)

Encrypts data using the DES key, and retrieves encrypted data.See “os4DESOperation”, page 287.


HRESULT desDecrypt([in] byte keyid, [in] IByteArray* ppin, [out,retval] IByteArray** ppout)

Decrypts encrypted data by using the DES key, and retrieves the original data. See “os4DESOperation”, page 287.

HRESULT getFileInfo( [in] BSTR path, [out,retval] IProFileInfo** ppinfo)

Selects a given file and returns the file information using the IProFileInfo enumerator.See “eTocx Enumerators”, page 306.See “os4GetFileInfo”, page 249.

HRESULT errorString([in] long err, [out,retval] BSTR* pErrString)

Converts an error from a number to a string. For the list of errors, see eToken.h.

HRESULT loginAdmin([in] IByteArray* password)

Logs in to an eToken as an administrator. (Only if formatted with admin password.) See “os4LoginAdmin”, page 241.

HRESULT logoutAdmin() Logs out from administrator mode. See “os4Logout”, page 242.

HRESULT changePasswordAdmin([in] IByteArray *password)

Changes the admin password. (Only an administrator can change the password.)See “os4ChangePasswordAdmin”, page 247.

HRESULT cardId([out, retval] IByteArray** cardId)

Retrieves the smartcard chip id. See “os4GetProperty”, page 235.

HRESULT createPassword([in] IByteArray* password, [in] byte errorCounter )

As an administrator, recreates the user password.See “os4CreatePassword”, page 245.




IeTokenProConfig

Represents an eToken CardOS/M4 configuration properties. All these methods are properties in property-supporting environments.

HRESULT label([out, retval] IByteArray** ppdata)

Get eToken PRO name (Label). Data can be a maximum of 32 characters.

HRESULT setLabel([in] IByteArray* ppdata)

Set eToken PRO name (Label). Data can be a maximum of 32 characters.

HRESULT os4GetPinFlag([ent, retval] long* pVal)

Gets eToken Pin flagPIN presentation flags. Can be combination of: pinOS4_USER,pinOS4_ADMIN, pinOS4_NOAKS.

Table 4.11: IeTokenProConfig


HRESULT tokenId([out, retval] long *pVal)

Retrieves the unique 32 bit eToken ID. See “os4GetProperty”, page 235.

HRESULT color([out, retval] short *pVal)

Retrieves the eToken color. Options listed in eToken.h file.See “os4GetProperty”, page 235.

HRESULT freeSpace([out, retval] long *pVal)

Retrieves the file system free space. See “os4GetProperty”, page 235.




IeTokenProConfig2

IeTokenProConfig2 interface inherits from the IeTokenProConfig interface.

IProFileInfo

Represents eToken CardOS/M4 file information. All these methods are properties in property-supporting environments.

Note: For further information, see “os4GetFileInfo”, page 249.

Table 4.12: IeTokenProConfig2


HRESULT fwVer([out, retval] short *pVal)

Retrieves the eToken CardOS/M4 FW version. See “os4GetProperty”, page 235.

HRESULT eeSize([out, retval] long *pVal)

Retrieves the eToken file system size - eTos4_Prop_EEpromsize.

HRESULT fips([out, retval] BOOL *pVal)

Returns TRUE if FIPS mode is enabled. See “os4GetProperty”, page 235.

HRESULT isSmartCard([out, retval] BOOL *pVal)

Returns TRUE if working with real smartcard. See “etGetReaderInfo”, page 81.

Table 4.13: IProFileInfo


HRESULT access([out, retval] short *pVal)

Retrieves the file access. Uses the etOS4Access enumerator.

HRESULT type([out, retval] short *pVal)

Retrieves the file type. Uses the etOS4Type enumerator.

HRESULT length([out, retval] short *pVal)

Retrieves the file size information.


ITracker

Provides two mechanisms:• Gets a snapshot view of the readers.For details, please refer to Table 4.14 on page 322.• Tracks eToken and Smart Card notification.For details, please refer to Table 4.15 on page 323

Note: The names for eToken R2 and PRO have been changed from those used previously - “eTokenHS” is now called “eToken R2” and “eTokenOS4 (T1 16k/32k)” is now called “eToken OS4”. For “eToken OS4” use the IetokenPRO::getConf function to determine whether the token is 16k or 32k.You should ensure that the new names are used across the code.

All ITracker objects use one internal additional threads.Table 4.14: ITracker


HRESULT snapshot( [out, retval] IBstrEnum** ppreaders)

Returns an enumeration of the current readers on the host.

HRESULT getCardInReader( [in] BSTR readerName, [out,retval] BSTR* pCardName)

Determines whether or not an eToken or card is inserted, and which card it is.You enter the readerName and retrieve the cardName, as it is defined in this reader. Optional Card Names: "eToken R2" , "eToken OS4" To retrieve additional card information use the token getconf() method. See “etGetReaderInfo”, page 81.


.

Note:When an eToken is inserted and the ITracker object is created, an event will be sent per reader about its actual state.For example, the following will be the result after a single eToken is inserted:

"AKS ifdh 0" - CardInserted"AKS ifdh 1" - CardRemoved

VB Example Code for Snapshot functionA VB Example Code is provided below:Private Sub tracker_cardRemoved(ByVal readername As String)Private Sub tracker_cardInserted(ByVal readername As String)

…Dim readers As ObjectSet readers = tracker.snapshotDoreadername = readers.NextIf readername = "" Then Exit DotokenType = tracker.getCardInReader(readername)

Loop

Table 4.15: ITrackerEvents


HRESULT cardInserted([in] BSTR readerName)

Retrieves the insertion event by implementing the ITrackerEvents interface.The readerName indicates on which reader the event occurred ("altered reader"). See “etGetReaderChanged”, page 89.

HRESULT cardRemoved([in] BSTR readerName)

Retrieves the removal event by implementing the ITrackerEvents interface.The readerName indicates on which reader the event occurred ("altered reader"). See “etGetReaderChanged”, page 89.


eTocx Error Handling

eTocx objects return an HRESULT that indicates an operation’s return value. The HRESULT may indicate a general communication error or an APDU status code.

Note: HRESULT: A value returned from a function call to an interface, consisting of a severity code, context information, a facility code, and a status code that describes the result.For more details, please refer to “eToken Error Codes”, on page 300.

To convert the error number to an error string, use the eToken R2 or eToken CardOS/M4 token object errorString( ) method. The table below lists the return value options for all the interface methods.

Note: The APDU status declarations appear in the eToken.h file.

Whether you are handling errors in VBA or in script, there are two basic tools you can use:• On Error statement: Enables error handling in a procedure. • Err object: Contains information about an error that has already

occurred. This must be cleared prior to the operation.

Table 4.16: Return Values for all Interface Methods

Return Value Description

0 = S_OK The operation was successful.

APDU status HRESULT Low 16bits (0-15). For further details, see Appendix E.The APDU status can be converted to a string by using the errorString( ) method.

E_INVALIDARG One or more arguments are invalid.

COM Error A COM error exception converts to HRESULT.(HRESULT)e.Error()

E_UNEXPECTED A severe failure occurred.The method returns an unknown exception.


A VB Example Code is provided below:VB Example Code…On Error Resume NextErr.Clear… If Not (Err.Number = 0) Then MsgBox ("Procedure Failed,error 0x" & CStr(Hex(Err.Number)) & vbCrLf & "Description :" & token.errorString(Err.Number))

Err.Clear Exit Sub End If…

Note: ... above denotes any token operation.

eTocx Error Handling 325

Chapter5Samples

This chapter includes the following sections:• eToken APDU Samples, page 328

• eToken R2 APDU Samples, page 328• eToken CardOS/M4 APDU Samples, page 334

• eToken Application Aid (eTAID) Sample, page 347• CAPI Samples, page 352• PKCS #11 Samples, page 353• eTocx Samples, page 354

Note: Use of these samples may cause data on the eToken to be deleted. It is advisable to use a test eToken when running any of the samples.

327

327

eToken APDU Samples

The following APDU samples are provided with the SDK:• eToken R2 APDU Samples, page 328• eToken CardOS/M4 APDU Samples, page 334

eToken R2 APDU Samples

Table 5.1 provides an overview of the eToken R2 APDU samples supplied with the SDK, and shows where you can find further details of each sample.Table 5.1: eToken R2 APDU Samples Overview

Name Sample Description Page

BinaryFile Binary File Sample

Creates a binary file on the eToken, writes data to the file, reads it and deletes the file.

330

Directory Directory Sample

Reads the contents of the current directory file on the eToken and prints its contents.

330

Cat File Concatenation Sample

Creates an EF file on the eToken, and writes data from two other files into it.

331

GetConfig Get Configuration Sample

Retrieves and prints the eToken configuration information.

331

KeyFile KeyFile Sample Creates a DESX key file on the eToken, writes data to it, performs a DESX operation and deletes the file.

332

LoginLogout Login-Logout Sample

Changes the eToken password, logs in with the new password and changes it back.

332

328 Samples

r2Time Time Measurement Sample

Measures common operations on the eToken R2, such as file creation, file writing and reading, file deletion, key creation and key use with different security attributes, and displays the results in human readable format.

333

r2Tree Tree Sample Recursively enumerates the eToken R2 file structure. Similar to the DOS 6.22 TREE.EXE utility.

333

Table 5.1: eToken R2 APDU Samples Overview


eToken APDU Samples 329

Binary File SamplePath: ...\Samples\eToken\APDU\R2\BinaryFile.This sample creates a binary file on the eToken, writes data to the file, reads it and deletes the file. The sample steps and API usage are outlined in Table 5.2.

Directory SamplePath: ...\Samples\eToken\APDU\R2\Directory.This sample reads the contents of the current directory file on the eToken and prints its contents, as outlined in Table 5.3.

Table 5.2: Binary File Sample

Sample steps API Usage Page

1. Log in to the eToken using a user-supplied password.

r2ApduVerify 92

2. Create EF file. r2ApduCreateFile 97

3. Select the file. r2ApduSelectFile 102

4. Write data into the file. r2ApduWriteBinaryFile 106

5. Read from the file. r2ApduReadBinaryFile 104

6. Delete the file. r2ApduDeleteFile 99

7. Log out from the eToken. r2ApduResetSecState 117

Table 5.3: Directory Sample

Sample steps API usage Page

1. Retrieve a list of smart card readers and their current states.

eTSnapShot Class in eTAID.h

83

2. Read the contents of the directory. r2ApduDirectory 100

3. For every file in the directory command list, print the file name.

330 Samples

File Concatenation SamplePath: ...\Samples\eToken\APDU\R2\Cat.This sample creates an EF file on the eToken, and writes data from two other files into it, as outlined in Table 5.4.

Get Configuration SamplePath: ...\Samples\eToken\APDU\R2\GetConfig.This sample, outlined in Table 5.5, retrieves and prints the eToken configuration information. It demonstrates the usage of the r2ApduGetConfig functions and the format of the response.

Table 5.4: File Concatenation Sample



r2ApduVerify 92

2. Select two MF files and create an EF file with size equal to the sum of the sizes of the two MF files.

r2ApduSelectFiler2ApduCreateFile

10297

3. Copy the data from both files to the new file, in blocks of 128 bytes.

r2ApduSelectFiler2ApduReadBinaryFiler2ApduSelectFiler2ApduWriteBinaryFile

102104102106


Table 5.5: Get Configuration Sample


1. Perform the Get Configuration command.

r2ApduGetConfigr2ApduGetConfig2

111113

2. Print the configuration.


KeyFile SamplePath: ...\Samples\eToken\APDU\R2\KeyFile.This sample creates a DESX key file on the eToken, writes data to it, performs a DESX operation and deletes the file. It uses the API functions relevant for cryptographic tasks, as outlined in Table 5.6.

Login-Logout SamplePath: ...\Samples\eToken\APDU\R2\LoginLogout.This sample changes the eToken password, logs in with the new password and changes it back. The sample steps and API usage are outlined in Table 5.7.

Table 5.6: KeyFile Sample



r2ApduVerify 92

2. Create DESX key file. r2ApduCreateFile 97

3. Select key file. r2ApduSelectFile 102

4. Write data to key file. r2ApduWriteKey 108

5. Perform DESX operation. r2ApduDesxOperation 109

6. Delete key file. r2ApduDeleteFile 99


Table 5.7: Login-Logout Sample



r2ApduVerify 92

2. Change to a new user-supplied password.

r2ApduChangeCode 94

3. Log in with new password. r2ApduVerify 92

4. Change back to the original user-supplied password.

r2ApduChangeCode 94


332 Samples

Time Measurement SamplePath: ...\Samples\eToken\APDU\R2\r2Time.This sample measures common operations on the eToken R2, such as file creation, file writing and reading, file deletion, key creation and key use with different security attributes, and displays the results in human readable format. The sample steps and API usage are outlined in Table 5.8.

Tree SamplePath: ...\Samples\eToken\APDU\R2\r2Tree.This sample performs a recursive enumeration of the eToken’s file structure. The output is similar to the DOS 6.22 tree utility. The sample steps and API usage are outlined in Table 5.9.

Table 5.8: Time Measurement Sample


1. Log in to the eToken. r2ApduVerify 92

2. Create EF file, measure time taken.

r2ApduCreateFile 97

3. Write to and read from the privatea nd public files. Measure the time for each operation.

r2ApduSelectFiler2ApduWriteBinaryFiler2ApduSelectFiler2ApduReadBinaryFile

102106102104

4. Perform various DESX operations, encryption and decryption. . Measure the time taken for each operation with 1 and 2 factor keys.

r2ApduWriteKeyr2ApduDesxOperation

108109

5. Delete the files, measure time taken.

r2ApduSelectFiler2ApduDeleteFile

10299


Table 5.9: Tree Sample


1. Read the contents of the directory. r2ApduDirectory 100

2. Select a specific file. r2ApduSelectFile 102


eToken CardOS/M4 APDU Samples

Table 5.10 provides an overview of the eToken CardOS/M4 APDU samples supplied with the SDK, and shows where you can find further details of each sample.Table 5.10: eToken CardOS/M4 APDU Samples Overview


AccessControl Access Conditions Sample

Sets up a binary file on the eToken with specific access conditions, and tests these access conditions.

336

Binary Binary File Sample

Creates a binary file on the eToken, writes data to the file, reads it and deletes the file.

337

CBC DES-CBC/3DES-CBC Samples

Shows the usage of all APIs relevant for both DES-CBC and 3DES-CBC algorithms.

337

DigitalSignature Digital Signature Sample

Shows the usage of all APIs relevant for Digital Signatures, and the sequence of commands needed to create RSA key pairs for signature and verification.

338

Directory Directory Sample

Reads the contents of the current directory file on the eToken and prints its contents.

339

GetConfig Get Configuration Sample

Retrieves and prints the eToken configuration information.

339

MAC MAC Sample Computes an external MAC and verifies it with the eToken.

340

PinTestSM Pin Test SM Sample

Creates a PIN test, creates a DES key and protects the verify operation by using the DES key as a secure messaging key.

341

EfRecFile Record File Sample

Shows the usage of the APIs relevant for record files, using a CYCLIC FIXED file.

342

334 Samples

Note: All APDU samples only work with non-FIPS mode tokens.

RSA RSA Sample Generates an RSA key pair and performs encryption and decryption.

343

smBinary Secure Messaging Sample

Shows the usage of secure messaging with file access conditions.

344

os4Time Time Measurement Sample

Measures common operations on the eToken, such as file creation, file writing and reading, file deletion, key creation and key use with different security attributes, and displays the results in human readable format.

345

TLVfile TLV File Sample

Shows the usage of all APDUs relevant for TLV files.

346

os4Tree Tree Sample Recursively enumerates the eToken file structure. Similar to the DOS 6.22 TREE.EXE utility.

346

Table 5.10: eToken CardOS/M4 APDU Samples Overview



Access Conditions SamplePath: ...\Samples\eToken\APDU\OS4\AccessControl.This sample sets up a binary file on the eToken with specific access conditions, and tests these access conditions. The sample steps and API usage are outlined in Table 5.11.Table 5.11: Access Conditions Sample


1. Create a 3DES MAC test. os4ApduSelectFileos4ApduCreateBS

152171

2. Create binary EF with passing the test as condition to read this file.

os4ApduCreateFile 155

3. Write to this file. os4ApduWriteBinary 129

4. Try to read this file to show that you cannot read the file without passing the test.

os4ApduReadBinary 132

5. Pass the test. os4ApduGetChallengeos4ApduExtAuthenticate

150120

6. Read the file. os4ApduReadBinary 132

7. Revoke test passing. os4ApduResetSecState 117

8. Attempt to read the file to confirm that you cannot read it without passing the test.


9. Change access condition for existing file using the Admin file APDU.

os4ApduAdminFile 158


11. Delete the file. os4ApduDeleteFile 157

336 Samples

Binary File SamplePath: ...\Samples\eToken\APDU\OS4\Binary.This sample sets up a binary file on the eToken, writes data to the file, reads it and deletes the file. The sample steps and API usage are outlined in Table 5.12.

DES-CBC/3DES-CBC SamplesPath: ...\Samples\eToken\APDU\OS4\CBC.This sample shows the usage of all APIs relevant for both DES-CBC and 3DES-CBC algorithms, as outlined in Table 5.13.

Table 5.12: Binary File Sample


1. Select MF. os4ApduSelectFile 152

2. Create binary EF. os4ApduCreateFile 155

3. Write to the file. os4ApduWriteBinary 129



Table 5.13: DES-CBC/3DES-CBC Samples


1. Select the MF. os4ApduSelectFile 152

2. Create a key BS object with the algorithm.

os4ApduCreateBS 171

3. Create security environment. os4ApduCreateSE 174

4. Restore security environment. os4ApduMSERestore 162

5. Encrypt plain text. os4ApduPSOEnc 175

6. Decrypt cipher text. os4ApduPSODec 177


Digital Signature SamplePath: ...\Samples\eToken\APDU\OS4\DigitalSignature.This sample shows the usage of all APIs relevant for Digital Signatures. It also shows the sequence of commands needed to create RSA key pairs for signature and verification. The sample gets a parameter name of the file to sign. The main sample steps and API usage are outlined in Table 5.14.Table 5.14: Digital Signature Sample


1. Generate 512-bit length RSA key pair.

os4ApduGenKeyPair 164

2. Create security environment for signature.

os4ApduCreateSE 174

3. Restore security environment for signature.

os4ApduMSERestore 162

4. For each 64-byte block of data to sign, sign “not final”.

os4ApduPSOSign 181

5. For last, less than 64-byte block, sign final.

os4ApduPSOSign 181

6. Create security environment for verification.

os4ApduCreateSE 174

7. Restore security environment for verification.


8. For each 64-byte block of data to verify, verify “not final”.

os4ApduPSOVerify 183

9. For last, less than 64-byte block, verify final.

os4ApduPSOVerify 183

338 Samples

Directory SamplePath: ...\Samples\eToken\APDU\OS4\Directory.This sample reads the contents of the current directory file on the eToken and prints its contents, as outlined in Table 5.15.

Get Configuration SamplePath: ...\Samples\eToken\APDU\OS4\GetConfig.This sample, outlined in Table 5.16, retrieves and prints the eToken configuration information. It demonstrates the usage of the os4ApduGetData function and the format of the response.

Table 5.15: Directory Sample


1. Read the contents of the directory. os4ApduSelectFileos4ApduDirectory

152160

2. For every file in the directory command list, print the file name.

Table 5.16: Get Configuration Sample


1. Call the os4ApduGetData function for several card parameters.

os4ApduGetData 126

2. Print the configuration.


MAC SamplePath: ...\Samples\eToken\APDU\OS4\MAC.This sample computes an external MAC and verifies it with the eToken. The sample gets a parameter name of the file to sign. The sample steps and API usage are outlined in Table 5.17.Table 5.17: MAC Sample



2. Create a BS MAC object. os4ApduCreateBS 171

3. Create security environment. os4ApduCreateSE 174

4. Restore security environment. os4ApduMSERestore 162

5. Calculate MAC with the eToken. os4ApduPSOComputeChecksum

167

6. Calculate an external MAC using the same key.

7. Verify externally calculated MAC with the eToken.

os4ApduPSOVerifyChecksum

165

340 Samples

Pin Test SM SamplePath: ...\Samples\eToken\APDU\OS4\PinTestSM.This sample shows how to create a PIN test, create a DES key and protect the verify operation by using the DES key as a secure messaging key. The sample steps and API usage are outlined in Table 5.18.Table 5.18: Pin Test SM Sample


1. Create DES CBC Secure Messaging Object.

os4ApduCreateBS 171

2. Create Pin Test BS Object. os4ApduCreateBS 171

3. Connect the Pin Test with the CBC SM Object.

os4ApduCreateBS 171

4. Create file with read only access after passing the Pin test.

os4ApduCreateFileos4ApduWriteBinary

155129

5. Try to read without passing the Pin test.


6. Pass the Pin test with verify command.

os4ApduVerifySM 124

7. Read data after passing the Pin test.



Record File SamplePath: ...\Samples\eToken\APDU\OS4\EfRecFile.This sample shows the usage of the APIs relevant for record files, using a CYCLIC FIXED file. The APIs operate in a very similar way with LINEAR FIXED files. The sample steps and API usage are outlined in Table 5.19.Table 5.19: Record File Sample


1. Select MF. os4ApduSelectFile 152

2. Create cyclic record EF file. os4ApduCreateFile 155

3. Append record. os4ApduAppendRecord 139

4. Write record. os4ApduWriteRecord 146

5. Increase record. os4ApduIncreaseRecord 135

6. Decrease record. os4ApduDecreaseRecord 137

7. Read record. os4ApduReadRecord 148

8. Delete file. os4ApduDeleteFile 157

342 Samples

RSA SamplePath: ...\Samples\eToken\APDU\OS4\RSA.This sample, outlined in Table 5.20, generates an RSA key pair and performs encryption and decryption. Table 5.20: RSA Sample


1. Create basic security object. os4ApduCreateBS 171

2. Generate a 512-bit RSA key pair. os4ApduGenKeyPair 164

3. Create security environment to encrypt.

os4ApduCreateSE 174

4. Restore security environment to encrypt.


5. Encrypt. os4ApduPSOEnc 175

6. Create security environment to decrypt.

os4ApduCreateSE 174

7. Restore security environment to decrypt.


8. Decrypt. os4ApduPSODec 177


Secure Messaging SamplePath: ...\Samples\eToken\APDU\OS4\smBinary.This sample, outlined in Table 5.21, shows the usage of secure messaging with file access conditions.Table 5.21: Secure Messaging Sample



2. Create a 3DES SM object. os4ApduCreateBS 171

3. Create a binary-EF file with Access Conditions specifying Read/Write using secure messaging with the object created in step 2.

os4ApduCreateFile 155

4. Write to the file using secure messaging.

os4ApduWriteBinarySM 130

5. Read the file using secure messaging.

os4ApduReadBinarySM 133


344 Samples

Time Measurement SamplePath: ...\Samples\eToken\APDU\OS4\os4TimeMeasures common operations such as file creation, file writing and reading, file deletion, key creation, key use with different security attributes and displays the results in human readable format.

The sample steps and API usage are outlined in Table 5.22.Table 5.22: Time Measurement Sample


1. Create file, measure time taken. os4ApduCreateFile 155

2. Read from and write to the file, with and without SM (Secure Messaging). Measure the time for each operation.

os4ApduSelectFileos4ApduReadBinaryos4ApduSelectFileos4ApduWriteBinary

152132152129

3. Perform various DES, DES3, RSA, SHA_1 operations, including encryption, decryption and hashing. Measure the time taken for each operation.

os4ApduCreateBSos4ApduCreateSEos4ApduMSERestoreos4ApduPSOEncos4ApduPSOHash

171174162175179

4. Delete the files, measure time taken.

os4ApduSelectFileos4ApduDeleteFile

152157


TLV File SamplePath: ...\Samples\eToken\APDU\OS4\TLVfile.This sample shows the usage of all APIs relevant for TLV files. The sample steps and API usage are outlined in Table 5.23.

Tree SamplePath: ...\Samples\eToken\APDU\OS4\os4Tree.This sample performs a recursive enumeration of the eToken’s file structure. The output is similar to the DOS 6.22 tree utility. The sample steps and API usage are outlined in Table 5.24.

Table 5.23: TLV File Sample



2. Create a binary-TLV file. os4ApduCreateFile 155

3. Append several TLVs. os4ApduAppendTLV 140

4. Read one TLV. os4ApduReadTLV 144

5. Write another TLV. os4ApduWriteTLV 142

6. Read this TLV. os4ApduReadTLV 144

7. Delete file. os4ApduDeleteFile 157

Table 5.24: Tree Sample


1. Read the contents of the directory. os4ApduDirectory 160

2. Select a specific file. os4ApduSelectFile 152

346 Samples

eToken Application Aid (eTAID) Sample

The eTAID project sample is provided for backward compatibility to assist developers who are familiar with the AID classes in previous versions of the eToken SDK. The sample provides the same classes (as the previous version of the SDK) as wrappers for the high level functions. The sample can be found in ...\Samples\eToken\eTAID. For further details on the functions, see Chapter 3, "eToken API Reference" and for further details on developing applications, see Chapter 2, "Developing Applications for eToken".Compilation options of the application and the sample should be the same. In particular, all samples are compiled for multithreading. This means that you should either compile your application also from multithreading OR change the compilation options of the sample.Table 5.25 provides an overview of the eToken eTAID classes supplied with the SDK, and shows where you can find further details of each sample.Table 5.25: eToken eTAID Samples Overview

Name Class Description Page

eTAID eTAID Sample Illustrates the usage of the General Functions, Talker Functions and the Reader List and Listener Functions APIs .

348

os4_aid os4_aid Sample Illustrates the usage of the eToken OS/4 AID File System Functions, OS/4 AID General Functions, OS/4 AID RSA Keys Functions, OS/4 AID DES Keys Functions and the OS/4 AID Certificate Functions APIs.

349

r2_aid r2_aid Sample Illustrates the usage of the eToken R2 AID File System Functions, R2 AID General Functions and R2 AID Encryption Storage Functions APIs.

350

Additional Additional Samples

Ilustrates the use of the OS4 Shell, R2 Shell and eToken Listener.

351

eToken Application Aid (eTAID) Sample 347

eTAID SamplePath: ...\Samples\eToken\eTAID.This sample illustrates the usage of the General, Talker Functions and the Reader List and Listener APIs :• General API: deals with library initialization and finalization. • Talker Functions API: manages the talker object and handle for a

given smart card reader and locks and unlocks the smart card in the reader.

• Reader List and Listener API: returns a list of smart card readers, returns the current state of a smart card reader, registers and unregisters a user notification receiver for a smart card listener and is used in WinProc (window message handler procedure) when a listener notification is received.

348 Samples

os4_aid SamplePath: ...\Samples\eToken\os4_aid.This sample illustrates the usage of the eToken OS/4 AID File System Functions, OS/4 AID General Functions, OS/4 AID RSA Keys Functions, OS/4 AID DES Keys Functions and the OS/4 AID Certificate Functions APIs. • OS/4 AID File System Functions API: retrieves the information

about a file or a directory, creates a new empty directory or file on the eToken OS/4, deletes a file or a directory and reads data from a binary or TLV file.

• OS/4 AID General Functions API: returns or sets the eToken's general information, logs in or out, changes the eToken OS/4 user password and changes the eToken OS/4 administrator password.

• OS/4 AID RSA Keys Functions API: reads the RSA key information about the existing on-token RSA key, generates an RSA key pair, exports an RSA key from an eToken OS/4 and deletes an RSA key pair and frees the memory on the eToken OS/4.

• OS/4 AID DES Keys Functions API: reads the DES key information about the existing on-token DES key, reads the list of existing DES keys, imports a DES key to the eToken OS/4 and deletes a DES key and frees the memory on the eToken OS/4.

• OS/4 AID Certificate Functions API: reads the certificate information about an existing certificate, creates a certificate, writes data to a certificate and deletes a certificate and frees the memory on the eToken OS/4.


r2_aid SamplePath: ...\Samples\eToken\r2_aid.This sample illustrates the usage of the eToken R2 AID File System Functions, R2 AID General Functions and R2 AID Encryption Storage Functions APIs. • R2 AID File System Functions API: retrieves the information

about a file, directory or key, creates a new directory, binary file or key file on the eToken R2, reads data from a file or write data to a file and deletes an existing file, directory or key.

• R2 AID General Functions API: returns or sets the eToken's general information, retrieves or set the token name, logs in or out and changes the eToken R2 password.

• R2 AID Encryption Storage Functions API: retrieves the information about an encrypted file, stores data in the encrypted on-token file, loads data from the encrypted on-token file and deletes an existing encrypted file.

350 Samples

Additional SamplesPath: ...\Samples\eToken\OS4Shell.This sample illustrates the usage of the eToken OS4 AID as a shell application.Path: ...\Samples\eToken\R2Shell.This sample illustrates the usage of the eToken R2 AID as a shell application. Path: ...\Samples\eToken\Listener.This sample illustrates the usage of the eToken Listener.


CAPI Samples

The eTCAPI/eTCertStore API is an open source API, which supports the industry standards CAPI. For more information about these components, see Chapter 2, “Developing Applications for eToken”.

Acquiring a Context with the eToken Sample

Path: ...\Samples\CAPI\kcs.Shows how to acquire a context with the eToken CAPI provider, how to create a key-container that is created on the token and how to remove it. All functions used are Win32 functions.

Enumerating Certificates from eToken Sample

Path: ...\Samples\CAPI\listcerts.Shows how to enumerate all the certificates present on an eToken. All functions used are Win32 functions.

Note: Results of this sample may be affected by the Load Local settings.

Using CapiCom

Path: ...\Samples\CAPI\VB\eTCapiCOM.Shows how to sign and verify/encrypt and decrypt using eToken with the Microsoft Capicom 2.0 objects.

Note: In order to use the CapiCom sample, it will be necessary to first register Microsoft Capicom 2.0 object.

352 Samples

PKCS #11 Samples

The eTCAPI/eTCertStore API is an open source API, which supports the industry standards CAPI. For more information about these components, see Chapter 2, “Developing Applications for eToken”.

PKCS #11 Init Token Sample

Path: ...\Samples\Code Examples\PKCS11\InitToken.Shows how to initialize an eToken for PKCS #11.

PKCS #11 Info Sample

Path: ...\Samples\Code Examples\PKCS11\Info.Shows how to receive token/slot information using PKCS #11.

PKCS #11 RSA Key Use Sample

Path: ...\Samples\Code Examples\PKCS11\SignVerify.Shows how to sign data and verify a signature using PKCS #11. The sample creates temporary keys for use during the operation and then deletes these keys from the token when complete.Path: ...\Samples\Code Examples\PKCS11\EncryptDecrypt.Shows how to encrypt and decrypt data using PKCS #11. The sample also creates temporary keys for use during the operation and then deletes these keys from the token when complete.

PKCS #11 Samples 353

eTocx Samples

To view the JScript sample use the following path: ...\Samples\eTOCX\JScript.To view the VBScript sample use the following path: ...\Samples\eTOCX\VBScript.To view the VB sample use the following path: ...\Samples\eTOCX\VB.To view the Delphi sample use the following path: ...\Samples\eTOCX\Delphi

354 Samples

AppendixAeToken Editor

This appendix describes the eToken Editor tool, supplied with the eToken SDK, that provides a user interface that enables you, according to your login access, to:• View the data structure and content for selected eTokens.• Create eToken folders and files.• Write public and private data for the eToken R2 and for the eToken

CardOS/M4.• Copy files between your computer and an eToken.The eToken Editor works with both the eToken R2 and the eToken CardOS/M4. Due to the different functionality of the two types of eTokens, there are visible differences in the screens you will see. In addition certain actions are restricted to one eToken type or the other (for example, the types of files that can be created).

Warning: This application is a low level utility and therefore the user must have a good knowledge level of the eToken file system before attempting to use eToken Editor to work within eToken files.

For this reason, this appendix contains a general section that describes functions that work in the same way with both eToken types, followed by two usage-specific sections:• Using the eToken Editor, page 356.• Using the eToken Editor with eToken R2, page 361.

355

355

• Using the eToken Editor with eToken CardOS/M4, page 366.

Using the eToken Editor

Some of the eToken Editor functions are common to both eToken types, as described in this section:• Starting the eToken Editor, below.• Logging In and Out, page 358.• Changing the eToken Password, page 359.• Deleting Files and Folders, page 359.• Refreshing the Display, page 361.

Starting the eToken Editor

When the SDK is installed, the eToken Editor shortcut is added to the Windows Start menu, in the Programs\eToken\SDK folder.

To start the eToken Editor:

1 Connect one or more eTokens to the USB ports or an eToken Smartcard to a Smartcard reader.

2 In the Start Menu, select Programs\eToken\SDK\eTEditor. The eToken Editor window is displayed, as shown in the example below:

The window displays a tree on the left showing the eTokens currently connected, and the folder contents on the right.

356 eToken Editor

The Menu Bar contains the following menus:• File: Allows you to create a new file or a new folder, edit and

delete a file and exit the application.• Edit: Allows you to cut, copy, paste, paste special and select all

when working with files.• Security: Allows you to login, logout and change the password.• View: Allows you to refresh the reader or all readers.• Help: Describes the tool.

This example displays the contents of an eToken R2. For an eToken CardOS/M4, both the contents list on the right and the text in the status bar may look slightly different.

Using the eToken Editor 357

Logging In and Out

It is necessary to log in to an eToken R2 in all cases and an eToken CardOS/M4 in most cases in order to create or edit folders and files. You remain logged in to an eToken until you log out of it, and you may be logged in to a number of eTokens concurrently.To log in to a new eToken with eToken Editor, you must use the factory default password 1234567890. You should then assign a user password, as described in “Changing the eToken Password”, on page 359.

To log in to an eToken:

1 Select any folder of an eToken, if more than one is connected and displayed in the Editor.

2 In the toolbar, click the Login icon, or select Login from the Security menu. The following dialog is displayed:

3 Enter the password for the eToken.4 Click OK. You can now create and access folders and files on the

selected eToken, based upon your access permission. You remain logged in to the selected eToken until you log out.

To log out of an eToken:

1 In the toolbar, click the Logout icon, or select Logout from the Security menu. A confirmation message is displayed.

2 Click Yes. You are now logged out of the eToken.

358 eToken Editor

Changing the eToken Password

You may change the eToken password using the Editor, as described below. The password should consist of at least four characters. To ensure strong password security, it is recommended that you specify a password containing at least seven characters, including letters, numerals and symbols.

To change the eToken password:

1 Select the eToken for which you want to change your password.2 In the toolbar, click the Change password icon or select Change

Password from the Security menu. The following window is displayed:

3 Enter the new password in the Enter new password: field, and type it again in the Confirm new password: field.

4 Click OK. The new password is saved.

Deleting Files and Folders

A logged-in user can delete public and private files and folders.

To delete a file or a folder:

1 Either:• Select the eToken folder that contains the file you want to delete,

and then select the file.OR• Select the root folder of an eToken, and then select the folder you

wish to delete.

Using the eToken Editor 359

2 In the toolbar, click the Delete button, or right-click in the window and select Delete icon or select Delete from the File menu. The selected file or folder is deleted.

Copying Files

eToken provides the facility to store digital certificates and other files in the eToken data storage area, providing a higher level of security than file storage on a computer, network or diskette. In most cases, a file can be copied to an eToken by dragging it from the computer desktop, or from Windows Explorer, and dropping it directly onto the eToken Editor window. A file can also be copied to the computer from an eToken by dragging it from the eToken Editor window and dropping it on the desktop or Windows Explorer display.

To copy a file from the computer to an eToken:

1 In the eToken Editor window, select the folder in which the file is to be stored.

2 Select the file from the desktop or appropriate folder on the computer, and drag and drop it in the upper right pane of the eToken Editor window. The Create Public File window is displayed.

Note: The value in the File Size field cannot be changed when you copy.

To copy a file from an eToken to the computer:

1 In the eToken Editor window, select the file to be copied.2 Drag the file and drop it on the desktop or Windows Explorer display.

A copy of the file is stored on the computer.

To copy a file to an eToken using Paste Special:

1 Select the file to be copied, either from the eToken Editor window, or the appropriate folder on the computer.

2 Copy the selection to the clipboard and select the destination folder.3 On the Edit menu, click Paste Special and a new dialog opens which

allows you to change the file name and access conditons of the copied file.

4 Click OK to close the dialog. The file is copied.5 Repeat Step 3 for each file to be copied.

360 eToken Editor

Refreshing the Display

The eToken Editor provides you with an option to close all folders and update the display or refresh a selected reader.

To close all folders and update the display:

• In the toolbar, click the Refresh all icon or select Refresh All Readers from the View menu.. All currently open folder branches are closed in the left display pane, and the right display panes are cleared.

To refresh a selected reader:

• In the toolbar, select Refresh Selected Reader from the View menu.. The selected reader is refreshed.

Using the eToken Editor with eToken R2

This section explains how to use the eToken Editor to:• Create eToken R2 folders and files.• Write public, private and secret key data for the eToken R2.

Creating eToken R2 Folders and Files

For the eToken R2, logged-in users can create public folders and files, private folders and files.Folder and file names consist of four characters. Valid characters for folder and file names are 0 through 9, and a through f. The following names are reserved: FFFF, 3F00, 3FFF, 0000, 3FFE.Each eToken R2 has a root folder with the hex name 3f00.In addition to the eToken Editor toolbar and popup menu options described in this appendix, you can also use Windows Explorer drag/drop facilities in the eToken Editor window.

Creating a FolderFolders are created in a tree structure from the root folder, similar to Windows Explorer. You can nest one folder inside another.

Tip

Using the eToken Editor with eToken R2 361

To create a folder:

1 Log in to the eToken.2 Select the eToken folder within which you want to create the new

folder.3 In the toolbar, click the Create new folder icon, or select

New Folder from the File menu. The following dialog is displayed:

In the New Folder name field, enter a four-character folder name. Valid characters for folder and file names are 0 through 9, and a through f. The following names are reserved: FFFF, 3F00, 3FFF, 0000, 3FFE.

4 In the Access field, select either a public or private folder type, and then click OK. The eToken Editor window displays the new folder in the tree. The folder details are displayed in the upper right pane.

Creating a Public or Private FileFiles can be created in the root folder or in any other folder of a selected eToken R2.

To create a file:

1 Log in to the eToken.2 Select the eToken folder within which you want to create the new file.

The contents of the folder are displayed in the right pane.3 In the toolbar, click the Create new file icon, or select New File

from the File menu.

362 eToken Editor

The following dialog is displayed:

4 In the New File name field, enter a four-digit file name.5 In the New File size field, enter the file size in bytes.6 In the Access field, select the file type as either public or private,

and then click OK. Private files can only be read when you are logged in to the eToken. The eToken Editor displays the new file in the upper right pane with the details of its type and size, as shown in the following example:.

The following information is displayed in the lower right pane:• The address offset, in hex characters, on the left.• The data written to the file, in hex characters, in the center.


• The ASCII equivalent of the hex data, on the right.The number of hex characters in the file is determined by the size of the file.

Reading and Writing eToken R2 Data

Data is stored on an eToken R2 in binary form. The eToken Editor displays the data in hex and ASCII.

Reading Public and Private DataUsers can read public file data at any time but must be logged-in to read data in private files.By default, the data in a new file is a byte buffer filled with the hex value FF.

To read the data in a file:

1 Select a folder in the tree. The contents of the folder are displayed in the upper right pane.

2 Select either a Public or Private file to read. While Public files can be read at any time, a Private file can only be read after you have logged in the eToken.

3 From the File menu select Edit. The Edit binary file dialog is displayed:

• The address offset, in hex characters, on the left.• The data written to the file, in hex characters, in the center.• The ASCII equivalent of the hex data, on the right.The number of hex characters in the file is determined by the file size.

364 eToken Editor

Writing Public and Private Data Logged-in users may write data to both public and private files. Data is written to eToken files in binary form.

To write data to a file:


2 Select the file in which you want to write data. From the File menu select Edit. The Edit binary file dialog is displayed.

3 Position the cursor on the required hex or ASCII characters, and enter the data.

4 If you want to discard your changes before saving, click Reload. The data currently in the file is read and displayed in the eToken Editor window, and your changes are lost.

5 Click Save, then OK to confirm. The file is updated.


Using the eToken Editor with eToken CardOS/M4

This section explains how to use the eToken Editor to:• Create eToken CardOS/M4 folders and files.• Write binary data for the eToken CardOS/M4.

Creating eToken CardOS/M4 Folders and Files

For the eToken CardOS/M4 users can create folders and public or private binary files.

Note: TLV file creation is not supported in the SDK 2.60 version of the Editor.

Folder and file names consist of four characters. Valid characters for folder and file names are 0 through 9, and a through f. The following names are reserved: FFFF, 3F00, 3FFF, 0000.Each eToken CardOS/M4 has a root folder with the hex name 3f00.In addition to the eToken Editor toolbar and popup menu options described in this appendix, you can also use Windows Explorer drag/drop facilities in the eToken Editor window.

Creating a FolderFolders are created in a tree structure from the root folder, similar to Windows Explorer. You can nest one folder inside another.

To create a folder:

1 Select the eToken folder within which you want to create the new folder.

2 In the toolbar, click the Create new folder icon, or select New Folder from the File menu. The following dialog is displayed:

Tip

366 eToken Editor

The following dialog is displayed:

In the New Folder name field, enter a four-character folder name. Valid characters for folder and file names are 0 through 9, and a through f. The following names are reserved: FFFF, 3F00, 3FFF, 0000.

3 Select the Access as either all access, public or other. 4 Click More if you want to provide access on specific criteria. The

following dialog is displayed:

Using the eToken Editor with eToken CardOS/M4 367

5 For each function, select from the drop down list what access rights are allowed:• ALWAYS• USER• ADMINISTRATOR• NEVER

6 Click OK to return to the Create New Folder dialog.7 Click OK. The eToken Editor window displays the new folder in the

tree. The folder details are displayed in the upper right pane.

Creating a Binary File (Public or Private)Files can be created in the root folder or in any other folder of a selected eToken CardOS/M4.

To create a file:

1 Select the eToken folder within which you want to create the new file.2 In the toolbar, click the Create new file icon, or select New File

from the File menu.3 The following dialog is displayed:

4 In the New File name field, enter a four-digit file name.5 In the New File size field, enter the file size in bytes.6 Select the Access as either all access, public, private or other.

368 eToken Editor

7 Click More if you want to provide access on specific criteria. The following dialog is displayed:

8 For each function, select from the drop down list what access rights are allowed:• ALWAYS• USER• ADMINISTRATOR• NEVER

9 Click OK to return to the Create New Folder dialog.


10 Click OK. The eToken Editor window displays the new file in the upper right pane with the details of its type and size, as shown in the example below.

The following information is displayed in Edit binary file dialog:• The address offset, in hex characters, on the left.• The data written to the file, in hex characters, in the center.• The ASCII equivalent of the hex data, on the right.The number of hex characters in the file is determined by the size of the file.

Reading and Writing eToken CardOS/M4 Data

Data is stored on an eToken CardOS/M4 in binary form. The eToken Editor displays the data in hex and ASCII.

Reading Public and Private DataLogged-in users can read data in their public and private files. Private files can only be read when you are logged in to the eToken.By default, the data in a new file is a byte buffer filled with the hex value 0.

370 eToken Editor

To read the data in a file:


2 Select either a Public or Private file to read. While Public files can be read at any time, a Private file can only be read after you have logged in the eToken.

3 Click Enter. The Edit binary file dialog is displayed:

The following information is displayed in the Edit binary file dialog:• The address offset, in hex characters, on the left.• The data written to the file, in hex characters, in the center.• The ASCII equivalent of the hex data, on the right.The number of hex characters in the file is determined by the file size.


Writing Public and Private DataLogged-in users may write data to both public and private files. Data is written to eToken files in hex characters.

To write data to a file:

1 Select a folder in the tree, then select the file in which you want to write data. The file data is displayed in the lower right pane.

2 Click Enter. The Edit binary file dialog is displayed3 Position the cursor on the required hex or ASCII characters, and

enter the data.4 If you want to discard your changes before saving, click Reload. The

data currently in the file is read and displayed in the eToken Editor window, and your changes are lost.

5 Click Save, then OK to confirm. The file is updated.

372 eToken Editor

AppendixBeToken Cryptoki Viewer

This appendix describes the eToken Cryptoki Viewer (ckView) tool supplied with the eToken SDK, which enables you to view the contents of an eToken according to PKCS #11 (Cryptoki) concepts.Whereas the eToken Editor, described in Appendix A, displays the file system of the eToken according to ISO 7816-4, the eToken Cryptoki Viewer provides a PKCS #11 object view of the eToken contents. For more information about PKCS #11, see “PKCS #11”, on page 16.The eToken Cryptoki Viewer works with both the eToken R2 and the eToken CardOS/M4. It can also be used without an eToken, with any DLL based on PKCS #11. The eToken Cryptoki Viewer displays:• All the objects on the eToken, for example, certificates and keys.• The attributes of selected public objects.• When logged in, the attributes of selected private objects.• Details of the eToken, slot and available PKCS #11 mechanisms.• A log of current API commands and error alerts (optional).

373

373

Using the eToken Cryptoki Viewer

When the SDK is installed, the eToken Cryptoki Viewer shortcut is added to the Windows Start menu, in the Programs\eToken\SDK folder.

To start the eToken Cryptoki Viewer:

1 In the Start Menu, select Programs\eToken\SDK\eToken PKCS#11 View. The eToken Cryptoki Viewer window is displayed, showing the available readers, as in the example below:

374 eToken Cryptoki Viewer

2 Connect one or more eTokens. The eToken contents are displayed, as shown in the example below:

The public objects on the eToken are displayed on the left, in an object tree. Public keys are shown in green. The details of the current eToken and slot are displayed on the right. Scroll down to see further details, including the PKCS #11 mechanisms available on the eToken.

Using the eToken Cryptoki Viewer 375

Viewing Attributes

Attributes of public objects can be viewed without logging in. You must log in with the eToken password in order to view the attributes of private objects.

To view the attributes of an object:

1 Click on an object in the object tree. The attributes of the selected object are displayed on the right. The example below shows the attributes of a selected public key:

The example below shows the attributes of a selected certificate:


Logging In and Out

To view the attributes of private objects, you must log in with the eToken password.

To log in to an eToken:

1 Select an eToken, and in the toolbar, click the Login icon, or select Login from the Action menu. The following dialog appears:

2 Enter the eToken password. To log in to a new eToken, you must use the factory default password 1234567890. To change the password, see “Changing the eToken Password”, on page 359.

3 Click OK. The eToken Cryptoki Viewer reads the private objects on the eToken and adds them to the display. Private keys are shown in red, as in the following example:

Using the eToken Cryptoki Viewer 377

4 To view the attributes of a private object, click on the object. The following example shows the attributes of a selected private key:

5 To log out, click the Logout icon in the toolbar, or select Logout from the Action menu.

Selecting the DLL

You can select the DLL to be used for the log. The default is the eToken PKCS #11 DLL, etpkcs11.dll.

To select the DLL:

1 In the toolbar, click the Options button, or select Library from the File menu. The following dialog appears:

2 Click OK.


AppendixCeToken Capi Viewer

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. Aladdin has implemented eTCAPI, an eToken-oriented CSP of type PROV_RSA_FULL. A CSP other than the default one is chosen when an application acquires a context to a provider, supplying its name as a parameter to the CryptAcquireContext() function. eTCAPI is named “eToken Base Cryptographic Provider”.This appendix describes the eToken Capi Viewer (capiView) tool supplied with the eToken SDK that enables you to view the contents of an eToken according to CAPI concepts.Whereas the eToken Editor, described in Appendix A, displays the file system of the eToken according to ISO 7816-4, the eToken Capi Viewer provides a CAPI view of the eToken contents. The eToken Capi Viewer works with both the eToken R2 and the eToken CardOS/M4.The eToken Capi Viewer displays:• The properties of all installed Cryptographic Providers.• Key containers and keys in all Cryptographic Provider.• Certificates stored in various certificate stores.

379

379

• Specifically for the eToken Base Cryptographic Provider, the stored objects (certificates and keys) are shown per each individual token.

Using the eToken Capi Viewer

When the SDK is installed, the eToken Capi Viewer shortcut is added to the Windows Start menu, in the Programs\eToken\SDK folder.

To start the eToken Capi Viewer:

1 Connect one or more eTokens.1 In the Start Menu, select Programs\eToken\SDK\Crypto API

Viewer. The eToken Crypto API View window is displayed, as in the example below:

The keys and certificates are displayed on the left, in an object tree. The properties and their values are displayed on the right.

380 eToken Capi Viewer

2 Select the eToken Base Cryptographic Provider reader. The eToken cryptographic properties are displayed, as shown in the example below:

Viewing Properties

To view the properties of an object:

1 Click on an object in the object tree. The properties of the selected object are displayed on the right. The example below shows the properties of the Microsoft Base Cryptographic Provider

Using the eToken Capi Viewer 381

The example below shows the properties of the Microsoft Enhanced Cryptographic Provider:

2 Select Exit from the File menu.

382 eToken Capi Viewer

AppendixDRedistributing eToken

Applications

383

383

Redistributing Applications for eToken

The redistributable version of the eToken Run Time Environment (RTE) enables you to install the eToken applications that you develop on your clients’ machines.The main features of the eToken RTE redistributable are as follows:• Simple to use (install and uninstall). The user does not know the

details of installing the RTE.• Ensures that installing or uninstalling one application will not

"break" other existing applications on the machine, since several applications can install the RTE on the same machine.

• Handles upgrades and downgrades. A newer RTE version can replace an older RTE, without breaking any other applications.

MSI Technology

The installation and redistribution platform used for the eToken RTE redistributable is Microsoft's Windows Installer (MSI) technology. This has been chosen because it is the most competent installation platform currently available and because it provides most of the features outlined above. (It's also free of charge...)The only drawback of MSI technology is that the MSI runtime engine must be installed on the machine before using MSI packages. The MS Windows 2000 and Windows Me operating systems are MSI-enabled, but older operating systems are not. Microsoft supplies an executable installation of the MSI runtime that is installed in eToken products before commencing RTE installation.

RTE Redistributable

The RTE 3.51 redistributable package includes the following components:• eToken device drivers.• eTCAPI: the eToken CSP for Microsoft CAPI. See “CAPI”, on

page 23.• eTCertStore: the eToken certificate store plugin for Microsoft CAPI.

See “eTCAPI and eTCertStore”, on page 24.

384 Redistributing eToken Applications

• eTpkcs11: the eToken PKCS#11 implementation. See “PKCS #11”, on page 16.

• eTSrv.exe: the eToken central server that monitors the readers and notifies clients.

• eTProps: eToken Properties utility that provides a user interface that allows users to change the eToken password and eToken name.

A single MSI package is used to install the entire RTE. The installation is per machine. After installation, the eToken RTE 3.51 shows up in the Windows Control Panel Add/Remove Programs applet and requires administrative privileges to install or modify. The RTE 3.51 directly installs the files shown in Table D.1. Note that all files are installed in various locations under the Windows directory. Table D.1: RTE 3.51 Installed Files

Component Win 98, Win Me Win 95 Win NT4 Win 2000/XP

aksifdh.sys %windir%\system32\drivers

%windir%\system

%windir%\system32\drivers

%windir%\system32\Setup\aladdin\eToken

aksup.sys %windir%\system32\drivers

%windir%\system


%windir%\system32\Setup\aladdin\eToken

adfrt.sys NONE %windir%\system


NONE

CertStoreInit %windir%\system

%windir%\system

%windir%\system32

%windir%\system32

eTcli16.dll NONE %windir%\system

NONE NONE

aksifdh.inf %windir%\inf %windir%\inf NONE %windir%\system32\Setup\aladdin\eToken

aksup.inf %windir%\inf %windir%\inf NONE %windir%\system32\Setup\aladdin\eToken

Redistributing Applications for eToken 385

aksifdh.cat NONE NONE NONE %windir%\system32\Setup\aladdin\eToken

aksup.cat NONE NONE NONE %windir%\system32\Setup\aladdin\eToken

eTCapi.dll %windir%\system

%windir%\system

%windir%\system32

%windir%\system32

eTCoreReg.dll %windir%\system

%windir%\system

%windir%\system32

%windir%\system32

eTNSModUtil.exe %windir%\system

%windir%\system

%windir%\system32

%windir%\system32

eTPass.ini %windir%\system

%windir%\system

%windir%\system32

%windir%\system32

eTpkcs11.dll %windir%\system

%windir%\system

%windir%\system32

%windir%\system32

eTPKIReg.dll %windir%\system

%windir%\system

%windir%\system32

%windir%\system32

eTProdVerifier.exe %windir%\system

%windir%\system

%windir%\system32

%windir%\system32

eTSrv.exe %windir%\system

%windir%\system

%windir%\system32

%windir%\system32

eTokcsp.dll %windir%\system

%windir%\system

%windir%\system32

%windir%\system32

eTokcsp.sig %windir%\system

%windir%\system

%windir%\system32

%windir%\system32

eToken.dll %windir%\system

%windir%\system

%windir%\system32

%windir%\system32

eTProps.exe %windir%\system

%windir%\system

%windir%\system32

%windir%\system32

eTUI.dll %windir%\system

%windir%\system

%windir%\system32

%windir%\system32

Table D.1: RTE 3.51 Installed Files (Contd)



On Win NT4 and Win9X systems, the RTE 3.51 also installs the Microsoft Windows Smart Card base components.The RTE 3.51 directly creates the following registry settings:• HKLM\Software\Aladdin\eToken\Core key.• HKLM\Software\Aladdin\eToken\Core\Readers (Win NT4 only)

value.• HKLM\Software\Microsoft\Cryptography\Provider\eToken Base

Cryptographic Provider key and sub-values.• HKCU\Software\Microsoft\SystemCertificates\PhysicalStores\

eToken key and sub-values.Other registry settings may be found in the RTE documentation.The RTE installs all components under the system directory of the machine. One reason for this is to prevent different applications from installing it in different places. Another reason is to prevent users from mistakenly removing critical components. Users rarely touch files in the system directories. The RTE redistributable is provided as follows:• A single RTE package for all operating systems. The logic in this

package detects the OS platform and installs the relevant components for it. This MSI package is relatively large.

Note: By default, the RTE installation installs 2 eToken readers (AKS ifdh 0,1). To install more readers, use the eTProps.exe.

eTVerify.dll %windir%\system

%windir%\system

%windir%\system32

%windir%\system32

usbDrv.sys NONE NONE %windir%\system32\drivers

NONE

usbHub.sys NONE NONE %windir%\system32\drivers

NONE

Table D.1: RTE 3.51 Installed Files (Contd)


Redistributing Applications for eToken 387

Using the RTE RedistributableThe fact that the eToken RTE is an MSI package does not mandate that a product that uses eToken must be installed using MSI technology. You can use your favorite installation technology for your product, and then simply perform the following two steps:

1 Install or upgrade the MSI runtime on the machine, using the MSI redistributable from Microsoft.

2 Launch the RTE package.

Command line:

msiinst.exe is the MSI redistributable installation.msiexec.exe is the MSI engine, which is installed into the system directory of the machine.To install:msiinst.exemsiexec.exe /qn /i RTE.MSI To uninstall:msiexec.exe /qn /x RTE.MSIMore information about msiexec command line options can be found in MSDN.

C/C++ code

Use the include file msi.h provided with the Microsoft Platform SDK and link to msi.lib. The MSI C/C++ interface is documented in MSDN.

Visual Basic/VBScript

MSI also supports an automation interface designed for use by scripting environments. This is also documented in MSDN.

MSI package

MSI 1.1 and higher supports the notion of nested installations. An MSI package can install the eToken MSI package as a nested installation. Refer to MSDN for more details.


AppendixEeToken SDK Installation

This appendix describes the procedure for installing the eToken SDK V3.50 and the eToken Utilities V2.10, provided on the eToken SDK CD.

Installing the eToken SDK Components

The SDK components installed from the eToken SDK CD are the eToken SDK V3.50 and the eToken Utilities V2.10. You may select to install one or both components. If a previous version of one or both of the components is currently installed the wizard will remove it.

389

389

To install the eToken SDK 3.50:

1 Double-click the sdk_3.50.msi file. The Welcome to eToken SDK 3.50 Installation window is displayed:

2 Click Next. The End-User License Agreement window is displayed:

390 eToken SDK Installation

3 You must select I accept the license agreement to continue. Click Next. The Select Installation Type window is displayed:

4 Select either Complete or Custom and click Next. The Ready to Install Application window is displayed:

Installing the eToken SDK Components 391

5 Click Next. The Updating System window is displayed:

New files are copied onto the system at this stage, as shown below:


The eToken SDK successfully installed window is displayed, as shown below:

6 Click Finish to exit the installation.

To install the eToken SDK Utilities 2.10:

1 Double-click the Utilities_2.10.msi file. The eToken Utilities 2.10 Setup window is displayed, as shown below:


2 Click Next. The End-User License Agreement window is displayed, as shown below:

3 You must select I accept the terms in the License Agreement to continue. Click Next. The Choose Setup Type window is displayed:


4 Select either Custom or Complete and click Next. The Ready to Install window is displayed:

5 Click Install.The eToken Utilities 2.10 successfully installed window is displayed:

6 Click Finish to exit the Setup Wizard.


AppendixFGlossary

This appendix explains the major terms and abbreviations used in this eToken Software Developer’s Guide. Table F.1: Glossary of Terms

Term Meaning

AC Access condition.

AID Application ID: Human-readable name for a directory (DF). The namespace for these names is global.

APDU Application Protocol Data Unit: a command sequence that can be sent by an application to a smart card.

API Application Programming Interface.

ATR Answer to Reset.

AUTH objects Symmetric and asymmetric keys used for authentication. One of the four Basic Security (BS) object types.

BS objects Basic Security objects.

CAPI Microsoft Cryptographic Application Programming Interface (CryptoAPI or CAPI) standard.

CertStore Microsoft API (part of CAPI) that handles certificate storage.

CHV Card holder verification.

397

397

Cryptoki Cryptographic token interface. See PKCS#11.

CSE Current security environment.

CSP Cryptographic service provider.

DES Data Encryption Standard.

DESX, 3DES Extended DES and Triple-DES: Enhanced encryption algorithms, based on DES.

DF Directory file. This is similar to a directory and contains other files.

DS Digital signature.

EF Elementary file: a regular binary file that contains data, or in the eToken CardOS/M4 file system, fixed-length records.

eTAID libraries Sets of components designed to help the developer write software applications for use with eToken.

eTCAPI eToken component providing CAPI support.

eTCertStore eToken component providing CertStore support.

eTListener eToken component that implements a client of eTSrv.

eTListenerEx Component that can detect the insertion and removal of eTokens before the user logs in to Windows 2000 or Windows NT.

eTocx eToken ActiveX component.

eToken CardOS/M4 A fast, readerless smart card: A USB device that incorporates a secure USB Micro controller and an off-the-shelf smart card chip, to form a secure computing and storage device capable of asymmetric key operations. Also known as eToken PRO.

eTpkcs11 eToken component providing PKCS #11support.

eToken PRO See eToken CardOS/M4.

eToken R2 A USB device that incorporates a secure USB Micro controller and an external EEPROM component, to form a secure computing and storage device capable of symmetric key operations.

eTSrv Notification service application that monitors the insertion and removal of eTokens and communicates with client applications via eTListener.

FCI File Control Information, according to ISO 7816-4.

Table F.1: Glossary of Terms (Contd)

Term Meaning

398 Glossary

FID Full file ID.

HS Historically, the eToken R2 was called eToken HS. Most of the API names still retain HS as part of their nomenclature.

ISO 7816-4 International standard that includes a definition of the functionality aspects of the APDU.

KF DESX key file (eToken R2).

MAC Message Authentication Coding.

MF Root directory file on both eToken R2 and eToken CardOS/M4.

MSI Microsoft Installer.

OCI Operation Control Information.

PKCS#11 PKCS (Public-Key Cryptography System or Cryptoki): API proposed by RSA Labs, which presents a “virtual token” for applications, and management functions to locate and manipulate cryptographic tokens.

PSO objects Symmetric and asymmetric keys used for general purpose cryptography. One of the four Basic Security (BS) object types.

RM Resource Manager.

RTE Run Time Environment. The eToken RTE includes all the necessary files and drivers to support eToken integration with tailored and third-party applications.

SDK Software Developer’s Kit.

SE objects Security environment objects. An SE object is loaded prior to any cryptographic activity and constitutes the current security environment (CSE). It specifies which BS objects will be used for a given cryptographic operation.

SECI Security Environment Control Information.

SFI Short file ID.

SM Secure messaging: The ability to protect and/or authenticate traffic between CardOS/M4 and the host, using symmetric DES or 3DES keys in the format of SM BS objects.

SM objects Symmetric keys used for secure messaging. One of the four Basic Security (BS) object types.


Term Meaning

399

TEST objects The only objects that can affect the security status of a DF-tree. One of the four Basic Security (BS) object types.

TLV files Files that map tags to <length, value> pairs.


Term Meaning

400 Glossary

Developer’s Guide - pudn.comread.pudn.com/downloads128/ebook/549477/eToken_SDK_3_50[1].pdf ·...

Documents

Transcript of Developer’s Guide - pudn.comread.pudn.com/downloads128/ebook/549477/eToken_SDK_3_50[1].pdf ·...