1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
|
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">
<erlref>
<header>
<copyright>
<year>2012</year>
<year>2021</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 preferred 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 preferred 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 compatibility.</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 preferred 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 preferred 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 compatibility.</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>
|
