IETF SECSH Working Group Simon Tatham Informal Proposal February 2001 User Database Functions for the SSH File Transfer Protocol 1. Status of this Memo This section needs filling in. Distribution of this memo is unlimited. 2. Copyright Notice Copyright (C) 2001 by Simon Tatham. 3. Abstract This memo describes a proposed extension to the SSH File Transfer Protocol (SFTP). It allows the SFTP client to perform lookups in the server's user database, allowing translation between textual user names and numeric user IDs, and also allowing the client to look up the locations of other users' home directories. The name of the proposed extension is located in domain-private space, so it could be implemented as it stands without requiring authority from anybody. It is being presented to the IETF SECSH working group for comments and to see if they want to standardise it. 4. Overview and Rationale The SSH File Transfer Protocol allows remote manipulation of a file system on a multi-user server. The protocol allows the client to retrieve a numeric user ID and group ID denoting the owner of any given file or directory, and also allows the client to specify a new numeric user ID or group ID for a file (assuming the user's account on the server is sufficiently privileged to do this). Many systems running SFTP servers maintain a user database mapping numeric user IDs to textual user names. When operating locally on such a system, users are accustomed to using the textual user names to specify ownership changes. They expect the system to translate back and forth between names and numbers wherever necessary, and they do not expect to have to remember any numeric user IDs at all. The interface presented by SFTP is unhelpful to such a user. In addition, there is often a need for a user to retrieve a file from Tatham [Page 1] Informal Proposal February 2001 another user's home directory. Again, when operating locally, the user is accustomed to being able to specify this location logically, using a syntax such as `~jrandom', rather than having to remember the physical location of that user's home directory. Therefore, once again, the interface presented by SFTP is lacking; a user might reasonably expect the SFTP client to be able to find another user's home directory automatically. 5. Enabling the Extension This protocol extension is announced by the SFTP server, as a pair of extension strings in the SSH_FXP_VERSION packet: string extension_name "sftp-userdb@sgt.greenend.org.uk" string extension_data "1" The extension_data string, "1", denotes the version of this extension. The version number should be incremented for each incompatible revision of the extension. If the client does not see this extension listed in the SSH_FXP_VERSION packet, it MUST NOT attempt any of the extended commands defined in this memo. 6. User and Group Database Entries New compound data types are defined for encoding a user database entry. They are just combinations of elementary types, defined once to ensure maintainability and consistency. The USER data type, encoding a user database entry, is defined here: uint32 flags uint32 uid always present uint32 gid present only if flag SSH_FILEXFER_UDB_GID string username present only if flag SSH_FILEXFER_UDB_USERNAME string homedir present only if flag SSH_FILEXFER_UDB_HOMEDIR uint32 extended_count present only if flag SSH_FILEXFER_UDB_EXTENDED string extended_type string extended_data ... more extended data (extended_type - extended_data pairs), so that number of pairs equals extended_count The `flags' specify which of the fields are present. Those fields for which the corresponding flag is not set are not present (not included in the packet). New flags can only be added by incrementing the extension version number (see section 5), or by using the extension mechanism. Tatham [Page 2] Informal Proposal February 2001 The `uid' field specifies the numeric user ID of the entry. It MUST have the same meaning as the numeric user IDs used in the ATTRS compound data type in the main SFTP protocol. The `uid' field has no corresponding flag and MUST be present. The `gid' field specifies the numeric group ID of the user's default group. The `username' field specifies a textual user name. It SHOULD be the same name that appears in the longname field of the ATTRS compound data type in the main SFTP protocol, if the longname field is in the recommended format. (That is, if the client receives an ATTRS record for a file owned by a particular user, and then performs a user-by- uid lookup on the numeric UID, it SHOULD receive the same username that was in the longname field for that file.) The `homedir' field specifies a full path name pointing at the user's home directory. This path name need not be fully canonical, but it MUST be valid if passed in a SSH_FXP_OPENDIR or SSH_FXP_REALPATH message in the main SFTP protocol. The `extended_count', `extended_type' and `extended_data' fields work similarly to the ATTRS compound data type in the main SFTP protocol. The GROUP data type, encoding a group database entry, is defined here: uint32 flags uint32 gid always present string groupname present only if flag SSH_FILEXFER_UDB_GROUPNAME uint32 extended_count present only if flag SSH_FILEXFER_UDB_EXTENDED string extended_type string extended_data ... more extended data (extended_type - extended_data pairs), so that number of pairs equals extended_count Like the USER data type, the `flags' specify which of the fields are present. The `gid' field specifies the numeric group ID of the entry. It MUST have the same meaning as the numeric group IDs used in the ATTRS compound data type in the main SFTP protocol. The `gid' field has no corresponding flag and MUST be present. The `groupname' field specifies a textual group name. It SHOULD be the same name that appears in the longname field of the ATTRS compound data type in the main SFTP protocol, if the longname field is in the recommended format. (That is, if the client receives an Tatham [Page 3] Informal Proposal February 2001 ATTRS record for a file owned by a particular group, and then performs a group-by-gid lookup on the numeric GID, it SHOULD receive the same group name that was in the longname field for that file.) The `extended_count', `extended_type' and `extended_data' fields work similarly to the ATTRS compound data type in the main SFTP protocol. 7. User Lookup Commands This extension defines four additional requests the client can make of the SFTP server. All of them use the SSH_FXP_EXTENDED packet type for the request. To look up a user by numeric user ID: uint32 id string "sftp-userdb-getuserbyuid@sgt.greenend.org.uk" uint32 uid To look up a user by name: uint32 id string "sftp-userdb-getuserbyname@sgt.greenend.org.uk" string username To look up a group by numeric group ID: uint32 id string "sftp-userdb-getgroupbygid@sgt.greenend.org.uk" uint32 gid To look up a group by name: uint32 id string "sftp-userdb-getgroupbyname@sgt.greenend.org.uk" string groupname The functions to look up a user return the following SSH_FXP_EXTENDED_REPLY packet if they succeed: uint32 id USER user The functions to look up a group return the following SSH_FXP_EXTENDED_REPLY packet if they succeed: uint32 id GROUP group Tatham [Page 4] Informal Proposal February 2001 If any of these functions fail, they return a SSH_FXP_STATUS packet with the error code set to SSH_FX_FAILURE. 8. Security Considerations This protocol extension operates within the SSH File Transfer Protocol, and accordingly makes the same assumption that it is externally protected from network-level attacks. This protocol provides access to the user database on the server (though this access MAY be constrained by the server implementation). It is the responsibility of the server implementation to enforce any access controls that may be required to limit the access allowed for any particular user (the user being authenticated externally to this protocol, typically using the SSH User Authentication Protocol). For example, if a server allows its authorised users SFTP access to manipulate the files they own, but also wishes to allow anonymous SFTP access to everybody for some particular publicly available files, it is likely that the server might wish to allow unrestricted user database access to authorised users but to provide only a restricted service, or no service at all, to anonymous users. 9. References This section needs filling in. Tatham [Page 5]