Create Subordinate CA

Before you begin

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.
Content-Type `Header`	(Mandatory) Specifies the nature of the data in the payload. Type: String Constraint: Value of the parameter should be ‘application/json’
gwsource `Query`	(Mandatory) Source from which the request is triggered Type: String
Payload `Body`	Contains all the parameters to be sent in the request body for the put request. Type: Payload

Payload

Table 2. Payload
Name	Description
name	(Mandatory) Name of the sub CA. Type: String
description	(Optional) Description for the sub CA. Type: String
rootCAName	(Mandatory) Name of the root CA under which this subordinate CA will be created. 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 sub 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 sub 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	ISSUING_CA_CONFIG_NOT_FOUND	Occurs when the rootCA name is not found for sub CA creation. Remediation: Ensure rootCA name is present.
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.
400 Bad Request	ROOT_CA_NAME_MANDATORY_FOR_SUB_CA	Occurs when the rootCAName field in payload for sub ca creation is not given. Remediation: Ensure that the rootCAName field in payload for sub ca creation is provided.

Sample Request/Response

Request Payload


{
        "name": "SubCA",
        "description": "sample description", 
        "rootCAName":"RootCaMay8",
        "validityUnitValue": "6",
        "validityUnit": "months",
        "policyId": "2.5.29.32.0",
        "maxIssuerPathLength": "NONE",
        "templateName": "SubCA_Default",
        "keySizeAlgorithm": "RSA_PKCS1_4096_SHA256",        
        "issuerMaxLength": "NONE",
        "caType": "Subordinate CA",
        "pkiKeySpec" :{
            "keyGenerationSource" : "AppViewX",
            "keySizeAlgorithm" :"RSA_PKCS1_4096_SHA256"
        },
        "csrParameters": {
            "organization": "AppViewX Inc.",
            "organizationUnit": "PE",
            "locality": "CBE",
            "state": "TN",
            "country": "IN",
            "commonName": "SubCA"
        }
}

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.