Create Root CA

Before you begin

Refer to the Ensure the following before attempting to renew certificate from any CA through AppViewX:

Refer to Prerequisites in the PKI User Guide.

Request Structure


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

Table 1. Input Parameters
Name	Description
sessionId `Header`	(Mandatory) Session Id received after login. Type: String Constraint: Required if username and password are not provided.
username `Header`	(Mandatory) AppViewX login username. Type: String Constraint: Required if sessionId is not provided.
password `Header`	(Mandatory) AppViewX login password. Type: String Constraint: Required if sessionId is not provided.

Payload

Table 2. Payload
Name	Description
name	(Mandatory) Name of the root CA. Type: String
description	(Optional) Description for the root CA. Type: String
validityUnitValue	(Mandatory) Duration of certificate validity. Type: String
validityUnit	(Mandatory) Unit of validity (e.g., years, months). Type: String
policyId	(Mandatory) OID (Object Identifier) of the certificate policy. Type: String
maxIssuerPathLength	(Mandatory) Maximum number of intermediate CAs that can follow this CA (or `"NONE"`). Type: String
templateName	(Mandatory) Name of the certificate template to apply. Type: String
keySizeAlgorithm	(Mandatory) Key algorithm and size (e.g., RSA, ECC, with hash type). Type: String
issuerMaxLength	(Mandatory) Max length of issuer path, possibly for constraint enforcement. Type: String
caType	(Mandatory) Type of CA being created (Root CA in this case). Type: String

Table 3. pkiKeySpec
Name	Description
keyGenerationSource	(Mandatory) Source of the key (e.g., "AppViewX", "HSM") Type: String
keySizeAlgorithm	(Mandatory) Key algorithm and size Type: String

Table 4. csrParameters
Name	Description
organization	(Mandatory) Organization name Type: String
organizationUnit	(Optional) Department or unit Type: String
locality	(Optional) City or location Type: String
state	(Optional) State or province Type: String
country	(Optional) Country code Type: String
commonName	(Mandatory) Common name for the root CA Type: String

Response Structure

Response returns string of type application/json with the following body parameters:

Table 5. Parameters
Name	Description
response	Indicates status of the API operation.
message	Success message - PKIaaS CA configuration added successfully Type: String
appStatusCode	Application specific status code for the response. It is a non-null value for a failure response. Type: String
tags	Additional information in case of failure response.

Status Codes


HTTP Code	appStatusCode	Response Message
200 Accepted	null	Create root CA action has been triggered successfully.
401 Unauthorized	AVX_GW_003	Authentication failed, reason - Invalid Credentials. Remediation: Ensure that valid username and password or a valid sessionId is provided as header parameters.
400 Bad Request	INVALID_TEMPLATE	Occurs when specified template is not present. Remediation: Ensure that specified template is selected.
400 Bad Request	VALIDATION_ERROR_0004	Occurs when type of value in invalid. Remediation: Provide valid input value. Example: validityUnit is string but integer is given.
400 Bad Request	HSM_DETAIL_NOT_FOUND_IN_KEYSPEC	Occurs when keyGenerationSource is HSM, but keyHandlerName or hsmDeviceName is not present. Remediation: Provide all fields required for HSM.
417 Expectation Failed	CA_CONFIG_NAME_EXIST	Occurs when CA name already exists. Remediation: Provide a unique CA name.

Sample Request/Response

Request Payload


{
    "name": "RootCA",
    "description": "sample description",
    "validityUnitValue": "1",
    "validityUnit": "years",
    "policyId": "2.5.29.32.0",
    "maxIssuerPathLength": "NONE",
    "templateName": "RootCA_Default",
    "keySizeAlgorithm": "RSA_PKCS1_4096_SHA256",
    "issuerMaxLength": "NONE",
    "caType": "Root CA",
    "pkiKeySpec": {
        "keyGenerationSource": "AppViewX",
        "keySizeAlgorithm": "RSA_PKCS1_4096_SHA256"
    },
    "csrParameters": {
        "organization": "AppViewX Inc.",
        "organizationUnit": "PE",
        "locality": "CBE",
        "state": "TN",
        "country": "IN",
        "commonName": "RootCA"
    }
}

Response


{
    "response": "Success",
    "message": "PKIaaS CA configuration added successfully.",
    "appStatusCode": null,
    "tags": {},
    "headers": null
}

References

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.
Example: 31443
avxapi: Path parameter value (static) that is part of the endpoint's URL
Endpoint: Endpoint of the API, for example: execute-hook
gwsource: Source or origin of a gateway, for example: external.