We have a new documentation site for cPanel & WHM! You can find our new documentation site at docs.cpanel.net.

We will continue to maintain our API documentation on this server.

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

Description

This function returns the most secure domain to use for a service.

Examples 


 cPanel or Webmail Session URL
https://hostname.example.com:2083/cpsess##########/execute/SSL/gen_cn_name?domain=example.com&service=cpanel


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.
 
// Retrieves the most secure domain to use for a service.
$SSL_get_cn_name = $cpanel->uapi(
    'SSL', 'get_cn_name',    array(
        'domain'          => 'example.com',
        'service'         => 'cpanel'
  )
);


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.
 
# Retrieves the most secure domain to use for a service.
my $SSL_get_cn_name = $cpliveapi->uapi(
    'SSL', 'get_cn_name',    {
        'domain'          => 'example.com',
        'service'         => 'cpanel'
    }
);


Note:

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

 Command Line
uapi --user=username SSL get_cn_name domain=example.com service=cpanel


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": {
	"is_currently_valid": 0,
    "is_self_signed": 1,
    "is_wild_card": 0,
    "ssldomain": "hostname.example.com",
    "ssldomain_matches_cert": 1,
    "cert_valid_not_after": "1394288638",
    "cert_match_method": "hostname"
  }
}


Note:

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

Parameters

ParameterTypeDescriptionPossible valuesExample
domainstring

Required

A domain name, cPanel username, or email address.

  • A valid domain name.
  • A valid cPanel username.
  • A valid email address.
example.com


servicestring

Required

The service's name.

  • cpanel
  • imap
  • pop3
  • smtp
cpanel
add_mail_subdomainBoolean

Whether to append mail to the domain value to find the best match.

For example, if you specify the domain example.com and call this parameter, the function only searches the mail.example.com service domains.

This parameter defaults to 0.

  • 1 — Append mail to the domain value during the search.
  • 0 — Match on the specified domain value only.
0

Returns

ReturnTypeDescriptionPossible valuesExample
ssldomainstringThe best domain to use to access the service.A valid domain.hostname.example.com
is_currently_validBoolean

Whether the certificate currently is valid.

If the certificate is valid, the following statements are true:

  • The certificate is not self-signed (the ssldomain_matches_cert value is 1).
  • The certificate matches the SSL domain (the ssldomain_matches_cert value is 1).
  • The certificate is within its validity period (the cert_valid_not_after value is less than the current time and date).
  • 1 — Valid.
  • 0 — Invalid.
0
is_self_signedBoolean

Whether the certificate is self-signed.

Note:

If the cert_match_method value is none, you should ignore this return's value.

  • 1 — Self-signed.
  • 0 — Not self-signed.
1
is_wild_cardBooleanWhether the certificate is a wildcard certificate.
  • 1 — Wildcard.
  • 0 — Not a wildcard.
0
ssldomain_matches_certBooleanWhether an SSL-protected domain matches the certificate.
  • 1 — Matches.
  • 0 — Does not match.
1
cert_valid_not_afterstringThe certificate's expiration date.A date in Unix time format.1394288638
cert_match_methodstringThe method that the system used to match the domain with the certificate.
  • none — No domain matches the certificate.
  • exact — The domain exactly matches the certificate.
  • exact-wildcard — The domain exactly matches the certificate.
  • mail-wildcard — The mail subdomain of the domain matches the domain of the wildcard certificate.
  • www-wildcard — The www subdomain of the domain matches the domain of the wildcard certificate.
  • hostname-wildcard — The hostname's domain matches the domain of the wildcard certificate.
  • hostname — The hostname matches the domain of the certificate.
  • localdomain_on_cert-mail-wildcard — A mail subdomain of a domain on the server that matches the certificate.
  • localdomain_on_cert-www-wildcard — A www subdomain of a domain on the server matches the certificate.
  • localdomain_on_cert — A domain on the server matches the certificate.
hostname