Using the REST API

Requesting a signature with PKI Agent consists of two steps:

First, the browser should send a request to the authorization endpoint, which will prompt the PKI Agent user to grant permission. The response to that request will contain information on the certificate selected by the user, as well as an authorization token for the second request.

Second, the browser should send an HTTP POST request to the signing endpoint, containing either the data to be signed or a hash of the data. By using the token from the first request, no user interaction is required for this step.

NOTE: For any request or response that uses JSON format, all binary data should be encoded as a hexadecimal string.

Authorization

The first step in signing with the PKI Agent REST API is to make a request to the authorization endpoint, /authorize. The following JavaScript code creates and sends an authorization request:

JavaScript
 Copy
// Create a random alphanumeric PIN to be shown to the user
const pin = randomPin();

// Display the PIN and application name to the user here
// notifypanel.innerHTML = `Your one-time authorization code is: ${pin}`;

// Send the authorization request
const authUrl = `http://127.0.0.1:9267/authorize?pin=${pin}&origin=My%20Application`;
const response = await fetch(authUrl, { method: 'GET' });
if (!response.ok) {
  throw new Error("Signing request rejected. Failed to obtain authorization.");
}

// Parse the token from the response
const resp = await response.json();
var token = resp.cred;

To begin, pick a random PIN for this authorization request and display it to the user in the browser along with the name of your application. When the request is sent, PKI Agent will show the user a popup window containing the PIN and application name, so they can verify that the information matches and grant permission for signing.

The response from the authorization request will be in JSON format and contain an authorization token along with information on the selected certificate:

 
 Copy
{
  "cred": "7530726a6d396431386d31717a326977326f6f7474393271646333356f646f69",
  "credtype": "Token",
  "service": "",
  "objects": [
    {
      "id": "59016E1DB603_c1d63efc135d7e14e1274aa1ba503e8107abc3aa4299585c39b4808377d6f17b",
      "class": "privatekey",
      "private": false,
      "sensitive": false,
      "exportable": false,
      "readonly": false,
      "group": "49440003353930313645314442363033",
      "label": "Private Key 3",
      "value": "",
      "fingerprint": "",
      "validfrom": "",
      "validto": "",
      "subject": "",
      "friendlyname": "",
      "alg": "rsa",
      "algparams": [],
      "size": 0,
      "ops": {
        "encrypt": true,
        "decrypt": true,
        "sign": true,
        "verify": true,
        "hash": false,
        "signrecover": false,
        "verifyrecover": false,
        "wrap": false,
        "unwrap": false,
        "derive": false
      },
      "props": [
        {
          "prop": "publickey",
          "propval": "3082020A0282020100C1...61AE6267EDE7F30203010001"
        }
      ]
    },
    {
      "id": "59016E1DB603_30561067f607cf21c598c8337435bfb9ef1d4fbb6334934a7c8a194f3e9ab7d0",
      "class": "certificate",
      "private": false,
      "sensitive": false,
      "exportable": false,
      "readonly": false,
      "group": "49440003353930313645314442363033",
      "label": "Certificate 3",
      "value": "30820646308204aea00302...c948a83fc0b8e47470dc95c7",
      "fingerprint": "2170a80c36fcafe9b0a2f5ce150ccdd496c7203d",
      "validfrom": "20230112",
      "validto": "20260112",
      "subject": "C=US, S=North Carolina, O=/N SOFTWARE INC., CN=/N SOFTWARE INC.",
      "issuer": "C=GB, O=Sectigo Limited, CN=Sectigo Public Code Signing CA R36",
      "serialno": "b090e0833143d13237e122ac8720e49d",
      "friendlyname": "",
      "size": 1610,
      "props": []
    }
  ]
}

Signing

The next step is to send the signing request itself to the /sign endpoint as an HTTP POST request. The request and response can use either binary or JSON data:

Option A (Binary data and response):

JavaScript
 Copy
const signUrl = `http://127.0.0.1:9267/sign?token=${token}`;
const buf = new TextEncoder().encode("MyData");
const signResponse = await fetch(signUrl, {
  method: 'POST',
  headers: { "Content-Type": "application/octet-stream" },
  body: buf
});
if (!signResponse.ok) {
  throw new Error("Signing authorization expired or request failed.");
}

const signature = toHexString(await signResponse.arrayBuffer())

This request uses the token from the authorization response as a token query parameter. By doing so, the user does not have to grant permission through the prompt window again. The contents of the request are binary data, and the signature is returned as a binary DER signature in PKCS1 format.

Option B (JSON data and response):

JavaScript
 Copy
const signUrl = `http://127.0.0.1:9267/sign?token=${token}&fmt=json`;
var hexEncodedData = toHexString(myData);

const buf = new TextEncoder().encode(JSON.stringify({
  plaintext: hexEncodedData,
  alg: {
    name: "sha256WithRSAEncryption",
    props: []
  }
}));
const signResponse = await fetch(signUrl, {
  method: 'POST',
  headers: { "Content-Type": "application/octet-stream" },
  body: buf
});
if (!signResponse.ok) {
  throw new Error("Signing authorization expired or request failed.");
}

// Parse the signature from the response
const signResp = await signResponse.json();
const signature = signResp.signature;

This request uses the token from the authorization response as a token query parameter. By doing so, the user does not have to grant permission through the prompt window again. The plaintext field in the request body contains the binary data to be signed, converted to a hex string for transmission. The alg field can be used to specify an algorithm to use for signing.

The response will contain a hex-encoded DER signature in PKCS1 format along with information about the certificate used to create the signature:

 
 Copy
{
  "signature": "46d77d860ca5f9021f7f6b612...e32d53048d7027e980d22e85f8f",
  "trace": "",
  "objects": [
    {
      "id": "59016E1DB603_c1d63efc135d7e14e1274aa1ba503e8107abc3aa4299585c39b4808377d6f17b",
      "class": "privatekey",
      "private": false,
      "sensitive": false,
      "exportable": false,
      "readonly": false,
      "group": "49440003353930313645314442363033",
      "label": "Private Key 3",
      "value": "",
      "fingerprint": "",
      "validfrom": "",
      "validto": "",
      "subject": "",
      "friendlyname": "",
      "alg": "rsa",
      "algparams": [],
      "size": 0,
      "ops": {
        "encrypt": false,
        "decrypt": true,
        "sign": true,
        "verify": false,
        "hash": false,
        "signrecover": false,
        "verifyrecover": false,
        "wrap": false,
        "unwrap": false,
        "derive": false
      },
      "props": [
        {
          "prop": "publickey",
          "propval": "3082020A0282020100C146...267EDE7F30203010001"
        }
      ]
    },
    {
      "id": "59016E1DB603_30561067f607cf21c598c8337435bfb9ef1d4fbb6334934a7c8a194f3e9ab7d0",
      "class": "certificate",
      "private": false,
      "sensitive": false,
      "exportable": false,
      "readonly": false,
      "group": "49440003353930313645314442363033",
      "label": "Certificate 3",
      "value": "30820646308204aea0030201...dd1da34c948a83fc0b8e47470dc95c7",
      "fingerprint": "2170a80c36fcafe9b0a2f5ce150ccdd496c7203d",
      "validfrom": "20230112",
      "validto": "20260112",
      "subject": "C=US, S=North Carolina, O=/N SOFTWARE INC., CN=/N SOFTWARE INC.",
      "issuer": "C=GB, O=Sectigo Limited, CN=Sectigo Public Code Signing CA R36",
      "serialno": "b090e0833143d13237e122ac8720e49d",
      "friendlyname": "",
      "size": 1610,
      "props": []
    }
  ]
}