Documentation Suite v24.4.2

Submit Search

PUT Certificate Store Types

The PUT /CertificateStoreTypes method is used to update a certificate store type in Keyfactor Command. This method returns HTTP 200 OK on a success with a message body containing a list of certificate store type details.

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

/certificate_stores/modify/

Important: Any previously populated fields that are not submitted with their full existing data using this method will be cleared of their existing data. When using this method, you should first do a GET to retrieve all the values for the record you want to update, enter corrected data into the field(s) you want to update, and then submit all the fields using PUT, including the fields that contain values but which you are not changing.

Note: Certificate store types can only be updated in a very limited way if they are actively in use (there are any certificate stores defined for them). Updates to the Name, ShortName and adding a job type are supported in this case as are additions to the SupportedOperations, but no other updates can be saved.

Table 421: PUT Certificate Store Types Input Parameters

Name In Description

BlueprintAllowed

Body

A Boolean that indicates whether certificate stores of this type will be included when creating or applying blueprints. For more details, see Orchestrator Blueprints. The default is false.

Capability

Body

A string containing a reference name for the certificate store type (e.g. NS for a NetScaler store).

Note: The Capability cannot be changed on an edit if an orchestrator has registered with Keyfactor Command, been approved, and included the certificate store type in its capability list.

CertificateFormat

Body

A string indicating the format for the certificate to deliver to the orchestrator. Supported values are PEM (or 1) and PFX (or 0). The PEM format is required if any hybrid certificates will be delivered to the orchestrators since the PFX format does not support multiple keys.

The value of the CertificateFormat field is also passed as a string to the extension in the orchestrator as the ContentsFormat property of the ManagementJobConfiguration object.

The default is PFX.

Important: The PEM option requires the Keyfactor Universal Orchestrator version 24.4 or later.

CustomAliasAllowed

Body

A string containing the selected certificate store type alias option:

Forbidden: A custom alias is not required and cannot be supplied.
Optional: A custom alias is optional.
Required: A custom alias is required.

The certificate store alias serves as an identifier for the certificate in the store. Depending on the type of store, it may be a file name, a certificate thumbprint, a string reference, or some other information. Some types of stores may not support associating an alias with the certificate (e.g. IIS trusted root).

The default is Forbidden.

EntryParameters

Body

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
StoreTypeID	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.
DisplayName	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. Note: This field cannot be modified on an edit.
RequiredWhen	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.
DependsOn	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.
DefaultValue	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:

Copy

"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).

JobProperties

Body

An array of strings defining properties that are required when performing management jobs on a certificate store of this type.

Note: The JobProperties parameter has been deprecated and replaced by EntryParameters. New implementations should use EntryParameters. JobProperties is retained to maintain backwards compatibility.

LocalStore

Body

A Boolean that indicates whether the store is local to the orchestrator machine (true) as, for example, JKS and PEM stores managed by the Keyfactor Java Agent or remote (false) as, for example, IIS stores managed by the Keyfactor Universal Orchestrator. The default is false.

Name Body Required. A string containing the full name of the certificate store type. A unique value must be supplied.

PasswordOptions

Body

An object indicating options for the password in the certificate store type. Show password option details.

Name

Description

EntrySupported

A Boolean that indicates whether entry of a password for the certificate in the certificate store is allowed (true) or not (false). The default is false.

StoreRequired

A Boolean that indicates whether entry of a password on the certificate store as a whole is required (true) or not (false). The default is false.

Style

A string containing the style of password:

Default: Keyfactor Command will randomly generate a password.
Custom: Allow a password to be entered and authenticated when enrolling for a certificate through Keyfactor Command when installing to a store of this type. The Custom option can be selected only if the Allow Custom Password in the Application Settings, is equal to True. For more details, see Application Settings: Enrollment Tab.

The default value is Default.

PowerShell

Body

A Boolean that indicates whether jobs for the store type are implemented using PowerShell (true) instead of a .NET class or not (false). The default is false.

PrivateKeyAllowed

Body

A string containing the option for private key requirements for certificates stored in stores with this certificate store type:

Forbidden: Private key is not required; generally, applies to trust stores (e.g. Root CA certificates).
Optional: Private key is optional; applies to store types that could represent either a Trust Store or End-Entity Store.
Required: Private key is required; applies to stores that hold an End-Entity Certificate (server or client authorization).

The default value is Forbidden.

Properties

Body

An array of objects indicating unique parameters for the certificate store type. In the Keyfactor Command Management Portal these are known as Custom Fields. Show property details.

Name	Description
StoreTypeID	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 property. If you choose to define a property, this field is required.
DisplayName	Required. A string containing the full display name of the property. If you choose to define a property, this field is required.
Type	Required. A string containing the type of the property: String Bool MultipleChoice Secret If you choose to define a property, this field is required. Note: This field cannot be modified on an edit.
DependsOn	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.
DefaultValue	A string containing the default value(s) of the parameter. If Type is Multiple Choice, this field should contain a comma-separated list of multiple choice options for this parameter. If Type is Boolean, this field should contain true or false.
Required	A Boolean that indicates whether the parameter is required (true) or not (false).

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.

For example, to set a multiple choice property:

Copy

"Properties": [
   {
      "StoreTypeId": 111,
      "Name": "Pets",
      "DisplayName": "Popular Pets",
      "Type": "MultipleChoice",
      "DependsOn": "",
      "DefaultValue": "Cat,Dog,Fish,Rat,Mouse",
      "Required": false
   }
]

This value is unset by default.

ServerRequired

Body

A Boolean that indicates whether server access is required for adding certificate stores for this certificate store type (true) or not (false). If set to true, a user will be prompted for a username and password to connect to the remote server. The default is false.

ShortName Body Required. A string containing the short name assigned to the certificate store type. A unique value must be supplied with a maximum of 10 characters.

StorePathType

Body

A string containing the selected store type:

Freeform: Users are required to enter a path defining the certificate store location.
Fixed: A store path does not apply, generally one store per device (e.g. IIS).
MultipleChoice: Allow a comma separated list of options to be entered that users will be able to select from when defining the certificate store location.

This value is unset by default.

StorePathValue

Body

A string containing the value(s) for the certificate store path if the StorePathType is set to Fixed or Multiple Choice.

Multiple choice values should be provided in a comma-delimited list like so:

"StorePathValue": "Apple,Cherry,Peach,Pear"

This value is unset by default.

StoreType

Body

Required. An integer indicating the Keyfactor Command reference ID for the certificate store type.

SupportedOperations

Body

An object containing Boolean values that indicate whether the certificate store type is enabled for the following functions:

Add
Create
Discovery
Enrollment
Remove

The default for each value is false.

Table 422: PUT Certificate Store Types Response Data

Name

Description

BlueprintAllowed

A Boolean that indicates whether certificate stores of this type will be included when creating or applying blueprints. For more details, see Orchestrator Blueprints.

Capability

A string containing a reference name for the certificate store type (e.g. NS for a NetScaler store).

CertificateFormat

The value of the CertificateFormat field is also passed as a string to the extension in the orchestrator as the ContentsFormat property of the ManagementJobConfiguration object.

Important: The PEM option requires the Keyfactor Universal Orchestrator version 24.4 or later.

CustomAliasAllowed

A string containing the selected certificate store type alias option:

Forbidden: A custom alias is not required and cannot be supplied.
Optional: A custom alias is optional.
Required: A custom alias is required.

DiscoveryJobType

A GUID identifying the job type for discovery jobs.

EnrollmentJobType

A GUID identifying the job type for reenrollment jobs.

EntryParameters

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
Name	A string containing the short name of the entry parameter.
DisplayName	A string containing the full display name of the entry parameter.
Type	A string containing the type of the entry parameter: String Bool MultipleChoice Secret
RequiredWhen	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. OnAdd: If set to true, a value must be provided for this field when configuring an add certificate job. OnRemove: If set to true, a value must be provided for this field when configuring a remove certificate job. OnReenrollment: If set to true, a value must be provided for this field when configuring a reenrollment job.
DependsOn	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.
DefaultValue	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.
Options	A string containing a comma-separated list of multiple choice options for this entry parameter.

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).

ImportType

An integer that indicates the import type for the certificate store type. The ID is automatically assigned by Keyfactor Command and generally matches the StoreType for custom certificate store types.

InventoryEndpoint

A string containing the orchestrator endpoint to which inventory updates are sent.

InventoryJobType

A GUID identifying the job type for inventory jobs.

JobProperties

An array of strings defining properties that are required when performing management jobs on a certificate store of this type.

LocalStore

ManagementJobType

A GUID identifying the job type for management jobs.

Name

A string containing the full name of the certificate store type.

PasswordOptions

An object indicating options for the password in the certificate store type. Show password option details.

Name

Description

EntrySupported

A Boolean that indicates whether entry of a password for the certificate in the certificate store is allowed (true) or not (false).

StoreRequired

A Boolean that indicates whether entry of a password on the certificate store as a whole is required (true) or not (false).

Style

A string containing the style of password:

Default: Keyfactor Command will randomly generate a password.
Custom: Allow a password to be entered and authenticated when enrolling for a certificate through Keyfactor Command when installing to a store of this type. The Custom option can be selected only if the Allow Custom Password in the Application Settings, is equal to True. For more details, see Application Settings: Enrollment Tab.

PowerShell

A Boolean that indicates whether jobs for the store type are implemented using PowerShell (true) instead of a .NET class or not (false).

PrivateKeyAllowed

A string containing the option for private key requirements for certificates stored in stores with this certificate store type:

Forbidden: Private key is not required; generally, applies to trust stores (e.g. Root CA certificates).
Optional: Private key is optional; applies to store types that could represent either a Trust Store or End-Entity Store.
Required: Private key is required; applies to stores that hold an End-Entity Certificate (server or client authorization).

Properties

An array of objects indicating unique parameters for the certificate store type. In the Keyfactor Command Management Portal these are known as Custom Fields. Show property details.

Name	Description
Name	A string containing the short name of the property.
DisplayName	A string containing the full display name of the property.
Type	A string containing the type of the property: String Bool MultipleChoice Secret
DependsOn	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.
DefaultValue	A string containing the default value(s) of the parameter. If Type is Multiple Choice, this field should contain a comma-separated list of multiple choice options for this parameter. If Type is Boolean, this field should contain true or false.
Required	A Boolean that indicates whether the parameter is required (true) or not (false).

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

ServerUsername
ServerPassword
ServerUseSsl

ServerRequired

ShortName

A string containing the short name assigned to the certificate store type.

StorePathValue

A string containing the value(s) for the certificate store path.

StoreType

An integer indicating the Keyfactor Command reference ID for the certificate store type. The ID is automatically assigned by Keyfactor Command.

SupportedOperations

An object containing Boolean values that indicate whether the certificate store type is enabled for the following functions:

Add
Create
Discovery
Enrollment
Remove

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

An API is 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 Keyfactor Command, it refers to the workflow builder, which allows you to automate event-driven tasks such as when a certificate is requested, revoked or found in a certificate store. 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 v24.4.2

On this page: