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
176       key() = public_key:public_key() | public_key:private_key()
177
178              The key representation.
179
180       experimental_openssh_key_v1() =
181           [{key() |
182             {ed_pri, ed25519 | ed448, Pub :: binary(), Priv :: binary()} |
183             {ed_pub, ed25519 | ed448, Key :: binary()},
184             openssh_key_v1_attributes()}]
185
186       openssh_key_v1_attributes() = [{atom(), term()}]
187
188              Types for the experimental implementaition of the openssh_key_v1
189              format.  The  #ECPoint{} and ECPrivateKey{} are not used for Ed‐
190              wards curves (ed25519 and ed448), but will be in next major  re‐
191              lease.
192

EXPORTS

194       host_key(Algorithm, Options) -> Result
195
196              Types:
197
198                 Algorithm = ssh:pubkey_alg()
199                 Result = {ok, public_key:private_key()} | {error, term()}
200                 Options = ssh_server_key_api:daemon_key_cb_options(none())
201
202              Types and description
203
204              See    the   api   description   in   ssh_server_key_api,   Mod‐
205              ule:host_key/2.
206
207              Options
208
209                * system_dir
210
211              Files
212
213                * SYSDIR/ssh_host_rsa_key
214
215                * SYSDIR/ssh_host_dsa_key
216
217                * SYSDIR/ssh_host_ecdsa_key
218
219                * SYSDIR/ssh_host_ed25519_key
220
221                * SYSDIR/ssh_host_ed448_keyc>
222
223       is_auth_key(Key, User, Options) -> boolean()
224
225              Types:
226
227                 Key = public_key:public_key()
228                 User = string()
229                 Options =
230                     ssh_server_key_api:daemon_key_cb_options(opti‐
231                 mize_key_lookup())
232
233              Types and description
234
235              See    the   api   description   in   ssh_server_key_api:   Mod‐
236              ule:is_auth_key/3.
237
238              Options
239
240                * user_dir_fun
241
242                * user_dir
243
244              Files
245
246                * USERDIR/authorized_keys
247
248                * USERDIR/authorized_keys2
249
250              This functions discards all options in the begining of the lines
251              of thoose files when reading them.
252
253       add_host_key(Host, Port, Key, Options) -> Result
254
255              Types:
256
257                 Host =
258                     inet:ip_address() |
259                     inet:hostname() |
260                     [inet:ip_address() | inet:hostname()]
261                 Port = inet:port_number()
262                 Key = public_key:public_key()
263                 Options = ssh_client_key_api:client_key_cb_options(none())
264                 Result = ok | {error, term()}
265
266              Types and description
267
268              See    the   api   description   in   ssh_client_key_api,   Mod‐
269              ule:add_host_key/4.
270
271              Note that the alternative, the old Module:add_host_key/3  is  no
272              longer supported by ssh_file.
273
274              Option
275
276                * user_dir
277
278              File
279
280                * USERDIR/known_hosts
281
282       is_host_key(Key, Host, Port, Algorithm, Options) -> Result
283
284              Types:
285
286                 Key = public_key:public_key()
287                 Host =
288                     inet:ip_address() |
289                     inet:hostname() |
290                     [inet:ip_address() | inet:hostname()]
291                 Port = inet:port_number()
292                 Algorithm = ssh:pubkey_alg()
293                 Options =
294                     ssh_client_key_api:client_key_cb_options(opti‐
295                 mize_key_lookup())
296                 Result = boolean() | {error, term()}
297
298              Types and description
299
300              See   the   api   description   in   ssh_client_key_api,    Mod‐
301              ule:is_host_key/5.
302
303              Note  that  the  alternative, the old Module:is_host_key/4 is no
304              longer supported by ssh_file.
305
306              Option
307
308                * user_dir
309
310              File
311
312                * USERDIR/known_hosts
313
314       user_key(Algorithm, Options) -> Result
315
316              Types:
317
318                 Algorithm = ssh:pubkey_alg()
319                 Result = {ok, public_key:private_key()} | {error, string()}
320                 Options = ssh_client_key_api:client_key_cb_options(none())
321
322              Types and description
323
324              See   the   api   description   in   ssh_client_key_api,    Mod‐
325              ule:user_key/2.
326
327              Options
328
329                * user_dir
330
331                * dsa_pass_phrase
332
333                * rsa_pass_phrase
334
335                * ecdsa_pass_phrase
336
337              Note that EdDSA passhrases (Curves 25519 and 448) are not imple‐
338              mented.
339
340              Files
341
342                * USERDIR/id_dsa
343
344                * USERDIR/id_rsa
345
346                * USERDIR/id_ecdsa
347
348                * USERDIR/id_ed25519
349
350                * USERDIR/id_ed448
351
352       decode(SshBin, Type) -> Decoded | {error, term()}
353
354              Types:
355
356                 SshBin = binary()
357                 Type =
358                     ssh2_pubkey | public_key | openssh_key | rfc4716_key |
359                     openssh_key_v1 | known_hosts | auth_keys
360                 Decoded =
361                     Decoded_ssh2_pubkey | Decoded_public | Decoded_openssh |
362                     Decoded_rfc4716 | Decoded_openssh_key_v1 |
363                     Decoded_known_hosts | Decoded_auth_keys
364                 Decoded_ssh2_pubkey = public_key:public_key()
365                 Decoded_public =
366                     Decoded_rfc4716   |    Decoded_openssh_key_v1    |    De‐
367                 coded_openssh
368                 Decoded_openssh =
369                     [{public_key:public_key(), [{comment, string()}]}]
370                 Decoded_rfc4716 = [{key(), [{headers, Attrs}]}]
371                 Decoded_openssh_key_v1 = experimental_openssh_key_v1()
372                 Decoded_known_hosts =
373                     [{public_key:public_key(),
374                       [{comment, string()} | {hostnames, [string()]}]}]
375                 Decoded_auth_keys =
376                     [{public_key:public_key(),
377                       [{comment, string()} | {options, [string()]}]}]
378                 Attrs = {Key :: string(), Value :: string()}
379
380              Decodes an SSH file-binary.
381
382              If Type is public_key the binary can be either an RFC4716 public
383              key or an OpenSSH public key.
384
385          Note:
386              The following key types have been renamed  from  the  deprecated
387              public_key:ssh_decode/2:
388
389                * rfc4716_public_key -> rfc4716_key
390
391                * openssh_public_key -> openssh_key
392
393          Note:
394              The implementation of the openssh_key_v1 format is still experi‐
395              mental.
396
397
398       encode(InData, Type) -> binary() | {error, term()}
399
400              Types:
401
402                 Type =
403                     ssh2_pubkey | openssh_key | rfc4716_key |  openssh_key_v1
404                 |
405                     known_hosts | auth_keys
406                 InData =
407                     InData_ssh2_pubkey | InData_openssh | InData_rfc4716 |
408                     InData_openssh_key_v1    |   InData_known_hosts   |   In‐
409                 Data_auth_keys
410                 InData_ssh2_pubkey = public_key:public_key()
411                 InData_openssh =
412                     [{public_key:public_key(), [{comment, string()}]}]
413                 InData_rfc4716 = [{key(), [{headers, Attrs}]}]
414                 InData_openssh_key_v1 = experimental_openssh_key_v1()
415                 InData_known_hosts =
416                     [{public_key:public_key(),
417                       [{comment, string()} | {hostnames, [string()]}]}]
418                 InData_auth_keys =
419                     [{public_key:public_key(),
420                       [{comment, string()} | {options, [string()]}]}]
421                 Attrs = {Key :: string(), Value :: string()}
422
423              Encodes a list of SSH file entries (public keys and  attributes)
424              to a binary.
425
426          Note:
427              The  following  key  types have been renamed from the deprecated
428              public_key:ssh_encode/2:
429
430                * rfc4716_public_key -> rfc4716_key
431
432                * openssh_public_key -> openssh_key
433
434          Note:
435              The implementation of the openssh_key_v1 format is still experi‐
436              mental.
437
438
439
440
441Ericsson AB                      ssh 4.13.2.1                      ssh_file(3)