public class

KnownHosts

extends Object
java.lang.Object
   ↳ com.trilead.ssh2.KnownHosts

Class Overview

The KnownHosts class is a handy tool to verify received server hostkeys based on the information in known_hosts files (the ones used by OpenSSH).

It offers basically an in-memory database for known_hosts entries, as well as some helper functions. Entries from a known_hosts file can be loaded at construction time. It is also possible to add more keys later (e.g., one can parse different known_hosts files).

It is a thread safe implementation, therefore, you need only to instantiate one KnownHosts for your whole application.

Summary

Constants
int HOSTKEY_HAS_CHANGED
int HOSTKEY_IS_NEW
int HOSTKEY_IS_OK
Fields
private LinkedList publicKeys
Public Constructors
KnownHosts()
KnownHosts(char[] knownHostsData)
KnownHosts(File knownHosts)
Public Methods
void addHostkey(String[] hostnames, String serverHostKeyAlgorithm, byte[] serverHostKey)
Adds a single public key entry to the database.
final static void addHostkeyToFile(File knownHosts, String[] hostnames, String serverHostKeyAlgorithm, byte[] serverHostKey)
Adds a single public key entry to the a known_hosts file.
void addHostkeys(File knownHosts)
Parses the given known_hosts file and adds entries to the database.
void addHostkeys(char[] knownHostsData)
Parses the given known_hosts data and adds entries to the database.
final static String createBubblebabbleFingerprint(String keytype, byte[] publickey)
Convert a ssh2 key-blob into a human readable bubblebabble fingerprint.
final static String createHashedHostname(String hostname)
Generate the hashed representation of the given hostname.
final static String createHexFingerprint(String keytype, byte[] publickey)
Convert a ssh2 key-blob into a human readable hex fingerprint.
String[] getPreferredServerHostkeyAlgorithmOrder(String hostname)
Try to find the preferred order of hostkey algorithms for the given hostname.
int verifyHostkey(String hostname, String serverHostKeyAlgorithm, byte[] serverHostKey)
Checks the internal hostkey database for the given hostkey.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final int HOSTKEY_HAS_CHANGED

Constant Value: 2 (0x00000002)

public static final int HOSTKEY_IS_NEW

Constant Value: 1 (0x00000001)

public static final int HOSTKEY_IS_OK

Constant Value: 0 (0x00000000)

Fields

private LinkedList publicKeys

Public Constructors

public KnownHosts ()

public KnownHosts (char[] knownHostsData)

Parameters
knownHostsData
Throws
IOException

public KnownHosts (File knownHosts)

Parameters
knownHosts
Throws
IOException

Public Methods

public void addHostkey (String[] hostnames, String serverHostKeyAlgorithm, byte[] serverHostKey)

Adds a single public key entry to the database. Note: this will NOT add the public key to any physical file (e.g., "~/.ssh/known_hosts") - use addHostkeyToFile() for that purpose. This method is designed to be used in a ServerHostKeyVerifier.

Parameters
hostnames A list of hostname patterns - at least one most be specified. Check out the OpenSSH sshd man page for a description of the pattern matching algorithm.
serverHostKeyAlgorithm As passed to the ServerHostKeyVerifier.
serverHostKey As passed to the ServerHostKeyVerifier.
Throws
IOException

public static final void addHostkeyToFile (File knownHosts, String[] hostnames, String serverHostKeyAlgorithm, byte[] serverHostKey)

Adds a single public key entry to the a known_hosts file. This method is designed to be used in a ServerHostKeyVerifier.

Parameters
knownHosts The file where the publickey entry will be appended.
hostnames A list of hostname patterns - at least one most be specified. Check out the OpenSSH sshd man page for a description of the pattern matching algorithm.
serverHostKeyAlgorithm As passed to the ServerHostKeyVerifier.
serverHostKey As passed to the ServerHostKeyVerifier.
Throws
IOException

public void addHostkeys (File knownHosts)

Parses the given known_hosts file and adds entries to the database.

Parameters
knownHosts
Throws
IOException

public void addHostkeys (char[] knownHostsData)

Parses the given known_hosts data and adds entries to the database.

Parameters
knownHostsData
Throws
IOException

public static final String createBubblebabbleFingerprint (String keytype, byte[] publickey)

Convert a ssh2 key-blob into a human readable bubblebabble fingerprint. The used bubblebabble algorithm (taken from OpenSSH) generates fingerprints that are easier to remember for humans.

Example fingerprint: xofoc-bubuz-cazin-zufyl-pivuk-biduk-tacib-pybur-gonar-hotat-lyxux.

Parameters
keytype Either "ssh-rsa" or "ssh-dss"
publickey Key data
Returns
  • Bubblebabble fingerprint

public static final String createHashedHostname (String hostname)

Generate the hashed representation of the given hostname. Useful for adding entries with hashed hostnames to a known_hosts file. (see -H option of OpenSSH key-gen).

Parameters
hostname
Returns
  • the hashed representation, e.g., "|1|cDhrv7zwEUV3k71CEPHnhHZezhA=|Xo+2y6rUXo2OIWRAYhBOIijbJMA="

public static final String createHexFingerprint (String keytype, byte[] publickey)

Convert a ssh2 key-blob into a human readable hex fingerprint. Generated fingerprints are identical to those generated by OpenSSH.

Example fingerprint: d0:cb:76:19:99:5a:03:fc:73:10:70:93:f2:44:63:47.

Parameters
keytype Either "ssh-rsa" or "ssh-dss"
publickey Key blob
Returns
  • Hex fingerprint

public String[] getPreferredServerHostkeyAlgorithmOrder (String hostname)

Try to find the preferred order of hostkey algorithms for the given hostname. Based on the type of hostkey that is present in the internal database (i.e., either ssh-rsa or ssh-dss) an ordered list of hostkey algorithms is returned which can be passed to Connection.setServerHostKeyAlgorithms.

Parameters
hostname
Returns
  • null if no key for the given hostname is present or there are keys of multiple types present for the given hostname. Otherwise, an array with hostkey algorithms is returned (i.e., an array of length 2).

public int verifyHostkey (String hostname, String serverHostKeyAlgorithm, byte[] serverHostKey)

Checks the internal hostkey database for the given hostkey. If no matching key can be found, then the hostname is resolved to an IP address and the search is repeated using that IP address.

Parameters
hostname The server's hostname, will be matched with all hostname patterns
serverHostKeyAlgorithm Type of hostkey, either ssh-rsa or ssh-dss
serverHostKey The key blob
Returns
    • HOSTKEY_IS_OK: the given hostkey matches an entry for the given hostname
    • HOSTKEY_IS_NEW: no entries found for this hostname and this type of hostkey
    • HOSTKEY_HAS_CHANGED: hostname is known, but with another key of the same type (man-in-the-middle attack?)
Throws
IOException if the supplied key blob cannot be parsed or does not match the given hostkey type.