POST SSHCertificates/Template/Retrieve

Returns information about an SSH CA template.

Requirements

  • Permissions: The caller must have View permission and Read permission to the CA issuance template.

  • 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

(Optional) The Distinguished Name (DN) of the SSH Certificate Issuance Template. Specify DN, Guid, or both. To get the value from the Platform Policy tree, switch to the Certificate Authority Templates folder. For example: \\VED\\Certificate Authority\\SSH\\Templates\\template_client.

'Location of Certificate Issuance template

Guid

(Optional) he unique identifier of the template. Specify DN, Guid, or both.. To get the value, open the template. For example: {5ae4cea0-13e0-4698-87b0-12a10361a756}.

Location of GUID

IncludeCAKeyPairDetails (Optional) true: Show additional details, including the public key, in CAKeyPair. false: Show only CAKeyPairDN and CAKeyPairGuid. Default is true.

Returns

Response description

Name

Description

HTTP 200 on Success

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

  • API Client: The template settings for the Web SDK caller:

    • AllowedToRequestCertificateIdentifier: true: allow the caller to override the Key ID. Otherwise, false allows only template defaults.
    • AllowedToRequestExtensions: true: Allow the caller to override Extensions. Otherwise, false allows only template defaults.
    • AllowedToRequestForceCommand: true: Allow the caller to override ForceCommand. Otherwise, false allows only template defaults.
    • AllowedToRequestPrincipals: true: Allow the caller to override Principals. Otherwise, false allows only template defaults.
    • AllowedToRequestSourceAddresses: true: Allow the caller to override SourceAddresses. Otherwise, false allows only template defaults.
  • AccessControl: The set of controls that apply whenever clients request a certificate via this template:

    • AllowedCertificateIdentifierPatterns: An array of regex patterns for the Key ID.
    • AllowedExtensions: An array of standard and custom extensions allowed to be requested. Example permit-pty, permit-port-forwarding, login@github.com.
    • AllowedForceCommandPatterns: An array of regex patterns for commands to execute after a successful login.
    • AllowedPrincipalsPatterns: An array of regex patterns to use to validate the requested principals.
    • AllowedSourceAddresses: An array of one or more valid IP, Classless Inter-Domain Routing (CIDR) addresses, or FQDNs used to validate the requested source addresses.
    • DefaultCertificateIdentifier: The default Key to use when API clients omit the KeyId during certificate requests.
    • DefaultExtensions: An array of default key-value pairs to use when API clients omit Extensions during certificate requests.
    • DefaultForceCommand: The default Key to use when API clients omit the ForceCommand during certificate requests.
    • DefaultPrincipals: An array of default SSH accounts use when API clients omit Principals during certificate requests.
    • DefaultSourceAddresses: An array of default SSH accounts use when API clients omit SourceAddresses during certificate requests.
  • CAKeyPairGuid: The unique identifier of the template.

  • CAKeyPairDN: Data about the public and private CA key pair. This information also appears in the Key Pairs folder of the Certificate Authority tree. Appears only when IncludeCAKeyPairDetails is true:

    • CreatedOn: The date the key pair was created.
    • DN: The DN of the public and private key pair.
    • FingerprintSHA256: The CA fingerprint.
    • Guid: The unique identifier of the key pair.
    • KeyAlgorithm: The key algorithm.
    • Name: The key pair name.

    • PublicKeyData: The public key of the trusted CA for this template. The key is in the OpenSSH format.
  • Certificate: Information this template provides to all SSH certificates that use the template:

    • AllowedPrivateKeyAlgorithms: An array of algorithms of the keys that can be sent for signing. For example, ECCP521.
    • AllowedPrivateKeyReuse: true:. Reuse certificate private key. false: Certificate private key cannot be re-used.
    • CertificateDestinationDn: The DN of the Policy folder where issued certificates will be stored by default.
    • DefaultPrivateKeyAlgorithm: The key algorithm and size/curve the service uses to generate keys.
    • SignatureHashingAlgorithm: The hashing algorithm for signing certificates.
    • Type: The Client or Host certificates that this template issues.
    • ValidityPeriod: The maximum amount of time before the SSH certificate expires. For example, if the value is 4h, the certificate is valid four hours.
  • Contacts: An array of identities for users or groups who receive notifications about events pertaining to the template.
  • CreatedOn: The creation date of the template.
  • DN: The DN of the template object.
  • Guid: The unique identifier of the template.
  • Name: The template name.
  • Response: The SSH SshWebResponse object.

HTTP 400

For invalid parameters or rejected requests, this call returns HTTP 400 Bad Request and the following message body:

HTTP 404

For requests that contain invalid data, this call returns HTTP 404 Not Found, and the following data in the message body:

Example: Determine what type of SSH Certificates a CA can issue

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

Request

POST https://tpp.venafi.example/vedsdk/SSHCertificates/Template/Retrieve				
{
   "DN":"\\VED\\Certificate Authority\\SSH\\Templates\\template_host",
   "Guid":"{44eabcd7-7a56-4beb-8f84-f4c4b39914e8}",
   "IncludeCAKeyPairDetails":true
}

Response

HTTP/1.1 200 OK
{
   "APIClient":{
      "AllowedToRequestCertificateIdentifier":true,
      "AllowedToRequestExtensions":false,
      "AllowedToRequestForceCommand":false,
      "AllowedToRequestPrincipals":true,
      "AllowedToRequestSourceAddresses":false
   },
   "AccessControl":{
      "AllowedCertificateIdentifierPatterns":[
         ".*"
      ],
      "AllowedExtensions":[
         "permit-pty",
         "permit-user-rc",
         "my-custom-extension"
      ],
      "AllowedForceCommandPatterns":[
         ".*"
      ],
      "AllowedPrincipalsPatterns":[
         ".*"
      ]
   },
   "CAKeyPair":{
      "CreatedOn":"2021-06-14T14:35:53.0074237Z",
      "DN":"\\VED\\Certificate Authority\\SSH\\Key Pairs\\template_host",
      "FingerprintSHA256":"a4i4PKU2S7qctNOca2YQsBAtQqM0DgTebyYLsKsvvq8",
      "Guid":"{ab928561-d602-487d-bd6f-144c124e817d}",
      "KeyAlgorithm":"RSA4096",
      "Name":"template_host",
      "PublicKeyData":"ssh-rsa AAAAB3Nz... template_host"
   },
   "CAKeyPairDN":"\\VED\\Certificate Authority\\SSH\\Key Pairs\\template_host",
   "CAKeyPairGuid":"{ab928561-d602-487d-bd6f-144c124e817d}",
   "Certificate":{
      "AllowedPrivateKeyAlgorithms":[
         "RSA2048",
         "RSA3072",
         "RSA4096",
         "ECCP256",
         "ECCP384",
         "ECCP521"
      ],
      "AllowPrivateKeyReuse":true,
      "CertificateDestinationDn":"\\VED\\Policy\\My Folder For Certs",
      "DefaultPrivateKeyAlgorithm":"RSA3072",
      "SignatureHashingAlgorithm":"SHA512",
      "Type":"Host",
      "ValidityPeriod":"365d"
   },
   "Contacts":[
      "local:{3b290173-5aa8-423d-a305-8c1d96f706b5}"
   ],
   "CreatedOn":"2021-06-14T14:35:52.4883947Z",
   "DN":"\\VED\\Certificate Authority\\SSH\\Templates\\template_host",
   "Guid":"{44eabcd7-7a56-4beb-8f84-f4c4b39914e8}",
   "Name":"template_host",
   "Response":{
      "ErrorMessage":"",
      "Success":true
   }
}