213. EPMO Open Source Coordination Office Redaction File Detail Report

Produced by Araxis Merge on 5/25/2018 9:22:54 AM Central Daylight Time. See www.araxis.com for information about Merge. This report uses XHTML and CSS2, and is best viewed with a modern standards-compliant browser. For optimum results when printing this report, use landscape orientation and enable printing of background images and colours in your browser.

213.1 Files compared

#	Location	File	Last Modified
1	C:\AraxisMergeCompare\Pri_un\ZIP\DSM-cif\Direct_API\application\views\api\onboarding\services	messages.php	Tue May 22 13:19:28 2018 UTC
2	C:\AraxisMergeCompare\Pri_re\ZIP\DSM-cif\Direct_API\application\views\api\onboarding\services	messages.php	Thu May 24 22:19:34 2018 UTC

213.2 Comparison summary

Description	Between Files 1 and 2
Description	Text Blocks	Lines
Unchanged	5	294
Changed	4	10
Inserted	0	0
Removed	0	0

213.3 Comparison options

Whitespace
Character case	Differences in character case are significant
Line endings	Differences in line endings (`CR` and `LF` characters) are ignored
CR/LF characters	Not shown in the comparison detail

213.4 Active regular expressions

No regular expressions were active.

213.5 Comparison detail

	1	<?php
	2	/**
	3	* @package direct-as -a-service
	4	* @subpack age views
	5	* @fileso urce
	6	/ /* */
	7
	8	$t his->load- >view('api /header');
	9	$t his->load- >view('api /nav');
	10	?>
	11	<h1><a h ref="/onbo arding/doc umentation /" class=" underline" >Documenta tion</a> & rarr; /dir ect/messag es - GET</ h1>
	12	<p>The m essage web service a llows auth orized app lications to retriev e and sear ch message s and can be accesse d by sendi ng a GET r equest to /direct/me ssages.</p >
	13	<h3>Auth entication </h3>
	14	<p>
	15	The API au thenticati on utilize d is based upon hash message a uthenticat ion code ( HMAC). HMA C is an au thenticati on method that combi nes a cryp tographic hash funct ion with a secret cr yptographi c key. Aft er the suc cessful re gistration of an app lication o n the API, a public and privat e key like the examp le below w ill be pro visioned f or its use .
	16	</p>
	17	<p class ="code">
	18	Public Key : REDACTED
	19	<br/>Priva te Key: RE DACTED
	20	</p>
	21	<p>
	22	On every r equest tha t an appli cation sen ds to the API they m ust includ e an Autho rization h eader. The authoriza tion heade r is a str ing that t he API wil l utilize to confirm the ident ity, and t he message content, of the sen der. The a uthorizati on header consists o f three pa rts. The f irst part is the API identifie r, represe nted by th e word "DA AS", which stands fo r Direct a s a Servic e. The API identifie r is follo wed by a s pace that separates it from th e identify ing conten t. The ide ntifying c ontent con sists of t he unique public key and the b ase64 enco ded HMAC h ash genera ted by the request c ontent and the priva te key, de limited by a colon. An example of the au thorizatio n header i s below.
	23	</p>
	24	<p class ="code">
	25	Authorizat ion: DAAS REDACTED
	26	</p>
	27	<p>
	28	The HMAC s tring is g enerated b y running an HMAC ha sh functio n on a pla in text st ring and t he applica tion's pri vate key. The plain text strin g that mus t be hashe d using HM AC is cons tructed as follows:
	29	<ul>
	30	<l i>HTTP Req uest Type< /li>
	31	<l i>Date</li >
	32	<l i>Content- MD5 (Optio nal)</li>
	33	<l i>URI</li>
	34	</ul>
	35	These valu es are sep arated by new line c haracters ("\n"). An example o f the plai n text str ing is bel ow:
	36	</p>
	37	<p class ="code">
	38	GET\n06/03 /2013 12:1 3:56 EST\n iB94gawbwU SiZy5FuruI OQ==\n/dir ect/messag es/format/ json?mailb ox=1
	39	</p>
	40	<p>
	41	The string above is hashed wit h the appl ication's private ke y using th e SHA-256 algorithm. A snippet of JavaSc ript code showing an example o f this is shown belo w:
	42	</p>
	43	<p class ="code">
	44	var hashSt ring = Cry ptoJS.Hmac SHA256("GE T\n06/03/2 013 12:13: 56 EDT\niB 94gawbwUSi Zy5FuruIOQ ==\n/direc t/messages /format/js on?mailbox =1"," REDACTED ");
	45	<br/>var b ase64 = en code64(""+ hashString );
	46	<br/>var a uthorizati on = "DAAS REDACTED :"+base64;
	47	</p>
	48	<p>
	49	In the exa mple above the Conte nt MD5 is provided b ut this is an option al field. If the Con tent MD5 h eader is n ot specifi ed then th e hash sho uld not ha ve the MD5 specified either.
	50	</p>
	51	<h3>Head ers</h3>
	52	<div cla ss="column ">
	53	<div class ="left">
	54	<u l>
	55	<li> Authorizat ion</li>
	56	<p>
	57	The fi rst requir ed header is the Aut horization header co vered in t he Authent ication se ction at t he top of this page.
	58	</p>
	59	<li> Date or X- Daas-Date< /li>
	60	<p>
	61	The se cond requi red header that must be includ ed is the Date heade r. Some br owsers wil l not let an applica tion speci fy the Dat e header p rogrammati cally, so in this ca se it is a lso accept able to us e the X-Da as-Date he ader as th e API will interpret them inte rchangeabl y. This he ader shoul d be popul ated with the curren t date and time, in any standa rd format (including time zone informati on if not time zone agnostic), when the GET reques t is submi tted. The value supp lied in th e Date hea der must m atch the v alue used in the cre ation of t he hash st ring for t he Authori zation hea der.
	62	</p>
	63	</ ul>
	64	</div>
	65	<div class ="right">
	66	<u l>
	67	<li> Content-Md 5</li>
	68	<p>
	69	The op tional hea der is the Content-M d5 header. This head er should contain an MD5 hash of the GET query str ing. If th is header is specifi ed then it must also be includ ed in the hash strin g for the authorizat ion header . This ext ra securit y measure is not typ ically nec essary for GET reque sts, howev er the opt ion is ava ilable so that the p arameters sent in th e GET requ est can be validated by the AP I as not h aving been tampered with in tr ansit.
	70	</p>
	71	</ ul>
	72	</div>
	73	</div>
	74	<h3>Argu ments</h3>
	75	<p>
	76	There are 10 argumen ts that ca n be sent to the mes sages web service fo r retrievi ng Direct messages.
	77	</p>
	78	<div cla ss="column ">
	79	<div class ="left">
	80	<u l>
	81	<li> Mailbox</l i>
	82	<p>
	83	This i s a requir ed field t hat identi fies which mailbox m essages sh ould be re turned fro m. This co rresponds to the loc al portion of the Di rect addre ss. For ex ample, if test.user@ <?php echo CLINICAL_ DOMAIN;?> is the Dir ect addres s the pass ed value p rovided sh ould be te st.user).
	84	</p>
	85	<li> Folder</li >
	86	<p>
	87	This i s an optio nal field that speci fies what folder the messages should be pulled fro m. This is either th e ID of a custom fol der or the following values: I nbox, Sent , Archived , Draft.
	88	</p>
	89	<li> ID</li>
	90	<p>
	91	This o ptional fi eld is use d to speci fy if you want to re turn one p articular message. T his is the ID of the message t hat you wa nt returne d.
	92	</p>
	93	<li> Mark</li>
	94	<p>
	95	This o ptional fi eld specif ies whethe r to retur n messages that are either rea d or unrea d. If you specify no thing then it return s both rea d and unre ad message s. The opt ions of th e "Mark" f unction ar e "read" a nd "unread ".
	96	</p>
	97	<li> Limit</li>
	98	<p>
	99	This o ptional fi eld specif ies how ma ny message s to retur n. If noth ing is spe cified it will retur n the API' s limit fo r the crit eria. The field is b uilt in fo r the syst em and it is specifi ed in the API consta nt MAX_MES SAGE.
	100	</p>
	101	</ ul>
	102	</div>
	103	<div class ="right">
	104	<u l>
	105	<li> Start</li>
	106	<p>
	107	This o ptional fi eld is the search of fset, gene rally used in pagina ting the r esults, an d works li ke an arra y. This is the first item to r eturn from the list (i.e. 0 st arts you a t the firs t message) .
	108	</p>
	109	<li> Part</li>
	110	<p>
	111	This o ptional fi eld specif ies which part of th e message to return. If nothin g is speci fied then it returns the full message wi th all of its parts. The optio ns for par t are: MIM E, Headers , Flags, a nd Raw_mim e.
	112	</p>
	113	<li> Filter</li >
	114	<p>
	115	This o ptional fi eld is a B ase-64 enc oded JSON array of v arious sea rch criter ia that wi ll be appl ied to the messages returned.
	116	</p>
	117	<li> Order By</ li>
	118	<p>
	119	This o ptional fi eld specif ies which field to s ort the re sponse by.
	120	</p>
	121	<li> Order</li>
	122	<p>
	123	This o ptional fi eld is eit her ASC or DESC and decides wh ich direct ion to sor t the mess ages using the colum n in the O rder By Ar gument.
	124	</p>
	125	</ ul>
	126	</div>
	127	</div>
	128	<h3>Exam ple Respon se</h3>
	129	<ul>
	130	<li>Succes s</li>
	131	<u l>
	132	<li> HTTP-200, {"request_ id":"1","m ailbox":"t auser","to tal":1,"to tal_unseen ":1,"count ":1,"ids": [181],"mai l":{"181": {"id":"181 ","sender" :"tauser@< ?php echo CLINICAL_D OMAIN;?>", "to":"taus er@<?php e cho CLINIC AL_DOMAIN; ?>, teuser @<?php ech o CLINICAL _DOMAIN;?> ","cc":nul l,"bcc":nu ll,"subjec t":"ABC123 4","timest amp":"1397 243735","s ize":"1215 ","seen":0 ,"flags":n ull,"draft ":0,"sent" :0,"archiv ed":0,"att achments": "{}","head ers":"<MIM E_HEADER>" ,"priority ":3}}}</li >
	133	</ ul>
	134	<li>Error< /li>
	135	<u l>
	136	<li> HTTP-401, {"request_ id":"2", " message": "Access De nied. Auth entication Failed."} </li>
	137	<li> HTTP-403, {"request_ id":"3","m essage":"A ccess Deni ed. Use No t Authoriz ed."}</li>
	138	<li> HTTP-403, {"request_ id":"4","m essage":"A ccess Deni ed. User N ot Authori zed."}</li >
	139	<li> HTTP-422, {"request_ id":"5","m essage":"M essage not found"}</ li>
	140	<li> HTTP-422, {"request_ id":"6","f ields":["m ailbox"]," message":" 'Mailbox' is a requi red field. "}</li>
	141	<li> HTTP-422, {"request_ id":"7","m essage":"' Mailbox' c ontains in valid inpu t","fields ":["mailbo x"]}</li>
	142	</ ul>
	143	</ul>
	144	<h3>Samp le Code</h 3>
	145	<p>
	146	The messag e web serv ice is con structed i n the same manner th at the val idate web service is . Please c lick <a hr ef="/onboa rding/docu mentation/ validate_e xample">he re</a> to be taken t o some sam ple code s nippets fo r the vali date web s ervice and use that as a basis for creat ing the me ssage call .
	147	</p>
	148	</div>
	149	<?PHP $this->loa d->view('a pi/footer' ); ?>
	150	</di v>
	151	</ body>
	152	</html>