You can find our user documentation at docs.cpanel.net.

Check out our new API beta site!

Child pages
  • UAPI Functions - SSL::installed_host
Skip to end of metadata
Go to start of metadata

Description

This function retrieves information about a certificate that is installed on a domain's dedicated IP address.

Important:

If you do not possess a dedicated IP address, this function will fail. For non-dedicated IP addresses, use the SSL::installed_hosts function.

Important:

In cPanel & WHM version 84 and later, when you disable the Calendars and Contacts, Receive MailWeb DiskWebmail, and Web Server roles, the system disables this function.

Examples


 cPanel or Webmail Session URL
https://hostname.example.com:2083/cpsess##########/execute/SSL/installed_host?domain=example.com&verify_certificate=1


Note:

This example calls the UAPI function via a cPanel session. For more information, read our Guide to UAPI documentation. 

 LiveAPI PHP Class
$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
 
// Retrieve certificate information for example.com domain's IP address.
$SSL_installed_host = $cpanel->uapi(
    'SSL', 'installed_host',    array(
        'domain'             => 'example.com',
        'verify_certificate' => '1' 
 )
);


Note:

For more information, read our Guide to the LiveAPI System.

 LiveAPI Perl Module
my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.
 
# Retrieve certificate information for example.com domain's IP address.
my $SSL_installed_host = $cpliveapi->uapi(
    'SSL', 'installed_host',    {
        'domain'         => 'example.com',
        'verify_certificate' => '1'
 }
);


Note:

For more information, read our Guide to the LiveAPI System.

 Command Line
uapi --user=username SSL installed_host domain=example.com verify_certificate=1


Notes:

  • You must URI-encode values.
  • username represents your account-level username.
  • For more information and additional output options, read our Guide to UAPI documentation or run the uapi --help command. 
  • If you run CloudLinux™, you must use the full path of the uapi command:

    /usr/local/cpanel/bin/uapi


 Output (JSON)
{
	"messages": null,
	"errors": null,
	"status": 1,
	"data": {
		"certificate": {
			"is_self_signed": "1",
			"validation_type": "dv",
			"signature_algorithm": "sha256WithRSAEncryption",
			"issuer.organizationName": "Organization",
			"modulus": "a673c3b17344664b35f8791f562d3aea6bf4d8faa3ae3fc0a519380fd453964a36677c34d48677ecb7f5ed035df026f5f0f8fbfe21745e52daf1f3b9e58c73f0baefdb709320e2202e7d05250b051a59b30ff1fef22d83d7140c1c81cea314a0890ce8d2226799872181c58a74016c7aaa2cff5ac72b575cecde8f304aa572a2ea03d8b173ab76c6e8cdb9dfd0da81e1119cefd4b8b4dbfbe0e46c7f1ee2fe8b5fd5504e58ccbc0d13b4fa41ecc9ebd0dabe1d1fec5c724f748167e7c0553e997f9b77eb36abce70973f06df151748d41b758de3efd7afa6f2464a1547f5ff158469d96e248be464df9eda0e7ce854a89332a2c1278b17c425368a9604f454db",
			"subject.commonName": "example.com",
			"subject_text": "commonName\nexample.com",
			"not_before": "1365633490",
			"modulus_length": "2048",
			"not_after": "1397169490",
	        "key_algorithm": "rsaEncryption",
			"ecdsa_curve_name": null,
        	"ecdsa_public": null,
			"domains": [
				"example.com"
			],
			"issuer.commonName": "example.com",
			"id": "example_com_c69ce_37ff5_1397169490_169c717cb2c260281df792788accf041",
			"issuer_text":
				"commonName\nexample.com\ncountryName\nUS\nemailAddress\nusername@example.com\norganizationName\nExample\nstateOrProvinceName\nTexas\nlocalityName\nHouston",
			"verify_error": ""
		},
		"host": "example.com"
	}
}


Note:

Use cPanel's API Shell interface (cPanel >> Home >> Advanced >> API Shell) to directly test cPanel API calls.

Parameters

ParameterTypeDescriptionPossible valuesExample
domainstring

The domain name.

This parameter defaults to the account's main domain.

A valid domain name.

example.com


verify_certificateBoolean

Verify the certificate.

This parameter defaults to 0.

  • 1 — Verify the certificate.
  • 0 — Do not verify the certificate.
1

Returns

ReturnTypeDescriptionPossible valuesExample
certificatehashA hash of the certificate information.This hash includes the owner, is_self_signed, issuer.organizationName, modulus, subject.commonName, not_before, modulus_length, signature_algorithm, validation_type, not_after, subject_text domains , verify_error, issuer.commonName , id issuer_textkey_algorithmecdsa_curve_name, and ecdsa_public returns.

is_self_signed

Boolean

Whether the certificate is self-signed.

The function returns this value in the certificate hash.

  • 1 — Self-signed.
  • 0 — Not self-signed.
1

validation_type

string

The certificate's validation type.

Note:

We introduced this return in cPanel & WHM version 56.

The function returns this value in the certificate hash.

  • ev — Extended Validation.
  • ov — Organization Validation.
  • dv — Domain Validation.
  • undef — The system could not parse and determine the certificate's validation type.
dv

signature_algorithm





                
string

The signature algorithm of the certificate.

Note:

We introduced this return in cPanel & WHM version 56.

The function returns this value in the certificate hash.

A valid OID hash algorithm name.
sha256WithRSAEncryption

issuer.organizationName

string

The certificate's organization.

The function returns this value in the certificate hash.

A valid string.Organization

modulus

string

The certificate's key's modulus, in hexadecimal format.

The function returns this value in the certificate hash.

  • A valid string.
  • null — The certificate's key is not an RSA key.

Note:

We added the null value in cPanel & WHM version 92.

 Click to view...
a74f7636fa6ac93ee6836a83a995b55deb5019ea36d7ba3dafb00e38d693acdb0c81b2ff777d6b433a420fae523f127f352a68bcc8b8f2d6ee7b70395bafabd8237ada8164fdddf8376b30375c35d4d4cbcce7d33d08069c17b409176a3689f1ebc97c0b08fe6ae44c19a92ac6d68448e7f1d13f3b360affd4222a51b4f35342de99b5a1fb5548e438f2d824664562a448002eed7fce24dedc7dc3e1ed179973d1dae959b33716eeb410d172708954e00632cbf60a0e26419860c8c0bc285d6bfe4b479de0dd189772a5dae676bd2a92acccc1369821be8cffddd8a7e6ecc061f8a32a9ae0661e4e946ed8e3827b277138d3a76116567cbd129cbd869ef9dddf

subject.commonName

string

The certificate's Common Name.

The function returns this value in the certificate hash.

A valid domain name.example.com

not_before

integer

The certificate's start time.

The function returns this value in the certificate hash.

A date in Unix time format.
1365633490

modulus_length

integer

The length, in bits, of the certificate's key's modulus.

The function returns this value in the certificate hash.

  • A positive integer.
  • null — The certificate's key is not an RSA key.

Note:

We added the null value in cPanel & WHM version 92.

2048

not_after

integer

The certificate's expiration time.

The function returns this value in the certificate hash.

A date in Unix time format.
1397169490

domains

array

The domains that the certificate covers.

The function returns this value in the certificate hash.

A valid domain or list of domains.example.com

issuer.commonName

string

The issuer's name.

The function returns this value in the certificate hash.

A valid string, typically a domain name.example.com

id

string

The certificate's ID.

The function returns this value in the certificate hash.

A valid string
 Click to view...
example_com_c69ce_37ff5_1397169490_169c717cb2c260281df792788accf041

issuer_text

string

The X.509 information about the issuer.

The function returns this value in the certificate hash.

A string that contains CSR information.
 Click to view...
 commonName\nexample.com\ncountryName\nUS\nemailAddress\nusername@example.com\norganizationName\nExample\nstateOrProvinceName\nTexas\nlocalityName\nHouston

subject_text

string

The X.509 information about the certificate's subject.

The function returns this value in the certificate hash.

A string that contains CSR information.
 Click to view...
commonName\nexample.com

verify_error

string

Any errors that exist during the certificate verification process.

Note:

You must set the verify_certificate parameter to 1 for this return to appear.

The function returns this value in the certificate hash.

  • An error message.
  • An empty string, if no error exists.
""

key_algorithm

string

The certificate's key's algorithm.

Note:

We added this return in cPanel & WHM version 92.

The function returns this value in the certificate hash.

  • rsaEncryption — RSA.
  • id-ecPublicKey — ECDSA.
rsaEncryption

ecdsa_curve_name

string

The ECDSA curve that the certificate's key uses.

Note:

We added this return in cPanel & WHM version 92.

The function returns this value in the certificate hash.

  • prime256v1
  • secp384r1
  • null — The certificate's key is not an ECDSA key.
prime256v1

ecdsa_public

string

The certificate's key's ECDSA compressed public point, in hexadecimal format.

Note:

We added this return in cPanel & WHM version 92.

The function returns this value in the certificate hash.

  • A valid string.
  • null — The certificate's key is not an ECDSA key.
02a2cb73408a5833ffbe6eedac9227b9985c54a94990cc4a13ea2a57f3bdecada1 
hoststringThe issuer's hostname.A valid domain name.example.com