.Net Strong Authentication API

Transcription

1 .Net Strng Authenticatin API fr Pwerful Authenticatin Management fr Service Prviders and Enterprises Authenticatin Service Delivery Made EASY

2 Micrsft Windws Lgn with BlackShield Cpyright Cpyright 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 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

3 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: Fax: supprt@cryptcard.cm Nrth America March Rad, Kanata, Ontari, Canada K2K 2E4 Phne: Fax: supprt@cryptcard.cm Fr infrmatin abut btaining a supprt cntract, see ur Supprt Web page at Overview 3

4 Micrsft Windws Lgn with BlackShield Authenticatin Service Delivery Platfrm Cmpatibility Publicatin Histry Date Changes Versin Dcument created Cpyright dates updated Minr updates 1.2 4

5 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

6 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

7 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

8 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

9 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: , 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 , and the BlackShield agent wuld display Please respnd t the challenge: Specificatin Overview 9

10 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

11 Micrsft Windws Lgn with BlackShield NOTE: Please see the lcalizatin nte in sectin 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

12 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

13 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 Finally, BSIDAPI.dll depends n the.net Framewrk versin 2.0, Micrsft Visual C Redistributable Package and CryptCOM.dll. Fr best results, deply CryptCOM.dll t the System32 flder. Specificatin Overview 13