POST SSHCertificates/Retrieve

Returns the status of an SSH Certificate. You can also get the status via the vCert sshpickup command. For more information, see https://github.com/Venafi/vcert/releases.

Requirements

  • Permissions: 

    • The certificate you want has a client-generated key pair: The caller must have View permission, and Read permission to retrieve the certificate.

    • The certificate you want has a service-generated key pair: The caller must have View permission, and Read permission. To get the corresponding private key, the caller must have Private Key Read permission to the Certificate object.

  • 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

Input parameters

Name

Description

DN

The Distinguished Name (DN) of the certificate in the Policy folder. To get the value, use the response from POST SSHCertificates/Request.
Guid The unique identifier of the SSH certificate. o get the value, use the response from POST SSHCertificates/Request. For example, {2b6b673f-2c55-46fc-935a-5836eae9b9db}.
IncludeCertificateDetails (Optional) Whether or not the response should include CertificateDetails: true: Return details such as Principals. Otherwise, false: Default. Omit details.
IncludePrivateKeyData (Optional) Whether or not the response should include PrivateKeyData: true: Return the prive key in the OPENSSH format. Otherwise, false: Default. Omit details.
PrivateKeyPassphrase (Optional) The passphrase that wraps the generated private key before it is returned in the API response. Applies only to a service-generated keypair.

Returns

Response description

Name

Description

HTTP 200

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

  • CADN: The DN of the CA that signed the requested certificate.

  • CAGuid: The unique identifier of the CA that signed the certificate.

  • CertificateData: Base-64 encoded string of the SSH certificate. Applications can directly consume the data.

  • CertificateDetails: Appears only when IncludeCertificateDetails is true.

    • CAFingerprintSHA256: Base-64 encoded SHA256 hash of the public key of the CA used for signing the requested certificate. Padding characters from the end are trimmed.

    • CertificateFingerprintSHA256: Base-64 encoded SHA256 hash of the issued certificate. Padding characters from the end are trimmed.

    • CertificateType: Whether the issued certificate is for client or host authentication.

    • Extensions: Sets of key/value pairs of common or custom certificate extensions.

    • ForceCommand: The command runs after a successful login.

    • KeyID: The name of the issued certificate.

    • KeyType: The type of the key.

    • Principals: An array of principal users of the issued certificate.

    • PublicKeyFingerprintSHA256: Base-64 encoded SHA256 hash of the public key. Padding characters from the end are trimmed.

    • SerialNumber: The certificate serial number.

    • SourceAddresses: An array of one or more valid IP or Classless Inter-Domain Routing (CIDR) addresses that can use the certificate.

    • ValidFrom: The timestamp when the certificate becomes valid. The value is in the Epoch format of the Universal Time Coordinated (UTC).

    • ValidTo: The timestamp when the certificate expires. The value is in the Epoch format.

  • DN: The Policy folder location and name of the certificate.
  • Guid: The unique identifier of the certificate.

  • KeyID: The certificate name.

  • PrivateKeyData: Appears only when IncludePrivateKeyData is true. If PrivateKeyPassphrase is in the request, the key is encrypted. Applications can directly consume the private key. However, private keys are valid only with the corresponding SSH certificate.

  • ProcessingDetails: If Success is false, the values are null. Otherwise, the progress of SSH certificate issuance:

    • Status: The current status of the SSH certificate. Issued, Pending, or Rejected.

    • StatusDescription: The status reason, if any.

  • PublicKeyData: Appears only when IncludePrivateKeyData is true. The public key in base-64 encoded OpenSSH format. Applications can directly consume the public key. However, the public and private keys are valid only with the corresponding SSH certificate.

  • RequestDetails: Audit information about the SSH certificate request.

    • OriginatingIP: The requestor's IP address.
    • RequestedBy: The identity of a person or application that requested the certificate.

  • Response: The SSH SshWebResponse object.

HTTP 400

For invalid parameters or rejected requests, this call returns HTTP 400 Bad Request and Error.

HTTP 404

For requests that contained missing parameters or an invalid data, this call returns HTTP 404 Not Found and the following data in the message body:

  • DN: null

  • Guid: null

  • ProcessingDetails:

    • Status: null

    • StatusDescription: null

  • RequestDetails:

    • OriginatingIP: null
    • OriginatingIP:null
    • RequestedBy: null

  • Response: The SSH SshWebResponse object.

Example: Find the status of a certificate; include certificate details

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

Request

POST https://tpp.venafi.example/vedsdk/SSHCertificates/Retrieve
Authorization:Bearer 4MyGeneratedBearerTknz==
{
   "DN":"\\VED\\Policy\\My Issued Certificates Folder\\HostCert",
   "Guid":"{d8e208c2-bcfb-4e06-b10d-2b32324b4a42}",
   "IncludeCertificateDetails":true,
   "IncludePrivateKeyData":true
}

Response

HTTP/1.1 200 OK
{
   "CADN":"\\VED\\Certificate Authority\\SSH\\Templates\\template_host",
   "CAGuid":"{1360805a-d9a6-4a59-a0e5-2be0ae0594f0}",
   "CertificateData":"ssh-rsa-cert-v01@openssh.com AAAAHHNz...my_key_id",
   "CertificateDetails":{
      "CAFingerprintSHA256":"BqBhBXCqv95NgtLZb5NzZ3qFMRRjPdVIcUNW1kQNIBg",
      "CertificateFingerprintSHA256":"SOYf0BIIhyy/fS2/G5/HhFw6hUSB1ak49Oq2oCg2Zpg",
      "CertificateType":"client",
      "Extensions":{
         "permit-pty":"",
         "permit-user-rc":""
      },
      "ForceCommand":"force",
      "KeyID":"my_key_id",
      "KeyType":"ssh-rsa-cert-v01@openssh.com",
      "Principals":[
         "jhost129root"
      ],
      "PublicKeyFingerprintSHA256":"vhHIw9UR7R9Z/s9UN5g5wH+LslXr3zMvcBWjJfj7pyU",
      "SerialNumber":"17233466579721295466",
      "SourceAddresses":[
         "192.168.1.1/24",
         "10.0.0.1"
      ],
      "ValidFrom":1638220831,
      "ValidTo":1639009521
   },
   "DN":"\\VED\\Policy\\My Issued Certificates Folder\\HostCert",
   "Guid":"{d8e208c2-bcfb-4e06-b10d-2b32324b4a42}",
   "PrivateKeyData":"-----BEGIN OPENSSH PRIVATE KEY-----\nb3BlbnNz...\n-----END OPENSSH PRIVATE KEY-----\n",
   "ProcessingDetails":{
      "Status":"Issued",
      "StatusDescription":null
   },
   "PublicKeyData":"ssh-rsa AAAAB3Nz...= my_key_id",
   "RequestDetails":{
      "DestinationAddress":"db.example.com",
      "OriginatingIP":"10.100.252.6",
      "RequestedBy":"local:admin"
   },
   "Response":{
      "ErrorMessage":"",
      "Success":true
   }
}