217. 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.

217.1 Files compared

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

217.2 Comparison summary

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

217.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

217.4 Active regular expressions

No regular expressions were active.

217.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/save - POST</h1>
	12	<p>The S ave Messag e web serv ice allows authorize d applicat ions to sa ve message s as draft s and can be accesse d by sendi ng a POST request to /direct/m essages/sa ve.</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>Content Type (Not including boundary)< /li>
	34	<l i>URI</li>
	35	</ul>
	36	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:
	37	</p>
	38	<p class ="code">
	39	POST\n06/0 3/2013 12: 13:56 EST\ niB94gawbw USiZy5Furu IOQ==\nmul tipart/for m-data\n/d irect/mess ages/save/ format/jso n
	40	</p>
	41	<p>
	42	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:
	43	</p>
	44	<p class ="code">
	45	var hashSt ring = Cry ptoJS.Hmac SHA256("PO ST\n06/03/ 2013 12:13 :56 EDT\ni B94gawbwUS iZy5FuruIO Q==\nmulti part/form- data\n/dir ect/messag es/save/fo rmat/json" ," REDACTED ");
	46	<br/>var b ase64 = en code64(""+ hashString );
	47	<br/>var a uthorizati on = "DAAS REDACTED :"+base64;
	48	</p>
	49	<p>
	50	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.
	51	</p>
	52	<h3>Head ers</h3>
	53	<p>
	54	There are three head ers that m ust be sen t with eac h save cal l and one optional h eader. The se headers are used in validat ing who th e message came from, who it is going to and the me ssage itse lf.
	55	</p>
	56	<div cla ss="column ">
	57	<div class ="left">
	58	<u l>
	59	<li> Authorizat ion</li>
	60	<p>
	61	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.
	62	</p>
	63	<li> Date or X- Daas-Date< /li>
	64	<p>
	65	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 POST reque st is subm itted. The value sup plied in t he Date he ader must match the value used in the cr eation of the hash s tring for the Author ization he ader.
	66	</p>
	67	</ ul>
	68	</div>
	69	<div class ="right">
	70	<u l>
	71	<li> Content-Ty pe</li>
	72	<p>
	73	The fi nal requir ed header for POST r equests is the Conte nt-Type. T he Content -Type head er must ma tch the Co ntent-Type provided in the has h string f or the Aut horization header ex cept the h ash string does not include th e boundary parameter of the Co ntent-Type if there is one (i. e. multipa rt/form-da ta Content -Type).
	74	</p>
	75	<li> Content-Md 5</li>
	76	<p>
	77	The op tional hea der is the Content-M d5 header. This head er should contain an MD5 hash of the ent ire POST b ody. If th is header is specifi ed then it must also be includ ed in the hash strin g for the Authorizat ion header . When pro vided, thi s serves a s an extra security precaution above and beyond TL S to ensur e the POST request s ent has no t been mod ified in t ransit.
	78	</p>
	79	</ ul>
	80	</div>
	81	</div>
	82	<h3>Argu ments</h3>
	83	<p>
	84	There are 9 argument s that can be sent t o the save web servi ce.
	85	</p>
	86	<div cla ss="column ">
	87	<div class ="left">
	88	<u l>
	89	<li> Sender</li >
	90	<p>
	91	This i s a requir ed field t hat define s who the Direct mes sage comes from.
	92	</p>
	93	<li> To</li>
	94	<p>
	95	This i s a requir ed field t hat define s who the Direct mes sage will be sent to . This fie ld will ac cept comma or semi-c olon delim ited RFC82 2 addresse s. The val idate web service wi ll be run on all add resses in the "To" f ield to va lidate tha t they are trusted r ecipients before bei ng sent ou t.
	96	</p>
	97	<li> CC</li>
	98	<p>
	99	This i s an optio nal field that defin es additio nal people that will receive t he Direct message as a carbon copy. This field wil l accept c omma or se mi-colon d elimited R FC822 addr esses. The validate web servic e will be run on all addresses in the "C C" field t o validate that they are trust ed recipie nts before being sen t out.
	100	</p>
	101	<li> Mailtype</ li>
	102	<p>
	103	This i s an optio nal field and define s what for mat the Di rect messa ge body wi ll be sent in. The o ptions for this fiel d are "Tex t" for pla in text or "HTML" fo r an HTML formatted message. I f no mailt ype, or an invalid m ailtype, i s specifie d the type will defa ult to HTM L.
	104	</p>
	105	<li> Draft ID</ li>
	106	<p>
	107	This i s an optio nal field that defin es what ex isting dra ft to over write with the one p rovided. T his is use d so that the draft folder doe sn't fill up with au to-saves f or the sam e message.
	108	</p>
	109	</ ul>
	110	</div>
	111	<div class ="right">
	112	<u l>
	113	<li> Priority</ li>
	114	<p>
	115	This i s an optio nal field that defin es what pr iority the Direct me ssage will be sent w ith. The o ptions for this fiel d are the numbers 1- 5, with 1 being the highest pr iority and 5 being t he lowest. If no pri ority, or an invalid priority, is specif ied it wil l default to 3 (norm al priorit y).
	116	</p>
	117	<li> Subject</l i>
	118	<p>
	119	This i s an optio nal field that defin es what th e subject line of th e Direct m essage wil l read. If no subjec t is speci fied then (No Subjec t) will be added as the subjec t by defau lt.
	120	</p>
	121	<li> Body</li>
	122	<p>
	123	This i s an optio nal field and define s what the message b ody of the Direct me ssage will contain. If no body is specif ied a blan k body wil l be sent with the m essage.
	124	</p>
	125	<li> Files</li>
	126	<p>
	127	Option ally, a PO ST request can be se nt as mult ipart/form -data with file data . This fil e data def ines the f iles that will be at tached to the direct message. The file f ields can be passed with any P OST field name that the third- party appl ication ch ooses, the y simply m ust be inc luded in t he multipa rt data. T he total s ize of all attachmen ts must be less than 10 MB and .exe file s cannot b e attached .
	128	</p>
	129	</ ul>
	130	</div>
	131	</div>
	132	<h3>Exam ple Respon se</h3>
	133	<ul>
	134	<li>Succes s</li>
	135	<u l>
	136	<li> HTTP-200, {"request_ id":"1","m ailbox":"t auser","id ":"235","m essage":"M essage sav ed"}</li>
	137	</ ul>
	138	<li>Error< /li>
	139	<u l>
	140	<li> HTTP-401, {"request_ id":"2","m essage": " Access Den ied. Authe ntication Failed."}< /li>
	141	<li> HTTP-403, {"request_ id":"3","m essage":"A ccess Deni ed. Use No t Authoriz ed."}</li>
	142	<li> HTTP-403, {"request_ id":"4","m essage":"A ccess Deni ed. User N ot Authori zed."}</li >
	143	<li> HTTP-422, {"request_ id":"5","m essage":"M essage not found"}</ li>
	144	<li> HTTP-422, {"request_ id":"6","f ields":["m ailbox"]," message":" 'Mailbox' is a requi red field. "}</li>
	145	<li> HTTP-422, {"request_ id":"7","m essage":"' Mailbox' c ontains in valid inpu t","fields ":["mailbo x"]}</li>
	146	</ ul>
	147	</ul>
	148	<h3>Samp le Code</h 3>
	149	<p>
	150	The save w eb service is constr ucted in t he same ma nner that the send w eb service is. Pleas e click <a href="/on boarding/d ocumentati on/send_ex ample">her e</a> to b e taken to some samp le code sn ippets for the send web servic e and use that as a basis for creating t he save ca ll.
	151	</p>
	152	</div>
	153	<?PHP $this->loa d->view('a pi/footer' ); ?>
	154	</di v>
	155	</ body>
	156	</html>