6.4 PKI Plug-in

The following table lists all the parameters that the PKI plug-in supports.

Parameter

Description

pki.vendorModule=<library-file-name>.dll

To set the PKCS#11 implementation library that the vendor module requires.

pki. hashMethod: SHA256

The default value is SHA256 and you can specify this value, if a parameter is not presented. The following methods are also supported: SHA224, SHA384, SHA512. To set the methods, ensure that the PKCS#11 module supports the required hash method.

pki.padding: PKCS#1

The default value is PKCS#1 and you can specify this value, if a parameter is not presented.The following options are also supported: PSS, OAEP.

pki.modulusBits: 2048

The default value is 2048 bit. For example, eToken PRO 32k does not support it so you need to set 1024 to use it.

pki.blockingMode: true

Detects and monitors the token connected to the system. It is set to true by default. OpenSC does not support the 'waiting for card' mechanism and it requires to change the option to False. Most of the vendors module work appropriately in the default mode.

PKI plug-in uses the simulator API for a card or token detection and POST methods.

6.4.1 POST Methods

The following table lists the different POST methods of PKI service and the respective response that the service returns.

Method

Syntax

Description

Response

getcertificates

https://127.0.0.1:8440/api/v1/pki/getcertificates

Retrieves all certificates from the connected token.

 
{ 
"readerid"=0, "certificates" : [
{ "keypairid":"9beb","certificate":"30820371308202daa00....0b90d7290a1a76b0450264dd536d2cb057230f8dbfa8cfda05"
}
]
}

where:

  • keypairid indicates ID of the key pair in the certificate. Save this ID for future logon operations.

  • certificate indicates certificate value in DER format.

generatekeypair

https://127.0.0.1:8440/api/v1/pki/generatekeypair- POST method, Request Body: {"pin":"your_pin"}

Replace your_pin with actual token PIN or leave it empty if there is no PIN.

Generate a Public Key Infrastructure (PKI) public and private key pair for a local digital certificate.

 
{
 "readerid"=your_reader_id, "keypairid":"6f4712e554544ac3", "modulus":"a1709fb049c35fdc6695193e9dd980c713c....91daaa9d2604eeeaad73d13b1", "exponent":"010001"
}

where:

  • keypairid indicates ID of the key pair in the certificate. Save this ID for future logon operations.

  • modulus

  • exponent

signchallenge

https://127.0.0.1:8440/api/v1/pki/signchallenge - POST method, Request Body: {"challenge":"3128", "pin":"your_pin", "keypairid":"9beb" }

where:

  • challenge is in hex-string format

  • pin is PIN of the token

  • keypairid is ID of keypair from token.

Enables the PKI plug-in to sign the challenge from the authentication server. User is provided with an interface to specify PIN and keypair ID.

If the challenge is successful, signature of given challenge is returned as response.

{
 "readerid"=your_reader_id, "hash":"SHA1", "padding":"PKCS#1", "signature":"58ad84f3a9b7244031aa55c0d0ad753b1a480ae709a37210d48....493130d7b11f128ea2be1fcc42d123bdb715a153974e992b16d022" 
}

where:

  • hash indicates hash method that is used.

  • padding indicates the padding method that is used.

  • signature indicates signature for given challenge in hex format.

verifychallenge

https://127.0.0.1:8440/api/v1/pki/verifychallenge - POST method, Request Body {"challenge":"3128", "pin":"your_pin", "keypairid":"9beb", "signature":"58ad84f3a9b72....bdb715a153974e992b16d022" }

Verifies the PKI plug-in challenge from the authentication server. User is provided with an interface to specify PIN, keypair ID, and signature.

 

if there is an issue with token or configuration, the above methods display error in the following format:

{ "result":"ERROR_ID"}

The following table lists all the error IDs for the POST methods of PKI service with description.

Error ID

Description

PLUGIN_NOT_INITTED

A vendor module or library is not present, invalid, or not specified

METHOD_NOT_FOUND

Method not found

NO_CARD

No token or card is presented. Use wait methods to get an event

JSON_PARSE_FAILED

Bad request

WRONG_PIN

Incorrect PIN

GET_PRIVATE_KEY_FAILED

Error while retrieving a private key from the token

OPERATION_FAILED

general operation failure

6.4.2 GET Methods

You can browse the following URL to check the PKI service:

https://127.0.0.1:8440/api/v1/pki/getmessage?

The response is displayed in the following format:

{
result: [<status>],
cardid: <card id>,
readerid: <reader id>
}

The following table describes the different status that the PKI service displays as response.

Status

Description

NO_READER

The Card service has not detected the connected card reader or the reader is not connected to the system

READER_ON

The Card service has detected the connected card reader

NO_CARD

A card is not inserted in the reader

CARD_ON

A card is inserted in the reader

NOTE:The cardid parameter is used only with the CARD_ON and NO_CARD statuses.

The following table lists the different GET methods of the PKI service and the respective response that the service returns.

Method

Response

https://127.0.0.1:8440/api/v1/pki/getmessage?

Displays the current status of the reader and card instantly.

Possible status values are:

  • NO_READER

  • NO_CARD

  • CARD_ON

https://127.0.0.1:8440/api/v1/pki/getmessage?wait

Waits for the next action.

For example, insertion or removal of a card from the reader.

NOTE:If you disconnect the reader with a card being inserted in reader, two messages NO_CARD and NO_READER are displayed.

When you connect a reader with a card inserted, two events READER_ON and CARD_ON take place. As a result, READER_ON is displayed as a response.

https://127.0.0.1:8440/api/v1/pki/getreaderon?nowait

Displays the current status of reader.

Possible status values are:

  • READER_ON

  • NO_READER

https://127.0.0.1:8440/api/v1/pki/getreaderon?wait

Displays READER_ON if the reader is connected or waits till you connect the reader.

https://127.0.0.1:8440/api/v1/pki/getcardon?nowait

Displays the current status of the card.

Possible status values:

  • NO_READER

  • NO_CARD

  • CARD_ON

https://127.0.0.1:8440/api/v1/pki/getcardon?wait

Displays NO_READER if a reader is not connected or waits till a card is inserted in the reader.

NOTE:If a card is inserted in the reader, the service waits till the card is removed and inserted again.

https://127.0.0.1:8440/api/v1/pki/getcardoff?cardid=<cardid>

Possible status values:

  • NO_READER

  • NO_CARD

  • CARD_ON

Use the cardid parameter to make the service wait when a specific card is removed.

https://127.0.0.1:8440/api/v1/card/getcardoff?wait

Possible status values:

  • NO_READER

  • NO_CARD

If a card is present on the reader, the service waits till the card removed from the reader.

https://127.0.0.1:8440/api/abort?cancel-cookie=xxx

All the wait methods support cancel-cookie=xxx parameter.

For example, https://127.0.0.1:8440/api/v1/pki/getmessage?wait&cancel-cookie=xxx. If you call abort with the cancel-cookie, all the waiting methods with the specified cookie are terminated.