PKI connector interactions
BlackBerry UEM
makes
API calls to the PKI connector using the HTTP POST method. The PKI connector supports password
authentication and certificate-based authentication.GetInfo API
This API detects the commands that the PKI connector has implemented. This command is also
used to verify the authentication credentials provided in
BlackBerry UEM
and to test
the connection between BlackBerry UEM
and the PKI connector.If this command is not implemented,
BlackBerry UEM
will
assume this is not a valid PKI connector.The path component of the URI sent is as follows:
customerSpecifiedPrefix/pki?operation=getInfo
The
customerSpecifiedPrefix
is optional. It
specifies where the service is hosted on the server when it is not hosted in the default path. The JSON formatted response expected in the HTTP body is as follows:
Element or Key | Type | Required | Response |
|---|---|---|---|
operations | Array of strings | Y | Array listing all of the commands implemented by the PKI connector |
Sample request/response
Assuming that in the
BlackBerry UEM
management
console, the PKI connector URL is set as: https://cert.example.comGET /pki?operation=getInfo HTTP/1.0 Host: cert.example.com Content-Type: application/json Content-Length: 0 Response HTTP/1.0 200 OK Host: cert.example.com Content-Type: application/json Content-Length: XYZ { “operations” : [“getInfo”, “getUserKeyPair”] }
Request Key Pair API
This API is used to fetch a user certificate when the key pair has been
created. This request may be used for initial certificate requests.
The path component of the URI is sent as follows:
customerSpecifiedPrefix/pki?operation=getUserKeyPair
.The
customerSpecifiedPrefix
is optional. It
specifies where the service is hosted on the server when it is not hosted in the default path. The JSON formatted input sent in the HTTP body is as follows:
Element or Key | Type | Required | Comment |
|---|---|---|---|
mType | String | Y | {"initialCert"] |
user | String | Y | User email address or some other identifier Subject for the certificate created by the issuer |
authToken | String | N | OTP or password (for initialCert) |
reqId | String | Y | To assist sender to match response |
The JSON formatted response in the HTTP body, a PKCS #12 payload which may be
encrypted, is as follows:
Element/Key | Type | Required | Comments |
|---|---|---|---|
status | String | Y | {success, failure} |
failureInfo | String | N | See Failure reasons below |
payloadType | String | N | =pkcs12 |
payload | Base64 encoded | N | pkcs12 containing the user's private key and public certificate. It may
or may not be encrypted. |
decryptionPassword | Base64 encoded | N | If the encryption password is the same as the OTP provided by the user,
there is no need to provide descryptionPassword. If pkcs12 was password encrypted and OTP was not used, the password may
be returned in the decryptionPassword. |
reqId | String | Y | reqID received in the request |
Sample request/response
Assuming that in the
BlackBerry UEM
management
console, the PKI connector URL is set as: https://cert.example.comRequest: Over the SSL connection to server cert.example.com the following
payload will be sent:
POST /pki?operation=getUserKeyPair HTTP/1.0 Host: cert.example.com Content-Type: application/json Content-Length: XYZ { "mType": "initialCert", "user": "joe.foo@example.com", "authToken": "56ht12d0", "reqId": "12487" }
If the server URL was set as https://cert.example.com/foo, the request will
look like:
POST /foo/pki?operation=getUserKeyPair HTTP/1.0 Host: cert.example.com Content-Type: application/json Content-Length: XYZ
Response:
HTTP/1.0 200 OK Host: cert.example.com Content-Type: application/json Content-Length: XYZ { "status":"success", "reqId": "12487", "payloadType":"pkcs12", "decryptionPassword":"NTZodDEyZDA=", "payload":"BASE64 Encoded PKCS#12" }
Failure reasons
These errors may be returned by the CA:
Failure | Description |
|---|---|
unknownUser | User does not exist or is not allowed |
badRequest | Badly formatted request |
unknownRequest | Requested action is not supported |
authFailure | Expired or incorrect OTP or password |
badAlg | Unsupported or unrecognized algorithm used |
unknownCert | Certificate used or referenced in the operation not found |
badMessageCheck | Signature or integrity check failed |
badTime | Time in the signature was not close enough |
unknown | Any other errors treated as unknown errors |