DokuWiki

Site Tools

Trace: • ws_submitterrequest • ws_payloads_lock_unlock_finalize • apex_managing_roles • ws_payloads • ws_payloads_delete_payload • ws_store_checksum • ws_payloads_get_repository_file_names
guides:ws_store_checksum

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
guides:ws_store_checksum [2018/10/26 17:40] – brett.zamoraguides:ws_store_checksum [2019/06/04 23:51] (current) – brett.zamora
Line 2: Line 2:
  
  
-The StoreChecksum web service is used to store the checksum of a Base64Document string in the CeRTNA Portal.+The StoreChecksum web service is used to store the checksum value of a Base64 string contained in a CeRTNA Standard XML PRIA_DOCUMENT node. The checksum value that is passed to the StoreChecksum web service is the SHA384 calculated binary checksum that has been converted to a Base64 string.
  
 +The StoreChecksum web service, returns a checksum key. The checksum key is the value that should be stored in either the RequestChecksumValue (agents) or ResponseChecksumValue(counties) property of the PRIA_DOCUMENT node, depending on who made the StoreChecksum request.
  
 +The following sample shows the checksum key stored in PRIA_DOCUMENT node:
  
  
 +<code xml>
 +<PRIA_DOCUMENT _Code="Deed" DocumentSequenceIdentifier="1" RequestChecksumAlgorithm="SHA384" RequestChecksumValue="19AEA2BD-D793-44F0-BBA4-C7F33F0ED27A" ResponseChecksumAlgorithm="SHA384" ResponseChecksumValue="66182401-414F-4901-A212-B8AC18C3E1DE">
 +</code>
  
  
 +The checksum key is used in the ValidateChecksum web service to facilitate the process of validating a checksum value that was stored by another party.
  
-In October 2018, CeRTNA added a requirement to include a SALT value when preparing your encrypted password string. The sample code blocks included later in this page show how to obtain your SALT value and use it when encrypting your password. 
  
 <color #7092be>Request Endpoint</color> <color #7092be>Request Endpoint</color>
  
-{{tablelayout?colwidth="100px,500px"&rowsFixed=1&rowsVisible=10&float=center}}+{{tablelayout?colwidth="75px,575px"&rowsFixed=1&rowsVisible=10&float=center}}
 ^ Method ^ URL ^ ^ Method ^ URL ^
-| POST | <nowiki>https://apex-prd.certna.org/user/login</nowiki> |+| POST | <nowiki>https://apex-prd.certna.org/APEX/Service/APEXPublicServer.svc/storechecksum</nowiki> |
  
  
Line 29: Line 34:
 ^ Key ^ Value ^ ^ Key ^ Value ^
 | Content-Type | application/json | | Content-Type | application/json |
 +| access_token | {soft-token} |
  
  
Line 35: Line 41:
 {{tablelayout?colwidth="150px,75px,100px,275px"&rowsFixed=1&rowsVisible=10&float=center}} {{tablelayout?colwidth="150px,75px,100px,275px"&rowsFixed=1&rowsVisible=10&float=center}}
 ^ Parm Name ^ Req/Opt ^ Format ^ Description ^ ^ Parm Name ^ Req/Opt ^ Format ^ Description ^
-| user_name | Required | [string] | User name. | +| checksum | Required | [string] | Locally calculated binary checksum value converted to a Base64 string. |
-| password | Required | [string] | Base64 encoded SHA1 hash. See Comment 1. | +
  
 <color #7092be>JSON Response Parameters</color> <color #7092be>JSON Response Parameters</color>
Line 43: Line 47:
 {{tablelayout?colwidth="125px,100px,375px"&rowsFixed=1&rowsVisible=10&float=center}} {{tablelayout?colwidth="125px,100px,375px"&rowsFixed=1&rowsVisible=10&float=center}}
 ^ Parm Name ^ Format ^ Description ^ ^ Parm Name ^ Format ^ Description ^
-| access_token | [string] | Upon successful login this parameter will be returned. | +| checksum_key | [string] | The key of the checksum record that was stored in the CeRTNA Portal. | 
-| code | [string] | Upon login failure this parameter will be returned. | +| code | [string] | Exception conditions will result in code/message being returned. | 
-| message | [string] | Upon login failure this parameter will be returned. |+| message | [string] | Longer description of exception condition. |
  
  
-As noted, any condition that results in an unsuccessful login will produce a JSON formatted response with a code and message property populated. Successful logins will result in the access_token property being returned and the token can be used for subsequent web service call for the duration of the web session.+As noted, any condition that results in an unsuccessful call to the StoreChecksum web service will produce a JSON formatted response with a code and message property populated. Successful calls will result in the checksum_key property being returned. The checksum_key is a required parameter of the ValidateChecksum web service.
  
  
Line 55: Line 59:
 **Endpoint:** **Endpoint:**
  
-<nowiki>https://apex-prd.certna.org/user/login</nowiki>+<nowiki>https://apex-prd.certna.org/APEX/Service/APEXPublicServer.svc/storechecksum</nowiki>
  
  
Line 67: Line 71:
 <code json> <code json>
 { {
-  "user_name" : "sample1", +  "checksum" : "1/l1YnJ1dnWFVbjEcUfp3IkBkPb1XBWhdC34T6nJ3YB859YuAtbhUUEG8Gcwimd1"
-  "password" : "i4Z15hsQxRv0527iliRhb4j3/OlbtFu0SCn/7Sp+Sqk="+
 } }
 </code> </code>
  
  
-**Sample Response:**+<color #7092be>Sample Response</color>
  
 Status Code: 200 Status Code: 200
  
-or 
- 
-Status Code: 500  (When an error occurs.) 
  
 <code json> <code json>
 { {
-    "access_token": "534d4c30-28a0-48c8-a76d-bbd265d7a1ac"+    "checksum_key": "315E7449-1A67-44A8-BCF4-7EB43666D54D"
 } }
 </code> </code>
  
-or  (example 1)+ 
 +**OR** 
 + 
 +Status Code: 500  (When an error occurs.) 
 + 
 + 
 +(example 1) 
  
 <code json> <code json>
Line 93: Line 100:
     "Exception": {     "Exception": {
         "Code": "DatabaseError",         "Code": "DatabaseError",
-        "Message": "The user name or/and password are invalid."+        "Message": "Procedure or function 'spStoreChecksumValue' expects parameter '@CHECKSUM_VALUE', which was not supplied."
     }     }
 } }
 </code> </code>
  
-or  (example 2) 
  
-<code json>+<color #7092be>Additional Comments</color> 
 + 
 +Comments and sample code are provided for reference purposes only and are not intended to show all exception handling conditions and/or completed code blocks. 
 + 
 + 
 +**Comment 1:** 
 + 
 +The StoreChecksum web service requires a Base64 encoded SHA384 checksum to be provided as one of the parameters. 
 +Following is a C# / .NET sample code snippet that shows how to generate a SHA3 checksum and convert the hash to a Base64 string: 
 + 
 + 
 +{{page>[:guides:sample_sha384_hash&noheader&noindent&nofooter&nouser&nodate&noeditbtn&nopermalink]}} 
 + 
 + 
 +**Comment 2:** 
 + 
 +Following is a C# / .NET sample code snippet that shows how to call the StoreChecksum web service. Your code will supply the values for the various parameters based on the following: 
 + 
 + 
 +{{tablelayout?colwidth="150px,450px"&rowsFixed=1&rowsVisible=10&float=center}} 
 +^ Parameter ^ Source ^ 
 +| checksum | The Base64 encoded value of the SHA384 binary checksum that was calculated for the DOCUMENT string.  | 
 + 
 + 
 +<code C#> 
 +Public static void StoreChecksumExample()
 { {
-    "Exception": { +// In this example I am picking up the checksum value I calculated from a  
-        "Code": "DatabaseError", +// form field in the sample application that is available on this Wiki. 
-        "Message": "Procedure or function 'spLogin_New' expects parameter '@PASSWORD', which was not supplied." + 
-    }+string strChecksumValue = tbChecksumValue.Text; 
 + 
 +// The following value was obtained from your call to the Login web service. 
 + 
 +string token = "ab34xyz3..."; 
 + 
 +strURL = null; 
 +client = null; 
 +request = null; 
 +response = null; 
 + 
 +strURL = "https://apex-prd.certna.org/APEX/Service/APEXPublicServer.svc/storechecksum"; 
 + 
 +client = new RestClient(strURL); 
 +request = new RestRequest(Method.POST); 
 + 
 +strParms = "{\n\t\"checksum\" : \""; 
 +strParms += strChecksumValue; 
 +strParms += "\"\n}"; 
 + 
 +request.AddHeader("Cache-Control", "no-cache"); 
 +request.AddHeader("Content-Type", "application/json"); 
 +request.AddHeader("access_token", token); 
 +request.AddParameter("StoreChecksum", strParms, ParameterType.RequestBody); 
 + 
 +response = client.Execute(request); 
 + 
 +if (response.IsSuccessful) 
 +{ 
 +var jsonResult2 = JsonConvert.DeserializeObject<dynamic>(response.Content); 
 +string strChecksumKey = jsonResult2.checksum_key; 
 + 
 +// (Agents) Update the RequestChecksumValue property of the PRIA_DOCUMENT node with the value of strChecksumKey 
 +// or 
 +// (Counties) Update the ResponseChecksumValue property of the PRIA_DOCUMENT node with the value of strChecksumKey 
 +} 
 +else 
 +{ 
 +var jsonResult2 = JsonConvert.DeserializeObject<dynamic>(response.Content); 
 +string str_ErrorCode = jsonResult2.ToString(); 
 + 
 +// Do something with the error result 
 +}
 } }
 </code> </code>
  
  
-<color #7092be>Additional Comments</color>+**Comment 3:**
  
-Comments and sample code are provided for reference purposes only and are not intended to show all exception handling conditions and/or completed code blocks.+Please note that before calling the CeRTNA web services you must establish the SecurityProtocol in your ServicePointManager. An example is shown below. The currently recommended protocol is Tls12.  
 + 
 +<code C#> 
 +public MainWindow() 
 +{ 
 +            InitializeComponent(); 
 +            System.Net.ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls | 
 +                                                  SecurityProtocolType.Tls11 | 
 +                                                  SecurityProtocolType.Tls12 | 
 +                                                  SecurityProtocolType.Ssl3; 
 +} 
 +</code> 
 + 
 + 
 +**Comment 4:** 
 + 
 +CeRTNA has posted a simple [[:guides:sample_web_service_project|Visual Studio 2015 WPF/C# project]] on the CeRTNA Wiki that demonstrates how to look up values in an XML file and how to use the Login, StoreChecksum, and ValidateChecksum web services. The project can be downloaded from the Wiki. As stated earlier, the purpose of the code samples is not to demonstrate well structured code, but rather to provide a very simple, functional sample, that you can use for reference in adding CeRTNA web service calls to your existing application. The code sample is provided as is, however, your production code would be expected to contain more extensive error handling, etc. 
 + 
 + 
 +**Comment 5:** 
 + 
 +A nice utility for experimenting with web service calls is POSTMAN. You can download a free version of POSTMAN from the following URL: https://www.getpostman.com/apps
  
guides/ws_store_checksum.1540575606.txt.gz · Last modified: by brett.zamora