.Net Strng Authenticatin API fr Pwerful Authenticatin Management fr Service Prviders and Enterprises Authenticatin Service Delivery Made EASY
Micrsft Windws Lgn with BlackShield Cpyright Cpyright 2011. CRYPTOCard Inc. All rights reserved. The infrmatin cntained herein is subject t change withut ntice. Prprietary Infrmatin f CRYPTOCard Inc. Disclaimer The infrmatin cntained in this dcument may change withut ntice, and may have been altered r changed if yu have received it frm a surce ther than CRYPTOCard Inc. While every effrt is made t ensure the accuracy f cntent ffered n these pages, CRYPTOCard Inc. shall have n liability fr errrs, missins r inadequacies in the cntent cntained herein r fr interpretatins theref. Use f this infrmatin cnstitutes acceptance fr use in an AS IS cnditin, withut warranties f any kind, and any use f this infrmatin is at the user s wn risk. N part f this dcumentatin may be reprduced withut the prir written permissin f the cpyright wner. CRYPTOCard Inc. disclaims all warranties, either expressed r implied, including the warranties f merchantability and fitness fr a particular purpse. In n event shall CRYPTOCard Inc. be liable fr any damages whatsever, including direct, indirect, incidental, cnsequential r special damages, arising frm the use r disseminatin heref, even if CRYPTOCard Inc. has been advised f the pssibility f such damages. Sme prvinces, states r cuntries d nt allw the exclusin r limitatin f liability fr cnsequential r incidental damages, s the freging limitatin may nt apply. Links and addresses t Internet resurces are inspected thrughly prir t release, but the everchanging nature f the Internet prevents CRYPTOCard Inc. frm guaranteeing the cntent r existence f the resurce. When pssible, the reference cntains alternate sites r keywrds that culd be used t acquire the infrmatin by ther methds. If yu find a brken r inapprpriate link, please send an email with the tpic name, link, and its behaviur t supprt@cryptcard.cm. The sftware described in this dcument is furnished under a license and may be used r cpied nly in accrdance with the terms f the license. Trademarks BlackShield ID, CRYPTOCard and the CRYPTOCard lg are trademarks and/r registered trademarks f CRYPTOCard Crp. in Canada and/r ther cuntries. All ther gds and/r services mentined are trademarks f their respective hlders. 2
Micrsft Windws Lgn with BlackShield Cntact Infrmatin CRYPTOCard s technical supprt specialists can prvide assistance when planning and implementing CRYPTOCard in yur netwrk. In additin t aiding in the selectin f the apprpriate authenticatin prducts, CRYPTOCard can suggest deplyment prcedures that prvide a smth, simple transitin frm existing access cntrl systems and a satisfying experience fr netwrk users. We can als help yu leverage yur existing netwrk equipment and systems t maximize yur return n investment. CRYPTOCard wrks clsely with channel partners t ffer wrldwide Technical Supprt services. If yu purchased this prduct thrugh a CRYPTOCard channel partner, please cntact yur partner directly fr supprt needs. T cntact CRYPTOCard directly: United Kingdm 2430 The Quadrant, Aztec West, Almndsbury, Bristl, BS32 4AQ, U.K. Phne: +44 870 7077 700 Fax: +44 870 70770711 supprt@cryptcard.cm Nrth America 600-340 March Rad, Kanata, Ontari, Canada K2K 2E4 Phne: +1 613 599 2441 Fax: +1 613 599 2442 supprt@cryptcard.cm Fr infrmatin abut btaining a supprt cntract, see ur Supprt Web page at http://www.cryptcard.cm Overview 3
Micrsft Windws Lgn with BlackShield Authenticatin Service Delivery Platfrm Cmpatibility Publicatin Histry Date Changes Versin 2009.01.26 Dcument created 1.0 2009.07.01 Cpyright dates updated 1.1 2009.10.16 Minr updates 1.2 4
Micrsft Windws Lgn with BlackShield Overview This dcument utlines the BlackShield ID authenticatin API that allws agents t supprt all the functinality that is required t interact with the BlackShield authenticatin server. BlackShield agents are essentially third party applicatins which have plug-in cde embedded in rder t allw the cllectin f user names and ne time passwrds t be passed t the BlackShield server t be verified. Specificatin Overview BlackShield ID Authenticatin API The BlackShield ID authenticatin API is represented by a single C# class BSIDAPI. This class has a default cnstructr which lads its cnfiguratin infrmatin frm a default registry lcatin, and als an alternate cnstructr t allw the user t define an alternate lcatin in the registry frm which t lad its cnfiguratin. Cnstructrs BSIDAPI() { } // reads registry SOFTWARE\CRYPTOCard\BlackShield ID\BSIDAPI BSIDAPI(string CnnectinInfrmatin) { } // reads registry key defined by CnnectinInfrmatin Nte: By using the cnnectin infrmatin in the cnstructr, an agent may specify ne r mre BlackShield servers in rder t implement failver authenticatins. The cnnectin infrmatin fr each BlackShield server can be stred in its wn key. Overview 5
Micrsft Windws Lgn with BlackShield Authenticate Methd All authenticatin related actins make use f a single API call: Authenticate ( string user, string rg, string ipaddress, string passcde, ref string challenge, ref string state ); returns: where: int 0 Authenticatin Failed 1 Authenticatin Succeeded 2 Challenge 3 Server prvided PIN 4 User needs t prvide PIN 5 Authenticatin in uter windw. Re-authenticate. 6 User must change their static passwrd. 7 Static passwrd change des nt satisfy plicies. 8- PIN prvided desn t meet requirements. Please prvide a new PIN. user a string representing the user name f the individual wh is authenticating. rg a string representing the rganizatin t which the individual wh is authenticating belngs. This currently shuld be passed as an empty string t represent the default rganizatin. ipaddress a string representing the IP address frm which the authenticatin request came. If this parameter is an empty string, the BlackShield server will attempt t detect the IP frm which the authenticatin request came frm. passcde a string representing the user s passcde. This may take frm f either: [PIN+OTP] fr server-side PIN authenticatin. [OTP] tken side PINs r n PIN. [PIN] when respnding t a server-side user changeable PIN change request. [StaticPasswrd] user has a static passwrd enabled r is respndng t a static passwrd change. Finally, this parameter may als be set t null t indicate a challenge is required. Specificatin Overview 6
Micrsft Windws Lgn with BlackShield challenge a string passed by reference that may be ppulated with a challenge/pin change/uter windw authenticatin message. state a string passed by reference that may be ppulated with a state attribute. When returning a challenge, the same state shuld passed back t the server. VerifySignature Methd Verifies the tken's signature fr a given hash. VerifySignature ( ); returns: string SerialNumber, string Hash, string Signature where: int 0 Signature is incrrect fr hash prvided. 1 Signature is crrect fr hash prvided. SerialNumber a string representing the tken s serial number. Hash a string representing the hash value t verify. Signature a string representing the signature t verify fr the prvided hash. Specificatin Overview 7
Micrsft Windws Lgn with BlackShield CheckServerStatus Methd The peratinal status f the BlackShield authenticatin server can be mnitred thrugh the use f the CheckServerStatus methd. CheckServerStatus ( ); // vid returns: int 0 Server is dwn 1 Server is peratinal Nte: The CheckServerStatus methd is useful t mnitr the health f a BlackShield server fr the purpse f initiating failver t a secndary server. Specificatin Overview 8
Micrsft Windws Lgn with BlackShield Use Case Scenaris The BlackShield ID architecture supprts the cncept f a tken-side and server-side PIN used in either QuickLg r Challenge/Respnse mde. In additin, agents must supprt challenges, inner/uter windw authenticatin, and static passwrd authenticatin. The fllwing sectins discuss these features in mre detail. Basic Authenticatin The cmmunicatin between a BlackShield agent and server is smewhat similar t that used in the RADIUS prtcl, in that the cncepts f challenge messages and states are used. The fllwing scenari shws the mst basic interactin between the agent and server: 1. Authenticating agent issues an authenticatin request with username, rganizatin name, and a passcde. 2. Server respnds with ne f nine pssible return cdes as utlined in Authenticate Methd n page 6. Challenge-Respnse Central t the cncept f challenge/respnse authenticatin, uter windw authenticatin, and server-side PIN changes, is a challenge message and state attribute issued frm the authenticating server. This mechanism is emplyed t authenticate tkens in challenge/respnse mde in the fllwing manner: 1. Authenticating agent issues an authenticatin request with username, rganizatin name, and a blank passcde. 2. Server respnds with a challenge message cntaining a challenge string i.e.: challenge: 19863257, and a state attribute. 3. Authenticating agent respnds t the challenge by issuing anther authenticatin request with their username, rganizatin name, a respnse, and the state attribute. NOTE: In rder t supprt lcalizatin, the BlackShield server returns nly necessary data in its challenge messages, and the agent is required t cnstruct a lcalized versin f it t display t the client. Fr example, the BlackShield server wuld return nly 19863257, and the BlackShield agent wuld display Please respnd t the challenge: 19863257. Specificatin Overview 9
Micrsft Windws Lgn with BlackShield Outer Windw Authenticatin Als harnessing the cncept f challenge messages and maintaining state, is the authenticating a user thrugh inner/uter windw authenticatin. Outer windw authenticatin allws a user t authenticate by prviding a match in a large lk ahead windw; hwever, they must als be able t respnd t a fllw up challenge which asks them t prvide the exact next OTP frm their tken. The fllw sequence illustrates this functinality: 1. Authenticating agent issues an authenticatin request with username, rganizatin name, and a passcde. 2. The server finds a match fr the prvided OTP in the uter windw, therefre it issues a challenge t the client cntaining an uter windw authenticatin string, i.e.: Please reauthenticate using the next OTP frm yur tken, and a state attribute. 3. Authenticating agent respnds t the challenge by issuing anther authenticatin request with their username, rganizatin name, a respnse, and the state attribute. PIN Styles NOTE: Please see the lcalizatin nte in Challenge-Respnse n page 9. A number f PIN styles in BlackShield ID are supprted: N PIN. Fixed PIN. (tken side PIN validatin) User-changeable PINs. (tken side PIN validatin) Stred n server, fixed PIN. Stred n server, user-changeable PIN. Stred n server, server-changeable PIN. The authenticatin mechanism in BlackShield supprts incming passcdes in the fllwing frmat [PIN+OTP], [OTP], [NEWPIN], [STATICPASSWORD] and an empty passcde t request a challenge. In the case f PINs which are stred n the server, yet are user r server changeable, the challenge framewrk needs t be leveraged again in the fllwing manner: Stred n server, user-changeable 1. Authenticating agent issues an authenticatin request with username, rganizatin name, and a passcde. 2. The server finds a match fr the prvided OTP hwever it determines that it is necessary fr the user t change their PIN, therefre it issues a challenge t the client cntaining a PIN change string, i.e.: Yur PIN has expired. Please enter a new PIN: and a state attribute. 3. The authenticating agent respnds t the challenge by returning the new PIN, and the state attribute. Specificatin Overview 10
Micrsft Windws Lgn with BlackShield NOTE: Please see the lcalizatin nte in sectin 3.2.2. Stred n server, server-changeable 1. Authenticating agent issues an authenticatin request with username, rganizatin name, and a passcde. 2. The server finds a match fr the prvided OTP hwever it determines that it is necessary fr the user t change their PIN, therefre it issues a challenge t the client cntaining a PIN change string, i.e.: Yur new PIN is 628. Please re-authenticate using this new PIN and yur next passcde and a state attribute. 3. Authenticating agent respnds t the challenge by issuing anther authenticatin request with their username, rganizatin name, the new PIN and OTP, and the state attribute. NOTE: Please see the lcalizatin nte in Challenge-Respnse n page 9. Static Passwrd Authenticatin BlackShield ID als ffers the ptin f static passwrd authenticatin, with the ability fr the user t change their passwrd. The challenge respnse architecture can be used t facilitate this functinality, in the fllwing manner: 1. Authenticating agent issues an authenticatin request with username, rganizatin name, and a static passcde. 2. If the user is nt required t change their static passwrd and it is crrect, the server returns access-accept. If the user is required t change their static passwrd, a challenge message will be issued t client, i.e.: Yur passwrd has expired. Please enter a new passwrd: and a state attribute. 3. The authenticating agent respnds t the challenge by issuing an access-request message with their username, rganizatin, the new static passwrd, and the state attribute. NOTE: Please see the lcalizatin nte in Challenge-Respnse n page 9. Specificatin Overview 11
Micrsft Windws Lgn with BlackShield 3.3 Agent Key Files The BlackShield ID API uses an encrypted key file t secure cmmunicatin with the server. T accmplish this, a key file is laded and registered with agents, and then a matching key is registered with the authenticatin server. A sample key file (default.bsidkey) has been installed fr evaluatin purpses; hwever, it is strngly recmmended that yu generate yur wn key file fr a prductin envirnment, as the sample file is publicly distributed. The sectin belw will describe the steps required t use yur wn key file. Lad Key File 1. Dwnlad an agent key file in the Agent Settings sectin f the System Tab. 2. Using Windws Explrer change yur current wrking directry t the KeyFile directry by typing "[INSTALLDIR]\KeyFile\" in the address bar where [INSTALLDIR] represents the install directry f this API. 3. Cpy and paste the agent key file btained frm step number ne abve. Register Key File 1. It is necessary t register the certificate that has been laded abve. T register, first pen up a cmmand windw (Start->Run) and type regedit, fllwed by clicking n OK. 2. Expand My Cmputer, HKEY_LOCAL_MACHINE, SOFTWARE, CRYPTOCARD, BLACKSHIELD ID, BSIDAPI 1 3. Duble click EncryptinKeyFile 4. In the text bx, enter the fully qualified path t the agent key file that was laded abve. Then click OK. 1 In the event that yu are using a custm registry key lcatin as passed t the BSIDAPI cnstructr, yu shuld update key file infrmatin f that registry key instead. Specificatin Overview 12
Micrsft Windws Lgn with BlackShield Lgging If an unexpected behavir ccurs, the BlackShield ID API will lg an errr message t the Windws Event Viewer s Applicatin lg. The surce will appear as BSIDAPI. API Example Please see the apitestclient directry fr an example f hw t add a reference t the BSIDAPI.dll, and use the BSIDAPI class t define cnnectin infrmatin, and call the Authenticate and CheckServerStatus methds. Deplyment Shuld yu wish t deply yur cmpleted applicatin t anther cmputer, yu shuld keep in mind the fllwing cnfiguratin needed t supprt the BlackShield ID API: 1. Deply the registry keys as defined by: SOFTWARE\CRYPTOCard\BlackShield ID\BSIDAPI Or if yu are using custm registry key(s) t define cnnectin infrmatin as passed t the BSIDAPI cnstructr, yu shuld deply thse registry key(s). 2. An agent key file shuld als be deplyed and installed using the instructins in 3.3 Agent Key Files n page 12. 3. Finally, BSIDAPI.dll depends n the.net Framewrk versin 2.0, Micrsft Visual C++ 2008 Redistributable Package and CryptCOM.dll. Fr best results, deply CryptCOM.dll t the System32 flder. Specificatin Overview 13