1ssh_file(3)                Erlang Module Definition                ssh_file(3)
2
3
4

NAME

6       ssh_file  - Default callback module for the client's and server's data‐
7       base operations in the ssh application
8

DESCRIPTION

10       This module is the default callback handler for the  client's  and  the
11       server's  user  and  host "database" operations. All data, for instance
12       key pairs, are stored in files in the normal  file  system.  This  page
13       documents  the  files,  where they are stored and configuration options
14       for this callback module.
15
16       The intention is to be compatible with the OpenSSH  storage  in  files.
17       Therefore it mimics directories and filenames of OpenSSH.
18
19       Ssh_file  implements the ssh_server_key_api and the ssh_client_key_api.
20       This enables the user to make an own  interface  using  for  example  a
21       database handler.
22
23       Such another callback module could be used by setting the option key_cb
24       when starting a client or  a  server  (with  for  example  ssh:connect,
25       ssh:daemon of ssh:shell ).
26
27   Note:
28       The  functions are Callbacks  for the SSH app. They are not intended to
29       be called from the user's code!
30
31

FILES, DIRECTORIES AND WHO USES THEM

33   Daemons
34       Daemons uses all files stored in the SYSDIR directory.
35
36       Optionaly, in case of publickey authorization, one or more of  the  re‐
37       mote  user's  public  keys  in  the USERDIR directory are used. See the
38       files USERDIR/authorized_keys and USERDIR/authorized_keys2.
39
40   Clients
41       Clients uses all files stored in the USERDIR directory.
42
43   Directory contents
44         LOCALUSER:
45           The user name of the OS process running the Erlang virtual  machine
46           (emulator).
47
48         SYSDIR:
49           This is the directory holding the server's files:
50
51           * ssh_host_dsa_key - private dss host key (optional)
52
53           * ssh_host_rsa_key - private rsa host key (optional)
54
55           * ssh_host_ecdsa_key - private ecdsa host key (optional)
56
57           * ssh_host_ed25519_key  -  private  eddsa  host key for curve 25519
58             (optional)
59
60           * ssh_host_ed448_key - private eddsa host key for  curve  448  (op‐
61             tional)
62
63           The key files could be generated with OpenSSH's ssh-keygen command.
64
65           At  least one host key must be defined. The default value of SYSDIR
66           is /etc/ssh.
67
68           For security reasons, this directory is normally accessible only to
69           the root user.
70
71           To change the SYSDIR, see the system_dir option.
72
73         USERDIR:
74           This is the directory holding the files:
75
76           * authorized_keys and, as second alternative authorized_keys2 - the
77             user's public keys are stored concatenated in one of those files.
78
79             It is composed of lines as for OpenSSH:
80
81           (options)? keytype base64-encoded-key comment
82
83             where
84
85           options :: option(,option)*
86           option :: % All options are skipped
87           keytype :: 'ssh-dsa'
88                    | 'ssh-rsa'
89                    | 'ssh-ecdsa-nistp256'
90                 | 'ssh-ecdsa-nistp384'
91                    | 'ssh-ecdsa-nistp521'
92                    | 'ssh-ed25519'
93                 | 'ssh-ed448'
94           base64-encoded-key :: % The user's public key
95           comment :: % Comments are skipped
96
97
98           * known_hosts - host keys from hosts visited concatenated. The file
99             is created and used by the client.
100
101             It is composed of lines as for OpenSSH:
102
103           (option)? pattern(,pattern)* keytype key (comment)?
104
105             where
106
107           option :: '@revoked'
108           pattern :: host | '[' host ']:' port
109           host :: ip-address | hostname | '*'
110           port :: portnumber | '*'
111           keytype :: 'ssh-dsa'
112                    | 'ssh-rsa'
113                    | 'ssh-ecdsa-nistp256'
114                 | 'ssh-ecdsa-nistp384'
115                    | 'ssh-ecdsa-nistp521'
116                    | 'ssh-ed25519'
117                 | 'ssh-ed448'
118           key :: % encoded key from eg ssh_host_*.pub
119
120
121           * id_dsa - private dss user key (optional)
122
123           * id_rsa - private rsa user key (optional)
124
125           * id_ecdsa - private ecdsa user key (optional)
126
127           * id_ed25519 - private eddsa user key for curve 25519 (optional)
128
129           * id_ed448 - private eddsa user key for curve 448 (optional)
130
131           The key files could be generated with OpenSSH's ssh-keygen command.
132
133           The default value of USERDIR is /home/LOCALUSER/.ssh.
134
135           To change the USERDIR, see the user_dir option
136

DATA TYPES

138   Options for the default ssh_file callback module
139       user_dir_common_option() = {user_dir, string()}
140
141              Sets the user directory.
142
143       user_dir_fun_common_option() = {user_dir_fun, user2dir()}
144
145       user2dir() =
146           fun((RemoteUserName :: string()) -> UserDir :: string())
147
148              Sets  the  user directory dynamically by evaluating the user2dir
149              function.
150
151       system_dir_daemon_option() = {system_dir, string()}
152
153              Sets the system directory.
154
155       pubkey_passphrase_client_options() =
156           {dsa_pass_phrase, string()} |
157           {rsa_pass_phrase, string()} |
158           {ecdsa_pass_phrase, string()}
159
160              If  the  user's  DSA,  RSA  or  ECDSA  key  is  protected  by  a
161              passphrase, it can be supplied with thoose options.
162
163              Note that EdDSA passhrases (Curves 25519 and 448) are not imple‐
164              mented.
165
166       optimize_key_lookup() = {optimize, time | space}
167
168              Make the handling of large files fast by setting time, but  this
169              will  use  more memory. The space variant shrinks the memory re‐
170              quirements, but with a higher time consumption.
171
172              To set it, set the option {key_cb,  {ssh_file,  [{optimize,Time‐
173              OrSpace}]}  in the call of "ssh:connect/3, ssh:daemon/2 or simi‐
174              lar function call that initiates an ssh connection.
175

EXPORTS

177       host_key(Algorithm, Options) -> Result
178
179              Types:
180
181                 Algorithm = ssh:pubkey_alg()
182                 Result = {ok, public_key:private_key()} | {error, term()}
183                 Options = ssh_server_key_api:daemon_key_cb_options(none())
184
185              Types and description
186
187              See   the   api   description   in   ssh_server_key_api,    Mod‐
188              ule:host_key/2.
189
190              Options
191
192                * system_dir
193
194              Files
195
196                * SYSDIR/ssh_host_rsa_key
197
198                * SYSDIR/ssh_host_dsa_key
199
200                * SYSDIR/ssh_host_ecdsa_key
201
202                * SYSDIR/ssh_host_ed25519_key
203
204                * SYSDIR/ssh_host_ed448_keyc>
205
206       is_auth_key(Key, User, Options) -> boolean()
207
208              Types:
209
210                 Key = public_key:public_key()
211                 User = string()
212                 Options =
213                     ssh_server_key_api:daemon_key_cb_options(opti‐
214                 mize_key_lookup())
215
216              Types and description
217
218              See   the   api   description   in   ssh_server_key_api:    Mod‐
219              ule:is_auth_key/3.
220
221              Options
222
223                * user_dir_fun
224
225                * user_dir
226
227              Files
228
229                * USERDIR/authorized_keys
230
231                * USERDIR/authorized_keys2
232
233              This functions discards all options in the begining of the lines
234              of thoose files when reading them.
235
236       add_host_key(Host, Port, Key, Options) -> Result
237
238              Types:
239
240                 Host =
241                     inet:ip_address() |
242                     inet:hostname() |
243                     [inet:ip_address() | inet:hostname()]
244                 Port = inet:port_number()
245                 Key = public_key:public_key()
246                 Options = ssh_client_key_api:client_key_cb_options(none())
247                 Result = ok | {error, term()}
248
249              Types and description
250
251              See   the   api   description   in   ssh_client_key_api,    Mod‐
252              ule:add_host_key/4.
253
254              Note  that  the alternative, the old Module:add_host_key/3 is no
255              longer supported by ssh_file.
256
257              Option
258
259                * user_dir
260
261              File
262
263                * USERDIR/known_hosts
264
265       is_host_key(Key, Host, Port, Algorithm, Options) -> Result
266
267              Types:
268
269                 Key = public_key:public_key()
270                 Host =
271                     inet:ip_address() |
272                     inet:hostname() |
273                     [inet:ip_address() | inet:hostname()]
274                 Port = inet:port_number()
275                 Algorithm = ssh:pubkey_alg()
276                 Options =
277                     ssh_client_key_api:client_key_cb_options(opti‐
278                 mize_key_lookup())
279                 Result = boolean() | {error, term()}
280
281              Types and description
282
283              See    the   api   description   in   ssh_client_key_api,   Mod‐
284              ule:is_host_key/5.
285
286              Note that the alternative, the old  Module:is_host_key/4  is  no
287              longer supported by ssh_file.
288
289              Option
290
291                * user_dir
292
293              File
294
295                * USERDIR/known_hosts
296
297       user_key(Algorithm, Options) -> Result
298
299              Types:
300
301                 Algorithm = ssh:pubkey_alg()
302                 Result = {ok, public_key:private_key()} | {error, string()}
303                 Options = ssh_client_key_api:client_key_cb_options(none())
304
305              Types and description
306
307              See    the   api   description   in   ssh_client_key_api,   Mod‐
308              ule:user_key/2.
309
310              Options
311
312                * user_dir
313
314                * dsa_pass_phrase
315
316                * rsa_pass_phrase
317
318                * ecdsa_pass_phrase
319
320              Note that EdDSA passhrases (Curves 25519 and 448) are not imple‐
321              mented.
322
323              Files
324
325                * USERDIR/id_dsa
326
327                * USERDIR/id_rsa
328
329                * USERDIR/id_ecdsa
330
331                * USERDIR/id_ed25519
332
333                * USERDIR/id_ed448
334
335       decode(SshBin, ssh2_pubkey) -> Key
336       decode(SshBin, rfc4716_key) -> ResultRfc4716
337       decode(SshBin, openssh_key) -> ResultOpenSsh
338       decode(SshBin, public_key) -> ResultRfc4716 | ResultOpenSsh
339
340              Types:
341
342                 SshBin = binary()
343                 ResultRfc4716 = [{Key, [{headers,Hdrs}]}] | Error
344                 ResultOpenSsh = [{Key, [{comment,string()}]}] | Error
345                 Key = public_key:public_key()
346                 Hdrs = [{Tag::string(), Value::string()}]
347                 Error = {error,term()}
348
349              Decodes an SSH file-binary.
350
351              If Type is public_key the binary can be either an RFC4716 public
352              key or an OpenSSH public key.
353
354          Note:
355              The following key types have been renamed  from  the  deprecated
356              public_key:ssh_decode/2:
357
358                * rfc4716_public_key -> rfc4716_key
359
360                * openssh_public_key -> openssh_key
361
362       encode(Key, ssh2_pubkey) -> Result
363       encode(KeyAttrsRfc4716, rfc4716_key) -> Result
364       encode(KeyAttrsOpenSsh, openssh_key) -> Result
365
366              Types:
367
368                 Key = public_key:public_key()
369                 Result = binary() | Error
370                 KeyAttrsRfc4716 = [{Key, [{headers,Hdrs}]}] | Error
371                 KeyAttrsOpenSsh = [{Key, [{comment,string()}]}] | Error
372                 Hdrs = [{Tag::string(), Value::string()}]
373                 Error = {error,term()}
374
375              Encodes  a list of SSH file entries (public keys and attributes)
376              to a binary.
377
378          Note:
379              The following key types have been renamed  from  the  deprecated
380              public_key:ssh_encode/2:
381
382                * rfc4716_public_key -> rfc4716_key
383
384                * openssh_public_key -> openssh_key
385
386Ericsson AB                       ssh 4.12.5                       ssh_file(3)