Package org.apache.sshd.client.keyverifier

Class KnownHostsServerKeyVerifier

java.lang.Object

org.apache.sshd.common.util.logging.AbstractLoggingBean

org.apache.sshd.common.util.io.ModifiableFileWatcher

org.apache.sshd.client.keyverifier.KnownHostsServerKeyVerifier

All Implemented Interfaces:

ModifiedServerKeyAcceptor, ServerKeyVerifier

Direct Known Subclasses:

DefaultKnownHostsServerKeyVerifier

public class KnownHostsServerKeyVerifier
extends ModifiableFileWatcher
implements ServerKeyVerifier, ModifiedServerKeyAcceptor

Author:

Apache MINA SSHD Project

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	KnownHostsServerKeyVerifier.HostEntryPair	Represents an entry in the internal verifier's cache

Field Summary

Fields

Modifier and Type	Field	Description
static String	KNOWN_HOSTS_FILE_OPTION	Standard option used to indicate alternative known hosts file location
static String	STRICT_CHECKING_OPTION	Standard option used to indicate whether to use strict host key checking or not.
protected Object	updateLock

Fields inherited from class org.apache.sshd.common.util.io.ModifiableFileWatcher

options, STRICTLY_PROHIBITED_FILE_PERMISSION

Fields inherited from class org.apache.sshd.common.util.logging.AbstractLoggingBean

log

Constructor Summary

Constructors

Constructor	Description
KnownHostsServerKeyVerifier(ServerKeyVerifier delegate, Path file)
KnownHostsServerKeyVerifier(ServerKeyVerifier delegate, Path file, LinkOption... options)

Method Summary

Modifier and Type	Method	Description
protected boolean	acceptIncompleteHostKeys(ClientSession clientSession, SocketAddress remoteAddress, PublicKey serverKey, Throwable reason)	Called if failed to reload known hosts - by default invokes acceptUnknownHostKey(ClientSession, SocketAddress, PublicKey)
protected boolean	acceptKnownHostEntries(ClientSession clientSession, SocketAddress remoteAddress, PublicKey serverKey, Collection<KnownHostsServerKeyVerifier.HostEntryPair> knownHosts)
protected boolean	acceptKnownHostEntry(ClientSession clientSession, SocketAddress remoteAddress, PublicKey serverKey, KnownHostEntry entry)	Invoked after known host entry located and keys match - by default checks that entry has not been revoked
boolean	acceptModifiedServerKey(ClientSession clientSession, SocketAddress remoteAddress, KnownHostEntry entry, PublicKey expected, PublicKey actual)	Invoked when a matching known host key was found but it does not match the presented one.
protected boolean	acceptUnknownHostKey(ClientSession clientSession, SocketAddress remoteAddress, PublicKey serverKey)	Invoked if none of the known hosts matches the current one - by default invokes the delegate.
protected KnownHostsServerKeyVerifier.HostEntryPair	findKnownHostEntry(ClientSession clientSession, SocketAddress remoteAddress, Collection<KnownHostsServerKeyVerifier.HostEntryPair> knownHosts)
ServerKeyVerifier	getDelegateVerifier()
protected PublicKeyEntryResolver	getFallbackPublicKeyEntryResolver()
protected NamedFactory<Mac>	getHostValueDigester(ClientSession clientSession, SocketAddress remoteAddress, SshdSocketAddress hostIdentity)	Invoked by prepareKnownHostEntry(ClientSession, SocketAddress, PublicKey) in order to query whether to use a hashed value instead of a plain one for the written host name/address - default returns null - i.e., no hashing
protected Supplier<Collection<KnownHostsServerKeyVerifier.HostEntryPair>>	getKnownHostSupplier(ClientSession clientSession, Path file)
ModifiedServerKeyAcceptor	getModifiedServerKeyAcceptor()
protected void	handleKnownHostsFileUpdateFailure(ClientSession clientSession, SocketAddress remoteAddress, PublicKey serverKey, Path file, Collection<KnownHostsServerKeyVerifier.HostEntryPair> knownHosts, Throwable reason)	Invoked when updateKnownHostsFile(ClientSession, SocketAddress, PublicKey, Path, Collection) fails - by default just issues a warning.
protected void	handleModifiedServerKeyUpdateFailure(ClientSession clientSession, SocketAddress remoteAddress, KnownHostsServerKeyVerifier.HostEntryPair match, PublicKey serverKey, Path file, Collection<KnownHostsServerKeyVerifier.HostEntryPair> knownHosts, Throwable reason)	Invoked if #updateModifiedServerKey(ClientSession, SocketAddress, HostEntryPair, PublicKey, Path) throws an exception.
protected KnownHostEntry	prepareKnownHostEntry(ClientSession clientSession, SocketAddress remoteAddress, PublicKey serverKey)	Invoked by updateKnownHostsFile(ClientSession, SocketAddress, PublicKey, Path, Collection) in order to generate the host entry to be written
protected String	prepareModifiedServerKeyLine(ClientSession clientSession, SocketAddress remoteAddress, KnownHostEntry entry, String curLine, PublicKey expected, PublicKey actual)	Invoked by updateModifiedServerKey(ClientSession, SocketAddress, HostEntryPair, PublicKey, Path, Collection) in order to prepare the replacement - by default it replaces the key part with the new one
protected List<KnownHostsServerKeyVerifier.HostEntryPair>	reloadKnownHosts(ClientSession session, Path file)
protected PublicKey	resolveHostKey(ClientSession session, KnownHostEntry entry, PublicKeyEntryResolver resolver)	Recover the associated public key from a known host entry
protected Collection<SshdSocketAddress>	resolveHostNetworkIdentities(ClientSession clientSession, SocketAddress remoteAddress)	Retrieves the host identities to be used when matching or updating an entry for it - by default returns the reported remote address and the original connection target host name/address (if same, then only one value is returned)
protected void	setLoadedHostsEntries(Collection<KnownHostsServerKeyVerifier.HostEntryPair> keys)
void	setModifiedServerKeyAcceptor(ModifiedServerKeyAcceptor acceptor)
protected KnownHostEntry	updateKnownHostsFile(ClientSession clientSession, SocketAddress remoteAddress, PublicKey serverKey, Path file, Collection<KnownHostsServerKeyVerifier.HostEntryPair> knownHosts)	Invoked if a new previously unknown host key has been accepted - by default appends a new entry at the end of the currently monitored known hosts file
protected void	updateModifiedServerKey(ClientSession clientSession, SocketAddress remoteAddress, KnownHostsServerKeyVerifier.HostEntryPair match, PublicKey actual, Path file, Collection<KnownHostsServerKeyVerifier.HostEntryPair> knownHosts)	Invoked if a matching host entry was found, but the key did not match and acceptModifiedServerKey(ClientSession, SocketAddress, KnownHostEntry, PublicKey, PublicKey) returned true.
boolean	verifyServerKey(ClientSession clientSession, SocketAddress remoteAddress, PublicKey serverKey)	Verify that the server key provided is really the one of the host.

Methods inherited from class org.apache.sshd.common.util.io.ModifiableFileWatcher

checkReloadRequired, exists, getPath, lastModified, resetReloadAttributes, size, toPathResource, toPathResource, toString, updateReloadAttributes, validateStrictConfigFilePermissions

Methods inherited from class org.apache.sshd.common.util.logging.AbstractLoggingBean

debug, debug, debug, debug, debug, error, error, error, error, error, getSimplifiedLogger, info, info, warn, warn, warn, warn, warn, warn, warn, warn

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

STRICT_CHECKING_OPTION

public static final String STRICT_CHECKING_OPTION

Standard option used to indicate whether to use strict host key checking or not. Values may be "yes/no", "true/false" or "on/off"

See Also:

Constant Field Values

KNOWN_HOSTS_FILE_OPTION

public static final String KNOWN_HOSTS_FILE_OPTION

Standard option used to indicate alternative known hosts file location

See Also:

Constant Field Values

updateLock

protected final Object updateLock

Constructor Detail

KnownHostsServerKeyVerifier

public KnownHostsServerKeyVerifier(ServerKeyVerifier delegate,
                                   Path file)

KnownHostsServerKeyVerifier

public KnownHostsServerKeyVerifier(ServerKeyVerifier delegate,
                                   Path file,
                                   LinkOption... options)

Method Detail

getDelegateVerifier

public ServerKeyVerifier getDelegateVerifier()

getModifiedServerKeyAcceptor

public ModifiedServerKeyAcceptor getModifiedServerKeyAcceptor()

Returns:

The delegate ModifiedServerKeyAcceptor to consult if a server presents a modified key. If null then assumed to reject such a modification

setModifiedServerKeyAcceptor

public void setModifiedServerKeyAcceptor(ModifiedServerKeyAcceptor acceptor)

Parameters:

acceptor - The delegate ModifiedServerKeyAcceptor to consult if a server presents a modified key. If null then assumed to reject such a modification

verifyServerKey

public boolean verifyServerKey(ClientSession clientSession,
                               SocketAddress remoteAddress,
                               PublicKey serverKey)

Description copied from interface: ServerKeyVerifier

Verify that the server key provided is really the one of the host.

Specified by:

verifyServerKey in interface ServerKeyVerifier

Parameters:

clientSession - the current ClientSession

remoteAddress - the host's SocketAddress

serverKey - the presented server PublicKey

Returns:

true if the key is accepted for the host

getKnownHostSupplier

protected Supplier<Collection<KnownHostsServerKeyVerifier.HostEntryPair>> getKnownHostSupplier(ClientSession clientSession,
                                                                                               Path file)

setLoadedHostsEntries

protected void setLoadedHostsEntries(Collection<KnownHostsServerKeyVerifier.HostEntryPair> keys)

reloadKnownHosts

protected List<KnownHostsServerKeyVerifier.HostEntryPair> reloadKnownHosts(ClientSession session,
                                                                           Path file)
                                                                    throws IOException,
                                                                           GeneralSecurityException

Parameters:

session - The ClientSession that triggered this request

file - The Path to reload from

Returns:

A List of the loaded KnownHostsServerKeyVerifier.HostEntryPairs - may be null/empty

Throws:

IOException - If failed to parse the file

GeneralSecurityException - If failed to resolve the encoded public keys

resolveHostKey

protected PublicKey resolveHostKey(ClientSession session,
                                   KnownHostEntry entry,
                                   PublicKeyEntryResolver resolver)
                            throws IOException,
                                   GeneralSecurityException

Recover the associated public key from a known host entry

Parameters:

session - The ClientSession that triggered this request

entry - The KnownHostEntry - ignored if null

resolver - The PublicKeyEntryResolver to use if immediate - decoding does not work - ignored if null

Returns:

The extracted PublicKey - null if none

Throws:

IOException - If failed to decode the key

GeneralSecurityException - If failed to generate the key

See Also:

getFallbackPublicKeyEntryResolver(), AuthorizedKeyEntry.resolvePublicKey(SessionContext, PublicKeyEntryResolver)

getFallbackPublicKeyEntryResolver

protected PublicKeyEntryResolver getFallbackPublicKeyEntryResolver()

acceptKnownHostEntries

protected boolean acceptKnownHostEntries(ClientSession clientSession,
                                         SocketAddress remoteAddress,
                                         PublicKey serverKey,
                                         Collection<KnownHostsServerKeyVerifier.HostEntryPair> knownHosts)

updateModifiedServerKey

protected void updateModifiedServerKey(ClientSession clientSession,
                                       SocketAddress remoteAddress,
                                       KnownHostsServerKeyVerifier.HostEntryPair match,
                                       PublicKey actual,
                                       Path file,
                                       Collection<KnownHostsServerKeyVerifier.HostEntryPair> knownHosts)
                                throws Exception

Invoked if a matching host entry was found, but the key did not match and acceptModifiedServerKey(ClientSession, SocketAddress, KnownHostEntry, PublicKey, PublicKey) returned true. By default it locates the line to be updated and updates only its key data, marking the file for reload on next verification just to be on the safe side.

Parameters:

clientSession - The ClientSession

remoteAddress - The remote host address

match - The KnownHostsServerKeyVerifier.HostEntryPair whose key does not match

actual - The presented server PublicKey to be updated

file - The file Path to be updated

knownHosts - The currently loaded entries

Throws:

Exception - If failed to update the file - Note: this may mean the file is now corrupted

See Also:

handleModifiedServerKeyUpdateFailure(ClientSession, SocketAddress, HostEntryPair, PublicKey, Path, Collection, Throwable), prepareModifiedServerKeyLine(ClientSession, SocketAddress, KnownHostEntry, String, PublicKey, PublicKey)

prepareModifiedServerKeyLine

protected String prepareModifiedServerKeyLine(ClientSession clientSession,
                                              SocketAddress remoteAddress,
                                              KnownHostEntry entry,
                                              String curLine,
                                              PublicKey expected,
                                              PublicKey actual)
                                       throws Exception

Invoked by updateModifiedServerKey(ClientSession, SocketAddress, HostEntryPair, PublicKey, Path, Collection) in order to prepare the replacement - by default it replaces the key part with the new one

Parameters:

clientSession - The ClientSession

remoteAddress - The remote host address

entry - The KnownHostEntry

curLine - The current entry line data

expected - The expected PublicKey

actual - The present key to be update

Returns:

The updated line - ignored if null/empty or same as original one

Throws:

Exception - if failed to prepare the line

handleModifiedServerKeyUpdateFailure

protected void handleModifiedServerKeyUpdateFailure(ClientSession clientSession,
                                                    SocketAddress remoteAddress,
                                                    KnownHostsServerKeyVerifier.HostEntryPair match,
                                                    PublicKey serverKey,
                                                    Path file,
                                                    Collection<KnownHostsServerKeyVerifier.HostEntryPair> knownHosts,
                                                    Throwable reason)

Invoked if #updateModifiedServerKey(ClientSession, SocketAddress, HostEntryPair, PublicKey, Path) throws an exception. This may mean the file is corrupted, but it can be recovered from the known hosts that are being provided. By default, it only logs a warning and does not attempt to recover the file

Parameters:

clientSession - The ClientSession

remoteAddress - The remote host address

match - The KnownHostsServerKeyVerifier.HostEntryPair whose key does not match

serverKey - The presented server PublicKey to be updated

file - The file Path to be updated

knownHosts - The currently cached entries (may be null/empty)

reason - The failure reason

acceptKnownHostEntry

protected boolean acceptKnownHostEntry(ClientSession clientSession,
                                       SocketAddress remoteAddress,
                                       PublicKey serverKey,
                                       KnownHostEntry entry)

Invoked after known host entry located and keys match - by default checks that entry has not been revoked

Parameters:

clientSession - The ClientSession

remoteAddress - The remote host address

serverKey - The presented server PublicKey

entry - The KnownHostEntry value - if null then no known matching host entry was found - default will call acceptUnknownHostKey(ClientSession, SocketAddress, PublicKey)

Returns:

true if OK to accept the server

findKnownHostEntry

protected KnownHostsServerKeyVerifier.HostEntryPair findKnownHostEntry(ClientSession clientSession,
                                                                       SocketAddress remoteAddress,
                                                                       Collection<KnownHostsServerKeyVerifier.HostEntryPair> knownHosts)

acceptIncompleteHostKeys

protected boolean acceptIncompleteHostKeys(ClientSession clientSession,
                                           SocketAddress remoteAddress,
                                           PublicKey serverKey,
                                           Throwable reason)

Called if failed to reload known hosts - by default invokes acceptUnknownHostKey(ClientSession, SocketAddress, PublicKey)

Parameters:

clientSession - The ClientSession

remoteAddress - The remote host address

serverKey - The presented server PublicKey

reason - The Throwable that indicates the reload failure

Returns:

true if accept the server key anyway

See Also:

acceptUnknownHostKey(ClientSession, SocketAddress, PublicKey)

acceptUnknownHostKey

protected boolean acceptUnknownHostKey(ClientSession clientSession,
                                       SocketAddress remoteAddress,
                                       PublicKey serverKey)

Invoked if none of the known hosts matches the current one - by default invokes the delegate. If the delegate accepts the key, then it is appended to the currently monitored entries and the file is updated

Parameters:

clientSession - The ClientSession

remoteAddress - The remote host address

serverKey - The presented server PublicKey

Returns:

true if accept the server key

See Also:

updateKnownHostsFile(ClientSession, SocketAddress, PublicKey, Path, Collection), handleKnownHostsFileUpdateFailure(ClientSession, SocketAddress, PublicKey, Path, Collection, Throwable)

handleKnownHostsFileUpdateFailure

protected void handleKnownHostsFileUpdateFailure(ClientSession clientSession,
                                                 SocketAddress remoteAddress,
                                                 PublicKey serverKey,
                                                 Path file,
                                                 Collection<KnownHostsServerKeyVerifier.HostEntryPair> knownHosts,
                                                 Throwable reason)

Invoked when updateKnownHostsFile(ClientSession, SocketAddress, PublicKey, Path, Collection) fails - by default just issues a warning. Note: there is a chance that the file is now corrupted and cannot be re-used, so we provide a way to recover it via overriding this method and using the cached entries to re-created it.

Parameters:

clientSession - The ClientSession

remoteAddress - The remote host address

serverKey - The server PublicKey that was attempted to update

file - The file Path to be updated

knownHosts - The currently known entries (may be null/empty

reason - The failure reason

updateKnownHostsFile

protected KnownHostEntry updateKnownHostsFile(ClientSession clientSession,
                                              SocketAddress remoteAddress,
                                              PublicKey serverKey,
                                              Path file,
                                              Collection<KnownHostsServerKeyVerifier.HostEntryPair> knownHosts)
                                       throws Exception

Invoked if a new previously unknown host key has been accepted - by default appends a new entry at the end of the currently monitored known hosts file

Parameters:

clientSession - The ClientSession

remoteAddress - The remote host address

serverKey - The server PublicKey that to update

file - The file Path to be updated

knownHosts - The currently cached entries (may be null/empty)

Returns:

The generated KnownHostEntry or null if nothing updated. If anything updated then the file will be re-loaded on next verification regardless of which server is verified

Throws:

Exception - If failed to update the file - Note: in this case the file may be corrupted so handleKnownHostsFileUpdateFailure(ClientSession, SocketAddress, PublicKey, Path, Collection, Throwable) will be called in order to enable recovery of its data

See Also:

ModifiableFileWatcher.resetReloadAttributes()

prepareKnownHostEntry

protected KnownHostEntry prepareKnownHostEntry(ClientSession clientSession,
                                               SocketAddress remoteAddress,
                                               PublicKey serverKey)
                                        throws Exception

Invoked by updateKnownHostsFile(ClientSession, SocketAddress, PublicKey, Path, Collection) in order to generate the host entry to be written

Parameters:

clientSession - The ClientSession

remoteAddress - The remote host address

serverKey - The server PublicKey that was attempted to update

Returns:

The KnownHostEntry to use - if null then entry is not updated in the file

Throws:

Exception - If failed to generate the entry - e.g. failed to hash

See Also:

resolveHostNetworkIdentities(ClientSession, SocketAddress), KnownHostEntry.getConfigLine()

getHostValueDigester

protected NamedFactory<Mac> getHostValueDigester(ClientSession clientSession,
                                                 SocketAddress remoteAddress,
                                                 SshdSocketAddress hostIdentity)

Invoked by prepareKnownHostEntry(ClientSession, SocketAddress, PublicKey) in order to query whether to use a hashed value instead of a plain one for the written host name/address - default returns null - i.e., no hashing

Parameters:

clientSession - The ClientSession

remoteAddress - The remote host address

hostIdentity - The entry's host name/address

Returns:

The digester NamedFactory - null if no hashing is to be made

resolveHostNetworkIdentities

protected Collection<SshdSocketAddress> resolveHostNetworkIdentities(ClientSession clientSession,
                                                                     SocketAddress remoteAddress)

Retrieves the host identities to be used when matching or updating an entry for it - by default returns the reported remote address and the original connection target host name/address (if same, then only one value is returned)

Parameters:

clientSession - The ClientSession

remoteAddress - The remote host address

Returns:

A Collection of the InetSocketAddress-es to use - if null/empty then ignored (i.e., no matching is done or no entry is generated)

See Also:

ClientSession.getConnectAddress(), SshdSocketAddress.toSshdSocketAddress(SocketAddress)

acceptModifiedServerKey

public boolean acceptModifiedServerKey(ClientSession clientSession,
                                       SocketAddress remoteAddress,
                                       KnownHostEntry entry,
                                       PublicKey expected,
                                       PublicKey actual)
                                throws Exception

Description copied from interface: ModifiedServerKeyAcceptor

Invoked when a matching known host key was found but it does not match the presented one.

Specified by:

acceptModifiedServerKey in interface ModifiedServerKeyAcceptor

Parameters:

clientSession - The ClientSession

remoteAddress - The remote host address

entry - The original KnownHostEntry whose key did not match

expected - The expected server PublicKey

actual - The presented server PublicKey

Returns:

true if accept the server key anyway

Throws:

Exception - if cannot process the request - equivalent to false return value