Description

This function checks whether a host's public key exists in the /home/user/.ssh/known_hosts file.


Examples  




https://hostname.example.com:2083/cpsess##########/execute/KnownHosts/verify?host_name=host.example.com



$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
 
// Verify the host
$verify = $cpanel->uapi(
    'KnownHosts', 'verify',
     array(
        'host_name'    => 'host.example.com';
     )
);



my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.
 
# Verify the host
my $verify = $cpliveapi->uapi(
    'KnownHosts', 'verify',    {
        'host_name'    => 'host.example.com',
    }
);



<!-- Verify the host. -->
[% data = execute( 
   'KnownHosts', 'verify', {
        'host_name'    => 'host.example.com',
   } 
); %]



uapi --user=username KnownHosts verify host_name=host.example.com



{  
   "errors":null,
   "data":{
      "status": 0,
      "failure_type": new,
      "errors": [
          "The “host.example.com” host does not exist in the known_hosts file."
      ],
      "host": [
          {
            "host": "host.example.com",
            "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCsj2bNKTBSpIYDEGk9KxsGh3mySTRgMtXL583qmBpzeQ+jqCMRgBqB98u3z++J1sKlXHWfM9dyhSevkMwSbhoR8XIq/U0tCNyokEi/ueaBMCvbcTHhO7FcwzY92WK4Yt0aGROY5qX2UKSeOvuP4D6TPqKF1onSzH9bx9XUf2lEdWT/ia1NEKjunUqu1xOB/StKDHMoX4/OKyIzuS0q/T1zOATthvasJFoPrAjkohTyaDUz2LN5JoH839hViyEG82yB+MjcFV5MU3N1l1QL3cVUCh93xSaua1N85qivl+siMkPGbO5xR/En4iEY6K2XPASUEMaieWVNTRCtJ4S8H+9",
            "line": "host.example.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCsj2bNKTBSpIYDEGk9KxsGh3mySTRgMtXL583qmBpzeQ+jqCMRgBqB98u3z++J1sKlXHWfM9dyhSevkMwSbhoR8XIq/U0tCNyokEi/ueaBMCvbcTHhO7FcwzY92WK4Yt0aGROY5qX2UKSeOvu\P4D6TPqKF1onrSzH9bx9XUf2lEdWT/ia1NEKjunUqu1xOB/StKDHMoX4/OKyIzuS0q/T1zOATthvasJFoPrAjkohTyaDUz2LN5JoH839hViyEG82yB+MjcFV5MU3N1l1QL3cVUCh93xSaua1N85qivl+siMkPGbO5xR/En4iEY6K2XPASUEMaieWVNTRCtJ4S8H+9",
            "meta": {
                "algorithm": "ssh-rsa",
                "body":  "AAAAB3NzaC1yc2EAAAADAQABAAABAQCsj2bNKTBSpIYDEGk9KxsGh3mySTRgMtXL583qmBpzeQ+jqCMRgBqB98u3z++J1sKlXHWfM9dyhSevkMwSbhoR8XIq/U0tCNyokEi/ueaBMCvbcTHhO7FcwzY92WK4Yt0aGROY5qX2UKSeOvuP4D6TPqKF1onrSzH9\bx9XUf2lEdWT/ia1NEKjunUqu1xOB/StKDHMoX4/OKyIzuS0q/T1zOATthvasJFoPrAjkohTyaDUz2LN5JoH839hViyEG82yB+MjcFV5MU3N1l1QL3cVUCh93xSaua1N85qivl+siMkPGbO5xR/En4iEY6K2XPASUEMaieWVNTRCtJ4S8H+9",
                "md5": "b6030e39979ed0e724cea3773e014209",
                "md5-printable": "MD5:b6:03:0e:39:97:9e:d0:e7:24:ce:a3:77:3e:01:42:09",
                "sha256": "44e405bcf4e11ab5b846e58ba0bf6dabd23dcc9e367cae17cb0c91b5b3b3fc44",
                "sha256-printable": "SHA256:ROQFvPThGrW4RuWLoL9tq9I9zJ42fK4XywyRtbOz/EQ"
            }
          }
      ]
   },
   "status":1,
   "metadata":{  
   },
   "messages":null
}



Parameters

ParameterTypeDescriptionPossible valuesExample
host_namestring

Required

The host to query.

A valid hostname.

host.example.com

portinteger

The SSH port to use, if the system uses a non-standard SSH port.

If you do not supply a value, the function uses the standard SSH port (22).

A valid port number.1234

 

Returns

ReturnTypeDescriptionPossible valuesExample
statusBoolean

Whether the host already exists in the /home/user/.ssh/known_hosts file, where user represents the cPanel account's username.

  • 1 — The host already exists.
  • 0 — The host does not already exist, or the system must re-register the hostname.
0

failure_type

string

The reason why the system will register the hostname.

  • new — The host does not already exist.
  • changed — The host's information has changed.
new

errors

array

An array of errors that the system generated.

A valid array of strings.


The “example.com” host does not exist in the known_hosts file.


host

array of hashes

An array of hashes of information for the host.

Each hash includes the host, key, and line returns and the meta hash.

host

string

The hostname.

The function returns this value in the host hash.

A valid hostname.host.example.com

key

string

The host's key.

The function returns this value in the host hash.

A valid algorithm and key.


ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAq2A7hRGmdnm9tUDbO9IDSwBK6TbQa+PXYPCPy6rbTrTtw7PHkccKrpp0yVhp5HdEIcKr6pLlVDBfOLX9QUsyCOV0wzfjIJNlGEYsdlLJizHhbn2mUjvSAHQqZETYP81eFzLQNnPHt4EVVUh7VfDESU84KezmD5QlWpXLmvU31/yMf+Se8xhHTvKSCZIFImWwoG6mbUoWf9nzpIoaSjB+weqqUUmpaaasXVal72J+UX2B+2RPW3RcT0eOzQgqlJL3RKrTJvdsjE3JEAvGq3lGHSZXy28G3skua2SmVi/w4yCE6gbODqnTWlg7+wC604ydGXA8VJiS5ap43JXiUFFAaQ==


line

string

The host's entry in the /home/user/.ssh/known_hosts file, where user represents the cPanel account's username.

The function returns this value in the host hash.

A valid entry that includes the hostname, the key's algorithm, and the public key.


host.example.com ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAq2A7hRGmdnm9tUDbO9IDSwBK6TbQa+PXYPCPy6rbTrTtw7PHkccKrpp0yVhp5HdEIcKr6pLlVDBfOLX9QUsyCOV0wzfjIJNlGEYsdlLJizHhbn2mUjvSAHQqZETYP81eFzLQNnPHt4EVVUh7VfDESU84KezmD5QlWpXLmvU31/yMf+Se8xhHTvKSCZIFImWwoG6mbUoWf9nzpIoaSjB+weqqUUmpaaasXVal72J+UX2B+2RPW3RcT0eOzQgqlJL3RKrTJvdsjE3JEAvGq3lGHSZXy28G3skua2SmVi/w4yCE6gbODqnTWlg7+wC604ydGXA8VJiS5ap43JXiUFFAaQ==


meta

hash

A hash of metadata about the host's public key.

The function returns this hash in the host hash.

This hash includes the algorithm, body, md5, md5-printable, sha256, and sha256-printable returns.

algorithm

string

The key's algorithm.

The function returns this value in the meta hash.

A valid key algorithm.ssh-rsa

body

string

The host's public key.

The function returns this value in the meta hash.

A valid public key.


AAAAB3NzaC1yc2EAAAABIwAAAQEAq2A7hRGmdnm9tUDbO9IDSwBK6TbQa+PXYPCPy6rbTrTtw7PHkccKrpp0yVhp5HdEIcKr6pLlVDBfOLX9QUsyCOV0wzfjIJNlGEYsdlLJizHhbn2mUjvSAHQqZETYP81eFzLQNnPHt4EVVUh7VfDESU84KezmD5QlWpXLmvU31/yMf+Se8xhHTvKSCZIFImWwoG6mbUoWf9nzpIoaSjB+weqqUUmpaaasXVal72J+UX2B+2RPW3RcT0eOzQgqlJL3RKrTJvdsjE3JEAvGq3lGHSZXy28G3skua2SmVi/w4yCE6gbODqnTWlg7+wC604ydGXA8VJiS5ap43JXiUFFAaQ==


md5

string

The key's MD5 fingerprint.

The function returns this value in the meta hash.

A valid MD5 value.b6030e39979ed0e724cea3773e014209

md5-printable

string

A human-readable version of the key's MD5 fingerprint.

The function returns this value in the meta hash.

A valid formatted MD5 value.


MD5:b6:03:0e:39:97:9e:d0:e7:24:ce:a3:77:3e:01:42:09


sha256

string

The key's SHA-256 fingerprint.

The function returns this value in the meta hash.

A valid SHA-256 value.


44e405bcf4e11ab5b846e58ba0bf6dabd23dcc9e367cae17cb0c91b5b3b3fc44


sha256-printable

string

A human-readable version of the key's SHA-256 fingerprint.

The function returns this value in the meta hash.

A valid formatted SHA-256 value.


SHA256:ROQFvPThGrW4RuWLoL9tq9I9zJ42fK4XywyRtbOz/EQ