POST CSR Generation Generate

The POST /CSRGeneration/Generate method is used to generate an X.509Closed X.509 defines public-key certificates that bind a public key to an identity. As profiled in RFC 5280, it’s the most common certificate/CA standard for TLS (web auth), client logins, S/MIME email, VPNs, and signed documents. Certificate Signing RequestClosed A CSR or certificate signing request is a block of encoded text that is submitted to a CA when enrolling for a certificate. When you generate a CSR within Keyfactor Command, the matching private key for it is stored in Keyfactor Command in encrypted format and will be married with the certificate once returned from the CA. in PKCS #10Closed The standard request format for X.509 certificates (RFC 2986). A PKCS #10 CSR includes the subject (identity) and public key, can carry requested X.509 v3 extensions via an extensionRequest (e.g., Subject Alternative Name), and is self-signed with the private key to prove possession; it isn’t a certificate, but the input you submit to a CA for issuance. format. This method returns HTTP 200 OK on a success with a message body containing the text of the CSRClosed A CSR or certificate signing request is a block of encoded text that is submitted to a CA when enrolling for a certificate. When you generate a CSR within Keyfactor Command, the matching private key for it is stored in Keyfactor Command in encrypted format and will be married with the certificate once returned from the CA. file created.

This method generates a private keyClosed Private keys are used in cryptography (symmetric and asymmetric) to encrypt or sign content. In asymmetric cryptography, they are used together in a key pair with a public key. The private or secret key is retained by the key's creator, making it highly secure. and stores it in the Keyfactor Command database. When you use the CSR resulting from this method to enroll for a certificate through Keyfactor Command (see POST Enrollment CSR), the resulting certificate is married together with the stored private key and may then be download with private key (see POST Certificates Recover).

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

/certificates/enrollment/csr_generation/

Note:  This endpointClosed An endpoint is a URL that enables the API to gain access to resources on a server. no longer includes the CSRFilePath return value in the response from the APIClosed 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. call. Code separate from the API should be used to handle receipt of the CSR and placement on the file system.
Note:  The following algorithms are supported as the primary key for enrollment:
  • SLH-DSA
    • SLH-DSA-SHA2-128s
    • SLH-DSA-SHA2-128f
    • SLH-DSA-SHA2-192s
    • SLH-DSA-SHA2-192f
    • SLH-DSA-SHA2-256s
    • SLH-DSA-SHA2-256f
    • SLH-DSA-SHAKE-128s
    • SLH-DSA-SHAKE-128f
    • SLH-DSA-SHAKE-192s
    • SLH-DSA-SHAKE-192f
    • SLH-DSA-SHAKE-256s
    • SLH-DSA-SHAKE-256f
Important:  An ML-DSA or SLH-DSA primary key cannot be used for a hybrid certificateClosed A certificate that uses a non-PQC (Post-Quantum Cryptography) primary key paired with an alternative key algorithm such as ML-DSA-44, ML-DSA-65, or ML-DSA-87 for enhanced security and quantum resistance. (a certificate with both a primary and alternative key).

The following Post-Quantum CryptographyClosed Cryptographic algorithms designed to be secure against the potential capabilities of quantum computers, which could break traditional encryption methods. (PQCClosed Cryptographic algorithms designed to be secure against the potential capabilities of quantum computers, which could break traditional encryption methods.) key algorithms are supported as the alternative key for enrollment:

  • ML-DSA
    • ML-DSA-44
    • ML-DSA-65
    • ML-DSA-87
  • SLH-DSA
    • SLH-DSA-SHA2-128s

    • SLH-DSA-SHA2-128f

    • SLH-DSA-SHA2-192s

    • SLH-DSA-SHA2-192f

    • SLH-DSA-SHA2-256s

    • SLH-DSA-SHA2-256f

    • SLH-DSA-SHAKE-128s

    • SLH-DSA-SHAKE-128f

    • SLH-DSA-SHAKE-192s

    • SLH-DSA-SHAKE-192f

    • SLH-DSA-SHAKE-256s

    • SLH-DSA-SHAKE-256f

The availability of these algorithms depends on the following factors:

When configuring key information policies at the enrollment pattern level, only key sizes that are valid for the selected algorithm will be available. These sizes are determined by the system-wide policy, enrollment pattern policy, and the supported key sizes in the template configuration. For PFXClosed A PFX file (personal information exchange format), also known as a PKCS#12 archive, is a single, password-protected certificate archive that contains both the public and matching private key and, optionally, the certificate chain. It is a common format for Windows servers. enrollment and CSR generation, you must submit a valid KeyType, and KeyLength or Curve as applicable, for the request.

Table 473: POST CSR Generation Generate Input Parameters

Name In Description
AlternativeCurve Body

A string indicating the elliptic curve for the requested alternate key.

This field is in the endpoint for future support. CSR generation with ECC as a secondary key is not supported at this time.
AlternativeKeyLength Body

An integer indicating the desired alternative key size of the certificate to be requested with the CSR.

For the currently supported AlternativeKeyType values, the supported AlternativeKeyLength values are 0 or null.
AlternativeKeyType Body

A string indicating the desired alternative key encryption algorithm of the certificate to be requested with the CSR. Supported key algorithms are:

  • ML-DSA-44

    OID: 2.16.840.1.101.3.4.3.17

  • ML-DSA-65

    OID: 2.16.840.1.101.3.4.3.18

  • ML-DSA-87

    OID: 2.16.840.1.101.3.4.3.19

A CSR with a secondary key using a Post-Quantum Cryptography (PQC) key algorithm can be used to enroll for a hybrid certificate (a certificate with two key pairs).
Curve Body

A string indicating the elliptic curve for the requested primary key. ECC curves must be specified using the OID for the ECC algorithm. Keyfactor recommends using one of the most commonly used ECC curves when possible, if a specific alternate curve is not required. Common curves include:

  • P-256/ prime256v1/ secp256r1 - 1.2.840.10045.3.1.7

  • P-384/secp384r1 - 1.3.132.0.34

  • P-521/secp521r1 - 1.3.132.0.35

ClosedShow named curves and associated OIDs.

If this value is not supplied and the KeyType is ECC, the value will be derived from the KeyLength if the length provided matches one of the default curves (P-256, P-384, or P-521).
Key Length Body

Required in some cases. An integer indicating the desired key size of the certificate to be requested with the CSR. Supported key sizes are:

  • 255
  • 256
  • 384
  • 448
  • 521
  • 2048
  • 3072
  • 4096
  • 8192

This value is required only if KeyType = RSA.
KeyType Body

Required. A string indicating the desired primary key encryption algorithm of the certificate to be requested with the CSR. Supported key algorithms are:

  • RSA

  • ECC

  • Ed448

  • Ed25519
SANs Body

An object that contains the elements for Keyfactor Command to use when generating the subject alternative name (SAN) for the certificate requested by the CSR, each of which is supplied as an array of strings. ClosedShow SAN key values.

For example:

Copy 
"SANs": {
   "dns": [
      "dnssan1.keyexample.com",
      "dnssan2.keyexample.com",
      "dnssan3.keyexample.com"
   ],
   "ip": [
      "192.168.2.73"
   ]
}
Subject Body

Required. A string containing the subject name of the certificate to be requested with the CSR using X.500 format for the full distinguished name (DN). For example:

Copy 
"Subject": "CN=websrvr14.keyexample.com, OU=IT, O=\"Key Example, Inc.\", L=Independence, ST=OH, C=US"

ClosedShow subject name fields.

Template Body A string indicating the template to use when generating the CSR. This field is optional.

If both the Template and EnrollmentPatternId are provided, the settings from the enrollment pattern take precedence.

Important:  The template must be configured with at least one enrollment pattern in order to be used (see POST Enrollment Patterns).
Note:  This parameter is considered deprecated and may be removed in a future release.
Important:  The template will not be included in the CSR. It is referenced in order to retrieve key and other information to help populate the CSR. In addition, the CSR generation function supports regular expressions for both subject parts and SANs at the template level. The regular expressions set at the template level take precedence over the system-wide regular expressions.

If you choose to select a template during CSR generation, you must choose the same template during CSR enrollment, because the CSR will contain elements from the template that may conflict with other template configurations.
Enrollment Pattern Id Body

An integer indicating the enrollment pattern to use when generating the CSR. The enrollment pattern must have been configured in Keyfactor Command to support CSR generation. If this value is not provided, the default enrollment pattern defined for the template provided in the request (see the Template parameter) will be used, if applicable. This field is optional.

If both the Template and EnrollmentPatternId are provided, the settings from the enrollment pattern take precedence.

Important:  The enrollment pattern will not be included in the CSR. It is referenced in order to retrieve key and other information to help populate the CSR. In addition, the CSR generation function supports regular expressions for both subject parts and SANs at the enrollment pattern level. The regular expressions set at the enrollment pattern level take precedence over the system-wide regular expressions.

If you choose to select an enrollment pattern during CSR generation, you must choose the same enrollment pattern during CSR enrollment, because the CSR will contain elements from the enrollment pattern that may conflict with other enrollment pattern configurations.

Table 474: POST CSR Generation Generate Response Data

Name Description
CSR The text of the CSR in PEM format.
Tip:  See the Keyfactor API Reference and Utility which provides a utility through which the Keyfactor API endpoints can be called and results returned. It is intended to be used primarily for validation, testing and workflowClosed 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.