A proposal for OPEN

[Joseph Galbraith <galb%vandyke.com@localhost>]

As we've worked with SFTP v4, we've found the open
command a little awkward in some cases because the
client can't really specify what access it wants
and so we are left guessing how to open the file.

For example, we typically open the file with
READ_DATA and/or WRITE_DATA access, but not
with WRITE_ACL.  If the client does a fsetstat
and includes an ACL, we will fail because we
didn't open the file with enough access.  But,
if we opened the file for WRITE_ACL, we might
fail to open the file and the client never
would have attempted to write an acl anyway.

I'm proposing the following new open command
for v5:

byte   SSH_FXP_OPEN
string filename
uint32 access_desired
uint32 access_flags
attrib open_attrs

access_desired
   Any of the ace-mask flags from section 5.7.

access_flags
   The access_flags is two seperate bit fields.  Bit values
   in the 0xFFFF0000 mask are required, and if they can not
   be supported, the operation MUST fail.

   Bit values in the 0x0000FFFF mask are requested, but if they
   can not be supported the operation SHOULD continue.

   Clients MUST NOT send any undefined bits in the access_flags
   field.  Servers should ignore any bits not specified here.

   Future IETF action may add additional bits without
   reving the version number.

   The following required fields are defined:
       ACCESS_DISPOSITION    = 0x00070000
           CREATE_NEW        = 0x00000000
           CREATE_OVERWRITE  = 0x00010000
           OPEN_EXISTING     = 0x00020000
           OPEN_OR_CREATE    = 0x00030000
           TRUNCATE_EXISTING = 0x00040000
       ACCESS_APPEND_DATA    = 0x00080000

   The following required fields are defined:
       ACCESS_SHARE_READ    = 0x00000001
       ACCESS_SHARE_WRITE   = 0x00000002
       ACCESS_SHARE_DELETE  = 0x00000004

   Several flags in the SSH_FILEXFER_ATTR_FLAGS
   in the open_attrs also control aspects of file
   creation; this flags have no affect during
   file open (to change these values for existing
   files, clients MUST use setstat or fsetstat)

    SSH_FILEXFER_ATTR_FLAGS_READONLY
        Advisory readonly bit should be set.  (This does not
        affect the current operation, only future operation.)

    SSH_FILEXFER_ATTR_FLAGS_SYSTEM
        The file should be marked as part of operating system.

    SSH_FILEXFER_ATTR_FLAGS_HIDDEN
        File should be hidden from the user.

    SSH_FILEXFER_ATTR_FLAGS_ARCHIVE
        The file should be included in backup / archive operations.

    SSH_FILEXFER_ATTR_FLAGS_ENCRYPTED
        The file should be encrypted.  If the filesystem doesn't support
        encryption, the operation must return UNSUPPORTED.

    SSH_FILEXFER_ATTR_FLAGS_COMPRESSED
        The file should be compressed.  If the filesystem doesn't support
        compression, the operation must return UNSUPPORTED.

    SSH_FILEXFER_ATTR_FLAGS_SPARSE_OPTION
    SSH_FILEXFER_ATTR_FLAGS_SPARSE_REQUIRED
        The file should be sparse.  If SPARSE_REQUIRED is specified, the operation
        MUST fail if it is not supported.

-----
   I've chosen the DISPOSITION value over the previous
   CREAT/TRUNC/EXCL bit mask because it:

   a. takes the same three bits
   b. removes the ability to specify poorly defined
      combinations (TRUNC|EXCL)
   c. I think it is easier to understand.
   d. Has room for expanision if we need it

What do people think?

Thanks,

Joseph