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"
}

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"
}