source: trunk/docs/frontends/FTP-and-SFTP.rst

Last change on this file was 5878a64, checked in by Jean-Paul Calderone <exarkun@…>, at 2021-10-26T00:50:19Z

Remove password-based authentication from the SFTP frontend

  • Property mode set to 100644
File size: 7.5 KB
Line 
1.. -*- coding: utf-8-with-signature -*-
2
3========================
4Tahoe-LAFS SFTP Frontend
5========================
6
71.  `SFTP Background`_
82.  `Tahoe-LAFS Support`_
93.  `Creating an Account File`_
104.  `Configuring SFTP Access`_
115.  `Dependencies`_
126.  `Immutable and Mutable Files`_
137.  `Known Issues`_
14
15
16SFTP Background
17===============
18
19FTP is the venerable internet file-transfer protocol, first developed in
201971. The FTP server usually listens on port 21. A separate connection is
21used for the actual data transfers, either in the same direction as the
22initial client-to-server connection (for PORT mode), or in the reverse
23direction (for PASV) mode. Connections are unencrypted, so passwords, file
24names, and file contents are visible to eavesdroppers.
25
26SFTP is the modern replacement, developed as part of the SSH "secure shell"
27protocol, and runs as a subchannel of the regular SSH connection. The SSH
28server usually listens on port 22. All connections are encrypted.
29
30Both FTP and SFTP were developed assuming a UNIX-like server, with accounts
31and passwords, octal file modes (user/group/other, read/write/execute), and
32ctime/mtime timestamps.
33
34Previous versions of Tahoe-LAFS supported FTP, but now only the superior SFTP
35frontend is supported. See `Known Issues`_, below, for details on the
36limitations of SFTP.
37
38Tahoe-LAFS Support
39==================
40
41All Tahoe-LAFS client nodes can run a frontend SFTP server, allowing regular
42SFTP clients (like ``/usr/bin/sftp``, the ``sshfs`` FUSE plugin, and many
43others) to access the file store.
44
45Since Tahoe-LAFS does not use user accounts or passwords, the SFTP
46servers must be configured with a way to first authenticate a user (confirm
47that a prospective client has a legitimate claim to whatever authorities we
48might grant a particular user), and second to decide what directory cap
49should be used as the root directory for a log-in by the authenticated user.
50As of Tahoe-LAFS v1.17,
51RSA/DSA public key authentication is the only supported mechanism.
52
53Tahoe-LAFS provides two mechanisms to perform this user-to-cap mapping.
54The first (recommended) is a simple flat file with one account per line.
55The second is an HTTP-based login mechanism.
56
57Creating an Account File
58========================
59
60To use the first form, create a file (for example ``BASEDIR/private/accounts``)
61in which each non-comment/non-blank line is a space-separated line of
62(USERNAME, KEY-TYPE, PUBLIC-KEY, ROOTCAP), like so::
63
64 % cat BASEDIR/private/accounts
65 # This is a public key line: username keytype pubkey cap
66 # (Tahoe-LAFS v1.11 or later)
67 carol ssh-rsa AAAA... URI:DIR2:ovjy4yhylqlfoqg2vcze36dhde:4d4f47qko2xm5g7osgo2yyidi5m4muyo2vjjy53q4vjju2u55mfa
68
69The key type may be either "ssh-rsa" or "ssh-dsa".
70
71Now add an ``accounts.file`` directive to your ``tahoe.cfg`` file, as described in
72the next sections.
73
74Configuring SFTP Access
75=======================
76
77The Tahoe-LAFS SFTP server requires a host keypair, just like the regular SSH
78server. It is important to give each server a distinct keypair, to prevent
79one server from masquerading as different one. The first time a client
80program talks to a given server, it will store the host key it receives, and
81will complain if a subsequent connection uses a different key. This reduces
82the opportunity for man-in-the-middle attacks to just the first connection.
83
84Exercise caution when connecting to the SFTP server remotely. The AES
85implementation used by the SFTP code does not have defenses against timing
86attacks. The code for encrypting the SFTP connection was not written by the
87Tahoe-LAFS team, and we have not reviewed it as carefully as we have reviewed
88the code for encrypting files and directories in Tahoe-LAFS itself. (See
89`Twisted ticket #4633`_ for a possible fix to this issue.)
90
91.. _Twisted ticket #4633: https://twistedmatrix.com/trac/ticket/4633
92
93If you can connect to the SFTP server (which is provided by the Tahoe-LAFS
94gateway) only from a client on the same host, then you would be safe from any
95problem with the SFTP connection security. The examples given below enforce
96this policy by including ":interface=127.0.0.1" in the "port" option, which
97causes the server to only accept connections from localhost.
98
99You will use directives in the tahoe.cfg file to tell the SFTP code where to
100find these keys. To create one, use the ``ssh-keygen`` tool (which comes with
101the standard OpenSSH client distribution)::
102
103 % cd BASEDIR
104 % ssh-keygen -f private/ssh_host_rsa_key
105
106The server private key file must not have a passphrase.
107
108Then, to enable the SFTP server with an accounts file, add the following
109lines to the BASEDIR/tahoe.cfg file::
110
111 [sftpd]
112 enabled = true
113 port = tcp:8022:interface=127.0.0.1
114 host_pubkey_file = private/ssh_host_rsa_key.pub
115 host_privkey_file = private/ssh_host_rsa_key
116 accounts.file = private/accounts
117
118The SFTP server will listen on the given port number and on the loopback
119interface only. The "accounts.file" pathname will be interpreted relative to
120the node's BASEDIR.
121
122Or, to use an account server instead, do this::
123
124 [sftpd]
125 enabled = true
126 port = tcp:8022:interface=127.0.0.1
127 host_pubkey_file = private/ssh_host_rsa_key.pub
128 host_privkey_file = private/ssh_host_rsa_key
129 accounts.url = https://example.com/login
130
131You can provide both accounts.file and accounts.url, although it probably
132isn't very useful except for testing.
133
134For further information on SFTP compatibility and known issues with various
135clients and with the sshfs filesystem, see wiki:SftpFrontend_
136
137.. _wiki:SftpFrontend: https://tahoe-lafs.org/trac/tahoe-lafs/wiki/SftpFrontend
138
139Dependencies
140============
141
142The Tahoe-LAFS SFTP server requires the Twisted "Conch" component (a "conch"
143is a twisted shell, get it?). Many Linux distributions package the Conch code
144separately: debian puts it in the "python-twisted-conch" package.
145
146Immutable and Mutable Files
147===========================
148
149All files created via SFTP are immutable files. However, files can
150only be created in writeable directories, which allows the directory entry to
151be relinked to a different file. Normally, when the path of an immutable file
152is opened for writing by SFTP, the directory entry is relinked to another
153file with the newly written contents when the file handle is closed. The old
154file is still present on the grid, and any other caps to it will remain
155valid. (See :doc:`../garbage-collection` for how to reclaim the space used by
156files that are no longer needed.)
157
158The 'no-write' metadata field of a directory entry can override this
159behaviour. If the 'no-write' field holds a true value, then a permission
160error will occur when trying to write to the file, even if it is in a
161writeable directory. This does not prevent the directory entry from being
162unlinked or replaced.
163
164When using sshfs, the 'no-write' field can be set by clearing the 'w' bits in
165the Unix permissions, for example using the command ``chmod 444 path/to/file``.
166Note that this does not mean that arbitrary combinations of Unix permissions
167are supported. If the 'w' bits are cleared on a link to a mutable file or
168directory, that link will become read-only.
169
170If SFTP is used to write to an existing mutable file, it will publish a new
171version when the file handle is closed.
172
173Known Issues
174============
175
176Known Issues in the SFTP Frontend
177---------------------------------
178
179Upload errors may not be reported when writing files using SFTP via sshfs
180(`ticket #1059`_).
181
182Non-ASCII filenames are supported with SFTP only if the client encodes
183filenames as UTF-8 (`ticket #1089`_).
184
185See also wiki:SftpFrontend_.
186
187.. _ticket #1059: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1059
188.. _ticket #1089: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1089
Note: See TracBrowser for help on using the repository browser.