Smarx Cloud Security (WEB API) 4.

0 White Paper
Purpose of this Solution: Online authentication for many fields of application (Premium or subscription services, updates and more), Access to content or administration panel only for authorized users Version: WEB API 4.0 Last Update: 17 July 2013 by Steffen Kaetsch Target Operating Systems: - Client: Windows 32 & 64 bit, Linux - Server with PHP, JSP or ASP.NET support Access to source code needed (of protection application) : Yes No Supported Programming Tools/Environment: PHP, JSP or ASP.NET Applicable for Product: CRYPTO-BOX SC / XS / Versa

Executive summary
Smarx Cloud Security (WEB API) ensures only authenticated users who are in the possession of a valid CRYPTO-BOX hardware unit connected to the computer or in the network gain access to a web portal or any kind of content distributed via the Internet/Intranet. There are many ways in which incorporating Smarx Cloud Security is smart and profitable for your business. Control that support is provided only for paying customers, allow access to content authorized only for service personnel, and much more. Smarx Cloud Security offers the following possibilities: 1. Manage access to web content with the CRYPTO-BOX 2. Updating subscriptions and licensing information stored inside the CRYPTO-BOX Smarx Cloud Security offers support for all popular web servers that support PHP, JSP or ASP.NET. The client site supports Internet Explorer, Chrome, Safari, Opera (Windows) and Firefox (Windows, Linux).

Copyright 2002, 2013 MARX CryptoTech LP

Table of Contents
1. Introduction to WEB API.................................................................................................................6 2. How does WEB API work?............................................................................................................... 7 2.1. Client side .............................................................................................................................. 7 2.1.1. Client knows PIN scenario: User Password (PIN/UPW) submission...................................8 2.1.2. Alternative scenario: Server knows PIN............................................................................8 2.2. Server side............................................................................................................................. 8 2.2.1. Server side encryption.....................................................................................................8 3. WEB API: General Requirements....................................................................................................9 3.1. Client side requirements.........................................................................................................9 3.2. Server side requirements......................................................................................................10 4. Software Components.................................................................................................................. 10 4.1. Client Component................................................................................................................. 10 4.1.1. Client Component for Microsoft Internet Explorer...........................................................11 4.1.2. Client Component for Firefox, Chrome, Safari, Opera.....................................................11 4.1.3. WEB API client setup....................................................................................................11 4.1.4. Client Diagnostic and Troubleshooting...........................................................................11 4.2. Web Server application (ASP.NET or JSP or PHP based)........................................................11 5. Developers Notes........................................................................................................................ 12 5.1. Start building a Secure Server Solution..................................................................................12 5.2. Handshake (sides authentication and verification, establishing secure connection)...............12 5.2.1. Client knows PIN scenario.............................................................................................12 5.2.2. Server knows PIN scenario............................................................................................13 5.3. WEB API: Client-Server Communication................................................................................13 5.4. WEB API: Client-Server Communication - Notifications..........................................................15 5.4.1. Microsoft Internet Explorer............................................................................................15 5.4.2. Firefox, Chrome, Safari, and Opera................................................................................15 5.5. Web Security Client-Server communication chart..................................................................16 5.6. Server demo sample description...........................................................................................17 5.6.1. PHP demo sample module description..........................................................................18 5.6.2. Java/JSP demo sample module description...................................................................19 5.6.3. ASP.NET demo sample module description...................................................................20 5.7. Login ................................................................................................................................... 21 5.8. Verification .......................................................................................................................... 23 5.9. DataObjects transaction generation......................................................................................24 5.10. DataObjects transaction result proceeding..........................................................................25 5.11. Error handling..................................................................................................................... 25 5.11.1. Error messages generated by client.............................................................................25 5.11.2. Error messages generated by Web Security server.......................................................25 5.11.3. Errors generated by HTTP server or Tomcat................................................................25 5.12. WEB API reference documentation.....................................................................................25 5.13. Client component............................................................................................................... 26 Copyright 2002, 2013 MARX CryptoTech LP

5.14. WEB API Server Side Source Code Samples........................................................................27 5.14.1. Generated HTML code for client side...........................................................................27 5.14.2. PHP ........................................................................................................................... 28 5.14.3. Java and Java Server Pages (JSP)................................................................................28 5.14.4. ASP.NET..................................................................................................................... 29 5.14.5. Associated C# code to generate and control HTML form listed above...........................29 6. Contact and Support.................................................................................................................... 31 7. Alphabetical Index....................................................................................................................... 32

Copyright 2002, 2013 MARX CryptoTech LP

1. Introduction to WEB API

1.

Introduction to WEB API

Smarx Cloud Security (WEB API) ensures only authenticated users (who are in the possession of a valid CRYPTO-BOX) gain access to a web portal or any kind of content distributed via the Internet/Intranet. There are many ways in which incorporating Smarx Cloud Security is smart and profitable for your business. Control that support is provided only for paying customers, allow access to content authorized only for service personnel, and much more. Smarx Cloud Security offers the following possibilities: Manage access to web content with the CRYPTO-BOX This scenario is useful if you want to allow authorized users to view content only. When accessing the website it will look for a valid CRYPTO-BOX, depending on the status it will allow or deny access to the site.Furthermore, the content of the clients CRYPTO-BOX can be used by Web applications (PHP-, JSP-, or ASP.NET-based) for making decision on providing access to various services to the client. Updating the CRYPTO-BOX Smarx Cloud Security can also be used for secure transfer of information to the client's CRYPTO-BOX, and to update the CRYPTO-BOX. Unlike the Remote Update Management System (RUMS, part of the CRYPTO-BOX Protection Kit) there is no need to (manually) send the activation keys. Furthermore, with Online License Management defined update plans can be easily created via the Smarx Application Framework. Smarx Cloud Security offers support for all popular web servers that support PHP, JSP or ASP.NET. The client site supports Internet Explorer, Chrome, Safari, Opera (Windows) and Firefox (Windows, Linux). WEB API version 4.0 is based on Smarx OS, so its compatible with other Smarx OS programming interfaces and applications. Smarx OS base functionality is used by WEB API for: Establishing secure connection; Client authentication and transactions encryption; Reliable transaction mechanism, based on Smarx OS Data Objects (DO) API; Web Security Client shares Smarx OS SSO (Single Sign On) environment For more details about Smarx OS, please refer to the see Smarx Compendium, chapter 10-13.

WEB API Reference July 2013

Copyright 2002, 2013 MARX CryptoTech LP

2. How does WEB API work?

2.

How does WEB API work?

2.1. Client side

WEB API contains two components: clients component (end-user side) and web server component (server side). The client component is used to access the CRYPTO-BOX connected either to the local USB port of the computer or in the network (using CBIOS Network Server). It is implemented as a COM object for Microsoft Internet Explorer and as a plug-in for Mozilla Firefox, Google Chrome, Safari and Opera. The component receives requests (encrypted transactions) from HTML/JavaScript pages, generated by the remote server and downloaded by clients browser. Requests are processed by clients component and encrypted result of the transaction is sent back to the server. Every Smarx OS formatted CRYPTO-BOX contains client's private RSA key and distributor's public RSA keys, which are used for the handshake - establishing secure connection and client authentication. In case of the CRYPTO-BOX SC all RSA operations are done in the hardware on the client site. In addition to hardware-implemented 128 bit Rijndael encryption, and software (Open SSL) 256 bit AES encryption are used to secure client-server communication. For more details about Web Security client-server handshake scenario, see chapter 5.2: Handshake (sides authentication and verification, establishing secure connection) . Smarx Cloud Security (WEB API) version 4.0 supports two basic scenarios: 1) Client knows PIN: this scenario is common for various security applications, it assumes that the client side must provide the token (CRYPTO-BOX SC, XS or Versa) and enter valid PIN in order to open the token for further server side access - two factor local authentication. 2) Server knows PIN: this scenario is specific for online distribution and license management, client side authentication is not important here. For this scenario the client side is only supposed to attach the valid token, while the server will open it remotely (by submitting valid PIN) for further access to token's secure data objects. For software distribution and license management the Server knows PIN scenario has to be used, because exposing the PIN (User Password UPW) of the CRYPTO-BOX to the user is not desired in that case.

WEB API Reference July 2013

Copyright 2002, 2013 MARX CryptoTech LP

2. How does WEB API work?

2.1.1. Client knows PIN scenario: User Password (PIN/UPW) submission

Local two-factor authentication requires CRYPTO-BOX User Password (PIN/UPW) to be submitted by the client. Further server side authentication (involving RSA encryption/decryption) proceeds after the password is submitted.

2.1.2. Alternative scenario: Server knows PIN

This scenario is used mostly for web based distribution and license management, where client side authentication is not important. The alternative handshake scenario requires a CRYPTO-BOX XS or Versa with firmware 2.2 and higher, or a CRYPTO-BOX SC.

2.2. Server side

Smarx Cloud Security server side is supported for different environments: PHP (can be deployed on any server platform with PHP support: Win/FreeBSD/Linux, etc.); ASP.NET technology (requires Win platform + IIS); Java/JSP (can be deployed on any server platform with Java/JSP support: Win32/FreeBSD/Linux/Sun Solaris, etc.); NOTE: WEB API 4.0 is currently supported for PHP server environment only. WEB API 2.0 is available for ASP.NET and JSP/Java environments - support of WEB API 4.0 for these environments is under development. For ASP.NET solution Windows is needed with IIS 6.0 or higher. For Java/JSP solution Jakarta Tomcat v4.1 or later is needed on server side. Various development tools, like Borland JBuilder can be used for server-side development. For PHP solution, PHP 5.04 or later must be installed together with the following encryption libraries: php5-gmp, php5-mcrypt, php5-session for FreeBSD/Linux; mcrypt.dll, bcmath.dll for Win32;

2.2.1. Server side encryption

Server side encryption required by Web Security includes: 1024 bit RSA, 128 bit AES (hardware-based Rijndael encryption with the CRYPTO-BOX) and 256 bit AES (Open SSL).

WEB API Reference July 2013

Copyright 2002, 2013 MARX CryptoTech LP

2. How does WEB API work?

WEB API (Smarx Cloud Security) general architecture

3.

WEB API: General Requirements

This section describes the requirements for client and server side.

3.1. Client side requirements

Hardware: Smarx OS formatted CRYPTO-BOX SC, XS or Versa, CRYPTO-BOX firmware 2.2 or higher is requires for Server knows PIN login scenario); Driver: CRYPTO-BOX driver must be installed for CRYPTO-BOX access on the client site (this driver is included to WEB API client setup or can be installed directly with CBUSetup or Windows Update); NOTE: Driver is not required on local computer in case of network access Client component - installed via WEB API client setup (see chapter 4.1.3) or Google Play (Chrome only): o o SMRXWEB COM-object for Microsoft Internet Explorer; npWebSec plug-in for FireFox, Chrome, Safari and Opera;

WEB API Reference July 2013

Copyright 2002, 2013 MARX CryptoTech LP

3. WEB API: General Requirements Single Sign On environment (for Client knows PIN scenario, optional);

10

Operation System/Browser: o Windows (32 and 64bit): Microsoft Internet Explorer 7 or higher, Firefox 3.6 or higher; up-to-date versions of Chrome, Safari, Opera o o Linux: Firefox Mac OS X: Safari (currently under development)

3.2. Server side requirements

Application: Customized Web application (PHP, Java/JSP or ASP.NET based) Web Server with PHP support: o OS: Windows, Linux, FreeBSD or any other PHP enabled system o Apache, Xitami, IIS, PWS, ... o PHP 5.04 or later o Encryption libraries (php5-gmp, php5-mcrypt, php5-session for FreeBSD/Linux; mcrypt.dll, bcmath.dll for Win32 Web Server with ASP.NET support: o OS: Windows 8/7/Vista/XP/Server 2008 o IIS 6.0 or higher Web Server with JSP support: o OS: Windows, Linux, FreeBSD or any other JSP/Java enabled system o Apache, IIS, o Jakarta Tomcat v4.1 or later o Java JDK v1.4.2 or later o Unlimited Strength Java(TM) Cryptography Extension (JCE) Policy Files for the Java(TM) 2 SDK, Standard Edition, v 1.4.2 (J2SDK).

4.

Software Components

4.1. Client Component

Depending on the browser used client component can be either COM-object (when using Microsoft Internet Explorer) or dynamic library plug-in when usinh Firefox, Chrome, Safari, or Opera. It provides direct access to the CRYPTO-BOX from the browser. Requests generated on the server side are encrypted and MIME-encoded, embedded into HTML/JavaScript page. They will be sent to the client's browser, where they are decrypted and executed by the WEB API client component. Transaction results are encrypted, MIME-encoded and sent back to the server.

WEB API Reference July 2013

Copyright 2002, 2013 MARX CryptoTech LP

4. Software Components

11

4.1.1. Client Component for Microsoft Internet Explorer

Consists of client side COM-object (SMRXWEB.EXE) and helper dynamic library (SMRXWEBNOTIFY.dll).

4.1.2. Client Component for Firefox, Chrome, Safari, Opera

Consists of Firebreath plug-in (npWebSec.DLL).

4.1.3. WEB API client setup

The easiest way to install the client component is to use the WEB API client setup. It installs the CRYPTO-BOX drivers for Windows 32/64 and the WEB API client component, depending on the installed browser type (COM object for Internet Explorer or plug-in for Firefox, Chrome, Opera and Safari). The latest version of the WEB API client setup can be found on our website: www.marx.com Support Downloads Driver and Diagnostic Tools.

4.1.4. Client Diagnostic and Troubleshooting

You can use MARX Analyzer diagnostics as well as Web API online diagnostic to check/troubleshoot your client configuration. MARX Analyzer can be downloaded from our website: www.marx.com Support Downloads Driver and Diagnostic Tools. For WEB API online diagnostic please visit: www.marx.com/webapi-check.

4.2. Web Server application (ASP.NET or JSP or PHP based)

The server side application, loads the Distributor Private RSA key and Client Public RSA key from binary profile files, obtained from MARX. Client Private RSA key and Distributor Public RSA key are pre-programmed to the CRYPTO-BOX by MARX at the production stage. The usage of these RSA key-pairs (unique for each MARX customer) allows client side CRYPTOBOX authentication (proving that this CRYPTO-BOX belongs to the customer) and to organize encryption/decryption of commands. All sensitive information have to be stored securely on server-side in the private area. After successful authentication, a session-unique 128-bit AES Rijndael key is generated randomly and programmed into the CRYPTO-BOX unit of the client. All further commands (transactions requests and results) are encrypted/decrypted with transaction-unique 256-bit AES Rijndael key. This key in turn is transferred, being encrypted with hardware 128-bit AES Rijndael key, stored in the CYPTO-BOX of the client and known to the server site.
WEB API Reference July 2013 Copyright 2002, 2013 MARX CryptoTech LP

5. Developers Notes

12

5.

Developers Notes

5.1. Start building a Secure Server Solution

This section describes steps of your own Web Security solution development. What do you need for this? Server and client requirements are described in the section 3. The client side components and WEB API client setup setup were already described in section 4.1. The end-user management (user profiles) and server side development will be described in further sections of this document.

5.2. Handshake (sides authentication and verification, establishing secure connection)

5.2.1. Client knows PIN scenario
For the Client knows PIN scenario client-server authentication is performed using the Distributor's and Client's RSA key pairs (1024 bit strength), so that both sides are considered to be trusted. If the CRYPTO-BOX SC model is used, all RSA operations are hardware implemented which increases security on the client side. When loading the login page, the Server generates a random SessionID. This SessionID is sent to the Client, encrypted with the clients RSA public key (known to distributors side) and digitally signed by the distributors RSA private key. Only having a CRYPTO-BOX unit with valid RSA keys (Clients private and Distributors public), the SessionID can be successfully decrypted by the Client side. During this process both sides (Client and Server) are verified. After that, a random Session Key value (128-bit Rijndael key) is generated on the Client side and submitted to the CRYPTO-BOX. The CRYPTO-BOX token S/N, (optionally model, memory size, etc) is encrypted with this Session Key and the Session Key itself is encrypted with Distributors RSA public key and digitally signed with Clients RSA private key. This package is sent back to the server. Only trusted server side can decrypt the Session Key and obtain the CRYPTO-BOX information. Finally, both sides are considered as verified and trusted and ready for secure communication. For further secure transactions the Session Key (known to both sides) is used for encryption and SessionID is sent unencrypted.

WEB API Reference July 2013

Copyright 2002, 2013 MARX CryptoTech LP

5. Developers Notes

13

5.2.2. Server knows PIN scenario

The alternative handshake scenario (Server knows PIN) is a little bit different. In addition to Distributor/Clients RSA key pairs, Server side also knows the hardware Fixed Key (128-bit Rijndael key), CRYPTO-BOX User Password (PIN) and/or Administrative Password (APW). Those values are provided by MARX in binary files. If you did not receive the binary files for your CRYPTO-BOX required for the Server knows PIN scenario, please contact MARX to obtain them. The end-user (client), accessing web login page, does not require to submit the PIN value. Instead the Server sends SessionID and PIN/APW, encrypted with the hardware Fixed Key. Only having a proper CRYPTO-BOX attached, the PIN can be decrypted and used for further CRYPTO-BOX access, including RSA key pairs verification. After that, a random Session Key value (128-bit Rijndael key) is generated on the client side and submitted to the CRYPTO-BOX. The CRYPTO-BOX S/N, (optionally model, memory size, etc) is encrypted with this session key and the session key itself is encrypted with Distributors RSA public key and digitally signed with Clients RSA private key. This package is sent back to the server.

5.3. WEB API: Client-Server Communication

After a secure connection is established, the server side can submit encrypted requests to be processed by the client side: get/update information in the internal memory of the CRYPTOBOX . The results of the request are encrypted and returned to the server. WEB API is based on Smarx OS Data Objects API. Every request contains the following data fields: App ID (partition number #999 is used for online demo); Memory zone (RAM1/RAM2/RAM3); Administrator Password (reserved for future customer specific implementations); Memory Offset Data Object Type (Expiration Date, Counter, Memory Object, etc...) Data Object Size (for Memory Object) Data Object Action Extra Parameters (reserved)

Each transaction request is encrypted with randomly generated Transaction Key (256 bit AES). The Transaction Key in turn is encrypted with the Session Key (obtained during clientserver handshake and valid for all transactions of current session). On the client side transaction request is decrypted using hardware Session Key and then software Transaction Key. After this, the request is executed. The result of the transaction
WEB API Reference July 2013 Copyright 2002, 2013 MARX CryptoTech LP

5. Developers Notes

14

and/or the error code is encrypted with a newly generated Transaction Key, which is encrypted in turn with the Session Key and the result of transaction is sent back to the server. The transaction result is decrypted on the server side and used for further server side processing. Executing Data Object command (by the client) implies forming request and analyzing result (returned by the client) by the server side code. Forming request consists of calling the following sequence of methods on PHP/JSP/ASP.NET page: 1. call Command constructor; 2. submit DO transaction by calling submitDOCommand(Command command) 3. commit DO transaction by calling commitDOCommand() There are two constructors used to initialize DO command:
public Command(short int int int int int int sPartitionId, // application partition Id iDOId, // Data Object Id iDOType, // Data Object type iDOOperation, // Data Object operation iRAM an!, // RAM ban! (RAM" # ", RAM$ # $, RAM% # %& iO''set, // o''set in application partition iReser(ed&) // reser(ed

and:
public Command(short sPartitionId, // application partition Id int iDOId, // Data Object Id int iDOType, // Data Object type int iDOOperation,// Data Object operation int iRAM an!, // RAM ban! (RAM" # ", RAM$ # $, RAM% # %& int iO''set, // o''set in application partition byte *+bDOData, // Data Object data int iDO,i-e, // Data Object data si-e int iReser(ed&) // reser(ed

First is used to form most of the DO commands, the second to form DO commands performing reading/writing to/from the internal CRYPTO-BOX memory. For detailed information on Data Objects API, please refer to the Smarx Compendium, chapter 13 and the DO API Reference. To analyze DO command results returned by the client the: proceedExecuteResults(String executeResult, ArrayWraper result) is called on the next PHP/JSP/ASP.NET page. Where: executeResult MIME string returned by the client; result wrapped byte array returned by the client (if data is returned).
WEB API Reference July 2013 Copyright 2002, 2013 MARX CryptoTech LP

5. Developers Notes If the method returns non-zero, error took place during DO command execution. Error code can be further analyzed by calling getErrorMessage(int errCode).

15

5.4. WEB API: Client-Server Communication - Notifications

To receive notifications on CRYPTO-BOX attachment/detachment the following technique can be used.

5.4.1. Microsoft Internet Explorer

Notifications can be handled with WSNOTIFIER (SMRXWEBNOTIFY.dll) object implemented by the following code:
.O /0CT ID#12,3OTI4I0R1 C5A,,ID#1C5,ID678$ 8 49:;C8%:9A7%: D;9:" 9 <%$A;D%;1/=

The following API calls can be used to enable notifications:

2,3OTI4I0R>attach0(ent(1 o?Attached1,handlerA&) 2,3OTI4I0R>attach0(ent(1 o?Remo(ed1,handlerR&)

where handlerA, handlerR javascript handler-functions describing attachment/detachment reaction. Example:

.script lan@ua@e#1ja(ascript1= 'unction handlerR(& A alert(1Bour CRBPTO: OC is remo(edD Please, attach CRBPTO: OC>1&) E i'(na(i@ator>app3ame>substrin@(;,F& ## GMicroso'tG& A document>Hrite(G.O /0CT ID#12,3OTI4I0R1 C5A,,ID#1C5,ID678$ 8 49:;C8%:9A7%: D;9:" 9 <%$A;D%;1=./O /0CT=G&) 2,3OTI4I0R>attach0(ent(1 o?Remo(ed1, handlerR&) E ./script=

5.4.2. Firefox, Chrome, Safari, and Opera

The following API calls can be used to enable notifications:
20 ,0C>add0(ent5istener(G o?Remo(edG,IandleR,true&) 20 ,0C>add0(ent5istener(G o?AttachedG,IandleA,true&)

where IandleA, IandleR javascript handler-functions describing attachment/detachment reaction (and 20 ,0C is plugin object). Example:
.script lan@ua@e#1ja(ascript1= 'unction handlerR(& A alert(1Bour CRBPTO: OC is remo(edD Please, attach the CRBPTO: OC>1&) E
WEB API Reference July 2013 Copyright 2002, 2013 MARX CryptoTech LP

5. Developers Notes
i'(na(i@ator>app3ame>substrin@(;,7& ## G3etscapeG& A 20 ,0C>add0(ent5istener(1 o?Remo(ed1, handlerR, true&) E ./script=

16

5.5. Web Security Client-Server communication chart

Client side (C +("O-,O-)
Get PIN (UPW)

SmarxOS Cloud Security Client-Server Communication Chart

Server side
Generate SessionID Encrypt SessionID Di'ita$$y si'n

SessionID % uni#ue Session ID& 'enerated on ser(er side for furt!er reco'nition of t!is session transactions Session 'ey % )*+ bit ,ES-"i.ndae$ key& 'enerated on c$ient side and submitted into t!e /rypToken for !ard are encryption& (a$id for t!is session (a$$ its transactions) "ransaction 'ey % *01 bit ,ES-"i.ndae$ key& 'enerated for soft are encryption& (a$id for encryptin'-decryptin' of transaction2s re#uest or resu$t packa'e3 Server side
Prepare "e#uest Generate Transaction Key

Handshake Header (SessionID) public

S! "oken si#ned $%Distributor&s private S!

Client side (C +("O-,O-)

"ransaction Header SessionID ("ransaction 'ey) Session 'ey ( e*uest) "ransaction 'ey Proceed "e#uest Generate ne Transaction Key

4erify si'nature Decrypt SessionID Generate Session Key Submit Session Key Encrypt Token Info Encrypt Session Key Di'ita$$y si'n Handshake Header SessionID (Session 'ey) (ublic
S! Distr

Encrypt "e#uest Encrypt Transaction Key

Encrypt Transaction "esu$ts "ransaction Header SessionID ("ransaction'ey) Session'ey ("ransaction esult) "ransaction'ey Decrypt TransactionKey Decrypt Transaction "esu$t Decrypt Token Info
Session ID is associated it! current session

Encrypt Transaction Key

("oken In)o) Session'ey

si#ned $%Client&s private S!

4erify si'nature Decrypt Session Key

Proceed Transaction "esu$t

/opyri'!t 5 *66*&*6)7 8,"9: /ryptoTec! ;P

Smarx Cloud Security (WEB API) Client-Server communication chart for Client knows PIN scenario

WEB API Reference July 2013

Copyright 2002, 2013 MARX CryptoTech LP

5. Developers Notes
Server side (kno$s (I/)
(Alternative handshake)
Handshake Header (0(1 % !(1) .ixed 'ey (SessionID) .ixed 'ey
si#ned $%Distributor&s private S!

17

SmarxOS Cloud Security Client-Server Communication Chart

SessionID % uni#ue Session ID& 'enerated on ser(er side for furt!er reco'nition of t!is session transactions .ixed 'ey % )*+ bit ,ES-"i.ndae$ key& pro'rammed in /"<PT=%>=9 and kno n to ser(er%side& used for secure UPW-,PW transmission durin' !ands!ake Session 'ey % )*+ bit ,ES-"i.ndae$ key& 'enerated on c$ient side and submitted into t!e /"<PT=%>=9 for !ard are encryption& (a$id for t!is session (a$$ its transactions) "ransaction 'ey % *01 bit ,ES-"i.ndae$ key& 'enerated for soft are encryption& (a$id for encryptin'-decryptin' of transaction2s re#uest or resu$t packa'e3 Server side
Prepare "e#uest Generate Transaction Key Encrypt "e#uest Encrypt Transaction Key Proceed "e#uest

Generate SessionID Encrypt UPW-,PW Encrypt SessionID Di'ita$$y si'n

Client side (C +("O-,O-)

Decrypt UPW-,PW Submit UPW-,PW 4erify si'nature Decrypt SessionID Generate Session Key Submit Session Key Encrypt Token Info Encrypt Session Key Di'ita$$y si'n Handshake Header SessionID (Session 'ey) (ublic
si#ned $%Client&s private S! Distr

Client side (C +("O-,O-)

"ransaction Header SessionID ("ransaction 'ey) Session 'ey ( e*uest) "ransaction 'ey

Generate ne

Transaction Key

Encrypt Transaction "esu$ts Encrypt Transaction Key

"ransaction Header SessionID ("ransaction'ey) Session'ey ("ransaction esult) "ransaction'ey

("oken In)o) Session'ey

S!

4erify si'nature Decrypt Session Key

Decrypt TransactionKey Decrypt Transaction "esu$t

Decrypt Token Info

Session ID is associated it! current session

Proceed Transaction "esu$t

/opyri'!t 5 *66*&*6)7 8,"9: /ryptoTec! ;P

Smarx Cloud Security (WEB API) Client-Server communication chart for Server knows PIN scenario Files, containing Distributor RSA Private key and Client RSA Public Key for the Demo CRYPTO-BOX (part of the CRYPTO-BOX Evaluation Kit) are included to the sample code and can be used for testing (sample.d.prv.bin and sample.c.pub.bin). Key files for customer specific CRYPTO-BOX units will be provided when buying WEB API.

5.6. Server demo sample description

The data exchange between server and client is performed the following way: The server generates pages, with client component calls, embedded into JavaScript. The encrypted transaction string, transformed into MIME64 format is transmitted as parameter for component functions. The result of client execution is also an encrypted string, which is sent to the server as form field value, using POST method. Below is a description of the modules contained in the different samples available for the server site (PHP, JSP, ASP.NET).

WEB API Reference July 2013

Copyright 2002, 2013 MARX CryptoTech LP

5. Developers Notes

18

5.6.1. PHP demo sample module description

PHP classes: WebSec.php AuthStr.php BCMath.php GMP.php Command.php Constants.php CryptParam.php - WebSec main class. - authorization string class. (is used to handle authorization) - provides set of math functions, which are used by RSA.php under Win32 platform - provides set of math functions, which are used by RSA.php under FreeBSD platform - Data Object Command class. (describes Data Object operation to be performed) - constants class - cryptographic parameters loader (loads RSA keys)

DOCommandResults.php - Data Object command result class. (proceeds results of Data Object operation returned by client) DOCreateTransactStr.php - exception class JSTag.php Rijndael.php RSA.php StringHeader.php Token.php Tools.php TransactStr.php WrongPwdLength.php - class is used to generate client side JavaScript code - CRYPTO-BOX compatible Rijndael implementation - CRYPTO-BOX compatible RSA implementation - common header used to wrap/unwrap authorization and transaction string - contains information on current Token - used to perform data conversions - class is used to securely wrap/unwrap DO operation data - exception class

Sample: activation.php bindingResult.php footer.php header.php how_to_use.php index.php

WEB API Reference July 2013

- activates CRYPTO-BOX previously bound to client's computer - displays binding results - contains copyright information - contains WEB API online demo tabs - contains instructions on sample evaluation scenario - startup file of the online demo ("Client knows PIN" scenario).
Copyright 2002, 2013 MARX CryptoTech LP

5. Developers Notes texteditor.php

19

- displays Text editor demo application (example for an application which can be used only if a valid CRYPTO-BOX is attached to the client's computer).

texteditor_read_only.php - displays Text editor in read-only mode transaction.php - displays transaction results, read from the client's CRYPTO-BOX: 1. 2. 3. verifyresult.php Displays full information about the client, Shows the number of visits Displays the last visit date and time (including time zone)

- validates the handshake results. In case of successful validation it prepares further sample transactions: 1. 2. 3. 4. 5. Get client info Increment visit counter Get the counter value Get last visit date Update the last visit date

websechelp.html jquery-1.5.2.min.js notifications.js

- help file with brief info about the WEB API Online Demo - JavaScript library - checks CRYPTO-BOX presence after log process. In case the CRYPTO-BOX was removed, it processes an auto-logout

The sample demonstrates the following steps of client authentication, transaction: [hardware selection] login client and binding details (verifyresult, transaction) Furthermore, the sample demonstrates the following features: ajax web development techniques network or local hardware selection, including support for FEST (allows testing of core features of the CRYPTO-BOX system without the need to a physical CRYPTO-BOX ideal for immediate testing) license management via WEB API (including binding & activation)

The brief functionality and design of each page is described starting with chapter 5.7. See WEB API reference documentation (contained in the /doc subfolder of the WEB API package) for a detailed description of the PHP classes.

5.6.2. Java/JSP demo sample module description

Java packages: com.marx.jsmrxweb
WEB API Reference July 2013

- basic WebSec.class
Copyright 2002, 2013 MARX CryptoTech LP

5. Developers Notes com.marx.jsmrxweb.crypt com.marx.jsmrxweb.exception com.marx.jsmrxweb.Script - encryption algorithms - exceptions - HTML/JavaScript tags generation

20

com.marx.jsmrxweb.transaction - transaction generation/processing com.marx.jsmrxweb.util org.bouncycastle.crypto org.bouncycastle.util.encoders - service classes - encryption algorithms** - service classes**

** - some modified and original encryption services, developed by The Legion Of The Bouncy Castle (www.bouncycastle.org) are used. Sample: login.jsp verifyresult.jsp transaction.jsp securityviolation.jsp servererror.jsp - login page - CRYPTO-BOX verification page - transactions page (client info) - transaction exception page - server error page

The sample demonstrates the following steps of client authentication, transaction: login.jsp verifyresult.jsp transaction.jsp If a transaction error occurs, it is processed on servererror.jsp page. The brief functionality and design of each page is described starting with chapter 5.7. See WEB API reference documentation (contained in the /doc subfolder of the WEB API package) for detailed description of Java packages/classes.

5.6.3. ASP.NET demo sample module description

\WebSec.sln \Web.config 1. WebSec project \WebSec\*.* \WebSec\bin\*.* \WebSec\classes\ *.*
WEB API Reference July 2013

- Smarx Cloud Security ASP.NET solution - Web configuration

- Smarx Cloud Security sample files - Dll files - Smarx Cloud Security ASP.NET classes
Copyright 2002, 2013 MARX CryptoTech LP

5. Developers Notes \WebSec\data\ *.* \WebSec\netsetup\*.* \WebSec\pics\*.* - RSA demo key files - ASP.NET client diagnostic files - sample images files

21

2. WebSec.Cryptography project \WebSec.Cryptography\*.* \WebSec.Cryptography\bin\*.* - Smarx Cloud Security Cryptography files - Dll files

\WebSec.Cryptography\RSA\*.* - Dll files The sample demonstrates the following steps of client authentication, transaction: Login.aspx VerifyResult.aspx Transaction.aspx The brief functionality and design of each page is described starting with chapter 5.7. See WEB API reference documentation (contained in the /doc subfolder of the WEB API package) for detailed description of the ASP.NET solution.

5.7. Login
The login page is the start page of the sample. It is generated by the server-side, using com>mar?>jsmr?Heb>2eb,ec class functions: @etITM5Ieader(&, @etMo-illaCode(&, @etIandsha!eCode(&, @etIidePHd0ntry(&, @etIandsha!e,ubmit utton(& (see WEB API reference documentation package for details). On this page client needs to submit password (if it was not submitted before). There should be input fields on this form holding client command execution results to be sent back to the server.
.'orm name#G'orm"G method#GpostG action#G(eri'yresult>jspG= .input type#GpassHordG name#GpassHordG (alue#GdemoG=

The password value is obtained from this input field. The handshake code getting information about the CRYPTO-BOX, attached to the client computer and doing CRYPTO-BOX verification is also embedded. The results of the handshake process are sent to the server.
.input type#GhiddenG name#G20 ,0CIandsha!eResultG (alue#G:G= .input type#GsubmitG name#GHebsecsubmitG (alue#G5o@inG onClic!#1 return doIandsha!e(this>'orm&)1= .script lan@ua@e#1ja(ascript1= 'unction doIandsha!e('rm& A i'(20 ,0C##null& A i'(na(i@ator>app3ame>substrin@(;,F& ## GMicroso'tG& A
WEB API Reference July 2013 Copyright 2002, 2013 MARX CryptoTech LP

5. Developers Notes
alert(G,MRC20 return 'alse) Acti(eC is not installed DG&)

22

E else i'(na(i@ator>app3ame>substrin@(;,7& ## G3etscapeG&A alert(G20 API compatible broHser plu@in is 3OT installedDG&) return 'alse) E E else A i' (20 ,0C>is,,OInstalled(&&A (ar ret # 20 ,0C>,,O5o@in(&) i' (ret ## ;?;8& Aalert(G3o CRBPTO: OCJ Has detected> KnPlease attach (alid CRBPTO: OCJ and try a@ainG&) return 'alse)E else i' (ret ## ;?;A& Aalert(GThis CRBPTO: OCJ is not supported> KnPlease attach (alid CRBPTO: OCJ and try a@ainG&) return 'alse)E else i' (ret ## ;?;F& Aalert(GDetected CRBPTO: OCJ is not 'ormatted> KnPlease attach (alid CRBPTO: OCJ and try a@ainG&) return 'alse)E else i' (ret ## ;?; & Aalert(GDetected CRBPTO: OCJ does not contain (alid partition> KnPlease attach (alid CRBPTO: OCJ and try a@ainG&) return 'alse)E else i' ((ret D# ;?;9& LL (ret D# ;?;M& LL (ret D# ;&& alert(G0rror lo@on to CRBPTO: OCJ> KnPlease try a@ain> KnContact your (endor i' problem persistsG&) i' (ret D# ;& return 'alse) E elseA (ar ret # 20 ,0C>2eb5o@in('rm>passHord>(alue&) i' (ret ## ;?$;;;"& alert(G3o CRBPTO: OCJ Has detected> KnPlease attach CRBPTO: OCJ and try a@ainG&) else i' (ret ## ;?$;;;%& alert(GThis CRBPTO: OCJ is not supported> KnPlease attach (alid CRBPTO: OCJ and try a@ainG&) else i' (ret ## ;?$;;;9& alert(GDetected CRBPTO: OCJ is not 'ormatted> KnPlease attach (alid CRBPTO: OCJ and try a@ainG&) else i' (ret ## ;?$;;;<& alert(GDetected CRBPTO: OCJ does not contain (alid partition> KnPlease attach (alid CRBPTO: OCJ and try a@ainG&) else i' (ret ## ;?$;;;7& alert(GBou ha(e entered Hron@ passHord> KnPlease try a@ainG&) else i' (ret D# ;& alert(G0rror lo@on to CRBPTO: OCJ> KnPlease try a@ain> KnContact your (endor i' problem persistsG&) i' (ret D# ;& return 'alse) E 'rm>20 ,0CIandsha!eResult>(alue # 20 ,0C>Iandsha!e(1A@0AAAAA0A0AAA " Ir 9N3uc?C28o@MOeAp@jae 8@(P!us0!%F%9jA QAAAIAAAADR<$/',3mSsC;-0IplIQlsbHic"c?cN h8lAMTjb,?RbCo!ORhBI3snRlMa<SRPS5Pj9NMQFehA8lri7rI8RA4Or@Q8OPFiO40R$SC5r%59@/euR8 riQTbTCm(o-yhPR!IQO(; ;T'<jdp?0/3N@Rlr<ub-5TiHT ?8pbTDiH'<u AAAACAAAAAT5aO!mm!Qp0 PU4,H'Cr5"QtT$5C"/AM7(cT%MHM4!OsojSc<U/Di(I-0uT8D-Pe4lRch3?8Ob4-ST?9R?lH4omSheO N e2uAyC7OnyCQ@IN"rQMhnP(ONb"?PjH('S/UAhu$CCm?4t7N0yM2CNBRjDp$3-Os4j;s3AH5/RocQ4M#1 &) E E ./script=

After the Login button is clicked, the handshake code is executed and the handshake result ('orm>20 ,0CIandsha!eResult& is sent to the server. The server receives and processes this data. If the CRYPTO-BOX was successfully verified the verification page is generated.

WEB API Reference July 2013

Copyright 2002, 2013 MARX CryptoTech LP

5. Developers Notes

23

For the demo sample, each demo-formatted CRYPTO-BOX matches (sample files contain demo values of Distributor RSA Private Key and Client RSA Public Key, used for verification). However in your own solution its a good idea to limit number of matching units with unique criteria, for instance the serial number of the CRYPTO-BOX. In this case verification can only be continued if the end-user has a CRYPTO-BOX with the proper Serial Number (this information has to be stored on the server side).

5.8. Verification
Verification page contains information about the CRYPTO-BOX, found on client-side and result of its verification. Handshake results are preceded, using com>mar?>jsmr?Heb>2eb,ec class function: proceedIandsha!eResults(& (see WEB API reference documentation for details).
.VW pa@e errorPa@e#Gser(ererror>jspG import#Gcom>mar?>jsmr?Heb>transaction>Command, com>mar?>jsmr?Heb>util>X, com>mar?>jsmr?Heb>e?ception>DOCreateTransact,trGV= .V // lo@out / restart i' needed i'((reNuest>@etParameter(GcancelG& D# null& Y (reNuest>@etParameter(Glo@outG& D # null&& A Hebsec # null) session>in(alidate(&) response>sendRedirect(Glo@in>jspG&) E // @o to error pa@e i' cbHeb bean does not e?ist i'(Hebsec ## null& A V= .jsp6'orHard pa@e#Gser(ererror>jspG= .jsp6param name#Gmessa@eG (alue#G2eb,ec bean is nullDG /= ./jsp6'orHard= .V E // handle security (iolations i'(Hebsec>@et,tate(& . Hebsec>,TAT0ZT0RI4BR0,P5T& A Hebsec>set,tate(Hebsec>,TAT0Z5OSI3&) V= .jsp6'orHard pa@e#Gsecurity(iolation>jspG= .jsp6param name#GerrorG (alue#Gin(alid sessionG /= .jsp6param name#GdescriptionG (alue#GAll sta@es o' lo@in and authentication must be passed 'rom the be@innin@>.br=Please note that a'ter a certain time o' inacti(ity, a time out occures and the session becomes in(alid>G /= ./jsp6'orHard= .V E ,trin@ handsha!eResults # reNuest>@etParameter(G20 ,0CIandsha!eResultG&) int r # Hebsec>proceedIandsha!eResults(handsha!eResults&) i'(r D# ;&A Hebsec>set,tate(Hebsec>,TAT0Z5OSI3&) V= .jsp6'orHard pa@e#Gsecurity(iolation>jspG= .jsp6param name#GerrorG (alue#G(ari'ication 'ailedG /= .jsp6param name#GdescriptionG (alue#GPser Has not authenticatedG /= ./jsp6'orHard=
WEB API Reference July 2013 Copyright 2002, 2013 MARX CryptoTech LP

5. Developers Notes
.V E // set bean to the ne?t state Hebsec>set,tate(Hebsec>,TAT0ZTRA3,ACTIO3&) Hebsec>setTeri'ied(true&) V=

24

If the CRYPTO-BOX was verified successfully, server and client sides are ready to execute memory transactions. However client can break connection by clicking the Logout button, and return to the start page. If none of the attached CRYPTO-BOX units was verified (encryption key pairs dont match), a page with an error message is generated, informing that client was not verified. If client was not verified, all further work with the CRYPTO-BOX is terminated.

5.9. DataObjects transaction generation

Scripts necessary for CRYPTO-BOX DataObjects transactions are only generated after successful CRYPTO-BOX verification. com>mar?>jsmr?Heb>transaction>Command class and the following functions of com>mar?>jsmr?Heb>2eb,ec class are used on server side for page generation:
submitDOCommand(&, commitDOTransact(&, @etTransaction o?,ubmit utton(&3 .'orm name#G'orm"G method#GpostG action#Gtransaction>jspG= .input type#GhiddenG name#G20 ,0C0?ecuteResultG (alue#G:G= .input type#GsubmitG name#GHebsecsubmitG (alue#GClient detailsG onClic!#1 return doTransaction(this>'orm&)1= .script lan@ua@e#1ja(ascript1= 'unction doTransaction('rm& A i'(20 ,0C##null& A i'(na(i@ator>app3ame>substrin@(;,F& ## GMicroso'tG& A alert(G,MRC20 Acti(eC is not installed DG&) return 'alse) E else i'(na(i@ator>app3ame>substrin@(;,7& ## G3etscapeG&A alert(G20 API compatible broHser plu@in is 3OT installed DG&) return 'alse) E E else A 'rm>20 ,0C0?ecuteResult>(alue # 20 ,0C>0?ecute(1A@IAAAAA0Q0AAAA t!m7nyR$ ?tr-48R7umd%eeN;u@IjI7?ppa<Nma;B QAAASRueIRM0AAAACAAAAAHAAAAyRP,DH""PD3o ONcoe7p"0/5,Bm@aFDutUONSD%QdTPMIsC;ORt'uH9'9cT$ulmP!0AAAAIAAAA 'SP(I-8o5e@(TM/u/P jsS7FuBABoIi3;O,str8uetiyPt$A IC/4/s?43 CQH-aa/-,d,ms%??h2?0(r<A5N@d7!HOoMiuiPoU( dnAsP7i</! p@oP5Om0lc/-8;5Pj'on@Q(%AN7<M7<OddPC jQmC-3ooB%Rd;;QlMRP@/PC!AAAADeF?t /2i,iP<3hpI--,'QMSRoQoC'sNti/3P"BCT(7uOnRh'4-!R@?AUI2UbI;hyUlBm;;3SOj9RR/HcCUAyQj 1&) E E ./script=

WEB API Reference July 2013

Copyright 2002, 2013 MARX CryptoTech LP

5. Developers Notes The result of transaction execution is sent back to the server with the 'orm>20 ,0C0?ecuteResult field.

25

5.10. DataObjects transaction result proceeding

The transaction page is generated as the result of transaction execution on client side. @etITM5Ieader(&, @etMo-illaCode(& and proceed0?ecuteResults functions of com>mar?>jsmr?Heb>2eb,ec class are used on server side for page generation see WEB API reference documentation package for details.

5.11. Error handling

Java and JSP mechanisms are used to control errors on server side. Here is a list of the most probable errors and how they are handled:

5.11.1. Error messages generated by client

The result of transaction contains an error code, if an error occurs on the client side. The return code can be used with the getErrorMessage() method to get an error description. It is a customers decision how to handle erroneous situation either the last page should be generated again or any other steps should be taken (i.e. to alert the system administrator, to lock the account, to redirect the client to the NetSetup or drivers update page, ..). Some errors should be processed locally on client-side, displaying alert messages (for example check if compatible CRYPTO-BOX is attached, etc)

5.11.2. Error messages generated by Web Security server

In case of erroneous situation on the server side, the server will log all the errors to stderr using System.err.println(). If there are some problems with the server part of this solution, look through the log files of Tomcat.

5.11.3. Errors generated by HTTP server or Tomcat

There is always the possibility that errors occur on JSP server level. If problems persist even after a server restart, it is recommended to check the server configuration files (server.xml for Tomcat) and to monitor the log files of Tomcat and the HTTP server.

5.12. WEB API reference documentation

Please refer to the JavaDoc-generated WEB API reference documentation package, which reflects the most up-to-date Java classes (see /doc subfolder in the WEB API package).

WEB API Reference July 2013

Copyright 2002, 2013 MARX CryptoTech LP

5. Developers Notes

26

5.13. Client component

The client component comes both as ActiveX COM object (for Internet Explorer) and as plug-in (for Chrome, Firefox, Safari, Opera) see chapter 4.1 for more details. This component performs client side operations and is called from JavaScript code on JSP pages. It contains the following methods:
IR0,P5T Handshake(*in+ ,TR Command, *out, ret(al+ ,TRX Result&)

Method accomplishes initial handshake. Input parameter - MIME string sent by the server. Output parameter - resulting MIME string, sent by the client to the server. Compatibility - used for both scenarios (client knows PIN; server knows PIN)
IR0,P5T Execute(*in+

Method accomplishes Data Object transaction. Input parameter - MIME string sent by the server. Output parameter - resulting MIME string, sent by the client to the server. Compatibility - used for both scenarios (client knows PIN; server knows PIN)
IR0,P5T isSSOInstalled(*out, ret(al+ TARIA3TZ OO5X 'Result&)

,TR Command, *out, ret(al+

,TRX Result&)

Method determines if SSO is installed. Compatibility - used only for scenario client knows PIN
IR0,P5T SSOLogin(*out, ret(al+ 5O3SX lResult&)

Method realizes client login by means of SSO. Compatibility - used only for scenario client knows PIN
IR0,P5T WebLogin(*in+

Method realizes client login by standard means. Compatibility - used only for scenario client knows PIN

,TR PP2, *out, ret(al+ 5O3SX lResult&)

IR0,P5T GetCTFirmware(*out, ret(al+ 5O3SX 'Result&)

Method determines the firmware version of the attached CRYPTO-BOX Compatibility - used only for scenario server knows PIN (firmware v2.2 and higher is needed)
IR0,P5T GetVersion(*out, ret(al+ ,TR XTersion&)

Method returns client components version. Compatibility - used for both scenarios (client knows PIN; server knows PIN)
IR0,P5T Logout((oid&)

Method realizes client components logout. Compatibility - used for both scenarios (client knows PIN; server knows PIN)
IR0,P5T ,earch o?es(*in+ ,TR Command,*in+ ,TR PP2, *out, ret(al+ ,TRX Result&)

Method searches local computer or network for available CRYPTO-BOX units specified by Command (in human-readable format, i.e.
WEB API Reference July 2013 Copyright 2002, 2013 MARX CryptoTech LP

5. Developers Notes "search=network,connect=broadcast,broadcastport=8766") . Result lists what was found, UPW is optional (makes sense only for client knows PIN scenario).
IR0,P5T ,et o?(*in+

27

Same as ,earch o?es except that only one CRYPTO-BOX (first-best) will be chosen for further work.

,TR Command,*in+

,TR PP2, *out, ret(al+

,TRX Result&)

5.14. WEB API Server Side Source Code Samples

5.14.1. Generated HTML code for client side
The following sample is a fragment of HTML page generated by the WEB API server to be received and processed by the client's browser:
.script lan@ua@e#[ja(ascript[= 'unction doIandsha!e('rm& A i'(20 ,0C##null& A alert(G,MRC20 is not installed DG&) return 'alse) E else A i' (20 ,0C>is,,OInstalled(&&A //,,O detection // per'orm auto lo@in in case i' ,,O is installed (ar ret # 20 ,0C>,,O5o@in(&) i' (ret ## ;?;8& Aalert(G3o CRBPTO: OCJ is detected> KnPlease, attach a (alid CRBPTO: OCJ and try a@ainG&) return 'alse)E ////////////////////////////////////////////////// /// \ more error processin@ code \ /// /////////////////////////////////////////////////// i' (ret D# ;& return 'alse) E elseA // Pse manually entered passHord to per'orm lo@in (ar ret # 20 ,0C>2eb5o@in('rm>passHord>(alue&) i' (ret ## ;?$;;;"& alert(G3o CRBPTO: OCJ is detected> KnPlease, attach a (alid CRBPTO: OCJ and try a@ainG&) ////////////////////////////////////////////////// /// \ more error processin@ code \ /// /////////////////////////////////////////////////// i' (ret D# ;& return 'alse) E // proceed Hith handsha!e command and paste results into // a special hidden 'ield ]20 ,0CIandsha!eResult[ 'rm>20 ,0CIandsha!eResult>(alue # 20 ,0C>Iandsha!e(1A@0AAAAA0A0AAA "Ir 9N3uc?C28o@MOeAp@jae 8@(P!us0!%F%9jA QAAAIA AAADR<$/',3mSsC;-0IplIQlsbHic"c?cNh8lAMTjb,?RbCo!ORhBI3snRlMa<SRPS5Pj9NMQFehA8lri 7rI8RA4Or@Q8OPFiO40R$SC5r%59@/euR8riQTbTCm(o-yhPR!IQO(; ;T'<jdp?0/3N@Rlr<ub-5TiHT ?8pbTDiH'<u AAAACAAAAAT5aO!mm!Qp0PU4,H'Cr5"QtT$5C"/AM7(cT%MHM4!OsojSc<U/Di(I-0uT 8D-Pe4lRch3?8Ob4-ST?9R?lH4omSheO Ne2uAyC7OnyCQ@IN"rQMhnP(ONb"?PjH('S/UAhu$CCm?4t7 N0yM2CNBRjDp$3-Os4j;s3AH5/RocQ4M#1&) E E ./script=
WEB API Reference July 2013 Copyright 2002, 2013 MARX CryptoTech LP

5. Developers Notes

28

.'orm name#G'orm"G method#GpostG action#G2eb4orm">asp?G= // action# ^\_ depends on the ser(er plat'orm6 // 2eb4orm">asp?/2eb4orm">jsp/2eb4orm">php Input passHord .input type#GpassHordG name#GpassHordG (alue#GdemoG= .input type#GhiddenG name#G20 ,0CIandsha!eResultG (alue#G:G= .input type#GsubmitG name#GHebsecsubmitG (alue#G5o@inG onClic!#1 return doIandsha!e(this>'orm&)1= ./'orm=

5.14.2. PHP
HTML form/template code for CRYPTO-BOX validation and server/client handshake:
// XXXXXXX 20 ,0C : include 2eb,ec XXXXXXX .`php includeZonce(^2eb,ec>php_&)`= .`php // ,ome code Hhich pro(ide lo@out/restart i' needed // create 2eb,ec instance i' needed i'(aHebsec ## null& aHebsec # neH 2eb,ec(&) // set the instance to the ne?t state aHebsec:=set,tate(aHebsec:=,TAT0ZT0RI4BR0,P5T&) aHebsec:=setTeri'ied('alse&) `= .html= .head= // 2eb,ec : insert header .`php print(aHebsec:=@etITM5Ieader(&&) `= ./head= .body b@color#Gb0M0 0 G te?t#Gb;;8AA;G= // 20 ,0C : insert the /a(a,cript Iandsha!e code in the pa@e .`php print(aHebsec:=@etIandsha!eCode(&&) `= .'orm name#G'orm"G method#GpostG action#G(eri'yresult>jspG= Input passHord .input type#GpassHordG name#GpassHordG (alue#GdemoG= // disable passHord entry 'ield i' ,,O is installed .`php print(aHebsec:=@etIidePHd0ntry(G'orm"G, GpassHordG&&) `= // 20 ,0C : place the submit:button here .`php print(aHebsec:=@etIandsha!e,ubmit utton(G5o@inG&&) `= ./'orm= ./body= ./html=

5.14.3. Java and Java Server Pages (JSP)

HTML form/template code for CRYPTO-BOX validation and server/client handshake:
.V:: XXXXXXX 20 ,0C : include 2eb,ec XXXXXXX ::V= .jsp6use ean id#GHebsecG scope#GsessionG class#Gcom>mar?>jsmr?Heb>2eb,ecG /= .V:: lo@out/restart i' needed ::V=

WEB API Reference July 2013

Copyright 2002, 2013 MARX CryptoTech LP

5. Developers Notes
.L:: @enerate 2eb,ec bean i' needed ::V= I' (Hebsec ## null& Hebsec # neH com>mar?>jsmr?Heb>2eb,ec(&) .V:: set bean to the ne?t state ::V= Hebsec>set,tate(Hebsec>,TAT0ZT0RI4BR0,P5T&) Hebsec>setTeri'ied('alse&) V= .html= .head= .V:: XXXXXXX 2eb,ec : insert header XXXXXXX ::V= .V out>print(Hebsec>@etITM5Ieader(&&) V= ./head= .body b@color#Gb0M0 0 G te?t#Gb;;8AA;G= .V:: XXX 20 ,0C : insert the /a(a,cript Iandsha!e code in the pa@e XXX ::V= .V out>print(Hebsec>@etIandsha!eCode(&&) V=

29

.'orm name#G'orm"G method#GpostG action#G(eri'yresult>jspG= Input passHord .input type#GpassHordG name#GpassHordG (alue#GdemoG= .V:: XXX 20 ,0C : disable passHord entry 'ield i' ,,O is installed XXX ::V= .V out>print(Hebsec>@etIidePHd0ntry(G'orm"G, GpassHordG&&) V= .V:: XXXXXXX 20 ,0C : place the submit:button here XXXXXXX ::V= .V out>print(Hebsec>@etIandsha!e,ubmit utton(G5o@inG&&) V= ./'orm= ./body= ./html=

5.14.4. ASP.NET
HTML form/template code for CRYPTO-BOX validation and server/client handshake:
.html= .head= // A,P labels are used here to insert // client side /a(a,cript code .asp6label id#G/a(a,criptIeaderG runat#Gser(erG= .asp6label id#G/a(a,criptIandsha!eCodeG runat#Gser(erG= .asp6label id#G/a(a,criptDisableP2DG runat#Gser(erG= ./head= ./html= .body= .4ORM id#G4orm"G method#GpostG runat#Gser(erG = // A,P labels are used here to insert // hidden 'ield and ^,ubmit_ button .asp6te?tbo? id#GTe?t o?"G runat#Gser(erG=./asp6te?tbo?= .asp6label id#GIandsha!e,ubmit uttonG runat#Gser(erG= ./4ORM= ./body=

5.14.5. Associated C# code to generate and control HTML form listed above
usin@ ,ystem) usin@ ,ystem>Collections) // \ de'ine more aliases 'or namespaces here
WEB API Reference July 2013 Copyright 2002, 2013 MARX CryptoTech LP

5. Developers Notes
namespace 2ebApplication" A public class 2eb4orm" 6 ,ystem>2eb>PI>Pa@e A protected ,ystem>2eb>PI>2ebControls> utton utton") protected ,ystem>2eb>PI>ItmlControls>Itml4orm 4orm") protected ,ystem>2eb>PI>2ebControls>Te?t o? Te?t o?")

30

pri(ate (oid Pa@eZ5oad(object sender, ,ystem>0(entAr@s e& A i' (this>IsPost ac!& A ,er(er>Trans'er (G2eb4orm$>asp?G, true&) // a'ter ITM5 'orm submit He ma!e a trans'er to 2eb4orm$>asp? // Hhich proceed recei(ed data E else A // create 2eb,ec instance i' needed i'(Hebsec ## null& A Hebsec # neH 2eb,ec(&) E Hebsec>set,tate(Hebsec>,TAT0ZT0RI4BR0,P5T&) Hebsec>setTeri'ied('alse&) // insert client side /a(a,cript code /a(a,criptIeader>Te?t#Hebsec>@etITM5Ieader(&) /a(a,criptIandsha!eCode>Te?t# Hebsec>@etIandsha!eCode(&) /a(a,criptDisableP2D>Te?t# Hebsec>@etIidePHd0ntry (G4orm"G, G Te?t o?"G&) Iandsha!e,ubmit utton>Te?t# Hebsec>@etIandsha!e,ubmit utton(G5o@inG&) E E o(erride protected (oid OnInit(0(entAr@s e& A // More code @enerated by T,>30T code desi@ner\ E E E

WEB API Reference July 2013

Copyright 2002, 2013 MARX CryptoTech LP

6. Contact and Support

31

6.

Contact and Support

Sales: Support: Phone: Fax: E-Mail: [email protected] [email protected] (+1) 770-904-0369 (+1) 678-730-1804 [email protected]

USA MARX CryptoTech LP 3355 Annandale Lane, Suite 2 Suwanee, GA 30024 USA www.marx.com Germany MARX Software Security GmbH Vohburger Str. 68 D-85104 Wackerstein Germany www.marx.com Italy CS Computers S.r.l. Via Indipendenza, 4-12 I-47033 Cattolica (FO) Italia www.cscomputers.it Poland BCSG Sp. z o.o. ul. Lubeckiego 16 60-348 Poznan Poland www.bcsg.pl

Sales: Support: Phone: Fax: E-Mail:

[email protected] [email protected] +49 (0) 8403 9295-0 +49 (0) 8403 1500 [email protected]

Contact: Phone: Fax: E-Mail:

Giorgio del Bene +39 0 541/963-801 +39 0 541/953-847 [email protected]

Contact: Phone: E-Mail:

Rafa Krlak +48 667 633 915 [email protected]

WEB API Reference July 2013

Copyright 2002, 2013 MARX CryptoTech LP

6. Contact and Support

32

7.

Alphabetical Index
L Linux 8 Login 19 M Mac OS X 8 MARX Analyzer 9 O Opera 8 P PHP 4, 26 PIN 5 R Remote Update 4 S Safari 8 Server knows PIN 5, 11 SessionID 10 Support 29 U User Password (UPW) 5 V Verification 21 W WEB API Client Component 8 WEB API reference 24 Windows 8
0-15Mar013ks(WEB_API_Reference).odt

A AES Rijndael encryption 9 Apache 8 ASP.NET 4, 18, 27 C Chrome 8 Client component 24 Client knows PIN 5, 10 Contact Information 29 Counter 11 D Data Objects (DO) API 11 Diagnostic 9 E Error handling 23 Expiration Date 11 F Firefox 8 FreeBSD 8 H Handshake 10 I IIS 8 Internet Explorer 8 J Java Server Pages 4, 17, 26

WEB API Reference July 2013

Copyright 2002, 2013 MARX CryptoTech LP