Difference between revisions of "API Method DirectAddressValidate"
m (→Address-level Certificates) |
(→Address-level Certificates) |
||
Line 10: | Line 10: | ||
=== Address-level Certificates === | === Address-level Certificates === | ||
− | For a recipient Direct address of <code>DrTom@DrTomsPractice.MyEHRDirect.com</code>, the first certificate search looks for a certificate issued for the recipient address: <code>DrTom@DrTomsPractice.MyEHRDirect.com</code>. If the | + | For a recipient Direct address of <code>DrTom@DrTomsPractice.MyEHRDirect.com</code>, the first certificate search looks for a certificate issued for the recipient address: <code>DrTom@DrTomsPractice.MyEHRDirect.com</code>. If all of the following are true, then <code>/DirectAddressValidate</code> will return <code>true</code>: |
+ | * a certificate is found (either via DNS or LDAP) | ||
+ | * the found certificate has not been revoked | ||
+ | * the found certificate is trusted or is signed by a trusted TrustAnchor | ||
+ | * the found certificate is not issued by a DirectTrust TrustAnchor OR the found certificate is issued by a DirectTrust TrustAnchor and the inquiring user is a member of a vetted practice | ||
+ | |||
+ | A from <code>/DirectAddressValidate</code> of <code>true</code> does '''not''' mean that the address itself is guaranteed to exist or that messages sent to it will be picked up by the intended recipient - only that a valid, non-revoked, trusted certificate can be found for the requested address. | ||
=== Domain-level Certificates === | === Domain-level Certificates === |
Revision as of 07:47, 26 June 2014
Contents |
Description
The following code samples describe the processes involved in "validating" a Direct address and discuss what happens behind the scenes with domain-level address validation and address-level validation.
Behind the Scenes
When a call is made to /DirectAddressValidate
, a search is performed for a current, non-revoked certificate for the target Direct address. There two types of certificates to search for:
Address-level Certificates
For a recipient Direct address of DrTom@DrTomsPractice.MyEHRDirect.com
, the first certificate search looks for a certificate issued for the recipient address: DrTom@DrTomsPractice.MyEHRDirect.com
. If all of the following are true, then /DirectAddressValidate
will return true
:
- a certificate is found (either via DNS or LDAP)
- the found certificate has not been revoked
- the found certificate is trusted or is signed by a trusted TrustAnchor
- the found certificate is not issued by a DirectTrust TrustAnchor OR the found certificate is issued by a DirectTrust TrustAnchor and the inquiring user is a member of a vetted practice
A from /DirectAddressValidate
of true
does not mean that the address itself is guaranteed to exist or that messages sent to it will be picked up by the intended recipient - only that a valid, non-revoked, trusted certificate can be found for the requested address.
Domain-level Certificates
For a recipient Direct address of DrBob@DrBobsPractice.OtherEHRDirect.com
, if no trusted, non-revoked certificate can be found for the address, the next certificate search will be performed on the domain of the intended recipient: DrBobsPractice.OtherEHRDirect.com
. A Domain-level certificate is used for all users in a given domain. The same certificate will be used to sign messages from DrBob@DrBobsPractice.OtherEHRDirect.com
as will be used to sign messages from NurseRatchett@DrBobsPractice.OtherEHRDirect.com
. Since there aren't any user-specific (aka Address-specific) certificates available to be searched, the most precise anyone can be about determining if the recipient Direct-address is valid is to confirm the existence of a trusted, non-revoked certificate for the domain. Again, this does not mean that the address itself is guaranteed to exist or that messages sent to it will be picked up by the intended recipient - only that a valid, non-revoked certificate signed by a trusted agency can be found for the domain.
Prerequisites
1 This API call requires Vendor-level credentials. The credentials should be populated into the applicationId
and applicationPassword
fields of the auth
block:
{ ... "auth": { "applicationId": "vendorId", "applicationPassword": "vendorPassword", "accountId": "", "userId": "" } }
Code Samples
Language | Source Code Examples |
---|---|
C# | public void TalkToUpdox() { string json = new JavaScriptSerializer().Serialize(new { recipient = "DrTom@DrTomsPractice.MyEHRDirect.com", // required auth = new { applicationId = "vendorId", applicationPassword = "vendorPassword", accountId : "accountId", userId: "userId" } }); string url = "https://updoxqa.com/io/directAddressValidate"; SendReceiveJSON(json, url); } private void SendReceiveJSON(string json, string url) { var httpWebRequest = WebRequest.Create(url); httpWebRequest.ContentType = "application/json"; httpWebRequest.Method = "POST"; using (var streamWriter = new StreamWriter(httpWebRequest.GetRequestStream())) { streamWriter.Write(json); streamWriter.Flush(); streamWriter.Close(); var httpResponse = (HttpWebResponse) httpWebRequest.GetResponse(); using (var streamReader = new StreamReader(httpResponse.GetResponseStream())) { var result = streamReader.ReadToEnd(); } } } |
Java |
import com.fasterxml.jackson.databind.JsonNode; import com.fasterxml.jackson.databind.ObjectMapper; import org.apache.http.HttpEntity; import org.apache.http.HttpResponse; import org.apache.http.client.HttpClient; import org.apache.http.client.methods.HttpPost; import org.apache.http.entity.StringEntity; import org.apache.http.impl.client.DefaultHttpClient; import org.apache.http.util.EntityUtils; import java.util.HashMap; import java.util.Map; public class UpdoxTest { public void TalkToUpdox() throws Exception { String uri = "https://updoxqa.com/io/directAddressValidate"; ObjectMapper mapper = new ObjectMapper(); Map<String,Object> messageData = BuildMessage(); String jsonData = mapper.writeValueAsString(messageData); HttpResponse httpResponse = SendReceiveJSON(jsonData, uri); HttpEntity responseEntity = httpResponse.getEntity(); String response = EntityUtils.toString(responseEntity); JsonNode actualObj = mapper.readTree(response); System.out.println(actualObj.get("responseCode")); System.out.println(actualObj.get("responseMessage")); } private Map<String,Object> BuildMessage() throws Exception { Map<String,Object> messageData = new HashMap(); Map<String,String> authData = new HashMap(); messageData.put("recipient", "DrTom@DrTomsPractice.MyEHRDirect.com"); Map<String,Object> authData = new HashMap(); authData.put("applicationId", "vendorId"); authData.put("applicationPassword", "vendorPassword"); authData.put("accountId", "accountId"); authData.put("userId", "userId"); messageData.put("auth", authData); messageData.put("auth", authData); return messageData; } private HttpResponse SendReceiveJSON(String jsonData, String uri) throws Exception { HttpClient httpClient = new DefaultHttpClient(); HttpResponse response = null; StringEntity params = new StringEntity(jsonData); try { HttpPost request = new HttpPost(uri); request.addHeader("content-type", "application/json"); request.setEntity(params); response = httpClient.execute(request); } catch (Exception ex) { // handle exception here } finally { httpClient.getConnectionManager().shutdown(); } return response; } } |
Messages
Destination Address
Request JSON
{ "recipient": "DrTom@DrTomsPractice.MyEHRDirect.com", "auth": { "applicationId": "vendorId", "applicationPassword": "vendorPassword", "accountId": "", "userId": "" } }
HTTP Response Status
200 OK
Response JSON
{ "successful": true, "responseMessage": "OK", "responseCode": 2000, "recipient": "contact:171099", "name": "DrTom@DrTomsPractice.MyEHRDirect.com", "directAddress": "DrTom@DrTomsPractice.MyEHRDirect.com", "validDirectAddress": true, "vettingRequired": false, "reason": null }
Relevant Response Codes
In addition to the General Error Set, this method may return the following values in the responseCode
and responseMessage
fields:
responseCode
|
responseMessage
|
---|