DokuWiki

You've loaded an old revision of the document! If you save it, you will create a new version with this data.

==== Web Service: ValidateChecksum ====

The ValidateChecksum web service is used to validate a locally calculated SHA384 checksum against a checksum record that was previously stored in the CeRTNA Portal. The locally calculated checksum_value is obtained by [[guides:sample_sha384_hash|calculating the SHA384 checksum of a Base64 string]] contained in a CeRTNA Standard XML PRIA_DOCUMENT node. The checksum_key value contained in RequestChecksumValue (supplied by agent) property or the ResponseChecksumValue (supplied by county) property of the PRIA_DOCUMENT node, provides the index for the checksum_value the caller is validating.

The ValidateChecksum web service, returns true, if the locally calculated value matches the value that was stored for the indexed record, otherwise it returns false.

<color #7092be>Request Endpoint</color>

{{tablelayout?colwidth="75px,525px"&rowsFixed=1&rowsVisible=10&float=center}}
^ Method ^ URL ^
| POST | <nowiki>https://apex-prd.certna.org/APEX/Service/APEXPublicServer.svc/validatechecksum</nowiki> |

<color #7092be>Request Body</color>

This endpoint accepts request body parameters using an application/json format.

<color #7092be>Request Headers</color>

{{tablelayout?colwidth="150px,450px"&rowsFixed=1&rowsVisible=10&float=center}}
^ Key ^ Value ^
| Content-Type | application/json |

<color #7092be>JSON Request Parameters</color>

{{tablelayout?colwidth="150px,75px,100px,275px"&rowsFixed=1&rowsVisible=10&float=center}}
^ Parm Name ^ Req/Opt ^ Format ^ Description ^
| checksum_key | Required | [string] | The checksum key of a checksum record stored in the CeRTNA Portal. |
| checksum | Required | [string] | Locally calculated binary checksum value converted to a Base64 string. |

<color #7092be>JSON Response Parameters</color>

{{tablelayout?colwidth="125px,100px,375px"&rowsFixed=1&rowsVisible=10&float=center}}
^ Parm Name ^ Format ^ Description ^
| is_valid | [string] | True if checksum values match, otherwise false. |
| code | [string] | Exception conditions will result in code/message being returned. |
| message | [string] | Longer description of exception condition. |

As noted, any condition that results in an unsuccessful call to the ValidateChecksum web service will produce a JSON formatted response with a code and message property populated.

<color #7092be>Sample Request</color>

**Endpoint:**

<nowiki>https://apex-prd.certna.org/APEX/Service/APEXPublicServer.svc/validatechecksum</nowiki>

**Headers:**

Content-Type: application/json

**Body:**

<code json>
{
  "checksum_key" : "D6D5895C-60BF-4D21-AE5B-945C8E255665",
  "checksum" : "1/l1YnJ1dnWFVbjEcUfp3IkBkPb1XBWhdC34T6nJ3YB859YuAtbhUUEG8Gcwimd1"
}
</code>

<color #7092be>Sample Response</color>

Status Code: 200

<code json>
{
    "is_valid": "true"
}
</code>

**OR**

Status Code: 500  (When an error occurs.)

(example 1)

<code json>
{
    "Exception": {
        "Code": "DatabaseError",
        "Message": "Conversion failed when converting from a character string to uniqueidentifier."
    }
}
</code>

<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 ValidateChecksum 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 ValidateChecksum 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_key | The checksum_key (index) of a checksum record that is stored in the CeRTNA Portal.  |
| checksum | The Base64 encoded value of the SHA384 binary checksum that was calculated for the DOCUMENT string.  |

<code C#>
Public static void ValidateChecksumExample()
{
// In this example I am picking up the checksum_key and the checksum value I calculated from a 
// form field in the sample application that is available on this Wiki.

string strChecksumKey = tbChecksumKey.Text;
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/validatechecksum";

client = new RestClient(strURL);
request = new RestRequest(Method.POST);

strParms = "{\n\t\"checksum_key\" : \"";
strParms += strChecksumKey;
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("ValidateChecksum", strParms, ParameterType.RequestBody);

response = client.Execute(request);

if (response.IsSuccessful)
{
var jsonResult2 = JsonConvert.DeserializeObject<dynamic>(response.Content);
string strIsValid = jsonResult2.is_valid;

// Continue processing based on your true or false result.
}
else
{
var jsonResult2 = JsonConvert.DeserializeObject<dynamic>(response.Content);
string str_ErrorCode = jsonResult2.ToString();

// Do something with the error result
}
}
</code>

**Comment 3:**

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

Edit summary

Note: By editing this page you agree to license your content under the following license: CC Attribution-Noncommercial-Share Alike 4.0 International