Step-by-step guide

Login to the Atrium SDK

Fetch temporary session key
Method	GET
URL	/login_sdk.xml
Data request	None
Data answer	XML answer to Login GET <LOGIN_SDK> <SDK_CFG user_id="-1" username="" lang=""/> <DEVICE serial="0A221037" product="A22M" mdl_label="A22 [2-Door Controller]" version="4.-1.0070"/> <CONNECTION timeout="900" session="ABED141026D7F6BC" err="ok" lock="0"/> </LOGIN_SDK> Use the session id ("LOGIN_SDK"→"CONNECTION"→"session") and the target serial number to generate the Session Key that will be used to encrypt the login request (POST) and any further communication with the embedded SDK. Login request parameters var sessionKey = md5(LOGIN_SDK.DEVICE.serial + LOGIN_SDK.CONNECTION.session); Backup the Session Key as it will be used to encrypt/decrypt any further communications with the SDK.
Source	https://bitbucket.org/team_mrd/d004_atrium_sdk_web/src/master/app/components/sdk/demo/login/sdk.demo.login.ctrl.js

Login to the Atrium SDK

Method

POST

URL

/login_sdk.xml

Data request

Login request parameters

var sessionKey = md5(LOGIN_SDK.DEVICE.serial + LOGIN_SDK.CONNECTION.session);
var data =
{
	sid: LOGIN_SDK.CONNECTION.session,
	cmd: "login",
    login_user: rc4(sessionKey, user_login_username),
    login_pass: md5(sessionKey + user_login_password)
}

Login request example

sid=ABED141026D7F6BC&cmd=login&login_user=84CB7FC2D8&login_pass=E0C122491A8785F7FE1A978222FF623C

Parameters description
Name	Type	Description
sid	hexadecimal string	LOGIN_SDK.CONNECTION.session
cmd	string	Command to execute in this request: "login" "logout"
login_user	hexadecimal string	Username of the user login (i.e.: "admin") encrypted using RC4 and the login session key
login_pass	hexadecimal string	MD5 of concatenation of the login session key and the password of the user login (i.e.: "admin").

Data answer

XML Answer to Login request

<LOGIN_SDK>
	<SDK_CFG user_id="0" username="admin" lang="0"/>
	<DEVICE serial="0A221037" product="A22M" mdl_label="A22 [2-Door Controller]" version="4.-1.0070"/>
	<CONNECTION timeout="900" session="86B4EDCFF6CBEACE" err="ok" lock="0"/>
</LOGIN_SDK>

Validate the login result "err". It should indicate "ok".

Backup the session as it will be used to identify the session for any further communications with the SDK.

Parameters description
Group	Name	Type	Description
<SDK_CFG>	user_id	integer	Id of the current user in the user list (-1 = unknown user)
	username	string	Username of the current user login
	lang	integer	Language id (0 = english)
<DEVICE>	serial	hexadecimal string	Username of the user login (i.e.: "admin") encrypted using RC4 and the temporary login session key
	product	string	Marketing name of the product
	mdl_label	string	Editable module label
	version	string	Version.revision.build of the product
<CONNECTION>	timeout	integer	Timeout of the session in seconds. Default = 900 seconds (15 minutes)
	session	hexadecimal string	Session id
	err	integer	Result of the connection request should be validated by the application. "ok" means succeed to login. Any other messages indicate errors in login.
	lock	integer	Indicate if the current session is temporarily locked due to too many bad login attempts. (0 = not locked; 1 = locked)

Source

https://bitbucket.org/team_mrd/d004_atrium_sdk_web/src/master/app/components/sdk/demo/login/sdk.demo.login.ctrl.js

Exchange encrypted data with the Atrium SDK

Exchange data with the Atrium SDK

Method

POST

URL

/sdk.xml

Data request

Original XML Request before encryption

<?xml version="1.0" encoding="utf-8"?>
<SDK xmlns='https://www.cdvi.ca/'>
    <RECORDS>
        <REC trans_id='693' cmd='read' sernum='0A221037' type='card' id='0' rec='cfg'>
            <DATA obj_status='' valid='' label3='' dword4='' hexv5='' hexv6='' byte8='' bit11='' bit20='' utc_time25=''/>
        </REC>
    </RECORDS>
</SDK>

XML Request - Encryption parameters

{
	sid:	  LOGIN_SDK.CONNECTION.session,
	post_enc: rc4(sessionKey, originalXmlData),
	post_chk: postChkCalc(originalXmlData)
}

XML Request after encryption

"sid=86B4EDCFF6CBEACE&post_enc=41DE3D0726FF54BE5C57118BDAC543137742ACD2D800DDAB6CB2E2F01CAFF1E6057A8575FECEFE619767876744FEA4EEBC5286478DA973920F88BDA03F326B
 6D3ECA2DB1C49D210BD3515EE39DE7E930F13D521C46DEAA98EF7EFF490A56C95E89D41B0A723D612B45D0E2AC88DFA4649E651AA39E3DA72FB92F2E084521E4A4F8FB5
 2248A8958CA3761A3BBE8A9CBB85A88EDF0D90657809735670C81628E6115C7329744FE9F46D6496AB67C25C80CC87310E48E989FD75B152B8692A0282A01D7F72D5E71
 CA26F3768538989E99795F3EA0344674384B2CF139C0EF583C4E6C6EF204CFEBD5F1740BE4A33C7C7F1272DFC9330FCD31F8B136D46EF75D266BCD9DA502E97C1A70112
 0BBBB8110EDE79590870B73E8B40DDA5B1DE10A10D3B2D73D&post_chk=56FD"

XML Request Parameters description
Name	Type	Description
sid	heaxdecimal string	LOGIN_SDK.CONNECTION.session
post_enc	hexadecimal string	Original XML data encrypted using RC4 and the user session key
post_chk	hexadecimal string	Checksum of the original XML data. Will be used by the Atrium SDK to validate the integrity of the data after decryption.

Data answer

Encrypted XML Answer example

"post_enc=41DE3D0726FF54BE5C57118BDAC543137742ACD2D800DDAB6CB2E2F01CAFF1E6057A8575FECEFE619767876744FEA4EEBC5786478DA973920F88BDA03F326B
 6D3ECA2DB1C49D2415D13F49E591FAFF279C3F3C0B40BDFE9EFC71E2653C5B90449DDB111E707E6F221CCAB2BB8CDAE766CD730DBF8525F735AB5E5D084620E7A0E8F90
 629839C00D07663B0ADABAB82AE02CCE0F59A1255C18A606119DB67DF3673A658EA20D0A96DA9487BA43572D45ACD7459F6D2D6C691465162D2C3E37B6D4D8BA8602622
 DA30E871923187CCCD3C5379F8341225760831BB6D9AB91C6E54697EB25DCBFC82B8364FB0FC77386C0323998C76019778E8CB649B27F76C3D6DB4CAFF56B73D0F2E577
 5F0A79D5BC8CDA4CA8F19039ED562E07A36A90302A2C6AC338364174BC864689C9CDAB5A0035ABC0C56521A8BE25CF572107EF02CCD009DF57BD81874468A3F34B116E8
 0F2F85AF63DCEF59863F4EFF11859F8452890FA67FC5CED9A3F4FBD4E7B919219FCB1C9AFA198C83838F6B9DD8DC60DC0CDC426E4BC3A886E5&post_chk=71BB"

XML Answer Parameters description
Name	Type	Description
post_enc	hexadecimal string	Atrium SDK XML data to decrypt using RC4 and the user session key
post_chk	hexadecimal string	Checksum of the Atrium SDK XML data used to validate the integrity of the data after decryption.

Decryption function

var decryptXml = function(xmlData){
	var postEnc = "post_enc=";
    var IdxEnc = xmlData.search(postEnc);									// Search for string "post_enc="
    if (IdxEnc >= 0){														// If string "post_enc=" found
    	IdxEnc = IdxEnc + postEnc.length;									// Set index of the data start
        var postChk = "&post_chk=";
        var IdxChk = xmlData.search(postChk);								// Search for string "&post_chk="
        if (IdxChk >= 0){													// If string "&post_chk=" found
        	var chkSumPost = xmlData.substr(IdxChk + postChk.length);		// Extract the checksum value
            xmlData = xmlData.substr(IdxEnc, (IdxChk - IdxEnc));			// Extract the data part
            if (getSetSessionKey() !== null) {
            	xmlData = rc4Decrypt(getSetSessionKey(), xmlData);			// Decrypt the data
                var chkSumCalc = postChkCalc(xmlData);						// Compute the checksum on the decrypted data
                chkSumCalc = parseInt(chkSumCalc, 16);						// Keep only the 16 lowest bits of the checksum 
                chkSumCalc &= 65535;
                chkSumPost = parseInt(chkSumPost, 16);
				if (chkSumPost == chkSumCalc){								// Compare received checksum with computed checksum to validate decrypted data integrity
                	return xmlData;
            	}
        	}
        }
    	return null;
    }
	return xmlData;
}

Atrium SDK XML Answer after decryption

<?xml version="1.0" encoding="utf-8"?>
<SDK xmlns='https://www.cdvi.ca/'>
    <RECORDS>
        <REC trans_id='693' cmd='read' sernum='0A221037' type='card' rec='cfg' res='ok'>
            <DATA res='ok' id='0' cnt='1' obj_status='used' valid='1' ro='0' protect='0' label3='John Doe&apos;s card' dword4='3' 
                  hexv5='00013A1C' hexv6='00000000' byte8='0' bit11='1' bit20='0' utc_time25='FFFFFFFF'/>
        </REC>
    </RECORDS>
</SDK>

Source

https://bitbucket.org/team_mrd/d004_atrium_sdk_web/src/master/app/components/sdk/xml.svc.js

Understanding XML data structure

To understand the XML data structure and find the available commands and options, please refer to
1. The Atrium SDK - XSD (XML data formater) explains in details every supported record types, commands, data types as well as the global XML file structure to use to communicate with the Atrium SDK.
2. The Object type documentation as part of the Atrium SDK demo software provide the different tags and data structure to use per Record type and Command for each of the different Object type.

Logout from the Atrium SDK

Logout to the Atrium SDK

Method

POST

URL

/login_sdk.xml

Data request

Logout request parameters

var data =
{
	sid: LOGIN_SDK.CONNECTION.session,
	cmd: "logout"
}

Login request example

sid=86B4EDCFF6CBEACE&cmd=logout

Parameters description

Name

Type

Description

sid

string

LOGIN_SDK.CONNECTION.session

cmd

string

Command to execute in this request:

"logout"

Data answer

XML Answer to Logout request

<LOGIN_SDK>
	<SDK_CFG user_id="-1" username="" lang=""/>
	<DEVICE serial="0A221037" product="A22M" mdl_label="A22 [2-Door Controller]" version="4.-1.0070"/>
	<CONNECTION timeout="900" session="86B4EDCFF6CBEACE" err="ok" lock="0"/>
</LOGIN_SDK>

Validate the logout result "err". It should indicate "ok".

Parameters description
Group	Name	Type	Description
<SDK_CFG>	user_id	integer	Id of the current user in the user list (-1 = unknown user)
	username	string	Username of the current user login
	lang	integer	Language id (0 = english)
<DEVICE>	serial	hexadecimal string	Username of the user login (i.e.: "admin") encrypted using RC4 and the temporary login session key
	product	string	Marketing name of the product
	mdl_label	string	Editable module label
	version	string	Version.revision.build of the product
<CONNECTION>	timeout	integer	Timeout of the session in seconds. Default = 900 seconds (15 minutes)
	session	hexadecimal string	Session id
	err	integer	Result of the disconnection request should be validated by the application. "ok" means succeed to login. Any other messages indicate errors in login.
	lock	integer	Indicate if the current session is temporarily locked due to too many bad login attempts. (0 = not locked; 1 = locked)

Source

https://bitbucket.org/team_mrd/d004_atrium_sdk_web/src/master/app/components/sdk/demo/login/sdk.demo.logout.ctrl.js

Related articles

Page:

SDK encryption functions
Page:

SDK Documentation and Demo
Page:

HOW-TO - Use the SDK demo
Page:

HOW-TO - Connect to the Atrium SDK
Page:

HOW-TO - Add license key
Page:

Atrium SDK - XSD (XML data formater)
Page:

Atrium SDK - XML data structure