Authentication

All requests to the REST API must be authenticated as one of the configured users. Users are created within the PKI Proxy application and can be assigned any of the following authentication methods:

When a certificate is shared, only the users which have been allowed access to that specific certificate may perform operations with it.

Basic Authentication

PKI Proxy supports standard HTTP Basic authentication. To perform Basic authentication, specify the username and password separated by a ':'. For instance username:password, then Base64 encode the result and include it in the Authorization header like this:

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

NTLM Authentication

PKI Proxy also supports NTLM authentication. This uses the standard Windows implementation, which your client will need to support if you want to use this authentication method.

In NTLM, the client sends a Negotiate message, which contains an Authorization header with a negotiation token:

Authorization: NTLM <Negotiation Token>

The server responds with a Challenge response, which contains a WWW-Authenticate header with a challenge token:

WWW-Authenticate: NTLM <Challenge Token>

And then the client sends an Authenticate response, which contains an Authorization header again, this time with an authorization token:

Authorization: NTLM <Auth Token>

When configuring NTLM in PKI Proxy, you can use the current Windows user or select to use another Windows user.

Secret Key Authentication

In addition to the Basic and NTLM authentication types, PKI Proxy supports a Secret Key authentication mechanism that operates on top of HTTP. The Secret Key mechanism relies on a pair of credentials secretly shared by the PKI Proxy client and server.

Secret Key authentication is already supported in the included PKCS11 driver and pkptool utility. The instructions below are only needed when connecting directly to the REST API.

While Secret Key authentication is broadly similar to HTTP Basic (both use a public credential / secret credential pair), the Secret Key mechanism provides a much stronger communication protection:

• HTTP Basic only authenticates the client. Secret Key authenticates both parties.
• HTTP Basic includes the password in the request. The secret keys are never sent over the network.
• HTTP Basic only proves that the client knows the password. Secret Key proves that the client and the server know the key and guarantees the integrity of the request and response content.
• HTTP Basic is susceptible to replay attacks. Secret Key is not.
• Passwords are easier for attackers to discover than arbitrary, random, binary secret keys.

Below we provide the algorithm that PKI Proxy uses to calculate the Secret Key authentication parameters. The algorithm assumes that the parties have already generated and exchanged the secret key value securely, and have it configured in their settings for the authenticating user. Secret Key authentication follows these steps:

• The client prepares a request imprint based on the HTTP request it plans to send.
• The client digitally signs the request imprint with its secret key, and includes the signature with the request - either as a sig parameter of the query string or as an X-Sig HTTP header.
• Upon receiving a signed request, the server builds its own version of the request imprint, using the actual request it received from the client.
• The server then calculates its own version of the signature, using the secret key and the request imprint it has just built. If the two signatures match, the request is genuine and intact.

Building the request imprint

The request imprint is a concatenation of the following elements:

• HTTP verb in lowercase
• LF
• The value of the Content-Type header
• LF
• The canonicalized query string (everything after the domain name, including the leading /, but excluding the sig parameter, if it is present)
• LF
• The body of the request, if present

Preparing a signature header

The signature header is a portion of the signature that contains information about the signature itself, and is included in the signature hash. Compose the signature header as following:

SIGNATURE_VERSION + ":" + KEYID + ":" + TIMESTAMP + ":" + SALT.

• SIGNATURE_VERSION specifies the variant of the signature that you intend to use (e.g. pkps3). See below for more details about the signature variants.
• KEYID specifies the key ID (aka the username) associated with the secret key. This should contain the name on your PKI Proxy user account.
• TIMESTAMP is current time in UTC expressed as the number of milliseconds from the Unix epoch (for example, 1732888798672 for November 29, 2024).
• SALT is a random 16-character value. PKI Proxy applications generate it as hex encoding of a random 8-element byte array, but you are free to use any sufficiently random string.

Calculating the signed value

PKI Proxy supports three signature methods. Method 1 is not as strong cryptographically as Methods 2 and 3, but it is easier to implement in native Javascript. Methods 2 and 3 are stronger, but less Javascript-friendly.

All the signature methods operate on the request imprint and header strings as defined above. They also use an auxiliary HASH function shown below: string HASH(string key, string data) { return HMACSHA256(key, data).ToHex().ToUppercase(); }

Method 1

In pseudocode, this method can be written as following: string SignedValueV1(string secretKey, string requestImprint, string header) { hkey = "PKPS1" + secretKey; for (i = 0; i < 1000; i++) { modifier = i.ToString() + header; hkey = HASH(hkey, modifier); } return HASH(hkey, requestImprint); }

The SIGNATURE-VERSION for Method 1 is pkps1.

Method 2

The pseudocode for Method 2 looks as following:

string SignedValueV2(string secretKey, string requestImprint, string header) { hkey = PBKDF2(SHA1, secretKey, header, 10000 /* iterations */, 32 /* output length in bits */); return HASH(hkey, requestImprint); }

The SIGNATURE-VERSION for Method 2 is pkps2.

Method 3

The Method 3 can be implemented using the following pseudocode:

string SignedValueV3(string secretKey, string requestImprint, string header) { hkey = PBKDF2(SHA256, secretKey, header, 10000 /* iterations */, 256 /* output length in bits */); return HASH(hkey, requestImprint); }

The SIGNATURE-VERSION for Method 3 is pkps3.

Adding the signed value to the request

The signed value should always be a 64-character hex string. Once you've calculated it, append the result to the header string separated by a colon and encode the result in base64 to complete the signature. You can then add the completed signature to your request either as an additional query parameter ("sig") or as an HTTP header ("X-Sig").

To validate the signature, follow the same method to build the request imprint and the signature, but instead of building the signature header yourself, use the parameters included in the header of the signature you are validating. Then compare the signature you received with the one you've just built. If the signatures match, the request or response is genuine and has not been modified.

Examples

This section will illustrate the use of two signature methods, 1 and 3. The example assumes that there is a user named keyuser set up on both sides of the PKI Proxy channel, with Secret Key authentication type configured, and the secret key of 1234567890. If the PKI Proxy client is sending a list request to PKI Proxy server for all certificate objects, the request will be a GET request to http://pkiproxy.server.com/objects?filter=class%3Dcertificate.

First, derive the request imprint and the header string:

Request imprint:

get 
\n
\n
/objects?filter=class%3Dcertificate
\n

The following are examples of signature headers for methods 1 and 3 respectively. For the same salt and timestamp, the signature method prefix is the only difference between the two:

pkps1:keyuser:1733143134108:2C86BA1E47132F32

pkps3:keyuser:1733143134108:2C86BA1E47132F32

Calculating the signed value for method 1 uses the following flow: string SignedValueV1(string secretKey = "1234567890", string requestImprint, string header = "pkps1:keyuser:1733143134108:2C86BA1E47132F32") { hkey = "PKPS1" + secretKey; // hkey = PKPS11234567890 for (i = 0; i < 1000; i++) { modifier = i.ToString() + header; // for the i value of 0, modifier is 0pkps1:keyuser:1733143134108:2C86BA1E47132F32, hkey = HASH(hkey, modifier); // and hkey is 24681907F88BCE1CDA911443759ABB236729EBEBA88C917B59AA48B204406BF3 } // By the exit of the loop, hkey is 932BB59B278773CA4F55E5BEF774961D88F001D793450FB0B30A1A75AE9994DB. // Passing it to HASH one final time: return HASH(hkey, requestImprint); // the result is D2A2C56F719E412681429C9F1D79ACBD8F2E5DA5AEE1EA43DFE21520DBBD21D6. }

Calculating the signed value for method 3 uses the following flow: string SignedValueV3(string secretKey = "1234567890", string requestImprint, string header = "pkps3:keyuser:1733143134108:2C86BA1E47132F32") { hkey = PBKDF2(SHA256, secretKey, header, 10000, 256); // The output of PBKDF2 is a 32-byte binary array of [4B, E0, A7, E6, 8E, 96, C2, AF, // 8E, B5, 48, F1, 89, 4C, 68, DD, 59, 8A, 84, 1C, 80, EC, 07, 14, 3B, A5, 0E, 52, // A5, 44, DB, C2]. return HASH(hkey, requestImprint); // the result is 799709C3D9A0BD12E249D8EEBE6411368D0F54ABFBEEFEF16A6107F234FEF3F3. }

Once the signed value has been created, form the full signature by appending it to the header and encoding the whole string with base64 (it does not need to be aligned to a 4-byte boundary with trailing '=' characters): // Method 1 signature_unencoded = pkps1:keyuser:1733143134108:2C86BA1E47132F32:D2A2C56F719E412681429C9F1D79ACBD8F2E5DA5AEE1EA43DFE21520DBBD21D6 signature_encoded = cGtwczE6a2V5dXNlcjoxNzMzMTQzMTM0MTA4OjJDODZCQTFFNDcxMzJGMzI6RDJBMkM1NkY3MTlFNDEyNjgxNDI5QzlGMUQ3OUFDQkQ4RjJFNURBNUFFRTFFQTQzREZFMjE1MjBEQkJEMjFENg // Method 3 signature_unencoded = pkps3:keyuser:1733143134108:2C86BA1E47132F32:799709C3D9A0BD12E249D8EEBE6411368D0F54ABFBEEFEF16A6107F234FEF3F3 signature_encoded = cGtwczM6a2V5dXNlcjoxNzMzMTQzMTM0MTA4OjJDODZCQTFFNDcxMzJGMzI6Nzk5NzA5QzNEOUEwQkQxMkUyNDlEOEVFQkU2NDExMzY4RDBGNTRBQkZCRUVGRUYxNkE2MTA3RjIzNEZFRjNGMw

Once you append the signature to the query string, it should look like this: // Method 1 /objects?filter=class%3Dcertificate&sig=cGtwczE6a2V5dXNlcjoxNzMzMTQzMTM0MTA4OjJDODZCQTFFNDcxMzJGMzI6RDJBMkM1NkY3MTlFNDEyNjgxNDI5QzlGMUQ3OUFDQkQ4RjJFNURBNUFFRTFFQTQzREZFMjE1MjBEQkJEMjFENg // Method 3 /objects?filter=class%3Dcertificate&sig=cGtwczM6a2V5dXNlcjoxNzMzMTQzMTM0MTA4OjJDODZCQTFFNDcxMzJGMzI6Nzk5NzA5QzNEOUEwQkQxMkUyNDlEOEVFQkU2NDExMzY4RDBGNTRBQkZCRUVGRUYxNkE2MTA3RjIzNEZFRjNGMw