Documentation Suite v11.0

GET Certificate Stores

The GET /CertificateStores method is used to return a list of all certificate stores defined in Keyfactor Command. The results include both approved certificates stores and certificates stores found on discovery but not yet approved. This method allows URL parameters to specify paging and the level of information detail. This method returns HTTP 200 OK on a success with details about the certificate store(s).

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

/certificate_stores/read/

/certificate_stores/read/#/ (where # is a reference to a specific certificate store container ID)

Permissions for certificate stores can be set at either the global or certificate store container level. See Container Permissions for more information about global vs container permissions.

Table 313: GET Certificate Stores Input Parameters

Name	In	Description
queryString	Query	A string containing a query to limit the results (e.g. field1 -eq value1 AND field2 -gt value2). The default is to return all records. Fields available for querying through the API for the most part match those that appear in the Keyfactor Command Management Portal search dropdowns for the same feature. For querying guidelines, refer to: Using the Certificate Store Search Feature. The query fields supported for this endpoint are: AddSupported (True, False) AgentAvailable (True, False) AgentId Approved (True, False) Category (0-Javakeystore, 2-PEMFile, 3-F5SSLProfiles,4-IISRoots, 5-NetScaler, 6-IISPersonal, 7-F5WebServer, 8-IISRevoked, 9-F5WebServerREST, 10-F5SSLProfilesREST, 11-F5CABundlesREST, 100-AmazonWebServices, 101-FileTransferProtocol) CertificateId ClientMachine Container (ContainerName) ContainerId HasInventoryScheduled (True, False) PrivateKeyAllowed (0-Forbidden, 1-Optional, 2-Required) RemoveSupported (True, False) StorePath Tip: Use the following query to limit the results to only active certificate stores and not include discovery results: approved -eq true
pageReturned	Query	An integer that specifies how many multiples of the returnLimit to skip and offset by before returning results, to enable paging. The default is 1.
returnLimit	Query	An integer that specifies how many results to return per page. The default is 50.
sortField	Query	A string containing the property by which the results should be sorted. Fields available for sorting through the API for the most part match those that appear as sortable columns in the Keyfactor Command Management Portal. The default sort field is ClientMachine.
sortAscending	Query	An integer that sets the sort order on the returned results. A value of 0 sorts results in ascending order while a value of 1 sorts results in descending order. The default is ascending.

Table 314: GET Certificate Stores Response Data

Name

Description

A string indicating the GUID of the certificate store within Keyfactor Command. This ID is automatically set by Keyfactor Command.

ContainerId

An integer indicating the ID of the certificate store's associated certificate store container, if applicable (see GET Certificate Store Containers).

Client Machine

A string containing the client machine name. The value for this will vary depending on the certificate store type. Typically, it is the hostname of the machine on which the store is located, but this may vary. See Adding or Modifying a Certificate Store for more information.

Storepath

A string indicating the path to the certificate store on the target. The format for this path will vary depending on the certificate store type. For example, for a Java keystore, this will be a file path (e.g. /opt/myapp/store.jks), but for an F5 device, this will be a partition name on the device (e.g. Common). See Adding or Modifying a Certificate Store for more information. The maximum number of characters supported in this field is 722.

CertStore Inventory JobId

A string indicating the GUID that identifies the inventory job for the certificate store in the Keyfactor Command database. This will be null if an inventory schedule is not set for the certificate store.

CertStore Type

An integer indicating the ID of the certificate store type, as defined in Keyfactor Command, for this certificate store. Built-in certificates store types are: (0-Javakeystore, 2-PEMFile, 3-F5SSLProfiles,4-IISRoots, 5-NetScaler, 6-IISPersonal, 7-F5WebServer, 8-IISRevoked, 9-F5WebServerREST, 10-F5SSLProfilesREST, 11-F5CABundlesREST, 100-AmazonWebServices, 101-FileTransferProtocol). Any custom extensions for the Keyfactor Universal Orchestrator you add will have certificate store types numbered 102+.

Approved

A Boolean that indicates whether a certificate store is approved (true) or not (false). If a certificate store is approved, it can be used and updated. A certificate store that has been discovered using the discover feature but not yet marked as approved will be false here.

Create IfMissing

A Boolean that indicates whether a new certificate store should be created with the information provided (true) or not (false). This option is only valid for Java keystores and any custom certificate store types you have defined to support this functionality.

Properties

Some types of certificate stores have additional properties that are stored in this parameter. The data is stored in a series of, typically, key value pairs that define the property name and value (see GET Certificate Store Types for more information).

When reading this field, the values are returned as simple key value pairs, with the values being individual values. When writing, the values are specified as objects, though they are typically single values.

For example, on a GET request for a PEM store configured with a separate private key, the contents of this field might be:

"{
  \"privateKeyPath\":\"/opt/app/mystore.key\",
  \"separatePrivateKey\":\"true\"
}"

However, the syntax used when updating the properties sets the value as a key value pair using value as the key. For example, on a POST or PUT request for a PEM store configured with a separate private key, the contents of this field might be:

"{
  \"privateKeyPath\":{\"value\":\"/opt/app/mystore.key\"},
  \"separatePrivateKey\":{\"value\":\"true\"}
}"

An example server properties parameter POST for an F5 or Citrix NetScaler store would contain:

"{
   \"ServerUsername\":{\"value\":{\"SecretValue\":\"KEYEXAMPLE\\\\jsmith\"}},
   \"ServerPassword\":{\"value\":{\"SecretValue\":\"MySuperSecretPassword\"}},
   \"ServerUseSsl\":{\"value\":\"true\"}
}"

An example server properties parameter POST for an F5 or Citrix NetScaler store with the username and password stored as PAM secrets would contain (where the Provider value—1 in this example—is the Id value from GET PAM Providers):

"{
   \"ServerUsername\":{\"value\":{\"Provider\":\"1\",\"Parameters\":{\"SecretId\":\"MyUserID\"}}},
   \"ServerPassword\":{\"value\":{\"Provider\":\"1\",\"Parameters\":{\"SecretId\":\"MyPasswordID\"}}},
   \"ServerUseSsl\":{\"value\":\"true\"}
}"

Note: There are three standard properties that are used for certificate store types that require server credentials (e.g. F5):

ServerUsername
ServerPassword
ServerUseSsl

These replace the separate certificate store server records that existed in previous versions of Keyfactor Command. For legacy support, if credentials are not provided through store properties during creation or editing of a certificate store, Keyfactor Command will attempt to find a certificate store server record and copy the credentials from it into the store properties for future use.

AgentId

A string indicating the Keyfactor Command GUID of the orchestrator for this store.

Agent Assigned

A Boolean that indicates whether there is an orchestrator assigned to this certificate store (true) or not (false).

Container Name

A string indicating the name of the certificate store's associated container, if applicable.

Inventory Schedule

An object indicating the inventory schedule for this certificate store. Show schedule details.

Name

Description

Off

Turn off a previously configured schedule.

Immediate

A Boolean that indicates a job scheduled to run immediately (true) or not (false).

Tip: In some instances, jobs initially scheduled as Immediate will appear on a GET as null.

Interval

A dictionary that indicates a job scheduled to run every x minutes with the specified parameter. Any interval that is selected in the UI will be converted to minutes when stored in the database.

Name	Description
Minutes	An integer indicating the number of minutes between each interval.

For example, every hour:

"Interval": {
   "Minutes": 60
}

Daily

A dictionary that indicates a job scheduled to run every day at the same time with the parameter:

Name	Description
Time	The date and time to next run the job. 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).

For example, daily at 11:30 pm:

"Daily": {
   "Time": "2022-02-25T23:30:00Z"
}

Exactly Once

A dictionary that indicates a job scheduled to run at the time specified with the parameter:

Name	Description
Time	The date and time to next run the job. 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).

For example, exactly once at 11:45 am:

"ExactlyOnce": {
   "Time": "2022-02-27T 11:45:00Z"
}

Tip: In some instances, jobs initially scheduled as Immediate will appear on a GET as ExactlyOnce.

Reenrollment Status

An object that indicates whether the certificate store can use the re-enrollment function with accompanying data about the re-enrollment job. Show reenrollment status details.

Name

Description

Data

A Boolean that indicates whether the certificate store can use the re-enrollment function (true) or not (false).

AgentId

A string indicating the Keyfactor Command GUID of the orchestrator that can re-enroll the certificate store.

Message

A string indicating the reason the certificate store cannot re-enroll, if applicable.

JobProperties

An array containing the unique entry parameters defined for the certificate store type that need to be populated for the certificate. The key is the name of the specific entry 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 CitrixAdc, the key name that is optionally used to associate the certificate with a virtual server is virtualServerName and is returned by GET CertificateStoreTypes like so:

"JobProperties": [ "sniCert", "virtualServerName"]

It can be seen in the Keyfactor Command Management Portal when editing the certificate store type on the Entry Parameters tab.

The setting is referenced using the following format:

"JobProperties": [
   {
      "sniCert":"MyCertificateName",
      "virtualServerName":"MyVirtualServerName"
   }
]

This field is optional.

Custom Alias Allowed

An integer indicating the option for a custom alias for this certificate store.

0—forbidden
1—optional
2—required

Entry Parameters

An array of objects indicating unique parameters that are required when performing management jobs on a certificate store of this type. Show entry parameter details.

Name	Description
Store Type ID	Required. An integer identifying the certificate store type. This is the same ID referenced by the StoreType parameter, above. If you are updating a certificate store type, this field is required.
Name	Required. A string containing the short name of the entry parameter. If you choose to define an entry parameter, this field is required. The name should be entered without spaces.
Display Name	Required. A string containing the full display name of the entry parameter. If you choose to define an entry parameter, this field is required.
Type	Required. A string containing the type of the entry parameter: String Bool MultipleChoice Secret If you choose to define an entry parameter, this field is required.
Required When	An object containing Boolean values indicating the circumstances under which a value is required to be provided for this entry parameter. These are: HasPrivateKey: If set to true, a value must be provided for this field when configuring a management job (either add or remove) if the certificate has an associated private key in Keyfactor Command. This would be the case, for example, when doing a PFX enrollment and adding the resulting certificate to a certificate store. The default is false. OnAdd: If set to true, a value must be provided for this field when configuring an add certificate job. The default is false. OnRemove: If set to true, a value must be provided for this field when configuring a remove certificate job. The default is false. OnReenrollment: If set to true, a value must be provided for this field when configuring a reenrollment job. The default is false.
Depends On	A string containing the name of the parameter on which this parameter depends. This only applies if at least two custom parameters have been created for this certificate store type. This option is used to configure one custom parameter to display only if another custom parameter contains a value.
Default Value	A string containing the default value for the entry parameter. If Type is Multiple Choice, this field should contain a single value that represents the default selection from the provided list (see Options) for this entry parameter. If Type is Boolean, this field should contain true or false. This value is unset by default.
Options	A string containing a comma-separated list of multiple choice options for this entry parameter. This field should only be populated if Type is set to MultipleChoice. This value is unset by default.

For example, to set a multiple choice entry parameter:

"EntryParameter": [
   {
      "StoreTypeId": 111,
      "Name": "ZooAnimal",
      "DisplayName": "Favorite Zoo Animal",
      "Type": "MultipleChoice",
      "RequiredWhen": {
         "HasPrivateKey": false,
         "OnAdd": true,
         "OnRemove": true,
         "OnReenrollment": true
      },
      "DefaultValue": "Penguin",
      "Options": "Tiger,Bear,Giraffe,Lion,Wolf,Penguin,Zebra"
   }
]

This value is unset by default.

Tip: What's the difference between properties (custom fields) and entry parameters?

Properties are about the certificate store definition itself and are static. For example, you might use a property to define the primary node name of an F5 instance. This node name is the same no matter what inventory or management jobs you do with the F5 device(s). Values for properties are entered in the certificate store record when creating or editing the certificate store record.
Entry parameters are about the specific certificate within the certificate store. They are used to send additional information related to the certificate to the server or device that hosts the certificate store when running management jobs for that certificate store. Often this is more fluid information that isn't the same for every use of that certificate store. For example, several virtual servers with separate certificates in the same folder may exist on a NetScaler device. When replacing one certificate, updates may need to be made to only the virtual server that is using the certificate. In this case, the authorized user will be prompted to enter the virtual server name based on an entry parameter. Values for entry parameters are entered at the time a management job is initiated (e.g. adding a certificate to a certificate store).

SetNew Password Allowed

A Boolean that indicates whether the store password can be changed (true) or not (false).

Password

Note: Secret data is stored in the secrets table or a PAM provider and is not returned in responses.

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 11.0

On this page: