Documentation Suite v12.3

Submit Search

POST Certificates Import

The POST /Certificates/Import method is used to import a certificate provided in the request body into Keyfactor Command. This method returns HTTP 200 OK on a success with a message body containing information about the import.

Tip: The following permissions (see Security Roles and Claims) are required to use this feature:

/certificates/import/

Table 232: POST Certificates Import Input Parameters

Name In Description

Certificate

Body

Required. A string containing the base-64 encoded contents of the certificate to be imported into Keyfactor Command. This may be a certificate with or without associated private key.

With PowerShell, for example, you could use the following commands to convert certificates of various types to the appropriate format (referencing $b64Cert in the request body Certificate field).

PEM-encoded certificate:
Copy
```
$crtCert = Get-Content 'C:\MyPath\MyCertificate.crt'
$b64Cert = [System.Convert]::ToBase64String(
   [System.Text.Encoding]::ASCII.GetBytes($crtCert)
)
```
Note: The commands are the same regardless of whether the PEM certificate file contains a private key. The private key is ignored. If the file contains chain certificates, the end entity certificate must precede the chain certificates; only the first certificate in the file is imported for this certificate type.

DER-encoded certificate:

Copy

$derCert = Get-Content 'C:\MyPath\MyCertificate.der' -Encoding Byte
$b64Cert = [System.Convert]::ToBase64String($derCert)

PKCS#12-encoded certificate:
Copy
```
$pfxCert = Get-Content 'C:\MyPath\MyCertificate.pfx' -Encoding Byte
$b64Cert = [System.Convert]::ToBase64String($pfxCert)
```
Note: Imports of this certificate type require specifying a Password to decrypt the specified file. Both the certificate and private key are imported.

PKCS#7-encoded binary certificate:

Copy

$p7bCert = Get-Content 'C:\MyPath\MyCertificate.p7b' -Encoding Byte
$b64Cert = [System.Convert]::ToBase64String($p7bCert)

Note: The order of the certificates in the certificate package is not important.

Tip: You can use the POST /Certificates/Analyze method (see POST Certificates Analyze) to confirm that the string you have generated contains the contents that you expect.

Password Body Required^*. A string containing the password used to decrypt the file containing the certificate to be imported. This field is required if a certificate of PKCS#12 format is provided in the Certificate field.

Metadata

Body

An object containing the certificate metadata that will be associated with the certificate once it is imported. This is provided as a set of key value pairs with the metadata field name in the key and the value in the value. For example:

Copy

"Metadata": {
   "AppOwnerFirstName": "John",
   "AppOwnerLastName": "Smith"
}

Store Ids Body An array of strings indicating the certificate store GUIDs that the imported certificate will be installed into.

Store Types

Body

An array of objects indicating the information for the specified store IDs.

Show store type details.

Name Description

Store Type Id

An integer indicating the ID of the store type being used. There must be one for each type of store ID used. Show store type IDs.

Alias Required^*. A string providing an alias to be used for the certificate upon entry into the certificate store. The function of the alias varies depending on the certificate store type. For example, for an F5 device, it serves as the file name used to store the file in the device file system, minus the extension (e.g. use alias MyFile for a file named MyFile.pfx) while for a Java keystore, it is stored in the keystore associated with the certificate. Some certificate store types don't require an alias and some do. See Add Certificate for more information. This field may be required depending on the store type selected.

Overwrite

A Boolean that sets whether a certificate in the store with the Alias provided should be overwritten with the certificate being imported (true) or not (false).

Use the GET Certificates/Locations/{id} method (see GET Certificates Locations ID) to retrieve a list of the locations an existing certificate is in to determine the alias used for the certificate in the certificate store.

Properties

An array of key/value pairs for the unique parameters defined for the certificate store type that need to be populated for the certificate. The key is the name of the specific parameter from the certificate store type definition as returned in the JobProperties on the store type using the GET CertificateStoreTypes method and the value is the value that should be set for that parameter on the certificate in the certificate store. For example, for NetScaler, the key name that is optionally used to associate the certificate with a virtual server is NetscalerVserver and is returned by GET CertificateStoreTypes like so:

"JobProperties": [ "NetscalerVserver" ]

It can be seen in the Keyfactor Command Management Portal when editing the certificate store type in the field for Management Job Custom Fields.

The setting is referenced using the following format:

Copy

"Properties": [
   {
      "NetscalerVserver":"MyVirtualServerName"
   }
]

Note: The only built-in certificate store type that makes use of properties that can be set on a certificate-by-certificate basis in the store is NetScaler. You may have custom certificate store types that make use of this functionality.

Schedule Body A string containing the time the imported certificate should be scheduled to be installed into the certificate store. The date and time should be given using the ISO 8601 UTC time format YYYY-MM-DDTHH:mm:ss.000Z (e.g. 2023-11-19T16:23:01Z).

Owner Role Id

Body

An integer indicating the Keyfactor Command reference ID of the security role assigned as the certificate owner.

Note: To assign a certificate owner, one of OwnerRoleId or OwnerRoleName is required, not both.

Owner Role Name

Body

A string containing the name of the security role assigned as the certificate owner. This name must match the existing name of the security role.

Note: To assign a certificate owner, one of OwnerRoleId or OwnerRoleName is required, not both.

Table 233: POST Certificates Import Response Data

Name

Description

Import Status

An integer indicating the status of the import job indicating, for example, whether the certificate was newly created in Keyfactor Command or already existed in Keyfactor Command and was just updated based on provided private key, metadata, or location information.

Invaild Key Stores

An array of objects indicating which key store items failed with some information.

Show key store details.

Job Status

An integer indicating the state of all certificate store jobs.

Tip: See the Keyfactor API Reference and Utility which provides a utility through which the Keyfactor API

A set of functions to allow creation of applications. Keyfactor offers the Keyfactor API, which allows third-party software to integrate with the advanced certificate enrollment and management features of Keyfactor Command. endpoints can be called and results returned. It is intended to be used primarily for validation, testing and workflow

A workflow is a series of steps necessary to complete a process. In the context of Keyfactor Command, it refers to the workflow builder, which allows you automate event-driven tasks when a certificate is requested or revoked. development. It also serves secondarily as documentation for the API. The link to the Keyfactor API Reference and Utility is in the dropdown from the help icon (

) at the top of the Management Portal page next to the Log Out button.

Version v12.3

On this page: