To perform requests to the TrackRecordPro API, you must authenticate with a self-signed SSL certificate. This certificate is identical in structure to that used for HTTPS, except that you can generate it yourself and that it is used purely for authentication to the system. To create a self-signed SSL certificate for use with the API, follow the steps below.
You will need the openssl suite, which is freely available and included in most Linux/BSD and commercial Unix distributions, OSX, and downloadable for Windows. Once you have installed OpenSSL, open up a command prompt window or terminal, and change to the directory where OpenSSL is installed if neccessary.
Run the following OpenSSL command to generate your private key and public certificate. Answer the questions as prompted. The Common Name should be the name of a responsible person at your organisation, and the Organisation Name should be the name of your company. In the Email Address field, enter the E-Mail address of your IT department or developer.
> openssl req -newkey rsa:2048 -nodes -keyout privatekey.pem -x509 -days 365 -out clientcert.pem Generating a 2048 bit RSA private key ..............+++ ..........................+++ writing new private key to 'privatekey.pem' ----- You are about to be asked to enter information that will be incorporated into your certificate request. What you are about to enter is what is called a Distinguished Name or a DN. There are quite a few fields but you can leave some blank For some fields there will be a default value, If you enter '.', the field will be left blank. ----- Country Name (2 letter code) [AU]:GB State or Province Name (full name) [Some-State]:Derbyshire Locality Name (eg, city) []:Derby Organization Name (eg, company) [Internet Widgits Pty Ltd]:TrackRecordPro Organizational Unit Name (eg, section) []:IT Department Common Name (e.g. server FQDN or YOUR name) []:Craig Edwards Email Address []:support@trackrecordpro.co.uk
You can then use the following to review the created certificate:
> openssl x509 -text -noout -in clientcert.pem
Certificate:
Data:
Version: 3 (0x2)
Serial Number:
f3:99:41:57:93:2f:d3:a6
Signature Algorithm: sha256WithRSAEncryption
Issuer: C=GB, ST=Derbyshire, L=Derby, O=TrackRecordPro, OU=IT Department, CN=Craig Edwards/emailAddress=support@trackrecordpro.co.uk
Validity
Not Before: Oct 10 08:34:46 2017 GMT
Not After : Oct 10 08:34:46 2018 GMT
Subject: C=GB, ST=Derbyshire, L=Derby, O=TrackRecordPro, OU=IT Department, CN=Craig Edwards/emailAddress=support@trackrecordpro.co.uk
Subject Public Key Info:
Public Key Algorithm: rsaEncryption
Public-Key: (2048 bit)
Modulus:
00:dc:2a:11:80:a8:18:d1:9c:8f:49:a2:2b:28:8a:
d5:37:01:d1:f5:95:6b:aa:4e:b3:aa:84:b5:c8:c6:
9d:69:4d:57:c8:da:3d:6d:86:51:e4:8f:05:b5:43:
8a:ea:e4:e3:ae:c9:ac:18:54:85:19:dc:b9:f5:33:
b8:42:52:8d:8c:68:ac:78:8c:80:8e:c0:74:54:36:
9b:64:d3:3d:99:69:8e:f6:ee:eb:b8:f6:ad:32:e5:
65:85:77:4d:f2:7b:33:ea:48:a5:96:78:db:88:74:
1e:41:d6:c4:28:69:ad:5f:d1:c3:f2:4f:fc:4b:1c:
c3:e7:cf:3b:bb:93:24:ec:d5:27:11:48:14:d1:6e:
ba:d7:14:0f:e0:04:f3:0e:d8:4d:22:48:22:25:2e:
cd:68:8f:9f:df:68:b9:fa:6d:87:4f:ac:60:fd:1f:
65:2a:dc:f4:48:ac:0d:61:02:5f:a2:9d:81:17:36:
10:2d:fa:de:12:b4:4a:6d:9a:37:bd:a7:65:73:48:
63:83:af:c1:9f:b3:bb:45:c2:a9:e2:73:4e:0f:83:
ee:d7:8d:d9:92:7e:68:c9:0a:77:43:c2:00:41:dd:
f8:c9:7f:8b:5e:2c:ee:ac:9b:ae:6f:88:71:35:e5:
30:d3:8d:42:f1:35:3a:05:e4:1f:86:f3:98:5e:69:
5e:19
Exponent: 65537 (0x10001)
X509v3 extensions:
X509v3 Subject Key Identifier:
DF:74:54:40:21:F4:BA:39:2A:23:F8:30:92:3E:66:C4:EB:6F:96:86
X509v3 Authority Key Identifier:
keyid:DF:74:54:40:21:F4:BA:39:2A:23:F8:30:92:3E:66:C4:EB:6F:96:86
X509v3 Basic Constraints:
CA:TRUE
Signature Algorithm: sha256WithRSAEncryption
af:0a:33:e9:65:70:c1:9f:49:f8:ff:eb:33:31:c0:4e:a1:b6:
5d:d0:b5:c1:9a:d7:f5:35:af:8f:35:7e:09:b4:d6:a1:aa:d4:
5d:56:72:7e:0e:3b:e8:1c:9b:af:f7:15:13:d5:f7:89:52:ec:
41:a2:6d:78:0c:e0:16:32:d5:88:ce:4d:be:0f:e9:76:ba:8c:
6d:11:30:f5:ed:cb:83:e3:6e:46:8d:91:bd:e2:45:df:2a:ad:
28:7d:33:b0:8e:d9:fd:79:5d:31:58:31:3c:3d:9c:3b:35:b9:
b4:2c:f2:9f:85:5f:86:88:63:80:ec:ce:b5:e8:f1:e1:30:e1:
77:f3:60:f4:0f:29:5a:87:5d:24:79:bb:bd:7b:e7:9c:5c:9c:
bd:0e:2a:c3:f3:fa:40:5e:88:90:d2:ae:2c:8b:ed:e5:a2:f1:
ea:fa:83:e7:3e:99:ca:a6:03:f4:a0:ad:9e:e6:89:8c:14:2a:
34:8c:5a:bb:ca:60:dd:21:2e:4d:66:61:36:ea:af:bc:35:1c:
c5:ff:1b:fc:d0:02:2d:97:8e:10:11:6d:54:d9:8c:1e:bd:11:
e9:df:1d:06:ab:01:bd:4b:85:c6:b6:93:77:96:7b:83:7b:7a:
f3:81:9a:e4:15:ea:73:33:ec:a6:87:23:aa:df:85:9d:41:54:
If you need to convert the certificate to p12 format (e.g. for certain windows libraries) you can run the following OpenSSL command:
> openssl pkcs12 -inkey key.pem -in certificate.pem -export -out certificate.p12 Enter Export Password: Verifying - Enter Export Password:
Once you have generated your SSL certificate, you should keep the privatekey.pem safe (you will use this on your end of the connection when authenticating to the API) and upload the clientcert.pem portion to TrackRecordPro so the system can recognise your connection. This can be done via the settings section of the TrackRecordPro website by clicking the button highlighted below:
You will be prompted for your SSL certificate - upload the public key part by selecting it into the box highlighted below:
Please note the warning on this page - uploading a new PEM certificate will invalidate any previous API connections, which will then need to be updated with the new files to continue functioning.
