POST SSHCertificates/Request

Creates an SSH certificate to enhance security for client or host SSH keys. This endpoint allows a CA to issue an SSH Certificate with an expiration date. Then, your local CA signs the client's public key. SSH Protect manages the certificate and keys. You can also get an SSH Certificate via the vCert sshenroll command. For more information, see https://github.com/Venafi/vcert/releases.

Once you request a certificate, you can monitor the status by calling POST SSHCertificates/Retrieve. SSH certificates, which match machine requirements, grant access to that machine. So you no longer need to add and remove users to each system.

TIP  If you want a TLS X.509 certificate, call POST Certificates/Request instead.

Prerequisites

Requirements

  • Permissions

    • The caller must have View permission and Create permission to the CA issuance template.

    • If the caller passes CADN and PolicyDN, the caller must have View permission and Create permission to the Policy folder for the SSH certificate.

  • Token scope:  SSH:Manage

Headers

  • Content type: Content-Type:application/json.

  • Token: The bearer access token that you received. For example, Authorization:Bearer 4MyGeneratedBearerTknz==. For more information, see Passing a bearer token in your API calls.

Parameters

Many values originate from the SSH Certificate Issuance Template. To see defaults and options, call POST SSHCertificates/Template/Retrieve.

Input parameters

Name

Description

ProcessingTimeout

(Optional) The maximum time the server will hold the connection that is waiting for certificate issuance before returning a Status of PendingIssue. Specify a value between 0 and 180 seconds (3 minutes).

IncludeCertificateDetails

(Optional) To include details about the issued certificate, such as Principals, specify true. Otherwise the default is false, and certificate details are excluded.

IncludePrivateKeyData

(Optional) Applies only to a service-generated keypair. To include the generated private key data, specify true. The default is true.

PrivateKeyPassphrase

(Optional) Applies only to a service-generated keypair. The passphrase that wraps the generated private key before it is returned in the response.

CADN

The Distinguished Name (DN) of the template to use for signing. Specify the correct template. For example: \\VED \\Certificate Authority\\SSH\\Templates\\myhost_template.

  • If you want a host certificate and a host key, specify a template that supports Type:Host.
  • If you have a client certificate and client key, specify a template that supports Type:Client.

DestinationAddress

(Optional) The destination host where the certificate will authenticate. Specify a Fully Qualified Domain name (FQDN) or IP address.

Extensions

(Optional) Case sensitive. Valid only for client certificates. A set of key-value pairs that contain certificate extensions from the CA template. The template AllowedToRequestExtensions value must be true. Either specify common sshd extensions, custom extensions. or both. Possible values:

  • permit-X11-forwarding
  • permit-agent-forwarding
  • permit-port-forwarding
  • permit-pty permit-user-rc
  • (custom example) login@github.com: alice@github.com

ForceCommand

(Optional) Add a command to the certificate. The command runs after a successful login. Specify force or source keys and a value or regex expression. The template AllowedToRequestForceCommand must be true and the value must match AllowedForceCommandPatterns. For example: /usr/scripts/db_backup.sh.

KeyId

The identifier that matches the issuance template naming pattern in Allowed Certificate Identifier. For auditing and tracking purposes.

ObjectName

(Optional) The friendly name of the SSH Certificate object. Omit this parameter, if KeyId is the friendly name. If the Certificate object is already present in the Policy folder, the old certificate archives and the CA issues a new certificate.

Origin

(Optional) Additional information, such as the name and version of the calling application, that describes the source of this request. The default is Web SDK.

PolicyDN

(Optional) The DN of a Policy folder where the SSH Certificate object will be created. Omit this parameter, if you want the template CertificateDestinationDn value.

Principals

(Optional) An array of names for which the requested certificate will be valid. The value must match AllowedPrincipalsPatterns from the template.

PublicKeyData

Optional) A public key that has the OpenSSH format. Omit this parameter, if you want SSH Protect to generate a new key pair. The embedded key algorithm must match Key Algorithm from the template. Otherwise, Error Code 29 shows a non-compliant key algorithm. The Comment section at the end is optional.

SourceAddresses

(Optional) An array of one or more valid IP or Classless Inter-Domain Routing (CIDR) addresses that can use the certificate. Valid only when the template AllowedToRequestSourceAddresses is true. For example: ["192.168.1.1/24", "10.0.0.1"\].

ValidityPeriod

(Optional) The certificate expiration time. Omit this value if you want the template ValidityPeriod value. When setting an expiration, follow your company's best practices. One of the following formats:

  • Relative time: The format is space delimited in w (weeks) d (days) h (hours), m (minutes), s (seconds). For example: 1w 2d 3h 4m 50s.

  • Universal Time Coordinated (UTC): One of these formats:

    • Calendar date: Use the yyyyMMdd format. For example, 20251217.
    • Both date and time: Use the yyyyMMddHHmmss format. For example, 20251217235900.

Returns

For a set of working examples, see Request an SSH certificate for host authentication.

IMPORTANT  After this API call runs, make sure the client or hosts can use the certificate. Use the prerequisites to confirm the OpenSSH service is operating properly on every remote server.

Response description

Name

Description

HTTP 200

For valid requests, this call returns HTTP 200 and the following data in the message body:

  • DN: The DN of the SSH Certificate object. If the request is invalid, the value is null.

  • Guid: The unique identifier of the certificate. If the request is invalid, the value is null.

  • ProcessingDetails: The progress of SSH certificate issuance:
    • Status: Appears only if the call succeeded. For more information, see SSHCertificates status.

    • StatusDescription: Additional information, if any.

  • Response: The SSH SshWebResponse object.

HTTP 202

If the VED service is unavailable, this call returns HTTP 202 Accepted and the following data in the message body:

  • DN: The DN of the SSH Certificate object. If the request is invalid, the value is null.

  • Guid: The unique identifier of the certificate. If the request is invalid, the value is null.

  • ProcessingDetails: The progress of SSH certificate issuance:
    • Status: Pending.

    • StatusDescription: Additional information, if any.

  • Response: The SSH SshWebResponse object.

HTTP 400

For invalid parameters or rejected requests, this call returns HTTP 400 Bad Request and Response: The SSH SshWebResponse object.

HTTP 404

For requests that contain invalid data, this call returns HTTP 404 Not Found and Response: The SSH SshWebResponse object.

Example: Request an SSH Certificate; generate and sign the public key

IMPORTANT  The correct endpoint name is SSHCertificates, not SSH/Certificates.

Request

POST https://tpp.venafi.example/vedsdk/SSHCertificates/Request 
{
   "PolicyDN":"\\VED\\Policy\\My Issued Certificates Folder",
   "CADN":"\\VED\\Certificate Authority\\SSH\\Templates\\template_host",
   "KeyId":"host_key_id",
   "ObjectName":"host_key_id",
   "Principals":[
      "jhost129"
   ],
   "DestinationAddress":"db.example.com",
   "ValidityPeriod":"1w 2d 3h 4m 50s",
   "SourceAddresses":[
      "192.168.1.1/24",
      "10.0.0.1"
   ],
   "ForceCommand":"force",
   "Extensions":{
      "permit-pty":"",
      "permit-port-forwarding":"",
      "login@github.com":"alice@github.com"
   },
   "ProcessingTimeout":120,
   "IncludeCertificateDetails":true,
   "IncludePrivateKeyData":true,
   "PrivateKeyPassphrase":"MyPassphrasethatmeetsCoRequirements"
}

Response

HTTP/1.1 200 OK
{
   "DN":"\\VED\\Policy\\My Issued Certificates Folder\\host_key_id",
   "Guid":"{5508941d-5922-406f-be73-2207af1853a0}",
   "ProcessingDetails":{
      "Status":"Pending Issue",
      "StatusDescription":null
   },
   "Response":{
      "ErrorMessage":"",
      "Success":true
   }
}