SSH Create Certificate

Before you begin

Before attempting to creating certificates, the user has to ensure the following:

CAs should be present in AppViewX.

Request Structure


Endpoint:	`/ssh/cert/create`
Type:	`POST`
Sample URL:	`https://<IP/HostName/TenantName>:<GWPORT>/avxapi/ssh/cert/create?gwsource=external` To understand the elements of the sample URL, click here.
Headers:
Content-Type:	application/json

Table 1. Request Parameters
Name	Description
sessionId `Header`	(Mandatory) Session ID received after login. Type: String Constraints: Required if username and password are not provided.
username `Header`	(Mandatory) AppViewX login username Type: String Constraints: Required if sessionId is not provided.
password `Header`	(Mandatory) AppViewX login password Type: String Constraints: Required if sessionId is not provided.
Content-Type `Header`	(Mandatory) Specifies the nature of the data in the payload Type: String Constraints: The value of the param should be ‘application/json’.
gwsource `Query`	(Mandatory) Source from which the request is triggered. (E.g. external) Type: String
Payload `Body`	(Mandatory) Contains all the parameters to be sent in the request body for the post request Type: Payload

Payload


Name	Description
publicKey	(Mandatory) Public key to create certificate Type: String
validityValue	(Mandatory) Validity of the certificate Type: String
validityUnit	(Mandatory) Validity unit of the certificate Type: String
certificateIdentity	(Mandatory) Identity of the certificate Type: String
caName	(Mandatory) CA name of the certificate Type: String
principals	(Mandatory) Principals of the certificate Type: List
certType	(Mandatory) Type of the certificate Type: String (User or Host)
validFrom	(Optional) Certificate valid from value Type: Long
validTo	(Optional) Certificate valid to value Type: Long

Response Structure

200 OK returns string of type application/json with the following body params.

Table 2. Response Parameters
Name	Description
response	Contains the response attributes for the certificate Type: response
message	Success message of the action or failure description in case of error. Will be non-null for failure response Type: String
appStatusCode	Application-specific status code for the response. Will be non-null for failure response Type: String
tags	More info in case of failure response

Table 3. Response
Name	Description
fingerPrint	Fingerprint of the certificate Type: String
certType	Type of the certificate Type: String
rawFPString	Raw fingerprint of the certificate Type: String
signingCA	Signing CA of the certificate Type: String
keyId	Key ID of the certificate Type: String
serialNumber	Serial number of the certificate Type: String
rawCertType	Raw cert type of the certificate Type: String
validFrom	Valid from value of the certificate Type: String
validTo	Valid to value of the certificate Type: String
validity	Validity of the certificate Type: String
validityUnit	Validity unit of the certificate Type: String
principals	Principals of the certificate Type: String
extensions	Extensions of the certificate Type: String
certContent	Content of the certificate Type: String
caName	CA name of the certificate Type: String
certStatus	Status of the certificate Type: String

Status Codes

Table 4. Status Codes and Description
HTTP Status code	appStatusCode	Message and Possible remediation
200 OK	NA	Success
401 Unauthorized	AVX_GW_003	Authentication failed, reason - Invalid Credentials Possible remediation: Ensure that valid username and password or valid sessionId is provided as the header param.
400 Bad Request	ERR-SSH_NB-268	Valid certificate already exists for the given Key Possible remediation: Valid certificate is available for the given public key. Please make sure to use different public key
	ERR-SSH_NB-268	Valid certificate already exists for the given Key Possible remediation: Valid certificate is available for the given public key. Please make sure to use different public key
	ERR-SSH_NB-267	Selected CA is not in Active status Possible remediation: Please make sure to provide active CA name
	ERR-SSH_NB-263	Selected CA cannot sign requested Cert Type Possible remediation: Please provide proper CA name
	ERR-SSH_NB-266	Validity start cannot exceed validity end Possible remediation: Possible remediation: Make sure to provide start value less than end value
	ERR-SSH_NB-269	validityValue must be greater than zero Possible remediation: validityValue field should not be 0 or less than 0
	ERR-SSH_NB-264	Certificate validity cannot exceed CA validity Possible remediation: Make sure to give the certificate validity less than CA validity
404 Not Found	ERR-SSH-NB-350	No CA found with given name or ID Possible remediation: Please make sure to provide the available CA name

Sample Request/Response

Use Case

To create certificate using create_certificate API.

Request URL

https://<IP/HostName/TenantName>:<GWPORT>/avxapi/ssh/cert/create?gwsource=external

Sample Request


{
      "publicKey": "dummy key",     
      "validityValue" : 1,
      "validityUnit" : "months",
      "certificateIdentity":"admin",
      "caName": "testVendor.user.ca",
      "principals": ["admin"],
      "certType" : "User"
}

Sample Response

{
    "response": {
        "fingerPrint": "AwQpO14LR7d1e9BubBGWcDmIoifmmrxC3M2xyceDO2s",
        "certType": "User",
        "rawFPString": "ECDSA-CERT SHA256:AwQpO14LR7d1e9BubBGWcDmIoifmmrxC3M2xyceDO2s",
        "signingCA": "ECDSA SHA256:A/Pfc4Se53vBzlIstXbTWVmRy5u7n8mBiySryI+UZgI (using ecdsa-sha2-nistp256)",
        "keyId": "admin",
        "serialNumber": "3515398573506688",
        "rawCertType": "[email protected] user certificate",
        "validFrom": 1716503060000,
        "validTo": 1719181460000,
        "validity": 30,
        "validityUnit": "days",
        "principals": [
            "admin"
        ],
        "extensions": {
            "permitX11Forwarding": true,
            "permitAgentForwarding": true,
            "permitPortForwarding": true,
            "permitPty": true,
            "permitUserRc": true
        },
        "certContent": "dummy cert",
        "caName": "testPermG1.user.ca",
        "certStatus": "Active",
        "filePaths": [],
        "onlyForWebTerminal": false
    },
    "message": "Success",
    "appStatusCode": "SSH-NB-200",
    "tags": {},
    "headers": null
}

Reference

Understanding the sample URL:

IP/HostName/TenantName: Replace with the actual IP address, hostname, or tenant name based on the specific configuration in AppViewX.
- IP: A unique identifier assigned to each device connected to a computer network that uses the Internet Protocol for communication
  The IP address will be included in the endpoint URL for an on-prem deployment.
- HostName: A human-readable label assigned to a device (host) on a network
  The hostname will be included in the endpoint URL for an on-prem deployment.
- TenantName: An identifier label for a tenant given to indicate which tenant's data the API request will access/modify
  The tenant name will be included in the endpoint URL for a SaaS deployment.
GWPORT: AppViewX gateway port
A gateway port refers to a network port through which data is sent and received to communicate with a gateway in an on-prem deployment.
Note: GWPORT is not required for SaaS setups.
Example: 31443
avxapi: Path parameter value (static) that is part of the endpoint's URL
Endpoint: Endpoint of the API, for example: /ssh/host/create
gwsource: Source or origin of a gateway, for example: external.