Skip Navigation
  1. BlackBerry Docs
  2. BlackBerry Dynamics
  3. Using a PKI Connector when UEM retrieves certificates for BlackBerry Dynamics apps
  4. BlackBerry Dynamics User Certificate Management protocol APIs
  5. getUserKeyPair2 API

getUserKeyPair2 API

UEM
 uses this API to fetch an initial key-pair and to renew an existing certificate. This API replaces the deprecated getUserKeyPair API.
The HTTP request line is: 
POST customerSpecifiedPrefix/pki?operation=getUserKeyPair2
UEM
 sends the following values:
Element
Type
Required
Details
mType
string
Yes
The value is 
initialCert
 if 
UEM
 is fetching the key-pair for the first time, and 
renewCert
 if 
UEM
 is renewing the certificate.
  
user
string
Yes
The user’s email address or another unique identifier. The certificate subject is created by the issuer.
authToken
string
No
An authentication token value provided by the user if it is required by the user credential profile.
reqId
string
No
For 
initialCert
 only, a request ID value to assist the sender in matching the response.
deviceId
string
No
For 
initialCert
 only, the 
BlackBerry Dynamics
 device ID. This value can be used to track if two apps on the same device are requesting the certificate at the same time.
deviceName
string
No
For 
initialCert
 only, the device name.
cmsSigned
string
No
When a 
BlackBerry Dynamics
 app renews an existing certificate, it uses the current private key to authenticate the request to renew. It sends this information in the 
cmsSigned
 element, and 
UEM
 sends this to the PKI connector without making any changes.
cmsSigned = base64 encoded (cms-signed-data(CertRequest))
CertRequest includes 
reqId, deviceId, deviceName,
 and 
pkcs10
 (base64 encoded CSR). 
The API call returns the following response values:
Element
Type
Required
Details
status
string
Yes
This can be a value of 
success
 or
 failure
.
failureInfo
string
No
This element provides details about a failure.
payloadType
string
No
This is a value of 
pkcs12
.
payload
Base64 encoded object
No
This is a value of 
BASE64 Encoded PKCS12
.
regID
string
Yes
This is a request ID value.
password
string
No
If pkcs12 was password encrypted and 
authToken
 was not used as the password for encryption, a decryption password may be returned. For certificate renewal, a password is required.

Initial enrollment sample

In this sample, the administrator has specified the following URL for the PKI connector in the management console: https://ra.lifeonthedot.com
Request: The following payload is sent over an SSL connection to https://ra.lifeonthedot.com:
POST /pki?operation=getUserKeyPair2 HTTP/1.0
Host: ra.lifeonthedot.com
Content-Type: application/json
Content-Length: XYZ

{
    "mType": "initialCert",
    "user": "joe.foo@lifeonthedot.com",
    "authToken": "56ht12d0",
    "reqId": "12487",
    “deviceId”: “6e8S8JCLN7Hc5v3cGqvfkfM/C/tAFDS1CFUPJ53ASL”,
    “deviceName”: “Joe’s iPhone6”
}
If the server URL was set as https//ra.lifeonthedot.com/foo in the management console, the request will be:
POST /foo/pki?operation=getUserKeyPair2 HTTP/1.0
Host: ra.lifeonthedot.com

Content-Type: application/json
Content-Length: XYZ
Response:
HTTP/1.0 200 OK
Host: ra.lifeonthedot.com
Content-Type: application/json
Content-Length: XYZ

{
    "status":"success",
    "reqId": "12487",
    "payloadType":"pkcs12",
    "password":"clearTextPassword",
    "payload":"BASE64 Encoded PKCS12"
}

Renew sample

Request:
POST /pki?operation=getUserKeyPair2 HTTP/1.0
Host: ra.lifeonthedot.com
Content-Type: application/json
Content-Length: XYZ

{
    "mType": "renewCert",
    "user": "joe.foo@lifeonthedot.com",
    "cmsSigned": "base64-enoded-CMS-signed-data"
}
Response:
HTTP/1.0 200 OK
Host: ra.lifeonthedot.com
Content-Type: application/json
Content-Length: XYZ

{
    "status":"success",
    "reqId": "12487",
    "payloadType":"pkcs12",
    "password":"clearTextPassword",
    "payload":"BASE64 Encoded PKCS12"
}