Blockchain Data Integrity User Guide. Implementation of Service in Predix

Transcription

1 Blockchain Data Integrity User Guide Implementation of Service in Predix Rev C Ericsson AB 2016

2 Blockchain Data Integrity 2 (29) Contents 1 Overview of Blockchain Data Integrity Three main functions of the service Generating a keyless signature for data Extending a keyless signature Verifying the integrity of signed data Interface API Signature request Signature extension request Signature verification request Success response Error response Using Blockchain Data Integrity with Predix Deleting a Blockchain Data Integrity instance Code examples Common code Using the Blockchain Data Integrity Client Software Development Kit Example without using the SDK Support FAQ Abbreviations... 29

3 Blockchain Data Integrity 3 (29) 1 Overview of Blockchain Data Integrity Ericsson s data integrity service, known as Blockchain Data Integrity, provides the ability for an application developer to provide data integrity for an application s users using a Keyless Signature Infrastructure (KSI ) via a RESTful API. Current data integrity functions allow users to: generate a non-reversible signature for user data extend the signature or publicize it verify that the current version of the user data has not been altered and that it matches the non-reversible signature Blockchain Data Integrity allows a developer to ensure that a collection of data has not been tampered with since a digital signature has been assigned. Verifying the signature guarantees that the data has not been modified since the signature was applied. The integrity of the data or digital asset is one of three core tenets of security, along with availability and confidentiality. This integrity aspect can be applied within Predix in two general ways, each having a specific application based on the industry vertical. The first role for the service is in providing evidence and proof of regulatory or process compliance. One core aspect of Predix is to support analytics of information flowing from industrial devices through Predix to generate insights and produce business impacts. Given the importance of these business impacts, it can be critical to be certain that the analysis has not been ruined by modified data inputs (inadvertent or deliberate). Verifying the integrity of the data inputs before using the results can be a key trust anchor for using the analytic results. For industry verticals that are under regulatory scrutiny, such as NERC/FERC, the integrity of the data from a particular industrial system may be a compliance requirement or audit point. The Blockchain Data Integrity service is used to verify that no data has been tampered with during an analytic process or during a process that is under regulatory control. The second role for the service is in providing for the security of an industrial device attached to Predix. In this case, the various configuration elements of the industrial device are verified as being in a proper state at a given time. Some aspects of the machine s configuration whether the underlying software or the machine s settings will often be updated by Predix analytics. Again, for regulatory reasons or security considerations, being able to verify the integrity of the configuration before a machine is placed into service is a critical aspect of security. This integrity element of security again comes into play in many industrial regulatory environments as cybersecurity for Internet of Things (IoT) devices becomes a concern.

4 Blockchain Data Integrity 4 (29) 2 Three main functions of the service Blockchain Data Integrity provides three main functions: generating a keyless signature for data, extending a keyless signature, and verifying the integrity of the signed data Generating a keyless signature for data When generating a signature for a piece of user data, typically a file, an SHA-256 hash value of the user data must be supplied (note: these hash algorithms are supported: SHA-1, SHA-256, SHA-384, SHA-512, RIPEMD160). An SHA-256 hash is an almost-unique fixed-size cryptographic value generated from a piece of data, and it cannot be reversed to obtain the original data. This hash value is delivered to the Blockchain Data Integrity service and combined with many other variables outside of the user s control to generate a unique signature that cannot be decrypted to obtain the user data. This signature must be stored by the application consuming this service and used as proof of data integrity Extending a keyless signature On a monthly basis, Ericsson publishes the top root hash of a calendar blockchain to extend the keyless signature. When extending a signature, the signature stored by the application must be provided to the Blockchain Data Integrity service to have it extended to the published value. Extending a signature involves inserting the hash value for the publication code, or published hash value. This allows the validation of the data offline with a code published monthly in both Twitter and the Financial Times Verifying the integrity of signed data When verifying the integrity of a previously signed piece of user data, the signature stored by the client application must be provided to Blockchain Data Integrity to validate the signature. If the service successfully validates the signature, the service responds back with the expected SHA-256 hash value of the data referenced by the signature. The final step of the verification is performed by the application: generating its own SHA- 256 hash value of the user data, and comparing this current file hash value against the service s expected hash value to determine whether they match. If the hashes match, the user can be confident that the data has not been changed or tampered with since it was previously signed. If a subsequent change to the signed data was made by an attacker, the fraudulent change will be detectable; the signature will not be validated because re-hashing is performed. When verification fails, the user can take the appropriate action to correct the data and restore it to original values. 2.2 Interface API All service requests must include the request headers noted in Table 1: Request Headers.

5 Blockchain Data Integrity 5 (29) Table 1: Request Headers Header Predix-Zone-Id Authentication Value <Service Instance Id> bearer <token>

6 Blockchain Data Integrity 6 (29) Signature request When generating a signature for a piece of user data (typically a file), an SHA-256 hash value of the user data must be supplied to Blockchain Data Integrity. Request and response messages are encoded in JSON format.

7 Blockchain Data Integrity 7 (29) Signature extension request The signature extension request message requires the signature token as a parameter. This signature token was saved by the application after user data was successfully signed by the Blockchain Data Integrity service. Note that a signature must be at least 30 days old or have a suitable publication before it can be extended.

8 Blockchain Data Integrity 8 (29) Signature verification request The signature verification request message requires the signature token as a parameter. This signature token was saved by the application after the user data was successfully signed by the Blockchain Data Integrity service.

9 Blockchain Data Integrity 9 (29) Success response All success responses have the same format and are encoded in JSON. Some fields may be optional and are not always included in the response messages. For example, the publicationrecord field and its sub-fields are not present in the response message until the signature has been extended. Table 2: Success Response (HttpStatus = 200 OK) Parameter details {aggregationtime, datahash {algorithm, value, identity, publicationrecord {datahash {algorthim, value, publicationcode, Description Nested JSON containing aggregationtime, datahash, identity, and publicationrecord Timestamp Nested JSON containing algorithm and value SHA-256 Base 64 encoded SHA-256 hash string value String Nested JSON containing datahash, publicationcode, publicationreferences[ ], publicationrepositoryuris[ ], and publicationtime Nested JSON containing algorithm and value SHA-256 Base 64 encoded SHA-256 hash string value String publicationreferences[ ], [ String ] publicationrepositoryuirs[ ], [ String ] publicationtime, signature, verificationresult {policyresults[ ] {policy, Timestamp String Nested JSON containing policyresults[ ] and status Array of nested JSON containing policy, policyresultcode, and verificationerror String

10 Blockchain Data Integrity 10 (29) policyresultcode, verificationerror, status String String String { "details": { "aggregationtime": 0, "datahash": { "algorithm": "SHA-256", "value": "GHgonhozPdhQkdMPABufb57U1CjVfgSb0OvU28ib0hA=", "identity": "string", "publicationrecord": { "datahash": { "algorithm": "SHA-256", "value": "GHgonhozPdhQkdMPABufb57U1CjVfgSb0OvU28ib0hA=", "publicationcode": "string", "publicationreferences": ["string"], "publicationrepositoryuris": ["string"], "publicationtime": 0, "signature": "string", "verificationresult": { "policyresults": [{ "policy": "string", "policyresultcode": "OK", "verificationerror": "GEN_1" ], "status": "OK"

11 Blockchain Data Integrity 11 (29) Error response All error responses have the same format. Like success responses, error responses are also encoded in JSON. Table 3: Error Response (HttpStatus!= 200 OK) Parameter errorcode errormessage requestid timestamp Description Machine readable error code that classifies the fault. (INVALID_REQUEST, NOT_FOUND, INTERNAL_SERVER_ERROR) Human-readable error message Message requestid Date and time of the error, expressed as milliseconds since January 1, 1970 (UTC)

12 Blockchain Data Integrity 12 (29) 2.3 Using Blockchain Data Integrity with Predix 1. Create and package your application. For guidelines about how to develop an application that is compatible with the cloud environment, see 2. Log in to your Cloud Foundry account. cf login 3. Change to the project folder where your application is located. cd <file_path>/<application_name> 4. Push the application to Cloud Foundry: cf push <application_name> Note: If you provide the application name in a manifest file, you do not have to provide the application name in the command. You can instead enter the following: cf push 5. List the available applications: cf apps You see the application you pushed with a STOPPED status. It cannot start until you create an instance of the Blockchain Data Integrity service and bind it to the application. 6. List the services in the Cloud Foundry marketplace:

13 Blockchain Data Integrity 13 (29) cf marketplace You can see the Blockchain Data Integrity service and associated plans. 7. Create a Blockchain Data Integrity service instance: cf create-service blockchain-data-integrity <plan> <myblockchain-data-integrity_service_instance> -c { trustedissuerids : [ ] where: <plan> is the plan associated with a service. <my-blockchain-data-integrity_service_instance> is the service instance you are creating. <UAA_instance> is the UAA service instance which will provide the OAuth token when interacting with the Blockchain Data Integrity service 8. Bind your application to your service instance: cf bind-service <application_name> <my- blockchain-dataintegrity_service_instance> 9. Restage your application to ensure the environment variable changes take effect: cf restage <application_name> 10. To view the environment variables for your application, enter the following command: cf env <application_name>

14 Blockchain Data Integrity 14 (29) A subset of the environment variables consists of the following information: credentials: { zone: { http-header-name: Predix-Zone-Id http-header-value: <serviceinstanceid> oauth-scope: <servicedefinitionid>.zones.<serviceinstanceid>.user uri: The application must also be bound to a UAA instance. The application should have a client ID defined in the UAA with permissions granted to the scope defined in by the oauth-scope value. All service requests must include the following two headers: Predix-Zone-Id, with the value defined in http-header-value Authorization, with the value of bearer <token> where <token> is the OAuth token value for the client ID created in the UAA for the application. 11. To view a list of available service instances, run the following command: cf services You can see your newly created service instance, as well as any other service instances used for the application.

15 Blockchain Data Integrity 15 (29) 2.4 Deleting a Blockchain Data Integrity instance You can remove the application and the service instance. 1. Log in to your Cloud Foundry account. cf login 2. Stop the application by entering the following command: cf stop <application_name> 3. Unbind your Blockchain Data Integrity service instance from the application. cf us <application_name> <my- blockchain-dataintegrity_service_instance> 4. Destroy the application. cf d <application_name> 5. Destroy the instance of the Blockchain Data Integrity service. cf ds <my- blockchain-data-integrity_service_instance> The application and service instance are decommissioned.

16 Blockchain Data Integrity 16 (29) 2.5 Code examples Common code Generating the SHA-256 hash for a file The following code shows an example of generating the SHA-256 hash for a user data file. public String getfilehash(string fname) { // Generate a file hash using SHA-256. // 1 Mb buffer int buff = ; FileInputStream fis = new FileInputStream(fName); MessageDigest hashsum = MessageDigest.getInstance("SHA-256"); byte[] buffer = new byte[buff]; int nread = 0; while ((nread = fis.read(buffer))!= -1) { hashsum.update(buffer, 0, nread); ; byte[] partialhash = hashsum.digest(); fis.close(); byte[] encodedpartialhash = Base64.encodeBase64(partialHash); String encodedhashstr = (new String(encodedPartialHash)). replaceall("\n", ""); return encodedhashstr;

17 Blockchain Data Integrity 17 (29) Using the Blockchain Data Integrity Client Software Development Kit Blockchain Data Integrity provides a client software development kit (SDK) that makes it easier and faster for software developers to write applications that communicate with Blockchain Data Integrity within GE Predix. The SDK contains a set of APIs that allow application developers to perform Blockchain Data Integrity functions, including signing data as well as verifying and extending signatures from client-side applications. The SDK can be downloaded from the following web page: The following lists the possible classes that can be included and used. // Main client class import com.ericsson.diaapi.client.diaclient; // Model classes import com.ericsson.diaapi.model.datahash; import com.ericsson.diaapi.model.details; import com.ericsson.diaapi.model.detailsrequest; import com.ericsson.diaapi.model.errorresponse; import com.ericsson.diaapi.model.extensionrequest; import com.ericsson.diaapi.model.policyresults; import com.ericsson.diaapi.model.publicationrecord; import com.ericsson.diaapi.model.signature; import com.ericsson.diaapi.model.signaturerequest; import com.ericsson.diaapi.model.verificationrequest; // Exception classes import com.ericsson.diaapi.exception.diaconnectionexception; import com.ericsson.diaapi.exception.diainternalexception;

18 Blockchain Data Integrity 18 (29) Client provisioning The client defines a client interface API to communicate with Blockchain Data Integrity. The following code shows an example of provisioning the client. The uri parameter provides the route to the Blockchain Data Integrity service. The instanceid parameter provides the service instance ID being used.... // Retrieve uri and instanceid from the VCAP SERVICES // environment variable. // Instantiate DIA client. try { diaclient = new DiaClient(uri, instanceid); catch (MalformedURLException e) { e.printstacktrace(); catch (URISyntaxException e) { e.printstacktrace();...

19 Blockchain Data Integrity 19 (29) APIs Usage of the Blockchain Data Integrity service is facilitated by calling the following APIs provided by the client SDK. These APIs send a POST message to Blockchain Data Integrity based on the client provisioning performed earlier. Sign Verify Extend Sign (create signature) The code shown below for invoking the sign method sends a signature request to the Blockchain Data Integrity service and provides the result. Internally, an HTTP POST request containing the appropriate message headers and body is sent to the service, which then sends the response back to the client application.... // - filehash contains the generated SHA-256 file hash // of the user data to be signed. // - token contains the bearer token from the UAA Client Id // to be used in the Authorization header in the POST message // to the data integrity assurance service. // - Note: other hash algorithms are accepted: // SHA-1, SHA-256, SHA-384, SHA-512, RIPEMD160 SignatureRequest requestdata = new SignatureRequest(); requestdata.setdatahash("sha-256", filehash); try { // Sign file Signature signresp = diaclient.sign(requestdata, token); catch (DiaConnectionException e) { e.printstacktrace(); catch (DiaInternalException e) { e.printstacktrace();...

20 Blockchain Data Integrity 20 (29) Verify (verify signature) The code shown below for invoking the verify method sends a verification request to the Blockchain Data Integrity service and provides the result. Internally, an HTTP POST request containing the appropriate message headers and body is sent to the service, which then sends the response back to the client application. Signature signatureobj;... // Get signature string for signed data. String signaturestr = signatureobj.getsignature(); try { // Verify signature. Signature verifyresp = diaclient.verify(signaturestr, token); // Get verification result. VerificationResult verifresult = verifyresp.getverificationresult();... catch (DiaConnectionException e) { e.printstacktrace(); catch (DiaInternalException e) { e.printstacktrace();...

21 Blockchain Data Integrity 21 (29) Extend (extend signature) The code shown below for invoking the extend method sends an extension request to the Blockchain Data Integrity service and provides the result. Internally, an HTTP POST request containing the appropriate message headers and body is sent to the service, which then sends the response back to the client application. Signature signatureobj;... // Get signature string for signed data. String signaturestr = signatureobj.getsignature(); try { // Extend signature. Signature extendresp = diaclient.extend(signaturestr, token);... catch (DiaConnectionException e) { e.printstacktrace(); catch (DiaInternalException e) { e.printstacktrace();...

22 Blockchain Data Integrity 22 (29) Model The following classes and public methods are defined within the Blockchain Data Integrity client SDK. These classes are used to facilitate data exchange in the request and response messaging between the application and the Blockchain Data Integrity service. public class SignatureRequest { public SignatureRequest() public DataHash getdatahash() public void setdatahash(string algorithm, String value) public class Signature { public Signature() public Signature(final String signature) public Details getdetails() public PublicationRecord getpublicationrecord() public String getsignature() public VerificationResult getverificationresult() public class Details { public Details() public long getaggregationtime() public DataHash getdatahash() public String getidentity()

23 Blockchain Data Integrity 23 (29) public class DataHash { public DataHash() public String getalgorithm() public String getvalue() public void setalgorithm(string algorithm) public void setvalue(string value) public class PublicationRecord { public PublicationRecord() public DataHash getdatahash() public String getpublicationcode() public List<String> getpublicationreferences() public List<String> getpublicationrepositoryuris() public long getpublicationtime() public class VerificationResult { public VerificationResult() public List<PolicyResults> getpolicyresults() public String getstatus() public class ErrorResponse { public ErrorResponse() public ErrorResponse(String errorcode, String errormessage) public String geterrorcode public String geterrormessage public Date gettimestamp() public String getrequestid() public int getstatus() public String geterror() public String getexception() public String getmessage() public String getpath public String geterrordescription()

24 Blockchain Data Integrity 24 (29) Exceptions The following exception classes are defined within the Blockchain Data Integrity client SDK and are used during exception/error scenarios. DiaInternalException occurs if there is an exception within the client SDK. DiaConnectionException occurs if there is issue with connecting to the Blockchain Data Integrity service. public class DiaInternalException extends Exception { public DiaInternalException (final String message) public class DiaConnectionException extends Exception { public DiaConnectionException(final String message, final ErrorResponse errorresponse) public ErrorResponse geterrorresponse()

25 Blockchain Data Integrity 25 (29) Example without using the SDK SignatureRequest and DataHash class definitions The following code shows an example of the SignatureRequest class and the DataHash class used by the SignatureRequest class. A SignatureRequest object is used to populate the request to create a signature. // SignatureRequest class = public class private DataHash datahash; public SignatureRequest() { public DataHash getdatahash() { return datahash; public void setdatahash(string algorithm, String value) { this.datahash = new DataHash(); this.datahash.setalgorithm(algorithm); this.datahash.setvalue(value);

26 Blockchain Data Integrity 26 (29) // DataHash class = public class @JsonProperty("algorithm") private @JsonProperty("value") private String value; public DataHash() { public String getalgorithm() { return algorithm; public String getvalue() { return value; public void setalgorithm(string algorithm) { this.algorithm = algorithm; public void setvalue(string value) { this.value = value; Post a message to a Blockchain Data Integrity API The following code shows how to send a POST request to one of the Blockchain Data Integrity APIs. Note that the <service-proxy-route> and the <serviceinstanceid> must be obtained from the application s environment variables after the application has been bound to an instance of the Blockchain Data Integrity service. The api parameter must be one of the following APIs: /v1/proxy/signature /v1/proxy/signature/details /v1/proxy/signature/extension

27 Blockchain Data Integrity 27 (29) private static Signature dopost(string api, String jsonstr) { // Send POST request message. String inputline = ""; Signature signresultobj = null; // Open a new connection for this URL. URL url = new URL(" + api); HttpURLConnection conn = (HttpURLConnection) url.openconnection(); // Set header parameters. conn.setrequestmethod("post"); // send using method="post". conn.setdooutput(true); // set connection output to true conn.setrequestproperty( "Content-type", "application/x-www-form-urlencoded"); conn.setrequestproperty( "Accept", "*/*" ); conn.setrequestproperty( "Predix-Zone-Id", <serviceinstanceid>); if (jsonstr!= null) { conn.setrequestproperty("content-type", "application/json"); // Get output stream that writes to this connection. OutputStream os = conn.getoutputstream(); if (jsonstr!= null) { // Write data to the connection. os.write(jsonstr.getbytes()); os.flush(); // Receive response as input stream from server Create a signature POST: /v1/proxy/signature The following code shows populating the datahash parameter in a message object and converting the message content to a JSON string (to be included in a POST request message).

28 Blockchain Data Integrity 28 (29) // Populate datahash parameter in message object // with file hash value. SignatureRequest sigrequestobj = new SignatureRequest(); sigrequestobj.setdatahash("sha-256", sha256filehash); // Convert message object to JSON string. String jsonstr = null; ObjectMapper mapper = new ObjectMapper(); jsonstr = mapper.writevalueasstring(sigrequestobj); // Invoke dopost method to send POST request message. Signature signresultobj = dopost("/v1/proxy/signature", jsonstr); Verify a signature POST: /v1/proxy/signature/details The following code shows sending a POST request message to the Blockchain Data Integrity service with a JSON string containing the signature token. This message is sent to the details endpoint requesting signature verification. String jsonstr = "{\"signature\":\"" + siguuid + "\""; Signature verifyresultobj = dopost("/v1/proxy/signature/details", jsonstr); Extend a signature POST: /v1/proxy/signature/extension The following code shows sending a POST request message to the Blockchain Data Integrity service with a JSON string containing the signature token. This message is sent to the extension endpoint requesting that the signature be extended to the publication record. String jsonstr = "{\"signature\":\"" + siguuid + "\""; Signature extendresultobj = dopost("/v1/proxy/signature/extension", jsonstr);

29 Blockchain Data Integrity 29 (29) 2.6 Support FAQ Question: How do I populate the required headers in a service request message to the Blockchain Data Integrity service? Answer: Predix-Zone-Id This header is used for multi-tenancy purposes and it specifies the service instance being used. The value should be retrieved from the VCAP_SERVICES Cloud Foundry environment variable. Authorization This header provides information about the user and their role. The value must be bearer <token> where <token> is the client s OAuth bearer token obtained from the UAA. 3 Abbreviations JSON KSI JavaScript Object Notation Keyless Signature Infrastructure SDK SHA UAA Software Development Kit Secure Hash Algorithm User Account and Authentication