SafeNet Authentication Client (Linux)

Developers Guide Version 8.0 Revision A

Copyright 2010, SafeNet, Inc. All rights reserved. All attempts have been made to make the information in this document complete and accurate. SafeNet, Inc. is not responsible for any direct or indirect damages or loss of business resulting from inaccuracies or omissions. The specifications contained in this document are subject to change without notice. SafeNet and SafeNet Authentication Client are trademarks of SafeNet, Inc. All other trademarks, brands, and product names used in this Manual are trademarks of their respective owners. SafeNet Hardware and/or Software products described in this document may be protected by one or more U.S. Patents, foreign patents, or pending applications. For details of FCC Compliance, CE Compliance and UL Notification, please contact SafeNet Support.

iii

Support
Weworkcloselywithourresellerpartnerstoofferthebestworldwide technicalsupportservices.Yourreselleristhefirstlineofsupport whenyouhavequestionsaboutproductsandservices.However,if yourequireadditionalassistanceyoucancontactusdirectlyat: Telephone Youcancallourhelpdesk24hoursaday,sevendaysaweek: USA:18005456608 International:+14109317520 Email Youcansendaquestiontothetechnicalsupportteamatthefollowing emailaddress:
support@safenet-inc.com

Website YoucansubmitaquestionthroughtheSafeNetSupportportal:
http://c3.safenet-inc.com/secure.asp

Additional Documentation
WerecommendreadingthefollowingSafeNetTokenpublication: SafeNetAuthenticationClient(Linux)8.0AdministratorsGuide SafeNetAuthenticationClient(Linux)8.0UsersGuide SafeNetAuthenticationClient(Linux)8.0ReadMe

iv

Table of Contents
1. Overview..................................................................................................... 1
SafeNet Authentication Client 8.0 ............................................................................. 2 Choosing the Correct API.......................................................................................... 2 PKCS#11............................................................................................................... 3 SAPI ...................................................................................................................... 3 Obsolete APIs............................................................................................................ 3 Developing in Non-C/C++ Environments.................................................................. 4 A Note on Cryptography............................................................................................ 5 Additional Cryptography Information Sources...................................................... 5 Password Management............................................................................................. 6 Multi-Language Support........................................................................................ 6 Password Policy Management ............................................................................. 6 Supported Token Models........................................................................................... 7

2. PKCS#11 and Configuration.................................................................... 9

PKCS#11 Implementation for SafeNet Authentication Client 8.0........................... 10 Using libeTPkcs11............................................................................................... 10 Supported Object types............................................................................................11 Supported Mechanisms........................................................................................... 12 PKCS#11 Functions ................................................................................................ 13 C_Initialize........................................................................................................... 13 C_Finalize............................................................................................................ 14 C_GetInfo ............................................................................................................ 14 C_GetSlotList ...................................................................................................... 15 C_GetSlotInfo...................................................................................................... 15 C_GetTokenInfo .................................................................................................. 16 C_WaitForSlotEvent............................................................................................ 18 C_InitToken.............................................................................................................. 18 C_SetPIN ............................................................................................................ 18 C_Login ............................................................................................................... 19

vi

C_CopyObject .....................................................................................................19 C_GetObjectSize.................................................................................................19 C_GetAttributeValue............................................................................................19 C_GenerateKeyPair ............................................................................................20 C_DeriveKey........................................................................................................20 C_SeedRandom..................................................................................................20 C_CreateObject...................................................................................................20 Major Backward Compatibility Issues of PKCS#11.................................................21

3. Token-Specific PKCS#11 Extensions...................................................23

General Overview ....................................................................................................24 Understanding Token-Specific PKCS#11 Extensions.........................................24 Encoding of Text Attributes, Fields and Parameters...........................................25 SafeNet Authentication Client .............................................................................26 Slot/Token IOCTL ................................................................................................27 Extensions Related to Operations with Slots and Tokens ..................................27 Special Token Capabilities...................................................................................31 Vendor-Specific Information.....................................................................................33 Vendor-Specific OTP Key Attributes ...................................................................33 Secondary authentication....................................................................................33 Token initialization................................................................................................35 Controlling Initialization Parameters....................................................................38 PIN Initialization...................................................................................................42 Behavior of Standard C_InitToken and C_InitPIN Functions..............................42 Backward Compatibility Issues............................................................................43 Special Authentication Features..........................................................................44 Miscellaneous Features.......................................................................................46 Reference.................................................................................................................47 Common Information...........................................................................................47 Constants.............................................................................................................47 Data Types...........................................................................................................49 Objects.................................................................................................................50 Challenge-Response Unlocking Capability Feature Object................................57 Private Data Caching Feature Object .................................................................58 Secondary Authentication Policy Feature Object ...............................................59 Functions .............................................................................................................60 Mechanisms.........................................................................................................70 Properties.............................................................................................................71

vii

Token Model Specifications..................................................................................... 74

4. SAPI...........................................................................................................75
Introduction .............................................................................................................. 76 Common Description of SAPI ................................................................................. 76 OTP Functionality................................................................................................ 77 Miscellaneous Functionality ................................................................................ 78 Data Types............................................................................................................... 79 CK_INIT_CALLBACK ......................................................................................... 79 CK_UNBLOCK_CALLBACK .............................................................................. 80 CK_UNBLOCK_CALLBACK_EX ....................................................................... 80 SAPI_PIN_POLICY_INFO.................................................................................. 81 CK_SAPI_OTP_MECHANISM_INFO ................................................................ 81 Error Codes ............................................................................................................. 82 SAPI Objects ........................................................................................................... 85 Slot Object........................................................................................................... 85 Token Object ....................................................................................................... 86 OTP Object.......................................................................................................... 94 Functions ................................................................................................................. 96 Common Functionality ........................................................................................ 96 Slot/Token Functionality ...................................................................................... 97 OTP Functionality.............................................................................................. 105 Major Backward Compatibility Issues of SAPI.......................................................112

5. Samples.................................................................................................. 113
Sample Overview ...................................................................................................114 Compiling the Samples ..........................................................................................114 PKCS#11 Samples.................................................................................................115 CACert............................................................................................................... 115 ClearToken ........................................................................................................ 116 Info Test............................................................................................................. 116 InitToken ............................................................................................................ 117 Password Policy................................................................................................ 118 PKCS#11 Token-Specific Extensions Samples .....................................................119 Initiating ............................................................................................................. 119 UnlockToken...................................................................................................... 119 SAPI Samples ....................................................................................................... 120 InitOTP .............................................................................................................. 120

viii

InitToken.............................................................................................................121 TokenInfo ...........................................................................................................121

Index ...................................................................................................123

Chapter 1

Overview
ThischapterprovidesanoverviewofSafeNetAuthenticationClient 8.0 SafeNet Authentication Client 8.0 Choosing the Correct API Obsolete APIs Developing in Non-C/C++ Environments A Note on Cryptography Password Management Supported Token Models

SafeNet Authentication Client 8.0

SafeNetAuthenticationClient8.0installsallthenecessaryfilesand tokendriverstosupporttokenintegrationwithvarioussecurity applications.Itenablesoperatingsystemsandthirdpartyapplications toaccessthetoken.InstallingtheSafeNetAuthenticationClient allowscommunicationwithallavailabletokendevicesandformsthe basisforSafeNetsvariousmanagementsolutions,suchasToken ManagementSystem(TMS);acompleteframeworkformanagingall aspectsoftokenassignment,deploymentandpersonalizationwithin anorganization. SafeNetstokenbasedPKISolutionsenabletheimplementationof strongtwofactorauthenticationusingstandardcertificates.Generic integrationwithPKCS#11securityinterfacesenablesinteroperability withavarietyofsecurityapplicationsuchasWebAccess,VPN Access,NetworkLogon,PCProtectionandSecureeMail.PKIkeys andcertificatescanbesecurelycreated,storedandusedfromwithin thetoken. WhenusedwitheTokenPRO/SmartcardoreTokenNGOTPthePKI Privatekeyscanbegeneratedandoperatedonboardthesecurechip. SafeNetAuthenticationClientsupportsthevarioustypesoftoken deviceinbothformfactors.ThismeansthatonlyasinglePKI installationisrequiredtoenableoperationsofeitheratraditional SmartcardoraUSBtoken(PRO/NGOTP),resultingineasy deploymentandcosteffectiveinstallationinuseoftokenproducts andsolutions. SafeNetAuthenticationClientcanbedeployedandupdatedusing anystandardsoftwaredistributionsystemsuchasTMS.Inaddition, theTMSsupportssoftwaredistributionusingtheMicrosoftGPO system.

Choosing the Correct API

Youhavethefollowingoptionswhendecidingwhichmethodologyto usewhenprogrammingapplicationsthatutilizethetoken: PKCS#11 SAPI

Obsolete APIs

PKCS#11
PKCS#11isaPublicKeyCryptographyStandard(PKCS)forpublic keycryptography,developedbyRSALaboratoriesandincludesboth algorithmspecificandalgorithmindependentimplementation standards.Itisanindustrystandardthatdefinesatechnology independentprogramminginterfaceforcryptographicdevicessuch assmartcardsandPCMCIAcards. Thisstandardspecifiesanapplicationprograminterface(API),called Cryptoki(CryptographicTokenInterface),todevices,eitherphysical orvirtual,whichholdcryptographicinformation(keysandother data)andperformcryptographicfunctions. ThisAPIisusedacrossmanyplatformsandispowerfulenoughfor mostsecurityrelatedapplications.SafeNetusesPKCS#11asthemain APIfortokenprogramming. AllvendorspecifictokenfunctionalityisavailableeitherviaPKCS#11 APIorviaproprietaryextensionsdevelopedtobeusableinPKCS#11 applications.

SAPI
SAPI(SupplementaryAPI)wasfirstintroducedineTokenRTE3.60to overcometherequirementforapplicationstouseobsoletelowlevel APIs.Itprovidedaccesstothetokenspecificcapabilitiesnotcovered bythePKCS#11standard.Thisfunctionalityisavailablenowvia PKCS#11API. SAPIissupportedinSafeNetAuthenticationClient(withrestrictions describedlaterinthisdocument)andmaybeusedbyapplications. HoweverthenewfeaturesarenotsupportedviaSAPI.Youare encouragedtousePKCS#11fornewdevelopment(unlessthe applicationisrequiredtorunoneTokenRTE3.65aswell).

Obsolete APIs
eTokenSDK3.51describedseverallowlevelAPIs,suchas: eTokenAPIthatprovidedlowlevelaccesstoatoken

4 ApartlydocumentedAPDUlevelAPDUthatallowed sendingaseparateAPDUtothetoken eTOCXCOMAPIforlowleveltokenfunctionality. AlllowlevelAPIsareconsideredobsoleteandarenotsupported inPKIClient5.0. TheCertificateStoreisnotsupportedinPKIClient5.0.The functionalityisnowavailablethroughthePKIClienttaskbar menu(PKIMonitor).

Developing in Non-C/C++ Environments

Using Sun's PKCS#11 Provider in Java
TheJavaplatformdefinesasetofprogramminginterfacesfor performingcryptographicoperations.Theseinterfacesarecollectively knownasJavaCryptographyArchitecture(JCA)andJava CryptographyExtension(JCE). Formoreinformation,referto:
http://java.sun.com/j2se/1.5.0/docs/guide/security/index.html

TheSunPKCS#11provideractsasabridgebetweenJCAandJCE interfacesandthenativePKCS#11provider.However,workinginthis mannerdoesnotprovidefullaccesstoallthefunctionalityof PKCS#11.Forinstance,itisonlypossibletoworkwithkeysand certificates. ThisfunctionalityissupportedsinceJava2PlatformStandardEdition 5(J2SE5.0).

Writing Wrapper Objects

Thealternatesolution(foreitherprogrammingenvironment)isto writeawrapperobjectthatanswerstheparticularneedsofthe application.Dependingontheseneeds,thewrapperobjectmaybea .NETassemblyobject,anActiveXobjectorsomethingelse.

A Note on Cryptography

A Note on Cryptography
Applicationdevelopersusetokenforoneortwomainpurposes: Addingstrongcryptographiccapabilitiestotheapplication Asasecuredatarepository Usingtokenforsecuredatastorageissimpleandobvious,but cryptographyisacomplicatedsubjectandrequiresafewcomments. Cryptographyitselfisnottoocomplicatedtounderstand,butitcanbe verycomplicatedtouseinthecorrectmanner.Thereareanumberof goodreferencestolearnaboutcryptography(SeeAdditional CryptographyInformationSourcesonpage5)butthefirstruleisdonot reinventthewheel.Inmostcasesitwillnotworkcorrectly. Therearemanygoodcryptographicalgorithmsavailable,butthey needtobeusedproperly.Manyoftherealworldsecurityattacksare theresultofimproperuseofcryptographyratherthantheuseofweak algorithms.Eachtaskrequiresthecorrectalgorithmtobeused. Whereverpossible,trytousestandardsolutions.Whenaproprietary solutionisrequired,obtaintheassistanceofacryptographyspecialist beforedevelopingtheapplicationandensurethattheprocessbeing followedisappropriateforthepurpose.

Additional Cryptography Information Sources

Thereareanumberofsourcesforinformationoncryptography.We recommendreadingsomeorallofthefollowing:

Books:
AppliedCryptographybyBruceSchneier AppliedCryptography:Protocols,Algorithms,andSourceCodeinC, SecondEditionbyBruceScneier PracticalCryptographybyNielsFerguson,BruceSchneier

Web Sources:
http://theory.lcs.mit.edu/~rivest/crypto-security.html http://www.cryptovb.com/links/links.html

Password Management
Multi-Language Support
Mostapplications,irrespectiveoftheselectedAPI,needtotransferthe passwordtothetoken.UsingnonASCIIcharactersinthepassword mayresultinseriouscompatibilityproblemswithotherapplications. SafeNetAuthenticationClientUIconvertsthepasswordtotheUTF8 encoding(asrequiredbylaterversionsofPKCS#11). Inordertoavoidcompatibilityproblemswerecommendthatthe passwordincludesonlyprintableASCIIcharacters.

Password Policy Management

ThePKIClient(sinceversion4.0)enforcespasswordpolicysetting: Thepasswordmustbechanged(forexample,duetoexpiration), andtheapplicationwillnotworkwiththetokenuntilthe passwordischanged.TheexactbehaviordependsontheAPIin use: PKCS#11applicationwillbehaveaccordingtothev2.20spec, whichmeans: C_LoginwithCKU_USER willsucceed. ThesubsequentcalltoC_GetTokenInforeturnsthe CKF_USER_PIN_TO_BE_CHANGEDflagset. Anysubsequentcallrequiringtheusertobeloggedfails withCKR_PIN_EXPIREDuntiltheuserchangesthe password.

Supported Token Models

SAPI_LoginnotinvolvingthePKIClientUIfailswith CKR_SAPI_PIN_EXPIRATION.

Thelogonoperation(inanyAPI)involvingPKIClientUIwill enforcetheusertochangethepassword. Passwordchangemayfailifthenewpassworddoesnotfitthe definedpasswordpolicy.

Supported Token Models

SafeNet Authentication Client supports multiple token types: eTokenPRO eTokenPROAnywhere eTokenNGFLASH eTokenNGFLASHAnywhere eTokenNGOTP SafeNeteTokenRescue SafeNeteTokenVirtual eTokenPROSmartcard InadditionSafeNetAuthenticationClientmaybeusedtoperform cryptographicoperationsintheabsenceofanytoken.

Chapter 2

PKCS#11 and Configuration

ThissectioncontainsinformationabouttheSafeNetAuthentication ClientimplementationofthePKCS#11standard. ForfullspecificationsonthePKCS#11standard,referto: http://www.rsasecurity.com/rsalabs/node.asp?id=2133. PKCS#11 Implementation for SafeNet Authentication Client 8.0 Supported Object types Supported Mechanisms PKCS#11 Functions Major Backward Compatibility Issues of PKCS#11

10

PKCS#11 Implementation for SafeNet Authentication Client 8.0

SafeNet Authentication Client8.0implementsPKCS#11v2.01.
Inaddition,SafeNet AuthenticationClient8.0provides implementationofsomefeaturesdefinedinlaterversionsofthe PKCS#11standard.

Note:
PKCS#11requiresthepresenceofatokentoperformany cryptographicoperation(evenifnokeyobjectiscreatedon thetoken).SafeNetAuthenticationClient8.0allowsthe applicationtoperformcryptographicoperationsinthe absenceofatoken.Thissocalledvirtualsessionisexplained laterinthisdocument. CallingPKCS#11functionsfromDLLdetachisforbidden. (Formoreinformation,seetheNoteinC_Finalizeonpage14)

Using libeTPkcs11
libeTPkcs11isasharedlibrary(libeTPkcs11.so)andis installedatthefollowinglocations: /usr/lib/on32bitmachine /usr/lib64/and/usr/lib32/onUbuntu64bit /usr/lib64/and/usr/lib/onCentos64bitandRHEL64 bit. We strongly recommend the following: Useonlyexplicitdynamiclinkingwhenlinkingwith libeTPkcs11,andusethefullpathtoloadthesharedlibraryto minimizeloadtimes.

Supported Object types

11

Usethedlsym()toobtaintheaddressofC_GetFunctionList(). However,toobtainthetableofotherfunctionpointersinthe sharedlibraryyoushoulduseC_GetFunctionList()andnotuse dlsym(). libeTPkcs11mapsaPKCS#11Slottoanyreaderthatisonthe systemwhenthePKCS#11libraryisfirstloaded.Atokenis presentinthisslotwheneveratokenisinsertedintothatreader.

Supported Object types

CKO_DATA CKO_CERTIFICATE (CKC_X_509 only)

Regularcertificate(CKA_CERTIFICATE_CATEGORY=0) CAcertificate (CKA_CERTIFICATE_CATEGORY=2) CKO_PRIVATE_KEY(CKK_RSAonly) CKO_PUBLIC_KEY(CKK_RSAonly) CKO_SECRET_KEY

CKK_DES CKK_DES2 CKK_DES3 CKK_HOTP CKK_AES CKK_RC4 CKK_GENERIC_SECRET CKO_HW_FEATURE.

Note:
CKK_HOTPisnotsupportedontokenmodelswithoutOTP

capabilities.SafeNeteTokenVirtualsimulatestheOTP capacityandsosupportsCKK_HOTP. CKK_AES, CKK_RC4andCKK_GENERIC_SECRETaresupported foreTokenPro(withFormat5),eTokenPro(Java),SafeNet eTokenVirtualandvirtualsessions. CKO_HW_FEATUREwasintroducedinlaterversionsofthe PKCS#11standardtoexplorevarioustokencapabilities. FeatureobjectssupportedbySafeNetAuthenticationClient 8.0arecoveredlaterinthisdocument.

12

Supported Mechanisms
Thesemechanismsaresupportedbyalltokentypes:
CKM_DES_MAC CKM_DES_MAC_GENERAL CKM_DES3_MAC_GENERAL CKM_DES_ECB CKM_DES_CBC CKM_DES_CBC_PAD CKM_DES3_ECB CKM_DES3_CBC CKM_DES3_CBC_PAD CKM_RSA_PKCS_KEY_PAIR_GEN CKM_RSA_PKCS CKM_RSA_X_509 CKM_MD5_RSA_PKCS CKM_SHA1_RSA_PKCS CKM_DES_KEY_GEN CKM_DES2_KEY_GEN CKM_DES3_KEY_GEN CKM_PBE_SHA1_DES3_EDE_CBC CKM_PBE_SHA1_DES2_EDE_CBC CKM_PBA_SHA1_WITH_SHA1_HMAC CKM_PBE_MD5_DES_CBC CKM_PKCS5_PBKD2 CKM_MD5_HMAC_GENERAL CKM_MD5_HMAC CKM_SHA_1_HMAC_GENERAL CKM_SHA_1_HMAC CKM_MD5 CKM_SHA_1 ETCKM_PBA_LEGACY (thisisaproprietarymechanismdescribed

laterinthisdocument) ThesemechanismsaresupportedbyeTokenPro(withFormat5), eTokenPro(Java),SafeNeteTokenVirtualandvirtualsessions:

CKM_AES_MAC CKM_AES_MAC_GENERAL CKM_RC4 CKM_AES_ECB CKM_AES_CBC CKM_AES_CBC_PAD

PKCS#11 Functions
CKM_RC4_KEY_GEN CKM_AES_KEY_GEN CKM_PBE_SHA1_RC4_128 CKM_PBE_SHA1_RC4_40 CKM_GENERIC_SECRET_KEY_GEN CKM_AES_ECB_ENCRYPT_DATA CKM_AES_CBC_ENCRYPT_DATA

13

ThismechanismisnotsupportedontokenswithoutOTPcapability:
CKM_HOTP

Note:
SafeNeteTokenVirtualsimulatestheOTPcapability,sosupports CKM_HOTP.

PKCS#11 Functions
ThissectioncoversdetailsofSafeNetAuthenticationClientPKCS#11 implementation.

Note:
Onhardwaretokens,exceptforeTokenPro(Format5)andeTokenPro (JavaCard),theapplicationmustperformuserlogontocreate,change orremovepublicobjects.

C_Initialize
Accordingtothespecifications,thesubsequentcalltoC_Initialize shouldfailwith CKR_CRYPTOKI_ALREADY_INITIALIZEDerror.SafeNet AuthenticationClientreturnsCKR_OKandincrementstheinit counter.ThisisdonetoovercometheproblemofPKCS#11enabled applicationscallingthirdpartcodethatalsousesPKCS#11API.

14

C_Finalize
Accordingtothespecifications,thesubsequentcalltoC_Finalize shouldfailwithCKR_CRYPTOKI_NOT_INITIALIZEDerror.SafeNet AuthenticationClientwillreturnthiscodeonlywhenthenumberof subsequentC_Finalizecallsovertakesthenumberofprevious C_Initialize calls.

Note:
CallingPKCS#11functionsfromDLLdetachisforbidden.
http://msdn2.microsoft.com/en-us/library/ms682583.aspx

Formoreinformationsee:

AccordingtotheMSDNdescriptionofDllMain,callingfunctionsthat requireDLLsotherthanKernel32.dllmayresultinproblemsthatare difficulttodiagnose.Forexample,callingUser,Shell,andCOM functionscancauseaccessviolationerrors,becausesomefunctions loadothersystemcomponents.Conversely,callingfunctionssuchas theseduringterminationcancauseaccessviolationerrorsbecausethe correspondingcomponentmayalreadyhavebeenunloadedor uninitialized.

C_GetInfo
Theinformationreturnedbythisfunctionmayvarybetweendifferent versionsofPKIClient.ForSafeNetAuthenticationClient8.0the followinginformationisreturned: cryptokiVersion=2.01 manufacturerID=SafeNet,Inc. libraryDescription=eTokenPKCS#11 libraryVersion=8.0

PKCS#11 Functions

15

C_GetSlotList
AccordingtothePKCS#11v2.01standard,thenumberofslots returnedtoanapplicationoncecannotchangeuntilC_Finalize.In reality,thismaybeproblematic.Forinstance,theusermay connect/disconnectthesmartcardreaders.Laterversionsofthe standardallowreturningdifferentnumberofslotsoncethefunctionis calledagainwithaNULLvalueofthepSlotListparameter.SafeNet AuthenticationClientdoesnotdothisforseveralreasons.Oneofthe majorreasonsisproblemofPKCS#11enabledapplicationsusing thirdpartcodewhichalsousesPKCS#11.Theapplicationmaynotbe awareofC_GetSlotListcalldonebythirdpartcode,whileSafeNet AuthenticationClientcannotdistinguishthesourceofcall(inthe contextofthesameprocess).ThereforetheSafeNetAuthentication Client8.0behavesasfollowing: ThenumberofslotsreportedbytheC_GetSlotListfunctiondoes notchangeafterthe C_Initializecall. Thenumberofreportedslots(builtfromthenumberofSafeNet eTokenVirtualslotsandPC/SCslotsforsmartcardreadersand hardwaretokendevices)isconfigurable. ThePC/SCreadersaremappedtothePKCS#11slots.Once mapped,aslotcannotbeusedforanotherreaderuntil C_Finalizeiscalled(toavoidconfusingofapplicationsusingslot description).

C_GetSlotInfo
Theinformationreturnedbythisfunctiondependsontheslotinuse andmayvarybetweenPKIClientversions. TheSafeNetAuthenticationClient8.0returnsthefollowing information: slotDescriptionis <smartcardreadername>forPC/SCslots. <filepath>forsoftwareslots(cuttothefieldsize). <empty>forreservedslots manufacturerID=SafeNet,Inc. flags CKF_REMOVABLE_DEVICE

16
CKF_HW_SLOTexceptforSafeNeteTokenVirtual CKF_TOKEN_PRESENTifthetokenispresentintheslot

hardwareVersion 0.0forPC/SCslotsinabsenceofvirtualdevice 1.0fortokenhardwaredevicesandSafeNeteTokenVirtual managedbySafeNetAuthenticationClientdrivers(Thatis, anytokendeviceexceptfortokenCardandCCIDcompliant tokens) 2.0forsmartcardreadersandCCIDcomplianttoken. firmwareVersion=0.0

Note: Moreinformationmaybereceivedviavendorspecific
extensions.

C_GetTokenInfo
Thereturnedinformationdependsonthetokeninuse.Insomeminor detailsitmayvarybetweenPKIClientversions.Theinformation returnedbythisfunctionhasbeenextendedaccordingtolatest PKCS#11version. ForSafeNetAuthenticationClient8.0thefollowinginformationwill bereturned: labeltokenlabel(UTF8) manufacturerID=SafeNet,Inc. model=eToken serialNumber=tokenserialnumber flags CKF_RNG exceptfortokeninitializedasFIPS CKF_LOGIN_REQUIREDexceptfortokeninitializedasone factor,anemptytoken,orSafeNeteTokenVirtual. CKF_USER_PIN_INITIALIZEDifC_InitPIN hasbeenissued CKF_DUAL_CRYPTO_OPERATIONS CKF_TOKEN_INITIALIZEDifC_InitTokenhasbeencalled CKF_USER_PIN_COUNT_LOWifuserPINretrycounter<3

PKCS#11 Functions

17

CKF_USER_PIN_LOCKEDwheneveruserPINislocked.Itmay

benotpossibletoknowthatthePINislockedtillunsuccessful
C_Login trial. CKF_USER_PIN_TO_BE_CHANGEDifuserPINmustbechanged

(enforcedoninitializationorduetoexpiration).Thisflagis guaranteedtobesetonlyaftersuccessfulC_Loginwith CKU_USER.

ulMaxSessionCount=CK_EFFECTIVELY_INFINITE ulSessionCount=actualnumberofsessionsthatthisapplication

currentlyhasopenwiththetoken ulMaxRwSessionCount=CK_EFFECTIVELY_INFINITE ulRwSessionCount=actualnumberofread/writesessionsthat thisapplicationcurrentlyhasopenwiththetoken ulMaxPinLen=255 ulMinPinLendependsoncurrentpasswordpolicy ulTotalPublicMemory takenfromtokenforhardwaretokens CK_EFFECTIVELY_INFINITEforsoftwaretokens ulFreePublicMemory takenfromtokenforhardwaretokens CK_EFFECTIVELY_INFINITEforsoftwaretokens
ulTotalPrivateMemorysameasulTotalPublicMemory ulFreePrivateMemorysameasulFreePublicMemory

hardwareVersion takenfromtoken(exceptforTokenCardandSafeNeteToken Virtual) 0.0forTokenCardandSafeNeteTokenVirtual firmwareVersion takenfromtoken(exceptforTokenCardandSafeNeteToken Virtual) 0.0forTokenCardandSafeNeteTokenVirtual

utcTimeempty

Note:
Moreinformationmaybereceivedthroughvendorspecific extensions.

18

C_WaitForSlotEvent
PKCS#11doesnotprovideamechanismtocanceltheblocked C_WaitForSlotEventcallexceptforC_Finalize.TheSafeNet AuthenticationClientprovidesmoreflexiblemechanismthrough vendorspecificextensions. TocancelC_WaitForSlotEventfunctionexecution,thetrackerhandle shouldbecreatedinadvance.Thiscanbedoneusingthefunction ETC_CreateTracker. Afterthetrackerhandlecreation,itshandleshouldbepassedto
C_WaitForSlotEventusingthepReservedparameter.Inthiscase,the executionofC_WaitForSlotEventcanbecanceledcallingthefunction ETC_DestroyTracker.

Seealso:ETC_CreateTracker(page64),ETC_DestroyTracker (page65).

C_InitToken
ThebehaviorofC_InitTokeninPKIClient5.0isnotcompatiblewith earlierversionsofeTokenRTE.TheresultsofC_InitTokenmaybe affectedbyPKIClientsettings.Lookforvendorspecificextensionsfor moredetails.

C_SetPIN
ThefunctionC_SetPINmaybecalledwithNULLasoldandnew PIN.InthiscasetheSafeNetAuthenticationClientUIwillbe launched. Iftheuser(CKU_USER)PINcannotbechangedduetopassword policyrestrictionsofthetoken,CKR_INVALID_PINwillbe returned. Ifthenewuser(CKU_USER)PINdoesnotfitthepasswordpolicy requirementsofthetoken,CKR_INVALID_PINor CKR_PIN_LEN_RANGEwillbereturned.

C_InitToken

19

C_Login
IftheuserPINmustbechanged,theC_Loginwillsucceed,butthe subsequentcallstoC_GetTokenInfowillreturn CKF_USER_PIN_TO_BE_CHANGEDflagset.Anyfurthercallrequiring theusertobeloggedinwillfailaslongasC_SetPINisnotissued. ThefunctionC_LoginmaybecalledwithNULLasaPIN.Inthis casetheSafeNetAuthenticationClientUIwillbelaunched.Itwill alsohandletheissueofpasswordchange(accordingtothe passwordpolicyofthetoken). InSingleLogonmode,theusercanlogonwithoutenteringaPIN value,ifthePINvaluewassuppliedtothePKIClientduringa previouslogon.Toenablethis,thePINparametermustcontaina predeterminedvalue.Youcangetthepredeterminedvalueusing ETC_SingleLogonGetPin.SeeETC_SingleLogonGetPin,on page68.

C_CopyObject
ThefunctionC_CopyObjectdoesnotallowobjectstobecopied betweentokens,asitisnotpossibleforhardwaretokenstocopy privateRSAkeys.

C_GetObjectSize
AccordingtothePKCS#11specifications,theC_GetObjectSize functionreturnsanapproximateobjectsizeandmaybeslightly inaccurate.Asaresult,whendeletingorcreatinganobject(for exampleusingC_CopyObject),thereportednumberofbytesmaynot becompletelyaccurateandshouldbemonitored.

C_GetAttributeValue
SafeNetAuthenticationClientmayreturnparticularattributesof privateobjectsevenafterC_Logout. Thefollowingattributesmaybereturned:
CKA_TOKEN

20
CKA_PRIVATE CKA_CERTIFICATE_TYPE CKA_KEY_TYPE CKA_ALWAYS_AUTHENTICATE CKA_MODULUS CKA_PUBLIC_EXPONENT

C_GenerateKeyPair
SafeNetAuthenticationClient8.0allowspassingNULLasa phPublicKeyparameter.Inthiscaseonlyaprivatekeywillbe generated. TokendevicesbasedonCardOSversion4.01ignorethepublic exponentvaluepassedbyanapplication.

C_DeriveKey
ThefunctionC_DeriveKeyreturnsCKR_FUNCTION_NOT_SUPPORTED.

C_SeedRandom
ThefunctionC_SeedRandomreturnssuccess(CKR_OK).

C_CreateObject
ThebooleanattributeETCKA_DESTROYABLEisusedtocreatenon deletablePKCS#11objects.ThisattributeisgiveninC_CreateObject functioninthecallerdefinedobjectstemplate.Tocreatenondeletable PKCS#11objects(RSAkeys,certificates,dataobjectsandsoon)the ETCKA_DESTROYABLEattributemustbeequaltoCK_FALSE.The objectsdefinedasnondeletablecantbechanged,exceptby initializingthetoken. ThedefaultvalueisCK_TRUE.Thismeansthenewobjectwillbe deletablebydefaultifitscreationtemplatehasno ETCKA_DESTROYABLEattribute.

Major Backward Compatibility Issues of PKCS#11

21

X.509 Attribute Tolerance

Thefollowingconditionsshouldbemetwhencreatingacertificate: ThecertifcatemustbecreatedintheDERencodedX.509format. Theserialnumber,subjectandissuerobjectsoftheinternal certificate(CKA_VALUE)mustmatchtheexternalattributes (CKA_SERIAL_NUMBER,CKA_SUBJECT,andCKA_ISSUER). Iftheaboveconditionsarenotmet,theTolerantX509Attributes attributemustbesetto1(True).Ifsetto0(False),theaboveconditions mustbemet. TolerantX509AttributeswasenabledbydefaultineTokenPKIClient versionsearlierthan4.0.

Major Backward Compatibility Issues of PKCS#11

ThefollowingcompatibilityissuesrelatetoeTokenRTE3.65.There hasbeennochangeintheseissuesbetweenetokenPKIClient4.0and 5.0. BehavioroffunctionsC_InitToken andC_InitPINhaschanged. Previousversionsmightdisplaypopupwindowsinvarious situations.Forinstance,iftokenrequiresusertobeloggedinto changethepublicobject,theUIcouldappeartoaskfortheuser password.PKIClient4.0,4.5and5.0donotdisplayaUIexcept thatcoveredbythisdocument(whichmaybepredictedand eliminatedbytheapplication). InformationreturnedbyC_GetSlotInfoandC_GetTokenInfo varies. PKIClientnowenforcespasswordpolicymechanismsas describedinlaterversionsofthePKCS#11standard. TheimplementationofCryptAcquireContextdealswithflags (CRYPT_NEWKEYSET|CRYPT_SILENT)indifferentwaysin PKIClient4.55and5.00. InthepreviousversionsofPKIthoseflagsleadtofunctionfailure, whileinthecurrentversionofPKIthefunctionsucceeds.

22 CryptAcquireContextwithCRYPT_NEWKEYSETisafirststepin thetwostepprocessofRSAkeygenerationorimport.Theentire processrequiresthattheuserentersatokenpassword.Sincethe flagCRYPT_SILENTcontradictsthis,theprocessofthekey generationorimportwillfail. Thedifferencebetweenpreviousandcurrentimplementationsis thatinthepreviousimplementations,thefailureoccuredinthe firststep(CryptAcquireContext),whilethenewimplementation failureoccursatthesecondstep(CryptGenKEyor CryptImportKey)onlyiftheuserdidntlogin.

Chapter 3

Token-Specific PKCS#11 Extensions

SafeNetAuthenticationClient8.0providesawidefunctionalitythat cannotbeexpressedintermsofthePKCS#11standard.Itisprovided throughspecialextensionstoPKCS#11.

In this chapter:
General Overview Vendor-Specific Information Reference

24

General Overview
Understanding Token-Specific PKCS#11 Extensions
Theextensionsareasfollows: Extensionstothefuturestandardversions.TheSafeNet AuthenticationClientimplementsPKCS#11v2.01.However,it supportsmanyfeaturesintroducedinthelaterversionsofthe PKCS#11standard.Theyarecoveredinthisdocument.The examplesofsuchextensionsare: OTPsupport; DistinguishingbetweenuserandCAcertificates; Returncodesandflagsrelatedtothepasswordpolicy. Vendorspecificattributesthatcanbeimplementedintheregular PKCS#11objects.TheexampleofsuchattributeisdurationofOTP valuepresentationonthetoken. Featureobjects:PKCS#11v2.20introduceshardwarefeature objects(CKO_HW_FEATURE)asPKCS#11objectsrepresenting variousdevicefeatures.Theapplicationdoesnotcreatesuch objects.Neitherhasitfoundtheminthetypical C_FindObjectsInitcallunlesstheparticularfeaturetypewas explicitlyspecifiedinthesearchtemplate.SafeNetAuthentication Clientusesfeatureobjectstorepresentandmanagevarioustoken characteristics.Themostusefulfeatureobjectsaretokenobject (ETCKH_TOKEN_OBJECT)representingthewholetokenand PasswordPolicyobject(ETCKH_PIN_POLICY)representingPIN policysettingsofthetoken.Featureobjectsarenotconsidered storageobjects,sotheydonothaveaCKA_PRIVATEattribute. Unlessspecifieddifferently,theybehaveasfollows: Theymaybereadwithoutauthentication. TheyhaveattributeCKA_MODIFIABLEattributespecifyingif theobjectmaybechangedinprinciple.Someattributes cannotbechangedbyprogram:theyrepresenttherealstatus oftheobjectandarechangedonlyasapartoftoken operations(suchaslastpasswordchangedate). TheyhaveattributeETCKA_OWNER (CK_ULONG)definingwho maychangetheobject.Thetokenobjecthasnotsuch attribute.Thesupportedvaluesare:

General Overview
CKU_USER CKU_SO IfCKA_MODIFIABLEisFALSE,thisattributeshouldbe

25

ignored VendorspecificfunctionsareusedwhereassomeSafeNet AuthenticationClientfunctionalitycannotbeexpressedproperly viaexistingPKCS#11functions.Theapplicationusesfunction ETC_GetFunctionListExtogetthestructureofpointerstothe vendorspecificfunctions(justasitusesC_GetFunctionListto getthestructureofpointerstothestandardfunctions). Thefollowingsectionsdescribethefunctionalityprovidedbythe tokenspecificPKCS#11extensions.Thenextsectioncontainsthe formalreference.

Encoding of Text Attributes, Fields and Parameters

UNICODE Support
Somefunctionshaveparametersthatmaybetreatedastextstrings. ThetypicalexampleisfilenameofSafeNeteTokenVirtual.Whenever itisnotmentioned,UTF8isassumed.AfunctionthatcreatesSafeNet eTokenVirtualorassociatesitwiththeslotshouldgetaUTF8string. InnonUNICODEapplications,passinganullterminatedASCII stringisenough.

Note:
AparticulartokenmayhaverestrictionsonthestoringofnonASCII informationforbackwardcompatibility.Wethereforerecommend usingASCIIonly.

Null-termination of strings
Usually,thePKCS#11specdoesnotusenullterminatorsforstrings: Forobjectattributes,theattributelengthispassedexplicitly. Structurefieldshaveafixedsize(andareusuallyblankpadded). SafeNetAuthenticationClientextensions,inmostcases,followamore friendlyconvention.Unlessspecifiedotherwise:

26 Thereturnedattributesarenullterminated(theattributelength takesintoaccountthenullterminator). TheSafeNetAuthenticationClientisreadytogettheincoming attributeswithandwithoutanullterminator.

SafeNet Authentication Client

ManyaspectsoftheSafeNetAuthenticationClientbehaviorare configurable.Typicalexamplesofconfigurablebehaviorare: Passwordqualitysettingstobeusedwheninitializingthetoken. 2048bitRSAkeysupport. TheconfigurableaspectsoftheSafeNetAuthenticationClientvaryin theirflexibility: Someofthemmaybemodifiedbyuser,whileothersmaybe modifiedonlybythecomputeradministrator. Someofthemmaybeconfigurablepermanentlyonaper applicationbasis. Someofthemmayevenbemodifiedperprocessintheruntime. TheSafeNetAuthenticationClientprovidesthefollowingfunctionsto dealwithproperties:
ETC_GetPropertyreturnsthecurrentsettingofparticular

property.Dependingonthepropertythesamevaluemaybeor maybenotreturnedforallprocesses. ETC_SetPropertysetsthenewvaluefortheproperty.Ifaninvalid valueispassed,thefunctionmaynotfail,buttheresultmaynot beasexpectedbytheapplication.Thepropertymaybechanged fortheentireprocessorforthecurrentthreadonly,dependingon thepassedETCKF_PROPERTY_THREADflag.PassingNULLvalue effectivelyresetstheeffectiftheallpreviouscallsto ETC_SetProperty.

General Overview

27

Slot/Token IOCTL
Somerarelyusedoperationsarenotpresentedasseparatedfunctions. TheyarejoinedtomultipurposeIOCTLfunctionsinstead.Thereare twosuchfunctions:
ETC_DeviceIOCTLgetsslotIDasaparameter.Thisfunctionis

necessarysincestandardPKCS#11providesalmostnofunctions thatcanbeappliedtotheslot.Itisdedicatedtooperations targetedtoaparticularslot(possiblyevenintheabsenceofthe token).Anexampleofsuchoperationisgettingthefilename associatedwithSafeNeteTokenVirtual. ETC_TokenIOCTLgetssessionandobjecthandlesasparameters. Thisfunctionisnecessaryforoperationsthatcannotbe reasonablyimpressedviaexistingPKCS#11functions(likegetting orsettingparticularattributes).

Extensions Related to Operations with Slots and Tokens

SafeNet eToken Virtual
TheSafeNeteTokenvirtualisafileinaspecialformatthatactsasa tokenintermsofPKCS#11.Privateobjectsinthistokenareencrypted withtheuserpassword.Itismostlyusedasapartofemployeeonthe roadsolution. UseETC_DeviceIOCTLwith
ETCK_IODEV_SOFTWARE_TOKEN_PLUGINtoplugintheSafeNet

eTokenvirtualtothefreeslot. UseETC_DeviceIOCTLwithETCK_IODEV_FULL_NAMEtogetthefile nameofthefileassociatedwiththeslot. UseETC_DeviceIOCTLwith ETCK_IODEV_SOFTWARE_TOKEN_PLUGOUTtodisconnecttheSafeNet eTokenVirtual.Thefileisnotremovedonthisstage;the applicationmayremoveitmanually.

Note:
SafeNeteTokenvirtualdoesnotsupportCKU_SO.

28

Transactions
TheSafeNetAuthenticationClientensuresthatnootherapplication willusethesametokenduringasingleapplicationcalltoanyAPI function.Howeveritispossibletolockatokenforlongerperiodof time.ThefunctionETC_BeginTransactionisusedtolockthetoken fortheexclusiveuseoftheapplication.Thefunction ETC_EndTransactionunlocksthetoken. Notethefollowing: Transactionsareusablewhenapplicationpreparesitsdataonthe token.Itensuresthatthetokenstateisnotchangedbyanyother applicationduringthetransaction. Transactionsareusablewhenapplicationperformsthesequence ofoperationswiththetoken.Itmayincreasetheperformance significantly. Transactionsdonotguaranteealogofchangesdonetothetoken. Ifthetokenisremovedortheapplicationcrashesduring transaction,thedataonthetokenwillnotberolledback.Itis moresimilartothesmartcardlocking,nottothedatabase transaction. Aslongasthetransactionisopened,otherapplicationswillnotbe abletoaccessthetoken,evenforthemostinnocentoperations (suchasC_GetSlotList).Donotkeepthetransactionopened longerthatitisneeded. DonotuseanyinteractiveUIduringtransactions.

Notifications
Amajorproblemwiththestandardeventtrackingmechanismin PKCS#11(C_WaitForSlotEvent)isthatitcannotbestopped.Itwill continuelisteningtillC_Finalizecall.Sometimesthisbehavioristoo restrictive.Theproposedsolutionusesthelastreservedparametersof thefunction.Theapplicationshould: Createthetrackerbycallingproprietaryfunction ETC_CreateTracker. CallC_WaitForSlotEvent,passingthepointertothetrackerasa parameterinordertostartlistening. Destroythetrackerbycallingtheproprietaryfunction ETC_DestroyTrackertostoplistening.

General Overview

29

Token-Less Operations
PKCS#11cryptographicoperationsareperformedwithinasession openedwithatoken.So,intheabsenceofatoken,cryptographic operationscannotbelaunched(evenifitwoulduseonlysession objects).SafeNetAuthenticationClientovercomesthisrestrictionwith thefunctionETC_CreateVirtualSession.Thisallowsthecreationofa sessionthatisnotassociatedwithanytoken.Multiplecallstothis functioncreatemultipleindependentsessions.Thevirtualsessionis usedtoperformtokenlessoperations,suchascryptographic operationsusedfortokenunblocking.Thefunction C_GetSessionInfo foravirtualsessionwillfailwitherrorcode CKR_FUNCTION_FAILED.

Password Quality Settings

TheSafeNetAuthenticationClientenforcesthepasswordquality settingswhenworkingwiththetoken.Thepasswordqualitysettings mayinclude: Minimumpasswordlength Maximumpasswordusageperiod Minimumpasswordusageperiod Warningperiodbeforepasswordexpiration Passwordhistorysize Minimumcharacterrepetitionsinapassword Passwordcomplexityrules Numerals,uppercaseletters,lowercaselettersorspecial characterspermitted,mandatoryorforbidden. Inaddition,theadministratormayenforceuserstochangethe passworduponthefirstuse.

30 Thepasswordqualitysettingsfortheparticulartokenisdefined duringthetokeninitializationandmaybechangedlater.Ifno passwordqualitysettingisstoredonthetoken(itmaybedone intentionallyorthetokenmaybeinitializedwithapreviousversionof eTokenPKIClient),thecurrentsettingsoftheSafeNetAuthentication Clientonthemachinewillbeused.Theyaredefinedbythe correspondingSafeNetAuthenticationClient.

Note:
ThepasswordpolicymechanismimplementedintheeTokenPKI Client4.0,4.5and5.0isnotbackwardcompatiblewiththeformer versionsoftheeTokenPKIClient. ThemechanismoperatesasdescribedinthePKCS#11v2.20: IfusermustchangethePIN(duetoadministratorenforcementor expiration),theC_LoginwithCKU_USERwillsucceed. ThesubsequentcalltoC_GetTokenInfowillreturn CKF_USER_PIN_TO_BE_CHANGEDflagset. UntilC_SetPIN isdone,anysubsequentPKCS#11callwhich requiresusertobeloggedinwillfailwiththeerrorcode CKR_PIN_EXPIRED. IfthenewlysuppliedPINcannotbeacceptedduetothecurrent passwordpolicy,thefunctionC_SetPINwillfailwiththeerror codeeitherCKR_PIN_LEN_RANGE(fortooshortpassword)or CKR_PIN_INVALID(foranyotherfailure).

Extended features in eToken PKI Client 5.0

TheeTokenPKIClient5.0extendsthestandardcapabilitieswiththe followingfeatures: UsingC_SetPINwithNULLpassedasbotholdandnewPIN,the applicationinvokestheeTokenPKIClientUI.Itmanages automaticallyallaspectsofthepasswordpolicy,performingall necessarychecks. SimilarlyusingC_LoginwithNULLinthecasewhentheuser passwordchangeisenforcedwillswitchyouautomaticallytothe passwordchangeprocess. Thepasswordpolicysettingsoftheparticulartokenmaybe examinedandcontrolledbyusingthespecialhardwarefeature objectETCKH_PIN_POLICY.Thisobjectmaybecreatedduringthe tokeninitialization.

General Overview

31

ThecurrentsettingsofthePKIClientitselfmaybeexaminedby readingthecorrespondingproperties. ByissuingC_GetSessionInfoafterC_Loginorafterunsuccessful C_SetPIN,theapplicationmaygetmoredetailedinformation aboutparticularneedtochangethepasswordoraboutparticular reasonoffailuretochangeit.ItisreturnedintheulDeviceError field. TheIOCTL ETCK_IOCTL_PIN_EVALUATEmaybeissuedtocheckthe acceptanceofthenewpasswordwithoutarealattempttochange it.

Additional Notes
ThepasswordpolicyisappliedonlytotheuserPIN. WhenadministratorsetstheuserPIN(C_InitPIN or ETC_InitPIN)functions,thepasswordpolicyisnotapplied. WhentheusingPINisunlockedbyusingchallengeresponse authentication(ETC_UnlockPIN)thepasswordpolicyisapplied buttheminimalpasswordageisignored.

Special Token Capabilities

OTP
SafeNetAuthenticationClientsupportsOneTimePasswords(OTP)as definedinPKCS#11v2.20Amendment1(PKCS#11Mechanismsfor OneTimePasswordTokens).Theonlycurrentlysupported mechanismisCKM_HOTP. WhenusingOTPfunctionality,thefollowingshouldbekeptinmind: NotalltokenssupportOTPfunctionality.Theapplicationshould checkwhetherthetokensupportstheCKM_HOTPmechanism. Thesupportedkeylengthmayvarybetweentokens.Itshouldbe checkedbyapplicationbyusingtheC_GetMechanismInfo function. ThehardwaretokenssupportingOTPhavesomerestrictions.In particular: OnlyoneOTPkeypertokenissupported.

32 TheflagCKF_NEXT_OTPisnotsupportedforhardwaretokens (forsecurityreasons). TheflagCKF_EXCLUDE_COUNTERissupported,butonsome oldermodelsofeTokenNGOTPtheoperationmayfail. Thefollowingattributesarenotsupportedforhardware tokens:

CKA_OTP_USER_IDENTIFIER CKA_OTP_SERVICE_IDENTIFIER CKA_OTP_SERVICE_LOGO CKA_OTP_SERVICE_LOGO_TYPE

Thefollowingvendorspecificattributesaresupportedforthe hardwaretokens: ETCKA_OTP_DURATIONdurationofOTPvalue representationontheLCD,inseconds.Maybepassed duringcreation.Maybepossibletochangelater, dependingonETCKA_MAY_CHANGE_DURATION. ETCKA_MAY_SET_DURATIONdefineswhetheritispossible tochangedurationafterobjectcreation.Cannotbe changedafterobjectcreation. ItispossibletousetheCKM_HOTPmechanisminthevirtualsession (toperformserversideOTPvalidation). CKA_OTP_TIMEattributeisnotsupportedasithasnosensefor CKM_HOTP. Thenewlyintroducednotification(CKN_OTP_CHANGED)isnot supportedbytheSafeNetAuthenticationClient. ForSafeNeteTokenvirtual,theOTPkeyobjectbehavesaccording totheCKA_PRIVATEattribute.Forhardwaretokens,CKA_PRIVATE attributesisignoredasassumedtobeFALSE.Howeverobject creation,deletionorchangingthedisplaydurationrequires CKU_USERtobeloggedin. OtherattributesdefinedinPKCS#11havethefollowingrestrictions:
CKA_OTP_FORMATonlyCK_OTP_FORMAT_DECIMALissupported. CKA_OTP_LENGTHmustbe6(accordingtoHOTPspec). CKA_OTP_CHALLENGE_REQUIREMENTshouldbe CK_OTP_PARAM_IGNORED. CKA_OTP_TIME_REQUIREMENT shouldbeCK_OTP_PARAM_IGNORED. CKA_OTP_COUNTER_REQUIREMENTshouldbe CK_OTP_PARAM_OPTIONALforvirtualsessionsand CK_OTP_PARAM_IGNOREDotherwise.

Vendor-Specific Information

33

CKA_OTP_PIN_REQUIREMENTshouldbeCK_OTP_PARAM_IGNORED. CKA_OTP_COUNTER (bytearray).Itshallbe8bytesinbigendian

form.Thedefaultvalueuponcreationis0.Thisvalueisnon modifiable(exceptforvirtualsession).

Vendor-Specific Information
VendorspecificAPIsaredefinedintheeTPkcs11.hheaderfile.

Vendor-Specific OTP Key Attributes

ThefollowingvendorspecificattributesaredefinedforOTPkeys:
ETCKA_OTP_DURATIONdurationofOTPvaluerepresentationon

theLCD,inseconds.Maybepassedduringcreation.Maybe possibletochangelater,dependingon ETCKA_MAY_CHANGE_DURATION. ETCKA_MAY_SET_DURATIONdefineswhetheritispossibleto changedurationafterobjectcreation.Cannotbechangedafter objectcreation.

Secondary authentication
Understanding Secondary Authentication
TheSafeNetAuthenticationClientmaysupporttheadditionallevelof protectionforRSAprivatekeys.Inthismodeanadditionalpassword mustbesuppliedeachtimewhenthecryptographicoperationwith theRSAprivatekeyisperformed.Thisfeatureisnamedsecondary authentication,meaningthatinordertousetheparticularRSAkey, theapplicationshouldpassanadditional(secondary)authentication (theusualuserloginisconsideredasaprimaryauthentication). Thesecondaryauthenticationiscontrolledbycombinationoftwo factors:thekeyobjectattributespassedduringtheRSAkeyobject creationandthespecialhardwarefeatureobjectETCKH_2AUTH.

34 MostPKCS#11applicationsarenotawareofthesecondary authenticationmechanism(asitwasaddedonlyinv2.20ofthe PKCS#11spec).Thespecialhardwarefeatureobjectallows configurationofthedefaultbehaviorofthetoken,givingmore flexibilityandpowertotheofftheshelfapplications.

Creation of the Protected RSA Key

ThelaterversionsofPKCS#11standardintroducesthenewattribute fortheRSAprivatekeyobject:CKA_ALWAYS_AUTHENTICATE.Beingset toTRUEduringobjectcreation,thisattributedefinesthatthePIN presentationisrequiredeachtimewhenthekeyisused.Thestandard doesnotdefinewhetheritistheregularuserPINortheseparatePIN. TheSafeNetAuthenticationClientusesseparatePINforeachsuch key.NotethatthisPINisnotsynchronizedwiththeregularuserPIN (isnotchangedtogetherwithit,isnotsubjecttoanyPINpolicyand cannotbeunlocked).Thiskeyisrequiredlaterforeachcryptographic operationandisnotrequiredforanyotheroperationwiththekey (suchaschangingofparticularattributesorobjectdeletion). Accordingtothestandard,thisattributecannotbechangedafter objectcreation. ThePKCS#11specdoesnotaddressthepassingoftheinitialPIN valueduringkeycreation.TheSafeNetAuthenticationClient introducesforthispurposetheproprietaryattributeETCKA _2NDAUTH_PIN,whichcontainsaUTF8encodedPINvalue.This attributemaybeusedonlyduringobjectcreation.Ifthisattributeis notpassed,theSafeNetAuthenticationClientwillpopupthespecial window,askingusertoenterthepassword.Ifitisnotsupplied(user cancelstheoperation),thebehaviordependsonETCKH_2AUTHobject, describedbelow.

Supplying Special PIN to the RSA Private Key Operation

ThePINforthesecondaryauthenticationisprovidedaccordingtothe v2.20ofthePKCS#11spec: TheapplicationissuesaPKCS#11callstartingthecryptographic operation(suchasC_SignInit)withtheRSAkeyprotectedwith thesecondaryauthenticationPIN(having CKA_ALWAYS_AUTHENTICATEattributesettoTRUE).

Vendor-Specific Information TheapplicationissuesaC_Logincallwithinthesamesession, passingCKU_CONTEXT_SPECIFICinsteadoftheusertypeand properPIN. Theapplicationcompletesthecryptographicoperation.

35

SafeNetAuthenticationClientextendsthisbehaviortosupport secondaryauthenticationprotectedkeysinthelegacyapplicationsin thefollowingway:ifC_LoginwithCKU_CONTEXT_SPECIFICwasnot issuedforthesecondaryauthenticationprotectedkey,theSafeNet AuthenticationClientwillpopupthewindowaskingusertosupply thepassword. TheSafeNetAuthenticationClientdoesnotprovideaninterfaceto changetheperkeyPINaftercreation.

Configuring Secondary Authentication for the Token

ThespecialhardwarefeatureobjectETCKH_2AUTHcontrolsthe behaviorofthesecondaryauthenticationfeatureonapertokenbasis. ItcontrolsthecreationofthenewRSAprivatekeyobjects(oncethe particularkeyobjecthasbeencreated,itsbehaviorcannotchange anymore).Thisfeatureobjectmaybecreatedduringthetoken initializationsession(otherwiseitiscreatedautomatically).

Token initialization
Why Extensions are Needed for Initialization
TheinitializationfunctionsprovidedinPKCS#11(C_InitTokenand C_InitPIN)arenotflexibleenough.Thisisbecausetokensfrom differentvendorsaresodifferent,itisalmostimpossibletocoverthem allbythesamestandardAPI.Belowarejustseveralfeaturesof SafeNetAuthenticationClientthatcannotbecoveredbythestandard functions. ItisimpossibletodefineerrorretrycountersforuserandSOPIN. Ifthetokenisinitializedinseveralmodes(forinstance,FIPSor onefactor),thereisnowaytoaddressit. Ifthetokenhasspecialcapabilitiesthatshouldbeexplicitly enabled(suchasOTPsupport)thereisnowaytodoit.

36

Proprietary Initialization Functions

Thetokeninitializationistwoormorestepsprocess.Inorderto managethisprocessthefollowingproprietaryfunctionsare introduced:
ETC_InitTokenInitthisfunctionstartstheprocessoftoken

initialization.
ETC_InitTokenFinalthisfunctioncompletestheprocessof

tokeninitialization. ETC_InitPINthisfunctioninitializestheuserPIN(providing moreflexibilitythanthestandardfunctionC_InitPIN).

Initialization Flow
Theflowofinitializationisasfollows: 1. Theapplicationexplorestokencapabilities,suchastheabilityto supportOTP,andprerequisitesrequiredforinitialization(need fortheoldPIN)intheregularsession,usingthetokenhardware featureobject. Theapplicationclosesallopensessionswiththetoken.Thisis becausePKCS#11requiresthatnosessionsareopenduring C_InitTokencall. ETC_InitTokenInitstartstheinitializationprocessandopensthe specialsession.Thissessionservesasthecontextofinitialization andwillbeclosedinETC_InitTokenFinalcall.Theapplication maycloseitbyC_CloseSessioncalltocanceltheinitialization.It isimportanttomentionthatthetokenwillremainin unpredictablestate.SOPINisommitedinthefollowing cricumstances. a. InitializingthetokenwithoutSO.Thiswillhappenif C_InitPIN orETC_InitPINiscalledduringtheinitialization session. b. Initializingonefactortokenoremptytoken(dependingon subsequentcalls). Ifthetokenrequiresoldpasswordtobepresentedinordertore initializethetoken,theapplicationshouldissuetheproper C_Login call.

2.

3.

4.

Vendor-Specific Information 5.

37

6.

IssueC_CreateObjecttocreatethetokenobject.Unlessyou initializethetokenasempty,thisisamandatorystep.Optionally issuemoreC_CreateObjectcallstocreateotherfeatureobjects. Typically,thepasswordpolicyobjectiscreatedhere.Notethat youcreatefeatureobjectshere.Thisisallowedonlyinan initializationsession.Anyattempttocreateanobjectthatmakes nosensefortheinitializationprocessmayfail(or ETC_InitTokenFinalmayfail). IssueC_InitPINorETC_InitPIN.Thisfunctioninitializestheuser PIN.ETC_InitPINgivesyoumoreflexibility.Thesefunctionsare notsubjecttothepasswordpolicies.Ifyoudonotissuethiscall: a. IfthetokenhasSOPIN,thetokenwillbeinitialized,butthe CKF_USER_PIN_INITIALIZED flagwillberesetinthetoken info.Theapplicationwillnotbeabletoperformuserlogin, untiltheSOinitializestheuserPIN. b. IfthetokenhasnoSOPIN,onefactororemptytokenis assumed(dependingontheattributesofthecreatedtoken object. TheETC_InitFinalcallcompletesthetokeninitializationprocess andclosestheinitializationsession.

7.

Notes:
TheSafeNetAuthenticationClientmayperformpartofthejob duringcallsissuedbyanapplicationorjustcollectthe informationandperformtheentireprocessduring ETC_InitFinal.Thisisimplementationspecificandmaychange betweenSafeNetAuthenticationClientversions.Theapplication cannotassumetheexactbehavior. Thevalidorinvalidvaluesofattributesorparametersmay dependontheentireprocess.Forexample,passingnonNULL labelintheETC_InitTokenInitfunctioniscorrectexceptwhen thetokenobjectdefinesthetokenasemptyfollowingcreation. Similarly,thepassingofapasswordpolicyobjectassumesthatthe initializedtokencontainsauserpassword. Someofparametersdependonthetokentype.Forexample,many parameterswillnotmakesenseforasoftwaretoken. Onlyspecialobjectscontrollingtheflowofinitializationmaybe createdintheinitializationsession. Hereareseveralexamplesoftheinitializationflow:

38 To create an empty token:

ETC_InitTokenInit(SO=NULL, Label=NULL) ETC_InitTokenFinal()

To create a one-factor authentication token (no user PIN)

ETC_InitTokenInit(SO=NULL) C_CreateObject(ETCKH_TOKEN_OBJECT with ETCKA_ONE_FACTOR=TRUE) ETC_InitTokenFinal()

To create a token without SO

ETC_InitTokenInit(SO=NULL) optional C_CreateObject(ETCKH_TOKEN_OBJECT) optional C_CreateObject(ETCKH_PIN_POLICY) C_InitPIN() or ETC_InitPIN() ETC_InitTokenFinal()

To create a token with SO

ETC_InitTokenInit(SO is not NULL) optional C_CreateObject(ETCKH_TOKEN_OBJECT) optional C_CreateObject(ETCKH_PIN_POLICY) C_InitPIN() or ETC_InitPIN() // may be postponed ETC_InitTokenFinal()

Controlling Initialization Parameters

Forallattributesdefinedhere,unlessstatedotherwise: Ifanattributeisnotpassed,thecorrespondingpropertysettingis lookedforintheregistry. Ifthereisnosuchsetting,SafeNetAuthenticationClienthassome internalbehavior(describedtogetherwithanattribute).Inrare casesthisinternalbehaviormaybetokendependent.

Vendor-Specific Information

39

Creation of Token Object

Thetokenobjectisusedtodefinethemajorcharacteristicsofthe newlyinitializedtoken.Thefollowingattributesmaybesetwhen creatingthisobjectduringinitialization:
CKA_CLASSMandatory,mustbeCKO_HW_FEATURE CKA_HW_FEATURE_TYPEMandatory,mustbe ETCKH_TOKEN_OBJECT ETCKA_FORMAT_VERSIONIfnotpassed,thedefaultvaluewill

dependonthetokentype.ForallCardOSbasedtokendevicesthe defaultvalueistakenfromthepropertyLEGACY-FORMAT-VERSION. ETCKA_ONE_FACTORTRUEifthetokenshouldbeinitializedas onefactor.Default:FALSE. ETCKA_FIPSTRUEiftokenshouldbeinitializedasFIPS compliant.Default:FALSE. ETCKA_HMAC_SHA1TRUEifHMAC_SHA1supportisrequired.This algorithmisessentialforOTPsupport.ItisignoredforSafeNet eTokenVirtualDefault:TRUEforalleTokenNGmodels. ETCKA_RSA_2048TRUEifthetokenisrequiredtosupport2048 bitRSAkeys.ItisignoredforSafeNeteTokenVirtualandforall tokenmodelshavingonboardsupportfor2048bitRSA(CardOS 4.20bbasedtokens).Default:TRUEforalleTokenPromodels usingCardOS4.20andhigher. ETCKA_RSA_AREA_SIZEsizeofarea(inbytes)tobereservedfor RSAkeys.CardOSbasedtokensusethisparametertoreservethe placeforRSAkeys.TheRSAkeysmaybecreatedonlywithinthis area(anditcannotbeusedtostoreanyotherdata).Passing0 preventscreationofRSAkeysonthetoken(effectivelyleaving moreplacefordata).Default:RTEcomputesitbasedoncard EEPROMsize.

40

Creation of Password Policy Object

Typically,theprocessoftokeninitializationincludescreationofthe passwordpolicyobject(unlessaonefactororemptytokenis initialized).Ifthisobjectisnotcreatedduringtokeninitialization, therewillbenoontokenpasswordpolicymanagementandSafeNet AuthenticationClientwillusethecurrentpasswordpolicyofthe computereachtime(whichmaycausethetokentobehavedifferently ondifferentcomputers).Thefollowingattributesmaybesetwhen creatingtheobject:
CKA_CLASSMandatory,mustbeCKO_HW_FEATURE CKA_HW_FEATURE_TYPEMandatory,mustbeETCKH_PIN_POLICY ETCKA_PIN_POLICY_TYPEMandatory,mustbe ETCKPT_GENERAL_PIN_POLICY ETCKA_OWNERDefault:CKU_SO fortokenwithSO,CKU_USER CKA_MODIFIABLEDefault:TRUEifETCKA_OWNER=CKU_SO

Allotherattributesofthepasswordpolicyobjectmaybepassed, exceptforETCKA_PROXY.Anymissingattributeistakenfromthe correspondingSafeNetAuthenticationClient.Thetypicalwayisto createthepasswordpolicyobjectwithmandatoryattributesonly, enforcingthedefaultsettingsfromtheSafeNetAuthenticationClient propertiestobetaken.

Note:
Theapplicationisresponsiblefortheconsistencyoftheattributes, evenifsomeofthemarepassedexplicitlyandothersaretakenfrom theproperties.Forexample,iftheminimalpasswordageissetequal toorhigherthanthepasswordexpirationperiodtheoperationwill fail.

Token Initialization Keys

Tokeninitializationkeysmaybesettoensurethatthetokenmaybe initializedonlybytheproperentity.ThisisrequiredonlyforCardOS basedtokens.

Vendor-Specific Information

41

Theoldkeyisassumedtobethecurrentone.Thenewkeyisassumed tobeswitchedtoafterinitialization.Absenceofoneofthemmeans thatthedefaultkeyisused.So,ifanapplicationneedstousethe initializationkeydifferingfromthedefault(butnottochangeit)it shouldcreatetwoobjectswiththesamekeyvalue.

Note:
Ifthewronginitializationkeyispassed,theinitializationwillfail.By continuousfailurestheapplicationmaylockthekeyanditwillnotbe possibletoreinitializethetoken. Typicallythetokensareshippedalreadyinitializedwiththedefault key.So,ifapplicationdoesnotneedtogainmorecontroloverthe initializationprocess,thereisnoneedtocreatetheseobjects. Ifcreated,thekeyobjectsshouldhavethefollowingattributes:
CKA_CLASS=CKO_SECRET_KEY CKA_KEY_TYPE =CKK_DES2 CKA_LABEL =OLDKEYorNEWKEY CKA_VALUE =16byteskeyvalue

Note:
PKIClientversionsprevioustoversion4.0performedMD5 calculationsonpassedvaluesbeforeactuallyusingitwiththetoken. Thiswasdonetoserveapplicationssupplyingdatafromhuman input.PKIClient4.0,4.5and5.0takethepassedvalueasthekey materialwithoutanyadditionalconversion.Thisoptionisusefulfor bigdeploymentswhereinitializationkeysmayvaryforeachtoken andarekeptinadatabase.Ifyourapplicationwantstousethesame inputsasinformerRTEversions,computeMD5hashofyourdata andusetheoutputasthekeyvalue.ThisisexactlywhatSAPIdoesto ensurebackwardcompatibility.

Other Hardware Feature Objects

Theinitializationprocessistheonlyopportunitytocreateother hardwarefeatureobjects(suchasETCKH_2NDAUTHand ETCKH_PRIVATE_CACHING).Ifnotcreatedexplicitlybyapplication,they willbecreatedautomaticallybytheSafeNetAuthenticationClient.

42

PIN Initialization
TheuserPINmaybeinitializedbyC_InitPINfunction(asdescribed inPKCS#11standard).ThereisproprietaryfunctionETC_InitPIN that: ProvidestheretrycounterfornewlycreatedPIN. ForcestheusertochangethePINuponthefirstlogin. Bothfunctionsmaybecalledinthesameconditions,eitherintheSO sessionorinthespecialinitializationsessiondescribedpreviously.

Behavior of Standard C_InitToken and C_InitPIN Functions

ThestandardwaytoinitializetokensinPKCS#11isbyissuinga C_InitTokencallfollowedbyaC_InitPINcall.Itisveryrestrictive andprovidesnoflexibility.ThefunctionsaresupportedbySafeNet AuthenticationClientareasfollows:
C_InitTokentreatsthepassedPINasnewSOPIN.

IfthetokenwasinitializedwithoutSOandrequireduser passwordforreinitialization,theoperationwillfail. Nopasswordpolicyobjectiscreated(proxybehavior). SoftwaretokencannotbeinitializedviaC_InitToken(sinceit doesnotsupportSO). Alldecisionsinregardtocustomizableparametersaretaken automaticallybySafeNetAuthenticationClientandmayvaryin thefutureversions.Someofthemmaybeaffectedbyvarious propertysettings. ThetokenhastheCKF_USER_PIN_INITIALIZEDflagreset,untilthe C_InitPIN(orETC_InitPIN)functionisbecalled.

Vendor-Specific Information

43

Backward Compatibility Issues

Tokens Initialized by Earlier PKI Client Versions
IfatokenformattedinapreviousPKIClientversionhadthe CKF_USER_PIN_INITIALIZEDflagreset,thetokenwillbehave differentlynow.InpreviousPKIClientversions,PKCS#11wouldfail tologinwithsuchatoken.InSafeNetAuthenticationClient8.0the CKF_USER_PIN_INITIALIZEDflagisnotsetforsuchatoken,but passwordpolicyenforcespasswordchangeonthefirstlogin.

Using Tokens Initialized by PKI Client 4.0, 4.5 or 5.0 in Earlier Versions
Theapplicationshouldconsiderwhethertoinitializethetokentobe backwardcompatible.Keepingtokenbackwardcompatiblemayhave significantperformancepenalty.Tokensarenotexpectedtowork slowerthaninolderPKIClientversionsinmostreallifescenarios,but someperformancegainwillbeadverselyaffected. Usingsomefeatures(suchasonefactorauthentication)preventtoken frombeingbackwardcompatible. EarlierPKIClientversionswillignorepasswordpolicysettingsofthe token,astheyusedadifferentmechanism. Thewaytocontrolduringinitializationwhetherthetokenwillbe backwardcompatibleisbysettingtheETCKA_FORMAT_VERSION attribute(explicitorviaproperty)inthetokenobject.Ifthetokenis initializedtobebackwardcompatible,C_InitPINorETC_InitPIN mustbecalledduringinitializationsession. EnforcementofpasswordchangeforbackwardcompatibleCardOS tokenswillbedisplayedinearliereTokenRTEversionsasPKCS#11 PINnotinitialized.

Backward Compatibility of C_InitToken/C_InitPIN

InPKIClientversionsearlierthan4.0.therewerecomplicated recommendationsofhowtoreinitializethetoken.These recommendationsarenowirrelevant.Vendorsarestrongly encouragedtousethenewmechanismdescribedinthisdocument.

44

Special Authentication Features

Single Logon Mode
SafeNetAuthenticationClientsupportstheSingleLogonmode, whereoneapplicationactuallyperformslogin.Belowisthe descriptionofthismechanism: UntiltheapplicationperformsCKU_USERlogin,itcannotaccess privateobjects. Theapplicationmayissueproprietarycalltothefunction ETC_SingleLogonGetPin.IftheSingleLogonmodeisdisabledor ifthepasswordwasnotenteredinthisusersession,thefunction fails. Ifthepasswordisavailable,thefunctionwillreturnwithsome printabledatastring.Theapplicationmaythenusethisstringin theconsequentC_Logincall.Thestringdoesnotcontaintheuser password.ItisjustamarkerenforcingtheSafeNetAuthentication Clienttousethepasswordenteredinanotherapplication. TheSafeNetAuthenticationClientsupportsatimeoutsettingfor SingleLoginmode.Thistimeoutdefineshowlongsincethe passwordwasreallysuppliedtoSafeNetAuthenticationClient,as itmaybeusedbyotherapplications.Afterthetimeoutoccurs,the consequentcallstoETC_SingleLogonGetPinfailaslongasthe passwordisnotsuppliedagainbyanapplicationinthesameuser session.Reachingtimeoutdoesnotaffecttheloginstateofthe applications. TheSingleLogonmechanismfitsuserpasswordonly(notSO).

One-Factor Authentication
TheSafeNetAuthenticationClientallowsatokentobeinitialized withoutrequiringauserpassword.Weusuallyrecommend eliminatingtheuseofthisfeature,asitdecreasesthesecurity dramatically.Still,someorganizationsmaypreferusingtokenas singlefactorauthenticationsolution.

Vendor-Specific Information

45

Iftokenhasbeeninitializedasonefactor,theflag CKF_LOGIN_REQUIREDinthetokeninformationstructurewillnotbe set.TheCKA_PRIVATEattributewillbeeffectivelyignoredandall objectswillbecreatedaspublicobjects.Suchtokendoesnotrequire C_Logincall.However,therearetwocaseswhentheC_Logincallis successful:

C_LoginwithNULLwillsucceed.Itisdonetosimplify

applicationsworkingwithRTEUI. C_Loginwithsomepredefined(undocumented)valuewill succeed.ThisisdonetosupportafuturePasswordManagement application. AnyothercalltoC_Loginwillfail. Theonefactormodeissupportedonlyforhardwaretokens(thatis, wherethereisanotherfactorofauthenticationexceptfortheuserPIN thetokenpresence).

User PIN Unlocking

IfauserforgetsthePIN,theadministrator(SO)logonisrequiredin ordertoresettheuserPINtoaknownvalue.Thismaybeproblemin adistributedenvironment,wheretheadministratorisphysically locatedatadifferentsite.Administratorswillusuallynotrevealtheir passwordtotheuser,sothestandardmechanismofPINunlocking maynotbeusable.TheSafeNetAuthenticationClientsupportsan alternatemechanismbasedonchallengeresponseauthentication: TheapplicationissuesETC_UnlockChallengecallgettingthe cryptographicchallengefromthetoken. Theapplicationpassesthischallengetotheadministratorinany way(networkconnection,email,phone,Webhelpdesksiteandso on)andgetsbackthecryptographicresponse(basedonthe challengeandtheadministratorpassword).Thetokenitselfisnot necessaryforacomputingresponse. TheapplicationissuesETC_UnlockResponsecall,passingboththe cryptographicresponseandthenewpassword.

46

Notes:
Tocheckwhethertheparticulartokensupportschallenge responsemechanismfortheuserPINunlocking,theapplication shouldcheckpresenceofthehardwarefeatureobject ETCKH_SO_UNLOCKThismechanicisavailableforalltokendevices initializedwithadministratorpasswordexceptfortokens initializedasFIPS. Nooperationswiththetokenshouldbeperformedbetween ETC_UnlockChallengeandETC_UnlockResponse calls,otherwise theauthenticationwillfail(whiledecrementingtheSOPINretry counter). TheserverapplicationshouldbeabletoconverttheSOPINinto thecryptographickey.Differenttokensmayusedifferent passwordderivationmechanisms(suchasthosedefinedin PKCS#5andPKCS#12standards).Allcurrenttokenmodelsuse theproprietaryalgorithm.Thedescriptionofthisalgorithmmay bereachedfromAladdinKnowledgeSystemsandisoutofthe scopeofthisdocument.IftheserverapplicationusesSafeNet AuthenticationClient(virtualsession),itmayuse ETCKM_PBA_LEGACY mechanism.

Using SafeNet Authentication Client UI

TheSafeNetAuthenticationClientallowspassingofNULLasPINin C_Login/C_SetPinfunctions.ThiswillenforceSafeNet AuthenticationClienttopopupthewindowforloginorpassword changecorrespondingly.

Miscellaneous Features
CA Certificates
SafeNetAuthenticationClient8.0supportsmanagementofCA certificatesontoken(inadditiontotheregularusercertificates).The CAcertificatesaredistinguishedbytheattribute. CKA_CERTIFICATE_CATEGORY(introducedinthelaterversionsofthe PKCS#11spec).Thisattributevalueshouldbe2forCAcertificate(for usercertificatesitis0).

Reference Usethisattributeintemplatesofobjectsearchorcreation.

47

Private Data Caching

Sincethetokensarerelativelyslowdevices(incomparisontothe desktopoperations),theSafeNetAuthenticationClientusesdata cachingtoimprovetheperformance.Thecachingoftheprivatedata (privateobjects)isconfigurablepertokenbyusingthespecial hardwarefeatureobjectETCKH_PRIVATE_CACHING.Bydefaultthe privatedatacachingisenabled.RSAprivatekeysdonotleavethe hardwaretoken(arenotcached)regardlessofthetokensettings.

Reference
Common Information
Allsystemspecificdefinitions(suchasstructurepackingand pointers)aredoneaccordingtoPKCS#11Hfilesonthesame platform.

Constants
ETCKF_PROPERTY_THREAD

ThisconstantisusedsolelyinflagsofETC_SetProperty function. Theapplicationshouldpassthisflagifthenewlysetpropertyvalue shouldapplyonlytothesubsequentcallsdonefromthesamethread (bydefaultitwillapplytothesubsequentcallsdonefromanythread oftheprocess).

ETCKO_SHADOW_PRIVATE_KEY

ThisclassisusedinsteadofCKO_PRIVATE_KEYwhenlookingfor RSAprivatekeyobjectswithoutbeingloggedon.
ETCKA_OWNER

48 Thisattribute(CK_USER_TYPE)ispartofsomeofthefeatureobjects (ETCKH_PIN_POLICY, ETCKH_PRIVATE_CACHING and ETCKH_2NDAUTH). Itdefineswhoisabletomodifytheobject(assumingthat CKA_MODIFIABLEisTRUE).ItmayhaveeithervalueCKU_USER or CKU_SO.IfCKA_MODIFIABLEisFALSE,thecorrespondingobjectcannot bechangedregardlesstoETCKA_OWNERvalue.Thisattributemaybeset onlyduringobjectcreation(thatis,duringtokeninitializationprocess sinceitrelatestohardwarefeatureobjects).
ETCKA_2NDAUTH_PIN

Thisattributemaybepassedfornewlycreatedkeyswithsecondary authentication(assumesCKA_ALWAYS_AUTHENTICATEtobeTRUE).If notpassed,theSafeNetAuthenticationClientwillpopupthe windowaskingforthepassword.

ETCKA_OTP_DURATION (CK_ULONG)

ThisisvendorspecificattributeoftheOTPkeyobject,definingthe duration(inseconds)oftheOTPvaluerepresentationbythetoken.It makessenseonlyforhardwaretokens.Ifnotpassedduringobject creation,itwillhavethedefaultvaluesetbytheSafeNet AuthenticationClient.DependingofETCKA_OTP_MAY_SET_DURATION mayormaynotbemodifiedlaterbyC_SetAttributeValue function(thechangewillrequireCKU_USERtobeloggedon).

ETCKA_OTP_MAY_SET_DURATION (CK_BBOOL)

ThisisvendorspecificattributeoftheOTPkeyobjectdefineswhether thevalueofETCKA_OTP_DURATIONmaybechangedby C_SetAttributeValue. TheseflagsdefinepossiblePINpolicyissues.Theyarereportedinthe ulDeviceErrorfieldofthestructurereturnedbythe C_GetSessionInfofunction.Thisfunctionshouldbecalledjustafter functionsinvolvingPINpolicy(suchasC_Login,C_SetPINor ETC_TokenIOCTLwithETCK_IOCTL_PIN_EVALUATE).Somemayreturn onlyfromparticularfunctions.Morethanoneflagmaybeset.

ETCKF_PIN_MIN_LEN thenewlysuppliedPINistooshort. ETCKF_PIN_MIX_CHARSthenewlysuppliedPINdoesnotmeet

mixedcharacterscriteria.

Reference

49

ETCKF_PIN_MAX_AGEthecurrentPINshouldbechangedsinceit

isexpired.
ETCKF_PIN_MIN_AGEthecurrentPINcannotbechangedsincethe minimallyrequirednumberofdayssincethelastPINchange didntpassyet. ETCKF_PIN_WARN_PERIODthecurrentPINwillbeexpiredsoon (i.e.itisnotexpiredyet,butwithinthewarningperiod). ETCKF_PIN_HISTORYthenewlysuppliedPINcannotbeaccepted sinceitrepeatsoneofthelastlyusedPINvalues. ETCKF_PIN_MUST_BE_CHANGEDthecurrentPINisenforced(by SO)tobechanged.

Data Types
typedef CK_ULONG ETCK_TRACKER_HANDLE;
typedef ETCK_TRACKER_HANDLE CK_PTR ETCK_TRACKER_HANDLE_PTR;

TheETCK_TRACKER_HANDLErepresentsthetrackerdatatype.The trackeriscreatedbythefunctionETC_CreateTrackerandapointerto itmaybepassedtoC_WaitForSlotEvent.Theadvantageofthe trackeristhatitmaybedestroyed(effectivelycancelingthewait process)bythefunctionETC_DestroyTracker whiletheregular C_WaitForSlotEventmaybecancelledonlybyissuingC_Finalize call.

50

typedef struct tag_ETCK_FUNCTION_LIST_EX { CK_VERSION version; /* Cryptoki extension version */ unsigned short flags; CK_ETC_GetFunctionListEx ETC_GetFunctionListEx; CK_ETC_DeviceIOCTL ETC_DeviceIOCTL; CK_ETC_TokenIOCTL ETC_TokenIOCTL; CK_ETC_CreateTracker ETC_CreateTracker; CK_ETC_DestroyTracker ETC_DestroyTracker; CK_ETC_BeginTransaction ETC_BeginTransaction; CK_ETC_EndTransaction ETC_EndTransaction; CK_ETC_GetProperty ETC_GetProperty; CK_ETC_SetProperty ETC_SetProperty; CK_ETC_CreateVirtualSession ETC_CreateVirtualSession; CK_VOID_PTR pReserved; CK_ETC_SingleLogonGetPin ETC_SingleLogonGetPin; CK_ETC_InitTokenInit ETC_InitTokenInit; CK_ETC_InitTokenFinal ETC_InitTokenFinal; CK_ETC_InitPIN ETC_InitPIN; CK_ETC_UnlockGetChallenge ETC_UnlockGetChallenge; CK_ETC_UnlockComplete ETC_UnlockComplete; } CK_FUNCTION_LIST_EX ; typedef ETCK_FUNCTION_LIST_EX CK_PTR ETCK_FUNCTION_LIST_EX_PTR; typedef ETCK_FUNCTION_LIST_EX_PTR CK_PTR ETCK_FUNCTION_LIST_EX_PTR_PTR;

Thisstructureisusedtoreachaddressesofthevendorspecific PKCS#11Extensionfunctions.Itisreturnedbythefunction ETC_GetFunctionListExfunction.Thestructurecontainsthe followingfields: VersionVersionofthestructure.Futureversionsofthestructure maycontainmorefunctions.Currentlyreturnedversionis1.0. Flagscurrently0,reservedforfutureuse. Allotherfieldsarepointerstothecorrespondingfunctions.

Objects
TheSafeNetAuthenticationClientintroducesseveralhardware featureobjectscoveredinthischapter.

Reference

51

Token Feature Object (ETCKH_TOKEN_OBJECT)

TheETCKH_TOKEN_OBJECTisusedtoobtaindetailedinformationabout tokencapabilities(thatisnotcoveredinstandardinformation returnedbytheC_GetTokenInfofunction)andfordefiningthe settingsofthenewlyinitializedtoken. Attribute
CKA_CLASS CKA_HW_FEATURE_TY PE CKA_LABEL ETCKA_PRODUCT_NAM E ETCKA_MODEL ETCKA_PRODUCTION_ DATE ETCKA_CASE_MODEL ETCKA_CARD_TYPE ETCKA_CARD_VERSIO N ETCKA_RETRY_USER ETCKA_RETRY_SO ETCKA_RETRY_USER_ MAX ETCKA_RETRY_SO_MA X ETCKA_HAS_LCD ETCKA_HAS_SO

Type
CK_OBJECT_CLASS CK_HW_FEATURE_TY PE CK_UTF8CHAR_PTR CK_UTF8CHAR_PTR CK_UTF8CHAR_PTR CK_DATE CK_ULONG CK_ULONG CK_ULONG CK_ULONG CK_ULONG CK_ULONG CK_ULONG CK_BBOOL CK_BBOOL

Meaning
CKO_HW_FEATURE ETCKH_TOKEN_OBJECT Token label Token product name. Token model Token production date Token case model Token card type CK_VERSION Current retry counter for user PIN Current retry counter for SO PIN Maximal retry counter for user PIN Maximal retry counter for SO PIN TRUE if token has LCD (i.e. may be used for off-line OTP computation) TRUE if SO may be logged in for this token (i.e. it has been initialized with SO PIN)

52 Attribute
ETCKA_FIPS ETCKA_FIPS_SUPPORT ED ETCKA_INIT_PIN_REQ ETCKA_RSA_2048 ETCKA_RSA_2048_SUP PORTED ETCKA_HMAC_SHA1 ETCKA_HMAC_SHA1_S UPPORTED ETCKA_MAY_INIT ETCKA_MASS_STORAG E_PRESENT ETCKA_ONE_FACTOR ETCKA_RSA_AREA_SIZ E ETCKA_FORMAT_VERSI ON ETCKA_USER_PIN_AGE

Type
CK_BBOOL CK_BBOOL CK_BBOOL CK_BBOOL CK_BBOOL CK_BBOOL CK_BBOOL CK_BBOOL CK_BBOOL CK_BBOOL CK_ULONG CK_ULONG CK_ULONG

Meaning
TRUE if token is initialized to be FIPScompliant TRUE if token can be initialized as FIPScompliant TRUE if authentication (either user or SO) is needed to re initialize the token. TRUE if token supports 2048-bit RSA keys TRUE if token may be initialized with 2048-bit RSA keys support TRUE if token supports HMAC-SHA1 TRUE if token may be initialized with HMACSHA1 support TRUE if the token may be re initialized with SafeNet Authentication Client TRUE if the token has built-in mass-storage device TRUE if the token is initialized as one-factor authentication device Amount of bytes reserved to store RSA keys Defines the token format version User PIN age (in days), i.e. how long ago the user PIN has been changed.

TheattributeCKA_LABELcontainsthetokenlabel(thesameoneasis returnedbytheC_GetTokenInfofunction)intheformofnull terminatedCK_UTF8CHARstring.Thisistheonlyattributethatcan bechangedbyusingC_SetAttributeValuefunction.Itrequires CKU_USERtobeloggedon. TheattributeETCKA_PRODUCT_NAMErepresentsthetokenproduct name(suchaseTokenNGOTP).

Reference

53

TheattributeETCKA_MODELisaprintablestringrepresentingtheexact tokenmodel(hardware/firmwareversionetc.).Itisusedsolelyfor supportpurposes.Thefollowingconstantsrepresentsupported valuesoftheETCKA_CASE_MODELattributeoftheETCKH_TOKENobject.

ETCK_CASE_NONEthecasemodelisnotrelevant.Thisvaluemay

bereturnedfortheSafeNeteTokenVirtualorfortheetoken smartcard. ETCK_CASE_CLASSIC theclassiccasemodelofeTokenPro. ETCK_CASE_NG1, ETCK_CASE_NG2 eTokenNGOTP ETCK_CASE_NG2_NOLCDeTokenNGFLASH TheattributeETCKA_PRODUCTION_DATEcontainsthedateoftoken production.Itisavailableonlyforparticulartokenmodels.Whenever itisnotavailable,zerobyteswillbereturnedforthisattribute. TheattributeETCKA_CASE_MODELmaybeusedtoassociatethetoken withparticulariconintheapplication(differenttokensmayhave differentviews). TheattributeETCKA_CARD_TYPEencodesthesmartcardtypeusedin theparticulartokenmodel(listedintheConstantssection).The followingconstantsrepresentsupportedvaluesofthe
ETCK_CARD_NONE thetokenhasnosmartcard(itmaybe

ETCKA_CARD_TYPE:

returned,forinstance,forSafeNeteTokenVirtual). ETCK_CARD_OSthetokencontainsSiemensCardOSsmartcard. TheattributeETCKA_RSA_SIZErepresentstheamountofmemory reservedduringtokeninitializationforRSAkeys.Ifthisisirrelevant forcertaintokens(thatis,thestorageshouldnotbespeciallyreserved forRSAkeys),thereturnedvaluemaybeCK_EFFECTIVELY_INFINITE orCK_UNAVAILABLE_INFORMATION. TheattributeETCKA_FORMAT_VERSIONdefinestheversionofthetoken formatinuse.Thevalidvaluesmayvarybetweentokenmodels.The formatversiondefinesbackwardcompatibilityandabilitytosupport suchorotherfeatures. Thefollowingconstantsrepresentsupportedvaluesofthe
ETCKA_FORMAT_VERSIONattributefortokensusingCardOSsmartcard (whenETCKA_CARD_TYPEisequaltoETCK_CARD_OS). ETCK_FORMAT_VERSION_LEGACY theformatversioncompatible

withpriorversionsofeTokenPKIClient.

54
ETCK_FORMAT_VERSION_4_0 theformatversionsupportedsince

eTokenPKIClient4.0.
ETCK_FORMAT_VERSION_5_0forJavaCards.IntroducedinPKI

CLient4.5. Thetokenobjectiscreateduringtokeninitializationprocessand cannotbechangedafterwards(exceptfortheCKA_LABELattribute). Onlyasubsetofattributesmaybepassedduringtokeninitialization.

Reference

55

PIN Policy Feature Object

Attribute
CKA_CLASS CKA_HW_FEATURE_TY PE CKA_MODIFIABLE ETCKA_OWNER ETCKA_PIN_POLICY_TY PE ETCKA_PIN_MIN_LEN ETCKA_PIN_MIN_AGE

Type
CK_OBJECT_CLASS CK_HW_FEATURE_TYP E CK_BBOOL CK_USER_TYPE CK_ULONG CK_ULONG CK_ULONG

Meaning
CKO_HW_FEATURE ETCKH_PIN_POLICY TRUE if the object can be changed The required logon type for changing the object PIN Policy type Minimal PIN length Minimal amount of days after that should pass since PIN change until it will be allowed to change it again by using C_SetPIN function PIN expiration period (in days) PIN change warning period (in days) PIN history size TRUE if no real PIN policy information is stored on the token Maximal retry counter for user PIN Maximum number of characters that can be repeated in sequence. Determines if numbers are permitted, mandatory or forbidden in the PIN

ETCKA_PIN_MAX_AGE ETCKA_PIN_WARN_PE RIOD ETCKA_PIN_HISTORY_ SIZE ETCKA_PIN_PROXY ETCKA_RETRY_USER_ MAX ETCKA_PIN_MAX_REPE ATED ETCKA_PIN_NUMBERS

CK_ULONG CK_ULONG CK_ULONG CK_BBOOL CK_ULONG CK_ULONG CK_ULONG

56 Attribute
ETCKA_PIN_UPPER_CA SE ETCKA_PIN_LOWER_C ASE ETCKA_PIN_SPECIAL

Type
CK_ULONG

Meaning
Determines if uppercase letters are permitted, mandatory or forbidden in the PIN Determines if lowercase letters are permitted, mandatory or forbidden in the PIN Determines if special characters are permitted, mandatory or forbidden in the PIN

CK_ULONG

CK_ULONG

TheETCKH_PIN_POLICY objectisusedtomanagetheuserPINpolicy ofthetoken. TheattributeETCKA_PIN_POLICY_TYPE definesthesupported attributesandbehaviorofthePINpolicy.ItwillallowdifferentPIN policyschemestobesupportedinthefuture.Theonlycurrently supportedvalueisETCKPT_GENERAL_PIN_POLICY.Thisattribute cannotbechangedafterobjectcreation. TheattributeETCKA_PIN_MIX_CHARS(ifsettoTRUE)meansthatfrom thefollowingcategoriesofcharacters(Englishuppercaseletters, Englishlowercaseletters,digits,andalltherest)atleast3shouldbe presentedinthePIN. TheattributeETCKA_PIN_WARN_PERIODisarecommendationforthe applications:howmanydaysbeforerealpasswordexpirationtheuser shouldbewarned. TheattributeETCKA_PIN_HISTORY_SIZE defineshowmanyoldPIN valuesshouldbepreventedfromusingforthenewPIN.Thetoken mayhaveanupperrestrictionforthisattributesinceitisstorage consuming. TheattributeETCKA_PIN_PROXYissettoTRUEifduringtoken initializationthePINpolicyobjecthasnotbeencreated(thatisnoPIN policysettingsarestoredontoken).Inthiscasethetokenwillbehave accordingtothepermachinesettingsoftheSafeNetAuthentication Client.ThePINpolicyhardwarefeatureobjectisstillreturnedtothe applicationtosimplifytheapplicationprogramming.Thisattribute cannotbechangedaftertokeninitialization.

Reference
The attributes ETCKA_PIN_NUMBERS, ETCKA_PIN_UPPER_CASE, ETCKA_PIN_LOWER_CASE and ETCKA_PIN_SPECIAL enable additional options when setting the manual complexity requirements in SafeNet Authentication Client. These attributes supportthefollowingvalues: ETCK_PIN_DONTCARE (0-default)allowsusageofthecharacters

57

determinedbytheattribute
ETCK_PIN_FORBIDDEN (1)prohibitsusageofthecharacters

determinedbytheattribute
ETCK_PIN_ENFORCE (2)forcesusageofthecharactersdeterminedby

theattribute

Challenge-Response Unlocking Capability Feature Object

TheETCKH_SO_UNLOCKobjectrepresentsthechallengeresponse unlockingcapabilityofthetoken(see ETC_UnlockGetChallenge/ETC_UnlockComplete functions).Ifsuch anobjectisnotfound,thetokensPINcannotbeunlockedbyusing challengeresponseeveninpresenceofSOPIN.Itisnotenoughto knowtheSOPINontheserversidetoperformthecryptographic responsecomputation.Theapplicationshouldalsohowtoconvertthe SOPINintothecryptographickey.ItmaybePKCS#5orPKCS#12or anyotherpasswordconversionscheme.ETCKH_SO_UNLOCKdescribes themechanismusedbyparticulartokenanditsparameters. Attribute
CKA_CLASS CKA_HW_FEATURE_TY PE ETCKA_PBA_MECHANI SM ETCKA_PBA_ITERATIO N ETCKA_PBA_SALT

Type
CK_OBJECT_CLASS CK_HW_FEATURE_TYP E CK_MECHANISM_TYPE CK_ULONG Byte array

Meaning
CKO_HW_FEATURE ETCKH_SO_UNLOCK Mechanism of password derivation Iteration counter Salt value

58 TheattributeETCKA_PBA_MECHANISMrepresentsthecryptographic mechanismusedforderivationofthecryptographickeyfromthe password.Alltokenssupportingchallengeresponsearecurrently usingtheproprietarymechanismETCKM_PBA_LEGACY.Noadditional parametersareneededforthismechanism. TheattributesETCKA_PBA_ITERATIONandETCKA_PBA_SALTare reservedforfutureuse.ForPKCS#5andPKCS#12basedpassword derivationtheywouldrepresenttheparametersofmechanismtobe used.ForETCKM_PBA_LEGACY theyhavenosense.

Private Data Caching Feature Object

TheETCKH_PRIVATE_CACHINGobjectdefinestherulesappliedtothe cachingoftheprivatedatacomingfromthetokenbytheSafeNet AuthenticationClient. Attribute
CKA_CLASS CKA_HW_FEATURE_TYP E CKA_MODIFIABLE ETCKA_OWNER ETCKA_CACHE_PRIVATE

Type
CK_OBJECT_CLASS CK_HW_FEATURE_TYPE CK_BBOOL CK_USER_TYPE CK_ULONG

Meaning
CKO_HW_FEATURE ETCKH_PRIVATE_CACHIN G TRUE if the object can be changed The required logon type for changing the object Caching policy

TheETCKA_CACHE_PRIVATEmayhavethefollowingvalues:
ETCK_CACHE_OFF thecachingofprivatedataisdisabled.

Reference

59

ETCK_CACHE_LOGINthecachingofprivatedataisenabledaslong astheuserisloggedon. ETCK_CACHE_ONtheprivatedatacachingisenabled.Thedatawill bekeptinthecache(butnotavailabletoapplication)evenwhen userisnotloggedon.Thisisthedefaultbehavior.

Note:
Regardlessoftheprivatedatacachingmodeforhardwaretokens,the RSAprivatekeysneverleavethetoken.

Secondary Authentication Policy Feature Object

TheETCKH_2AUTHobjectrepresentsthesecondaryauthentication settingsofthetoken. Attribute
CKA_CLASS CKA_HW_FEATURE_TYP E CKA_MODIFIABLE ETCKA_OWNER ETCKA_2NDAUTH_CREA TE

Type
CK_OBJECT_CLASS CK_HW_FEATURE_TYPE CK_BBOOL CK_USER_TYPE CK_ULONG

Meaning
CKO_HW_FEATURE ETCKH_2AUTH TRUE if the object can be changed The required logon type for changing the object Secondary authentication policy

TheattributeETCKA _2NDAUTH_CREATE defineshowRSAprivatekeys arecreated.Itmayhaveoneofthefollowingvalues:

ETCK _2NDAUTH_PROMPT_NEVER(default):thenewlycreatedRSA

privatekeyswillberegularprivateobjects(thatis,theywillnotbe protectedwithanadditionalpassword).The CKA_ALWAYS_AUTHENTICATEattributewillbeignored.

60
ETCK _2NDAUTH_PROMPT_CONDITIONAL - thenewlycreateRSA

privatekeysisprotectedwithsecondaryauthenticationonlyifthe
CKA_ALWAYS_AUTHENTICATEattributehasbeensettoTRUEduring

theobjectcreation.Iftheuserdidntsupplythepassword,the windowwillappear.CancellingtheoperationcreatestheRSA privatekeywithCKA_ALWAYS_AUTHENTICATEequaltoFALSE. ETCK _2NDAUTH_PROMPT_ALWAYSbehavessimilarlytoETCK _2NDAUTH_PROMPT_CONDITIONALexceptthattheUIwillappear regardlessoftheinitialvalueoftheCKA_ALWAYS_AUTHENTICATE attribute. ETCK _2NDAUTH_PROMPTmandatorybehavessimilarlytoETCK _2NDAUTH_PROMPT_ALWAYS,exceptthatthecreationofkeysnot protectedwiththesecondaryauthenticationisprohibited. Cancellingofoperationbytheuserwillfinishtheoperationwith thefailure.

Functions
ETC_GetFunctionListEx
CK_DECLARE_FUNCTION(CK_RV, ETC_GetFunctionListEx) ( ETCK_FUNCTION_LIST_EX_PTR_PTR ppFunctionListEx /* receives pointer to extention functions list */ );

ETC_GetFunctionListEx obtainsapointertothedatastructure containingpointerstoallPKCS#11Extensionsfunctions. ppFunctionListExpointstoavaluewhichwillreceiveapointerto thelibrarysETCK_FUNCTION_LISTstructure,whichinturncontains functionpointersforallthePKCS#11Extensionsroutinesinthe library.Thepointerthusobtainsmaypointsintomemorywhichis ownedbytheSafeNetAuthenticationClient,andwhichmayormay notbewritable.Noattemptshouldbemadetowritetothismemory.

Reference

61

ETC_DeviceIOCTL
CK_DECLARE_FUNCTION(CK_RV, ETC_DeviceIOCTL) ( CK_SLOT_ID slotId, CK_ULONG code, CK_VOID_PTR pInput, CK_ULONG ulInputLength, CK_VOID_PTR pOutput, CK_ULONG_PTR pulOutputLength );

ETC_DeviceIOCTLisusedtoperformvariousslotleveloperationsnot

coveredbythePKCS#11spec.Themaindifferencebetween
ETC_DeviceIOCTLandETC_TokenIOCTListhatETC_DeviceIOCTLis

directedtotheentireslotandinmostofcasesdoesnotevenassumea readytoworktokentobeplugged.
ETC_DeviceIOCTLdirectsthecommandwithfunctioncodetothe slotID.Themeaningoftheinputparameter pInputofulInputLength andtheoutputbufferpOutputofpulOutputLengthdependson

particularoperationtobeperformed.

ETCK_IODEV_SOFTWARE_TOKEN_PLUGIN
ETCK_IODEV_SOFTWARE_TOKEN_PLUGINconnectstheSafeNeteToken

Virtualfiletothefreetokenslot.TheSafeNeteTokenVirtualmaybe connectedonlytothesofttokenslotwhichhasnotokenconnectedto it.ThepInputshouldpointtotheSafeNeteTokenVirtualfilename (UTF8encoded). Notethefollowing: ThecorrespondingfileshouldexistandkeepavalidSafeNet eTokenVirtual.SafeNetAuthenticationClientdoesnotcheckthe filepresenceandcorrectness,butfutureversionsofSafeNet AuthenticationClientmaydothis.Also,variousapplications (suchasSafeNetAuthenticationClient)mayautomatically unplugtheSafeNeteTokenVirtualifthecorrespondingfileis unavailableorcorrupted. Thefileshouldbeachievable(forthesamereasons).Itistherefore notrecommendedtoplugintheSafeNeteTokenVirtuallocated ontheremovablestorage(ornetwork)device. Thefileshouldbeavailableforread/writeaccess;otherwisethe subsequentoperationswiththeSafeNeteTokenVirtualmayfail.

62 Allapplications(includingonewhoissuedtheETC_DeviceIOCTL) willgetnotificationabouttheslotevent(via C_WaitForSlotEvent). Thetokenwillremainedpluggedinaslongasitwillnotbe pluggedoutbysomeapplication.

ETCK_IODEV_SOFTWARE_TOKEN_PLUGOUT
ETCK_IODEV_SOFTWARE_TOKEN_PLUGOUTdisconnectstheSafeNet

eTokenVirtualfromtheslot.Noinput/outputparametersaredefined forthisfunction.TheslotIDistheonlynecessaryinformation.Upon plugout,allapplications(includingtheonethatissuedthe ETC_DeviceIOCTL)willgetnotificationabouttheslotevent(via C_WaitForSlotEvent).Thefunctiondoesnotremovethefile physically,itjustdisconnectsitfromtheslot.

ETCK_IODEV_FULL_NAME
ETCK_IODEV_FULL_NAMEreturnsthefullnameforparticularslot.Itis

usedtoovercomePKCS#11restrictionof64bytesforslotdescription. ThepOutputisbufferwherethenamewillbereturned.Thefunction willreturnthefollowing: Forsmartcardreaderfullreadername. ForsoftwareslotwithconnectedSafeNeteTokenVirtualthe filenameoftheSafeNeteTokenVirtual.

ETCK_IODEV_SOFTWARE_GET_EMULATE
ETCK_IODEV_SOFTWARE_GET_EMULATEcheckswhetherthesoftware

slotisinthesmartcardreaderemulationmode.Onlyoneslot(with SafeNeteTokenvirtualconnected)maybeinsuchmodeinanyperiod oftime.ThepOutputisconsideredasCK_BBOOL_PTR.TRUEorFALSE willbereturned,dependingontheslotstate. ThefollowingconstantsrepresentthecurrentlysupportedslotIOCTL codes.Seedescriptionof ETC_DeviceIOCTLfunctionfordetailsofuse.

Reference

63

ETCK_IODEV_SOFTWARE_SET_EMULATE
ETCK_IODEV_SOFTWARE_SET_EMULATEisusedtoturnthesmartcard readeremulationmodeonorofffortheparticularslot.ThepInputis consideredasCK_BBOOL_PTR,pointingtotheinputparameter.IfTRUE

ispassed,theemulationwillbeturnedon.IfFALSEispassed,the emulationwillbeturnedoff.

ETCK_IODEV_CHECK_NAME
ETCK_IODEV_CHECK_NAMEisusedtocheckwhethertheparticularname isassociatedwiththepassedslotID.ThepInputisconsideredas CK_UTF8CHAR_PTRpointingtothename,andpOutputisCK_BBOOL_PTR

pointingtotheresulttobereturned.Usually,thefunctionwillreturn TRUEifthepassednameisthesameoneasreturnedby ETCK_IODEV_FULL_NAME.Theonlyexceptionisthatsoftwareslotin emulationmodewillalsoreturnTRUEifthenameofassociated smartcardreaderispassed.

ETC_TokenIOCTL
CK_DECLARE_FUNCTION(CK_RV, ETC_TokenIOCTL) ( CK_SESSION_HANDLE hSession, CK_OBJECT_HANDLE hObject, CK_ULONG code, CK_VOID_PTR pInput, CK_ULONG ulInputLength, CK_VOID_PTR pOutput, CK_ULONG_PTR pulOutputLength );

ETC_TokenIOCTLisusedtoperformvariousoperationsthatarenot coveredbythePKCS#11spec.ThehSessionandhObjectdefinethe

sessionandobjectinuseandthecodedefinesparticularoperationto beperformed.ThemeaningoftheinputparameterpInputof ulInputLengthandtheoutputbufferpOutputofpulOutputLength dependsonparticularoperationtobeperformed.

ETCK_IOCTL_PIN_EVALUATE
ETCK_IOCTL_PIN_EVALUATEisusedtocheckwhetherthePINmeets

thePINpolicyrequirements,withoutactuallychangingthePIN.

64 Theparametersare:
hSessionsessionopenedwiththerequestedtoken. hObject isignoredbytheSafeNetAuthenticationClient8.0.Itis recommendedhowevertopassthehandletothePINpolicy hardwarefeaturetoken(forforwardcompatibility). codeETCK_IOCTL_PIN_EVALUATE. pInput, ulInputLengththenewPINvaluetobeevaluated.If NULLispassed,thefunctionwillcheckonlyifthePINchangeis alreadyallowed(accordingtotheminimalPINagesetting). pOutput, pulOutputLengththeoutputparameterisoftype CK_ULONG.ItreturnssomeestimationaboutthepassedPIN (accordingtoPINpolicy)asthenumberbetween0and100.The applicationmayusethisnumberforuserinterfacepurposes.No valueofthisparametershouldbeunderstoodasacceptanceor rejectionofthepassedPINvalue.IfpInputisNULL,pOutput shouldbeNULLtoo.

ThefunctionreturnsCKR_OKifthePINisacceptable,oralternatively, CKR_INVALID_PIN or CKR_PIN_LEN_RANGE(anyothercodeis consideredasanerrorofthefunction).Moreinformationmaybe receivedbysubsequentcalltotheC_GetSessionInfofunction. Notethefollowing: ThefunctionmaynotcheckwhetherthePINisequivalenttoone oftheoldPINvalues.So,evenifthefunctionsucceeded,the subsequentC_SetPINmayfailduetothePINhistory. IftheapplicationintendstouseETC_UnlockCompleteratherthan C_SetPIN,theoperationignorestheminimalpasswordage.In thiscase,eveninthecaseofCKR_INVALID_PINbeingreturned,the applicationshouldcheckthereasonforfailure.IfminimalPIN ageistheonlyfailure,theETC_UnlockComplete willstillsucceed.

ETC_CreateTracker
CK_DECLARE_FUNCTION(CK_RV, ETC_CreateTracker) ( ETCK_TRACKER_HANDLE_PTR pTracker, CK_VOID_PTR param );

Reference

65

ETC_CreateTrackercreatesthetrackerobjectthatmaylaterbeused intheC_WaitForSlotEventfunction.pTrackeristhepointerforthe trackerhandletobereturned,paramisreservedforfutureuseand

mustbeNULL.Thereasontousetrackersisthatthetrackermaybe destroyedlater(effectivelybreakingthewaitandunlockingthe waitingthread)withoutstoppingtheentireapplicationactivitywith C_Finalize.

ETC_DestroyTracker
CK_DECLARE_FUNCTION(CK_RV, ETC_DestroyTracker) ( ETCK_TRACKER_HANDLE hTracker );

ETC_DestroyTracker destroyshTrackerpreviouslycreatedbythe ETC_CreateTrackerfunction.

ETC_BeginTransaction
CK_DECLARE_FUNCTION(CK_RV, ETC_BeginTransaction) ( CK_SESSION_HANDLE hSession );

66
ETC_BeginTransactionlocksthetokenforusingfromotherprocesses orthreadsuntilETC_EndTransactionisperformed.Lockingthetoken ensuresthatnootherapplication(orthread)willworkwiththetoken atthattime.Usingtransactionsforlongseriesofoperationswiththe tokenallowstheapplicationtoensureconsistencyandimprove performance.

Note:
Lockingthetokenmeansonlypreventingotherapplicationsfrom usingit.Thereisnodatabaseliketransaction(Iftheapplication crashesbeforefinishingatransaction,thereisnorollback). Iftheapplicationfinisheswithoutendingthetransaction,itwillbe endedautomatically.However,ifthethreadfinisheswithoutreleasing thetransaction,thebehaviorisunpredictable:thetransactionmaybe endedimmediatelyoronlyafterfinishingtheapplication.So,if anotherthreadofthesameapplicationtriestoaccessthetoken,the deadlockispossible. Thetransactionwithsometokenmayblockeveninnocent operationsworkingwithmultipleslots(suchasC_GetSlotList). Donotkeepopenatransactionlongerthannecessary.Inparticular, donotperformanyuserinteractionduringopenedtransaction.

ETC_EndTransaction
CK_DECLARE_FUNCTION(CK_RV, ETC_EndTransaction) ( CK_SESSION_HANDLE hSession );

ETC_EndTransactionendsthetransactionopenedbythe ETC_BeginTransactioncall.

ETC_GetProperty
CK_DECLARE_FUNCTION(CK_RV, ETC_GetProperty) ( CK_UTF8CHAR_PTR name, CK_VOID_PTR pBuffer, CK_ULONG_PTR pulSize, CK_VOID_PTR pReserved /* NULL */ );

Reference
ETC_GetPropertyreturnsthecurrentsettingofparticularproperty. pReservedisreservedforfutureuseandmustbeNULL.

67

ETC_SetProperty
CK_DECLARE_FUNCTION(CK_RV, ETC_SetProperty) ( CK_UTF8CHAR_PTR name, CK_VOID_PTR pBuffer, CK_ULONG ulSize, CK_ULONG flags, CK_VOID_PTR pReserved /* NULL */ );

ETC_SetPropertymodifiesthepropertysetting.Onlysomeproperties maybesetinthebyapplication.Thechangeaffectsonlycurrent process.TheonlycurrentlydefinedflagisETCKF_PROPERTY_THREAD. Whenpassed,thechangewillaffectonlytheparticularthread; otherwiseitwillaffecttheentireprocess.PassingNULLvaluewill effectivelyresetthepropertyvaluetoitsinitialvalue(thattakenplace onapplicationlaunch). pReservedisreservedforfutureuseandmustbeNULL.

ETC_CreateVirtualSession
CK_DECLARE_FUNCTION(CK_RV, ETC_CreateVirtualSession) ( CK_SESSION_HANDLE_PTR phSession );

ETC_CreateVirtualSessioncreatesthevirtualsession,thatis,the

sessionthatisnotassociatedwithanytoken.Itisusefulforserverside operations,suchas: Cryptographicoperationsbasedonanykeysknowntothe application. OTPverification. Computationresponsefortheusertokenunlocking. TheapplicationmaycallETC_CreateVirtualSessionmanytimes,all createdsessionsareindependent.

68

ETC_SingleLogonGetPin
CK_DECLARE_FUNCTION(CK_RV, ETC_SingleLogonGetPin) ( CK_SESSION_HANDLE hSession, CK_CHAR_PTR pPin, CK_ULONG_PTR ulPinLen );

ETC_SingleLogonGetPinreturnsapseudoPINvaluethatmaybe laterusedinaC_Logincall.IftheSafeNetAuthenticationClientis

currentlynotintheSingleLoginModethefunctionwillfail.Ifthe userPINwasnotenteredyet,thefunctionwillfail. ThedatareturnedbytheETC_SingleLogonGetPinisnotrelatedin anywaytotheuserPINvalue.Itisjustsomedatathatwillbelater understoodbyC_LoginasanattempttoreusePINvalue(ifalready knowntotheSafeNetAuthenticationClientinthecurrentuser session).

ETC_InitTokenInit
CK_DECLARE_FUNCTION(CK_RV, ETC_InitTokenInit) ( CK_SLOT_ID slotID, CK_UTF8CHAR_PTR pPin, CK_ULONG ulPinLen, CK_ULONG ulRetryCounter, CK_UTF8CHAR_PTR pLabel, CK_SESSION_HANDLE_PTR phSession );

ETC_InitTokenInitopenstheinitializationsessionwiththetoken locatedintheslotIdandreturnsinphSessionthehandletothis

session.Theinitializationsessionwilllaterbeusedforcreationof hardwarefeatureobjects.ItisclosedbyETC_InitTokenFinalorby C_CloseSession.TheparameterspPinandulPinLenrepresentthe SOPIN.NULLshouldbepassedifthetokenwillhavenoSOPIN. ulRetryCounteristheretrycounterfortheSOPIN.Ifzeroispassed, theSafeNetAuthenticationClientwillusethedefaultvalue.

Reference

69

ETC_InitTokenFinal
CK_DECLARE_FUNCTION(CK_RV, ETC_InitTokenFinal) ( CK_SESSION_HANDLE hSession );

ETC_InitTokenFinalperformstheactualtokeninitializationand closestheinitializationsessionopenedbyETC_InitTokenInit.

ETC_InitPIN
CK_DECLARE_FUNCTION(CK_RV, ETC_InitPIN) ( CK_SESSION_HANDLE hSession, CK_UTF8CHAR_PTR pPin, CK_ULONG ulPinLen, CK_ULONG ulRetryCounter, CK_BBOOL toBeChanged );

ETC_InitPIN initializestheuserPIN.Itextendsthefunctionalityof thestandardfunctionC_InitPIN.Thefunctionshouldbecalledwhen

SOisloggedinorduringtheinitializationsessionopenedby
ETC_InitTokenInit.

Ifthefunctioniscalledduringtheinitializationsession,
ulRetryCounterdefinestheretrycounterfortheuserpassword.If

zeroispassed,theSafeNetAuthenticationClientwillusethedefault value.Ifthefunctioniscalledaftertokeninitialization,itis recommendedtopasszero(sothattheretrycounterwillnotbe changed),sincenotalltokenmodelsmaybeabletochangeretry counterwithouttokenreinitialization. TheparametertoBeChangedallowstoenforcetheusertochangethe PINuponthefirstlogin.

ETC_UnlockGetChallenge
CK_DECLARE_FUNCTION(CK_RV, ETC_UnlockGetChallenge) ( CK_SESSION_HANDLE hSession, CK_VOID_PTR pChallenge, CK_ULONG_PTR pulChallengeLen );

70

ETC_UnlockChallengereturnsinpChallengebufferthe

cryptographicchallenge.Theapplicationshouldcomputeresponse andcallwithitthefunctionETC_UnlockCompleteinordertounlock theuserPIN.

ETC_UnlockComplete;
CK_DECLARE_FUNCTION(CK_RV, ETC_UnlockComplete) ( CK_SESSION_HANDLE hSession, CK_VOID_PTR pResponse, CK_ULONG ulResponse, CK_UTF8CHAR_PTR pPin, CK_ULONG ulPinLen, CK_ULONG ulRetryCounter, CK_BBOOL toBeChanged );

ETC_UnlockCompletecompletestheprocessofuserPINunlocking. pResponseshouldbethecryptographicresponsecomputedby

applicationforthechallengereturnedfromthefunction
ETC_UnlockChallenge.ThenewlypasseduserPIN(pPin)should

meetthePINPolicysettingsofthetoken.Itisrecommendedthatthe
ulRetryCounterwillbethesameonethatthepasswordhadbeforeor

zero(incaseofzerotheSafeNetAuthenticationClientkeepstheold counter).Othervaluesmaybeormaynotbesupportedbythe particulartoken.TheparametertoBeChangedmaybeusedtoforcethe usertochangethePINuponthefirstlogin.

Mechanisms
ETCKM_PBA_LEGACY
ThisisvendorspecificmechanismofkeyderivationfromthePIN.Itis usedtoconverttheSOPINtotheTripleDESMACkey.ThePINvalue servesastheonlymechanismparameter.Inotherwords,the CK_MECHANISMstructureforkeygenerationfromtheSOPINshouldbe filledasfollowsforthismechanism: mechanismETCKM_PBA_LEGACY.

Reference
pParameterpointertotheSOPIN ulParameterLenlengthoftheSOPIN

71

Properties
TheSafeNetAuthenticationClientSDKprovidesSetandGetproperty functions.ThepropertiesaredefinedbytheSafeNetAuthentication Clientmodule. InversionsearlierthaneTokenPKIClient5.0,somepropertiesdidnot allowtheSetfunction.InSafeNetAuthenticationClient8.0,properties arearrangedaccordingtoahierarchy,andtheSetfunctionisavailable accordingtothelocationofthepropertyinthishierarchy: Policy(Machine)requiresAdministratorpermissions Policy(User)requiresAdministratorpermissions UserrequiresUserpermissions MachinerequiresUserpermissions CurrentUserrequiresUserpermissions TheSetfunctionisenabledforpropertiesthatarelocatedintheareas accessiblewithUserpermissions. Formoreinformation,seetheConfigurationSettingschapterinthe SafeNetAuthenticationClientAdministratorsGuide.

General
Property name
TolerantX509Attributes

Explanation
TolerantX509Attributes determines if the following conditions must be met when creating a certificate: The certificate must be created in the DER encoded X.509 format. The serial number, subject and issuer objects of the internal certificate must match the external attributes. For more information see X.509 Attribute Tolerance on page 21

72

Password Policy
Property name
pqMinLen pqMixChars pqMaxAge pqMinAge pqWarnPeriod

Explanation
Default value for ETCKA_PIN_MIN_LEN attribute (see Password Policies) Default value for ETCKA_PIN_MIX_CHARS attribute (see Password Policies) Default value for ETCKA_PIN_MAX_AGE attribute (see Password Policies) Default value for ETCKA_PIN_MIN_AGE attribute (see Password Policies) Default value for ETCKA_PIN_WARN_PERIOD attribute (see Password Policies) Default value for ETCKA_PIN_HISTORY_SIZE attribute (see Password Policies) Default value for ETCKA_PIN_NUMBERS attribute Default value for ETCKA_PIN_LOWER_CASE attribute Default value for ETCKA_PIN_UPPER_CASE attribute Default value for ETCKA_PIN_SPECIAL attribute Default value for ETCKA_PIN_MAX_REPEATED attribute

pqHistorySize pqNumbers pqLowerCase pqUpperCase pqSpecial pqMaxRepeated

Reference

73

Initialization
Property name
HMAC-SHA1

Explanation
Default value for ETCKA_HMAC_SHA1 attribute (see token initialization). If not set, there is no default value, the logic of SafeNet Authentication Client may vary depending on the token model. Default value for ETCKA_RSA_2048 attribute (see token initialization). If not set, there is no default value, the logic of SafeNet Authentication Client may vary depending on the token model. Default value for ETCKA_FORMAT_VERSION attribute for CardOS-based eToken models (see token initialization). Default value for ETCKA_RSA_AREA_SIZE attribute (see token initialization). If not set, there is no default value, the logic of SafeNet Authentication Client may vary depending on the token model.

RSA-2048

LEGACY-FORMAT-VERSION

RSA-AREA-SIZE

74

Token Model Specifications

FIPS Java Card
No

HMAC*
Built in

2048
Controlled by FW CFG block Yes

One Factor
Yes

RSA Area Size

Not relevant

SafeNet eToken Virtual

No

Yes

No

Set the area size attribute to ZERO to disable RSA use. Applies to formats 0 and 4. Set the area size attribute to ZERO to disable RSA use. Applies to formats 0 and 4. Set the area size attribute to ZERO to disable RSA use. Applies to formats 0 and 4. Set the area size attribute to ZERO to disable RSA use.

eToken Pro/ eToken-NG Card OS 4.20.B

Yes, with format version 5

Yes, through external package

Yes

Yes, with format version 4 and 5 (non FIPS)

eToken Pro/ eToken-NG Card OS 4.20

No

Yes, through external package

Yes, through external package

Yes, with format version 4 and 5

eToken Pro/ eToken-NG Card OS 4.01

Yes, with format version 0 (compatible with RTE 3.65)

No

No

Yes, with format version 4 (non FIPS)

*OTPdependsontheHMACalgorithm.

Chapter 4

SAPI
ThischapterdescribesSAPIasimplementedinSafeNet AuthenticationClient8.0,differencesinbehaviorandbackward compatibilityissues. Introduction Common Description of SAPI Data Types Error Codes SAPI Objects Functions Major Backward Compatibility Issues of SAPI

76

Introduction
SAPI(SupplementaryAPI)wasintroducedinSDK3.60toprovide developerswithaccesstotokenfunctionalitynotcoveredatthatstage byPKCS#11API,suchas: Obtainingextendedinformationabouttheversionand capabilitiesofaparticulartokendevice. Initializingoftokeninamoreflexiblemannerthanprovidedby theC_InitTokenPKCS#11function. SecureunblockingofauserPIN. ManagingtheOTP(onetimepassword)functionalityoftoken devicessupportingOTP. InSafeNetAuthenticationClient8.0,allthisfunctionalityisavailable throughPKCS#11API(includingvendorspecificextensions describedinthisdocument).HoweverSAPIcontinuestobe supportedforreasonsofbackwardcompatibility.However,new functionalitywillbeprovidedonlythroughPKCS#11.Therefore,we recommendusingPKCS#11forfuturedevelopment,whileusingSAPI formaintenancepurposes.

Common Description of SAPI

WhenworkingwithSAPIfunctions: TheapplicationmaycallSAPIfunctionsinoneoftwoways: StaticallylinkinglibeTSapi.sobyusingtheimportlibrary suppliedwiththeSDK. DynamicallyloadinglibeTSapi.sobyusingthe LoadLibraryfunctionandthenlocatingAPIfunctionsby usingGetProcAddress. TheapplicationshouldcallthePKCS#11C_Initializefunction priortoanyusageofSAPIfunctions. TheapplicationshouldnotcalltheC_Finalizefunctionaslongas itcontinuestouseSAPIfunctions. ThissectioncontainsabriefdescriptionoftheproposedSAPI functions. Foreachfunction,thefollowingapplies:

Common Description of SAPI FunctionreturnsCK_RVasthereturnvalueasinallPKCS#11 functions.Severalvendorspecificreturncodesaredefinedby SAPI.

77

Note:
Errorcodesreturnedbythesamefunctionmayvarybetween versionsofPKIClient. Ifthefunctionoperateswithaparticularslot,itgetseitheraslot IDorsessionhandleasaparameter.Asessionhandleisusedifit isexpectedthatthetokenmustbeproperlyinitializedbeforethe functioncall. WheneverpossibledatatypesandstructuresdefinedinPKCS#11 areused.SAPIdefinesseveralmoredatatypes. ParametertemplatemeansCK_ATTRIBUTE_PTRwhichpointstothe attributesarrayandCK_ULONGcontainingthearraysize.The handlingofthisparameterissimilartootherPKCS#11functions. AlthoughSAPIdescribesnewobjectclasses,thisAPIdoesnot reallyusePKCS#11objectrelatedfunctions(suchas C_FindObjects).Theseobjectclassesareusedonlytogroupthe relevantattributes,whileseparateAPIfunctionsareusedto operatewitheachfeature. TheAPIisdefinedintheeTSAPI.hheaderfile.

OTP Functionality
Sometokendevices,suchaseTokenNGOTPandSafeNeteToken Virtual,supportonetimepassword(OTP)functionality.OTPcapable tokensshouldbeinitializedwithsomeOTPsecret.Theusermaythen generateanewOTPvaluebypressingthebuttonwithouteven connectingthetokentothecomputerandusethetokeninvarious passwordprotectionschemes(certainly,properbackendsupportis needed). Generallyspeakingthetokenmaybeabletosupportinthefuture multipleOTPsecretsandsupportmultipleOTPalgorithms.ButSAPI supportsaddressingofonlyoneOTPsecretpertokenissupported,it isreferencedindirectlybyallOTPfunctions. Similarly,currentlyonlyoneOTPalgorithmissupported.Thisisan HMACSHA1basedHOTPalgorithm.

78 Formoreinformation,referto: http://tools.ietf.org/html/draftmraihioathhmacotp04 ThetokenshouldbeinitializedwithHMACSHA1supporttouse HOTPfunctionality. The application may use:

SAPI_OTP_GetMechanismListandSAPI_OTP_GetMechanismInfo toexaminethetokensOTPcapabilities. SAPI_OTP_CreatetocreateinstancesoftheOTPobject. SAPI_OTP_Destroytodeleteit(theOTPobject). SAPI_OTP_GetAttributeValuetoexamineattributesofthe existingOTPobject. SAPI_OTP_SetAttributeValuetochangethepresentation durationoftheOTPobjectonthetoken. SAPI_OTP_ExecutetoperformOTPcalculationsonthetoken. SAPI_Server_OTP_CalculatetoperformOTPcalculations withoutthetoken,passingtheOTPsecretasaparameter.This functionisusedbytheserverapplicationtovalidateuser authentication.

Miscellaneous Functionality
SupplementaryAPIprovidesapplicationdeveloperswithadditional functionalitythatmaybeusableforsomeapplications. The application may use:
SAPI_GetLibraryInfo toobtaininformationaboutthelibrary

version.
SAPI_GetSlotInfotoobtaininformationabouttheparticularslot. SAPI_GetTokenInfo toobtainfullinformationaboutthetoken

model,versionandcapability.Thefunctionreturnstherequired informationinthetemplateofattributesthatdescribestoken object. SAPI_InitToken toinitializethetoken.Thefunctiongetsthe initializationparametersinthetemplateofattributesthatdescribe tokenobject(manyoftheseattributesarecommonwiththe SAPI_GetTokenInfofunction).

Data Types

79

SAPI_FindTokensorSAPI_LocateTokentofindtheneededtoken

betweenalltokenscurrentlyinsertedinthecomputer. SAPI_UnblockPIN,SAPI_UnblockPINExand SAPI_Server_UnblocktounblocktheuserPINremotely.Unlike theC_InitPINfunctionofPKCS#11,itallowsunblockingofthe userPINwithouttheSecurityOfficerPIN(SOPIN)beingknown bytheclientapplicationbyusingachallengeresponse mechanism.ThefunctionSAPI_UnblockPINisrunontheclient machine(wherethetokenisinserted),whilethefunction SAPI_Server_Unblockcooperatesontheserverside,computing thepropercryptographicresponse. SAPI_LoginandSAPI_SetPINallowapplicationstouseUIand passwordpolicymechanismsoftheSafeNetAuthentication Client(somethingthatcomesautomaticallysincePKIClient4.0, butnotinpreviousversions).

Data Types
SAPIusesdatatypesasdefinedinPKCS#11andinadditiondefines severalmore.Thesearedescribedhere:

CK_INIT_CALLBACK
typedef CK_CALLBACK_FUNCTION (CK_RV, CK_INIT_CALLBACK) (CK_VOID_PTR pContext, CK_ULONG progress);

ThiscallbackfunctionisusedwiththeSAPI_InitTokenfunctiontolet theapplicationshowitsprogressaspercentages. The parameters are:

pContextthecontextthathasbeenpassedtoSAPI_InitToken progresstheformattingprogressinpercentage.

ThisfunctionshouldreturnCKR_OKtocontinuetheinitializationor anyotherreturnvaluetostopit.

80

CK_UNBLOCK_CALLBACK
typedef CK_CALLBACK_FUNCTION (CK_RV, CK_UNBLOCK_CALLBACK) (CK_SESSION_HANDLE hSession, CK_VOID_PTR pChallenge, CK_VOID_PTR pResponse);

ThiscallbackfunctionisfortheSAPI_UnblockPINfunctionandis usedtocompletethechallengeresponsecalculation. The parameters are:

hSessionthesessionhandlethathasbeenpassedtothe

SAPI_UnblockPINfunction pChallengethecryptographicchallengeascreatedbythetoken pResponsetheresponsetothechallenge

CK_UNBLOCK_CALLBACK_EX
typedef CK_CALLBACK_FUNCTION (CK_RV, CK_UNBLOCK_CALLBACK_EX) (CK_VOID_PTR pContext, CK_VOID_PTR pChallenge, CK_VOID_PTR pResponse);

ThiscallbackfunctionisfortheSAPI_UnblockPINExfunctionandis usedtocompletethechallengeresponsecalculation. The parameters are:

pContextapplicationcontextthathasbeenpassedtothe

SAPI_UnblockPINfunction pChallengethecryptographicchallengeascreatedbythetoken pResponsetheresponsetothechallenge

Data Types

81

SAPI_PIN_POLICY_INFO
typedef struct tagSAPI_PIN_POLICY_INFO { CK_RV warning; CK_ULONG days; CK_ULONG warningPeriod; CK_ULONG expiryPeriod; }SAPI_PIN_POLICY_INFO;

ThisstructureisusedinfunctionSAPI_Logintoreturnthe informationaboutneedtochangepassword.

CK_SAPI_OTP_MECHANISM_INFO
typedef struct tagCK_SAPI_OTP_MECHANISM_INFO { CK_ULONG mechanism;// CK_SAPI_OTP_HMAC_SHA1_DEC6 CK_ULONG minKeyLen; CK_ULONG maxKeyLen; CK_ULONG OTPLen;// 6 CK_ULONG defDuration; CK_ULONG flags; }CK_SAPI_OTP_MECHANISM_INFO, *CK_SAPI_OTP_MECHANISM_INFO_PTR;

ThisstructuredescribesinformationabouttheOTPmechanismas returnedfromthefunctionSAPI_OTP_GetMechanismInfo. The fields of the structure are:

mechanismOTPmechanism(onlythe CK_SAPI_OTP_HMAC_SHA1_DEC6mechanismiscurrently

supported) minKeyLentheminimumkeylengthoftheOTPsecret maxKeyLenthemaximumkeylengthoftheOTPsecret OTPLenthesizeoftheproducedOTPvalue(excludingthefinal zerocharacter) defDurationthedurationoftheOTPpresentationinseconds flagsthiscanbeacombinationofoneormoreflagsthat describethemechanismscapabilities.Theycanbe:

82
CK_SAPI_OTP_CURRENT_SUPPORTEDthetokensupports retrievingthecurrentOTPvalue.See SAPI_OTP_Executeonpage109. CK_SAPI_OTP_ZERO_SUPPORTEDthetokensupports retrievingthezeroOTPvalue.SeeSAPI_OTP_Execute onpage109. CK_SAPI_OTP_CUSTOM_DURATIONthetokensupports customizationoftheOTPdisplayduration. CK_SAPI_OTP_CTL_DURATIONtheabilitytochangethe OTPdisplaydurationcanberestrictedatthetimeof OTPobjectcreation. CK_SAPI_OTP_BUTTON SUPPORTEDtokensupportsthe useofanOTPbuttonwhenthetokenisconnectedto thecomputer. Theseflagsarekeptforbackwardcompatibility.InSafeNet AuthenticationClient8.0alltheseflagsareset.

Error Codes
Usually,SAPIfunctionsreturnthestandardPKCS#11errorcodes.The followingtableshowssomeofthemorecommonerrorcodeslikelyto bereturned.Inadditiontothese,refertothePKCS#11documentation foracompletelistoftheerrorcodes: http://www.rsasecurity.com/rsalabs/node.asp?id=2133 General PKCS#11 Error Codes Name
CKR_TEMPLATE_INCO MPLETE CKR_TEMPLATE_INCON SISTENT

Description
A mandatory attribute is not passed. Certain passed attributes make no sense together.

Error Codes Name

CKR_ARGUMENTS_BAD CKR_USER_NOT_LOGG ED_IN CKR_DEVICE_ERROR

83

Description
The required operation cannot be performed with the passed parameters The user is required to be logged in. An object is damaged.

84 eTSAPIfunctionalityallowsforcertainactionsthatarenotcoveredby PKCS#11errorcodesandfortheseactionsSAPIspecificcodesare required.Theinstancesofthisarelimited.Thefollowingtableshows SAPIspecificerrorcodes. SAPI Specific Error Codes Name

CKR_SAPI_OBJECT_DOE S_NOT_EXIST CKR_SAPI_OBJECT_ALR EADY_EXISTS CKR_SAPI_NOT_SUPPO RTED_BY_TOKEN CKR_SAPI_PIN_QUALITY CKR_SAPI_PIN_DEFAULT

Description
The object asked about in the operation does not exist. An object already exists. This may be returned from functions like SAPI_BI_Create and SAPI_OTP_Create The token does not support the requested feature. The newly supplied PIN does not meet requirements of password policy The default PIN must be changed. This error code will never return in SafeNet Authentication Client 8.0 (due to changes in the password policy mechanisms). The PIN is expired. The PIN change is currently not allowed The UI operation is cancelled by user.

CKR_SAPI_PIN_EXPIRAT ION CKR_SAPI_PIN_CHANGE _NOT_ALLOWED CKR_SAPI_CANCELLED

Note:
Thespecificerrorcodesreturnedbyfunctionsinthecaseofsuchor otherfailuremaysometimesvarybetweenPKIClientversions. DuetohistoricalreasonsSAPIintroducesseveralerrorcodes similartoerrorcodesintroducedinlaterversionsofPKCS#11.

SAPI Objects

85

SAPI Objects
Asmentionedpreviously,SAPIdoesnothaveconceptofobjectsasit isintroducedbyPKCS#11.YoucannotoperatewithSAPIobjectsby usingPKCS#11functions.However,similartoPKCS#11,SAPIuses templatesofattributestoidentifytheentitiesitworkswith.Theyare calledobjectsaslongaswespeakaboutSAPI.

Slot Object
Theslotobjectisusedtorepresentthetokencharacteristicsthatare notavailableviatheC_GetSlotInfo function.

CKA_SAPI_SLOT_NAME (CK_UTF8CHAR_PTR)
Thisattributeisanullterminatedstring.ForPC/SCreadersitcontains thefullreadernamewhileforSafeNeteTokenVirtualcontainsthefile name(emptystringisreturnedifnofileisassociatedwiththeSafeNet eTokenvirtualslot).SeeETCK_IODEV_FULL_NAMEonpage62.

CKA_SAPI_SLOT_TYPE (CK_ULONG)
Thisattributecontainsaconstantthatdefinestheslottypethereby distinguishingvirtualslotsfromrealslotsandtokensfrom smartcards. These are the possible values:
CK_SAPI_SLOT_SC_READERPKCS#11slotcorrespondstothereal

smartcardreader(Forexample,Athenareader).
CK_SAPI_SLOT_SC_VIRTUALPKCS#11slotcorrespondstotheSafeNet

eTokenVirtualreader(namedordinalyAKSifdh0,..1,..2andso on).
CK_SAPI_SLOT_FILEPKCS#11slotcorrespondstothesoftware

token(thatis,thebinaryfile).

86

Token Object
This object is used to: Representtokencharacteristicsnotavailableviathe C_GetTokenInfofunction. Learnwhetherthetokenhassomespecialcapabilities(likeOTP). Performtokeninitialization.

Note:
Sometokenattributesmaynotbeallowedduringinitialization,while othersareallowedonlyduringinitialization. InSafeNetAuthenticationClient8.0mostofthisinformationis representedviathespecialhardwarefeatureobject ETCKH_TOKEN_OBJECT.

CKA_SAPI_CARD_ID (CK_BYTE_PTR)
ThisisthesmartcardsuniqueID.Itisuniqueforcardsfroma particularOSvendor(inconjunctionwithCKA_SAPI_CARD_TYPE). Cardlesstokens(forexample,SafeNeteTokenVirtual)returnan emptybytearrayasthesmartcardID. Thisisareadonlyattribute. SeealsoETCKA_CARD_ID,intheTokenFeatureObject (ETCKH_TOKEN_OBJECT)tableonpage51.

CKA_SAPI_CARD_TYPE (CK_ULONG)
Thisdistinguishescardsfromdifferentvendorswith CK_SAPI_CARD_NONE meaningNoSmartcardandCK_SAPI_CARD_OS meaningSiemensCardOS. Thisisareadonlyattribute. SeealsoETCKA_CARD_TYPEintheTokenFeatureObject (ETCKH_TOKEN_OBJECT)tableonpage51.

SAPI Objects

87

CKA_SAPI_CARD_VERSION (CK_VERSION)
ThisistheOSversionofthesmartcard. Thisisareadonlyattribute SeealsoETCKA_CARD_VERSIONintheTokenFeatureObject (ETCKH_TOKEN_OBJECT)tableonpage51.

CKA_SAPI_CASE_MODEL (CK_ULONG)
Thisreferstoconstantsthatstatehowthecasinglooks:
CK_SAPI_CASE_NONE CK_SAPI_CASE_CLASSIC CK_SAPI_CASE_NG1 CK_SAPI_CASE_NG2 ETCK_CASE_NG2_NOLCD Smartcard or SafeNet eToken Virtual Classic shape (eToken PRO) "NG1" shape (eToken NG-OTP) "NG2" shape (eToken NG-OTP) "NG2" shape (eToken NG Flash)

Thisisareadonlyattribute. SeealsoETCKA_CASE_MODELintheTokenFeatureObject (ETCKH_TOKEN_OBJECT)tableonpage51.

CKA_SAPI_COLOR (CK_ULONG)
Thisprovidesinformationonthetokencolorwhereithasbeenburnt inoronasmartcard.SeealsoETCKA_COLORin ETCKH_TOKEN_OBJECT.Fortokensthatkeepnoinformationabout tokencolorPKIClient4.0setsthisattributetoUnknown (0xFFFFFFFF).

CKA_SAPI_FIPS (CK_BBOOL)
WhenusedintheSAPI_GetTokenInfofunction,thisattributestates whetherthetokeniscurrentlyinitializedasFIPScompliantornot. WhenpassedtotheSAPI_InitTokenfunction,thisattributedefines whetherthetokenshouldbeinitializedasFIPScompliantornot.

88 SeealsoETCKA_FIPSintheTokenFeatureObject (ETCKH_TOKEN_OBJECT)tableonpage51.

CKA_SAPI_FIPS_SUPPORTED (CK_BBOOL)
ThisattributestateswhetherthetokencanbeinitializedasaFIPS token. Thisisareadonlyattribute. SeealsoETCKA_FIPS_SUPPORTEDintheTokenFeatureObject (ETCKH_TOKEN_OBJECT)tableonpage51.

CKA_SAPI_HAS_LCD (CK_BBOOL)
ThisindicateswhetherornotthetokenhasanLCDdisplaybymeans ofatrueorfalseanswer. Thisisareadonlyattribute. SeealsoETCKA_HAS_LCDintheTokenFeatureObject (ETCKH_TOKEN_OBJECT)tableonpage51.

CKA_SAPI_HAS_SO (CK_BBOOL)
ThisindicateswhetherornotthetokenhasaSecurityOfficerby meansofatrueorfalseanswer. Thisisareadonlyattribute. SeealsoETCKA_HAS_SOintheTokenFeatureObject (ETCKH_TOKEN_OBJECT)tableonpage51.

CKA_SAPI_HAS_USER (CK_BBOOL)
Thisattributesdetermineswhetherthetokenisinitializedorempty. Thisisareadonlyattribute. SafeNetAuthenticationClient8.0returnsthisinformationalsovia flagCKF_USER_PIN_INITIALIZEDintheCK_TOKEN_INFOstructure.

SAPI Objects

89

CKA_SAPI_HMAC_SHA1 (CK_BBOOL)
Whenusedinthe SAPI_GetTokenInfofunction,thisattributestates whetherthetokencurrentlysupportstheHMACSHA1algorithmor not.WhenpassedtotheSAPI_InitTokenfunction,thisattribute defineswhetheryouneedthetokentosupporttheHMACSHA1 algorithm. SeealsoETCKA_HMAC_SHA1intheTokenFeatureObject (ETCKH_TOKEN_OBJECT)tableonpage51.

CKA_SAPI_HMAC_SHA1_SUPPORTED (CK_BBOOL)
ThisattributestateswhetherthetokencanbeinitializedwithHMAC SHA1algorithmsupport. Thisisareadonlyattribute. SeealsoETCKA_HMAC_SHA1_SUPPORTEDintheTokenFeature Object(ETCKH_TOKEN_OBJECT)tableonpage51.

CKA_SAPI_INIT_PIN_REQ CK_BBOOL)
ThisattributestateswhethertheCKA_SAPI_PIN_CURRENTattributeis requiredfortokeninitialization. Thisisareadonlyattribute.

CKA_SAPI_MAY_INIT(CK_BBOOL)
Thisattributestateswhetherornotitispossibletoinitializethetoken viaSAPI_InitToken. Thisisareadonlyattribute.

CKA_SAPI_MODEL (CK_CHAR_PTR0)
Thisproducesacharacterstringdescribingtheproductandincludes informationonthehardwareversion.Thisinformationmaybe displayedbyanapplicationtogetatokendescription.This descriptionisnotinformativeforuserapplications,butmaybe helpfulforsupportreasonsincludingtroubleshooting.

90 ThecontentofthisattributemaychangeasaresultofatokenFW upgrade. Thisisareadonlyattribute. SeealsoETCKA_MODELintheTokenFeatureObject (ETCKH_TOKEN_OBJECT)tableonpage51.

CKA_SAPI_NEW_KEY (CK_BYTE_PTR)
Thisattributedefinesthesecretkeythatwillbesetonthetokenfor furtherinitialization.Absenceofthisattributemeansthatthedefault keywillbeused.Thisattributemaybeusedonlywhencalling SAPI_InitToken.

CKA_SAPI_OLD_KEY (CK_BYTE_PTR)
Thisattributedefinesthesecretkeyusedfortokeninitialization. Absenceofthisattributemeansthatthedefaultkeywillbeused.This attributemaybeusedonlywhencallingSAPI_InitToken.

CKA_SAPI_PIN_CURRENT (CK_CHAR_PTR)
ThisisthecurrentpasswordoftheuserorSO.Thisissuppliedonlyif thetokenisreinitializedafterhavingbeeninitializedinFIPSmode. ThisattributemaybeusedonlywhencallingSAPI_InitToken.

CKA_SAPI_PIN_SO (CK_CHAR_PTR)
Thisisusedonlyfortokeninitializationandtheadministrator passwordisprovidedtothetoken.Ifnopasswordissupplied,the tokenwillnothaveanadministrator.Thisattributemaybeusedonly whencallingSAPI_InitToken.

CKA_SAPI_PIN_USER (CK_CHAR_PTR0
Thisisusedonlyfortokeninitializationandtheuserpasswordis providedtothetoken.Ifnopasswordissupplied,thetokenis initializedasempty.Thisattributemaybeusedonlywhencalling SAPI_InitToken.

SAPI Objects

91

CKA_SAPI_PRODUCT_NAME (CK_CHAR_PTR)
ThisisaproductnamelikeeTokenPROoreTokenNGOTPand containsthetokentypeencodedasastring. Thisisareadonlyattribute. SeealsoETCKA_PRODUCT_NAMEintheTokenFeatureObject (ETCKH_TOKEN_OBJECT)tableonpage51.

CKA_SAPI_PRODUCTION_DATE (CK_DATE)
Thisisthedateonwhichthetokenwasproduced.Thisattributemay bezeroedfortokensthatdonotstoretheproductiondate.Ifthis informationisnotavailable,thesizeofthereturnedattributewillbe0 bytes Thisisareadonlyattribute. SeealsoETCKA_PRODUCTION_DATEintheTokenFeatureObject (ETCKH_TOKEN_OBJECT)tableonpage51.

CKA_SAPI_REAL_COLOR(CK_BBOOL)
Thisindicateswhetherthecolorinformationreturnedbythe CKA_SAPI_COLORattributeisburnedontothetokenduring production.IfthisattributeisFALSE,theSafeNetAuthentication Client8.0willreturnUnknown(0xFFFFFFFF)asthecolorvalue (earlierversionscouldreturnanarbitraryvalue). Thisisareadonlyattribute. SeealsoETCKA_REAL_COLORintheTokenFeatureObject (ETCKH_TOKEN_OBJECT)tableonpage51.

CKA_SAPI_RETRY_SO (CK_ULONG)
Thisisthecurrentnumberoffailedlogattemptsremainingbeforethe SecurityOfficer(SO)PINislocked.Itshouldbenotedthatwhenlog inissuccessful,thecounterautomaticallyrevertstothemaximumfor futureattempts. Thisisareadonlyattribute.

92 SeealsoETCKA_RETRY_SOintheTokenFeatureObject (ETCKH_TOKEN_OBJECT)tableonpage51.

CKA_SAPI_RETRY_SO_MAX (CK_ULONG)
Thisattributedefinesthemaximumnumberoflogonattemptsauser canmakewithincorrectpasswordsbeforetheSOPINislocked.When initializingthetoken,thisattributeappliesonlyifaSOPIN (CKA_SAPI_SO_PIN)isalsosupplied. SeealsoETCKA_RETRY_SO_MAXintheTokenFeatureObject (ETCKH_TOKEN_OBJECT)tableonpage51.

CKA_SAPI_RETRY_USER (CK_ULONG)
Thisisthecurrentnumberoffailedlogonattemptsremainingbefore theuserPINislocked.Whenthelogonissuccessful,thecounter automaticallyrevertstothemaximumforfutureattempts. Thisisareadonlyattribute. SeealsoETCKA_RETRY_USERintheTokenFeatureObject (ETCKH_TOKEN_OBJECT)tableonpage51.

CKA_SAPI_RETRY_USER_MAX (CK_ULONG)
Thisattributedefinesthemaximumnumberofloginattemptsauser canmakewithincorrectpasswordsbeforetheuserPINhasbeen locked.Wheninitializingthetoken,thisattributeappliesonlyifauser PIN(CKA_SAPI_USER_PIN)isalsosupplied. SeealsoETCKA_RETRY_USER_MAXintheTokenFeatureObject (ETCKH_TOKEN_OBJECT)tableonpage51.

CKA_SAPI_RSA_KEYS (CK_ULONG)
ThisattributeisusedonlyintheSAPI_InitTokenfunctiontodefine theamountofspacereservedforRSAkeysduringtokeninitialization. Itisdefinedintermsofthenumberof1024bitRSAkeysthatmaybe created.Ifthisparameterisomitted,thedefaultvaluewillbeused.If0 ispassed,noplacewillbeallocatedforRSAkeys.

SAPI Objects SeealsoETCKA_RSA_AREA_SIZEintheTokenFeatureObject (ETCKH_TOKEN_OBJECT)tableonpage51.

93

CKA_SAPI_RSA_2048 (CK_BBOOL)
WhenusedintheSAPI_GetTokenInfofunction,thisattributestates whetherthetokencurrentlysupportsRSA2048keysornot.When passedtotheSAPI_InitTokenfunction,thisattributedefineswhether youneedthetokentosupportRSA2048keys. SeealsoETCKA_RSA_2048intheTokenFeatureObject (ETCKH_TOKEN_OBJECT)tableonpage51.

CKA_SAPI_RSA_2048_SUPPORTED (CK_BBOOL)
ThisattributestateswhetherthetokencanbeinitializedwithRSA 2048keysupport. Thisisareadonlyattribute. SeealsoETCKA_RSA_2048_SUPPORTEDintheTokenFeatureObject (ETCKH_TOKEN_OBJECT)tableonpage51.

CKA_SAPI_SERIAL (CK_CHAR_PTR)
Thisisauniquetokenidentifier.Thisfieldshouldbeusedby applicationstorefertotheparticulartoken.Itisguaranteedtobe uniqueandcompatiblewiththecorrespondingfieldinthe CK_TOKEN_INFOstructureinPKCS#11. Thisisareadonlyattribute.

CKA_SAPI_TOKEN_ID (CK_BYTE_PTR)
ThisisauniqueIDforeachUSBtoken.Thetokensthathaveno meaningfultokenID(suchassmartcards)returnanemptybytearray asthetokenID. Thisisareadonlyattribute. SeealsoETCKA_TOKEN_IDintheTokenFeatureObject (ETCKH_TOKEN_OBJECT)tableonpage51.

94

CKA_SAPI_USER_PIN_INITIALIZED (CK_BBOOL)
ThisattributedefinestheuserPINasbeinginitialized.Thedefault valueforthisattributeisTRUE.Thisattributemaybeusedonlywhen callingSAPI_InitToken.

OTP Object
TheOTPobjectrepresentstheOTPsecretandcorrespondingdata (suchascounter),storedandoperatedbythetoken.Generally speaking,thetokenmaysupportmultipleOTPalgorithmsaswellas multipleobjectsimplementingthesameOTPalgorithm.Onlyone OTPobjectpertokeniscurrentlysupportedbySAPI.

Attributes
Whenthetokenisinitialized,theseattributescontrolhowthetoken willbehave.Whentheattributesaresimplybeingread,theyinform theapplicationabouthowthetokenbehaves.Theseattributescannot bechanged.

CKA_SAPI_OTP_COUNTER (CK_ULONG)
Thisdeterminesthecurrentvalueofthemovingfactor.Ifnotsupplied tothefunctionSAPI_OTP_Create,0willbeusedasthedefaultvalue. Thisattributemaynotbechangedbyanapplicationaftercreation. SeealsoCKA_OTP_COUNTERonpage33.

CKA_SAPI_OTP_CURRENT_ALLOWED (CK_BBOOL)
ThisattributedefineswhetherthelastOTPvaluemaybereceivedby usingtheSAPI_OTP_Executefunction.ThisattributeisTRUEforall currentlysupportedtokens.SafeNetAuthenticationClient8.0always returnsTRUEforthisattribute. Thisisareadonlyattribute.

SAPI Objects

95

CKA_SAPI_OTP_CUSTOM_DURATION_ALLOWED (CK_BBOOL)
Thisindicateswhether,aftertheobjectwascreated,thedurationcan bechanged. SeealsoETCKA_OTP_MAY_SET_DURATIONinPKCS#11 CKO_OTPobjectonpage48.

CKA_SAPI_OTP_DURATION (CK_ULONG)
Thisdeterminesforhowlong(inseconds)theOTPvalueappearson thetokenwhenthebuttonispressed. SeealsoETCKA_OTP_DURATIONinPKCS#11CKO_OTPobjecton page32.

CKA_SAPI_OTP_MECHANISM (CK_MECHANISM_TYPE)
ThisidentifiestheparticularOTPmechanism.

CKA_SAPI_OTP_VALUE (CK_BYTE_PTR)
ThisattributecontainsthevalueoftheOTPsecretthatshouldbe passedtotheSAPI_OTP_Createfunction.Thisisasensitiveattribute inPKCS#11terms. The OTP secret value range is different for Java Card & CardOS OTP devices: JavaCardOTPMinKeySize=20 JavaCardOTPMaxKeySize=24 CardOSOTPMinKeySize=20 CardOSOTPMaxKeySize=32

CKA_SAPI_OTP_ZERO_ALLOWED (CK_BBOOL)
ThisattributedefineswhethertheOTPcomputationbasedonazero counterisallowed.InSafeNetAuthenticationClient8.0itshouldbe passedasTRUE. RefertotheSAPI_OTP_Executefunctiononpage109formore information.

96

Functions
Note:
InthissectionthetermobjectmeansSAPIpseudoobjects,unless specifieddifferently.

Common Functionality
SAPI_GetLibraryInfo
Thisfunctionreturnsversioninformationaboutthecurrentlyinstalled SAPIandunderlyingSafeNetAuthenticationClient.
CK_RV SAPI_GetLibraryInfo ( CK_VERSION_PTR pSapiVersion, CK_VERSION_PTR pRteVersion

); Parameters pSapiVersion [out]PointertothestructurethatreceivesthecurrentSAPIAPI versionnumber.SafeNetAuthenticationClient8.0returns1.2inthis field. pRTEVersion [out]PointertothestructurethatreceivesthecurrentlyinstalledPKI Clientversionnumber.TheSafeNetAuthenticationClientreturns8.0 inthisfield.

Functions

97

Slot/Token Functionality
SAPI_GetSlotInfo
Thisfunctionreturnsinformationaboutaparticularslot.Thetemplate mayincludeanyattributesdefinedfortheslotobject.
CK_RV SAPI_GetSlotInfo ( CK_SLOT_ID slotId, CK_ATTRIBUTE_PTR pTemplate, CK_ULONG ulCount

);

Parameters
slotId [in]Slotidentifierforwhichinformationisrequested. pTemplate [in/out]Pointertotheattributesarraythatreceivestherequested information. ulCount [in]CountofattributesinthepTemplatearray.

SAPI_GetTokenInfo
Thisfunctionreturnsinformationaboutaparticulartoken.The templatemaycontainanyattributesdefinedforthetokenobject.
CK_RV SAPI_GetTokenInfo ( CK_SLOT_ID slotId, CK_ATTRIBUTE_PTR pTemplate, CK_ULONG ulCount

);

Parameters
slotId [in]identifieroftheslotwherethetokenislocated pTemplate

98 [in/out]Pointertotheattributesarraythatreceivestherequested information. ulCount [in]CountofattributesinthepTemplatearray.

SAPI_SetTokenName
Thisfunctionisusedtosetthetokennamewithoutreinitializingit. Sinceitiscurrentlytheonlyfunctionthatsetsatokenpropertyand sincethispropertyisavailableviatheC_GetTokenInfostructure,it doesnotusethetemplateasaparameter.
CK_RV SAPI_SetTokenName ( CK_SESSION_HANDLE hSession, CK_CHAR_PTR label

);

Parameters
hSession [in]Sessionhandleopenedforgiventoken. label [in]Zeroterminatedstringofthenewtokennamethatwillbeset.

Remarks
Theapplicationshouldpassproperauthenticationtousethis function.Thetokenlabelissubjecttosizerestrictionasdefinedin CK_TOKEN_INFOstructureandinPKCS#11partofthisdocument.

Functions

99

SAPI_InitToken
Thisfunctionisusedtoinitializethetoken.Tokenattributesare passedtocustomizetheinitialization.Thecallbackfunctionmaybe usedtoreportthestatusofinitialization.
CK_RV SAPI_InitToken ( CK_SLOT_ID slotId, CK_ATTRIBUTE_PTR pTemplate, CK_ULONG ulCount, CK_VOID_PTR pContext, CK_INIT_CALLBACK_p Callback

);

Parameters
slotId [in]identifieroftheslotwherethetokenislocated pTemplate [in]Pointertotheattributesarraythatcontainstheinitialization parameters. ulCount [in]CountofattributesinthepTemplatearray. pContext [in]UserprovidedparametertobepassedtopCallbackfunction. pCallback [in]Callbackfunctionthatletstheapplicationshowtheprogressof thetokeninitializationprocess.Thecallbackisoptional(NULLmay bepassed).

100

SAPI_FindTokens
Thisfunctionreturnsalistofslotscontainingtokensthatcomplywith searchcriteria.Thesearchcriteriamaycontainanytokenattributes exceptthosethatmaybeusedonlyforinitialization.

Note:
Wedonotrecommendcallingthisfunctionwithanemptytemplate, asthebehaviormayvarybetweenPKIClientversions.
CK_RV SAPI_FindTokens ( CK_SLOT_ID_PTR pSlots, CK_ULONG_PTR pSlotCount, CK_ATTRIBUTE_PTR pTemplate, CK_ULONG ulCount

);

Parameters
pSlots [out]Pointertothearraythatwillbefilledbyfoundslotidentifiers. pSlotCount [in/out]Pointertothevariablethat: OninputdefinesthesizeofthepSlotsarray Onoutputreceivestheactualnumberoffoundslots pTemplate [in]Pointertotheattributesarraycontainingtheparametersofthe requestedtokens. ulCount [in]CountofattributesinthepTemplatearray.

Functions

101

SAPI_LocateToken
Thisfunctionfindstheslotwhereaparticulartokenislocated.
CK_RV SAPI_LocateToken ( CK_VOID_PTR unique, CK_ULONG size, CK_SLOT_ID_PTR pSlotId

);

Parameters
unique [in]Pointertothebuffercontainingtheserialnumber (CKA_SAPI_SERIAL)ofthetokentobelocated. size [in]Sizeoftheuniquebuffer. pSlotId [out]Pointertothevariablethatreceivesthelocatedtokensslot identifier.

SAPI_UnblockPIN
ThisfunctionisusedtounblocktheuserPIN(usingachallenge responsemechanism).ThetokenshouldhaveanSecurityOfficer(SO) PIN,buttheSOshouldnotbeloggedon. PKCS#11hasthefunctionC_InitPIN thatmaybeusedbytheSOto unblocktheuserpassword.However,itrequirestheapplicationtolog onfirstlywiththeSOpassword.Thisapproachmaynotbeapplicable forsomerealworldapplicationswhenthetokenislocatedonthe userssitebecausetheadministratorwillnotbereadytorevealtheSO passwordtotheuser.

102 ThefunctionSAPI_UnblockPINusesachallengeresponsemechanism insteadofthepasswordtoauthenticatetheadministrator.The cryptographicchallengeisreceivedfromthetokenandpassedtothe pCallbackfunctionprovidedbytheapplication.Theapplicationhas tocomputearesponseinordertocompleteauthenticationtothe token.TheSAPI_Server_Unblockfunctionmaybeusedforthis purpose.Sincethisfunctiondoesnotrequireatokenpresenceitmay beperformedontheserversite.

CK_RV SAPI_UnblockPIN ( CK_SESSION_HANDLE hSession, CK_CHAR_PTR pNewPin, CK_ULONG ulNewPinLen, CK_UNBLOCK_CALLBACK pCallback

);

Parameters
hSession [in]Sessionhandleopenedforthegiventoken. pNewPin [in]PointertothenewuserPIN. pNewPinLen [in]SizeofpNewPin. pCallback [in]Callbackfunctionthatisexpectedtocomputetheresponseforthe givenchallenge.

SAPI_UnblockPINEx
ThefunctionisequivalenttoSAPI_UnblockPIN,exceptthatitgetsone moreparameter(pContext),whichispassedtothecallbackfunction.
CK_RV SAPI_UnblockPIN ( CK_SESSION_HANDLE hSession, CK_CHAR_PTR pNewPin, CK_ULONG ulNewPinLen, CK_UNBLOCK_CALLBACK_EX pCallback, CK_VOID_PTR pContext

);

Functions

103

Parameters
hSession [in]Sessionhandleopenedforthegiventoken. pNewPin [in]PointertothenewuserPIN. pNewPinLen [in]SizeofpNewPin. pCallback [in]Callbackfunctionthatisexpectedtocomputetheresponseforthe givenchallenge. pContext [in]Contextthatwillbepassedtothecallbackfunction.

SAPI_Login
ThefunctionextendsC_LoginfunctionalitybyUIandpassword policymanagement.
CK_RV SAPI_Login ( CK_SESSION_HANDLE hSession, CK_USER_TYPE userType, CK_CHAR_PTR pPin, CK_ULONG ulPinLen, SAPI_PIN_POLICY_INFO* pPolicyInfo

);

Parameters
hSession [in]Sessionhandleopenedforthegiventoken. userType [in]CKU_USERorCKU_SO. pPin [in]PIN. ulPinLen

104 [in]PINlength. pPolicyInfo [out]Informationaboutpasswordexpiration.

Remarks
Thefunctiontakesinaccountthepasswordpolicysettingseven forpriorversions. IfNULLispassedaspPinand0ispassedasulPinLen,the SafeNetAuthenticationClientUIwillappearpromptingforuser orSOlogin. IfpPolicyInfoispassed,thefunctionwillreturnvaluable informationaboutpasswordexpiration.Itreturnsinformation aboutexpirationandwarningperiodandnumberofdays remainedtillpasswordexpiration.Ifthepasswordchangeis required,thefunctionwillfailwiththepropererrorcode.Ifthe passwordwillexpiresoon,thefunctionwillsuccessandwill returntheexpected(future)errorinthewarningfield. pPolicyInfocannotbeusedtogetherwithSafeNet AuthenticationClientUI. PasswordpolicyisappliedonlytotheuserPIN.

SAPI_SetPIN
ThefunctionextendsC_SetPINfunctionalitybyUIandpassword policymanagement.
CK_RV SAPI_SetPIN ( CK_SESSION_HANDLE hSession, CK_CHAR_PTR pOldPin, CK_ULONG ulOldPinLen, CK_CHAR_PTR pNewPin, CK_ULONG ulNewPinLen );

Parameters
hSession [in]Sessionhandleopenedforthegiventoken. pOldPin

Functions [in]OldPIN. ulOldPinLen [in]OldPINlength. pNewPin [in]NewPIN. ulNewPinLen [in]NewPINlength. Remarks:

105

IfNULLispassedasoldandnewPIN,theSafeNet AuthenticationClientUIwillappearpromptingforuserorSO passwordchange. PasswordpolicyisappliedonlytotheuserPIN.

OTP Functionality
TheoreticallyasingletokenmaysupportmultipleOTPalgorithms andkeepmorethanoneOTPobject.HoweverSAPImakesthe followingassumptions: OnlyoneOTPobjectcurrentlyexistsonthetoken.Thereforeno specialmechanismisproposedtoaddresstheparticularOTP objectinstanceonthetoken. ThesupportedOTPalgorithmsarecounterbased(only CK_SAPI_OTP_HMAC_SHA1_DEC6issupported,whichisequivalent toCKM_HOTP).ItisnotmentionedexplicitlyacrosstheAPI,butis impliedfromthesetofattributesdefinedfortheOTPobject. ThetokenisproperlyinitializedinordertooperatewithOTP.

SAPI_OTPGetMechanismList
ThisfunctionreturnsalistofavailableOTPmechanisms.Depending onOTPsupportonthetoken,eitherCK_SAPI_OTP_HMAC_SHA1_DEC6 orzerolengthlistwillbereturned.
CK_RV SAPI_OTP_GetMechanismList ( CK_SLOT_ID slotId, CK_ULONG_PTR pMechanismList, CK_ULONG_PTR pCount

106 );

Parameters
slotId [in]identifieroftheslotwherethetokenislocated pMechanismList [out]PointertothearraythatwillbefilledbyOTPmechanism identifiers. pCount [in/out]Pointertothevariablethat: OninputdefinesthesizeofthepMechanismListarray Onoutputreceivestheactualnumberoffoundmechanisms

SAPI_OTP_GetMechanismInfo
ThisfunctionreturnsinformationaboutaspecificOTPmechanism.
CK_RV SAPI_OTP_GetMechanismInfo ( CK_SLOT_ID slotId, CK_ULONG mechanism, CK_SAPI_OTP_MECHANISM_INFO_PTR pMechanismInfo

);

Parameters
slotId [in]identifieroftheslotwherethetokenislocated mechanism [in]OTPmechanismidentifierforwhichinformationisrequested. pMechanismInfo [out]PointertothestructurethatreceivestheOTPmechanism information.

Functions

107

SAPI_OTP_Create
ThisfunctioncreatesanOTPobject.Userloginshouldbeperformed priortothisoperation.
CK_RV SAPI_OTP_Create ( CK_SESSION_HANDLE hSession, CK_ATTRIBUTE_PTR pTemplate, CK_ULONG ulCount

);

Parameters
hSession [in]Sessionhandleopenedforgiventoken. pTemplate [in]Pointertotheattributesarraycontainingtheparametersofthe createdOTPobject. ulCount [in]CountofattributesinthepTemplatearray.

Remarks
MandatoryattributestobeprovidedareCKA_SAPI_OTP_MECHANISM andCKA_SAPI_OTP_VALUE. Ifnospecificattributeisprovided,thenzerowillbeusedasthe defaultvaluefortheseattributes.

SAPI_OTP_GetAttributeValue
ThisfunctionreturnsthecharacteristicsofanexistingOTPobject.The keyvalueissensitiveandwillnotbereturned.
CK_RV SAPI_OTP_GetAttributeValue ( CK_SESSION_HANDLE hSession, CK_ATTRIBUTE_PTR pTemplate, CK_ULONG ulCount );

108

Parameters
hSession [in]Sessionhandleopenedforgiventoken. pTemplate [in/out]Pointertotheattributesarraythatreceivestherequested information. ulCount [in]CountofattributesinthepTemplatearray.

SAPI_OTP_SetAttributeValue
ThisfunctionisusedtochangetheOTPobjectparameters.Onlythe displaydurationmaybechanged.
CK_RV SAPI_OTP_SetAttributeValue ( CK_SESSION_HANDLE hSession, CK_ATTRIBUTE_PTR pTemplate, CK_ULONG ulCount );

Parameters
hSession [in]Sessionhandleopenedforgiventoken. pTemplate [in]Pointertotheattributesarraycontainingthenewparametersof theOTPobject. ulCount [in]CountofattributesinthepTemplatearray.

SAPI_OTP_Destroy
ThisfunctiondeletesanexistingOTPobject.Userloginshouldbe performedpriortothisoperation.
CK_RV SAPI_OTP_Destroy ( CK_SESSION_HANDLE hSession );

Functions

109

Parameters
hSession [in]Sessionhandleopenedforgiventoken.

SAPI_OTP_Execute
ThisfunctioncomputesanOTPvalue.
CK_RV SAPI_OTP_Execute ( CK_SESSION_HANDLE hSession, CK_ULONG mode, CK_CHAR_PTR pResult, CK_ULONG_PTR pSize );

Parameters
hSession [in]Sessionhandleopenedforgiventoken. mode [in]Executionmode.(SeeRemarks) pResult [out]Pointertothebufferwhichreceivestheexecutedvalue. pSize [in/out]Pointertothevariablethat: OninputdefinesthesizeofthepResultarray OnoutputreceivestheactuallengthofthepResultarray.

Remarks
ModeCK_OTP_CURRENTreturnsthelastOTPcomputationwithout movingthecounter.

110 ModeCK_OTP_RELEASEiskeptonlyforbackwardcompatibility.In priorversionstheapplicationwassupposedtocallthe SAPI_OTP_Executefunctionwiththismodeaftergettinganew OTPvalueinordertoreleasethetokenforfutureOTPoperations. Thismodeisdeprecatednowandbehavesthesameas CK_OTP_CURRENT. Mode CK_OTP_ZEROperformsanOTPcomputationforthezero counter.Thismodemaybeusedwhenthetokenandtheserver areunsynchronizedinordertoresynchronizethem.

SAPI_Server_OTP_Calculate
ThisfunctioncalculatestheOTPvalueontheserverforagiven mechanism,keyandcounter.
CK_RV_SAPI_Server_OTP_Calculate ( CK_ATTRIBUTE_PTR pTemplate, CK_ULONG ulCount, CK_CHAR_PTR pResult, CK_ULONG_PTR pSize );

Parameters
pTemplate [in]PointertotheattributesarraycontainingtheOTPobject parameters. ulCount [in]CountofattributesinthepTemplatearray. pResult [out]Pointertothebufferwhichreceivesthecalculatedvalue. pSize [in/out]Pointertothevariablethat: OninputdefinesthesizeofthepResultarray OnoutputreceivestheactuallengthofthepResultarray.

Functions

111

Remarks
Thetemplateshouldcontainthefollowingattributes:
CKA_MECHANISM CKA_COUNTER CKA_VALUE

SAPI_Server_BI_EstimateValue
Thisfunctionisdeprecated.

SAPI_Server_BI_EstimateRetainDays
Thisfunctionisdeprecated.

SAPI_Server_Unblock
Thisfunctioncomputestheproperresponseforthechallenge responsemechanismusedduringuserPINunblocking.
CK_RV SAPI_Server_Unblock ( CK_CHAR_PTR pPin, CK_ULONG ulPinLen, CK_VOID_PTR pChallenge, CK_VOID_PTR pResponse );

Parameters
pPin [in]PointertotheSecurityOfficer(SO)PINstring. ulPinLen [in]LengthofSOPIN. pChallenge [in]Pointertothe8bytelengthchallengebufferreceivedfromthe token. pResponse

112 [out]Pointertothe8bytelengthresponsebufferprovidedtounblock theuserPIN.

Major Backward Compatibility Issues of SAPI

ManySAPIfunctionsaredeprecated(especiallybattery indication). ErrorsreturnedbytheSAPIfunctionsmayvarybetweenversions. PriortoPKIClient4.0itwasenoughtoredistributeonly libeTSapi.sotouseserveronlyfunctionality.SincePKIClient 4.0itisnottrue;PKIClientmustbeinstalled. SomeOTPattributesaretakenasfixed.

Chapter 5

Samples
ThischapterdescribesthecurrentSafeNetAuthenticationClient32 bitsamples. Sample Overview Compiling the Samples PKCS#11 Samples PKCS#11 Token-Specific Extensions Samples SAPI Samples

114

Sample Overview
Thischapterprovidesadescriptionofthesamples.Thesamples themselvesareavailableonthetokenwebsite.Fordetailscontact Support(SeeSupportonpageiii) AllsamplesareinC/C++. Thesamplescoverdifferentprogrammingtechniquestoshowthe multipleoptionsavailable.Differentsamplesmayachievesimilar results,butthroughdifferentmethodologies. Thesamplesarenotalwaysfullyfunctionalapplications.Certain details,suchaserrorhandling,maybeomittedforthesakeofbrevity. Thefollowingsamplesaredescribedinthischapter: API
PKCS#11

Sample
Info Test InitToken Password Policy CACert

PKCS#11 Token Specific Extensions SAPI

Initiating UnlockToken InitOTP InitToken TokenInfo

Compiling the Samples

Youcancompilethesamplesinoneofthefollowingways: UseSlickEdit:opentherelevantsamplesSlickEditproject(vpw). RunMakefile:gototherelevantsampleandrunthemake command.

PKCS#11 Samples

115

PKCS#11 Samples
Readthefollowingintroductoryremarksbeforestartingtoworkwith thesesamples: Werecommendloadingthelibrarydynamically. Donotusehardcodedfunctionnames.Accordingtothe standard,youshouldcallthefunctionC_GetFunctionList to reachtheaddressesofotherfunctions.Thisistheonlyfunction namethatisguaranteedtoyou. InmanycryptographicapplicationsyouhavetodealwithX.509 certificates.TheX.509certificatehasacomplicateddatastructure encodedinaspecialway(DERencodingofASN.1).Thereisno simplewayforapplicationstodealwiththisdatastructure. SafeNetAuthenticationClientdoesnotprovidespecialhelper functionsforthispurpose.However,youmayuseMicrosoft helperfunctionsdescribedinMSDN.Theyareusedwidelyinthe samples.

CACert
ThissampledemonstrateshowtoimportaCAcertificateintoatoken. The sample performs the following actions: ReadstheCERfile. ExtractsthesubjectoftheCERfile. Searchesforthefirstconnectedtoken. Opensasessionandperformslogintothetoken. ImportstheCAcertificateintothetoken.

116

ClearToken
Thissamplegetsthetokenpasswordandacertificatelabel.Itthen runsoverallthetokensobjectsdeletingthem,excludingtheobject withthegivenlabel.

Info Test
ThissampleprintsgeneralinformationaboutthePKCS#11libraryand waitsforanyslotevents(tokeninsertionorremoval).Upontoken insertion,itprintsinformationaboutthetokenanditscertificates. Thesamplecontinuesthisoperationinanendlessloop.Itcanbe stoppedbyendingtheprocess.Noparametersarepassedtothis sample. Thissampledemonstratesthefollowingtechniques: DynamicloadingandinitializationofthePKCS#11library(all othersamplesfollowthesametechnique)andreachingaddresses offunctionsviaC_GetFunctionList. Obtaininginformationaboutthelibrary,slotsandtokensvia functionsC_Info, C_GetSlotInfo,C_GetTokenInfo. ObtainingthesupportedRSAkeysizewiththefunction C_GetMechanismInfo. Findingobjectsthatsatisfyaparticularpattern(setofattributes); thesampleshowshowtofindaX.509certificateobject. Retrievingobjectattributes. UsingMicrosofthelperfunctionstoextractinformationfromthe certificate.

PKCS#11 Samples

117

InitToken
Theinitializationoftokeniscomplicatedbythefactthatsome importantissues,suchastheneedforauthentication,arepurposely keptoutofthescopeofthePKCS#11standard.Thissample demonstrateshowtoinitializethetokenusingPKCS#11.Thefunction thatisusedinthissampleforinitializationisC_InitToken(andnot oneofPKIClientsextendedfunctionsforinitialization). ThissamplealsodemonstrateshowtogenerateanRSAkeypairon thetoken. Thesamplehasthefollowingcommandlineparameters: Readername. Tokenformattingpassword: ForanoninitializedtokenusetheSOpasswordthatisset afterinitialization(seeBehaviorofStandardC_InitTokenand C_InitPINFunctionsonpage42). Foratokeninitializedwithanadministratorpassword,use theadministratorpassword. Foratokeninitializedwithoutanadministratorpassword, usethecurrentuserpassword. Userpasswordtobesetafterinitialization. ThissampledemonstratesthataflowdoesnotrequireaUIforany kindoftoken(notinitialized,initializedwithorwithoutadministrator password). The suggested flow is: 1. 2. 3. 4. MapthereadernametotheslotID. Openthesessionwiththetoken.SafeNetAuthenticationClient willallowthesessiontoopenevenwithanoninitializedtoken. LoginastheSOwiththetokenformattingpassword. Closethesession. YoushouldclosethesessionsinceitcannotperformC_InitToken ifatleastonesessionwiththetokenisopen.Yourtokenwillbe loggedout,butSafeNetAuthenticationClientwillkeepthe passwordforaperiod,preventingloginUI(forthenextstep). PerformC_InitEToken. Thesameformattingpasswordispassedastheparameter.

5.

118 6. 7. 8. 9. Openanewsession. LoginasSOwiththeformattingpassword. PerformC_InitPintoinitializetheuserpassword. PerformC_Logout.Yourtokenisinitializednow. Todemonstratesuccessfultokeninitialization,thesamplethen logsinastheuserandgeneratesanRSAkeypair.

Note:
TreatmentoftheC_InitTokenparametervariesbetweenversions ofPKCS#11.Laterversions(v2.11,v2.20)defineitas: Foranemptytoken:NewSOpassword Foralreadyinitializedtoken:CurrentSOpassword Suchadefinitionismuchmoreuseful.Whenfutureversionsofthe SafeNetAuthenticationClientsupportlaterversionsofPKCS#11,this approachwillbeapplied.

Password Policy
Thissampledemonstrateshowtomanipulatethetokenpassword policyobject.Afterthetokenisinitializedwechangethecurrent passwordpolicyobject. Thissampledemonstratestheuseofthefollowingfunctions,tofind thePINpolicyobject:
C_FindObjectsInit C_FindObjects C_FindObjectsFinal

ThesamplethenusesthefollowingtoupdatethecurrentPINPolicy Object:
C_SetAttributeValue

PKCS#11 Token-Specific Extensions Samples

119

Thesamplethendemonstratesatheuseofsometokenfunctionsthat verifythenewupdatedsettings.

PKCS#11 Token-Specific Extensions Samples

Initiating
ThissampledemonstrateshowtoinitializethetokenusingPKCS#11 tokenspecificextensions. ThesampleloadsthePKCS#11andthePKCS11TokenSpecific extensionsfunctionlistsandthengetsinformationfromthetokento decideifthetokensupportsthe2048keysize.Theinitialization processthenbegins. ThesamplealsodemonstratestheinitializationofthePinPolicy Object. The sample uses the following functions:
ETC_InitTokenInitcreatethesession(startthetransaction) ETC_InitPINsameasC_InitPinbutwiththeadditionoftwo

newvariables: Userretrycounter Flagtochangethepassword ETC_InitTokenFinal endthetransactionandphysically initializethetoken

UnlockToken
TakesatokenandunlocksitusingPCKS#11Extensionsfunctions.The sampleshowstheuseoftheChallengeResponseprocess.

Note:
ThissampleissupportedinPKIClient4.55orlater.

120 The sample performs the following Openssessionwiththetoken. PrintsthepointersofthePCKS#11Extendedfunctions. ChecksETC_ UnlockGetChallenge. CallsPCKs#11standardfunctionsandprintstheuserretry counterfromthetoken. Performsunlockingofthetoken: PCKS#11ExtensionsETC_ UnlockGetChallenge SAPISAPI_Server_Unblock PCKS#11ExtensionsETC_UnlockComplete

SAPI Samples
InitOTP
ThissampledemonstratestheOTPfunctionallyofthetokenusing SAPI.ThissampledemonstratestheOTPfunctionalityofthetoken.It isassumedthattokenhasOTPcapabilitiesandthatthetoken firmwaresupportstheOTPcalculationintheonlinemode(thatis, whenthetokenconnected).Thisinformationisreceivedfromthe SAPI_OTP_GetMechanismInfofunction. The sample performs the following: Opensthesessionwiththetoken Logsintheuser(itisnecessarytocreateanOTPobject) DestroysoldOTPobjects(ifany) CreatesanewOTPobject(Inarealapplication,thesamekey shouldbestoredontheserveraswell) DemonstratesanonlineOTPcalculation(itisrarelyusedinreal applications) Demonstratesaserversidecalculation

SAPI Samples

121

InitToken
ThissampledemonstrateshowtoinitializeatokenusingSAPI.

TokenInfo
ThissampledemonstrateshowtouseSAPItoobtainmoredetailed informationaboutaparticulartoken.

122

Index
A
API_Server_BI_EstimateRetainDays 111 CKA_SAPI_CARD_ID(CK_BYTE_PTR) 86 CKA_SAPI_CARD_TYPE(CK_ULONG) 86 CKA_SAPI_CARD_VERSION (CK_VERSION) 87 CKA_SAPI_CASE_MODEL (CK_ULONG) 87 CKA_SAPI_COLOR(CK_ULONG) 87 CKA_SAPI_FIPS(CK_BBOOL) 87 CKA_SAPI_FIPS_SUPPORTED (CK_BBOOL) 88 CKA_SAPI_HAS_LCD(CK_BBOOL) 88 CKA_SAPI_HAS_SO(CK_BBOOL) 88 CKA_SAPI_HAS_USER(CK_BBOOL) 88 CKA_SAPI_HMAC_SHA1(CK_BBOOL) 89 CKA_SAPI_HMAC_SHA1_SUPPORTED (CK_BBOOL) 89 CKA_SAPI_INIT_PIN_REQCK_BBOOL) 89 CKA_SAPI_MAY_INIT(CK_BBOOL) 89 CKA_SAPI_MODEL(CK_CHAR_PTR0) 89 CKA_SAPI_NEW_KEY(CK_BYTE_PTR) 90 CKA_SAPI_OLD_KEY(CK_BYTE_PTR) 90 CKA_SAPI_OTP_COUNTER( CK_ULONG) 94 CKA_SAPI_OTP_CUSTOM_DURATION _ALLOWED(CK_BBOOL) 95 CKA_SAPI_OTP_DURATION( CK_ULONG) 95 CKA_SAPI_OTP_MECHANISM( CK_MECHANISM_TYPE) 95

B
BackwardCompatibilityIssues 43 BackwardCompatibilityof C_InitToken/C_InitPIN 43

C
C_CopyObject 19 C_DeriveKey 20 C_Finalize 14 C_GenerateKeyPair 20 C_GetAttributeValue 19 C_GetInfo 14 C_GetObjectSize 19 C_GetSlotInfo 15 C_GetSlotList 15 C_GetTokenInfo 16 C_Initialize 13 C_InitToken 18 C_Login 19 C_SeedRandom 20 C_SetPIN 18 C_WaitForSlotEvent 18 CACertificates 46 CACert 115 CAPISupport 46 ChoosingtheCorrectAPI 2 CK_INIT_CALLBACK 79 CK_SAPI_OTP_MECHANISM_INFO 81 CK_UNBLOCK_CALLBACK 80 CK_UNBLOCK_CALLBACK_EX 80

124
CKA_SAPI_OTP_VALUE( CK_BYTE_PTR) 95 CKA_SAPI_OTP_ZERO_ALLOWED (CK_BBOOL) 95 CKA_SAPI_PIN_CURRENT( CK_CHAR_PTR) 90 CKA_SAPI_PIN_SO(CK_CHAR_PTR) 90 CKA_SAPI_PIN_USER( CK_CHAR_PTR0 90 CKA_SAPI_PRODUCT_NAME( CK_CHAR_PTR) 91 CKA_SAPI_PRODUCTION_DATE( CK_DATE) 91 CKA_SAPI_REAL_COLOR (CK_BBOOL) 91 CKA_SAPI_RETRY_SO(CK_ULONG) 91 CKA_SAPI_RETRY_USER (CK_ULONG) 92 CKA_SAPI_RETRY_USER_MAX( CK_ULONG) 92 CKA_SAPI_RSA_2048(CK_BBOOL) 93 CKA_SAPI_RSA_2048_SUPPORTED( CK_BBOOL) 93 CKA_SAPI_RSA_KEYS(CK_ULONG) 92 CKA_SAPI_SERIAL(CK_CHAR_PTR) 93 CKA_SAPI_SLOT_NAME (CK_UTF8CHAR_PTR) 85 CKA_SAPI_SLOT_TYPE(CK_ULONG) 85 CKA_SAPI_TOKEN_ID( CK_BYTE_PTR) 93 CKA_SAPI_USER_PIN_INITIALIZED( CK_BBOOL) 94 CommonDescriptionofSAPI 76 CompilingtheSamples 114 ConfiguringSecondaryAuthentication fortheToken 35 Constants 47 Controllinginitializationparameters 38 CreationofPasswordPolicyObject 40 CreationoftheProtectedRSAKey 34 CreationTokenObject 39 CryptographyInformationSources 5

D
DataTypes 49

E
ErrorCodes 82 ETC_BeginTransaction 65 ETC_CreateVirtualSession 67 ETC_DestroyTracker 65 ETC_EndTransaction 66 ETC_GetProperty 66 ETC_InitPIN 69 ETC_InitTokenFinal 69 ETC_InitTokenInit 68 ETC_SetProperty 67 ETC_SingleLogonGetPin 68 ETC_UnlockComplete 70 ETC_UnlockGetChallenge 69 ETCKM_PBA_LEGACY 70 ExtensionsRelatedtoOperationswith SlotsandTokens 27

I
InfoTest 116 Initiating 119 InitToken 117, 121

K
KA_SAPI_OTP_CURRENT_ALLOWED (CK_BBOOL) 94 KA_SAPI_RETRY_SO_MAX (CK_ULONG) 92

125

M
Majorbackwardcompatibilityissuesof PKCS#11 21 Majorbackwardcompatibilityissuesof SAPI 112 MiscellaneousFunctionality 78 MultiLanguageSupport 6

N
Notification 118 Notifications 28 Nullterminationofstrings 25

O
Objects 50 OneFactorAuthentication 44 OTP 31 OTPFunctionality 77, 105 OTPObject 94

P
Passwordmanagement 6 PasswordPolicy 29, 118 PasswordPolicyManagement 6 PINInitialization 42 PKCS#11Functions 13 PKCS#11Samples 115 PKCS#11TokenSpecificExtensions Samples 119 PrivateDataCaching 47 Proprietaryinitializationfunctions 36

SAPI_GetSlotInfo 97 SAPI_GetTokenInfo 97 SAPI_InitToken 99 SAPI_LocateToken 101 SAPI_Login 103 SAPI_OTP_Create 107 SAPI_OTP_Destroy 108 SAPI_OTP_Execute 109 SAPI_OTP_GetAttributeValue 107 SAPI_OTP_GetMechanismInfo 106 SAPI_OTP_SetAttributeValue 108 SAPI_OTPGetMechanismList 105 SAPI_PIN_POLICY_INFO 81 SAPI_Server_BI_EstimateValue 111 SAPI_Server_OTP_Calculate 110 SAPI_Server_Unblock 111 SAPI_SetPIN 104 SAPI_SetTokenName 98 SAPI_UnblockPIN 101 SAPI_UnblockPINEx 102 Secondaryauthentication 33 SingleLogonMode 44 SlotObject 85 Slot/TokenFunctionality 97 Slot/TokenIOCTL 27 SpecialAuthenticationFeatures 44 StandardC_InitTokenandC_InitPIN Functions 42 SupplyingSpecialPINtotheRSAPrivate KeyOperation 34 SupportedeTokenModels 7

T
TheInitializationFlow 36 Tokeninitialization 35 TokenInitializationKeys 40 TokenObject 86 TokenlessOperations 29 TokensInitializedbyEarleirPKIClient 43 TokenspecificPKCS#11Extensions 23 TokenspecificPKCS#11extensions 24 Transactions 28

S
SafeNeteTokenVirtual 27 SampleOverview 114 SAPIObjects 85 SAPI_FindTokens 100 SAPI_GetLibraryInfo 96

126

U
Understandingsecondaryauthentication 33 UNICODESupport 25 UnlockToken 119 UserPINunlocking 45 UsingTokensInitializedbyPKIClient 4.0,4.5or5.0inEarlierVersions 43

V
VendorspecificOTPKeyAttributes 33

W
WhyExtensionsareNeededfor Initialization 35 WritingWrapperObjects 4