<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">

<erlref>
  <header>
    <copyright>
      <year>2012</year>
      <year>2018</year>
      <holder>Ericsson AB, All Rights Reserved</holder>
    </copyright>
    <legalnotice>
      Licensed under the Apache License, Version 2.0 (the "License");
      you may not use this file except in compliance with the License.
      You may obtain a copy of the License at
 
          http://www.apache.org/licenses/LICENSE-2.0

      Unless required by applicable law or agreed to in writing, software
      distributed under the License is distributed on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      See the License for the specific language governing permissions and
      limitations under the License.

      The Initial Developer of the Original Code is Ericsson AB.
    </legalnotice>
    <title>ssh_client_key_api</title>
    <prepared></prepared>
    <docno></docno>
    <date></date>
    <rev></rev>
  </header>
  <module since="OTP R16B">ssh_client_key_api</module>
  <modulesummary>
     -behaviour(ssh_client_key_api).
  </modulesummary>
  <description>
    <p>Behavior describing the API for public key handling of an SSH client. By implementing
    the callbacks defined in this behavior, the public key handling of an SSH client can
    be customized. By default the <c>ssh</c> application implements this behavior
    with help of the standard OpenSSH files,
    see the <seeapp marker="SSH_app"> ssh(6)</seeapp> application manual.</p>
  </description>

  <datatypes>
    <datatype>
      <name name="client_key_cb_options"/>
      <desc>
	<p>Options provided to <seemfa marker="ssh#connect/3">ssh:connect/[3,4]</seemfa>.
	</p>
	<p>The option list given in the
	<seetype marker="ssh#key_cb_common_option"><c>key_cb</c></seetype>
	option is available with the key <c>key_cb_private</c>.
	</p>
      </desc>
    </datatype>
  </datatypes>

  <funcs>
    <func>
      <name since="OTP R16B">Module:add_host_key(HostNames, PublicHostKey, ConnectOptions) -> ok | {error, Reason}</name>
      <fsummary>Adds a host key to the set of trusted host keys.</fsummary>
      <type>
	<v>HostNames = string()</v>
	<d>Description of the host that owns the <c>PublicHostKey</c>.</d>

	<v>PublicHostKey = <seetype marker="public_key:public_key#public_key">public_key:public_key()</seetype></v>
	<d>Of ECDSA keys, only the Normally an RSA, DSA or ECDSA public key, but handling of other public keys can be added.</d>

	<v>ConnectOptions =  <seetype marker="#client_key_cb_options">client_key_cb_options()</seetype></v>
      </type>
      <desc>
	<p>This function is retired in favour for <c>Module:add_host_key/4</c> which is the prefered API function.
	The calling SSH application will still try the <c>add_host_key/3</c> if the call to <c>add_host_key/4</c> failed.
	</p>
	 <p>Adds a host key to the set of trusted host keys.</p>
      </desc>
    </func>

    <func>
      <name since="OTP R16B">Module:add_host_key(Host, Port, PublicHostKey, ConnectOptions) -> ok | {error, Reason}</name>
      <fsummary>Adds a host key to the set of trusted host keys.</fsummary>
      <type>
	<v>Host = <seetype marker="kernel:inet#ip_address">inet:ip_address()</seetype>
	| <seetype marker="kernel:inet#hostname">inet:hostname()</seetype>
        | [ <seetype marker="kernel:inet#ip_address">inet:ip_address()</seetype>
	  | <seetype marker="kernel:inet#hostname">inet:hostname()</seetype> ]</v>
	<d>The host that owns the <c>PublicHostKey</c>. One or more IP addresses or hostnames.</d>

	<v>Port = <seetype marker="kernel:inet#port_number">inet:port_number()</seetype></v>
	<d>The Port number of the Host.</d>

	<v>PublicHostKey = <seetype marker="public_key:public_key#public_key">public_key:public_key()</seetype></v>
	<d>Of ECDSA keys, only the Normally an RSA, DSA or ECDSA public key, but handling of other public keys can be added.</d>

	<v>ConnectOptions =  <seetype marker="#client_key_cb_options">client_key_cb_options()</seetype></v>
      </type>
      <desc>
	 <p>Adds a host key to the set of trusted host keys.</p>
	 <p>This function is prefered to the old <c>Module:add_host_key/3</c> since it also uses
	the peer host port number and may return an error message.</p>
	<p>The OTP/SSH application first calls this function in the callback module, and then
	the old <c>Module:add_host_key/3</c> for compatibilty.</p>
      </desc>
    </func>

    <func>
      <name since="OTP R16B">Module:is_host_key(Key, Host, Algorithm, ConnectOptions) -> Result</name>
      <fsummary>Checks if a host key is trusted.</fsummary>
      <type>
	<v>Key = <seetype marker="public_key:public_key#public_key">public_key:public_key()</seetype></v>
	<d>Normally an RSA, DSA or ECDSA public key, but handling of other public keys can be added.</d>

	<v>Host = string()</v>
	<d>Description of the host.</d>

	<v>Algorithm = <seetype marker="ssh#pubkey_alg">ssh:pubkey_alg()</seetype></v>
	<d>Host key algorithm.</d>

	<v>ConnectOptions =  <seetype marker="#client_key_cb_options">client_key_cb_options()</seetype></v>

	<v>Result = boolean()</v>
      </type>
      <desc>
	<p>This function is retired in favour for <c>Module:is_host_key/5</c> which is the prefered API function.
	The calling SSH application will still try the <c>is_host_key/4</c> if the call to <c>is_host_key/5</c> failed.
	</p>
	<p>Checks if a host key is trusted.</p>
      </desc>
    </func>

    <func>
      <name since="OTP 23.0">Module:is_host_key(Key, Host, Port, Algorithm, ConnectOptions) -> Result</name>
      <fsummary>Checks if a host key is trusted.</fsummary>
      <type>
	<v>Key = <seetype marker="public_key:public_key#public_key">public_key:public_key()</seetype></v>
	<d>Normally an RSA, DSA or ECDSA public key, but handling of other public keys can be added.</d>

	<v>Host = <seetype marker="kernel:inet#ip_address">inet:ip_address()</seetype>
	| <seetype marker="kernel:inet#hostname">inet:hostname()</seetype>
        | [ <seetype marker="kernel:inet#ip_address">inet:ip_address()</seetype>
	  | <seetype marker="kernel:inet#hostname">inet:hostname()</seetype> ]</v>
	<d>Description of the host with one or more IP addresses or hostnames.</d>

	<v>Port = <seetype marker="kernel:inet#port_number">inet:port_number()</seetype></v>
	<d>The Port number of the host.</d>

	<v>Algorithm = <seetype marker="ssh#pubkey_alg">ssh:pubkey_alg()</seetype></v>
	<d>Host key algorithm.</d>

	<v>ConnectOptions =  <seetype marker="#client_key_cb_options">client_key_cb_options()</seetype></v>

	<v>Result = boolean() | {error, Error::term()}</v>
	<d>The exact error message depends on the actual callback module. The Error message makes
	the connection to fail, and is returned from e.g ssh:connect/3.</d>
      </type>
      <desc>
	<p>Checks if a host key is trusted.</p>
	<p>This function is prefered to the old <c>Module:is_host_key/4</c> since it also uses
	the peer host port number and may return an error message.</p>
	<p>The OTP/SSH application first calls this function in the callback module, and then
	the old <c>Module:is_host_key/4</c> for compatibilty.</p>
      </desc>
    </func>

    <func>
      <name since="OTP R16B">Module:user_key(Algorithm, ConnectOptions) -> Result</name>
      <fsummary>Fetches the users <em>public key</em> matching the <c>Algorithm</c>.</fsummary>
      <type>
	<v>Algorithm = <seetype marker="ssh#pubkey_alg">ssh:pubkey_alg()</seetype></v>
	<d>Host key algorithm.</d>

	<v>ConnectOptions =  <seetype marker="#client_key_cb_options">client_key_cb_options()</seetype></v>

	<v>Result = {ok, <seetype marker="public_key:public_key#private_key">public_key:private_key()</seetype>} |
                    {ok, {ssh2_pubkey, PubKeyBlob :: binary()}} |
                    {error, term()}</v>
      </type>

      <desc>
	<p>Fetches the users <em>public key</em> matching the <c>Algorithm</c>. Some key callback modules
	may return <c>{ssh2_pubkey, PubKeyBlob :: binary()}</c>.</p>
	<note><p>The private key contains the public key.</p></note>

      </desc>
    </func>

  </funcs>

</erlref>
