Testing Digital Signatures

All 3rd party software must use digital signature algorithms to meet the authentication requirements for submitting ERS event reports.

The algorithm chosen is ECDSA (ANSI X9.62) NIST P-256 elliptic curve known as prime256v1 or secp256r1.

Information is provided below so that you can test your generation of public keys and signatures against our algorithm implementation, as well as testing the signature over the whole request body. This includes command files for the windows version of OpenSSL. 

There are four steps to this process.

Step 1: Generate keys

generate-keys.cmd: generates a public and private key pair using OpenSSL

  • Edit register.json
    • change the softwareInstallationId to your company name or something unique
    • change the publicKey to the generated key in public.pem, without the carriage return.
  • Edit payload.json
    • change the softwareInstallationId to match what you have changed in register.json
generate-keys.cmd
@echo off
set path=%path%;C:\Program Files\OpenSSL-Win64\bin;

openssl ecparam -name prime256v1 -genkey -out private.pem
echo private.pem
type private.pem
echo.

openssl pkcs8 -topk8 -nocrypt -in private.pem -out private-pkcs8.pem
echo private-pkcs8.pem
type private-pkcs8.pem
echo.

openssl ec -in private.pem -pubout -out public.pem
echo public.pem
type public.pem
echo.

pause
Example:register.json
{
"softwareInstallationId": "example1234",
"publicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEGTzANOubqiWo5HwgRbE16uCrNYv0VOWIaY+xUgIoqumXNAaNKGKIC3lFzC1ZeECnA+sHsnEELvNoyISYWOaCFg==",
}
Example:payload.json
{
"SoftwareInstallationId": "example1234",
"testText": "Digital Signature Test", 
"textNumber": 9933
}
Example:Output of generate-keys.cmd
private.pem
-----BEGIN EC PARAMETERS-----
BggqhkjOPQMBBw==
-----END EC PARAMETERS-----
-----BEGIN EC PRIVATE KEY-----
MHcCAQEEINaAjvpQf76wIOycx+3KFRU6LbDmZN7clQDYcie4kwmZoAoGCCqGSM49
AwEHoUQDQgAEkR3iWAes8sIBQNi0FH1ulx0EEPRD7wxFtWGNlezsBdEmsjoC/orF
7LdHHzLnofY9bXViLJbvPLe9TDow5RCIfg==
-----END EC PRIVATE KEY-----

private-pkcs8.pem
-----BEGIN PRIVATE KEY-----
MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQg1oCO+lB/vrAg7JzH
7coVFTotsOZk3tyVANhyJ7iTCZmhRANCAASRHeJYB6zywgFA2LQUfW6XHQQQ9EPv
DEW1YY2V7OwF0SayOgL+isXst0cfMueh9j1tdWIslu88t71MOjDlEIh+
-----END PRIVATE KEY-----

read EC key
writing EC key
public.pem
-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEkR3iWAes8sIBQNi0FH1ulx0EEPRD
7wxFtWGNlezsBdEmsjoC/orF7LdHHzLnofY9bXViLJbvPLe9TDow5RCIfg==
-----END PUBLIC KEY-----

Step 2: Register the Public Key

register-public-key.cmd: uses cURL to register the public key in register.json

The key will be registered in a 4 hour cache for testing purposes.

register-public-key.cmd
@echo off
set path=%path%;C:\Program Files\cURL\src;

echo register.json
type register.json
echo.
echo.

curl -i -X POST -H "Content-Type: application/json" -d @register.json https://ers.uat.kupe.fishserve.co.nz/api/security/test/fake-register
echo.

pause
Example:Output of register-public-key.cmd
register.json
{
        "softwareInstallationId": "example1234",
        "publicKey": " MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEkR3iWAes8sIBQNi0FH1ul
x0EEPRD7wxFtWGNlezsBdEmsjoC/orF7LdHHzLnofY9bXViLJbvPLe9TDow5RCIfg==”
}

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json; charset=utf-8
Expires: -1
Strict-Transport-Security: max-age=31536000
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Date: Wed, 08 Nov 2017 00:40:03 GMT
Content-Length: 2

{}

Step 3: Generate Signature

generate-signature.cmd: uses OpenSSL to generate a signature from the private key and payload.json

generate-signature.cmd
@echo off
set path=%path%;C:\Program Files\OpenSSL-Win64\bin;

echo payload.json
type payload.json
echo.
echo.

openssl dgst -sha256 -binary -sign private.pem -out signature.bin payload.json
openssl base64 -in signature.bin -out signature.base64
echo signature.base64
type signature.base64
echo.

openssl dgst -sha256 -verify public.pem -signature signature.bin payload.json
echo.

del signature.bin

pause
Example:Output of generate-signature.cmd
payload.json
{
        "SoftwareInstallationId": "example1234",
        "testText": "Digital Signature Test",
        "textNumber": 9933
}

signature.base64
MEUCID8+PO1IQR3+vGI/v5f06LrUb1M1R4YS82Q5qILgdeV4AiEAxO9Ec4eUzA4y
+WENot7ud45+J2fPypP2RmVsE46z114=

Verified OK

Step 4: Post payload using digital signature

post-payload.cmd: uses cURL to verify payload.json against the signature using the public key stored by register-public-key.cmd

  • Edit post-payload.cmd
    • replace the signature with the content of signature.base64 created in Step 3: Generate Signature above.

Please note: Some utilities such as Postman and cURL will modify the JSON payload by stripping out carriage returns or swapping tabs for spaces. If this occurs your submission will fail validation. We suggest; 

  • in cURL: use --databinary to stop cURL from modifying the signed payload,
  • in Postman: set request body to raw and load your payload from file. 
post-payload.cmd
@echo off
set path=%path%;C:\Program Files\cURL\src;

echo payload.json
type payload.json
echo.
echo.


curl -i -X POST -H "Content-Type: application/json" -H "Signature: MEUCIDM3KjUJay/ukGwXDTr/Kw46ou1+js8ZHO9vnwYonU2xAiEA+PoIt7qPHhOSGSBE9I2dSFqiu6I3s6OKkqlmkPAz6Fk=" --data-binary @payload.json https://ers.uat.kupe.fishserve.co.nz/api/security/test/algo-with-register
echo.


pause
Example:Output of post-payload.cmd
payload.json
{
        "SoftwareInstallationId": "example1234",
        "testText": "Digital Signature Test",
        "textNumber": 9933
}

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json; charset=utf-8
Expires: -1
Strict-Transport-Security: max-age=31536000
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Date: Wed, 08 Nov 2017 00:48:56 GMT
Content-Length: 2

{}

Error Messages

If the public key, signature or payload is modified, then the response will be;

Status: 400 Bad Request

Error body
{
    "errors": [
        {
            "propertyName": null,
            "attemptedValue": null,
            "errorCode": null,
            "errorMessage": "NOT VERIFIED"
        }
    ]
}

If the SoftwareInstallationId within the request is changed, then the response will be;

Status: 400 Bad Request

Error body
{
    "errors": [
        {
            "propertyName": "PublicKey",
            "attemptedValue": null,
            "errorCode": null,
            "errorMessage": "PublicKey not registered"
        }
    ]
}

Return to Electronic Reporting - ERS

Back to top