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       Optionally, 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(), openssh_key_v1_attributes()}]
182
183       openssh_key_v1_attributes() = [{atom(), term()}]
184
185              Types for the experimental implementaition of the openssh_key_v1
186              format.
187

EXPORTS

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