/**
 * $Id: SshCallback.java 3 2005-06-11 14:50:40Z elkner $ 
 * 
 * Copyright (c) 2005-2005 Jens Elkner.
 * All Rights Reserved.
 *
 * This software is the proprietary information of Jens Elkner.
 * Use is subject to license terms.
 */
package com.jcraft.jsch;

/**
 * Callback from ssh, which are customizable by the application using the ssh.
 * 
 * @author 	Jens Elkner
 * @version	$Revision: 3 $
 */
public interface SshCallback {
	
	/**
	 * Create the given file.
	 * @param name	name of the file to create (usually the known hosts file).
	 * @return <code>true</code> if the file exits and is writable
	 */
	public boolean createFile(String name);
	
	/**
	 * Display a info message
	 * @param message	message to display
	 */
	public void showInfoMessage(String message);

	/**
	 * Get the passphrase for public key authentication.
	 * 
	 * @param srcName 	the name of the keystore
	 * 
	 * @return	<code>null</code> if the user canceled this authentication
	 * 		method, the passphrase otherwise (which might be an empty String).
	 * @throws UnsupportedAuthenticationException  if the application/handler
	 * 	does not support passphrases.
	 */
	public char[] getPassphrase(String srcName) 
		throws UnsupportedAuthenticationException;

	/**
	 * Get the response for keyboard interactive authentication.
	 * 
	 * @param name			the name of the info message
	 * @param instruction	server instruction hint, what this request wanna know.
	 * 		Might be empty.
	 * @param prompt		the user prompts for each information. Might be of
	 * 		length 0.
	 * @param echo			whether the user input should be echo'd. Has the 
	 * 		same length as <i>prompt</i>.
	 * 
	 * @return	<code>null</code> if the user canceled this authentication
	 * 		method.
	 * 		<p> 
	 * 		Otherwise a response with the same length as <i>prompt</i>, which
	 * 		contains the "answers" for the prompts in the same order.
	 * 		Each field in the response
	 * 		must be a non-<code>null</code> String, but is allowed to be empty.
	 * 
	 * @throws UnsupportedAuthenticationException if the application/handler
	 * 	does not support keyboard-interactive authentication.
	 * 
	 * @see <a href="http://ietf.org/internet-drafts/draft-ietf-secsh-auth-kbdinteract-07.txt"
	 * 	>Generic Message Exchange Authentication For SSH (3.2)</a>
	 */
	public String[] getAuthenticationResponse(String name, 
		String instruction, String[] prompt, boolean[] echo) 
		throws UnsupportedAuthenticationException;
	
	/**
	 * Get the password for password authentication.
	 * 
	 * @param username	remote username
	 * @param host		remote hostname/address
	 * @param port		remote port
	 * 
	 * @return <code>null</code> if the user canceled this authentication
	 * 		method.
	 * 
	 * @throws UnsupportedAuthenticationException if the application/handler
	 * 	does not support password authentication
	 */
	public char[] getPassword(String username, String host, int port) 
		throws UnsupportedAuthenticationException;
	
	/**
	 * Inform the user, that the authenticity of a host could not be validated
	 * and ask, whether to continue authentication (not recommended - man
	 * in the middle attack).
	 * 
	 * @param host	the host with missing authenticity
	 * @param keyType	the type of key, offered by the <i>host</i>
	 * @param fingerprint	the fingerprint of the key send by the <i>host</i>
	 * @return <code>true</code> if the session should be continued and the new
	 * 		host key inserted into the known hosts file/repository. 
	 */
	public boolean hostKeyValidationFailed(String host, String keyType,
		String fingerprint);
	
	/**
	 * Display a message, that the hostkey of the host has been changed.
	 * The session will be canceled.
	 * 
	 * @param keyType	the type of key, offered by the <i>host</i>
	 * @param fingerprint	the fingerprint of the key send by the <i>host</i>
	 * @param knownHostsFile	the file, which contains the previously accepted
	 * 		public key of the host
	 */
	public void hostKeyChanged(String keyType, String fingerprint, 
		String knownHostsFile);
}