Commit 89aa679cfb96d2b32ad35356758248996faa6060 - libnet-sftp-foreign-perl

[svn-upgrade] new version libnet-sftp-foreign-perl (1.62) Nicholas Bamber 13 years ago

19 changed file(s) with 8205 addition(s) and 121 deletion(s). Raw diff Collapse all Expand all

+58

-6

Changes less more

0	0	Revision history for Net::SFTP::Foreign
1	1
	2
	3	1.62 Oct 5, 2010
	4	- _catch_tainted_args was not being imported from helpers (bug
	5	report by rfbits at PerlMonks)
	6
	7	1.61 Sep 22, 2010
	8	- remove some dead code introducing unneded constraints that
	9	cause the Net::SSH2 backend to fail (bug report by Philippe
	10	Vouters)
	11
	12	1.60 Sep 20, 2010
	13	- _ensure_list was not being imported from Helpers (bug report
	14	and solution by Jean-Benoît Baudens)
	15
	16	1.59 Sep 16, 2010
	17	- kill ssh subprocess with KILL signal on Windows
	18
	19	1.58_08 Aug 22, 2010
	20	- import _hexdump from Helpers.pm (bug report by Chuck Kozak)
	21	- call kill passing the signal name instead of using POSIX to
	22	get its number
	23
	24	1.58_07 Aug 2, 2010
	25	- dump $! on failed sysreads and syswrites
	26
	27	1.58_06 Jul 12, 2010
	28	- rput was broken under Windows (bug report by Brian
	29	E. Lozier)
	30	- do not use Fcntl S_IS* macro wrappers as S_ISLNK is not
	31	available under Windows
	32	- new FAQ about put failing because of forbidden setstat
	33	- minor doc improvements
	34	- use "kill $name" instead of using POSIX to get the signal
	35	number
	36
	37	1.58_05 Jun 7, 2010
	38	- add support for stderr_discard also in Windows backend
	39
	40	1.58_04 Jun 7, 2010
	41	- add support for stderr_discard
	42
	43	1.58_03 May 27, 2010
	44	- even more debugging for put method and the resume feature
	45
	46	1.58_02
	47	- add FAQ about strict host key checking
	48	- better debugging for put method
	49
	50	1.58_01 Apr 19, 2010
	51	- add stderr redirection feature
	52	- minor doc corrections
	53	- add donating to OpenSSH entry in docs
	54
2	55	1.57 Mar 14, 2010
3		- release as stable
	56	- release as stable
4	57
5	58	1.56_09 Mar 11, 2010
6		- realpath feature was broken on find and ls methods (bug
7		report by Paul Kolano)
8		- taint checks on hashes where not reporting problemns
9		properly
10		- minor doc corrections
	59	- realpath feature was broken on find and ls methods (bug
	60	report by Paul Kolano)
	61	- taint checks on hashes were not reporting problems properly
	62	- minor doc corrections
11	63
12	64	1.56_08 Jan 5, 2010
13	65	- put'ting a tied file handle was generating some warnings

-0

MANIFEST less more

14	14	Makefile.PL
15	15	MANIFEST
16	16	README
	17	rfc/draft-ietf-secsh-filexfer-02.txt
	18	rfc/draft-ietf-secsh-filexfer-03.txt
	19	rfc/draft-ietf-secsh-filexfer-12.txt
	20	rfc/draft-ietf-secsh-filexfer-extensions-00.txt
	21	rfc/OpenSSH-protocol-deviations.txt
17	22	samples/capture_stderr.pl
18	23	samples/passwd_conn.pl
19	24	samples/psftp
20	25	samples/sftp_tail.pl
	26	samples/resume_put.pl
21	27	t/1_run.t
22	28	t/2_pods.t
23	29	t/3_convert.t

-1

META.yml less more

0	0	--- #YAML:1.0
1	1	name: Net-SFTP-Foreign
2		version: 1.57
	2	version: 1.62
3	3	abstract: Secure File Transfer Protocol client
4	4	author:
5	5	- Salvador Fandino <sfandino@yahoo.com>

-2

TODO less more

0	0
1	1	TODO
2	2	====
3
4		- add support for capture_stderr option in constructor
5	3
6	4	- port to OpenVMS
7	5

17	15	DONE
18	16	====
19	17
	18	- add support for capture_stderr option in constructor
	19
20	20	- add support for new extension methods available from late OpenSSH
21	21	SFTP server (http://www.sfr-fresh.com/unix/misc/openssh-5.1.tar.gz:a/ssh/PROTOCOL)
22	22

+16

-14

debug.txt less more

0		1 - message queueing/dequeuing
1		2 - remote file/dir open/close
2		4 - DESTROY calls
3		8 - hexdumps of incomming packets
4		16 - hexdumps of outgoing packets
5		32 - _do_io, _conn_lost
6		64 - _set_error, _set_status
7		128 - on the fly transformations
8		256 - add timestamp and process id
9		512 -
10		1024 - hexdump of sysreads
11		2048 - hexdump of syswrites
12		4096 - _rel2abs
13		8192 - mkpath
	0	1 - message queueing/dequeuing
	1	2 - remote file/dir open/close
	2	4 - DESTROY calls
	3	8 - hexdumps of incomming packets
	4	16 - hexdumps of outgoing packets
	5	32 - _do_io, _conn_lost
	6	64 - _set_error, _set_status
	7	128 - on the fly transformations
	8	256 - add timestamp and process id
	9	512 -
	10	1024 - hexdump of sysreads
	11	2048 - hexdump of syswrites
	12	4096 - _rel2abs
	13	8192 - mkpath
	14	16384 - put method
	15	32768 - recursive methods

+51

-19

lib/Net/SFTP/Foreign/Backend/Unix.pm less more

0	0	package Net::SFTP::Foreign::Backend::Unix;
1	1
2		our $VERSION = '0.02';
	2	our $VERSION = '1.58_07';
3	3
4	4	use strict;
5	5	use warnings;

8	8	our @CARP_NOT = qw(Net::SFTP::Foreign);
9	9
10	10	use Fcntl qw(O_NONBLOCK F_SETFL F_GETFL);
	11	use IPC::Open3;
11	12	use IPC::Open2;
12	13	use Net::SFTP::Foreign::Helpers qw(_tcroak _ensure_list _debug _hexdump $debug);
13	14	use Net::SFTP::Foreign::Constants qw(SSH2_FX_BAD_MESSAGE

28	29	}
29	30	}
30	31
	32	sub _open_dev_null {
	33	my $sftp = shift;
	34	my $dev_null;
	35	unless (open $dev_null, '>', "/dev/null") {
	36	$sftp->_conn_failed("Unable to redirect stderr to /dev/null");
	37	return;
	38	}
	39	$dev_null
	40	}
	41
31	42	sub _ipc_open2_bug_workaround {
32	43	# in some cases, IPC::Open3::open2 returns from the child
33	44	my $pid = shift;

37	48	}
38	49	}
39	50
	51	sub _open3 {
	52	my $sftp = shift;
	53	if (defined $_[2]) {
	54	my $sftp_err = $_[2];
	55	my $fno = eval { no warnings; fileno($sftp_err) };
	56	local *SSHERR;
	57	unless (defined $fno and $fno >= 0 and
	58	open(SSHERR, ">>&=", $fno)) {
	59	$sftp->_conn_failed("Unable to duplicate stderr redirection file handle: $!");
	60	return undef;
	61	}
	62	local ($@, $SIG{__DIE__}, $SIG{__WARN__});
	63	return eval { open3(@_[1,0], ">&SSHERR", @_[3..$#_]) }
	64	}
	65	else {
	66	local ($@, $SIG{__DIE__}, $SIG{__WARN__});
	67	return eval { open2(@_[0,1], @_[3..$#_]) };
	68	}
	69	}
	70
40	71	sub _init_transport {
41	72	my ($class, $sftp, $opts) = @_;
42	73

52	83	}
53	84	}
54	85	else {
55		my (@open2_cmd, $pass, $passphrase, $expect_log_user);
56
57		$pass = delete $opts->{passphrase};
58
	86	my $pass = delete $opts->{passphrase};
	87	my $passphrase;
59	88	if (defined $pass) {
60	89	$passphrase = 1;
61	90	}

64	93	defined $pass and $sftp->{_password_authentication} = 1;
65	94	}
66	95
67		$expect_log_user = delete $opts->{expect_log_user} \|\| 0;
68
	96	my $expect_log_user = delete $opts->{expect_log_user} \|\| 0;
	97	my $stderr_discard = delete $opts->{stderr_discard};
	98	my $stderr_fh = ($stderr_discard ? undef : delete $opts->{stderr_fh});
69	99	my $open2_cmd = delete $opts->{open2_cmd};
	100
	101	my @open2_cmd;
70	102	if (defined $open2_cmd) {
71	103	@open2_cmd = _ensure_list($open2_cmd);
72	104	}

121	153	if (${^TAINT} and Scalar::Util::tainted($ENV{PATH})) {
122	154	_tcroak('Insecure $ENV{PATH}')
123	155	}
	156
	157	if ($stderr_discard) {
	158	$stderr_fh = $class->_open_dev_null($sftp) or return;
	159	}
124	160
125	161	my $this_pid = $$;
126	162

148	184	$expect->raw_pty(1);
149	185	$expect->log_user($expect_log_user);
150	186
151		$child = do {
152		local ($@, $SIG{__DIE__}, $SIG{__WARN__});
153		eval { open2($sftp->{ssh_in}, $sftp->{ssh_out}, '-') }
154		};
	187	$child = _open3($sftp, $sftp->{ssh_in}, $sftp->{ssh_out}, $stderr_fh, '-');
	188
155	189	if (defined $child and !$child) {
156	190	$pty->make_slave_controlling_terminal;
157	191	do { exec @open2_cmd }; # work around suppress warning under mod_perl

196	230	$expect->close_slave();
197	231	}
198	232	else {
199		do {
200		local ($@, $SIG{__DIE__}, $SIG{__WARN__});
201		$sftp->{pid} = eval { open2($sftp->{ssh_in}, $sftp->{ssh_out}, @open2_cmd) };
202		};
	233	$sftp->{pid} = _open3($sftp, $sftp->{ssh_in}, $sftp->{ssh_out}, $stderr_fh, @open2_cmd);
203	234	_ipc_open2_bug_workaround $this_pid;
204	235
205	236	unless (defined $sftp->{pid}) {

257	288	if (vec($wv1, $fnoout, 1)) {
258	289	my $written = syswrite($sftp->{ssh_out}, $$bout, 64 * 1024);
259	290	if ($debug and $debug & 32) {
260		_debug (sprintf "_do_io write queue: %d, syswrite: %s, max: %d",
	291	_debug (sprintf "_do_io write queue: %d, syswrite: %s, max: %d, \$!: %s",
261	292	length $$bout,
262	293	(defined $written ? $written : 'undef'),
263		64 * 1024);
	294	64 * 1024, $!);
264	295	$debug & 2048 and $written and _hexdump(substr($$bout, 0, $written));
265	296	}
266	297	unless ($written) {

272	303	if (vec($rv1, $fnoin, 1)) {
273	304	my $read = sysread($sftp->{ssh_in}, $$bin, 64 * 1024, length($$bin));
274	305	if ($debug and $debug & 32) {
275		_debug (sprintf "_do_io read sysread: %s, total read: %d",
	306	_debug (sprintf "_do_io read sysread: %s, total read: %d, \$!: %s",
276	307	(defined $read ? $read : 'undef'),
277		length $$bin);
	308	length $$bin,
	309	$!);
278	310	$debug & 1024 and $read and _hexdump(substr($$bin, -$read));
279	311	}
280	312	unless ($read) {

+11

-1

lib/Net/SFTP/Foreign/Backend/Windows.pm less more

0	0	package Net::SFTP::Foreign::Backend::Windows;
1	1
2		our $VERSION = '0.01';
	2	our $VERSION = '1.58_05';
3	3
4	4	use strict;
5	5	use warnings;

22	22	my ($self, $sftp) = @_;
23	23	binmode $sftp->{ssh_in};
24	24	binmode $sftp->{ssh_out};
	25	}
	26
	27	sub _open_dev_null {
	28	my $sftp = shift;
	29	my $dev_null;
	30	unless (open $dev_null, '>', "NUL:") {
	31	$sftp->_conn_failed("Unable to redirect stderr to NUL:");
	32	return;
	33	}
	34	$dev_null
25	35	}
26	36
27	37	sub _sysreadn {

+10

-11

lib/Net/SFTP/Foreign/Common.pm less more

5	5	use warnings;
6	6	use Carp;
7	7	use Scalar::Util qw(dualvar tainted);
8		use Fcntl qw(S_ISLNK S_ISDIR);
9
10		use Net::SFTP::Foreign::Helpers qw(_gen_wanted _ensure_list _debug _glob_to_regex $debug);
	8
	9	use Net::SFTP::Foreign::Helpers qw(_gen_wanted _ensure_list _debug _glob_to_regex _is_lnk _is_dir $debug);
11	10	use Net::SFTP::Foreign::Constants qw(:status);
12	11
13	12	my %status_str = ( SSH2_FX_OK, "OK",

154	153	my $entry = shift;
155	154	my $fn = $entry->{filename};
156	155	for (1) {
157		my $follow = ($follow_links and S_ISLNK($entry->{a}->perm));
	156	my $follow = ($follow_links and _is_lnk($entry->{a}->perm));
158	157
159	158	if ($follow or $realpath) {
160	159	unless (defined $entry->{realpath}) {

200	199	my $a = $try->{a} \|\|= $self->lstat($fn)
201	200	or next;
202	201
203		next if (S_ISDIR($a->perm) and $done{$fn}++);
	202	next if (_is_dir($a->perm) and $done{$fn}++);
204	203
205	204	$task->($try);
206	205
207		if (S_ISDIR($a->perm)) {
	206	if (_is_dir($a->perm)) {
208	207	if (!$descend or $descend->($self, $try)) {
209	208	if ($ordered or $atomic_readdir) {
210	209	my $ls = $self->ls( $fn,

228	227	if ($child !~ /^\.\.?$/) {
229	228	$entry->{filename} = $self->join($fn, $child);
230	229
231		if (S_ISDIR($entry->{a}->perm)) {
	230	if (_is_dir($entry->{a}->perm)) {
232	231	push @queue, $entry;
233	232	}
234	233	else {

294	293	if ($e->{filename} =~ $re) {
295	294	my $fn = $e->{filename} = $sftp->join($pfn, $e->{filename});
296	295	if ( (@parts or $follow_links)
297		and S_ISLNK($e->{a}->perm) ) {
	296	and _is_lnk($e->{a}->perm) ) {
298	297	if (my $a = $sftp->stat($fn)) {
299	298	$e->{a} = $a;
300	299	}

304	303	}
305	304	}
306	305	if (@parts) {
307		push @res, $e if S_ISDIR($e->{a}->perm)
	306	push @res, $e if _is_dir($e->{a}->perm)
308	307	}
309	308	elsif (!$wanted or $wanted->($sftp, $e)) {
310	309	if ($wantarray) {

332	331	if (my $a = $sftp->$method($fn)) {
333	332	my $e = { filename => $fn, a => $a };
334	333	if (@parts) {
335		push @res, $e if S_ISDIR($a->{perm})
	334	push @res, $e if _is_dir($a->{perm})
336	335	}
337	336	elsif (!$wanted or $wanted->($sftp, $e)) {
338	337	if ($wantarray) {

357	356	sub test_d {
358	357	my ($sftp, $name) = @_;
359	358	my $a = $sftp->stat($name);
360		$a ? S_ISDIR($a->perm) : undef;
	359	$a ? _is_dir($a->perm) : undef;
361	360	}
362	361
363	362	1;

-1

lib/Net/SFTP/Foreign/Helpers.pm less more

20	20	_hexdump
21	21	$debug
22	22	);
23		our @EXPORT_OK = qw( _do_nothing
	23	our @EXPORT_OK = qw( _is_lnk
	24	_is_dir
	25	_is_reg
	26	_do_nothing
24	27	_glob_to_regex
25	28	_tcroak );
26	29

300	303	}
301	304	}
302	305
	306	sub _is_lnk { (0120000 & shift) == 0120000 }
	307	sub _is_dir { (0040000 & shift) == 0040000 }
	308	sub _is_reg { (0100000 & shift) == 0100000 }
	309
303	310	1;
304	311

+146

-52

lib/Net/SFTP/Foreign.pm less more

0	0	package Net::SFTP::Foreign;
1	1
2		our $VERSION = '1.57';
	2	our $VERSION = '1.62';
3	3
4	4	use strict;
5	5	use warnings;
6	6	use Carp qw(carp croak);
7	7
8		use Fcntl qw(:mode);
9	8	use Symbol ();
10	9	use Errno ();
11	10	use Scalar::Util;

29	28	# knowing anything about the Helpers package!
30	29	our $debug;
31	30	BEGIN { *Net::SFTP::Foreign::Helpers::debug = \$debug };
32		use Net::SFTP::Foreign::Helpers;
	31	use Net::SFTP::Foreign::Helpers qw(_is_reg _is_lnk _is_dir _debug
	32	_sort_entries _gen_wanted _gen_converter
	33	_hexdump _ensure_list _catch_tainted_args);
33	34	use Net::SFTP::Foreign::Constants qw( :fxp :flags :att
34	35	:status :error
35	36	SSH2_FILEXFER_VERSION );

99	100	}
100	101
101	102	sub _conn_failed {
102		shift->_conn_lost(SSH2_FX_NO_CONNECTION,
	103	my $sftp = shift;
	104	$sftp->_conn_lost(SSH2_FX_NO_CONNECTION,
103	105	SFTP_ERR_CONNECTION_BROKEN,
104	106	@_)
	107	unless $sftp->error;
105	108	}
106	109
107	110	sub _get_msg {

235	238	close $sftp->{ssh_out} if (defined $sftp->{ssh_out} and not $sftp->{_ssh_out_is_not_dupped});
236	239	close $sftp->{ssh_in} if defined $sftp->{ssh_in};
237	240	if ($windows) {
238		require POSIX;
239		kill POSIX::SIGTERM(), $pid
	241	kill KILL => $pid
240	242	and waitpid($pid, 0);
241	243	}
242	244	else {

245	247	: $dirty_cleanup );
246	248
247	249	if ($dirty or not defined $dirty) {
248		require POSIX;
249		my $TERM = POSIX::SIGTERM();
250		my $KILL = POSIX::SIGKILL();
251		for my $sig (($dirty ? () : 0), $TERM, $TERM, $KILL, $KILL) {
	250	for my $sig (($dirty ? () : 0), qw(TERM TERM KILL KILL)) {
252	251	$sig and kill $sig, $pid;
253	252
254	253	my $except;

455	454	return undef unless defined $cwd;
456	455	my $a = $sftp->stat($cwd)
457	456	or return undef;
458		if (S_ISDIR($a->perm)) {
	457	if (_is_dir($a->perm)) {
459	458	return $sftp->{cwd} = $cwd;
460	459	}
461	460	else {

638	637	my @written;
639	638	my $written = 0;
640	639	my $end;
641
642		my $selin = '';
643		vec($selin, fileno($sftp->{ssh_in}), 1) = 1;
644	640
645	641	while (!$end or @msgid) {
646	642	while (!$end and @msgid < $qsize) {

1449	1445	unless (defined $perm or $local_is_fh);
1450	1446
1451	1447	if ($resume) {
1452		if (CORE::open $fh, '>>', $local) {
	1448	if (CORE::open $fh, '>', $local) {
1453	1449	binmode $fh;
1454	1450	CORE::seek($fh, 0, 2);
1455	1451	$askoff = CORE::tell $fh;

1465	1461	"Couldn't resume transfer, local file is bigger than remote");
1466	1462	return undef;
1467	1463	}
1468
1469	1464	$size == $askoff and return 1;
1470	1465	}
1471	1466	}

1518	1513	my @msgid;
1519	1514	my @askoff;
1520	1515	my $loff = $askoff;
1521		my $rfno = fileno($sftp->{ssh_in});
1522	1516	my $adjustment = 0;
1523		my $selin = '';
1524	1517	my $n = 0;
1525	1518	local $\;
1526
1527		vec ($selin, $rfno, 1) = 1;
1528	1519
1529	1520	while (1) {
1530	1521	# request a new block if queue is not full

1755	1746	) {
1756	1747	# $fh can point at some place inside the file, not just at the
1757	1748	# begining
1758		if ($local_is_fh) {
	1749	if ($local_is_fh and defined $lsize) {
1759	1750	my $tell = eval { CORE::tell $fh };
1760	1751	$lsize -= $tell if ($tell and $tell > 0);
1761	1752	}

1765	1756	"Couldn't stat local file '$local'", $!);
1766	1757	return undef;
1767	1758	}
1768		else {
1769		undef $resume if ($resume and $resume eq 'auto');
	1759	elsif ($resume and $resume eq 'auto') {
	1760	$debug and $debug & 16384 and _debug "not resuming because stat'ing the local file failed";
	1761	undef $resume
1770	1762	}
1771	1763	}
1772	1764

1783	1775	my $rattrs = $sftp->stat($remote);
1784	1776	if ($rattrs) {
1785	1777	if ($resume and $resume eq 'auto' and $rattrs->mtime >= $lmtime) {
	1778	$debug and $debug & 16384 and
	1779	_debug "not resuming because local file is newer, r: ".$rattrs->mtime." l: $lmtime";
1786	1780	undef $resume;
1787	1781	}
1788	1782	else {
1789	1783	$writeoff = $rattrs->size;
	1784	$debug and $debug & 16384 and _debug "resuming from $writeoff";
1790	1785	}
1791	1786	}
1792	1787	elsif ($append) {

1795	1790	}
1796	1791
1797	1792	if ($resume and $writeoff) {
	1793	$debug and $debug & 16384 and _debug "resuming file transfer from $writeoff";
1798	1794	if ($converter) {
1799	1795	# as size could change, we have to read and convert
1800	1796	# data until we reach the given position on the local

1805	1801	my $len = length $converted_input;
1806	1802	my $delta = $writeoff - $off;
1807	1803	if ($delta <= $len) {
	1804	$debug and $debug & 16384 and _debug "discarding $delta converted bytes";
1808	1805	substr $converted_input, 0, $delta, '';
1809	1806	last;
1810	1807	}

1837	1834	while ($off) {
1838	1835	my $read = CORE::read($fh, my($buf), ($off < 16384 ? $off : 16384));
1839	1836	if ($read) {
	1837	$debug and $debug & 16384 and _debug "discarding $read bytes";
1840	1838	$off -= $read;
1841	1839	}
1842	1840	else {

1904	1902	# if lsize is undef, we initialize it to $writeoff:
1905	1903	$lsize += $writeoff if ($append or not defined $lsize);
1906	1904
1907		my $rfno = fileno($sftp->{ssh_in});
1908	1905	# when a converter is used, the EOF can become delayed by the
1909	1906	# buffering introduced, we use $eof_t to account for that.
1910	1907	my ($eof, $eof_t);

1923	1920	}
1924	1921	$eof_t = 1;
1925	1922	}
	1923
1926	1924	# note that the $converter is called a last time
1927	1925	# with an empty string
1928	1926	$lsize += $converter->($input);

1935	1933	$eof = 1 if ($eof_t and !$len);
1936	1934	}
1937	1935	else {
	1936	$debug and $debug & 16384 and
	1937	_debug "reading block at offset ".CORE::tell($fh)." block_size: $block_size";
	1938
1938	1939	$len = CORE::read($fh, $data, $block_size);
	1940
1939	1941	if ($len) {
	1942	$debug and $debug & 16384 and _debug "block read, size: $len";
	1943
1940	1944	utf8::downgrade($data, 1)
1941		or croak "wide characters unexpectedly read from file";
	1945	or croak "wide characters unexpectedly read from file";
	1946
	1947	$debug and $debug & 16384 and length $data != $len and
	1948	_debug "read data changed size on downgrade to " . length($data);
1942	1949	}
1943	1950	else {
1944	1951	unless (defined $len) {

1965	1972	}
1966	1973
1967	1974	if ($len) {
	1975	$debug and $debug & 16384 and
	1976	_debug "writing block at offset $writeoff, length " . length($data);
	1977
1968	1978	my $id = $sftp->_queue_new_msg(SSH2_FXP_WRITE, str => $rfid,
1969	1979	int64 => $writeoff, str => $data);
1970	1980	push @msgid, $id;

2087	2097	longname => $ln,
2088	2098	a => $a };
2089	2099
2090		if ($follow_links and S_ISLNK($a->perm)) {
	2100	if ($follow_links and _is_lnk($a->perm)) {
2091	2101
2092	2102	if ($a = $sftp->stat($sftp->join($dir, $fn))) {
2093	2103	$entry->{a} = $a;

2166	2176	wanted => sub {
2167	2177	my $e = $_[1];
2168	2178	my $fn = $e->{filename};
2169		if (S_ISDIR($e->{a}->perm)) {
	2179	if (_is_dir($e->{a}->perm)) {
2170	2180	push @dirs, $e;
2171	2181	}
2172	2182	else {

2211	2221	$overwrite = 1 unless (defined $overwrite or $numbered);
2212	2222
2213	2223	my $a = $sftp->lstat($remote) or return undef;
2214		unless (S_ISLNK($a->perm)) {
	2224	unless (_is_lnk($a->perm)) {
2215	2225	$sftp->_set_error(SFTP_ERR_REMOTE_BAD_OBJECT,
2216	2226	"Remote object '$remote' is not a symlink");
2217	2227	return undef;

2263	2273	"Couldn't stat local file '$local'", $!);
2264	2274	return undef;
2265	2275	}
2266		unless (S_ISLNK($perm)) {
	2276	unless (_is_lnk($perm)) {
2267	2277	$sftp->_set_error(SFTP_ERR_LOCAL_BAD_OBJECT,
2268	2278	"Local file $local is not a symlink");
2269	2279	return undef;

2368	2378	wanted => sub {
2369	2379	my $e = $_[1];
2370	2380	# print "file fn:$e->{filename}, a:$e->{a}\n";
2371		unless (S_ISDIR($e->{a}->perm)) {
	2381	unless (_is_dir($e->{a}->perm)) {
2372	2382	if (!$wanted or $wanted->($sftp, $e)) {
2373	2383	my $fn = $e->{filename};
2374	2384	if ($fn =~ $reremote) {
2375	2385	my $lpath = File::Spec->catfile($local, $1);
2376	2386	($lpath) = $lpath =~ /(.*)/ if ${^TAINT};
2377		if (S_ISLNK($e->{a}->perm) and !$ignore_links) {
	2387	if (_is_lnk($e->{a}->perm) and !$ignore_links) {
2378	2388	if ($sftp->get_symlink($fn, $lpath,
2379	2389	overwrite => $overwrite,
2380	2390	numbered => $numbered,

2383	2393	return undef;
2384	2394	}
2385	2395	}
2386		elsif (S_ISREG($e->{a}->perm)) {
	2396	elsif (_is_reg($e->{a}->perm)) {
2387	2397	if ($newer_only and -e $lpath
2388	2398	and (CORE::stat _)[9] >= $e->{a}->mtime) {
2389	2399	$sftp->_set_error(SFTP_ERR_LOCAL_ALREADY_EXISTS,

2489	2499	# print "descend: $e->{filename}\n";
2490	2500	if (!$wanted or $wanted->($lfs, $e)) {
2491	2501	my $fn = $e->{filename};
	2502	$debug and $debug and 32768 and _debug "rput handling $fn";
2492	2503	if ($fn =~ $relocal) {
2493		my $rpath = $sftp->join($remote, $1);
	2504	my $rpath = $sftp->join($remote, File::Spec->splitdir($1));
	2505	$debug and $debug and 32768 and _debug "rpath: $rpath";
2494	2506	if ($sftp->test_d($rpath)) {
2495	2507	$lfs->_set_error(SFTP_ERR_REMOTE_ALREADY_EXISTS,
2496		"remote directory '$rpath' already exists");
	2508	"Remote directory '$rpath' already exists");
2497	2509	$lfs->_call_on_error($on_error, $e);
2498	2510	return 1;
2499	2511	}

2520	2532	wanted => sub {
2521	2533	my $e = $_[1];
2522	2534	# print "file fn:$e->{filename}, a:$e->{a}\n";
2523		unless (S_ISDIR($e->{a}->perm)) {
	2535	unless (_is_dir($e->{a}->perm)) {
2524	2536	if (!$wanted or $wanted->($lfs, $e)) {
2525	2537	my $fn = $e->{filename};
	2538	$debug and $debug and 32768 and _debug "rput handling $fn";
2526	2539	if ($fn =~ $relocal) {
2527		my $rpath = $sftp->join($remote, $1);
2528		if (S_ISLNK($e->{a}->perm) and !$ignore_links) {
	2540	my (undef, $d, $f) = File::Spec->splitpath($1);
	2541	my $rpath = $sftp->join($remote, File::Spec->splitdir($d), $f);
	2542	if (_is_lnk($e->{a}->perm) and !$ignore_links) {
2529	2543	if ($sftp->put_symlink($fn, $remote,
2530	2544	overwrite => $overwrite,
2531	2545	numbered => $numbered)) {

2534	2548	}
2535	2549	$lfs->_copy_error($sftp);
2536	2550	}
2537		elsif (S_ISREG($e->{a}->perm)) {
	2551	elsif (_is_reg($e->{a}->perm)) {
2538	2552	my $ra;
2539	2553	if ( $newer_only and
2540	2554	$ra = $sftp->stat($rpath) and

2611	2625	require File::Spec;
2612	2626	for my $e (@remote) {
2613	2627	my $perm = $e->{a}->perm;
2614		if (S_ISDIR($perm)) {
	2628	if (_is_dir($perm)) {
2615	2629	$sftp->_set_error(SFTP_ERR_REMOTE_BAD_OBJECT,
2616	2630	"Remote object '$e->{filename}' is a directory");
2617	2631	}

2622	2636	$local = File::Spec->catfile($localdir, $local)
2623	2637	if defined $localdir;
2624	2638
2625		if (S_ISLNK($perm)) {
	2639	if (_is_lnk($perm)) {
2626	2640	next if $ignore_links;
2627	2641	$sftp->get_symlink($fn, $local, %get_symlink_opts);
2628	2642	}

2666	2680	require File::Spec;
2667	2681	for my $e (@local) {
2668	2682	my $perm = $e->{a}->perm;
2669		if (S_ISDIR($perm)) {
	2683	if (_is_dir($perm)) {
2670	2684	$sftp->_set_error(SFTP_ERR_REMOTE_BAD_OBJECT,
2671	2685	"Remote object '$e->{filename}' is a directory");
2672	2686	}

2676	2690	$remote = $sftp->join($remotedir, $remote)
2677	2691	if defined $remotedir;
2678	2692
2679		if (S_ISLNK($perm)) {
	2693	if (_is_lnk($perm)) {
2680	2694	next if $ignore_links;
2681	2695	$sftp->put_symlink($fn, $remote, %put_symlink_opts);
2682	2696	}

3228	3242
3229	3243	=item ssh1 =E<gt> 1
3230	3244
3231		Use old SSH1 approach for starting the remote SFTP server.
	3245	use old SSH1 approach for starting the remote SFTP server.
3232	3246
3233	3247	=item transport =E<gt> $fh
3234	3248

3258	3272	passed to L<IPC::Open2::open2> to open a pipe to the remote
3259	3273	server.
3260	3274
	3275	=item stderr_fh =E<gt> $fh
	3276
	3277	redirects the output sent to stderr by the SSH subprocess to the given
	3278	file handle.
	3279
	3280	It can be used to suppress banners:
	3281
	3282	open my $ssherr, '>', '/dev/null' or die "unable to open /dev/null";
	3283	my $sftp = Net::SFTP::Foreign->new($host,
	3284	stderr_fh => $ssherr);
	3285
	3286	Or to send SSH stderr to a file in order to capture errors for later
	3287	analysis:
	3288
	3289	my $ssherr = File::Temp->new or die "File::Temp->new failed";
	3290	my $sftp = Net::SFTP::Foreign->new($hostname, more => ['-v'],
	3291	stderr_fh => $ssherr);
	3292	if ($sftp->error) {
	3293	print "sftp error: ".$sftp->error."\n";
	3294	seek($ssherr, 0, 0);
	3295	while (<$ssherr>) {
	3296	print "captured stderr: $_";
	3297	}
	3298	}
	3299
	3300	=item stderr_discard =E<gt> 1
	3301
	3302	redirects stderr to /dev/null
	3303
3261	3304	=item block_size =E<gt> $default_block_size
3262	3305
3263	3306	=item queue_size =E<gt> $default_queue_size

3267	3310
3268	3311	=item autodisconnect =E<gt> $ad
3269	3312
3270		By default, the SSH connection is closed from the DESTROY method when
	3313	by default, the SSH connection is closed from the DESTROY method when
3271	3314	the object goes out of scope. But on scripts that fork new processes,
3272	3315	that results on the SSH connection being closed by the first process
3273	3316	where the object goes out of scope, something undesirable.

4362	4405	C<$sl> pointing to C<$target>.
4363	4406
4364	4407	C<$target> is stored as-is, without any path expansion taken place on
4365		it. User C<realpath> to normalize it:
	4408	it. Use C<realpath> to normalize it:
4366	4409
4367	4410	$sftp->symlink("foo.lnk" => $sftp->realpath("../bar"))
4368	4411

4510	4553
4511	4554	As a work around, you can use plink C<-pw> argument to pass the
4512	4555	password on the command line, but it is B<highly insecure>, anyone
4513		with a shell account on the machine would be able to get the password.
4514		Use at your own risk!:
	4556	with a shell account on the local machine would be able to get the
	4557	password. Use at your own risk!:
4515	4558
4516	4559	# HIGHLY INSECURE!!!
4517	4560	my $sftp = Net::SFTP::Foreign->new('foo@bar',

4549	4592	can add code for your particular server software to activate the
4550	4593	work-around automatically.
4551	4594
	4595	=item Put method fails even with late_set_perm set
	4596
	4597	B<Q>: I added C<late_set_perm =E<gt> 1> to the put call, but we are still
	4598	receiving the error "Couldn't setstat remote file (setstat)".
	4599
	4600	B<A>: Some servers forbid the SFTP C<setstat> operation used by the
	4601	C<put> method for replicating the file permissions and timestamps on
	4602	the remote side.
	4603
	4604	As a work around you can just disable the feature:
	4605
	4606	$sftp->put($local_file, $remote_file,
	4607	copy_perms => 0, copy_time => 0);
	4608
4552	4609	=item Disable password authentication completely
4553	4610
4554	4611	B<Q>: When we try to open a session and the key either doesn't exist

4577	4634	print "$entry->{filename} is a directory\n";
4578	4635	}
4579	4636	}
	4637
	4638	=item Host key checking
	4639
	4640	B<Q>: Connecting to a remote server with password authentication fails
	4641	with the following error:
	4642
	4643	The authenticity of the target host can not be established,
	4644	connect from the command line first
	4645
	4646	B<A>: That probably means that the public key from the remote server
	4647	is not stored in the C<~/.ssh/known_hosts> file. Run an SSH Connection
	4648	from the command line as the same user as the script and answer C<yes>
	4649	when asked to confirm the key suplied.
	4650
	4651	Example:
	4652
	4653	$ ssh pluto /bin/true
	4654	The authenticity of host 'pluto (172.25.1.4)' can't be established.
	4655	RSA key fingerprint is 41:b1:a7:86:d2:a9:7b:b0:7f:a1:00:b7:26:51:76:52.
	4656	Are you sure you want to continue connecting (yes/no)? yes
	4657
	4658	Your SSH client may also support some flag to disable this check, but
	4659	doing it can ruin the security of the SSH protocol so I advise against
	4660	its usage.
	4661
	4662	Example:
	4663
	4664	# Warning: don't do that unless you fully understand
	4665	# its security implications!!!
	4666	$sftp = Net::SFTP::Foreign->new($host,
	4667	more => [-o => 'StrictHostKeyChecking no'],
	4668	...);
4580	4669
4581	4670	=back
4582	4671

4614	4703
4615	4704	Also, the following features should be considered experimental:
4616	4705
	4706	- redirecting SSH stderr stream
	4707
4617	4708	- multi-backend support
4618	4709
4619		- passing file handles to put and get methods
4620
4621	4710	- mput and mget methods
4622	4711
4623		- numbered option
	4712	- numbered feature
4624	4713
4625	4714	=head1 SUPPORT
4626	4715

4639	4728	If you like this module and you're feeling generous, take a look at my
4640	4729	Amazon Wish List: L<http://amzn.com/w/1WU1P6IR5QZ42>
4641	4730
	4731	Also consider contributing to the OpenSSH project this module builds
	4732	upon: L<http://www.openssh.org/donations.html>.
	4733
4642	4734	=head1 SEE ALSO
4643	4735
4644	4736	Information about the constants used on this module is available from

4652	4744	Net::SFTP::Foreign integrates nicely with my other module
4653	4745	L<Net::OpenSSH>.
4654	4746
	4747	L<Net::SFTP::Foreign::Backend::Net_SSH2> allows to run
	4748	Net::SFTP::Foreign on top of L<Net::SSH2>.
	4749
4655	4750	Modules offering similar functionality available from CPAN are
4656	4751	L<Net::SFTP> and L<Net::SSH2>.
4657	4752
4658		L<Net::SFTP::Foreign::Backend::Net_SSH2> allows to run
4659		Net::SFTP::Foreign on top of L<Net::SSH2>.
	4753	L<Test::SFTP> allows to run tests against a remote SFTP server.
4660	4754
4661	4755	=head1 COPYRIGHT
4662	4756

+243

-0

rfc/OpenSSH-protocol-deviations.txt less more

	0	This documents OpenSSH's deviations and extensions to the published SSH
	1	protocol.
	2
	3	Note that OpenSSH's sftp and sftp-server implement revision 3 of the SSH
	4	filexfer protocol described in:
	5
	6	http://www.openssh.com/txt/draft-ietf-secsh-filexfer-02.txt
	7
	8	Features from newer versions of the draft are not supported, unless
	9	explicitly implemented as extensions described below.
	10
	11	The protocol used by OpenSSH's ssh-agent is described in the file
	12	PROTOCOL.agent
	13
	14	1. transport: Protocol 2 MAC algorithm "umac-64@openssh.com"
	15
	16	This is a new transport-layer MAC method using the UMAC algorithm
	17	(rfc4418). This method is identical to the "umac-64" method documented
	18	in:
	19
	20	http://www.openssh.com/txt/draft-miller-secsh-umac-01.txt
	21
	22	2. transport: Protocol 2 compression algorithm "zlib@openssh.com"
	23
	24	This transport-layer compression method uses the zlib compression
	25	algorithm (identical to the "zlib" method in rfc4253), but delays the
	26	start of compression until after authentication has completed. This
	27	avoids exposing compression code to attacks from unauthenticated users.
	28
	29	The method is documented in:
	30
	31	http://www.openssh.com/txt/draft-miller-secsh-compression-delayed-00.txt
	32
	33	3. connection: Channel write close extension "eow@openssh.com"
	34
	35	The SSH connection protocol (rfc4254) provides the SSH_MSG_CHANNEL_EOF
	36	message to allow an endpoint to signal its peer that it will send no
	37	more data over a channel. Unfortunately, there is no symmetric way for
	38	an endpoint to request that its peer should cease sending data to it
	39	while still keeping the channel open for the endpoint to send data to
	40	the peer.
	41
	42	This is desirable, since it saves the transmission of data that would
	43	otherwise need to be discarded and it allows an endpoint to signal local
	44	processes of the condition, e.g. by closing the corresponding file
	45	descriptor.
	46
	47	OpenSSH implements a channel extension message to perform this
	48	signalling: "eow@openssh.com" (End Of Write). This message is sent by an
	49	endpoint when the local output of a channel is closed or experiences a
	50	write error. The message is formatted as follows:
	51
	52	byte SSH_MSG_CHANNEL_REQUEST
	53	uint32 recipient channel
	54	string "eow@openssh.com"
	55	boolean FALSE
	56
	57	On receiving this message, the peer SHOULD cease sending data of
	58	the channel and MAY signal the process from which the channel data
	59	originates (e.g. by closing its read file descriptor).
	60
	61	As with the symmetric SSH_MSG_CHANNEL_EOF message, the channel does
	62	remain open after a "eow@openssh.com" has been sent and more data may
	63	still be sent in the other direction. This message does not consume
	64	window space and may be sent even if no window space is available.
	65
	66	4. connection: disallow additional sessions extension
	67	"no-more-sessions@openssh.com"
	68
	69	Most SSH connections will only ever request a single session, but a
	70	attacker may abuse a running ssh client to surreptitiously open
	71	additional sessions under their control. OpenSSH provides a global
	72	request "no-more-sessions@openssh.com" to mitigate this attack.
	73
	74	When an OpenSSH client expects that it will never open another session
	75	(i.e. it has been started with connection multiplexing disabled), it
	76	will send the following global request:
	77
	78	byte SSH_MSG_GLOBAL_REQUEST
	79	string "no-more-sessions@openssh.com"
	80	char want-reply
	81
	82	On receipt of such a message, an OpenSSH server will refuse to open
	83	future channels of type "session" and instead immediately abort the
	84	connection.
	85
	86	Note that this is not a general defence against compromised clients
	87	(that is impossible), but it thwarts a simple attack.
	88
	89	5. connection: Tunnel forward extension "tun@openssh.com"
	90
	91	OpenSSH supports layer 2 and layer 3 tunnelling via the "tun@openssh.com"
	92	channel type. This channel type supports forwarding of network packets
	93	with datagram boundaries intact between endpoints equipped with
	94	interfaces like the BSD tun(4) device. Tunnel forwarding channels are
	95	requested by the client with the following packet:
	96
	97	byte SSH_MSG_CHANNEL_OPEN
	98	string "tun@openssh.com"
	99	uint32 sender channel
	100	uint32 initial window size
	101	uint32 maximum packet size
	102	uint32 tunnel mode
	103	uint32 remote unit number
	104
	105	The "tunnel mode" parameter specifies whether the tunnel should forward
	106	layer 2 frames or layer 3 packets. It may take one of the following values:
	107
	108	SSH_TUNMODE_POINTOPOINT 1 /* layer 3 packets */
	109	SSH_TUNMODE_ETHERNET 2 /* layer 2 frames */
	110
	111	The "tunnel unit number" specifies the remote interface number, or may
	112	be zero to allow the server to automatically chose an interface. A server
	113	that is not willing to open a client-specified unit should refuse the
	114	request with a SSH_MSG_CHANNEL_OPEN_FAILURE error. On successful open,
	115	the server should reply with SSH_MSG_CHANNEL_OPEN_SUCCESS.
	116
	117	Once established the client and server may exchange packet or frames
	118	over the tunnel channel by encapsulating them in SSH protocol strings
	119	and sending them as channel data. This ensures that packet boundaries
	120	are kept intact. Specifically, packets are transmitted using normal
	121	SSH_MSG_CHANNEL_DATA packets:
	122
	123	byte SSH_MSG_CHANNEL_DATA
	124	uint32 recipient channel
	125	string data
	126
	127	The contents of the "data" field for layer 3 packets is:
	128
	129	uint32 packet length
	130	uint32 address family
	131	byte[packet length - 4] packet data
	132
	133	The "address family" field identifies the type of packet in the message.
	134	It may be one of:
	135
	136	SSH_TUN_AF_INET 2 /* IPv4 */
	137	SSH_TUN_AF_INET6 24 /* IPv6 */
	138
	139	The "packet data" field consists of the IPv4/IPv6 datagram itself
	140	without any link layer header.
	141
	142	The contents of the "data" field for layer 3 packets is:
	143
	144	uint32 packet length
	145	byte[packet length] frame
	146
	147	The "frame" field contains an IEEE 802.3 Ethernet frame, including
	148	header.
	149
	150	6. sftp: Reversal of arguments to SSH_FXP_SYMLINK
	151
	152	When OpenSSH's sftp-server was implemented, the order of the arguments
	153	to the SSH_FXP_SYMLINK method was inadvertently reversed. Unfortunately,
	154	the reversal was not noticed until the server was widely deployed. Since
	155	fixing this to follow the specification would cause incompatibility, the
	156	current order was retained. For correct operation, clients should send
	157	SSH_FXP_SYMLINK as follows:
	158
	159	uint32 id
	160	string targetpath
	161	string linkpath
	162
	163	7. sftp: Server extension announcement in SSH_FXP_VERSION
	164
	165	OpenSSH's sftp-server lists the extensions it supports using the
	166	standard extension announcement mechanism in the SSH_FXP_VERSION server
	167	hello packet:
	168
	169	uint32 3 /* protocol version */
	170	string ext1-name
	171	string ext1-version
	172	string ext2-name
	173	string ext2-version
	174	...
	175	string extN-name
	176	string extN-version
	177
	178	Each extension reports its integer version number as an ASCII encoded
	179	string, e.g. "1". The version will be incremented if the extension is
	180	ever changed in an incompatible way. The server MAY advertise the same
	181	extension with multiple versions (though this is unlikely). Clients MUST
	182	check the version number before attempting to use the extension.
	183
	184	8. sftp: Extension request "posix-rename@openssh.com"
	185
	186	This operation provides a rename operation with POSIX semantics, which
	187	are different to those provided by the standard SSH_FXP_RENAME in
	188	draft-ietf-secsh-filexfer-02.txt. This request is implemented as a
	189	SSH_FXP_EXTENDED request with the following format:
	190
	191	uint32 id
	192	string "posix-rename@openssh.com"
	193	string oldpath
	194	string newpath
	195
	196	On receiving this request the server will perform the POSIX operation
	197	rename(oldpath, newpath) and will respond with a SSH_FXP_STATUS message.
	198	This extension is advertised in the SSH_FXP_VERSION hello with version
	199	"1".
	200
	201	9. sftp: Extension requests "statvfs@openssh.com" and
	202	"fstatvfs@openssh.com"
	203
	204	These requests correspond to the statvfs and fstatvfs POSIX system
	205	interfaces. The "statvfs@openssh.com" request operates on an explicit
	206	pathname, and is formatted as follows:
	207
	208	uint32 id
	209	string "statvfs@openssh.com"
	210	string path
	211
	212	The "fstatvfs@openssh.com" operates on an open file handle:
	213
	214	uint32 id
	215	string "fstatvfs@openssh.com"
	216	string handle
	217
	218	These requests return a SSH_FXP_STATUS reply on failure. On success they
	219	return the following SSH_FXP_EXTENDED_REPLY reply:
	220
	221	uint32 id
	222	uint64 f_bsize /* file system block size */
	223	uint64 f_frsize /* fundamental fs block size */
	224	uint64 f_blocks /* number of blocks (unit f_frsize) */
	225	uint64 f_bfree /* free blocks in file system */
	226	uint64 f_bavail /* free blocks for non-root */
	227	uint64 f_files /* total file inodes */
	228	uint64 f_ffree /* free file inodes */
	229	uint64 f_favail /* free file inodes for to non-root */
	230	uint64 f_fsid /* file system id */
	231	uint64 f_flag /* bit mask of f_flag values */
	232	uint64 f_namemax /* maximum filename length */
	233
	234	The values of the f_flag bitmask are as follows:
	235
	236	#define SSH_FXE_STATVFS_ST_RDONLY 0x1 /* read-only */
	237	#define SSH_FXE_STATVFS_ST_NOSUID 0x2 /* no setuid */
	238
	239	This extension is advertised in the SSH_FXP_VERSION hello with version
	240	"2".
	241
	242	$OpenBSD: PROTOCOL,v 1.9 2008/06/28 14:08:30 djm Exp $

+1626

-0

rfc/draft-ietf-secsh-filexfer-02.txt less more

	0
	1
	2	Network Working Group T. Ylonen
	3	Internet-Draft S. Lehtinen
	4	Expires: April 1, 2002 SSH Communications Security Corp
	5	October 2001
	6
	7
	8	SSH File Transfer Protocol
	9	draft-ietf-secsh-filexfer-02.txt
	10
	11	Status of this Memo
	12
	13	This document is an Internet-Draft and is in full conformance with
	14	all provisions of Section 10 of RFC2026.
	15
	16	Internet-Drafts are working documents of the Internet Engineering
	17	Task Force (IETF), its areas, and its working groups. Note that
	18	other groups may also distribute working documents as Internet-
	19	Drafts.
	20
	21	Internet-Drafts are draft documents valid for a maximum of six months
	22	and may be updated, replaced, or obsoleted by other documents at any
	23	time. It is inappropriate to use Internet-Drafts as reference
	24	material or to cite them other than as "work in progress."
	25
	26	The list of current Internet-Drafts can be accessed at http://
	27	www.ietf.org/ietf/1id-abstracts.txt.
	28
	29	The list of Internet-Draft Shadow Directories can be accessed at
	30	http://www.ietf.org/shadow.html.
	31
	32	This Internet-Draft will expire on April 1, 2002.
	33
	34	Copyright Notice
	35
	36	Copyright (C) The Internet Society (2001). All Rights Reserved.
	37
	38	Abstract
	39
	40	The SSH File Transfer Protocol provides secure file transfer
	41	functionality over any reliable data stream. It is the standard file
	42	transfer protocol for use with the SSH2 protocol. This document
	43	describes the file transfer protocol and its interface to the SSH2
	44	protocol suite.
	45
	46
	47
	48
	49
	50
	51
	52
	53
	54	Ylonen & Lehtinen Expires April 1, 2002 [Page 1]
	55
	56	Internet-Draft SSH File Transfer Protocol October 2001
	57
	58
	59	Table of Contents
	60
	61	1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
	62	2. Use with the SSH Connection Protocol . . . . . . . . . . . . 4
	63	3. General Packet Format . . . . . . . . . . . . . . . . . . . 5
	64	4. Protocol Initialization . . . . . . . . . . . . . . . . . . 7
	65	5. File Attributes . . . . . . . . . . . . . . . . . . . . . . 8
	66	6. Requests From the Client to the Server . . . . . . . . . . . 10
	67	6.1 Request Synchronization and Reordering . . . . . . . . . . . 10
	68	6.2 File Names . . . . . . . . . . . . . . . . . . . . . . . . . 11
	69	6.3 Opening, Creating, and Closing Files . . . . . . . . . . . . 11
	70	6.4 Reading and Writing . . . . . . . . . . . . . . . . . . . . 13
	71	6.5 Removing and Renaming Files . . . . . . . . . . . . . . . . 14
	72	6.6 Creating and Deleting Directories . . . . . . . . . . . . . 15
	73	6.7 Scanning Directories . . . . . . . . . . . . . . . . . . . . 15
	74	6.8 Retrieving File Attributes . . . . . . . . . . . . . . . . . 16
	75	6.9 Setting File Attributes . . . . . . . . . . . . . . . . . . 17
	76	6.10 Dealing with Symbolic links . . . . . . . . . . . . . . . . 18
	77	6.11 Canonicalizing the Server-Side Path Name . . . . . . . . . . 18
	78	7. Responses from the Server to the Client . . . . . . . . . . 20
	79	8. Vendor-Specific Extensions . . . . . . . . . . . . . . . . . 24
	80	9. Security Considerations . . . . . . . . . . . . . . . . . . 25
	81	10. Changes from previous protocol versions . . . . . . . . . . 26
	82	10.1 Changes between versions 3 and 2 . . . . . . . . . . . . . . 26
	83	10.2 Changes between versions 2 and 1 . . . . . . . . . . . . . . 26
	84	10.3 Changes between versions 1 and 0 . . . . . . . . . . . . . . 26
	85	11. Trademark Issues . . . . . . . . . . . . . . . . . . . . . . 27
	86	References . . . . . . . . . . . . . . . . . . . . . . . . . 28
	87	Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 28
	88	Full Copyright Statement . . . . . . . . . . . . . . . . . . 29
	89
	90
	91
	92
	93
	94
	95
	96
	97
	98
	99
	100
	101
	102
	103
	104
	105
	106
	107
	108
	109
	110	Ylonen & Lehtinen Expires April 1, 2002 [Page 2]
	111
	112	Internet-Draft SSH File Transfer Protocol October 2001
	113
	114
	115	1. Introduction
	116
	117	This protocol provides secure file transfer (and more generally file
	118	system access) functionality over a reliable data stream, such as a
	119	channel in the SSH2 protocol [3].
	120
	121	This protocol is designed so that it could be used to implement a
	122	secure remote file system service, as well as a secure file transfer
	123	service.
	124
	125	This protocol assumes that it runs over a secure channel, and that
	126	the server has already authenticated the user at the client end, and
	127	that the identity of the client user is externally available to the
	128	server implementation.
	129
	130	In general, this protocol follows a simple request-response model.
	131	Each request and response contains a sequence number and multiple
	132	requests may be pending simultaneously. There are a relatively large
	133	number of different request messages, but a small number of possible
	134	response messages. Each request has one or more response messages
	135	that may be returned in result (e.g., a read either returns data or
	136	reports error status).
	137
	138	The packet format descriptions in this specification follow the
	139	notation presented in the secsh architecture draft.[3].
	140
	141	Even though this protocol is described in the context of the SSH2
	142	protocol, this protocol is general and independent of the rest of the
	143	SSH2 protocol suite. It could be used in a number of different
	144	applications, such as secure file transfer over TLS RFC 2246 [1] and
	145	transfer of management information in VPN applications.
	146
	147
	148
	149
	150
	151
	152
	153
	154
	155
	156
	157
	158
	159
	160
	161
	162
	163
	164
	165
	166	Ylonen & Lehtinen Expires April 1, 2002 [Page 3]
	167
	168	Internet-Draft SSH File Transfer Protocol October 2001
	169
	170
	171	2. Use with the SSH Connection Protocol
	172
	173	When used with the SSH2 Protocol suite, this protocol is intended to
	174	be used from the SSH Connection Protocol [5] as a subsystem, as
	175	described in section ``Starting a Shell or a Command''. The
	176	subsystem name used with this protocol is "sftp".
	177
	178
	179
	180
	181
	182
	183
	184
	185
	186
	187
	188
	189
	190
	191
	192
	193
	194
	195
	196
	197
	198
	199
	200
	201
	202
	203
	204
	205
	206
	207
	208
	209
	210
	211
	212
	213
	214
	215
	216
	217
	218
	219
	220
	221
	222	Ylonen & Lehtinen Expires April 1, 2002 [Page 4]
	223
	224	Internet-Draft SSH File Transfer Protocol October 2001
	225
	226
	227	3. General Packet Format
	228
	229	All packets transmitted over the secure connection are of the
	230	following format:
	231
	232	uint32 length
	233	byte type
	234	byte[length - 1] data payload
	235
	236	That is, they are just data preceded by 32-bit length and 8-bit type
	237	fields. The `length' is the length of the data area, and does not
	238	include the `length' field itself. The format and interpretation of
	239	the data area depends on the packet type.
	240
	241	All packet descriptions below only specify the packet type and the
	242	data that goes into the data field. Thus, they should be prefixed by
	243	the `length' and `type' fields.
	244
	245	The maximum size of a packet is in practice determined by the client
	246	(the maximum size of read or write requests that it sends, plus a few
	247	bytes of packet overhead). All servers SHOULD support packets of at
	248	least 34000 bytes (where the packet size refers to the full length,
	249	including the header above). This should allow for reads and writes
	250	of at most 32768 bytes.
	251
	252	There is no limit on the number of outstanding (non-acknowledged)
	253	requests that the client may send to the server. In practice this is
	254	limited by the buffering available on the data stream and the queuing
	255	performed by the server. If the server's queues are full, it should
	256	not read any more data from the stream, and flow control will prevent
	257	the client from sending more requests. Note, however, that while
	258	there is no restriction on the protocol level, the client's API may
	259	provide a limit in order to prevent infinite queuing of outgoing
	260	requests at the client.
	261
	262
	263
	264
	265
	266
	267
	268
	269
	270
	271
	272
	273
	274
	275
	276
	277
	278	Ylonen & Lehtinen Expires April 1, 2002 [Page 5]
	279
	280	Internet-Draft SSH File Transfer Protocol October 2001
	281
	282
	283	The following values are defined for packet types.
	284
	285	#define SSH_FXP_INIT 1
	286	#define SSH_FXP_VERSION 2
	287	#define SSH_FXP_OPEN 3
	288	#define SSH_FXP_CLOSE 4
	289	#define SSH_FXP_READ 5
	290	#define SSH_FXP_WRITE 6
	291	#define SSH_FXP_LSTAT 7
	292	#define SSH_FXP_FSTAT 8
	293	#define SSH_FXP_SETSTAT 9
	294	#define SSH_FXP_FSETSTAT 10
	295	#define SSH_FXP_OPENDIR 11
	296	#define SSH_FXP_READDIR 12
	297	#define SSH_FXP_REMOVE 13
	298	#define SSH_FXP_MKDIR 14
	299	#define SSH_FXP_RMDIR 15
	300	#define SSH_FXP_REALPATH 16
	301	#define SSH_FXP_STAT 17
	302	#define SSH_FXP_RENAME 18
	303	#define SSH_FXP_READLINK 19
	304	#define SSH_FXP_SYMLINK 20
	305	#define SSH_FXP_STATUS 101
	306	#define SSH_FXP_HANDLE 102
	307	#define SSH_FXP_DATA 103
	308	#define SSH_FXP_NAME 104
	309	#define SSH_FXP_ATTRS 105
	310	#define SSH_FXP_EXTENDED 200
	311	#define SSH_FXP_EXTENDED_REPLY 201
	312
	313	Additional packet types should only be defined if the protocol
	314	version number (see Section ``Protocol Initialization'') is
	315	incremented, and their use MUST be negotiated using the version
	316	number. However, the SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY
	317	packets can be used to implement vendor-specific extensions. See
	318	Section ``Vendor-Specific-Extensions'' for more details.
	319
	320
	321
	322
	323
	324
	325
	326
	327
	328
	329
	330
	331
	332
	333
	334	Ylonen & Lehtinen Expires April 1, 2002 [Page 6]
	335
	336	Internet-Draft SSH File Transfer Protocol October 2001
	337
	338
	339	4. Protocol Initialization
	340
	341	When the file transfer protocol starts, it first sends a SSH_FXP_INIT
	342	(including its version number) packet to the server. The server
	343	responds with a SSH_FXP_VERSION packet, supplying the lowest of its
	344	own and the client's version number. Both parties should from then
	345	on adhere to particular version of the protocol.
	346
	347	The SSH_FXP_INIT packet (from client to server) has the following
	348	data:
	349
	350	uint32 version
	351	<extension data>
	352
	353	The SSH_FXP_VERSION packet (from server to client) has the following
	354	data:
	355
	356	uint32 version
	357	<extension data>
	358
	359	The version number of the protocol specified in this document is 3.
	360	The version number should be incremented for each incompatible
	361	revision of this protocol.
	362
	363	The extension data in the above packets may be empty, or may be a
	364	sequence of
	365
	366	string extension_name
	367	string extension_data
	368
	369	pairs (both strings MUST always be present if one is, but the
	370	`extension_data' string may be of zero length). If present, these
	371	strings indicate extensions to the baseline protocol. The
	372	`extension_name' field(s) identify the name of the extension. The
	373	name should be of the form "name@domain", where the domain is the DNS
	374	domain name of the organization defining the extension. Additional
	375	names that are not of this format may be defined later by the IETF.
	376	Implementations MUST silently ignore any extensions whose name they
	377	do not recognize.
	378
	379
	380
	381
	382
	383
	384
	385
	386
	387
	388
	389
	390	Ylonen & Lehtinen Expires April 1, 2002 [Page 7]
	391
	392	Internet-Draft SSH File Transfer Protocol October 2001
	393
	394
	395	5. File Attributes
	396
	397	A new compound data type is defined for encoding file attributes. It
	398	is basically just a combination of elementary types, but is defined
	399	once because of the non-trivial description of the fields and to
	400	ensure maintainability.
	401
	402	The same encoding is used both when returning file attributes from
	403	the server and when sending file attributes to the server. When
	404	sending it to the server, the flags field specifies which attributes
	405	are included, and the server will use default values for the
	406	remaining attributes (or will not modify the values of remaining
	407	attributes). When receiving attributes from the server, the flags
	408	specify which attributes are included in the returned data. The
	409	server normally returns all attributes it knows about.
	410
	411	uint32 flags
	412	uint64 size present only if flag SSH_FILEXFER_ATTR_SIZE
	413	uint32 uid present only if flag SSH_FILEXFER_ATTR_UIDGID
	414	uint32 gid present only if flag SSH_FILEXFER_ATTR_UIDGID
	415	uint32 permissions present only if flag SSH_FILEXFER_ATTR_PERMISSIONS
	416	uint32 atime present only if flag SSH_FILEXFER_ACMODTIME
	417	uint32 mtime present only if flag SSH_FILEXFER_ACMODTIME
	418	uint32 extended_count present only if flag SSH_FILEXFER_ATTR_EXTENDED
	419	string extended_type
	420	string extended_data
	421	... more extended data (extended_type - extended_data pairs),
	422	so that number of pairs equals extended_count
	423
	424	The `flags' specify which of the fields are present. Those fields
	425	for which the corresponding flag is not set are not present (not
	426	included in the packet). New flags can only be added by incrementing
	427	the protocol version number (or by using the extension mechanism
	428	described below).
	429
	430	The `size' field specifies the size of the file in bytes.
	431
	432	The `uid' and `gid' fields contain numeric Unix-like user and group
	433	identifiers, respectively.
	434
	435	The `permissions' field contains a bit mask of file permissions as
	436	defined by posix [1].
	437
	438	The `atime' and `mtime' contain the access and modification times of
	439	the files, respectively. They are represented as seconds from Jan 1,
	440	1970 in UTC.
	441
	442	The SSH_FILEXFER_ATTR_EXTENDED flag provides a general extension
	443
	444
	445
	446	Ylonen & Lehtinen Expires April 1, 2002 [Page 8]
	447
	448	Internet-Draft SSH File Transfer Protocol October 2001
	449
	450
	451	mechanism for vendor-specific extensions. If the flag is specified,
	452	then the `extended_count' field is present. It specifies the number
	453	of extended_type-extended_data pairs that follow. Each of these
	454	pairs specifies an extended attribute. For each of the attributes,
	455	the extended_type field should be a string of the format
	456	"name@domain", where "domain" is a valid, registered domain name and
	457	"name" identifies the method. The IETF may later standardize certain
	458	names that deviate from this format (e.g., that do not contain the
	459	"@" sign). The interpretation of `extended_data' depends on the
	460	type. Implementations SHOULD ignore extended data fields that they
	461	do not understand.
	462
	463	Additional fields can be added to the attributes by either defining
	464	additional bits to the flags field to indicate their presence, or by
	465	defining extended attributes for them. The extended attributes
	466	mechanism is recommended for most purposes; additional flags bits
	467	should only be defined by an IETF standards action that also
	468	increments the protocol version number. The use of such new fields
	469	MUST be negotiated by the version number in the protocol exchange.
	470	It is a protocol error if a packet with unsupported protocol bits is
	471	received.
	472
	473	The flags bits are defined to have the following values:
	474
	475	#define SSH_FILEXFER_ATTR_SIZE 0x00000001
	476	#define SSH_FILEXFER_ATTR_UIDGID 0x00000002
	477	#define SSH_FILEXFER_ATTR_PERMISSIONS 0x00000004
	478	#define SSH_FILEXFER_ATTR_ACMODTIME 0x00000008
	479	#define SSH_FILEXFER_ATTR_EXTENDED 0x80000000
	480
	481
	482
	483
	484
	485
	486
	487
	488
	489
	490
	491
	492
	493
	494
	495
	496
	497
	498
	499
	500
	501
	502	Ylonen & Lehtinen Expires April 1, 2002 [Page 9]
	503
	504	Internet-Draft SSH File Transfer Protocol October 2001
	505
	506
	507	6. Requests From the Client to the Server
	508
	509	Requests from the client to the server represent the various file
	510	system operations. Each request begins with an `id' field, which is
	511	a 32-bit identifier identifying the request (selected by the client).
	512	The same identifier will be returned in the response to the request.
	513	One possible implementation of it is a monotonically increasing
	514	request sequence number (modulo 2^32).
	515
	516	Many operations in the protocol operate on open files. The
	517	SSH_FXP_OPEN request can return a file handle (which is an opaque
	518	variable-length string) which may be used to access the file later
	519	(e.g. in a read operation). The client MUST NOT send requests the
	520	server with bogus or closed handles. However, the server MUST
	521	perform adequate checks on the handle in order to avoid security
	522	risks due to fabricated handles.
	523
	524	This design allows either stateful and stateless server
	525	implementation, as well as an implementation which caches state
	526	between requests but may also flush it. The contents of the file
	527	handle string are entirely up to the server and its design. The
	528	client should not modify or attempt to interpret the file handle
	529	strings.
	530
	531	The file handle strings MUST NOT be longer than 256 bytes.
	532
	533	6.1 Request Synchronization and Reordering
	534
	535	The protocol and implementations MUST process requests relating to
	536	the same file in the order in which they are received. In other
	537	words, if an application submits multiple requests to the server, the
	538	results in the responses will be the same as if it had sent the
	539	requests one at a time and waited for the response in each case. For
	540	example, the server may process non-overlapping read/write requests
	541	to the same file in parallel, but overlapping reads and writes cannot
	542	be reordered or parallelized. However, there are no ordering
	543	restrictions on the server for processing requests from two different
	544	file transfer connections. The server may interleave and parallelize
	545	them at will.
	546
	547	There are no restrictions on the order in which responses to
	548	outstanding requests are delivered to the client, except that the
	549	server must ensure fairness in the sense that processing of no
	550	request will be indefinitely delayed even if the client is sending
	551	other requests so that there are multiple outstanding requests all
	552	the time.
	553
	554
	555
	556
	557
	558	Ylonen & Lehtinen Expires April 1, 2002 [Page 10]
	559
	560	Internet-Draft SSH File Transfer Protocol October 2001
	561
	562
	563	6.2 File Names
	564
	565	This protocol represents file names as strings. File names are
	566	assumed to use the slash ('/') character as a directory separator.
	567
	568	File names starting with a slash are "absolute", and are relative to
	569	the root of the file system. Names starting with any other character
	570	are relative to the user's default directory (home directory). Note
	571	that identifying the user is assumed to take place outside of this
	572	protocol.
	573
	574	Servers SHOULD interpret a path name component ".." as referring to
	575	the parent directory, and "." as referring to the current directory.
	576	If the server implementation limits access to certain parts of the
	577	file system, it must be extra careful in parsing file names when
	578	enforcing such restrictions. There have been numerous reported
	579	security bugs where a ".." in a path name has allowed access outside
	580	the intended area.
	581
	582	An empty path name is valid, and it refers to the user's default
	583	directory (usually the user's home directory).
	584
	585	Otherwise, no syntax is defined for file names by this specification.
	586	Clients should not make any other assumptions; however, they can
	587	splice path name components returned by SSH_FXP_READDIR together
	588	using a slash ('/') as the separator, and that will work as expected.
	589
	590	It is understood that the lack of well-defined semantics for file
	591	names may cause interoperability problems between clients and servers
	592	using radically different operating systems. However, this approach
	593	is known to work acceptably with most systems, and alternative
	594	approaches that e.g. treat file names as sequences of structured
	595	components are quite complicated.
	596
	597	6.3 Opening, Creating, and Closing Files
	598
	599	Files are opened and created using the SSH_FXP_OPEN message, whose
	600	data part is as follows:
	601
	602	uint32 id
	603	string filename
	604	uint32 pflags
	605	ATTRS attrs
	606
	607	The `id' field is the request identifier as for all requests.
	608
	609	The `filename' field specifies the file name. See Section ``File
	610	Names'' for more information.
	611
	612
	613
	614	Ylonen & Lehtinen Expires April 1, 2002 [Page 11]
	615
	616	Internet-Draft SSH File Transfer Protocol October 2001
	617
	618
	619	The `pflags' field is a bitmask. The following bits have been
	620	defined.
	621
	622	#define SSH_FXF_READ 0x00000001
	623	#define SSH_FXF_WRITE 0x00000002
	624	#define SSH_FXF_APPEND 0x00000004
	625	#define SSH_FXF_CREAT 0x00000008
	626	#define SSH_FXF_TRUNC 0x00000010
	627	#define SSH_FXF_EXCL 0x00000020
	628
	629	These have the following meanings:
	630
	631	SSH_FXF_READ
	632	Open the file for reading.
	633
	634	SSH_FXF_WRITE
	635	Open the file for writing. If both this and SSH_FXF_READ are
	636	specified, the file is opened for both reading and writing.
	637
	638	SSH_FXF_APPEND
	639	Force all writes to append data at the end of the file.
	640
	641	SSH_FXF_CREAT
	642	If this flag is specified, then a new file will be created if one
	643	does not already exist (if O_TRUNC is specified, the new file will
	644	be truncated to zero length if it previously exists).
	645
	646	SSH_FXF_TRUNC
	647	Forces an existing file with the same name to be truncated to zero
	648	length when creating a file by specifying SSH_FXF_CREAT.
	649	SSH_FXF_CREAT MUST also be specified if this flag is used.
	650
	651	SSH_FXF_EXCL
	652	Causes the request to fail if the named file already exists.
	653	SSH_FXF_CREAT MUST also be specified if this flag is used.
	654
	655	The `attrs' field specifies the initial attributes for the file.
	656	Default values will be used for those attributes that are not
	657	specified. See Section ``File Attributes'' for more information.
	658
	659	Regardless the server operating system, the file will always be
	660	opened in "binary" mode (i.e., no translations between different
	661	character sets and newline encodings).
	662
	663	The response to this message will be either SSH_FXP_HANDLE (if the
	664	operation is successful) or SSH_FXP_STATUS (if the operation fails).
	665
	666
	667
	668
	669
	670	Ylonen & Lehtinen Expires April 1, 2002 [Page 12]
	671
	672	Internet-Draft SSH File Transfer Protocol October 2001
	673
	674
	675	A file is closed by using the SSH_FXP_CLOSE request. Its data field
	676	has the following format:
	677
	678	uint32 id
	679	string handle
	680
	681	where `id' is the request identifier, and `handle' is a handle
	682	previously returned in the response to SSH_FXP_OPEN or
	683	SSH_FXP_OPENDIR. The handle becomes invalid immediately after this
	684	request has been sent.
	685
	686	The response to this request will be a SSH_FXP_STATUS message. One
	687	should note that on some server platforms even a close can fail.
	688	This can happen e.g. if the server operating system caches writes,
	689	and an error occurs while flushing cached writes during the close.
	690
	691	6.4 Reading and Writing
	692
	693	Once a file has been opened, it can be read using the SSH_FXP_READ
	694	message, which has the following format:
	695
	696	uint32 id
	697	string handle
	698	uint64 offset
	699	uint32 len
	700
	701	where `id' is the request identifier, `handle' is an open file handle
	702	returned by SSH_FXP_OPEN, `offset' is the offset (in bytes) relative
	703	to the beginning of the file from where to start reading, and `len'
	704	is the maximum number of bytes to read.
	705
	706	In response to this request, the server will read as many bytes as it
	707	can from the file (up to `len'), and return them in a SSH_FXP_DATA
	708	message. If an error occurs or EOF is encountered before reading any
	709	data, the server will respond with SSH_FXP_STATUS. For normal disk
	710	files, it is guaranteed that this will read the specified number of
	711	bytes, or up to end of file. For e.g. device files this may return
	712	fewer bytes than requested.
	713
	714	Writing to a file is achieved using the SSH_FXP_WRITE message, which
	715	has the following format:
	716
	717	uint32 id
	718	string handle
	719	uint64 offset
	720	string data
	721
	722	where `id' is a request identifier, `handle' is a file handle
	723
	724
	725
	726	Ylonen & Lehtinen Expires April 1, 2002 [Page 13]
	727
	728	Internet-Draft SSH File Transfer Protocol October 2001
	729
	730
	731	returned by SSH_FXP_OPEN, `offset' is the offset (in bytes) from the
	732	beginning of the file where to start writing, and `data' is the data
	733	to be written.
	734
	735	The write will extend the file if writing beyond the end of the file.
	736	It is legal to write way beyond the end of the file; the semantics
	737	are to write zeroes from the end of the file to the specified offset
	738	and then the data. On most operating systems, such writes do not
	739	allocate disk space but instead leave "holes" in the file.
	740
	741	The server responds to a write request with a SSH_FXP_STATUS message.
	742
	743	6.5 Removing and Renaming Files
	744
	745	Files can be removed using the SSH_FXP_REMOVE message. It has the
	746	following format:
	747
	748	uint32 id
	749	string filename
	750
	751	where `id' is the request identifier and `filename' is the name of
	752	the file to be removed. See Section ``File Names'' for more
	753	information. This request cannot be used to remove directories.
	754
	755	The server will respond to this request with a SSH_FXP_STATUS
	756	message.
	757
	758	Files (and directories) can be renamed using the SSH_FXP_RENAME
	759	message. Its data is as follows:
	760
	761	uint32 id
	762	string oldpath
	763	string newpath
	764
	765	where `id' is the request identifier, `oldpath' is the name of an
	766	existing file or directory, and `newpath' is the new name for the
	767	file or directory. It is an error if there already exists a file
	768	with the name specified by newpath. The server may also fail rename
	769	requests in other situations, for example if `oldpath' and `newpath'
	770	point to different file systems on the server.
	771
	772	The server will respond to this request with a SSH_FXP_STATUS
	773	message.
	774
	775
	776
	777
	778
	779
	780
	781
	782	Ylonen & Lehtinen Expires April 1, 2002 [Page 14]
	783
	784	Internet-Draft SSH File Transfer Protocol October 2001
	785
	786
	787	6.6 Creating and Deleting Directories
	788
	789	New directories can be created using the SSH_FXP_MKDIR request. It
	790	has the following format:
	791
	792	uint32 id
	793	string path
	794	ATTRS attrs
	795
	796	where `id' is the request identifier, `path' and `attrs' specifies
	797	the modifications to be made to its attributes. See Section ``File
	798	Names'' for more information on file names. Attributes are discussed
	799	in more detail in Section ``File Attributes''. specifies the
	800	directory to be created. An error will be returned if a file or
	801	directory with the specified path already exists. The server will
	802	respond to this request with a SSH_FXP_STATUS message.
	803
	804	Directories can be removed using the SSH_FXP_RMDIR request, which
	805	has the following format:
	806
	807	uint32 id
	808	string path
	809
	810	where `id' is the request identifier, and `path' specifies the
	811	directory to be removed. See Section ``File Names'' for more
	812	information on file names. An error will be returned if no directory
	813	with the specified path exists, or if the specified directory is not
	814	empty, or if the path specified a file system object other than a
	815	directory. The server responds to this request with a SSH_FXP_STATUS
	816	message.
	817
	818	6.7 Scanning Directories
	819
	820	The files in a directory can be listed using the SSH_FXP_OPENDIR and
	821	SSH_FXP_READDIR requests. Each SSH_FXP_READDIR request returns one
	822	or more file names with full file attributes for each file. The
	823	client should call SSH_FXP_READDIR repeatedly until it has found the
	824	file it is looking for or until the server responds with a
	825	SSH_FXP_STATUS message indicating an error (normally SSH_FX_EOF if
	826	there are no more files in the directory). The client should then
	827	close the handle using the SSH_FXP_CLOSE request.
	828
	829
	830
	831
	832
	833
	834
	835
	836
	837
	838	Ylonen & Lehtinen Expires April 1, 2002 [Page 15]
	839
	840	Internet-Draft SSH File Transfer Protocol October 2001
	841
	842
	843	The SSH_FXP_OPENDIR opens a directory for reading. It has the
	844	following format:
	845
	846	uint32 id
	847	string path
	848
	849	where `id' is the request identifier and `path' is the path name of
	850	the directory to be listed (without any trailing slash). See Section
	851	``File Names'' for more information on file names. This will return
	852	an error if the path does not specify a directory or if the directory
	853	is not readable. The server will respond to this request with either
	854	a SSH_FXP_HANDLE or a SSH_FXP_STATUS message.
	855
	856	Once the directory has been successfully opened, files (and
	857	directories) contained in it can be listed using SSH_FXP_READDIR
	858	requests. These are of the format
	859
	860	uint32 id
	861	string handle
	862
	863	where `id' is the request identifier, and `handle' is a handle
	864	returned by SSH_FXP_OPENDIR. (It is a protocol error to attempt to
	865	use an ordinary file handle returned by SSH_FXP_OPEN.)
	866
	867	The server responds to this request with either a SSH_FXP_NAME or a
	868	SSH_FXP_STATUS message. One or more names may be returned at a time.
	869	Full status information is returned for each name in order to speed
	870	up typical directory listings.
	871
	872	When the client no longer wishes to read more names from the
	873	directory, it SHOULD call SSH_FXP_CLOSE for the handle. The handle
	874	should be closed regardless of whether an error has occurred or not.
	875
	876	6.8 Retrieving File Attributes
	877
	878	Very often, file attributes are automatically returned by
	879	SSH_FXP_READDIR. However, sometimes there is need to specifically
	880	retrieve the attributes for a named file. This can be done using the
	881	SSH_FXP_STAT, SSH_FXP_LSTAT and SSH_FXP_FSTAT requests.
	882
	883	SSH_FXP_STAT and SSH_FXP_LSTAT only differ in that SSH_FXP_STAT
	884	follows symbolic links on the server, whereas SSH_FXP_LSTAT does not
	885	follow symbolic links. Both have the same format:
	886
	887	uint32 id
	888	string path
	889
	890	where `id' is the request identifier, and `path' specifies the file
	891
	892
	893
	894	Ylonen & Lehtinen Expires April 1, 2002 [Page 16]
	895
	896	Internet-Draft SSH File Transfer Protocol October 2001
	897
	898
	899	system object for which status is to be returned. The server
	900	responds to this request with either SSH_FXP_ATTRS or SSH_FXP_STATUS.
	901
	902	SSH_FXP_FSTAT differs from the others in that it returns status
	903	information for an open file (identified by the file handle). Its
	904	format is as follows:
	905
	906	uint32 id
	907	string handle
	908
	909	where `id' is the request identifier and `handle' is a file handle
	910	returned by SSH_FXP_OPEN. The server responds to this request with
	911	SSH_FXP_ATTRS or SSH_FXP_STATUS.
	912
	913	6.9 Setting File Attributes
	914
	915	File attributes may be modified using the SSH_FXP_SETSTAT and
	916	SSH_FXP_FSETSTAT requests. These requests are used for operations
	917	such as changing the ownership, permissions or access times, as well
	918	as for truncating a file.
	919
	920	The SSH_FXP_SETSTAT request is of the following format:
	921
	922	uint32 id
	923	string path
	924	ATTRS attrs
	925
	926	where `id' is the request identifier, `path' specifies the file
	927	system object (e.g. file or directory) whose attributes are to be
	928	modified, and `attrs' specifies the modifications to be made to its
	929	attributes. Attributes are discussed in more detail in Section
	930	``File Attributes''.
	931
	932	An error will be returned if the specified file system object does
	933	not exist or the user does not have sufficient rights to modify the
	934	specified attributes. The server responds to this request with a
	935	SSH_FXP_STATUS message.
	936
	937	The SSH_FXP_FSETSTAT request modifies the attributes of a file which
	938	is already open. It has the following format:
	939
	940	uint32 id
	941	string handle
	942	ATTRS attrs
	943
	944	where `id' is the request identifier, `handle' (MUST be returned by
	945	SSH_FXP_OPEN) identifies the file whose attributes are to be
	946	modified, and `attrs' specifies the modifications to be made to its
	947
	948
	949
	950	Ylonen & Lehtinen Expires April 1, 2002 [Page 17]
	951
	952	Internet-Draft SSH File Transfer Protocol October 2001
	953
	954
	955	attributes. Attributes are discussed in more detail in Section
	956	``File Attributes''. The server will respond to this request with
	957	SSH_FXP_STATUS.
	958
	959	6.10 Dealing with Symbolic links
	960
	961	The SSH_FXP_READLINK request may be used to read the target of a
	962	symbolic link. It would have a data part as follows:
	963
	964	uint32 id
	965	string path
	966
	967	where `id' is the request identifier and `path' specifies the path
	968	name of the symlink to be read.
	969
	970	The server will respond with a SSH_FXP_NAME packet containing only
	971	one name and a dummy attributes value. The name in the returned
	972	packet contains the target of the link. If an error occurs, the
	973	server may respond with SSH_FXP_STATUS.
	974
	975	The SSH_FXP_SYMLINK request will create a symbolic link on the
	976	server. It is of the following format
	977
	978	uint32 id
	979	string linkpath
	980	string targetpath
	981
	982	where `id' is the request identifier, `linkpath' specifies the path
	983	name of the symlink to be created and `targetpath' specifies the
	984	target of the symlink. The server shall respond with a
	985	SSH_FXP_STATUS indicating either success (SSH_FX_OK) or an error
	986	condition.
	987
	988	6.11 Canonicalizing the Server-Side Path Name
	989
	990	The SSH_FXP_REALPATH request can be used to have the server
	991	canonicalize any given path name to an absolute path. This is useful
	992	for converting path names containing ".." components or relative
	993	pathnames without a leading slash into absolute paths. The format of
	994	the request is as follows:
	995
	996	uint32 id
	997	string path
	998
	999	where `id' is the request identifier and `path' specifies the path
	1000	name to be canonicalized. The server will respond with a
	1001	SSH_FXP_NAME packet containing only one name and a dummy attributes
	1002	value. The name is the returned packet will be in canonical form.
	1003
	1004
	1005
	1006	Ylonen & Lehtinen Expires April 1, 2002 [Page 18]
	1007
	1008	Internet-Draft SSH File Transfer Protocol October 2001
	1009
	1010
	1011	If an error occurs, the server may also respond with SSH_FXP_STATUS.
	1012
	1013
	1014
	1015
	1016
	1017
	1018
	1019
	1020
	1021
	1022
	1023
	1024
	1025
	1026
	1027
	1028
	1029
	1030
	1031
	1032
	1033
	1034
	1035
	1036
	1037
	1038
	1039
	1040
	1041
	1042
	1043
	1044
	1045
	1046
	1047
	1048
	1049
	1050
	1051
	1052
	1053
	1054
	1055
	1056
	1057
	1058
	1059
	1060
	1061
	1062	Ylonen & Lehtinen Expires April 1, 2002 [Page 19]
	1063
	1064	Internet-Draft SSH File Transfer Protocol October 2001
	1065
	1066
	1067	7. Responses from the Server to the Client
	1068
	1069	The server responds to the client using one of a few response
	1070	packets. All requests can return a SSH_FXP_STATUS response upon
	1071	failure. When the operation is successful, any of the responses may
	1072	be returned (depending on the operation). If no data needs to be
	1073	returned to the client, the SSH_FXP_STATUS response with SSH_FX_OK
	1074	status is appropriate. Otherwise, the SSH_FXP_HANDLE message is used
	1075	to return a file handle (for SSH_FXP_OPEN and SSH_FXP_OPENDIR
	1076	requests), SSH_FXP_DATA is used to return data from SSH_FXP_READ,
	1077	SSH_FXP_NAME is used to return one or more file names from a
	1078	SSH_FXP_READDIR or SSH_FXP_REALPATH request, and SSH_FXP_ATTRS is
	1079	used to return file attributes from SSH_FXP_STAT, SSH_FXP_LSTAT, and
	1080	SSH_FXP_FSTAT requests.
	1081
	1082	Exactly one response will be returned for each request. Each
	1083	response packet contains a request identifier which can be used to
	1084	match each response with the corresponding request. Note that it is
	1085	legal to have several requests outstanding simultaneously, and the
	1086	server is allowed to send responses to them in a different order from
	1087	the order in which the requests were sent (the result of their
	1088	execution, however, is guaranteed to be as if they had been processed
	1089	one at a time in the order in which the requests were sent).
	1090
	1091	Response packets are of the same general format as request packets.
	1092	Each response packet begins with the request identifier.
	1093
	1094	The format of the data portion of the SSH_FXP_STATUS response is as
	1095	follows:
	1096
	1097	uint32 id
	1098	uint32 error/status code
	1099	string error message (ISO-10646 UTF-8 [RFC-2279])
	1100	string language tag (as defined in [RFC-1766])
	1101
	1102	where `id' is the request identifier, and `error/status code'
	1103	indicates the result of the requested operation. The value SSH_FX_OK
	1104	indicates success, and all other values indicate failure.
	1105
	1106
	1107
	1108
	1109
	1110
	1111
	1112
	1113
	1114
	1115
	1116
	1117
	1118	Ylonen & Lehtinen Expires April 1, 2002 [Page 20]
	1119
	1120	Internet-Draft SSH File Transfer Protocol October 2001
	1121
	1122
	1123	Currently, the following values are defined (other values may be
	1124	defined by future versions of this protocol):
	1125
	1126	#define SSH_FX_OK 0
	1127	#define SSH_FX_EOF 1
	1128	#define SSH_FX_NO_SUCH_FILE 2
	1129	#define SSH_FX_PERMISSION_DENIED 3
	1130	#define SSH_FX_FAILURE 4
	1131	#define SSH_FX_BAD_MESSAGE 5
	1132	#define SSH_FX_NO_CONNECTION 6
	1133	#define SSH_FX_CONNECTION_LOST 7
	1134	#define SSH_FX_OP_UNSUPPORTED 8
	1135
	1136	SSH_FX_OK
	1137	Indicates successful completion of the operation.
	1138
	1139	SSH_FX_EOF
	1140	indicates end-of-file condition; for SSH_FX_READ it means that no
	1141	more data is available in the file, and for SSH_FX_READDIR it
	1142	indicates that no more files are contained in the directory.
	1143
	1144	SSH_FX_NO_SUCH_FILE
	1145	is returned when a reference is made to a file which should exist
	1146	but doesn't.
	1147
	1148	SSH_FX_PERMISSION_DENIED
	1149	is returned when the authenticated user does not have sufficient
	1150	permissions to perform the operation.
	1151
	1152	SSH_FX_FAILURE
	1153	is a generic catch-all error message; it should be returned if an
	1154	error occurs for which there is no more specific error code
	1155	defined.
	1156
	1157	SSH_FX_BAD_MESSAGE
	1158	may be returned if a badly formatted packet or protocol
	1159	incompatibility is detected.
	1160
	1161	SSH_FX_NO_CONNECTION
	1162	is a pseudo-error which indicates that the client has no
	1163	connection to the server (it can only be generated locally by the
	1164	client, and MUST NOT be returned by servers).
	1165
	1166	SSH_FX_CONNECTION_LOST
	1167	is a pseudo-error which indicates that the connection to the
	1168	server has been lost (it can only be generated locally by the
	1169	client, and MUST NOT be returned by servers).
	1170
	1171
	1172
	1173
	1174	Ylonen & Lehtinen Expires April 1, 2002 [Page 21]
	1175
	1176	Internet-Draft SSH File Transfer Protocol October 2001
	1177
	1178
	1179	SSH_FX_OP_UNSUPPORTED
	1180	indicates that an attempt was made to perform an operation which
	1181	is not supported for the server (it may be generated locally by
	1182	the client if e.g. the version number exchange indicates that a
	1183	required feature is not supported by the server, or it may be
	1184	returned by the server if the server does not implement an
	1185	operation).
	1186
	1187	The SSH_FXP_HANDLE response has the following format:
	1188
	1189	uint32 id
	1190	string handle
	1191
	1192	where `id' is the request identifier, and `handle' is an arbitrary
	1193	string that identifies an open file or directory on the server. The
	1194	handle is opaque to the client; the client MUST NOT attempt to
	1195	interpret or modify it in any way. The length of the handle string
	1196	MUST NOT exceed 256 data bytes.
	1197
	1198	The SSH_FXP_DATA response has the following format:
	1199
	1200	uint32 id
	1201	string data
	1202
	1203	where `id' is the request identifier, and `data' is an arbitrary byte
	1204	string containing the requested data. The data string may be at most
	1205	the number of bytes requested in a SSH_FXP_READ request, but may also
	1206	be shorter if end of file is reached or if the read is from something
	1207	other than a regular file.
	1208
	1209	The SSH_FXP_NAME response has the following format:
	1210
	1211	uint32 id
	1212	uint32 count
	1213	repeats count times:
	1214	string filename
	1215	string longname
	1216	ATTRS attrs
	1217
	1218	where `id' is the request identifier, `count' is the number of names
	1219	returned in this response, and the remaining fields repeat `count'
	1220	times (so that all three fields are first included for the first
	1221	file, then for the second file, etc). In the repeated part,
	1222	`filename' is a file name being returned (for SSH_FXP_READDIR, it
	1223	will be a relative name within the directory, without any path
	1224	components; for SSH_FXP_REALPATH it will be an absolute path name),
	1225	`longname' is an expanded format for the file name, similar to what
	1226	is returned by "ls -l" on Unix systems, and `attrs' is the attributes
	1227
	1228
	1229
	1230	Ylonen & Lehtinen Expires April 1, 2002 [Page 22]
	1231
	1232	Internet-Draft SSH File Transfer Protocol October 2001
	1233
	1234
	1235	of the file as described in Section ``File Attributes''.
	1236
	1237	The format of the `longname' field is unspecified by this protocol.
	1238	It MUST be suitable for use in the output of a directory listing
	1239	command (in fact, the recommended operation for a directory listing
	1240	command is to simply display this data). However, clients SHOULD NOT
	1241	attempt to parse the longname field for file attributes; they SHOULD
	1242	use the attrs field instead.
	1243
	1244	The recommended format for the longname field is as follows:
	1245
	1246	-rwxr-xr-x 1 mjos staff 348911 Mar 25 14:29 t-filexfer
	1247	1234567890 123 12345678 12345678 12345678 123456789012
	1248
	1249	Here, the first line is sample output, and the second field indicates
	1250	widths of the various fields. Fields are separated by spaces. The
	1251	first field lists file permissions for user, group, and others; the
	1252	second field is link count; the third field is the name of the user
	1253	who owns the file; the fourth field is the name of the group that
	1254	owns the file; the fifth field is the size of the file in bytes; the
	1255	sixth field (which actually may contain spaces, but is fixed to 12
	1256	characters) is the file modification time, and the seventh field is
	1257	the file name. Each field is specified to be a minimum of certain
	1258	number of character positions (indicated by the second line above),
	1259	but may also be longer if the data does not fit in the specified
	1260	length.
	1261
	1262	The SSH_FXP_ATTRS response has the following format:
	1263
	1264	uint32 id
	1265	ATTRS attrs
	1266
	1267	where `id' is the request identifier, and `attrs' is the returned
	1268	file attributes as described in Section ``File Attributes''.
	1269
	1270
	1271
	1272
	1273
	1274
	1275
	1276
	1277
	1278
	1279
	1280
	1281
	1282
	1283
	1284
	1285
	1286	Ylonen & Lehtinen Expires April 1, 2002 [Page 23]
	1287
	1288	Internet-Draft SSH File Transfer Protocol October 2001
	1289
	1290
	1291	8. Vendor-Specific Extensions
	1292
	1293	The SSH_FXP_EXTENDED request provides a generic extension mechanism
	1294	for adding vendor-specific commands. The request has the following
	1295	format:
	1296
	1297	uint32 id
	1298	string extended-request
	1299	... any request-specific data ...
	1300
	1301	where `id' is the request identifier, and `extended-request' is a
	1302	string of the format "name@domain", where domain is an internet
	1303	domain name of the vendor defining the request. The rest of the
	1304	request is completely vendor-specific, and servers should only
	1305	attempt to interpret it if they recognize the `extended-request'
	1306	name.
	1307
	1308	The server may respond to such requests using any of the response
	1309	packets defined in Section ``Responses from the Server to the
	1310	Client''. Additionally, the server may also respond with a
	1311	SSH_FXP_EXTENDED_REPLY packet, as defined below. If the server does
	1312	not recognize the `extended-request' name, then the server MUST
	1313	respond with SSH_FXP_STATUS with error/status set to
	1314	SSH_FX_OP_UNSUPPORTED.
	1315
	1316	The SSH_FXP_EXTENDED_REPLY packet can be used to carry arbitrary
	1317	extension-specific data from the server to the client. It is of the
	1318	following format:
	1319
	1320	uint32 id
	1321	... any request-specific data ...
	1322
	1323
	1324
	1325
	1326
	1327
	1328
	1329
	1330
	1331
	1332
	1333
	1334
	1335
	1336
	1337
	1338
	1339
	1340
	1341
	1342	Ylonen & Lehtinen Expires April 1, 2002 [Page 24]
	1343
	1344	Internet-Draft SSH File Transfer Protocol October 2001
	1345
	1346
	1347	9. Security Considerations
	1348
	1349	This protocol assumes that it is run over a secure channel and that
	1350	the endpoints of the channel have been authenticated. Thus, this
	1351	protocol assumes that it is externally protected from network-level
	1352	attacks.
	1353
	1354	This protocol provides file system access to arbitrary files on the
	1355	server (only constrained by the server implementation). It is the
	1356	responsibility of the server implementation to enforce any access
	1357	controls that may be required to limit the access allowed for any
	1358	particular user (the user being authenticated externally to this
	1359	protocol, typically using the SSH User Authentication Protocol [6].
	1360
	1361	Care must be taken in the server implementation to check the validity
	1362	of received file handle strings. The server should not rely on them
	1363	directly; it MUST check the validity of each handle before relying on
	1364	it.
	1365
	1366
	1367
	1368
	1369
	1370
	1371
	1372
	1373
	1374
	1375
	1376
	1377
	1378
	1379
	1380
	1381
	1382
	1383
	1384
	1385
	1386
	1387
	1388
	1389
	1390
	1391
	1392
	1393
	1394
	1395
	1396
	1397
	1398	Ylonen & Lehtinen Expires April 1, 2002 [Page 25]
	1399
	1400	Internet-Draft SSH File Transfer Protocol October 2001
	1401
	1402
	1403	10. Changes from previous protocol versions
	1404
	1405	The SSH File Transfer Protocol has changed over time, before it's
	1406	standardization. The following is a description of the incompatible
	1407	changes between different versions.
	1408
	1409	10.1 Changes between versions 3 and 2
	1410
	1411	o The SSH_FXP_READLINK and SSH_FXP_SYMLINK messages were added.
	1412
	1413	o The SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY messages were
	1414	added.
	1415
	1416	o The SSH_FXP_STATUS message was changed to include fields `error
	1417	message' and `language tag'.
	1418
	1419
	1420	10.2 Changes between versions 2 and 1
	1421
	1422	o The SSH_FXP_RENAME message was added.
	1423
	1424
	1425	10.3 Changes between versions 1 and 0
	1426
	1427	o Implementation changes, no actual protocol changes.
	1428
	1429
	1430
	1431
	1432
	1433
	1434
	1435
	1436
	1437
	1438
	1439
	1440
	1441
	1442
	1443
	1444
	1445
	1446
	1447
	1448
	1449
	1450
	1451
	1452
	1453
	1454	Ylonen & Lehtinen Expires April 1, 2002 [Page 26]
	1455
	1456	Internet-Draft SSH File Transfer Protocol October 2001
	1457
	1458
	1459	11. Trademark Issues
	1460
	1461	"ssh" is a registered trademark of SSH Communications Security Corp
	1462	in the United States and/or other countries.
	1463
	1464
	1465
	1466
	1467
	1468
	1469
	1470
	1471
	1472
	1473
	1474
	1475
	1476
	1477
	1478
	1479
	1480
	1481
	1482
	1483
	1484
	1485
	1486
	1487
	1488
	1489
	1490
	1491
	1492
	1493
	1494
	1495
	1496
	1497
	1498
	1499
	1500
	1501
	1502
	1503
	1504
	1505
	1506
	1507
	1508
	1509
	1510	Ylonen & Lehtinen Expires April 1, 2002 [Page 27]
	1511
	1512	Internet-Draft SSH File Transfer Protocol October 2001
	1513
	1514
	1515	References
	1516
	1517	[1] Dierks, T., Allen, C., Treese, W., Karlton, P., Freier, A. and
	1518	P. Kocher, "The TLS Protocol Version 1.0", RFC 2246, January
	1519	1999.
	1520
	1521	[2] Institute of Electrical and Electronics Engineers, "Information
	1522	Technology - Portable Operating System Interface (POSIX) - Part
	1523	1: System Application Program Interface (API) [C Language]",
	1524	IEEE Standard 1003.2, 1996.
	1525
	1526	[3] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S.
	1527	Lehtinen, "SSH Protocol Architecture", draft-ietf-secsh-
	1528	architecture-09 (work in progress), July 2001.
	1529
	1530	[4] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S.
	1531	Lehtinen, "SSH Protocol Transport Protocol", draft-ietf-secsh-
	1532	architecture-09 (work in progress), July 2001.
	1533
	1534	[5] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S.
	1535	Lehtinen, "SSH Connection Protocol", draft-ietf-secsh-connect-11
	1536	(work in progress), July 2001.
	1537
	1538	[6] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S.
	1539	Lehtinen, "SSH Authentication Protocol", draft-ietf-secsh-
	1540	userauth-11 (work in progress), July 2001.
	1541
	1542
	1543	Authors' Addresses
	1544
	1545	Tatu Ylonen
	1546	SSH Communications Security Corp
	1547	Fredrikinkatu 42
	1548	HELSINKI FIN-00100
	1549	Finland
	1550
	1551	EMail: ylo@ssh.com
	1552
	1553
	1554	Sami Lehtinen
	1555	SSH Communications Security Corp
	1556	Fredrikinkatu 42
	1557	HELSINKI FIN-00100
	1558	Finland
	1559
	1560	EMail: sjl@ssh.com
	1561
	1562
	1563
	1564
	1565
	1566	Ylonen & Lehtinen Expires April 1, 2002 [Page 28]
	1567
	1568	Internet-Draft SSH File Transfer Protocol October 2001
	1569
	1570
	1571	Full Copyright Statement
	1572
	1573	Copyright (C) The Internet Society (2001). All Rights Reserved.
	1574
	1575	This document and translations of it may be copied and furnished to
	1576	others, and derivative works that comment on or otherwise explain it
	1577	or assist in its implementation may be prepared, copied, published
	1578	and distributed, in whole or in part, without restriction of any
	1579	kind, provided that the above copyright notice and this paragraph are
	1580	included on all such copies and derivative works. However, this
	1581	document itself may not be modified in any way, such as by removing
	1582	the copyright notice or references to the Internet Society or other
	1583	Internet organizations, except as needed for the purpose of
	1584	developing Internet standards in which case the procedures for
	1585	copyrights defined in the Internet Standards process must be
	1586	followed, or as required to translate it into languages other than
	1587	English.
	1588
	1589	The limited permissions granted above are perpetual and will not be
	1590	revoked by the Internet Society or its successors or assigns.
	1591
	1592	This document and the information contained herein is provided on an
	1593	"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
	1594	TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
	1595	BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
	1596	HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
	1597	MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
	1598
	1599	Acknowledgement
	1600
	1601	Funding for the RFC Editor function is currently provided by the
	1602	Internet Society.
	1603
	1604
	1605
	1606
	1607
	1608
	1609
	1610
	1611
	1612
	1613
	1614
	1615
	1616
	1617
	1618
	1619
	1620
	1621
	1622	Ylonen & Lehtinen Expires April 1, 2002 [Page 29]
	1623
	1624
	1625

+1962

-0

rfc/draft-ietf-secsh-filexfer-03.txt less more

	0
	1
	2
	3	Secure Shell Working Group J. Galbraith
	4	Internet-Draft VanDyke Software
	5	Expires: April 16, 2003 T. Ylonen
	6	S. Lehtinen
	7	SSH Communications Security Corp
	8	October 16, 2002
	9
	10
	11	SSH File Transfer Protocol
	12	draft-ietf-secsh-filexfer-03.txt
	13
	14	Status of this Memo
	15
	16	This document is an Internet-Draft and is in full conformance with
	17	all provisions of Section 10 of RFC2026.
	18
	19	Internet-Drafts are working documents of the Internet Engineering
	20	Task Force (IETF), its areas, and its working groups. Note that
	21	other groups may also distribute working documents as Internet-
	22	Drafts.
	23
	24	Internet-Drafts are draft documents valid for a maximum of six months
	25	and may be updated, replaced, or obsoleted by other documents at any
	26	time. It is inappropriate to use Internet-Drafts as reference
	27	material or to cite them other than as "work in progress."
	28
	29	The list of current Internet-Drafts can be accessed at http://
	30	www.ietf.org/ietf/1id-abstracts.txt.
	31
	32	The list of Internet-Draft Shadow Directories can be accessed at
	33	http://www.ietf.org/shadow.html.
	34
	35	This Internet-Draft will expire on April 16, 2003.
	36
	37	Copyright Notice
	38
	39	Copyright (C) The Internet Society (2002). All Rights Reserved.
	40
	41	Abstract
	42
	43	The SSH File Transfer Protocol provides secure file transfer
	44	functionality over any reliable data stream. It is the standard file
	45	transfer protocol for use with the SSH2 protocol. This document
	46	describes the file transfer protocol and its interface to the SSH2
	47	protocol suite.
	48
	49
	50
	51
	52
	53
	54
	55	Galbraith, et al. Expires April 16, 2003 [Page 1]
	56
	57	Internet-Draft SSH File Transfer Protocol October 2002
	58
	59
	60	Table of Contents
	61
	62	1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 3
	63	2. Use with the SSH Connection Protocol . . . . . . . . . . . 4
	64	3. General Packet Format . . . . . . . . . . . . . . . . . . 5
	65	4. Protocol Initialization . . . . . . . . . . . . . . . . . 7
	66	4.1 Client Initialization . . . . . . . . . . . . . . . . . . 7
	67	4.2 Server Initialization . . . . . . . . . . . . . . . . . . 7
	68	4.3 Determining Server Newline Convention . . . . . . . . . . 8
	69	5. File Attributes . . . . . . . . . . . . . . . . . . . . . 9
	70	5.1 Flags . . . . . . . . . . . . . . . . . . . . . . . . . . 9
	71	5.2 Type . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
	72	5.3 Size . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
	73	5.4 Owner and Group . . . . . . . . . . . . . . . . . . . . . 10
	74	5.5 Permissions . . . . . . . . . . . . . . . . . . . . . . . 11
	75	5.6 Times . . . . . . . . . . . . . . . . . . . . . . . . . . 11
	76	5.7 ACL . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
	77	5.8 Extended attributes . . . . . . . . . . . . . . . . . . . 12
	78	6. Requests From the Client to the Server . . . . . . . . . . 13
	79	6.1 Request Synchronization and Reordering . . . . . . . . . . 13
	80	6.2 File Names . . . . . . . . . . . . . . . . . . . . . . . . 14
	81	6.3 Opening, Creating, and Closing Files . . . . . . . . . . . 14
	82	6.4 Reading and Writing . . . . . . . . . . . . . . . . . . . 17
	83	6.5 Removing and Renaming Files . . . . . . . . . . . . . . . 18
	84	6.6 Creating and Deleting Directories . . . . . . . . . . . . 19
	85	6.7 Scanning Directories . . . . . . . . . . . . . . . . . . . 19
	86	6.8 Retrieving File Attributes . . . . . . . . . . . . . . . . 20
	87	6.9 Setting File Attributes . . . . . . . . . . . . . . . . . 21
	88	6.10 Dealing with Symbolic links . . . . . . . . . . . . . . . 22
	89	6.11 Canonicalizing the Server-Side Path Name . . . . . . . . . 23
	90	6.11.1 Best practice for dealing with paths . . . . . . . . . . . 23
	91	7. Responses from the Server to the Client . . . . . . . . . 24
	92	8. Vendor-Specific Extensions . . . . . . . . . . . . . . . . 28
	93	9. Security Considerations . . . . . . . . . . . . . . . . . 29
	94	10. Changes from previous protocol versions . . . . . . . . . 30
	95	10.1 Changes between versions 4 and 3 . . . . . . . . . . . . . 30
	96	10.2 Changes between versions 3 and 2 . . . . . . . . . . . . . 31
	97	10.3 Changes between versions 2 and 1 . . . . . . . . . . . . . 31
	98	10.4 Changes between versions 1 and 0 . . . . . . . . . . . . . 31
	99	11. Trademark Issues . . . . . . . . . . . . . . . . . . . . . 32
	100	References . . . . . . . . . . . . . . . . . . . . . . . . 33
	101	Authors' Addresses . . . . . . . . . . . . . . . . . . . . 33
	102	Full Copyright Statement . . . . . . . . . . . . . . . . . 35
	103
	104
	105
	106
	107
	108
	109
	110
	111	Galbraith, et al. Expires April 16, 2003 [Page 2]
	112
	113	Internet-Draft SSH File Transfer Protocol October 2002
	114
	115
	116	1. Introduction
	117
	118	This protocol provides secure file transfer (and more generally file
	119	system access) functionality over a reliable data stream, such as a
	120	channel in the SSH2 protocol [5].
	121
	122	This protocol is designed so that it could be used to implement a
	123	secure remote file system service, as well as a secure file transfer
	124	service.
	125
	126	This protocol assumes that it runs over a secure channel, and that
	127	the server has already authenticated the user at the client end, and
	128	that the identity of the client user is externally available to the
	129	server implementation.
	130
	131	In general, this protocol follows a simple request-response model.
	132	Each request and response contains a sequence number and multiple
	133	requests may be pending simultaneously. There are a relatively large
	134	number of different request messages, but a small number of possible
	135	response messages. Each request has one or more response messages
	136	that may be returned in result (e.g., a read either returns data or
	137	reports error status).
	138
	139	The packet format descriptions in this specification follow the
	140	notation presented in the secsh architecture draft. [5]
	141
	142	Even though this protocol is described in the context of the SSH2
	143	protocol, this protocol is general and independent of the rest of the
	144	SSH2 protocol suite. It could be used in a number of different
	145	applications, such as secure file transfer over TLS RFC 2246 [1] and
	146	transfer of management information in VPN applications.
	147
	148
	149
	150
	151
	152
	153
	154
	155
	156
	157
	158
	159
	160
	161
	162
	163
	164
	165
	166
	167	Galbraith, et al. Expires April 16, 2003 [Page 3]
	168
	169	Internet-Draft SSH File Transfer Protocol October 2002
	170
	171
	172	2. Use with the SSH Connection Protocol
	173
	174	When used with the SSH2 Protocol suite, this protocol is intended to
	175	be used from the SSH Connection Protocol [7] as a subsystem, as
	176	described in section ``Starting a Shell or a Command''. The
	177	subsystem name used with this protocol is "sftp".
	178
	179
	180
	181
	182
	183
	184
	185
	186
	187
	188
	189
	190
	191
	192
	193
	194
	195
	196
	197
	198
	199
	200
	201
	202
	203
	204
	205
	206
	207
	208
	209
	210
	211
	212
	213
	214
	215
	216
	217
	218
	219
	220
	221
	222
	223	Galbraith, et al. Expires April 16, 2003 [Page 4]
	224
	225	Internet-Draft SSH File Transfer Protocol October 2002
	226
	227
	228	3. General Packet Format
	229
	230	All packets transmitted over the secure connection are of the
	231	following format:
	232
	233	uint32 length
	234	byte type
	235	byte[length - 1] data payload
	236
	237	That is, they are just data preceded by 32-bit length and 8-bit type
	238	fields. The `length' is the length of the data area, and does not
	239	include the `length' field itself. The format and interpretation of
	240	the data area depends on the packet type.
	241
	242	All packet descriptions below only specify the packet type and the
	243	data that goes into the data field. Thus, they should be prefixed by
	244	the `length' and `type' fields.
	245
	246	The maximum size of a packet is in practice determined by the client
	247	(the maximum size of read or write requests that it sends, plus a few
	248	bytes of packet overhead). All servers SHOULD support packets of at
	249	least 34000 bytes (where the packet size refers to the full length,
	250	including the header above). This should allow for reads and writes
	251	of at most 32768 bytes.
	252
	253	There is no limit on the number of outstanding (non-acknowledged)
	254	requests that the client may send to the server. In practice this is
	255	limited by the buffering available on the data stream and the queuing
	256	performed by the server. If the server's queues are full, it should
	257	not read any more data from the stream, and flow control will prevent
	258	the client from sending more requests. Note, however, that while
	259	there is no restriction on the protocol level, the client's API may
	260	provide a limit in order to prevent infinite queuing of outgoing
	261	requests at the client.
	262
	263	The following values are defined for packet types.
	264
	265
	266
	267
	268
	269
	270
	271
	272
	273
	274
	275
	276
	277
	278
	279	Galbraith, et al. Expires April 16, 2003 [Page 5]
	280
	281	Internet-Draft SSH File Transfer Protocol October 2002
	282
	283
	284	#define SSH_FXP_INIT 1
	285	#define SSH_FXP_VERSION 2
	286	#define SSH_FXP_OPEN 3
	287	#define SSH_FXP_CLOSE 4
	288	#define SSH_FXP_READ 5
	289	#define SSH_FXP_WRITE 6
	290	#define SSH_FXP_LSTAT 7
	291	#define SSH_FXP_FSTAT 8
	292	#define SSH_FXP_SETSTAT 9
	293	#define SSH_FXP_FSETSTAT 10
	294	#define SSH_FXP_OPENDIR 11
	295	#define SSH_FXP_READDIR 12
	296	#define SSH_FXP_REMOVE 13
	297	#define SSH_FXP_MKDIR 14
	298	#define SSH_FXP_RMDIR 15
	299	#define SSH_FXP_REALPATH 16
	300	#define SSH_FXP_STAT 17
	301	#define SSH_FXP_RENAME 18
	302	#define SSH_FXP_READLINK 19
	303	#define SSH_FXP_SYMLINK 20
	304
	305	#define SSH_FXP_STATUS 101
	306	#define SSH_FXP_HANDLE 102
	307	#define SSH_FXP_DATA 103
	308	#define SSH_FXP_NAME 104
	309	#define SSH_FXP_ATTRS 105
	310
	311	#define SSH_FXP_EXTENDED 200
	312	#define SSH_FXP_EXTENDED_REPLY 201
	313
	314	RESERVED_FOR_EXTENSIONS 210-255
	315
	316	Additional packet types should only be defined if the protocol
	317	version number (see Section ``Protocol Initialization'') is
	318	incremented, and their use MUST be negotiated using the version
	319	number. However, the SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY
	320	packets can be used to implement vendor-specific extensions. See
	321	Section ``Vendor-Specific-Extensions'' for more details.
	322
	323
	324
	325
	326
	327
	328
	329
	330
	331
	332
	333
	334
	335	Galbraith, et al. Expires April 16, 2003 [Page 6]
	336
	337	Internet-Draft SSH File Transfer Protocol October 2002
	338
	339
	340	4. Protocol Initialization
	341
	342	When the file transfer protocol starts, the client first sends a
	343	SSH_FXP_INIT (including its version number) packet to the server.
	344	The server responds with a SSH_FXP_VERSION packet, supplying the
	345	lowest of its own and the client's version number. Both parties
	346	should from then on adhere to particular version of the protocol.
	347
	348	The version number of the protocol specified in this document is 4.
	349	The version number should be incremented for each incompatible
	350	revision of this protocol.
	351
	352	4.1 Client Initialization
	353
	354	The SSH_FXP_INIT packet (from client to server) has the following
	355	data:
	356
	357	uint32 version
	358
	359	Version 3 of this protocol allowed clients to include extensions in
	360	the SSH_FXP_INIT packet; however, this can cause interoperability
	361	problems with version 1 and version 2 servers because the client must
	362	send this packet before knowing the servers version.
	363
	364	In this version of the protocol, clients MUST use the
	365	SSH_FXP_EXTENDED packet to send extensions to the server after
	366	version exchange has completed. Clients MUST NOT include extensions
	367	in the version packet. This will prevent interoperability problems
	368	with older servers
	369
	370	4.2 Server Initialization
	371
	372	The SSH_FXP_VERSION packet (from server to client) has the following
	373	data:
	374
	375	uint32 version
	376	<extension data>
	377
	378	'version' is the lower of the protocol version supported by the
	379	server and the version number received from the client.
	380
	381	The extension data may be empty, or may be a sequence of
	382
	383	string extension_name
	384	string extension_data
	385
	386	pairs (both strings MUST always be present if one is, but the
	387	`extension_data' string may be of zero length). If present, these
	388
	389
	390
	391	Galbraith, et al. Expires April 16, 2003 [Page 7]
	392
	393	Internet-Draft SSH File Transfer Protocol October 2002
	394
	395
	396	strings indicate extensions to the baseline protocol. The
	397	`extension_name' field(s) identify the name of the extension. The
	398	name should be of the form "name@domain", where the domain is the DNS
	399	domain name of the organization defining the extension. Additional
	400	names that are not of this format may be defined later by the IETF.
	401	Implementations MUST silently ignore any extensions whose name they
	402	do not recognize.
	403
	404	4.3 Determining Server Newline Convention
	405
	406	In order to correctly process text files in a cross platform
	407	compatible way, the newline convention must be converted from that of
	408	the server to that of the client, or, during an upload, from that of
	409	the client to that of the server.
	410
	411	Versions 3 and prior of this protocol made no provisions for
	412	processing text files. Many clients implemented some sort of
	413	conversion algorithm, but without either a 'canonical' on the wire
	414	format or knowledge of the servers newline convention, correct
	415	conversion was not always possible.
	416
	417	Starting with Version 4, the SSH_FXF_TEXT file open flag (Section
	418	6.3) makes it possible to request that the server translate a file to
	419	a 'canonical' on the wire format. This format uses \r\n as the line
	420	separator.
	421
	422	Servers for systems using multiple newline characters (for example,
	423	Mac OS X or VMS) or systems using counted records, MUST translate to
	424	the canonical form.
	425
	426	However, to ease the burden of implementation on servers that use a
	427	single, simple separator sequence, the following extension allows the
	428	canonical format to be changed.
	429
	430	string "newline"
	431	string new-canonical-separator (usually "\r" or "\n" or "\r\n")
	432
	433	All clients MUST support this extension.
	434
	435	When processing text files, clients SHOULD NOT translate any
	436	character or sequence that is not an exact match of the servers
	437	newline separator.
	438
	439	In particular, if the newline sequence being used is the canonical
	440	"\r\n" sequence, a lone \r or a lone \n SHOULD be written through
	441	without change.
	442
	443
	444
	445
	446
	447	Galbraith, et al. Expires April 16, 2003 [Page 8]
	448
	449	Internet-Draft SSH File Transfer Protocol October 2002
	450
	451
	452	5. File Attributes
	453
	454	A new compound data type is defined for encoding file attributes.
	455	The same encoding is used both when returning file attributes from
	456	the server and when sending file attributes to the server. When
	457	sending it to the server, the flags field specifies which attributes
	458	are included, and the server will use default values for the
	459	remaining attributes (or will not modify the values of remaining
	460	attributes). When receiving attributes from the server, the flags
	461	specify which attributes are included in the returned data. The
	462	server normally returns all attributes it knows about.
	463
	464	uint32 flags
	465	byte type always present
	466	uint64 size present only if flag SSH_FILEXFER_ATTR_SIZE
	467	string owner present only if flag SSH_FILEXFER_ATTR_OWNERGROUP
	468	string group present only if flag SSH_FILEXFER_ATTR_OWNERGROUP
	469	uint32 permissions present only if flag SSH_FILEXFER_ATTR_PERMISSIONS
	470	uint32 atime present only if flag SSH_FILEXFER_ATTR_ACCESSTIME
	471	uint32 createtime present only if flag SSH_FILEXFER_ATTR_CREATETIME
	472	uint32 mtime present only if flag SSH_FILEXFER_ATTR_MODIFYTIME
	473	string acl present only if flag SSH_FILEXFER_ATTR_ACL
	474	uint32 extended_count present only if flag SSH_FILEXFER_ATTR_EXTENDED
	475	string extended_type
	476	string extended_data
	477	... more extended data (extended_type - extended_data pairs),
	478	so that number of pairs equals extended_count
	479
	480
	481	5.1 Flags
	482
	483	The `flags' specify which of the fields are present. Those fields
	484	for which the corresponding flag is not set are not present (not
	485	included in the packet). New flags can only be added by incrementing
	486	the protocol version number (or by using the extension mechanism
	487	described below).
	488
	489	The flags bits are defined to have the following values:
	490
	491	#define SSH_FILEXFER_ATTR_SIZE 0x00000001
	492	#define SSH_FILEXFER_ATTR_PERMISSIONS 0x00000004
	493	#define SSH_FILEXFER_ATTR_ACCESSTIME 0x00000008
	494	#define SSH_FILEXFER_ATTR_CREATETIME 0x00000010
	495	#define SSH_FILEXFER_ATTR_MODIFYTIME 0x00000020
	496	#define SSH_FILEXFER_ATTR_ACL 0x00000040
	497	#define SSH_FILEXFER_ATTR_OWNERGROUP 0x00000080
	498	#define SSH_FILEXFER_ATTR_EXTENDED 0x80000000
	499
	500
	501
	502
	503	Galbraith, et al. Expires April 16, 2003 [Page 9]
	504
	505	Internet-Draft SSH File Transfer Protocol October 2002
	506
	507
	508	In previous versions of this protocol flags value 0x00000002 was
	509	SSH_FILEXFER_ATTR_UIDGID. This value is now unused, and OWNERGROUP
	510	was given a new value in order to ease implementation burden.
	511	0x00000002 MUST NOT appear in the mask. Some future version of this
	512	protocol may reuse flag 0x00000002.
	513
	514	5.2 Type
	515
	516	The type field is always present. The following types are defined:
	517
	518	#define SSH_FILEXFER_TYPE_REGULAR 1
	519	#define SSH_FILEXFER_TYPE_DIRECTORY 2
	520	#define SSH_FILEXFER_TYPE_SYMLINK 3
	521	#define SSH_FILEXFER_TYPE_SPECIAL 4
	522	#define SSH_FILEXFER_TYPE_UNKNOWN 5
	523
	524	On a POSIX system, these values would be derived from the permission
	525	field.
	526
	527	5.3 Size
	528
	529	The `size' field specifies the size of the file on disk, in bytes.
	530	If it is present during file creation, it should be considered a hint
	531	as to the files eventual size.
	532
	533	Files opened with the SSH_FXF_TEXT flag may have a size that is
	534	greater or less than the value of the size field.
	535
	536	5.4 Owner and Group
	537
	538	The `owner' and `group' fields are represented as UTF-8 strings; this
	539	is the form used by NFS v4. See NFS version 4 Protocol. [3] The
	540	following text is selected quotations from section 5.6.
	541
	542	To avoid a representation that is tied to a particular underlying
	543	implementation at the client or server, the use of UTF-8 strings has
	544	been chosen. The string should be of the form user@dns_domain".
	545	This will allow for a client and server that do not use the same
	546	local representation the ability to translate to a common syntax that
	547	can be interpreted by both. In the case where there is no
	548	translation available to the client or server, the attribute value
	549	must be constructed without the "@". Therefore, the absence of the @
	550	from the owner or owner_group attribute signifies that no translation
	551	was available and the receiver of the attribute should not place any
	552	special meaning with the attribute value. Even though the attribute
	553	value can not be translated, it may still be useful. In the case of
	554	a client, the attribute string may be used for local display of
	555	ownership.
	556
	557
	558
	559	Galbraith, et al. Expires April 16, 2003 [Page 10]
	560
	561	Internet-Draft SSH File Transfer Protocol October 2002
	562
	563
	564	5.5 Permissions
	565
	566	The `permissions' field contains a bit mask of file permissions as
	567	defined by POSIX [1].
	568
	569	5.6 Times
	570
	571	The 'atime', 'createtime', and 'mtime' contain the access, creation,
	572	and modification times of the files, respectively. They are
	573	represented as seconds from Jan 1, 1970 in UTC.
	574
	575	5.7 ACL
	576
	577	The 'ACL' field contains an ACL similar to that defined in section
	578	5.9 of NFS version 4 Protocol [3].
	579
	580	uint32 ace-count
	581
	582	repeated ace-count time:
	583	uint32 ace-type
	584	uint32 ace-flag
	585	uint32 ace-mask
	586	string who [UTF-8]
	587
	588	ace-type is one of the following four values (taken from NFS Version
	589	4 Protocol [3]:
	590
	591	const ACE4_ACCESS_ALLOWED_ACE_TYPE = 0x00000000;
	592	const ACE4_ACCESS_DENIED_ACE_TYPE = 0x00000001;
	593	const ACE4_SYSTEM_AUDIT_ACE_TYPE = 0x00000002;
	594	const ACE4_SYSTEM_ALARM_ACE_TYPE = 0x00000003;
	595
	596	ace-flag is a combination of the following flag values. See NFS
	597	Version 4 Protocol [3] section 5.9.2:
	598
	599	const ACE4_FILE_INHERIT_ACE = 0x00000001;
	600	const ACE4_DIRECTORY_INHERIT_ACE = 0x00000002;
	601	const ACE4_NO_PROPAGATE_INHERIT_ACE = 0x00000004;
	602	const ACE4_INHERIT_ONLY_ACE = 0x00000008;
	603	const ACE4_SUCCESSFUL_ACCESS_ACE_FLAG = 0x00000010;
	604	const ACE4_FAILED_ACCESS_ACE_FLAG = 0x00000020;
	605	const ACE4_IDENTIFIER_GROUP = 0x00000040;
	606
	607	ace-mask is any combination of the following flags (taken from NFS
	608	Version 4 Protocol [3] section 5.9.3:
	609
	610
	611
	612
	613
	614
	615	Galbraith, et al. Expires April 16, 2003 [Page 11]
	616
	617	Internet-Draft SSH File Transfer Protocol October 2002
	618
	619
	620	const ACE4_READ_DATA = 0x00000001;
	621	const ACE4_LIST_DIRECTORY = 0x00000001;
	622	const ACE4_WRITE_DATA = 0x00000002;
	623	const ACE4_ADD_FILE = 0x00000002;
	624	const ACE4_APPEND_DATA = 0x00000004;
	625	const ACE4_ADD_SUBDIRECTORY = 0x00000004;
	626	const ACE4_READ_NAMED_ATTRS = 0x00000008;
	627	const ACE4_WRITE_NAMED_ATTRS = 0x00000010;
	628	const ACE4_EXECUTE = 0x00000020;
	629	const ACE4_DELETE_CHILD = 0x00000040;
	630	const ACE4_READ_ATTRIBUTES = 0x00000080;
	631	const ACE4_WRITE_ATTRIBUTES = 0x00000100;
	632	const ACE4_DELETE = 0x00010000;
	633	const ACE4_READ_ACL = 0x00020000;
	634	const ACE4_WRITE_ACL = 0x00040000;
	635	const ACE4_WRITE_OWNER = 0x00080000;
	636	const ACE4_SYNCHRONIZE = 0x00100000;
	637
	638	who is a UTF-8 string of the form described in 'Owner and Group'
	639	(Section 5.4)
	640
	641	5.8 Extended attributes
	642
	643	The SSH_FILEXFER_ATTR_EXTENDED flag provides a general extension
	644	mechanism for vendor-specific extensions. If the flag is specified,
	645	then the `extended_count' field is present. It specifies the number
	646	of extended_type-extended_data pairs that follow. Each of these
	647	pairs specifies an extended attribute. For each of the attributes,
	648	the extended_type field should be a string of the format
	649	"name@domain", where "domain" is a valid, registered domain name and
	650	"name" identifies the method. The IETF may later standardize certain
	651	names that deviate from this format (e.g., that do not contain the
	652	"@" sign). The interpretation of `extended_data' depends on the
	653	type. Implementations SHOULD ignore extended data fields that they
	654	do not understand.
	655
	656	Additional fields can be added to the attributes by either defining
	657	additional bits to the flags field to indicate their presence, or by
	658	defining extended attributes for them. The extended attributes
	659	mechanism is recommended for most purposes; additional flags bits
	660	should only be defined by an IETF standards action that also
	661	increments the protocol version number. The use of such new fields
	662	MUST be negotiated by the version number in the protocol exchange.
	663	It is a protocol error if a packet with unsupported protocol bits is
	664	received.
	665
	666
	667
	668
	669
	670
	671	Galbraith, et al. Expires April 16, 2003 [Page 12]
	672
	673	Internet-Draft SSH File Transfer Protocol October 2002
	674
	675
	676	6. Requests From the Client to the Server
	677
	678	Requests from the client to the server represent the various file
	679	system operations. Each request begins with an `id' field, which is
	680	a 32-bit identifier identifying the request (selected by the client).
	681	The same identifier will be returned in the response to the request.
	682	One possible implementation is a monotonically increasing request
	683	sequence number (modulo 2^32).
	684
	685	Many operations in the protocol operate on open files. The
	686	SSH_FXP_OPEN request can return a file handle (which is an opaque
	687	variable-length string) which may be used to access the file later
	688	(e.g. in a read operation). The client MUST NOT send requests the
	689	server with bogus or closed handles. However, the server MUST
	690	perform adequate checks on the handle in order to avoid security
	691	risks due to fabricated handles.
	692
	693	This design allows either stateful and stateless server
	694	implementation, as well as an implementation which caches state
	695	between requests but may also flush it. The contents of the file
	696	handle string are entirely up to the server and its design. The
	697	client should not modify or attempt to interpret the file handle
	698	strings.
	699
	700	The file handle strings MUST NOT be longer than 256 bytes.
	701
	702	6.1 Request Synchronization and Reordering
	703
	704	The protocol and implementations MUST process requests relating to
	705	the same file in the order in which they are received. In other
	706	words, if an application submits multiple requests to the server, the
	707	results in the responses will be the same as if it had sent the
	708	requests one at a time and waited for the response in each case. For
	709	example, the server may process non-overlapping read/write requests
	710	to the same file in parallel, but overlapping reads and writes cannot
	711	be reordered or parallelized. However, there are no ordering
	712	restrictions on the server for processing requests from two different
	713	file transfer connections. The server may interleave and parallelize
	714	them at will.
	715
	716	There are no restrictions on the order in which responses to
	717	outstanding requests are delivered to the client, except that the
	718	server must ensure fairness in the sense that processing of no
	719	request will be indefinitely delayed even if the client is sending
	720	other requests so that there are multiple outstanding requests all
	721	the time.
	722
	723
	724
	725
	726
	727	Galbraith, et al. Expires April 16, 2003 [Page 13]
	728
	729	Internet-Draft SSH File Transfer Protocol October 2002
	730
	731
	732	6.2 File Names
	733
	734	This protocol represents file names as strings. File names are
	735	assumed to use the slash ('/') character as a directory separator.
	736
	737	File names starting with a slash are "absolute", and are relative to
	738	the root of the file system. Names starting with any other character
	739	are relative to the user's default directory (home directory). Note
	740	that identifying the user is assumed to take place outside of this
	741	protocol.
	742
	743	Servers SHOULD interpret a path name component ".." as referring to
	744	the parent directory, and "." as referring to the current directory.
	745	If the server implementation limits access to certain parts of the
	746	file system, it must be extra careful in parsing file names when
	747	enforcing such restrictions. There have been numerous reported
	748	security bugs where a ".." in a path name has allowed access outside
	749	the intended area.
	750
	751	An empty path name is valid, and it refers to the user's default
	752	directory (usually the user's home directory).
	753
	754	Otherwise, no syntax is defined for file names by this specification.
	755	Clients should not make any other assumptions; however, they can
	756	splice path name components returned by SSH_FXP_READDIR together
	757	using a slash ('/') as the separator, and that will work as expected.
	758
	759	In order to comply with IETF Policy on Character Sets and Languages
	760	[2], all filenames are to be encoded in UTF-8. The shortest valid
	761	UTF-8 encoding of the UNICODE data MUST be used. The server is
	762	responsible for converting the UNICODE data to whatever canonical
	763	form it requires.
	764
	765	For example, if the server requires that precomposed characters
	766	always be used, the server MUST NOT assume the filename as sent by
	767	the client has this attribute, but must do this normalization itself.
	768
	769	It is understood that the lack of well-defined semantics for file
	770	names may cause interoperability problems between clients and servers
	771	using radically different operating systems. However, this approach
	772	is known to work acceptably with most systems, and alternative
	773	approaches that e.g. treat file names as sequences of structured
	774	components are quite complicated.
	775
	776	6.3 Opening, Creating, and Closing Files
	777
	778	Files are opened and created using the SSH_FXP_OPEN message, whose
	779	data part is as follows:
	780
	781
	782
	783	Galbraith, et al. Expires April 16, 2003 [Page 14]
	784
	785	Internet-Draft SSH File Transfer Protocol October 2002
	786
	787
	788	uint32 id
	789	string filename [UTF-8]
	790	uint32 pflags
	791	ATTRS attrs
	792
	793	The `id' field is the request identifier as for all requests.
	794
	795	The `filename' field specifies the file name. See Section ``File
	796	Names'' for more information.
	797
	798	The `pflags' field is a bitmask. The following bits have been
	799	defined.
	800
	801	#define SSH_FXF_READ 0x00000001
	802	#define SSH_FXF_WRITE 0x00000002
	803	#define SSH_FXF_APPEND 0x00000004
	804	#define SSH_FXF_CREAT 0x00000008
	805	#define SSH_FXF_TRUNC 0x00000010
	806	#define SSH_FXF_EXCL 0x00000020
	807	#define SSH_FXF_TEXT 0x00000040
	808
	809	These have the following meanings:
	810
	811	SSH_FXF_READ
	812	Open the file for reading.
	813
	814	SSH_FXF_WRITE
	815	Open the file for writing. If both this and SSH_FXF_READ are
	816	specified, the file is opened for both reading and writing.
	817
	818	SSH_FXF_APPEND
	819	Force all writes to append data at the end of the file. The
	820	offset parameter to write will be ignored.
	821
	822	SSH_FXF_CREAT
	823	If this flag is specified, then a new file will be created if one
	824	does not already exist (if O_TRUNC is specified, the new file will
	825	be truncated to zero length if it previously exists).
	826
	827	SSH_FXF_TRUNC
	828	Forces an existing file with the same name to be truncated to zero
	829	length when creating a file by specifying SSH_FXF_CREAT.
	830	SSH_FXF_CREAT MUST also be specified if this flag is used.
	831
	832	SSH_FXF_EXCL
	833	Causes the request to fail if the named file already exists.
	834	SSH_FXF_CREAT MUST also be specified if this flag is used.
	835
	836
	837
	838
	839	Galbraith, et al. Expires April 16, 2003 [Page 15]
	840
	841	Internet-Draft SSH File Transfer Protocol October 2002
	842
	843
	844	SSH_FXF_TEXT
	845	Indicates that the server should treat the file as text and
	846	convert it to the canonical newline convention in use. (See
	847	Determining Server Newline Convention. (Section 4.3)
	848
	849	When a file is opened with the FXF_TEXT flag, the offset field in
	850	both the read and write function are ignored.
	851
	852	Servers MUST correctly process multiple parallel reads and writes
	853	correctly in this mode. Naturally, it is permissible for them to
	854	do this by serializing the requests. It would not be possible for
	855	a client to reliably detect a server that does not implement
	856	parallel writes in time to prevent damage.
	857
	858	Clients SHOULD use the SSH_FXF_APPEND flag to append data to a
	859	text file rather then using write with a calculated offset.
	860
	861	To support seeks on text file the following SSH_FXP_EXTENDED
	862	packet is defined.
	863
	864
	865
	866	string "text-seek"
	867	string file-handle
	868	uint64 line-number
	869
	870	line-number is the index of the line number to seek to, where byte
	871	0 in the file is line number 0, and the byte directly following
	872	the first newline sequence in the file is line number 1 and so on.
	873
	874	The response to a "text-seek" request is an SSH_FXP_STATUS
	875	message.
	876
	877	An attempt to seek past the end-of-file should result in a
	878	SSH_FX_EOF status.
	879
	880	Servers SHOULD support at least one "text-seek" in order to
	881	support resume. However, a client MUST be prepared to receive
	882	SSH_FX_OP_UNSUPPORTED when attempting a "text-seek" operation.
	883	The client can then try a fall-back strategy, if it has one.
	884
	885	Clients MUST be prepared to handle SSH_FX_OP_UNSUPPORTED returned
	886	for read or write operations that are not sequential.
	887
	888	The `attrs' field specifies the initial attributes for the file.
	889	Default values will be used for those attributes that are not
	890	specified. See Section ``File Attributes'' for more information.
	891
	892
	893
	894
	895	Galbraith, et al. Expires April 16, 2003 [Page 16]
	896
	897	Internet-Draft SSH File Transfer Protocol October 2002
	898
	899
	900	The response to this message will be either SSH_FXP_HANDLE (if the
	901	operation is successful) or SSH_FXP_STATUS (if the operation fails).
	902
	903	A file is closed by using the SSH_FXP_CLOSE request. Its data field
	904	has the following format:
	905
	906	uint32 id
	907	string handle
	908
	909	where `id' is the request identifier, and `handle' is a handle
	910	previously returned in the response to SSH_FXP_OPEN or
	911	SSH_FXP_OPENDIR. The handle becomes invalid immediately after this
	912	request has been sent.
	913
	914	The response to this request will be a SSH_FXP_STATUS message. One
	915	should note that on some server platforms even a close can fail.
	916	This can happen e.g. if the server operating system caches writes,
	917	and an error occurs while flushing cached writes during the close.
	918
	919	6.4 Reading and Writing
	920
	921	Once a file has been opened, it can be read using the SSH_FXP_READ
	922	message, which has the following format:
	923
	924	uint32 id
	925	string handle
	926	uint64 offset
	927	uint32 len
	928
	929	where `id' is the request identifier, `handle' is an open file handle
	930	returned by SSH_FXP_OPEN, `offset' is the offset (in bytes) relative
	931	to the beginning of the file from where to start reading, and `len'
	932	is the maximum number of bytes to read.
	933
	934	In response to this request, the server will read as many bytes as it
	935	can from the file (up to `len'), and return them in a SSH_FXP_DATA
	936	message. If an error occurs or EOF is encountered before reading any
	937	data, the server will respond with SSH_FXP_STATUS. For normal disk
	938	files, it is guaranteed that this will read the specified number of
	939	bytes, or up to end of file. For e.g. device files this may return
	940	fewer bytes than requested.
	941
	942	Writing to a file is achieved using the SSH_FXP_WRITE message, which
	943	has the following format:
	944
	945
	946
	947
	948
	949
	950
	951	Galbraith, et al. Expires April 16, 2003 [Page 17]
	952
	953	Internet-Draft SSH File Transfer Protocol October 2002
	954
	955
	956	uint32 id
	957	string handle
	958	uint64 offset
	959	string data
	960
	961	where `id' is a request identifier, `handle' is a file handle
	962	returned by SSH_FXP_OPEN, `offset' is the offset (in bytes) from the
	963	beginning of the file where to start writing, and `data' is the data
	964	to be written.
	965
	966	The write will extend the file if writing beyond the end of the file.
	967	It is legal to write way beyond the end of the file; the semantics
	968	are to write zeroes from the end of the file to the specified offset
	969	and then the data. On most operating systems, such writes do not
	970	allocate disk space but instead leave "holes" in the file.
	971
	972	The server responds to a write request with a SSH_FXP_STATUS message.
	973
	974	6.5 Removing and Renaming Files
	975
	976	Files can be removed using the SSH_FXP_REMOVE message. It has the
	977	following format:
	978
	979	uint32 id
	980	string filename [UTF-8]
	981
	982	where `id' is the request identifier and `filename' is the name of
	983	the file to be removed. See Section ``File Names'' for more
	984	information. This request cannot be used to remove directories.
	985
	986	The server will respond to this request with a SSH_FXP_STATUS
	987	message.
	988
	989	Files (and directories) can be renamed using the SSH_FXP_RENAME
	990	message. Its data is as follows:
	991
	992	uint32 id
	993	string oldpath [UTF-8]
	994	string newpath [UTF-8]
	995
	996	where `id' is the request identifier, `oldpath' is the name of an
	997	existing file or directory, and `newpath' is the new name for the
	998	file or directory. It is an error if there already exists a file
	999	with the name specified by newpath. The server may also fail rename
	1000	requests in other situations, for example if `oldpath' and `newpath'
	1001	point to different file systems on the server.
	1002
	1003	The server will respond to this request with a SSH_FXP_STATUS
	1004
	1005
	1006
	1007	Galbraith, et al. Expires April 16, 2003 [Page 18]
	1008
	1009	Internet-Draft SSH File Transfer Protocol October 2002
	1010
	1011
	1012	message.
	1013
	1014	6.6 Creating and Deleting Directories
	1015
	1016	New directories can be created using the SSH_FXP_MKDIR request. It
	1017	has the following format:
	1018
	1019	uint32 id
	1020	string path [UTF-8]
	1021	ATTRS attrs
	1022
	1023	where `id' is the request identifier.
	1024
	1025	`path' specifies the directory to be created. See Section ``File
	1026	Names'' for more information on file names.
	1027
	1028	`attrs' specifies the attributes that should be applied to it upon
	1029	creation. Attributes are discussed in more detail in Section ``File
	1030	Attributes''.
	1031
	1032	The server will respond to this request with a SSH_FXP_STATUS
	1033	message. If a file or directory with the specified path already
	1034	exists, an error will be returned.
	1035
	1036	Directories can be removed using the SSH_FXP_RMDIR request, which has
	1037	the following format:
	1038
	1039	uint32 id
	1040	string path [UTF-8]
	1041
	1042	where `id' is the request identifier, and `path' specifies the
	1043	directory to be removed. See Section ``File Names'' for more
	1044	information on file names.
	1045
	1046	The server responds to this request with a SSH_FXP_STATUS message.
	1047	Errors may be returned from this operation for various reasons,
	1048	including, but not limited to, the path does not exist, the path does
	1049	not refer to a directory object, the directory is not empty, or the
	1050	user has insufficient access or permission to perform the requested
	1051	operation.
	1052
	1053	6.7 Scanning Directories
	1054
	1055	The files in a directory can be listed using the SSH_FXP_OPENDIR and
	1056	SSH_FXP_READDIR requests. Each SSH_FXP_READDIR request returns one
	1057	or more file names with full file attributes for each file. The
	1058	client should call SSH_FXP_READDIR repeatedly until it has found the
	1059	file it is looking for or until the server responds with a
	1060
	1061
	1062
	1063	Galbraith, et al. Expires April 16, 2003 [Page 19]
	1064
	1065	Internet-Draft SSH File Transfer Protocol October 2002
	1066
	1067
	1068	SSH_FXP_STATUS message indicating an error (normally SSH_FX_EOF if
	1069	there are no more files in the directory). The client should then
	1070	close the handle using the SSH_FXP_CLOSE request.
	1071
	1072	The SSH_FXP_OPENDIR opens a directory for reading. It has the
	1073	following format:
	1074
	1075	uint32 id
	1076	string path [UTF-8]
	1077
	1078	where `id' is the request identifier and `path' is the path name of
	1079	the directory to be listed (without any trailing slash). See Section
	1080	``File Names'' for more information on file names. This will return
	1081	an error if the path does not specify a directory or if the directory
	1082	is not readable. The server will respond to this request with either
	1083	a SSH_FXP_HANDLE or a SSH_FXP_STATUS message.
	1084
	1085	Once the directory has been successfully opened, files (and
	1086	directories) contained in it can be listed using SSH_FXP_READDIR
	1087	requests. These are of the format
	1088
	1089	uint32 id
	1090	string handle
	1091
	1092	where `id' is the request identifier, and `handle' is a handle
	1093	returned by SSH_FXP_OPENDIR. (It is a protocol error to attempt to
	1094	use an ordinary file handle returned by SSH_FXP_OPEN.)
	1095
	1096	The server responds to this request with either a SSH_FXP_NAME or a
	1097	SSH_FXP_STATUS message. One or more names may be returned at a time.
	1098	Full status information is returned for each name in order to speed
	1099	up typical directory listings.
	1100
	1101	If there are no more names available to be read, the server MUST
	1102	respond with a SSH_FXP_STATUS message with error code of SSH_FX_EOF.
	1103
	1104	When the client no longer wishes to read more names from the
	1105	directory, it SHOULD call SSH_FXP_CLOSE for the handle. The handle
	1106	should be closed regardless of whether an error has occurred or not.
	1107
	1108	6.8 Retrieving File Attributes
	1109
	1110	Very often, file attributes are automatically returned by
	1111	SSH_FXP_READDIR. However, sometimes there is need to specifically
	1112	retrieve the attributes for a named file. This can be done using the
	1113	SSH_FXP_STAT, SSH_FXP_LSTAT and SSH_FXP_FSTAT requests.
	1114
	1115	SSH_FXP_STAT and SSH_FXP_LSTAT only differ in that SSH_FXP_STAT
	1116
	1117
	1118
	1119	Galbraith, et al. Expires April 16, 2003 [Page 20]
	1120
	1121	Internet-Draft SSH File Transfer Protocol October 2002
	1122
	1123
	1124	follows symbolic links on the server, whereas SSH_FXP_LSTAT does not
	1125	follow symbolic links. Both have the same format:
	1126
	1127	uint32 id
	1128	string path [UTF-8]
	1129	uint32 flags
	1130
	1131	where `id' is the request identifier, and `path' specifies the file
	1132	system object for which status is to be returned. The server
	1133	responds to this request with either SSH_FXP_ATTRS or SSH_FXP_STATUS.
	1134
	1135	The flags field specify the attribute flags in which the client has
	1136	particular interest. This is a hint to the server. For example,
	1137	because retrieving owner / group and acl information can be an
	1138	expensive operation under some operating systems, the server may
	1139	choose not to retrieve this information unless the client expresses a
	1140	specific interest in it.
	1141
	1142	The client has no guarantee the server will provide all the fields
	1143	that it has expressed an interest in.
	1144
	1145	SSH_FXP_FSTAT differs from the others in that it returns status
	1146	information for an open file (identified by the file handle). Its
	1147	format is as follows:
	1148
	1149	uint32 id
	1150	string handle
	1151	uint32 flags
	1152
	1153	where `id' is the request identifier and `handle' is a file handle
	1154	returned by SSH_FXP_OPEN. The server responds to this request with
	1155	SSH_FXP_ATTRS or SSH_FXP_STATUS.
	1156
	1157	6.9 Setting File Attributes
	1158
	1159	File attributes may be modified using the SSH_FXP_SETSTAT and
	1160	SSH_FXP_FSETSTAT requests. These requests are used for operations
	1161	such as changing the ownership, permissions or access times, as well
	1162	as for truncating a file.
	1163
	1164	The SSH_FXP_SETSTAT request is of the following format:
	1165
	1166	uint32 id
	1167	string path [UTF-8]
	1168	ATTRS attrs
	1169
	1170	where `id' is the request identifier, `path' specifies the file
	1171	system object (e.g. file or directory) whose attributes are to be
	1172
	1173
	1174
	1175	Galbraith, et al. Expires April 16, 2003 [Page 21]
	1176
	1177	Internet-Draft SSH File Transfer Protocol October 2002
	1178
	1179
	1180	modified, and `attrs' specifies the modifications to be made to its
	1181	attributes. Attributes are discussed in more detail in Section
	1182	``File Attributes''.
	1183
	1184	An error will be returned if the specified file system object does
	1185	not exist or the user does not have sufficient rights to modify the
	1186	specified attributes. The server responds to this request with a
	1187	SSH_FXP_STATUS message.
	1188
	1189	The SSH_FXP_FSETSTAT request modifies the attributes of a file which
	1190	is already open. It has the following format:
	1191
	1192	uint32 id
	1193	string handle
	1194	ATTRS attrs
	1195
	1196	where `id' is the request identifier, `handle' (MUST be returned by
	1197	SSH_FXP_OPEN) identifies the file whose attributes are to be
	1198	modified, and `attrs' specifies the modifications to be made to its
	1199	attributes. Attributes are discussed in more detail in Section
	1200	``File Attributes''. The server will respond to this request with
	1201	SSH_FXP_STATUS.
	1202
	1203	6.10 Dealing with Symbolic links
	1204
	1205	The SSH_FXP_READLINK request may be used to read the target of a
	1206	symbolic link. It would have a data part as follows:
	1207
	1208	uint32 id
	1209	string path [UTF-8]
	1210
	1211	where `id' is the request identifier and `path' specifies the path
	1212	name of the symlink to be read.
	1213
	1214	The server will respond with a SSH_FXP_NAME packet containing only
	1215	one name and a dummy attributes value. The name in the returned
	1216	packet contains the target of the link. If an error occurs, the
	1217	server may respond with SSH_FXP_STATUS.
	1218
	1219	The SSH_FXP_SYMLINK request will create a symbolic link on the
	1220	server. It is of the following format
	1221
	1222	uint32 id
	1223	string linkpath [UTF-8]
	1224	string targetpath [UTF-8]
	1225
	1226	where `id' is the request identifier, `linkpath' specifies the path
	1227	name of the symlink to be created and `targetpath' specifies the
	1228
	1229
	1230
	1231	Galbraith, et al. Expires April 16, 2003 [Page 22]
	1232
	1233	Internet-Draft SSH File Transfer Protocol October 2002
	1234
	1235
	1236	target of the symlink. The server shall respond with a
	1237	SSH_FXP_STATUS indicating either success (SSH_FX_OK) or an error
	1238	condition.
	1239
	1240	6.11 Canonicalizing the Server-Side Path Name
	1241
	1242	The SSH_FXP_REALPATH request can be used to have the server
	1243	canonicalize any given path name to an absolute path. This is useful
	1244	for converting path names containing ".." components or relative
	1245	pathnames without a leading slash into absolute paths. The format of
	1246	the request is as follows:
	1247
	1248	uint32 id
	1249	string path [UTF-8]
	1250
	1251	where `id' is the request identifier and `path' specifies the path
	1252	name to be canonicalized. The server will respond with a
	1253	SSH_FXP_NAME packet containing the name in canonical form and a dummy
	1254	attributes value. If an error occurs, the server may also respond
	1255	with SSH_FXP_STATUS.
	1256
	1257	6.11.1 Best practice for dealing with paths
	1258
	1259	The client SHOULD treat the results of SSH_FXP_REALPATH as a
	1260	canonical absolute path, even if the path does not appear to be
	1261	absolute. A client that use REALPATH(".") and treats the result as
	1262	absolute, even if there is no leading slash, will continue to
	1263	function correctly, even when talking to a Windows NT or VMS style
	1264	system, where absolute paths may not begin with a slash.
	1265
	1266	For example, if the client wishes to change directory up, and the
	1267	server has returned "c:/x/y/z" from REALPATH, the client SHOULD use
	1268	"c:/x/y/z/..".
	1269
	1270	As a second example, if the client wishes to open the file "x.txt" in
	1271	the current directory, and server has returned "dka100:/x/y/z" as the
	1272	canonical path of the directory, the client SHOULD open "dka100:/x/y/
	1273	z/x.txt"
	1274
	1275
	1276
	1277
	1278
	1279
	1280
	1281
	1282
	1283
	1284
	1285
	1286
	1287	Galbraith, et al. Expires April 16, 2003 [Page 23]
	1288
	1289	Internet-Draft SSH File Transfer Protocol October 2002
	1290
	1291
	1292	7. Responses from the Server to the Client
	1293
	1294	The server responds to the client using one of a few response
	1295	packets. All requests can return a SSH_FXP_STATUS response upon
	1296	failure. When the operation is successful, any of the responses may
	1297	be returned (depending on the operation). If no data needs to be
	1298	returned to the client, the SSH_FXP_STATUS response with SSH_FX_OK
	1299	status is appropriate. Otherwise, the SSH_FXP_HANDLE message is used
	1300	to return a file handle (for SSH_FXP_OPEN and SSH_FXP_OPENDIR
	1301	requests), SSH_FXP_DATA is used to return data from SSH_FXP_READ,
	1302	SSH_FXP_NAME is used to return one or more file names from a
	1303	SSH_FXP_READDIR or SSH_FXP_REALPATH request, and SSH_FXP_ATTRS is
	1304	used to return file attributes from SSH_FXP_STAT, SSH_FXP_LSTAT, and
	1305	SSH_FXP_FSTAT requests.
	1306
	1307	Exactly one response will be returned for each request. Each
	1308	response packet contains a request identifier which can be used to
	1309	match each response with the corresponding request. Note that it is
	1310	legal to have several requests outstanding simultaneously, and the
	1311	server is allowed to send responses to them in a different order from
	1312	the order in which the requests were sent (the result of their
	1313	execution, however, is guaranteed to be as if they had been processed
	1314	one at a time in the order in which the requests were sent).
	1315
	1316	Response packets are of the same general format as request packets.
	1317	Each response packet begins with the request identifier.
	1318
	1319	The format of the data portion of the SSH_FXP_STATUS response is as
	1320	follows:
	1321
	1322	uint32 id
	1323	uint32 error/status code
	1324	string error message (ISO-10646 UTF-8 [RFC-2279])
	1325	string language tag (as defined in [RFC-1766])
	1326
	1327	where `id' is the request identifier, and `error/status code'
	1328	indicates the result of the requested operation. The value SSH_FX_OK
	1329	indicates success, and all other values indicate failure.
	1330
	1331	Currently, the following values are defined (other values may be
	1332	defined by future versions of this protocol):
	1333
	1334
	1335
	1336
	1337
	1338
	1339
	1340
	1341
	1342
	1343	Galbraith, et al. Expires April 16, 2003 [Page 24]
	1344
	1345	Internet-Draft SSH File Transfer Protocol October 2002
	1346
	1347
	1348	#define SSH_FX_OK 0
	1349	#define SSH_FX_EOF 1
	1350	#define SSH_FX_NO_SUCH_FILE 2
	1351	#define SSH_FX_PERMISSION_DENIED 3
	1352	#define SSH_FX_FAILURE 4
	1353	#define SSH_FX_BAD_MESSAGE 5
	1354	#define SSH_FX_NO_CONNECTION 6
	1355	#define SSH_FX_CONNECTION_LOST 7
	1356	#define SSH_FX_OP_UNSUPPORTED 8
	1357	#define SSH_FX_INVALID_HANDLE 9
	1358	#define SSH_FX_NO_SUCH_PATH 10
	1359	#define SSH_FX_FILE_ALREADY_EXISTS 11
	1360	#define SSH_FX_WRITE_PROTECT 12
	1361
	1362	SSH_FX_OK
	1363	Indicates successful completion of the operation.
	1364
	1365	SSH_FX_EOF
	1366	indicates end-of-file condition; for SSH_FX_READ it means that no
	1367	more data is available in the file, and for SSH_FX_READDIR it
	1368	indicates that no more files are contained in the directory.
	1369
	1370	SSH_FX_NO_SUCH_FILE
	1371	is returned when a reference is made to a file which does not
	1372	exist.
	1373
	1374	SSH_FX_PERMISSION_DENIED
	1375	is returned when the authenticated user does not have sufficient
	1376	permissions to perform the operation.
	1377
	1378	SSH_FX_FAILURE
	1379	is a generic catch-all error message; it should be returned if an
	1380	error occurs for which there is no more specific error code
	1381	defined.
	1382
	1383	SSH_FX_BAD_MESSAGE
	1384	may be returned if a badly formatted packet or protocol
	1385	incompatibility is detected.
	1386
	1387	SSH_FX_NO_CONNECTION
	1388	is a pseudo-error which indicates that the client has no
	1389	connection to the server (it can only be generated locally by the
	1390	client, and MUST NOT be returned by servers).
	1391
	1392	SSH_FX_CONNECTION_LOST
	1393	is a pseudo-error which indicates that the connection to the
	1394	server has been lost (it can only be generated locally by the
	1395	client, and MUST NOT be returned by servers).
	1396
	1397
	1398
	1399	Galbraith, et al. Expires April 16, 2003 [Page 25]
	1400
	1401	Internet-Draft SSH File Transfer Protocol October 2002
	1402
	1403
	1404	SSH_FX_OP_UNSUPPORTED
	1405	indicates that an attempt was made to perform an operation which
	1406	is not supported for the server (it may be generated locally by
	1407	the client if e.g. the version number exchange indicates that a
	1408	required feature is not supported by the server, or it may be
	1409	returned by the server if the server does not implement an
	1410	operation).
	1411
	1412	SSH_FX_INVALID_HANDLE
	1413	The handle value was invalid.
	1414
	1415	SSH_FX_NO_SUCH_PATH
	1416	The file path does not exist or is invalid.
	1417
	1418	SSH_FX_FILE_ALREADY_EXISTS
	1419	The file already exists.
	1420
	1421	SSH_FX_WRITE_PROTECT
	1422	The file is on read only media, or the media is write protected.
	1423
	1424	The SSH_FXP_HANDLE response has the following format:
	1425
	1426	uint32 id
	1427	string handle
	1428
	1429	where `id' is the request identifier, and `handle' is an arbitrary
	1430	string that identifies an open file or directory on the server. The
	1431	handle is opaque to the client; the client MUST NOT attempt to
	1432	interpret or modify it in any way. The length of the handle string
	1433	MUST NOT exceed 256 data bytes.
	1434
	1435	The SSH_FXP_DATA response has the following format:
	1436
	1437	uint32 id
	1438	string data
	1439
	1440	where `id' is the request identifier, and `data' is an arbitrary byte
	1441	string containing the requested data. The data string may be at most
	1442	the number of bytes requested in a SSH_FXP_READ request, but may also
	1443	be shorter if end of file is reached or if the read is from something
	1444	other than a regular file.
	1445
	1446	The SSH_FXP_NAME response has the following format:
	1447
	1448
	1449
	1450
	1451
	1452
	1453
	1454
	1455	Galbraith, et al. Expires April 16, 2003 [Page 26]
	1456
	1457	Internet-Draft SSH File Transfer Protocol October 2002
	1458
	1459
	1460	uint32 id
	1461	uint32 count
	1462	repeats count times:
	1463	string filename [UTF-8]
	1464	ATTRS attrs
	1465
	1466	where `id' is the request identifier, `count' is the number of names
	1467	returned in this response, and the remaining fields repeat `count'
	1468	times (so that all three fields are first included for the first
	1469	file, then for the second file, etc). In the repeated part,
	1470	`filename' is a file name being returned (for SSH_FXP_READDIR, it
	1471	will be a relative name within the directory, without any path
	1472	components; for SSH_FXP_REALPATH it will be an absolute path name),
	1473	and `attrs' is the attributes of the file as described in Section
	1474	``File Attributes''.
	1475
	1476	The SSH_FXP_ATTRS response has the following format:
	1477
	1478	uint32 id
	1479	ATTRS attrs
	1480
	1481	where `id' is the request identifier, and `attrs' is the returned
	1482	file attributes as described in Section ``File Attributes''.
	1483
	1484
	1485
	1486
	1487
	1488
	1489
	1490
	1491
	1492
	1493
	1494
	1495
	1496
	1497
	1498
	1499
	1500
	1501
	1502
	1503
	1504
	1505
	1506
	1507
	1508
	1509
	1510
	1511	Galbraith, et al. Expires April 16, 2003 [Page 27]
	1512
	1513	Internet-Draft SSH File Transfer Protocol October 2002
	1514
	1515
	1516	8. Vendor-Specific Extensions
	1517
	1518	The SSH_FXP_EXTENDED request provides a generic extension mechanism
	1519	for adding vendor-specific commands. The request has the following
	1520	format:
	1521
	1522	uint32 id
	1523	string extended-request
	1524	... any request-specific data ...
	1525
	1526	where `id' is the request identifier, and `extended-request' is a
	1527	string of the format "name@domain", where domain is an internet
	1528	domain name of the vendor defining the request. The rest of the
	1529	request is completely vendor-specific, and servers should only
	1530	attempt to interpret it if they recognize the `extended-request'
	1531	name.
	1532
	1533	The server may respond to such requests using any of the response
	1534	packets defined in Section ``Responses from the Server to the
	1535	Client''. Additionally, the server may also respond with a
	1536	SSH_FXP_EXTENDED_REPLY packet, as defined below. If the server does
	1537	not recognize the `extended-request' name, then the server MUST
	1538	respond with SSH_FXP_STATUS with error/status set to
	1539	SSH_FX_OP_UNSUPPORTED.
	1540
	1541	The SSH_FXP_EXTENDED_REPLY packet can be used to carry arbitrary
	1542	extension-specific data from the server to the client. It is of the
	1543	following format:
	1544
	1545	uint32 id
	1546	... any request-specific data ...
	1547
	1548	There is a range of packet types reserved for use by extensions. In
	1549	order to avoid collision, extensions that turn on the use of
	1550	additional packet types should determine those numbers dynamically.
	1551
	1552	The suggested way of doing this is have an extension request from the
	1553	client to the server that enables the extension; the extension
	1554	response from the server to the client would specify the actual type
	1555	values to use, in additional to any other data.
	1556
	1557	Extension authors should be mindful of the limited range of packet
	1558	types available (there are only 45 values available) and avoid
	1559	requiring a new packet type where possible.
	1560
	1561
	1562
	1563
	1564
	1565
	1566
	1567	Galbraith, et al. Expires April 16, 2003 [Page 28]
	1568
	1569	Internet-Draft SSH File Transfer Protocol October 2002
	1570
	1571
	1572	9. Security Considerations
	1573
	1574	This protocol assumes that it is run over a secure channel and that
	1575	the endpoints of the channel have been authenticated. Thus, this
	1576	protocol assumes that it is externally protected from network-level
	1577	attacks.
	1578
	1579	This protocol provides file system access to arbitrary files on the
	1580	server (only constrained by the server implementation). It is the
	1581	responsibility of the server implementation to enforce any access
	1582	controls that may be required to limit the access allowed for any
	1583	particular user (the user being authenticated externally to this
	1584	protocol, typically using the SSH User Authentication Protocol [8].
	1585
	1586	Care must be taken in the server implementation to check the validity
	1587	of received file handle strings. The server should not rely on them
	1588	directly; it MUST check the validity of each handle before relying on
	1589	it.
	1590
	1591
	1592
	1593
	1594
	1595
	1596
	1597
	1598
	1599
	1600
	1601
	1602
	1603
	1604
	1605
	1606
	1607
	1608
	1609
	1610
	1611
	1612
	1613
	1614
	1615
	1616
	1617
	1618
	1619
	1620
	1621
	1622
	1623	Galbraith, et al. Expires April 16, 2003 [Page 29]
	1624
	1625	Internet-Draft SSH File Transfer Protocol October 2002
	1626
	1627
	1628	10. Changes from previous protocol versions
	1629
	1630	The SSH File Transfer Protocol has changed over time, before it's
	1631	standardization. The following is a description of the incompatible
	1632	changes between different versions.
	1633
	1634	10.1 Changes between versions 4 and 3
	1635
	1636	Many of the changes between version 4 and version 3 are to the
	1637	attribute structure to make it more flexible for non-unix platforms.
	1638
	1639	o Make all filenames UTF-8.
	1640
	1641	o Added 'newline' extension.
	1642
	1643	o Made file attribute owner and group strings so they can actually
	1644	be used on disparate systems.
	1645
	1646	o Added createtime field, and added separate flags for atime,
	1647	createtime, and mtime so they can be set separately.
	1648
	1649	o Split the file type out of the permissions field and into it's own
	1650	field (which is always present.)
	1651
	1652	o Added acl attribute.
	1653
	1654	o Added SSH_FXF_TEXT file open flag.
	1655
	1656	o Added flags field to the get stat commands so that the client can
	1657	specifically request information the server might not normally
	1658	included for performance reasons.
	1659
	1660	o Removed the long filename from the names structure-- it can now be
	1661	built from information available in the attrs structure.
	1662
	1663	o Added reserved range of packet numbers for extensions.
	1664
	1665	o Added several additional error codes.
	1666
	1667	o Change the way version negotiate works slightly. Previously, if
	1668	the client version were higher than the server version, the server
	1669	was supposed to 'echo back' the clients version. The server now
	1670	sends it's own version and the lower of the two is considered to
	1671	be the one in use.
	1672
	1673
	1674
	1675
	1676
	1677
	1678
	1679	Galbraith, et al. Expires April 16, 2003 [Page 30]
	1680
	1681	Internet-Draft SSH File Transfer Protocol October 2002
	1682
	1683
	1684	10.2 Changes between versions 3 and 2
	1685
	1686	o The SSH_FXP_READLINK and SSH_FXP_SYMLINK messages were added.
	1687
	1688	o The SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY messages were
	1689	added.
	1690
	1691	o The SSH_FXP_STATUS message was changed to include fields `error
	1692	message' and `language tag'.
	1693
	1694
	1695	10.3 Changes between versions 2 and 1
	1696
	1697	o The SSH_FXP_RENAME message was added.
	1698
	1699
	1700	10.4 Changes between versions 1 and 0
	1701
	1702	o Implementation changes, no actual protocol changes.
	1703
	1704
	1705
	1706
	1707
	1708
	1709
	1710
	1711
	1712
	1713
	1714
	1715
	1716
	1717
	1718
	1719
	1720
	1721
	1722
	1723
	1724
	1725
	1726
	1727
	1728
	1729
	1730
	1731
	1732
	1733
	1734
	1735	Galbraith, et al. Expires April 16, 2003 [Page 31]
	1736
	1737	Internet-Draft SSH File Transfer Protocol October 2002
	1738
	1739
	1740	11. Trademark Issues
	1741
	1742	"ssh" is a registered trademark of SSH Communications Security Corp
	1743	in the United States and/or other countries.
	1744
	1745
	1746
	1747
	1748
	1749
	1750
	1751
	1752
	1753
	1754
	1755
	1756
	1757
	1758
	1759
	1760
	1761
	1762
	1763
	1764
	1765
	1766
	1767
	1768
	1769
	1770
	1771
	1772
	1773
	1774
	1775
	1776
	1777
	1778
	1779
	1780
	1781
	1782
	1783
	1784
	1785
	1786
	1787
	1788
	1789
	1790
	1791	Galbraith, et al. Expires April 16, 2003 [Page 32]
	1792
	1793	Internet-Draft SSH File Transfer Protocol October 2002
	1794
	1795
	1796	References
	1797
	1798	[1] Dierks, T., Allen, C., Treese, W., Karlton, P., Freier, A. and
	1799	P. Kocher, "The TLS Protocol Version 1.0", RFC 2246, January
	1800	1999.
	1801
	1802	[2] Alvestrand, H., "IETF Policy on Character Sets and Languages",
	1803	BCP 18, RFC 2277, January 1998.
	1804
	1805	[3] Shepler, S., Callaghan, B., Robinson, D., Thurlow, R., Beame,
	1806	C., Eisler, M. and D. Noveck, "NFS version 4 Protocol", RFC
	1807	3010, December 2000.
	1808
	1809	[4] Institute of Electrical and Electronics Engineers, "Information
	1810	Technology - Portable Operating System Interface (POSIX) - Part
	1811	1: System Application Program Interface (API) [C Language]",
	1812	IEEE Standard 1003.2, 1996.
	1813
	1814	[5] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S.
	1815	Lehtinen, "SSH Protocol Architecture", draft-ietf-secsh-
	1816	architecture-13 (work in progress), September 2002.
	1817
	1818	[6] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S.
	1819	Lehtinen, "SSH Protocol Transport Protocol", draft-ietf-secsh-
	1820	transport-15 (work in progress), September 2002.
	1821
	1822	[7] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S.
	1823	Lehtinen, "SSH Connection Protocol", draft-ietf-secsh-connect-16
	1824	(work in progress), September 2002.
	1825
	1826	[8] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S.
	1827	Lehtinen, "SSH Authentication Protocol", draft-ietf-secsh-
	1828	userauth-16 (work in progress), September 2002.
	1829
	1830
	1831	Authors' Addresses
	1832
	1833	Joseph Galbraith
	1834	VanDyke Software
	1835	4848 Tramway Ridge Blvd
	1836	Suite 101
	1837	Albuquerque, NM 87111
	1838	US
	1839
	1840	Phone: +1 505 332 5700
	1841	EMail: galb-list@vandyke.com
	1842
	1843
	1844
	1845
	1846
	1847	Galbraith, et al. Expires April 16, 2003 [Page 33]
	1848
	1849	Internet-Draft SSH File Transfer Protocol October 2002
	1850
	1851
	1852	Tatu Ylonen
	1853	SSH Communications Security Corp
	1854	Fredrikinkatu 42
	1855	HELSINKI FIN-00100
	1856	Finland
	1857
	1858	EMail: ylo@ssh.com
	1859
	1860
	1861	Sami Lehtinen
	1862	SSH Communications Security Corp
	1863	Fredrikinkatu 42
	1864	HELSINKI FIN-00100
	1865	Finland
	1866
	1867	EMail: sjl@ssh.com
	1868
	1869
	1870
	1871
	1872
	1873
	1874
	1875
	1876
	1877
	1878
	1879
	1880
	1881
	1882
	1883
	1884
	1885
	1886
	1887
	1888
	1889
	1890
	1891
	1892
	1893
	1894
	1895
	1896
	1897
	1898
	1899
	1900
	1901
	1902
	1903	Galbraith, et al. Expires April 16, 2003 [Page 34]
	1904
	1905	Internet-Draft SSH File Transfer Protocol October 2002
	1906
	1907
	1908	Full Copyright Statement
	1909
	1910	Copyright (C) The Internet Society (2002). All Rights Reserved.
	1911
	1912	This document and translations of it may be copied and furnished to
	1913	others, and derivative works that comment on or otherwise explain it
	1914	or assist in its implementation may be prepared, copied, published
	1915	and distributed, in whole or in part, without restriction of any
	1916	kind, provided that the above copyright notice and this paragraph are
	1917	included on all such copies and derivative works. However, this
	1918	document itself may not be modified in any way, such as by removing
	1919	the copyright notice or references to the Internet Society or other
	1920	Internet organizations, except as needed for the purpose of
	1921	developing Internet standards in which case the procedures for
	1922	copyrights defined in the Internet Standards process must be
	1923	followed, or as required to translate it into languages other than
	1924	English.
	1925
	1926	The limited permissions granted above are perpetual and will not be
	1927	revoked by the Internet Society or its successors or assigns.
	1928
	1929	This document and the information contained herein is provided on an
	1930	"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
	1931	TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
	1932	BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
	1933	HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
	1934	MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
	1935
	1936	Acknowledgement
	1937
	1938	Funding for the RFC Editor function is currently provided by the
	1939	Internet Society.
	1940
	1941
	1942
	1943
	1944
	1945
	1946
	1947
	1948
	1949
	1950
	1951
	1952
	1953
	1954
	1955
	1956
	1957
	1958
	1959	Galbraith, et al. Expires April 16, 2003 [Page 35]
	1960
	1961

+3306

-0

rfc/draft-ietf-secsh-filexfer-12.txt less more

	0
	1
	2
	3
	4	Secure Shell Working Group J. Galbraith
	5	Internet-Draft VanDyke Software
	6	Expires: July 29, 2006 O. Saarenmaa
	7	F-Secure
	8	January 25, 2006
	9
	10
	11	SSH File Transfer Protocol
	12	draft-ietf-secsh-filexfer-12.txt
	13
	14	Status of this Memo
	15
	16	By submitting this Internet-Draft, each author represents that any
	17	applicable patent or other IPR claims of which he or she is aware
	18	have been or will be disclosed, and any of which he or she becomes
	19	aware will be disclosed, in accordance with Section 6 of BCP 79.
	20
	21	Internet-Drafts are working documents of the Internet Engineering
	22	Task Force (IETF), its areas, and its working groups. Note that
	23	other groups may also distribute working documents as Internet-
	24	Drafts.
	25
	26	Internet-Drafts are draft documents valid for a maximum of six months
	27	and may be updated, replaced, or obsoleted by other documents at any
	28	time. It is inappropriate to use Internet-Drafts as reference
	29	material or to cite them other than as "work in progress."
	30
	31	The list of current Internet-Drafts can be accessed at
	32	http://www.ietf.org/ietf/1id-abstracts.txt.
	33
	34	The list of Internet-Draft Shadow Directories can be accessed at
	35	http://www.ietf.org/shadow.html.
	36
	37	This Internet-Draft will expire on July 29, 2006.
	38
	39	Copyright Notice
	40
	41	Copyright (C) The Internet Society (2006).
	42
	43	Abstract
	44
	45	The SSH File Transfer Protocol provides secure file transfer
	46	functionality over any reliable data stream. It is the standard file
	47	transfer protocol for use with the SSH2 protocol. This document
	48	describes the file transfer protocol and its interface to the SSH2
	49	protocol suite.
	50
	51
	52
	53
	54
	55	Galbraith & Saarenmaa Expires July 29, 2006 [Page 1]
	56
	57	Internet-Draft SSH File Transfer Protocol January 2006
	58
	59
	60	Table of Contents
	61
	62	1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
	63	2. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 4
	64	3. Use with the SSH Connection Protocol . . . . . . . . . . . . . 4
	65	3.1. The Use of 'stderr' in the server . . . . . . . . . . . . 5
	66	4. General Packet Format . . . . . . . . . . . . . . . . . . . . 5
	67	4.1. Request Synchronization and Reordering . . . . . . . . . . 6
	68	4.2. New data types defined by this document . . . . . . . . . 7
	69	4.3. Packet Types . . . . . . . . . . . . . . . . . . . . . . . 7
	70	5. Protocol Initialization . . . . . . . . . . . . . . . . . . . 9
	71	5.1. Client Initialization . . . . . . . . . . . . . . . . . . 9
	72	5.2. Server Initialization . . . . . . . . . . . . . . . . . . 9
	73	5.3. Determining Server Newline Convention . . . . . . . . . . 10
	74	5.4. Supported Features . . . . . . . . . . . . . . . . . . . . 10
	75	5.5. Version re-negotiation . . . . . . . . . . . . . . . . . . 13
	76	6. File Names . . . . . . . . . . . . . . . . . . . . . . . . . . 14
	77	7. File Attributes . . . . . . . . . . . . . . . . . . . . . . . 16
	78	7.1. valid-attribute-flags . . . . . . . . . . . . . . . . . . 17
	79	7.2. Type . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
	80	7.3. Size . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
	81	7.4. allocation-size . . . . . . . . . . . . . . . . . . . . . 19
	82	7.5. Owner and Group . . . . . . . . . . . . . . . . . . . . . 19
	83	7.6. Permissions . . . . . . . . . . . . . . . . . . . . . . . 20
	84	7.7. Times . . . . . . . . . . . . . . . . . . . . . . . . . . 20
	85	7.8. ACL . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
	86	7.9. attrib-bits and attrib-bits-valid . . . . . . . . . . . . 24
	87	7.10. text-hint . . . . . . . . . . . . . . . . . . . . . . . . 27
	88	7.11. mime-type . . . . . . . . . . . . . . . . . . . . . . . . 27
	89	7.12. link-count . . . . . . . . . . . . . . . . . . . . . . . . 27
	90	7.13. untranslated-name . . . . . . . . . . . . . . . . . . . . 28
	91	7.14. Extended Attributes . . . . . . . . . . . . . . . . . . . 28
	92	8. Requests From the Client to the Server . . . . . . . . . . . . 28
	93	8.1. Opening and Closing Files and Directories . . . . . . . . 28
	94	8.1.1. Opening a File . . . . . . . . . . . . . . . . . . . . 29
	95	8.1.2. Opening a Directory . . . . . . . . . . . . . . . . . 35
	96	8.1.3. Closing Handles . . . . . . . . . . . . . . . . . . . 35
	97	8.2. Reading and Writing . . . . . . . . . . . . . . . . . . . 36
	98	8.2.1. Reading Files . . . . . . . . . . . . . . . . . . . . 36
	99	8.2.2. Reading Directories . . . . . . . . . . . . . . . . . 37
	100	8.2.3. Writing Files . . . . . . . . . . . . . . . . . . . . 37
	101	8.3. Removing and Renaming Files . . . . . . . . . . . . . . . 38
	102	8.4. Creating and Deleting Directories . . . . . . . . . . . . 39
	103	8.5. Retrieving File Attributes . . . . . . . . . . . . . . . . 40
	104	8.6. Setting File Attributes . . . . . . . . . . . . . . . . . 41
	105	8.7. Dealing with Links . . . . . . . . . . . . . . . . . . . . 42
	106	8.8. Byte-range locks . . . . . . . . . . . . . . . . . . . . . 43
	107	8.9. Canonicalizing the Server-Side Path Name . . . . . . . . . 44
	108
	109
	110
	111	Galbraith & Saarenmaa Expires July 29, 2006 [Page 2]
	112
	113	Internet-Draft SSH File Transfer Protocol January 2006
	114
	115
	116	8.9.1. Best Practice for Dealing with Paths . . . . . . . . . 46
	117	9. Responses from the Server to the Client . . . . . . . . . . . 47
	118	9.1. Status Response . . . . . . . . . . . . . . . . . . . . . 47
	119	9.2. Handle Response . . . . . . . . . . . . . . . . . . . . . 51
	120	9.3. Data Response . . . . . . . . . . . . . . . . . . . . . . 52
	121	9.4. Name Response . . . . . . . . . . . . . . . . . . . . . . 52
	122	9.5. Attrs Response . . . . . . . . . . . . . . . . . . . . . . 53
	123	10. Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . 53
	124	11. Implementation Considerations . . . . . . . . . . . . . . . . 54
	125	12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 55
	126	13. Security Considerations . . . . . . . . . . . . . . . . . . . 55
	127	14. Changes from Previous Protocol Versions . . . . . . . . . . . 56
	128	15. References . . . . . . . . . . . . . . . . . . . . . . . . . . 56
	129	15.1. Normative References . . . . . . . . . . . . . . . . . . . 56
	130	15.2. Informative References . . . . . . . . . . . . . . . . . . 57
	131	Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 58
	132	Intellectual Property and Copyright Statements . . . . . . . . . . 59
	133
	134
	135
	136
	137
	138
	139
	140
	141
	142
	143
	144
	145
	146
	147
	148
	149
	150
	151
	152
	153
	154
	155
	156
	157
	158
	159
	160
	161
	162
	163
	164
	165
	166
	167	Galbraith & Saarenmaa Expires July 29, 2006 [Page 3]
	168
	169	Internet-Draft SSH File Transfer Protocol January 2006
	170
	171
	172	1. Introduction
	173
	174	This protocol provides secure file transfer (and more generally file
	175	system access.) It is designed so that it could be used to implement
	176	a secure remote file system service, as well as a secure file
	177	transfer service.
	178
	179	This protocol assumes that it runs over a secure channel, such as a
	180	channel in [RFC4251], and that the server has already authenticated
	181	the client, and that the identity of the client user is available to
	182	the protocol.
	183
	184	In general, this protocol follows a simple request-response model.
	185	Each request and response contains a sequence number and multiple
	186	requests may be pending simultaneously. There are a relatively large
	187	number of different request messages, but a small number of possible
	188	response messages. Each request has one or more response messages
	189	that may be returned in result (e.g., a read either returns data or
	190	reports error status).
	191
	192	The packet format descriptions in this specification follow the
	193	notation presented in [RFC4251].
	194
	195	Even though this protocol is described in the context of the SSH2
	196	protocol, this protocol is general and independent of the rest of the
	197	SSH2 protocol suite. It could be used in a number of different
	198	applications, such as secure file transfer over TLS [RFC2246] and
	199	transfer of management information in VPN applications.
	200
	201
	202	2. Acknowledgements
	203
	204	This document owes it's initial creation and protocol design to Tatu
	205	Ylonen and Sami Lehtinen of SSH Communications Security Corp.
	206
	207	We express our gratitude to them for their initial work on this
	208	protocol.
	209
	210
	211	3. Use with the SSH Connection Protocol
	212
	213	When used with the SSH2 Protocol suite, this protocol is intended to
	214	be used as a subsystem as described in [RFC4254] in the section
	215	"Starting a Shell or a Command". The subsystem name used with this
	216	protocol is "sftp".
	217
	218
	219
	220
	221
	222
	223	Galbraith & Saarenmaa Expires July 29, 2006 [Page 4]
	224
	225	Internet-Draft SSH File Transfer Protocol January 2006
	226
	227
	228	3.1. The Use of 'stderr' in the server
	229
	230	This protocol uses stdout and stdin to transmit binary protocol data.
	231	The "session" channel ([RFC4254]), which is used by the subsystem,
	232	also supports the use of stderr.
	233
	234	Data sent on stderr by the server SHOULD be considered free format
	235	debug or supplemental error information, and MAY be displayed to the
	236	user.
	237
	238	For example, during initialization, there is no client request
	239	active, so errors or warning information cannot be sent to the client
	240	as part of the SFTP protocol at this early stage. However, the
	241	errors or warnings MAY be sent as stderr text.
	242
	243
	244	4. General Packet Format
	245
	246	All packets transmitted over the secure connection are of the
	247	following format:
	248
	249	uint32 length
	250	byte type
	251	uint32 request-id
	252	... type specific fields ...
	253
	254	'length'
	255	The length of the entire packet, excluding the length field
	256	itself, such that, for example, for a packet type containing no
	257	type specific fields, the length field would be 5, and 9 bytes of
	258	data would be sent on the wire. (This is the packet format used
	259	in [RFC4253].)
	260
	261	All packet descriptions in this document omit the length field for
	262	brevity; the length field MUST be included in any case.
	263
	264	The maximum size of a packet is in practice determined by the
	265	client (the maximum size of read or write requests that it sends,
	266	plus a few bytes of packet overhead). All servers SHOULD support
	267	packets of at least 34000 bytes (where the packet size refers to
	268	the full length, including the header above). This should allow
	269	for reads and writes of at most 32768 bytes.
	270
	271	'type'
	272	The type code for the packet.
	273
	274
	275
	276
	277
	278
	279	Galbraith & Saarenmaa Expires July 29, 2006 [Page 5]
	280
	281	Internet-Draft SSH File Transfer Protocol January 2006
	282
	283
	284	'request-id'
	285	Each request from the client contains a 'request-id' field. Each
	286	response from the server includes that same 'request-id' from the
	287	request that the server is responding to. One possible
	288	implementation is for the client to us a monotonically increasing
	289	request sequence number (modulo 2^32). There is, however, no
	290	particular requirement the 'request-id' fields be unique.
	291
	292	There are two packets, INIT and VERSION, which do not use the
	293	request-id.
	294	Packet descriptions in this document will contain the 'request-id'
	295	field, but will not redefine it.
	296
	297
	298	Implementations MUST ignore excess data at the end of an otherwise
	299	valid packet. Implementations MUST respond to unrecognized packet
	300	types with an SSH_FX_OP_UNSUPPORTED error. This will allow the
	301	protocol to be extended in a backwards compatible way as needed.
	302
	303	Additionally, when a packet has two or more optional fields, and an
	304	implementation wishes to use the i-th optional field, all fields from
	305	1 to i MUST be present. In other words, only fields after the last
	306	field the implementation wishes to send are actually options.
	307
	308	There is no limit on the number of outstanding (non-acknowledged)
	309	requests that the client may send to the server. In practice this is
	310	limited by the buffering available on the data stream and the queuing
	311	performed by the server. If the server's queues are full, it should
	312	not read any more data from the stream, and flow control will prevent
	313	the client from sending more requests. Note, however, that while
	314	there is no restriction on the protocol level, the client's API may
	315	provide a limit in order to prevent infinite queuing of outgoing
	316	requests at the client.
	317
	318	4.1. Request Synchronization and Reordering
	319
	320	The protocol and implementations MUST process requests relating to
	321	the same file in the order in which they are received. In other
	322	words, if an application submits multiple requests to the server, the
	323	results in the responses will be the same as if it had sent the
	324	requests one at a time and waited for the response in each case. For
	325	example, the server may process non-overlapping read/write requests
	326	to the same file in parallel, but overlapping reads and writes cannot
	327	be reordered or parallelized. However, there are no ordering
	328	restrictions on the server for processing requests from two different
	329	file transfer connections. The server may interleave and parallelize
	330	them at will.
	331
	332
	333
	334
	335	Galbraith & Saarenmaa Expires July 29, 2006 [Page 6]
	336
	337	Internet-Draft SSH File Transfer Protocol January 2006
	338
	339
	340	There are no restrictions on the order in which responses to
	341	outstanding requests are delivered to the client, except that the
	342	server must ensure fairness in the sense that processing of no
	343	request will be indefinitely delayed even if the client is sending
	344	other requests so that there are multiple outstanding requests all
	345	the time.
	346
	347	A client MUST be prepared to receive responses to multiple overlapped
	348	requests out of order.
	349
	350	4.2. New data types defined by this document
	351
	352	This document defines these data types in addition to those defined
	353	in [RFC4251].
	354
	355	uint16
	356	Represents a 16-bit unsigned integer. Stored as 2 bytes in the
	357	order of decreasing significance (network byte order).
	358
	359	int64
	360	Represents a 64-bit signed integer. Stored using two's
	361	complement, as eight bytes in the order of decreasing significance
	362	(network byte order).
	363
	364	extension-pair
	365
	366	string extension-name
	367	string extension-data
	368
	369	'extension-name' is the name of a protocol extension. Extensions
	370	not defined by IETF CONSENSUS MUST follow the the DNS
	371	extensibility naming convention outlined in [RFC4251].
	372
	373	'extension-data' is any data specific to the extension, and MAY be
	374	zero length if the extension has no data.
	375
	376
	377	4.3. Packet Types
	378
	379	The following values are defined for packet types.
	380
	381
	382
	383
	384
	385
	386
	387
	388
	389
	390
	391	Galbraith & Saarenmaa Expires July 29, 2006 [Page 7]
	392
	393	Internet-Draft SSH File Transfer Protocol January 2006
	394
	395
	396	SSH_FXP_INIT 1
	397	SSH_FXP_VERSION 2
	398	SSH_FXP_OPEN 3
	399	SSH_FXP_CLOSE 4
	400	SSH_FXP_READ 5
	401	SSH_FXP_WRITE 6
	402	SSH_FXP_LSTAT 7
	403	SSH_FXP_FSTAT 8
	404	SSH_FXP_SETSTAT 9
	405	SSH_FXP_FSETSTAT 10
	406	SSH_FXP_OPENDIR 11
	407	SSH_FXP_READDIR 12
	408	SSH_FXP_REMOVE 13
	409	SSH_FXP_MKDIR 14
	410	SSH_FXP_RMDIR 15
	411	SSH_FXP_REALPATH 16
	412	SSH_FXP_STAT 17
	413	SSH_FXP_RENAME 18
	414	SSH_FXP_READLINK 19
	415	SSH_FXP_LINK 21
	416	SSH_FXP_BLOCK 22
	417	SSH_FXP_UNBLOCK 23
	418
	419	SSH_FXP_STATUS 101
	420	SSH_FXP_HANDLE 102
	421	SSH_FXP_DATA 103
	422	SSH_FXP_NAME 104
	423	SSH_FXP_ATTRS 105
	424
	425	SSH_FXP_EXTENDED 200
	426	SSH_FXP_EXTENDED_REPLY 201
	427
	428	SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY packets can be used to
	429	implement extensions, which can be vendor specific. See Section
	430	''Extensions'' for more details.
	431
	432	Values 210-255 are reserved for use in conjunction with these
	433	extensions. The SSH_FXP_EXTENDED packet can be used to negotiate the
	434	meaning of these reserved types. It is suggested that the actual
	435	value to be used also be negotiated, since this will prevent
	436	collision among multiple uncoordinated extensions.
	437
	438	The server MUST respond with SSH_FXP_STATUS(SSH_FX_OP_UNSUPPORTED) if
	439	it receives a packet it does not recognize.
	440
	441	The use of additional packet types in the non-extension range MUST be
	442	introduced through IETF consensus. New packet types to be sent from
	443	the client to the server MAY be introduced without changing the
	444
	445
	446
	447	Galbraith & Saarenmaa Expires July 29, 2006 [Page 8]
	448
	449	Internet-Draft SSH File Transfer Protocol January 2006
	450
	451
	452	protocol version (Section 5). Because the client has no way to
	453	respond to unrecognized packet types, new packet types to be sent
	454	from the server to the client the client MUST not used unless the
	455	protocol version is changed or the client has negotiated to received
	456	them. This negotiation MAY be explicit, through the use of
	457	extensions, or MAY be implicit, by the client itself using a packet
	458	type not defined above.
	459
	460
	461	5. Protocol Initialization
	462
	463	When the file transfer protocol starts, the client first sends a
	464	SSH_FXP_INIT (including its version number) packet to the server.
	465	The server responds with a SSH_FXP_VERSION packet, supplying the
	466	lowest of its own and the client's version number. Both parties
	467	should from then on adhere to that particular version of the
	468	protocol.
	469
	470	The version number of the protocol specified in this document is 6.
	471	The version number should be incremented for each incompatible
	472	revision of this protocol.
	473
	474	Note that these two packets DO NOT contain a request id. These are
	475	the only such packets in the protocol.
	476
	477	5.1. Client Initialization
	478
	479	The SSH_FXP_INIT packet (from client to server) has the following
	480	data:
	481
	482	uint32 version
	483
	484	'version' is the version number of the client. If the client wishes
	485	to interoperate with servers that support discontinuous version
	486	numbers it SHOULD send '3', and then use the 'version-select'
	487	extension (see below.) Otherwise, this value is '6' for this version
	488	of the protocol.
	489
	490	5.2. Server Initialization
	491
	492	The SSH_FXP_VERSION packet (from server to client) has the following
	493	data:
	494
	495	uint32 version
	496	extension-pair extensions[0..n]
	497
	498	'version' is the lower of the protocol version supported by the
	499	server and the version number received from the client.
	500
	501
	502
	503	Galbraith & Saarenmaa Expires July 29, 2006 [Page 9]
	504
	505	Internet-Draft SSH File Transfer Protocol January 2006
	506
	507
	508	'extensions' is 0 or more extension-pairs (Section 4.2).
	509	Implementations MUST silently ignore any extensions whose names they
	510	do not recognize.
	511
	512	5.3. Determining Server Newline Convention
	513
	514	In order to correctly process text files in a cross platform
	515	compatible way, newline sequences must be converted between client
	516	and server conventions.
	517
	518	The SSH_FXF_TEXT_MODE file open flag (Section 8.1.1) makes it
	519	possible to request that the server translate a file to a 'canonical'
	520	wire format. This format uses CRLF as the line separator.
	521
	522	Servers for systems using other conventions MUST translate to and
	523	from the canonical form.
	524
	525	However, to ease the burden of implementation on servers that use a
	526	single, simple, separator sequence the following extension allows the
	527	canonical format to be changed.
	528
	529	string "newline"
	530	string new-canonical-separator (usually CR or LF or CRLF)
	531
	532	All clients MUST support this extension.
	533
	534	When processing text files, clients SHOULD NOT translate any
	535	character or sequence that is not an exact match of the server's
	536	newline separator.
	537
	538	In particular, if the newline sequence being used is the canonical
	539	CRLF sequence, a lone CR or a lone LF SHOULD be written through
	540	without change.
	541
	542	5.4. Supported Features
	543
	544	The sftp protocol has grown to be very rich, and now supports a
	545	number of features that may not be available on all servers.
	546
	547	When a server receives a request for a feature it cannot support, it
	548	MUST return a SSH_FX_OP_UNSUPPORTED status code, unless otherwise
	549	specified. The following extension facilitates clients being able to
	550	use the maximum available feature set, and yet not be overly burdened
	551	by dealing with SSH_FX_OP_UNSUPPORTED status codes. All servers MUST
	552	include as part of their version packet.
	553
	554
	555
	556
	557
	558
	559	Galbraith & Saarenmaa Expires July 29, 2006 [Page 10]
	560
	561	Internet-Draft SSH File Transfer Protocol January 2006
	562
	563
	564	string "supported2"
	565	string supported-structure
	566	uint32 supported-attribute-mask
	567	uint32 supported-attribute-bits
	568	uint32 supported-open-flags
	569	uint32 supported-access-mask
	570	uint32 max-read-size
	571	uint16 supported-open-block-vector
	572	uint16 supported-block-vector
	573	uint32 attrib-extension-count
	574	string attrib-extension-names[attrib_extension-count]
	575	uint32 extension-count
	576	string extension-names[extension-count]
	577
	578	Note that the name "supported2" is used here to avoid conflict with
	579	the slightly different "supported" extension that was previously
	580	used.
	581	supported-attribute-mask
	582	This mask MAY by applied to the 'File Attributes' valid-attribute-
	583	flags field (Section 7.1) to ensure that no unsupported attributes
	584	are present during a operation which writes attributes.
	585
	586	supported-attribute-bits
	587	This mask MAY by applied to the 'File Attributes' attrib-bits
	588	field (Section 7.9) to ensure that no unsupported attrib-bits are
	589	present during a operation which writes attributes.
	590
	591	supported-open-flags
	592	The supported-open-flags mask MAY be applied to the SSH_FXP_OPEN
	593	(Section 8.1.1) flags field.
	594
	595	supported-access-mask
	596	This mask may be applied to the ace-mask field of an ACL.
	597
	598	This mask SHOULD NOT be applied to the desired-access field of the
	599	SSH_FXP_OPEN (Section 8.1.1) request. Doing so will simply result
	600	in not requesting the access required by the client. In this
	601	case, the server is responsible for translating the clients
	602	requested access to a mode it supports that is sufficient to grant
	603	all access requested by the client.
	604
	605	max-read-size
	606	This is the maximum read size that the server guarantees to
	607	complete. For example, certain embedded server implementations
	608	complete only the first 4K of a read, even if there is additional
	609	data to be read from the file.
	610
	611
	612
	613
	614
	615	Galbraith & Saarenmaa Expires July 29, 2006 [Page 11]
	616
	617	Internet-Draft SSH File Transfer Protocol January 2006
	618
	619
	620	If the server specifies a non-zero value for max-read-size, it
	621	MUST return the requested number of bytes for reads that are less
	622	than or equal to the value, unless it encounters EOF or an ERROR.
	623
	624	The server MAY use this value to express that it is willing to
	625	handle very large read requests, in excess of the standard 34000
	626	bytes specified in Section 4.
	627
	628	supported-open-block-vector
	629	supported-block-vector
	630	16-bit masks specifying which combinations of blocking flags are
	631	supported. Each bit corresponds to one combination of the
	632	SSH_FXF_BLOCK_READ, SSH_FXF_BLOCK_WRITE, SSH_FXF_BLOCK_DELETE, and
	633	SSH_FXF_BLOCK_ADVISORY bits from Section 7.1.1.3, with a set bit
	634	corresponding to a supported combination and a clear bit an
	635	unsupported combination. The index of a bit, bit zero being the
	636	least significant bit, viewed as a four-bit number, corresponds to
	637	a combination of flag bits, shifted right so that BLOCK_READ is
	638	the least significant bit. The combination `no blocking flags'
	639	MUST be supported, so the low bit will always be set.
	640
	641	For example, a server supporting only the classic advisory read
	642	(shared) and write (exclusive) locks would set the bits
	643	corresponding to READ+WRITE+ADVISORY, 0b1011, and WRITE+ADVISORY,
	644	0b1010, plus the always-set bit 0b0000, giving a mask value of
	645	0b0000110000000001, or 0x0c01; a server supporting no locking at
	646	all would set only bit zero, giving 0x0001.
	647
	648	'supported-open-block-masks' applies to the SSH_FXP_OPEN
	649	(Section 8.1.1) flags field. 'supported-block-masks' applies to
	650	the SSH_FXF_BLOCK request.
	651
	652	attrib-extension-count
	653	Count of extension names in the attrib-extension-names array.
	654
	655	attrib-extension-names
	656	Names of extensions that can be used in an ATTRS (Section 7.14)
	657	structure.
	658
	659	extension-count
	660	Count of extension names in the extension-names array.
	661
	662	extension-names
	663	Names of extensions that can be used with the SSH_FXP_EXTEND
	664	(Section 10) packet.
	665
	666
	667	Naturally, if a given attribute field, attribute mask bit, open flag,
	668
	669
	670
	671	Galbraith & Saarenmaa Expires July 29, 2006 [Page 12]
	672
	673	Internet-Draft SSH File Transfer Protocol January 2006
	674
	675
	676	or extension is required for correct operation, the client MUST
	677	either not allow the bit to be masked off, or MUST fail the operation
	678	gracefully without sending the request to the server.
	679
	680	The client MAY send requests that are not supported by the server;
	681	however, it is not normally expected to be productive to do so. The
	682	client SHOULD apply the mask even to attrib structures received from
	683	the server. The server MAY include attributes or attrib-bits that
	684	are not included in the mask. Such attributes or attrib-bits are
	685	effectively read-only.
	686
	687	The supported capabilities of the acl attribute are sent using the
	688	following extension.
	689
	690	string "acl-supported"
	691	string supported-structure
	692	uint32 capabilities
	693
	694	'capabilities' is a combination of the following bits:
	695
	696	SSH_ACL_CAP_ALLOW 0x00000001
	697	SSH_ACL_CAP_DENY 0x00000002
	698	SSH_ACL_CAP_AUDIT 0x00000004
	699	SSH_ACL_CAP_ALARM 0x00000008
	700	SSH_ACL_CAP_INHERIT_ACCESS 0x00000010
	701	SSH_ACL_CAP_INHERIT_AUDIT_ALARM 0x00000020
	702
	703	SSH_ACL_CAP_ALLOW
	704	SSH_ACL_CAP_DENY
	705	SSH_ACL_CAP_AUDIT
	706	SSH_ACL_CAP_ALARM
	707	The server supports the associated ACL ACE type.
	708
	709	SSH_ACL_CAP_INHERIT_ACCESS
	710	The server can control whether a ACL will inherit DENY and ALLOW
	711	ACEs that are marked inheritable from it's parent object.
	712
	713	SSH_ACL_CAP_INHERIT_AUDIT_ALARM
	714	The server can control whether a ACL will inherit AUDIT or ALARM
	715	ACEs that are marked inheritable from it's parent object.
	716
	717
	718	5.5. Version re-negotiation
	719
	720	If the server supports other versions than what was negotiated, it
	721	may wish to send the 'versions' extension to inform the client of
	722	this fact. The client may then optionally choose to use one of the
	723	other versions supported.
	724
	725
	726
	727	Galbraith & Saarenmaa Expires July 29, 2006 [Page 13]
	728
	729	Internet-Draft SSH File Transfer Protocol January 2006
	730
	731
	732	string "versions"
	733	string comma-separated-versions
	734
	735	'comma-separated-versions' is a string of comma separated version
	736	numbers. Defined versions are: "2", "3", "4", "5", "6". Any other
	737	version advertised by the server must follow the DNS extensibility
	738	naming convention outlined in [RFC4251].
	739
	740	For example: "2,3,6,private@example.com".
	741
	742	If the client and server have negotiated a a version greater than or
	743	equal to version '3' (the version at which SSH_FXP_EXTENDED was
	744	introduced) in the initial VERSION/INIT exchange, the client may
	745	select a new version to use from the list the server provided using
	746	the following SSH_FXP_EXTENDED request.
	747
	748	string "version-select"
	749	string version-from-list
	750
	751	If the 'version-from-list' is one of the versions on the servers
	752	list, the server MUST respond with SSH_FX_OK. If the server did not
	753	send the "versions" extension, or the version-from-list was not
	754	included, the server MAY send a status response describing the
	755	failure, but MUST then close the channel without processing any
	756	further requests.
	757
	758	The 'version-select' MUST be the first request from the client to the
	759	server; if it is not, the server MUST fail the request and close the
	760	channel.
	761
	762	Although this request does take a full round trip, no client need
	763	wait for the response before continuing, because any valid request
	764	MUST succeed, and any invalid request results in a channel close.
	765	Since the request is the first request, it is not possible for the
	766	server to have already sent responses conforming to the old version.
	767
	768	Typically, the client SHOULD NOT down-grade the protocol version
	769	using this extension; however, it is not forbidden to do so. One
	770	reason a client might do so is to work around a buggy implementation.
	771
	772
	773	6. File Names
	774
	775	This protocol represents file names as strings. File names are
	776	assumed to use the slash ('/') character as a directory separator.
	777
	778	File names starting with a slash are "absolute", and are relative to
	779	the root of the file system. Names starting with any other character
	780
	781
	782
	783	Galbraith & Saarenmaa Expires July 29, 2006 [Page 14]
	784
	785	Internet-Draft SSH File Transfer Protocol January 2006
	786
	787
	788	are relative to the user's default directory (home directory). Note
	789	that identifying the user is assumed to take place outside of this
	790	protocol.
	791
	792	Servers SHOULD interpret a path name component ".." (Section 13) as
	793	referring to the parent directory, and "." as referring to the
	794	current directory.
	795
	796	An empty path name is valid, and it refers to the user's default
	797	directory (usually the user's home directory).
	798
	799	Otherwise, no syntax is defined for file names by this specification.
	800	Clients should not make any other assumptions; however, they can
	801	splice path name components returned by SSH_FXP_READDIR together
	802	using a slash ('/') as the separator, and that will work as expected.
	803
	804	It is understood that the lack of well-defined semantics for file
	805	names may cause interoperability problems between clients and servers
	806	using radically different operating systems. However, this approach
	807	is known to work acceptably with most systems, and alternative
	808	approaches that e.g. treat file names as sequences of structured
	809	components are quite complicated.
	810
	811	The preferred encoding for filenames is UTF-8. This is consistent
	812	with IETF Policy on Character Sets and Languages [RFC2277] and it is
	813	further supposed that the server is more likely to support any local
	814	character set and be able to convert it to UTF-8.
	815
	816	However, because the server does not always know the encoding of
	817	filenames, it is not always possible for the server to preform a
	818	valid translation to UTF-8. When an invalid translation to UTF-8 is
	819	preformed, it becomes impossible to manipulate the file, because the
	820	translation is not reversible. Therefore, the following extensions
	821	are provided in order to make it possible for the server to
	822	communicate it's abilities to the client, and to allow the client to
	823	control whether the server attempts the conversion.
	824
	825	A server MAY include the following extension with it's version
	826	packet.
	827
	828	string "filename-charset"
	829	string charset-name
	830
	831	A server that can always provide a valid UTF-8 translation for
	832	filenames SHOULD NOT send this extension. Otherwise, the server
	833	SHOULD send this extension and include the encoding most likely to be
	834	used for filenames. This value will most likely be derived from the
	835	LC_CTYPE on most unix-like systems.
	836
	837
	838
	839	Galbraith & Saarenmaa Expires July 29, 2006 [Page 15]
	840
	841	Internet-Draft SSH File Transfer Protocol January 2006
	842
	843
	844	A server that does not send this extension MUST send all filenames
	845	encoded in UTF-8. All clients MUST support UTF-8 filenames.
	846
	847	If the server included the 'filename-charset' extension with its
	848	VERSION packet, a client MAY send the following extension to turn off
	849	server translation to UTF-8.
	850
	851	string "filename-translation-control"
	852	bool do-translate
	853
	854	If the client does not send this extension, the server MUST continue
	855	to attempt translation to UTF-8. When a client sends this extension,
	856	the server MUST enable filename translation if 'do-translate' is
	857	true, or disable filename translation if it is false.
	858
	859	The server MUST respond with a STATUS response; if the server sent a
	860	'filename-charset' extension, the status MUST be SUCCESS. Otherwise,
	861	the status MUST be SSH_FX_OP_UNSUPPORTED.
	862
	863	When UTF-8 is sent, the shortest valid UTF-8 encoding of the UNICODE
	864	data MUST be used. The server is responsible for converting the
	865	UNICODE data to whatever canonical form it requires. For example, if
	866	the server requires that precomposed characters always be used, the
	867	server MUST NOT assume the filename as sent by the client has this
	868	attribute, but must do this normalization itself.
	869
	870
	871	7. File Attributes
	872
	873	A new compound data type, 'ATTRS', is defined for encoding file
	874	attributes. The same encoding is used both when returning file
	875	attributes from the server and when sending file attributes to the
	876	server.
	877
	878
	879
	880
	881
	882
	883
	884
	885
	886
	887
	888
	889
	890
	891
	892
	893
	894
	895	Galbraith & Saarenmaa Expires July 29, 2006 [Page 16]
	896
	897	Internet-Draft SSH File Transfer Protocol January 2006
	898
	899
	900	uint32 valid-attribute-flags
	901	byte type always present
	902	uint64 size if flag SIZE
	903	uint64 allocation-size if flag ALLOCATION_SIZE
	904	string owner if flag OWNERGROUP
	905	string group if flag OWNERGROUP
	906	uint32 permissions if flag PERMISSIONS
	907	int64 atime if flag ACCESSTIME
	908	uint32 atime-nseconds if flag SUBSECOND_TIMES
	909	int64 createtime if flag CREATETIME
	910	uint32 createtime-nseconds if flag SUBSECOND_TIMES
	911	int64 mtime if flag MODIFYTIME
	912	uint32 mtime-nseconds if flag SUBSECOND_TIMES
	913	int64 ctime if flag CTIME
	914	uint32 ctime-nseconds if flag SUBSECOND_TIMES
	915	string acl if flag ACL
	916	uint32 attrib-bits if flag BITS
	917	uint32 attrib-bits-valid if flag BITS
	918	byte text-hint if flag TEXT_HINT
	919	string mime-type if flag MIME_TYPE
	920	uint32 link-count if flag LINK_COUNT
	921	string untranslated-name if flag UNTRANSLATED_NAME
	922	uint32 extended-count if flag EXTENDED
	923	extended-pair extensions
	924
	925	7.1. valid-attribute-flags
	926
	927	The 'valid-attribute-flags' specifies which of the fields are
	928	present. Those fields for which the corresponding flag is not set
	929	are not present (not included in the packet).
	930
	931	The server generally includes all attributes it knows about; however,
	932	it may exclude attributes that are overly expensive to retrieve
	933	unless the client explicitly requests them.
	934
	935	When writing attributes, the server SHOULD NOT modify attributes that
	936	are not present in the structure. However, if necessary, the server
	937	MAY use a default value for an absent attribute.
	938
	939	In general, unless otherwise specified, if a server cannot support
	940	writing an attribute requested, it must fail the setstat operation.
	941	In this case, none of the attributes SHOULD be changed.
	942
	943	New fields can only be added by incrementing the protocol version
	944	number (or by using the extension mechanism described below).
	945
	946	The following values are defined:
	947
	948
	949
	950
	951	Galbraith & Saarenmaa Expires July 29, 2006 [Page 17]
	952
	953	Internet-Draft SSH File Transfer Protocol January 2006
	954
	955
	956	SSH_FILEXFER_ATTR_SIZE 0x00000001
	957	SSH_FILEXFER_ATTR_PERMISSIONS 0x00000004
	958	SSH_FILEXFER_ATTR_ACCESSTIME 0x00000008
	959	SSH_FILEXFER_ATTR_CREATETIME 0x00000010
	960	SSH_FILEXFER_ATTR_MODIFYTIME 0x00000020
	961	SSH_FILEXFER_ATTR_ACL 0x00000040
	962	SSH_FILEXFER_ATTR_OWNERGROUP 0x00000080
	963	SSH_FILEXFER_ATTR_SUBSECOND_TIMES 0x00000100
	964	SSH_FILEXFER_ATTR_BITS 0x00000200
	965	SSH_FILEXFER_ATTR_ALLOCATION_SIZE 0x00000400
	966	SSH_FILEXFER_ATTR_TEXT_HINT 0x00000800
	967	SSH_FILEXFER_ATTR_MIME_TYPE 0x00001000
	968	SSH_FILEXFER_ATTR_LINK_COUNT 0x00002000
	969	SSH_FILEXFER_ATTR_UNTRANSLATED_NAME 0x00004000
	970	SSH_FILEXFER_ATTR_CTIME 0x00008000
	971	SSH_FILEXFER_ATTR_EXTENDED 0x80000000
	972
	973	0x00000002 was used in a previous version of this protocol. It is
	974	now a reserved value and MUST NOT appear in the mask. Some future
	975	version of this protocol may reuse this value.
	976
	977	7.2. Type
	978
	979	The type field is always present. The following types are defined:
	980
	981	SSH_FILEXFER_TYPE_REGULAR 1
	982	SSH_FILEXFER_TYPE_DIRECTORY 2
	983	SSH_FILEXFER_TYPE_SYMLINK 3
	984	SSH_FILEXFER_TYPE_SPECIAL 4
	985	SSH_FILEXFER_TYPE_UNKNOWN 5
	986	SSH_FILEXFER_TYPE_SOCKET 6
	987	SSH_FILEXFER_TYPE_CHAR_DEVICE 7
	988	SSH_FILEXFER_TYPE_BLOCK_DEVICE 8
	989	SSH_FILEXFER_TYPE_FIFO 9
	990
	991	On a POSIX system, these values would be derived from the mode field
	992	of the stat structure. SPECIAL should be used for files that are of
	993	a known type which cannot be expressed in the protocol. UNKNOWN
	994	should be used if the type is not known.
	995
	996	7.3. Size
	997
	998	The 'size' field specifies the number of bytes that can be read from
	999	the file, or in other words, the location of the end-of-file.
	1000
	1001	If this field is present during file creation, it indicates the
	1002	number of bytes the client intends to transfer, but SHOULD NOT effect
	1003	the creation of the file. The server can use this information to
	1004
	1005
	1006
	1007	Galbraith & Saarenmaa Expires July 29, 2006 [Page 18]
	1008
	1009	Internet-Draft SSH File Transfer Protocol January 2006
	1010
	1011
	1012	determine if the client sent all the intended data and the file was
	1013	transfered in it's entirity.
	1014
	1015	If this field is present during a setstat operation, the file MUST be
	1016	extended or truncated to the specified size.
	1017
	1018	Files opened with the SSH_FXF_TEXT flag may have a size that is
	1019	greater or less than the value of the size field. The server MAY
	1020	fail setstat operations specifying size for files opened with the
	1021	SSH_FXF_TEXT flag.
	1022
	1023	7.4. allocation-size
	1024
	1025	The 'allocation-size' field specifies the number of bytes that the
	1026	file consumes on disk. This field MAY be less than the 'size' field
	1027	if the file is 'sparse' (Section 7.9).
	1028
	1029	When present during file creation, the file SHOULD be created and the
	1030	specified number of bytes preallocated. If the preallocation fails,
	1031	the file should be removed (if it was created) and an error returned.
	1032
	1033	If this field is present during a setstat operation, the file SHOULD
	1034	be extended or truncated to the specified size. The 'size' of the
	1035	file may be affected by this operation. If the operation succeeds,
	1036	the 'size' should be the minimum of the 'size' before the operation
	1037	and the new 'allocation-size'.
	1038
	1039	Querying the 'allocation-size' after setting it MUST return a value
	1040	that is greater-than or equal to the value set, but it MAY not return
	1041	the precise value set.
	1042
	1043	If both 'size' and 'allocation-size' are set during a setstat
	1044	operation, and 'allocation-size' is less than 'size', the server MUST
	1045	return SSH_FX_INVALID_PARAMETER.
	1046
	1047	7.5. Owner and Group
	1048
	1049	The 'owner' and 'group' fields are represented as UTF-8 strings; this
	1050	is the form used by NFS v4. See NFS version 4 Protocol [RFC3010].
	1051	The following text is selected quotations from section 5.6.
	1052
	1053	To avoid a representation that is tied to a particular underlying
	1054	implementation at the client or server, the use of UTF-8 strings has
	1055	been chosen. The string should be of the form "user@dns_domain".
	1056	This will allow for a client and server that do not use the same
	1057	local representation the ability to translate to a common syntax that
	1058	can be interpreted by both. In the case where there is no
	1059	translation available to the client or server, the attribute value
	1060
	1061
	1062
	1063	Galbraith & Saarenmaa Expires July 29, 2006 [Page 19]
	1064
	1065	Internet-Draft SSH File Transfer Protocol January 2006
	1066
	1067
	1068	must be constructed without the "@". Therefore, the absence of the @
	1069	from the owner or owner_group attribute signifies that no translation
	1070	was available and the receiver of the attribute should not place any
	1071	special meaning on the attribute value. Even though the attribute
	1072	value cannot be translated, it may still be useful. In the case of a
	1073	client, the attribute string may be used for local display of
	1074	ownership.
	1075
	1076	user@localhost represents a user in the context of the server.
	1077
	1078	If either the owner or group field is zero length, the field should
	1079	be considered absent, and no change should be made to that specific
	1080	field during a modification operation.
	1081
	1082	7.6. Permissions
	1083
	1084	The 'permissions' field contains a bit mask specifying file
	1085	permissions. These permissions correspond to the st_mode field of
	1086	the stat structure defined by POSIX [IEEE.1003-1.1996].
	1087
	1088	This protocol uses the following values for the symbols declared in
	1089	the POSIX standard.
	1090
	1091	S_IRUSR 0000400 (octal)
	1092	S_IWUSR 0000200
	1093	S_IXUSR 0000100
	1094	S_IRGRP 0000040
	1095	S_IWGRP 0000020
	1096	S_IXGRP 0000010
	1097	S_IROTH 0000004
	1098	S_IWOTH 0000002
	1099	S_IXOTH 0000001
	1100	S_ISUID 0004000
	1101	S_ISGID 0002000
	1102	S_ISVTX 0001000
	1103
	1104	Implementations MUST NOT send bits that are not defined.
	1105
	1106	The server SHOULD NOT apply a 'umask' to the mode bits; but should
	1107	set the mode bits as specified by the client. The client MUST apply
	1108	an appropriate 'umask' to the mode bits before sending them.
	1109
	1110	7.7. Times
	1111
	1112	The 'atime' field contains the last access time of the file. Many
	1113	operating systems either don't have this field, only optionally
	1114	maintain it, or maintain it with less resolution than other fields.
	1115
	1116
	1117
	1118
	1119	Galbraith & Saarenmaa Expires July 29, 2006 [Page 20]
	1120
	1121	Internet-Draft SSH File Transfer Protocol January 2006
	1122
	1123
	1124	The 'mtime' contains the last time the file was written.
	1125
	1126	'createtime' contains the creation time of the file.
	1127
	1128	'ctime' contains the last time the file attributes were changed. The
	1129	exact meaning of this field depends on the server.
	1130
	1131	All times are represented as seconds from Jan 1, 1970 in UTC. A
	1132	negative value indicates number of seconds before Jan 1, 1970. In
	1133	both cases, if the SSH_FILEXFER_ATTR_SUBSECOND_TIMES flag is set, the
	1134	nseconds field is to be added to the seconds field for the final time
	1135	representation. For example, if the time to be represented is one-
	1136	half second before 0 hour January 1, 1970, the seconds field would
	1137	have a value of negative one (-1) and the nseconds fields would have
	1138	a value of one-half second (500000000). Values greater than
	1139	999,999,999 for nseconds are considered invalid.
	1140
	1141	7.8. ACL
	1142
	1143	The 'ACL' field contains an ACL similar to that defined in section
	1144	5.9 of NFS version 4 Protocol [RFC3010].
	1145
	1146	The structure of the ACL is:
	1147
	1148	uint32 acl-flags
	1149	uint32 ace-count
	1150	ACE ace[ace-count]
	1151
	1152	The ACE data structure is composes as follows:
	1153
	1154	uint32 ace-type
	1155	uint32 ace-flag
	1156	uint32 ace-mask
	1157	string who [UTF-8]
	1158
	1159	acl-flags
	1160
	1161
	1162	SFX_ACL_CONTROL_INCLUDED 0x00000001
	1163	SFX_ACL_CONTROL_PRESENT 0x00000002
	1164	SFX_ACL_CONTROL_INHERITED 0x00000004
	1165	SFX_ACL_AUDIT_ALARM_INCLUDED 0x00000010
	1166	SFX_ACL_AUDIT_ALARM_INHERITED 0x00000020
	1167
	1168
	1169
	1170
	1171
	1172
	1173
	1174
	1175	Galbraith & Saarenmaa Expires July 29, 2006 [Page 21]
	1176
	1177	Internet-Draft SSH File Transfer Protocol January 2006
	1178
	1179
	1180	SFX_ACL_CONTROL_INCLUDED
	1181	SFX_ACL_CONTROL_PRESENT
	1182	SFX_ACL_CONTROL_INHERITED
	1183	If INCLUDED is set during a setstat operation, then the client
	1184	intends to modify the ALLOWED/DENIED entries of the ACL.
	1185	Otherwise, the client intends for these entries to be
	1186	preserved.
	1187
	1188	If the PRESENT bit is not set, then the client wishes to remove
	1189	control entries. If the server doesn't support separate
	1190	control and audit information, the client MUST not clear this
	1191	bit without also clearing the AUDIT_ALARM_PRESENT bit.
	1192
	1193	If the PRESENT bit is clear, then control of the file MAY be
	1194	through the permissions mask. The server MAY also grant full
	1195	access to the file.
	1196
	1197	If the both the INCLUDE and the PRESENT bit are set, but their
	1198	are no ALLOW/DENY entries in the list, the client wishes to
	1199	deny all access to the file or directory. The server may have
	1200	to transform this into a ACL with a deny entry to implement it.
	1201
	1202	If INHERITED is set, then ALLOW/DENY ACEs MAY be inherited from
	1203	the parent directory. If it is off, then they MUST not be
	1204	INHERITED. If the server does not support controlling
	1205	inheritance, then the client MUST clear this bit; in this case
	1206	the inheritance properties of the server are undefined.
	1207
	1208	SFX_ACL_AUDIT_ALARM_INCLUDED
	1209	SFX_ACL_AUDIT_ALARM_INHERITED
	1210	If INCLUDE is set during a setstat operation, then the client
	1211	intends to modify the AUDIT/ALARM entries of the ACL.
	1212	Otherwise, the client intends for these entries to be
	1213	preserved.
	1214
	1215	If INHERITED is set, then AUDIT/ALARM ACEs MAY be inherited
	1216	from the parent directory. If it is off, then they MUST not be
	1217	INHERITED. If the server does not support controlling
	1218	inheritance, then the client MUST clear this bit; in this case
	1219	the inheritance properties of the server are undefined.
	1220
	1221	Because some server require special permissions / privileges in
	1222	order to modify the AUDIT/ALARM entries in the ACL, it is
	1223	important to communicate to the server the clients intent to
	1224	modify these entries. The client MUST both use the
	1225	ACCESS_AUDIT_ALARM_ATTRIBUTES bit in the desired attribute of the
	1226	open request and must set the SFX_ACL_AUDIT_ALARM_INCLUDED during
	1227	the setstat operation.
	1228
	1229
	1230
	1231	Galbraith & Saarenmaa Expires July 29, 2006 [Page 22]
	1232
	1233	Internet-Draft SSH File Transfer Protocol January 2006
	1234
	1235
	1236	Clients that do not intend specifically to modify the AUDIT or
	1237	ALARM entries SHOULD NOT set SSH_FXF_ACCESS_AUDIT_ALARM_INFO in
	1238	the open-flags and SHOULD NOT set the SFX_ACL_AUDIT_ALARM_INCLUDED
	1239	bit because these operations are often privileged and will fail.
	1240
	1241	If the SFX_ACL_AUDIT_ALARM_INCLUDED is set, and the requested
	1242	change can not be made, the server MUST fail the request.
	1243
	1244	Servers that do not seperate control and audit/alarm information
	1245	may have to read the existing ACL and merge in enteries not
	1246	included by the client. The server must take this into account
	1247	when opening files with the ACE4_WRITE_ACL permission requested.
	1248
	1249	ace-type
	1250	one of the following four values (taken from NFS Version 4
	1251	Protocol [RFC3010]:
	1252
	1253
	1254
	1255	ACE4_ACCESS_ALLOWED_ACE_TYPE 0x00000000
	1256	ACE4_ACCESS_DENIED_ACE_TYPE 0x00000001
	1257	ACE4_SYSTEM_AUDIT_ACE_TYPE 0x00000002
	1258	ACE4_SYSTEM_ALARM_ACE_TYPE 0x00000003
	1259
	1260	ace-flag
	1261	A combination of the following flag values. See NFS Version 4
	1262	Protocol [RFC3010] section 5.9.2:
	1263
	1264
	1265
	1266	ACE4_FILE_INHERIT_ACE 0x00000001
	1267	ACE4_DIRECTORY_INHERIT_ACE 0x00000002
	1268	ACE4_NO_PROPAGATE_INHERIT_ACE 0x00000004
	1269	ACE4_INHERIT_ONLY_ACE 0x00000008
	1270	ACE4_SUCCESSFUL_ACCESS_ACE_FLAG 0x00000010
	1271	ACE4_FAILED_ACCESS_ACE_FLAG 0x00000020
	1272	ACE4_IDENTIFIER_GROUP 0x00000040
	1273
	1274	ace-mask
	1275	Combination of the following flags (taken from [RFC3010], section
	1276	5.9.3. The semantic meaning of these flags is also given in
	1277	[RFC3010].
	1278
	1279
	1280
	1281
	1282
	1283
	1284
	1285
	1286
	1287	Galbraith & Saarenmaa Expires July 29, 2006 [Page 23]
	1288
	1289	Internet-Draft SSH File Transfer Protocol January 2006
	1290
	1291
	1292	ACE4_READ_DATA 0x00000001
	1293	ACE4_LIST_DIRECTORY 0x00000001
	1294	ACE4_WRITE_DATA 0x00000002
	1295	ACE4_ADD_FILE 0x00000002
	1296	ACE4_APPEND_DATA 0x00000004
	1297	ACE4_ADD_SUBDIRECTORY 0x00000004
	1298	ACE4_READ_NAMED_ATTRS 0x00000008
	1299	ACE4_WRITE_NAMED_ATTRS 0x00000010
	1300	ACE4_EXECUTE 0x00000020
	1301	ACE4_DELETE_CHILD 0x00000040
	1302	ACE4_READ_ATTRIBUTES 0x00000080
	1303	ACE4_WRITE_ATTRIBUTES 0x00000100
	1304	ACE4_DELETE 0x00010000
	1305	ACE4_READ_ACL 0x00020000
	1306	ACE4_WRITE_ACL 0x00040000
	1307	ACE4_WRITE_OWNER 0x00080000
	1308	ACE4_SYNCHRONIZE 0x00100000
	1309
	1310	who
	1311	UTF-8 string of the form described in 'Owner and Group'
	1312	(Section 7.5)
	1313	Also, as per '5.9.4 ACE who' [RFC3010] there are several
	1314	identifiers that need to be understood universally. Some of these
	1315	identifiers cannot be understood when an client access the server,
	1316	but have meaning when a local process accesses the file. The
	1317	ability to display and modify these permissions is permitted over
	1318	SFTP.
	1319
	1320	OWNER The owner of the file.
	1321	GROUP The group associated with the file.
	1322	EVERYONE The world.
	1323	INTERACTIVE Accessed from an interactive terminal.
	1324	NETWORK Accessed via the network.
	1325	DIALUP Accessed as a dialup user to the server.
	1326	BATCH Accessed from a batch job.
	1327	ANONYMOUS Accessed without any authentication.
	1328	AUTHENTICATED Any authenticated user (opposite of ANONYMOUS).
	1329	SERVICE Access from a system service.
	1330	To avoid conflict, these special identifiers are distinguish by an
	1331	appended "@". For example: ANONYMOUS@.
	1332
	1333	7.9. attrib-bits and attrib-bits-valid
	1334
	1335	These fields, taken together, reflect various attributes of the file
	1336	or directory, on the server.
	1337
	1338	Bits not set in 'attrib-bits-valid' MUST be ignored in the 'attrib-
	1339	bits' field. This allows both the server and the client to
	1340
	1341
	1342
	1343	Galbraith & Saarenmaa Expires July 29, 2006 [Page 24]
	1344
	1345	Internet-Draft SSH File Transfer Protocol January 2006
	1346
	1347
	1348	communicate only the bits it knows about without inadvertently
	1349	twiddling bits they don't understand.
	1350
	1351	The following attrib-bits are defined:
	1352
	1353	SSH_FILEXFER_ATTR_FLAGS_READONLY 0x00000001
	1354	SSH_FILEXFER_ATTR_FLAGS_SYSTEM 0x00000002
	1355	SSH_FILEXFER_ATTR_FLAGS_HIDDEN 0x00000004
	1356	SSH_FILEXFER_ATTR_FLAGS_CASE_INSENSITIVE 0x00000008
	1357	SSH_FILEXFER_ATTR_FLAGS_ARCHIVE 0x00000010
	1358	SSH_FILEXFER_ATTR_FLAGS_ENCRYPTED 0x00000020
	1359	SSH_FILEXFER_ATTR_FLAGS_COMPRESSED 0x00000040
	1360	SSH_FILEXFER_ATTR_FLAGS_SPARSE 0x00000080
	1361	SSH_FILEXFER_ATTR_FLAGS_APPEND_ONLY 0x00000100
	1362	SSH_FILEXFER_ATTR_FLAGS_IMMUTABLE 0x00000200
	1363	SSH_FILEXFER_ATTR_FLAGS_SYNC 0x00000400
	1364	SSH_FILEXFER_ATTR_FLAGS_TRANSLATION_ERR 0x00000800
	1365
	1366	SSH_FILEXFER_ATTR_FLAGS_READONLY
	1367	Advisory, read-only bit. This bit is not part of the access
	1368	control information on the file, but is rather an advisory field
	1369	indicating that the file should not be written.
	1370
	1371	SSH_FILEXFER_ATTR_FLAGS_SYSTEM
	1372	The file is part of the operating system.
	1373
	1374	SSH_FILEXFER_ATTR_FLAGS_HIDDEN
	1375	File SHOULD NOT be shown to user unless specifically requested.
	1376	For example, most UNIX systems SHOULD set this bit if the filename
	1377	begins with a 'period'. This bit may be read-only (Section 5.4).
	1378	Most UNIX systems will not allow this to be changed.
	1379
	1380	SSH_FILEXFER_ATTR_FLAGS_CASE_INSENSITIVE
	1381	This attribute applies only to directories. This attribute is
	1382	always read-only, and cannot be modified. This attribute means
	1383	that files and directory names in this directory should be
	1384	compared without regard to case.
	1385
	1386	It is recommended that where possible, the server's filesystem be
	1387	allowed to do comparisons. For example, if a client wished to
	1388	prompt a user before overwriting a file, it should not compare the
	1389	new name with the previously retrieved list of names in the
	1390	directory. Rather, it should first try to create the new file by
	1391	specifying SSH_FXF_CREATE_NEW flag. Then, if this fails and
	1392	returns SSH_FX_FILE_ALREADY_EXISTS, it should prompt the user and
	1393	then retry the create specifying SSH_FXF_CREATE_TRUNCATE.
	1394
	1395
	1396
	1397
	1398
	1399	Galbraith & Saarenmaa Expires July 29, 2006 [Page 25]
	1400
	1401	Internet-Draft SSH File Transfer Protocol January 2006
	1402
	1403
	1404	Unless otherwise specified, filenames are assumed to be case
	1405	sensitive.
	1406
	1407	SSH_FILEXFER_ATTR_FLAGS_ARCHIVE
	1408	The file should be included in backup / archive operations.
	1409
	1410	SSH_FILEXFER_ATTR_FLAGS_ENCRYPTED
	1411	The file is stored on disk using file-system level transparent
	1412	encryption. This flag does not affect the file data on the wire
	1413	(for either READ or WRITE requests.)
	1414
	1415	SSH_FILEXFER_ATTR_FLAGS_COMPRESSED
	1416	The file is stored on disk using file-system level transparent
	1417	compression. This flag does not affect the file data on the wire.
	1418
	1419	SSH_FILEXFER_ATTR_FLAGS_SPARSE
	1420	The file is a sparse file; this means that file blocks that have
	1421	not been explicitly written are not stored on disk. For example,
	1422	if a client writes a buffer at 10 M from the beginning of the
	1423	file, the blocks between the previous EOF marker and the 10 M
	1424	offset would not consume physical disk space.
	1425
	1426	Some servers may store all files as sparse files, in which case
	1427	this bit will be unconditionally set. Other servers may not have
	1428	a mechanism for determining if the file is sparse, and so the file
	1429	MAY be stored sparse even if this flag is not set.
	1430
	1431	SSH_FILEXFER_ATTR_FLAGS_APPEND_ONLY
	1432	Opening the file without either the SSH_FXF_APPEND_DATA or the
	1433	SSH_FXF_APPEND_DATA_ATOMIC flag (Section 8.1.1.3) MUST result in
	1434	an SSH_FX_INVALID_PARAMETER error.
	1435
	1436	SSH_FILEXFER_ATTR_FLAGS_IMMUTABLE
	1437	The file cannot be deleted or renamed, no hard link can be created
	1438	to this file, and no data can be written to the file.
	1439
	1440	This bit implies a stronger level of protection than
	1441	SSH_FILEXFER_ATTR_FLAGS_READONLY, the file permission mask or
	1442	ACLs. Typically even the superuser cannot write to immutable
	1443	files, and only the superuser can set or remove the bit.
	1444
	1445	SSH_FILEXFER_ATTR_FLAGS_SYNC
	1446	When the file is modified, the changes are written synchronously
	1447	to the disk.
	1448
	1449
	1450
	1451
	1452
	1453
	1454
	1455	Galbraith & Saarenmaa Expires July 29, 2006 [Page 26]
	1456
	1457	Internet-Draft SSH File Transfer Protocol January 2006
	1458
	1459
	1460	SSH_FILEXFER_ATTR_FLAGS_TRANSLATION_ERR
	1461	The server MAY include this bit in a directory listing or realpath
	1462	response. It indicates there was a failure in the translation to
	1463	UTF-8. If this flag is included, the server SHOULD also include
	1464	the UNTRANSLATED_NAME attribute.
	1465
	1466
	1467	7.10. text-hint
	1468
	1469	The value is one of the following enumerations, and indicates what
	1470	the server knows about the content of the file.
	1471
	1472	SSH_FILEXFER_ATTR_KNOWN_TEXT 0x00
	1473	SSH_FILEXFER_ATTR_GUESSED_TEXT 0x01
	1474	SSH_FILEXFER_ATTR_KNOWN_BINARY 0x02
	1475	SSH_FILEXFER_ATTR_GUESSED_BINARY 0x03
	1476
	1477	SSH_FILEXFER_ATTR_KNOWN_TEXT
	1478	The server knows the file is a text file, and should be opened
	1479	using the SSH_FXF_TEXT_MODE flag.
	1480
	1481	SSH_FILEXFER_ATTR_GUESSED_TEXT
	1482	The server has applied a heuristic or other mechanism and believes
	1483	that the file should be opened with the SSH_FXF_TEXT_MODE flag.
	1484
	1485	SSH_FILEXFER_ATTR_KNOWN_BINARY
	1486	The server knows the file has binary content.
	1487
	1488	SSH_FILEXFER_ATTR_GUESSED_BINARY
	1489	The server has applied a heuristic or other mechanism and believes
	1490	has binary content, and should not be opened with the
	1491	SSH_FXF_TEXT_MODE flag.
	1492
	1493
	1494	This flag MUST NOT be present during either a setstat or a fsetstat
	1495	operation.
	1496
	1497	7.11. mime-type
	1498
	1499	The 'mime-type' field contains the mime-type [RFC1521] string. Most
	1500	servers will not know this information and should not set the bit in
	1501	their supported-attribute-mask.
	1502
	1503	7.12. link-count
	1504
	1505	This field contains the hard link count of the file. This attribute
	1506	MUST NOT be present during a setstat operation.
	1507
	1508
	1509
	1510
	1511	Galbraith & Saarenmaa Expires July 29, 2006 [Page 27]
	1512
	1513	Internet-Draft SSH File Transfer Protocol January 2006
	1514
	1515
	1516	7.13. untranslated-name
	1517
	1518	This field contains the name before filename translation was attempt.
	1519	It MUST NOT be included unless the server also set the
	1520	SSH_FILEXFER_ATTR_FLAGS_TRANSLATION_ERR (Section 7.9) bit in the
	1521	attrib-bits field.
	1522
	1523	7.14. Extended Attributes
	1524
	1525	The SSH_FILEXFER_ATTR_EXTENDED flag provides a general extension
	1526	mechanism for the attrib structure. If the flag is specified, then
	1527	the 'extended_count' field is present. It specifies the number of
	1528	'extension-pair' items that follow. Each of these items specifies an
	1529	extended attribute. Implementations MUST return SSH_FX_UNSUPPORTED
	1530	if there are any unrecognized extensions. Clients can avoid sending
	1531	unsupported extensions by examining the attrib-extension-names of the
	1532	"supported2" extension attrib-extension-names (Section 5.4).
	1533
	1534	Additional fields can be added to the attributes by either defining
	1535	additional bits to the flags field to indicate their presence, or by
	1536	defining extended attributes for them. The extended attributes
	1537	mechanism is recommended for most purposes; additional flags bits
	1538	should be defined only by an IETF standards action that also
	1539	increments the protocol version number. The use of such new fields
	1540	MUST be negotiated by the version number in the protocol exchange.
	1541	It is a protocol error if a packet with unsupported protocol bits is
	1542	received.
	1543
	1544
	1545	8. Requests From the Client to the Server
	1546
	1547	Requests from the client to the server represent the various file
	1548	system operations.
	1549
	1550	8.1. Opening and Closing Files and Directories
	1551
	1552	Many operations in the protocol operate on open files. The
	1553	SSH_FXP_OPEN and SSH_FXP_OPENDIR requests return a handle (which is
	1554	an opaque, variable-length string) which may be used to access the
	1555	file or directory later. The client MUST NOT send requests to the
	1556	server with bogus or closed handles. However, the server MUST
	1557	perform adequate checks on the handle in order to avoid security
	1558	risks due to fabricated handles.
	1559
	1560	This design allows either stateful and stateless server
	1561	implementation, as well as an implementation which caches state
	1562	between requests but may also flush it. The contents of the file
	1563	handle string are entirely up to the server and its design. The
	1564
	1565
	1566
	1567	Galbraith & Saarenmaa Expires July 29, 2006 [Page 28]
	1568
	1569	Internet-Draft SSH File Transfer Protocol January 2006
	1570
	1571
	1572	client should not modify or attempt to interpret the file handle
	1573	strings.
	1574
	1575	The file handle strings MUST NOT be longer than 256 bytes.
	1576
	1577	8.1.1. Opening a File
	1578
	1579	Files are opened and created using the SSH_FXP_OPEN message.
	1580
	1581	byte SSH_FXP_OPEN
	1582	uint32 request-id
	1583	string filename [UTF-8]
	1584	uint32 desired-access
	1585	uint32 flags
	1586	ATTRS attrs
	1587
	1588	The response to this message will be either SSH_FXP_HANDLE (if the
	1589	operation is successful) or SSH_FXP_STATUS (if the operation fails.)
	1590
	1591	8.1.1.1. filename
	1592
	1593	The 'filename' field specifies the file name. See Section ''File
	1594	Names'' for more information. If 'filename' is a directory file, the
	1595	server MUST return an SSH_FX_FILE_IS_A_DIRECTORY error.
	1596
	1597	8.1.1.2. desired-access
	1598
	1599	The 'desired-access' field is a bitmask containing a combination of
	1600	values from the ace-mask flags (Section 7.8). Note that again, the
	1601	meaning of these flags is given in [RFC3010].
	1602
	1603	The server MUST be prepared to translate the SFTP access flags into
	1604	its local equivalents. If the server cannot grant the access
	1605	desired, it MUST return SSH_FX_PERMISSION_DENIED.
	1606
	1607	The server MAY open the file with greater access than requested if
	1608	the user has such access and the server implementation requires it.
	1609	For example, a server that does not distinguish between
	1610	READ_ATTRIBUTE and READ_DATA will have to request full 'read' access
	1611	to the file when the client only requested READ_ATTRIBUTE, resulting
	1612	in greater access than the client originally requested.
	1613
	1614	In such cases, it is possible, and permissible in the protocol, that
	1615	the client could open a file requesting some limited access, and then
	1616	access the file in a way not permitted by that limited access and the
	1617	server would permit such action. However, the server MUST NOT ever
	1618	grant access to the file that the client does not actually have the
	1619	rights to.
	1620
	1621
	1622
	1623	Galbraith & Saarenmaa Expires July 29, 2006 [Page 29]
	1624
	1625	Internet-Draft SSH File Transfer Protocol January 2006
	1626
	1627
	1628	8.1.1.3. flags
	1629
	1630	The 'flags' field controls various aspects of the operation,
	1631	including whether or not the file is created and the kind of locking
	1632	desired.
	1633
	1634	The following 'flags' are defined:
	1635
	1636	SSH_FXF_ACCESS_DISPOSITION = 0x00000007
	1637	SSH_FXF_CREATE_NEW = 0x00000000
	1638	SSH_FXF_CREATE_TRUNCATE = 0x00000001
	1639	SSH_FXF_OPEN_EXISTING = 0x00000002
	1640	SSH_FXF_OPEN_OR_CREATE = 0x00000003
	1641	SSH_FXF_TRUNCATE_EXISTING = 0x00000004
	1642	SSH_FXF_APPEND_DATA = 0x00000008
	1643	SSH_FXF_APPEND_DATA_ATOMIC = 0x00000010
	1644	SSH_FXF_TEXT_MODE = 0x00000020
	1645	SSH_FXF_BLOCK_READ = 0x00000040
	1646	SSH_FXF_BLOCK_WRITE = 0x00000080
	1647	SSH_FXF_BLOCK_DELETE = 0x00000100
	1648	SSH_FXF_BLOCK_ADVISORY = 0x00000200
	1649	SSH_FXF_NOFOLLOW = 0x00000400
	1650	SSH_FXF_DELETE_ON_CLOSE = 0x00000800
	1651	SSH_FXF_ACCESS_AUDIT_ALARM_INFO = 0x00001000
	1652	SSH_FXF_ACCESS_BACKUP = 0x00002000
	1653	SSH_FXF_BACKUP_STREAM = 0x00004000
	1654	SSH_FXF_OVERRIDE_OWNER = 0x00008000
	1655
	1656	SSH_FXF_ACCESS_DISPOSITION
	1657	Disposition is a 3 bit field that controls how the file is opened.
	1658	The server MUST support these bits. Any one of the following
	1659	enumeration is allowed:
	1660
	1661	SSH_FXF_CREATE_NEW
	1662	A new file is created; if the file already exists, the server
	1663	MUST return status SSH_FX_FILE_ALREADY_EXISTS.
	1664
	1665	SSH_FXF_CREATE_TRUNCATE
	1666	A new file is created; if the file already exists, it is opened
	1667	and truncated.
	1668
	1669	SSH_FXF_OPEN_EXISTING
	1670	An existing file is opened. If the file does not exist, the
	1671	server MUST return SSH_FX_NO_SUCH_FILE. If a directory in the
	1672	path does not exist, the server SHOULD return
	1673	SSH_FX_NO_SUCH_PATH. It is also acceptable if the server
	1674	returns SSH_FX_NO_SUCH_FILE in this case.
	1675
	1676
	1677
	1678
	1679	Galbraith & Saarenmaa Expires July 29, 2006 [Page 30]
	1680
	1681	Internet-Draft SSH File Transfer Protocol January 2006
	1682
	1683
	1684	SSH_FXF_OPEN_OR_CREATE
	1685	If the file exists, it is opened. If the file does not exist,
	1686	it is created.
	1687
	1688	SSH_FXF_TRUNCATE_EXISTING
	1689	An existing file is opened and truncated. If the file does not
	1690	exist, the server MUST return the same error codes as defined
	1691	for SSH_FXF_OPEN_EXISTING.
	1692
	1693	SSH_FXF_APPEND_DATA
	1694	Data is always written at the end of the file. The offset field
	1695	of the SSH_FXP_WRITE requests are ignored.
	1696
	1697	Data is not required to be appended atomically. This means that
	1698	if multiple writers attempt to append data simultaneously, data
	1699	from the first may be lost. However, data MAY be appended
	1700	atomically.
	1701
	1702	SSH_FXF_APPEND_DATA_ATOMIC
	1703	Data is always written at the end of the file. The offset field
	1704	of the SSH_FXP_WRITE requests are ignored.
	1705
	1706	Data MUST be written atomically so that there is no chance that
	1707	multiple appenders can collide and result in data being lost.
	1708
	1709	If both append flags are specified, the server SHOULD use atomic
	1710	append if it is available, but SHOULD use non-atomic appends
	1711	otherwise. The server SHOULD NOT fail the request in this case.
	1712
	1713	SSH_FXF_TEXT_MODE
	1714	Indicates that the server should treat the file as text and
	1715	convert it to the canonical newline convention in use. (See
	1716	Determining Server Newline Convention. (Section 5.3)
	1717
	1718	When a file is opened with this flag, the offset field in the read
	1719	and write functions is ignored.
	1720
	1721	Servers MUST process multiple, parallel reads and writes correctly
	1722	in this mode. Naturally, it is permissible for them to do this by
	1723	serializing the requests.
	1724
	1725	Clients SHOULD use the SSH_FXF_APPEND_DATA flag to append data to
	1726	a text file rather then using write with a calculated offset.
	1727
	1728
	1729
	1730
	1731
	1732
	1733
	1734
	1735	Galbraith & Saarenmaa Expires July 29, 2006 [Page 31]
	1736
	1737	Internet-Draft SSH File Transfer Protocol January 2006
	1738
	1739
	1740	To support seeks on text files the following SSH_FXP_EXTENDED
	1741	packet is defined.
	1742
	1743
	1744	string "text-seek"
	1745	string file-handle
	1746	uint64 line-number
	1747
	1748	line-number is the index of the line number to seek to, where byte
	1749	0 in the file is line number 0, and the byte directly following
	1750	the first newline sequence in the file is line number 1 and so on.
	1751
	1752	The response to a "text-seek" request is an SSH_FXP_STATUS
	1753	message.
	1754
	1755	An attempt to seek past the end-of-file should result in a
	1756	SSH_FX_EOF status.
	1757
	1758	Servers SHOULD support at least one "text-seek" in order to
	1759	support resume. However, a client MUST be prepared to receive
	1760	SSH_FX_OP_UNSUPPORTED when attempting a "text-seek" operation.
	1761	The client can then try a fall-back strategy, if it has one.
	1762
	1763	SSH_FXF_BLOCK_READ
	1764	The server MUST guarantee that no other handle has been opened
	1765	with ACE4_READ_DATA access, and that no other handle will be
	1766	opened with ACE4_READ_DATA access until the client closes the
	1767	handle. (This MUST apply both to other clients and to other
	1768	processes on the server.)
	1769
	1770	If there is a conflicting lock the server MUST return
	1771	SSH_FX_LOCK_CONFLICT. If the server cannot make the locking
	1772	guarantee, it MUST return SSH_FX_OP_UNSUPPORTED.
	1773
	1774	Other handles MAY be opened for ACE4_WRITE_DATA or any other
	1775	combination of accesses, as long as ACE4_READ_DATA is not included
	1776	in the mask.
	1777
	1778	SSH_FXF_BLOCK_WRITE
	1779	The server MUST guarantee that no other handle has been opened
	1780	with ACE4_WRITE_DATA or ACE4_APPEND_DATA access, and that no other
	1781	handle will be opened with ACE4_WRITE_DATA or ACE4_APPEND_DATA
	1782	access until the client closes the handle. (This MUST apply both
	1783	to other clients and to other processes on the server.)
	1784
	1785
	1786
	1787
	1788
	1789
	1790
	1791	Galbraith & Saarenmaa Expires July 29, 2006 [Page 32]
	1792
	1793	Internet-Draft SSH File Transfer Protocol January 2006
	1794
	1795
	1796	If there is a conflicting lock the server MUST return
	1797	SSH_FX_LOCK_CONFLICT. If the server cannot make the locking
	1798	guarantee, it MUST return SSH_FX_OP_UNSUPPORTED.
	1799
	1800	Other handles MAY be opened for ACE4_READ_DATA or any other
	1801	combination of accesses, as long as neither ACE4_WRITE_DATA nor
	1802	ACE4_APPEND_DATA are included in the mask.
	1803
	1804	SSH_FXF_BLOCK_DELETE
	1805	The server MUST guarantee that no other handle has been opened
	1806	with ACE4_DELETE access, opened with the SSH_FXF_DELETE_ON_CLOSE
	1807	flag set, and that no other handle will be opened with ACE4_DELETE
	1808	access or with the SSH_FXF_DELETE_ON_CLOSE flag set, and that the
	1809	file itself is not deleted in any other way until the client
	1810	closes the handle.
	1811
	1812	If there is a conflicting lock the server MUST return
	1813	SSH_FX_LOCK_CONFLICT. If the server cannot make the locking
	1814	guarantee, it MUST return SSH_FX_OP_UNSUPPORTED.
	1815
	1816	SSH_FXF_BLOCK_ADVISORY
	1817	If this bit is set, the above BLOCK modes are advisory. In
	1818	advisory mode, only other accesses that specify a BLOCK mode need
	1819	be considered when determining whether the BLOCK can be granted,
	1820	and the server need not prevent I/O operations that violate the
	1821	block mode.
	1822
	1823	The server MAY perform mandatory locking even if the
	1824	BLOCK_ADVISORY bit is set.
	1825
	1826	SSH_FXF_NOFOLLOW
	1827	If the final component of the path is a symlink, then the open
	1828	MUST fail, and the error SSH_FX_LINK_LOOP MUST be returned.
	1829
	1830	SSH_FXF_DELETE_ON_CLOSE
	1831	The file should be deleted when the last handle to it is closed.
	1832	(The last handle may not be an sftp-handle.) This MAY be emulated
	1833	by a server if the OS doesn't support it by deleting the file when
	1834	this handle is closed.
	1835
	1836	It is implementation specific whether the directory entry is
	1837	removed immediately or when the handle is closed.
	1838
	1839	SSH_FXF_ACCESS_AUDIT_ALARM_INFO
	1840	The client wishes the server to enable any privileges or extra
	1841	capabilities that the user may have in to allow the reading and
	1842	writing of AUDIT or ALARM access control entries.
	1843
	1844
	1845
	1846
	1847	Galbraith & Saarenmaa Expires July 29, 2006 [Page 33]
	1848
	1849	Internet-Draft SSH File Transfer Protocol January 2006
	1850
	1851
	1852	SSH_FXF_ACCESS_BACKUP
	1853	The client wishes the server to enable any privileges or extra
	1854	capabilities that the user may have in order to bypass normal
	1855	access checks for the purpose of backing up or restoring files.
	1856
	1857	SSH_FXF_BACKUP_STREAM
	1858	This bit indicates that the client wishes to read or write a
	1859	backup stream. A backup stream is a system dependent structured
	1860	data stream that encodes all the information that must be
	1861	preserved in order to restore the file from backup medium.
	1862
	1863	The only well defined use for backup stream data read in this
	1864	fashion is to write it to the same server to a file also opened
	1865	using the BACKUP_STREAM flag. However, if the server has a well
	1866	defined backup stream format, their may be other uses for this
	1867	data outside the scope of this protocol.
	1868
	1869	ACCESS_OVERRIDE_OWNER
	1870	This bit indicates that the client wishes the server to enable any
	1871	privileges or extra capabilities that the user may have in order
	1872	to gain access to the file with WRITE_OWNER permission.
	1873
	1874	This bit MUST always be specified in combination with
	1875	ACE4_WRITE_OWNER.
	1876
	1877
	1878	The 'attrs' field specifies the initial attributes for the file.
	1879	Default values MUST be supplied by the server for those attributes
	1880	that are not specified. See Section ''File Attributes'' for more
	1881	information.
	1882
	1883	The 'attrs' field is ignored if an existing file is opened.
	1884
	1885	The following table is provided to assist in mapping POSIX semantics
	1886	to equivalent SFTP file open parameters:
	1887	O_RDONLY
	1888	desired-access = READ_DATA\|READ_ATTRIBUTES
	1889
	1890	O_WRONLY
	1891	desired-access = WRITE_DATA\|WRITE_ATTRIBUTES
	1892
	1893	O_RDWR
	1894	desired-access = READ_DATA\|READ_ATTRIBUTES\|WRITE_DATA\|
	1895	WRITE_ATTRIBUTES
	1896
	1897
	1898
	1899
	1900
	1901
	1902
	1903	Galbraith & Saarenmaa Expires July 29, 2006 [Page 34]
	1904
	1905	Internet-Draft SSH File Transfer Protocol January 2006
	1906
	1907
	1908	O_APPEND
	1909	desired-access = WRITE_DATA\|WRITE_ATTRIBUTES\|APPEND_DATA
	1910	flags = SSH_FXF_APPEND_DATA and or SSH_FXF_APPEND_DATA_ATOMIC
	1911
	1912	O_CREAT
	1913	flags = SSH_FXF_OPEN_OR_CREATE
	1914
	1915	O_TRUNC
	1916	flags = SSH_FXF_TRUNCATE_EXISTING
	1917
	1918	O_TRUNC\|O_CREATE
	1919	flags = SSH_FXF_CREATE_TRUNCATE
	1920
	1921	8.1.2. Opening a Directory
	1922
	1923	To enumerate a directory, the client first obtains a handle and then
	1924	issues directory read requests. When enumeration is complete, the
	1925	handle MUST be closed.
	1926
	1927	byte SSH_FXP_OPENDIR
	1928	uint32 request-id
	1929	string path [UTF-8]
	1930
	1931	path
	1932	The 'path' field is the path name of the directory to be listed
	1933	(without any trailing slash). See Section 'File Names' for more
	1934	information on file names.
	1935
	1936	If 'path' does not refer to a directory, the server MUST return
	1937	SSH_FX_NOT_A_DIRECTORY.
	1938
	1939
	1940	The response to this message will be either SSH_FXP_HANDLE (if the
	1941	operation is successful) or SSH_FXP_STATUS (if the operation fails).
	1942
	1943	8.1.3. Closing Handles
	1944
	1945	A handle is closed using the following request.
	1946
	1947	byte SSH_FXP_CLOSE
	1948	uint32 request-id
	1949	string handle
	1950
	1951	handle
	1952	'handle' is a handle previously returned in the response to
	1953	SSH_FXP_OPEN or SSH_FXP_OPENDIR. The handle becomes invalid
	1954	immediately after this request has been sent.
	1955
	1956
	1957
	1958
	1959	Galbraith & Saarenmaa Expires July 29, 2006 [Page 35]
	1960
	1961	Internet-Draft SSH File Transfer Protocol January 2006
	1962
	1963
	1964	The response to this request will be a SSH_FXP_STATUS message. Note
	1965	that on some server platforms even a close can fail. For example, if
	1966	the server operating system caches writes, and an error occurs while
	1967	flushing cached writes, the close operation may fail.
	1968
	1969	Note that the handle is invalid regardless of the SSH_FXP_STATUS
	1970	result. There is no way for the client to recover a handle that
	1971	fails to close. The client MUST release all resources associated
	1972	with the handle regardless of the status. The server SHOULD take
	1973	whatever steps it can to recover from a close failure and to ensure
	1974	that all resources associated with the handle on the server are
	1975	correctly released.
	1976
	1977	8.2. Reading and Writing
	1978
	1979	8.2.1. Reading Files
	1980
	1981	The following request can be used to read file data:
	1982
	1983	byte SSH_FXP_READ
	1984	uint32 request-id
	1985	string handle
	1986	uint64 offset
	1987	uint32 length
	1988
	1989	handle
	1990	'handle' is an open file handle returned by SSH_FXP_OPEN. If
	1991	'handle' is not a handle returned by SSH_FXP_OPEN, the server MUST
	1992	return SSH_FX_INVALID_HANDLE.
	1993
	1994	offset
	1995	The offset (in bytes) relative to the beginning of the file that
	1996	the read MUST start at. This field is ignored if
	1997	SSH_FXF_TEXT_MODE was specified during the open.
	1998
	1999	length
	2000	'length' is the maximum number of bytes to read.
	2001
	2002	The server MUST not respond with more data than is specified by
	2003	the 'length' parameter. However, the server MAY respond with less
	2004	data if EOF is reached, an error is encountered, or the servers
	2005	internal buffers can not handle such a large request.
	2006
	2007	If the server specified a non-zero 'max-read-size' in its
	2008	'supported2' (Section 5.4) extension, then failure to return
	2009	'length' bytes indicates that EOF or an error occurred.
	2010
	2011
	2012
	2013
	2014
	2015	Galbraith & Saarenmaa Expires July 29, 2006 [Page 36]
	2016
	2017	Internet-Draft SSH File Transfer Protocol January 2006
	2018
	2019
	2020	8.2.2. Reading Directories
	2021
	2022	In order to retrieve a directory listing, the client issues one or
	2023	more SSH_FXP_READDIR requests. In order to obtain a complete
	2024	directory listing, the client MUST issue repeated SSH_FXP_READDIR
	2025	requests until the server responds with an SSH_FXP_STATUS message.
	2026
	2027	byte SSH_FXP_READDIR
	2028	uint32 request-id
	2029	string handle
	2030
	2031	handle
	2032	'handle' is a handle returned by SSH_FXP_OPENDIR. If 'handle' is
	2033	an ordinary file handle returned by SSH_FXP_OPEN, the server MUST
	2034	return SSH_FX_INVALID_HANDLE.
	2035
	2036
	2037	The server responds to this request with either a SSH_FXP_NAME or a
	2038	SSH_FXP_STATUS message. One or more names may be returned at a time.
	2039	Full status information is returned for each name in order to speed
	2040	up typical directory listings.
	2041
	2042	If there are no more names available to be read, the server MUST
	2043	respond with a SSH_FXP_STATUS message with error code of SSH_FX_EOF.
	2044
	2045	8.2.3. Writing Files
	2046
	2047	Writing to a file is achieved using the following message:
	2048
	2049	byte SSH_FXP_WRITE
	2050	uint32 request-id
	2051	string handle
	2052	uint64 offset
	2053	string data
	2054
	2055	handle
	2056	'handle' is an open file handle returned by SSH_FXP_OPEN. If
	2057	'handle' is not a handle returned by SSH_FXP_OPEN, the server MUST
	2058	return SSH_FX_INVALID_HANDLE.
	2059
	2060	offset
	2061	The offset (in bytes) relative to the beginning of the file that
	2062	the write MUST start at. This field is ignored if
	2063	SSH_FXF_TEXT_MODE was specified during the open.
	2064
	2065
	2066
	2067
	2068
	2069
	2070
	2071	Galbraith & Saarenmaa Expires July 29, 2006 [Page 37]
	2072
	2073	Internet-Draft SSH File Transfer Protocol January 2006
	2074
	2075
	2076	The write will extend the file if writing beyond the end of the
	2077	file. It is legal to write to an offset that extends beyond the
	2078	end of the file; the semantics are to write the byte value 0x00
	2079	from the end of the file to the specified offset and then the
	2080	data. On most operating systems, such writes do not allocate disk
	2081	space but instead create a sparse file.
	2082
	2083	data
	2084	The data to write to the file.
	2085
	2086	The server responds to a write request with a SSH_FXP_STATUS message.
	2087
	2088	8.3. Removing and Renaming Files
	2089
	2090	The following request can be used to remove a file:
	2091
	2092	byte SSH_FXP_REMOVE
	2093	uint32 request-id
	2094	string filename [UTF-8]
	2095
	2096	filename
	2097	'filename' is the name of the file to be removed. See Section
	2098	'File Names' for more information.
	2099
	2100	If 'filename' is a symbolic link, the link is removed, not the
	2101	file it points to.
	2102	This request cannot be used to remove directories. The server
	2103	MUST return SSH_FX_FILE_IS_A_DIRECTORY in this case.
	2104
	2105
	2106	The server will respond to this request with a SSH_FXP_STATUS
	2107	message.
	2108
	2109	Files (and directories) can be renamed using the SSH_FXP_RENAME
	2110	message.
	2111
	2112	byte SSH_FXP_RENAME
	2113	uint32 request-id
	2114	string oldpath [UTF-8]
	2115	string newpath [UTF-8]
	2116	uint32 flags
	2117
	2118	where 'request-id' is the request identifier, 'oldpath' is the name
	2119	of an existing file or directory, and 'newpath' is the new name for
	2120	the file or directory.
	2121
	2122	'flags' is 0 or a combination of:
	2123
	2124
	2125
	2126
	2127	Galbraith & Saarenmaa Expires July 29, 2006 [Page 38]
	2128
	2129	Internet-Draft SSH File Transfer Protocol January 2006
	2130
	2131
	2132	SSH_FXF_RENAME_OVERWRITE 0x00000001
	2133	SSH_FXF_RENAME_ATOMIC 0x00000002
	2134	SSH_FXF_RENAME_NATIVE 0x00000004
	2135
	2136	If flags does not include SSH_FXP_RENAME_OVERWRITE, and there already
	2137	exists a file with the name specified by newpath, the server MUST
	2138	respond with SSH_FX_FILE_ALREADY_EXISTS.
	2139
	2140	If flags includes SSH_FXP_RENAME_ATOMIC, and the destination file
	2141	already exists, it is replaced in an atomic fashion. I.e., there is
	2142	no observable instant in time where the name does not refer to either
	2143	the old or the new file. SSH_FXP_RENAME_ATOMIC implies
	2144	SSH_FXP_RENAME_OVERWRITE.
	2145
	2146	If flags includes SSH_FXP_RENAME_ATOMIC and the server cannot replace
	2147	the destination in an atomic fashion, then the server MUST respond
	2148	with SSH_FX_OP_UNSUPPORTED.
	2149
	2150	Because some servers cannot provide atomic rename, clients should
	2151	only specify atomic rename if correct operation requires it. If
	2152	SSH_FXP_RENAME_OVERWRITE is specified, the server MAY perform an
	2153	atomic rename even if it is not requested.
	2154
	2155	If flags includes SSH_FXP_RENAME_NATIVE, the server is free to do the
	2156	rename operation in whatever fashion it deems appropriate. Other
	2157	flag values are considered hints as to desired behavior, but not
	2158	requirements.
	2159
	2160	The server will respond to this request with a SSH_FXP_STATUS
	2161	message.
	2162
	2163	8.4. Creating and Deleting Directories
	2164
	2165	New directories can be created using the SSH_FXP_MKDIR request. It
	2166	has the following format:
	2167
	2168	byte SSH_FXP_MKDIR
	2169	uint32 request-id
	2170	string path [UTF-8]
	2171	ATTRS attrs
	2172
	2173	where 'request-id' is the request identifier.
	2174
	2175	'path' specifies the directory to be created. See Section ''File
	2176	Names'' for more information on file names.
	2177
	2178	'attrs' specifies the attributes that should be applied to it upon
	2179	creation. Attributes are discussed in more detail in Section ''File
	2180
	2181
	2182
	2183	Galbraith & Saarenmaa Expires July 29, 2006 [Page 39]
	2184
	2185	Internet-Draft SSH File Transfer Protocol January 2006
	2186
	2187
	2188	Attributes''.
	2189
	2190	The server will respond to this request with a SSH_FXP_STATUS
	2191	message. If a file or directory with the specified path already
	2192	exists, an error will be returned.
	2193
	2194	Directories can be removed using the SSH_FXP_RMDIR request, which has
	2195	the following format:
	2196
	2197	byte SSH_FXP_RMDIR
	2198	uint32 request-id
	2199	string path [UTF-8]
	2200
	2201	where 'request-id' is the request identifier, and 'path' specifies
	2202	the directory to be removed. See Section ''File Names'' for more
	2203	information on file names.
	2204
	2205	The server responds to this request with a SSH_FXP_STATUS message.
	2206
	2207	8.5. Retrieving File Attributes
	2208
	2209	Very often, file attributes are automatically returned by
	2210	SSH_FXP_READDIR. However, sometimes there is need to specifically
	2211	retrieve the attributes for a named file. This can be done using the
	2212	SSH_FXP_STAT, SSH_FXP_LSTAT and SSH_FXP_FSTAT requests.
	2213
	2214	SSH_FXP_STAT and SSH_FXP_LSTAT only differ in that SSH_FXP_STAT
	2215	follows symbolic links on the server, whereas SSH_FXP_LSTAT does not
	2216	follow symbolic links. Both have the same format:
	2217
	2218	byte SSH_FXP_STAT or SSH_FXP_LSTAT
	2219	uint32 request-id
	2220	string path [UTF-8]
	2221	uint32 flags
	2222
	2223	where 'request-id' is the request identifier, and 'path' specifies
	2224	the file system object for which status is to be returned. The
	2225	server responds to this request with either SSH_FXP_ATTRS or
	2226	SSH_FXP_STATUS.
	2227
	2228	The flags field specify the attribute flags in which the client has
	2229	particular interest. This is a hint to the server. For example,
	2230	because retrieving owner / group and acl information can be an
	2231	expensive operation under some operating systems, the server may
	2232	choose not to retrieve this information unless the client expresses a
	2233	specific interest in it.
	2234
	2235	The client has no guarantee the server will provide all the fields
	2236
	2237
	2238
	2239	Galbraith & Saarenmaa Expires July 29, 2006 [Page 40]
	2240
	2241	Internet-Draft SSH File Transfer Protocol January 2006
	2242
	2243
	2244	that it has expressed an interest in.
	2245
	2246	SSH_FXP_FSTAT differs from the others in that it returns status
	2247	information for an open file (identified by the file handle).
	2248
	2249	byte SSH_FXP_FSTAT
	2250	uint32 request-id
	2251	string handle
	2252	uint32 flags
	2253
	2254	handle
	2255	'handle' is an open file handle from either SSH_FXP_OPEN or
	2256	SSH_FXP_OPENDIR.
	2257
	2258
	2259	The server responds to this request with SSH_FXP_ATTRS or
	2260	SSH_FXP_STATUS.
	2261
	2262	8.6. Setting File Attributes
	2263
	2264	File attributes may be modified using the SSH_FXP_SETSTAT and
	2265	SSH_FXP_FSETSTAT requests.
	2266
	2267	byte SSH_FXP_SETSTAT
	2268	uint32 request-id
	2269	string path [UTF-8]
	2270	ATTRS attrs
	2271
	2272
	2273	byte SSH_FXP_FSETSTAT
	2274	uint32 request-id
	2275	string handle
	2276	ATTRS attrs
	2277
	2278	path
	2279	The file system object (e.g. file or directory) whose attributes
	2280	are to be modified. If this object does not exist, or the user
	2281	does not have sufficient access to write the attributes, the
	2282	request MUST fail.
	2283
	2284	handle
	2285	'handle' is an open file handle from either SSH_FXP_OPEN or
	2286	SSH_FXP_OPENDIR. If the handle was not opened with sufficient
	2287	access to write the requested attributes, the request MUST fail.
	2288
	2289
	2290
	2291
	2292
	2293
	2294
	2295	Galbraith & Saarenmaa Expires July 29, 2006 [Page 41]
	2296
	2297	Internet-Draft SSH File Transfer Protocol January 2006
	2298
	2299
	2300	attrs
	2301	Specifies the modified attributes to be applied. Attributes are
	2302	discussed in more detail in Section ''File Attributes''.
	2303
	2304	The server will respond with a SSH_FXP_STATUS message.
	2305
	2306	Because some systems must use separate system calls to set various
	2307	attributes, it is possible that a failure response will be returned,
	2308	but yet some of the attributes may be have been successfully
	2309	modified. If possible, servers SHOULD avoid this situation; however,
	2310	clients MUST be aware that this is possible.
	2311
	2312	8.7. Dealing with Links
	2313
	2314	The SSH_FXP_READLINK request reads the target of a symbolic link.
	2315
	2316	byte SSH_FXP_READLINK
	2317	uint32 request-id
	2318	string path [UTF-8]
	2319
	2320	where 'request-id' is the request identifier and 'path' specifies the
	2321	path name of the symlink to be read.
	2322
	2323	The server will respond with a SSH_FXP_NAME packet containing only
	2324	one name and a dummy attributes value. The name in the returned
	2325	packet contains the target of the link. If an error occurs, the
	2326	server MAY respond with SSH_FXP_STATUS.
	2327
	2328	The SSH_FXP_LINK request creates a link (either hard or symbolic) on
	2329	the server.
	2330
	2331	byte SSH_FXP_LINK
	2332	uint32 request-id
	2333	string new-link-path [UTF-8]
	2334	string existing-path [UTF-8]
	2335	bool sym-link
	2336
	2337	new-link-path
	2338	Specifies the path name of the new link to create.
	2339
	2340	existing-path
	2341	Specifies the path of an existing file system object to which the
	2342	new-link-path will refer.
	2343
	2344
	2345
	2346
	2347
	2348
	2349
	2350
	2351	Galbraith & Saarenmaa Expires July 29, 2006 [Page 42]
	2352
	2353	Internet-Draft SSH File Transfer Protocol January 2006
	2354
	2355
	2356	sym-link
	2357	Specifies that the link should be a symbolic link, or a special
	2358	file that redirects file system parsing to the resulting path. It
	2359	is generally possible to create symbolic links across device
	2360	boundaries; however, it is not required that a server support
	2361	this.
	2362
	2363	If 'sym-link' is false, the link should be a hard link, or a
	2364	second directory entry referring to the same file or directory
	2365	object. It is generally not possible to create hard links across
	2366	devices.
	2367
	2368
	2369	The server shall respond with a SSH_FXP_STATUS. Clients should be
	2370	aware that some servers may return SSH_FX_OP_UNSUPPORTED for either
	2371	the hard-link, sym-link, or both operations.
	2372
	2373	8.8. Byte-range locks
	2374
	2375	SSH_FXP_BLOCK creates a byte-range lock on the file specified by the
	2376	handle. The lock can be either mandatory (meaning that the server
	2377	enforces that no other process or client can perform operations in
	2378	violation of the lock) or advisory (meaning that no other process can
	2379	obtain a conflicting lock, but the server does not enforce that no
	2380	operation violates the lock.
	2381
	2382	A server MAY implement an advisory lock in a mandatory fashion; in
	2383	other words, the server MAY enforce that no operation violates the
	2384	lock even when operating in advisory mode.
	2385
	2386	The result is a SSH_FXP_STATUS return.
	2387
	2388	byte SSH_FXP_BLOCK
	2389	uint32 request-id
	2390	string handle
	2391	uint64 offset
	2392	uint64 length
	2393	uint32 uLockMask
	2394
	2395	handle
	2396	'handle' is a handle returned by SSH_FXP_OPEN or SSH_FXP_OPENDIR.
	2397	Note that some server MAY return SSH_FX_OP_UNSUPPORTED if the
	2398	handle is a directory handle.
	2399
	2400
	2401
	2402
	2403
	2404
	2405
	2406
	2407	Galbraith & Saarenmaa Expires July 29, 2006 [Page 43]
	2408
	2409	Internet-Draft SSH File Transfer Protocol January 2006
	2410
	2411
	2412	offset
	2413	Beginning of the byte-range to lock.
	2414
	2415	length
	2416	Number of bytes in the range to lock. The special value 0 means
	2417	lock from 'offset' to the end of the file.
	2418
	2419	uLockMask
	2420	A bit mask of SSH_FXF_BLOCK_* values; the meanings are described
	2421	in Section 8.1.1.3.
	2422
	2423	SSH_FXP_UNBLOCK removes a previously acquired byte-range lock on the
	2424	specified handle.
	2425
	2426	The result is a SSH_FXP_STATUS return.
	2427
	2428	byte SSH_FXP_UNBLOCK
	2429	uint32 request-id
	2430	string handle
	2431	uint64 offset
	2432	uint64 length
	2433
	2434	handle
	2435	'handle' on which a SSH_FXP_BLOCK request has previously been
	2436	issued.
	2437
	2438	offset
	2439	Beginning of the byte-range to lock.
	2440
	2441	length
	2442	Number of bytes in the range to lock. The special value 0 means
	2443	lock from 'offset' to the end of the file.
	2444
	2445	8.9. Canonicalizing the Server-Side Path Name
	2446
	2447	The SSH_FXP_REALPATH request can be used to have the server
	2448	canonicalize any given path name to an absolute path. This is useful
	2449	for converting path names containing ".." components or relative
	2450	pathnames without a leading slash into absolute paths. The format of
	2451	the request is as follows:
	2452
	2453	byte SSH_FXP_REALPATH
	2454	uint32 request-id
	2455	string original-path [UTF-8]
	2456	byte control-byte [optional]
	2457	string compose-path[0..n] [optional]
	2458
	2459
	2460
	2461
	2462
	2463	Galbraith & Saarenmaa Expires July 29, 2006 [Page 44]
	2464
	2465	Internet-Draft SSH File Transfer Protocol January 2006
	2466
	2467
	2468	original-path
	2469	The first component of the path which the client wishes resolved
	2470	into a absolute canonical path. This may be the entire path.
	2471
	2472	control-byte
	2473
	2474	SSH_FXP_REALPATH_NO_CHECK 0x00000001
	2475	SSH_FXP_REALPATH_STAT_IF 0x00000002
	2476	SSH_FXP_REALPATH_STAT_ALWAYS 0x00000003
	2477
	2478	This field is optional, and if it is not present in the packet, it
	2479	is assumed to be SSH_FXP_REALPATH_NO_CHECK.
	2480
	2481	If SSH_FXP_REALPATH_NO_CHECK is specified, the server MUST NOT
	2482	fail the request if the path does not exist, is hidden, or the
	2483	user does not have access to the path or some component thereof.
	2484	In addition, the path MUST NOT resolve symbolic links. This
	2485	allows paths to be composed for the SSH_FXP_REMOVE command to
	2486	remove symbolic links.
	2487
	2488	The server MAY fail the request if the path is not syntactically
	2489	valid, or for other reasons.
	2490
	2491	If SSH_FXP_REALPATH_STAT_IF is specified, the server MUST stat the
	2492	path if it exists and is accessible to the client. However, if
	2493	the path does not exist, isn't visible, or isn't accessible, the
	2494	server MUST NOT fail the request. If the stat failed, the file
	2495	type will be SSH_FILEXFER_TYPE_UNKNOWN. If the client needs to
	2496	distinguish between files that are actually
	2497	SSH_FILEXFER_TYPE_UNKNOWN and paths that don't exist, it will have
	2498	to issue a separate stat command in this case.
	2499
	2500	If SSH_FXP_REALPATH_STAT_ALWAYS is specified the server MUST stat
	2501	the path. If the stat operation fails, the server MUST fail the
	2502	request.
	2503
	2504	compose-path
	2505	A path which the client wishes the server to compose with the
	2506	original path to form the new path. This field is optional, and
	2507	if it is not present in the packet, it is assumed to be a zero
	2508	length string.
	2509
	2510	The client may specify multiple 'compose-path' elements, in which
	2511	case the server should build the resultant path up by applying
	2512	each compose path to the accumulated result until all 'compose-
	2513	path' elements have been applied.
	2514
	2515
	2516
	2517
	2518
	2519	Galbraith & Saarenmaa Expires July 29, 2006 [Page 45]
	2520
	2521	Internet-Draft SSH File Transfer Protocol January 2006
	2522
	2523
	2524	The server MUST take the 'original-path' and apply the 'compose-path'
	2525	as a modification to it. 'compose-path' MAY be relative to 'original-
	2526	path' or may be an absolute path, in which case 'original-path' will
	2527	be discarded. The 'compose-path' MAY be zero length.
	2528
	2529	The server will respond with a SSH_FXP_NAME packet containing the
	2530	canonical form of the composite path. If SSH_FXP_REALPATH_NO_CHECK
	2531	is specified, the attributes are dummy values.
	2532
	2533	8.9.1. Best Practice for Dealing with Paths
	2534
	2535	BEGIN: RFCEDITOR REMOVE BEFORE PUBLISHING
	2536
	2537	Previous to this version, clients typically composed new paths
	2538	themselves and then called both realpath and stat on the resulting
	2539	path to get its canonical name and see if it really existed and was a
	2540	directory.
	2541
	2542	This required clients to assume certain things about how a relative
	2543	vs. realpath looked. The new realpath allows clients to no longer
	2544	make those assumptions and to remove one round trip from the process
	2545	and get deterministic behavior from all servers.
	2546
	2547	END: RFCEDITOR REMOVE BEFORE PUBLISHING
	2548
	2549	The client SHOULD treat the results of SSH_FXP_REALPATH as a
	2550	canonical absolute path, even if the path does not appear to be
	2551	absolute. A client that uses REALPATH(".", "") and treats the result
	2552	as absolute, even if there is no leading slash, will continue to
	2553	function correctly, even when talking to a Windows NT or VMS style
	2554	system, where absolute paths may not begin with a slash.
	2555
	2556	The client SHOULD also use SSH_FXP_REALPATH call to compose paths so
	2557	that it does not need to know when a path is absolute or relative.
	2558
	2559	For example, if the client wishes to change directory up, and the
	2560	server has returned "c:/x/y/z" from REALPATH, the client SHOULD use
	2561	REALPATH("c:/x/y/z", "..", SSH_FXP_REALPATH_STAT_ALWAYS)
	2562
	2563	As a second example, if the client wishes transfer local file "a" to
	2564	remote file "/b/d/e", and server has returned "dka100:/x/y/z" as the
	2565	canonical path of the current directory, the client SHOULD send
	2566	REALPATH("dka100:/x/y/z", "/b/d/e", SSH_FXP_REALPATH_STAT_IF). This
	2567	call will determine the correct path to use for the open request and
	2568	whether the /b/d/e represents a directory.
	2569
	2570
	2571
	2572
	2573
	2574
	2575	Galbraith & Saarenmaa Expires July 29, 2006 [Page 46]
	2576
	2577	Internet-Draft SSH File Transfer Protocol January 2006
	2578
	2579
	2580	9. Responses from the Server to the Client
	2581
	2582	The server responds to the client using one of a few response
	2583	packets. All requests can return a SSH_FXP_STATUS response upon
	2584	failure. When the operation is successful, and no data needs to be
	2585	returned, the SSH_FXP_STATUS response with SSH_FX_OK status is
	2586	appropriate.
	2587
	2588	Exactly one response will be returned for each request. Each
	2589	response packet contains a request identifier which can be used to
	2590	match each response with the corresponding request. Note that it is
	2591	legal to have several requests outstanding simultaneously, and the
	2592	server is allowed to send responses to them in a different order from
	2593	the order in which the requests were sent (the result of their
	2594	execution, however, is guaranteed to be as if they had been processed
	2595	one at a time in the order in which the requests were sent).
	2596
	2597	Response packets are of the same general format as request packets.
	2598	Each response packet begins with the request identifier.
	2599
	2600	9.1. Status Response
	2601
	2602	The format of the data portion of the SSH_FXP_STATUS response is as
	2603	follows:
	2604
	2605	byte SSH_FXP_STATUS
	2606	uint32 request-id
	2607	uint32 error/status code
	2608	string error message (ISO-10646 UTF-8 [RFC-2279])
	2609	string language tag (as defined in [RFC-1766])
	2610	error-specific data
	2611
	2612	request-id
	2613	The 'request-id' specified by the client in the request the server
	2614	is responding to.
	2615
	2616	error/status code
	2617	Machine readable status code indicating the result of the request.
	2618	Error code values are defined below. The value SSH_FX_OK
	2619	indicates success, and all other values indicate failure.
	2620
	2621	Implementations MUST be prepared to receive unexpected error codes
	2622	and handle them sensibly (such as by treating them as equivalent
	2623	to SSH_FX_FAILURE). Future protocol revisions will add additional
	2624	error codes without changing the version number.
	2625
	2626
	2627
	2628
	2629
	2630
	2631	Galbraith & Saarenmaa Expires July 29, 2006 [Page 47]
	2632
	2633	Internet-Draft SSH File Transfer Protocol January 2006
	2634
	2635
	2636	error message
	2637	Human readable description of the error.
	2638
	2639	language tag
	2640	'language tag' specifies the language the error is in.
	2641
	2642	error-specific data
	2643	The error-specific data may be empty, or may contain additional
	2644	information about the error. For error codes that send error-
	2645	specific data, the format of the data is defined below.
	2646
	2647	Error codes:
	2648
	2649	SSH_FX_OK 0
	2650	SSH_FX_EOF 1
	2651	SSH_FX_NO_SUCH_FILE 2
	2652	SSH_FX_PERMISSION_DENIED 3
	2653	SSH_FX_FAILURE 4
	2654	SSH_FX_BAD_MESSAGE 5
	2655	SSH_FX_NO_CONNECTION 6
	2656	SSH_FX_CONNECTION_LOST 7
	2657	SSH_FX_OP_UNSUPPORTED 8
	2658	SSH_FX_INVALID_HANDLE 9
	2659	SSH_FX_NO_SUCH_PATH 10
	2660	SSH_FX_FILE_ALREADY_EXISTS 11
	2661	SSH_FX_WRITE_PROTECT 12
	2662	SSH_FX_NO_MEDIA 13
	2663	SSH_FX_NO_SPACE_ON_FILESYSTEM 14
	2664	SSH_FX_QUOTA_EXCEEDED 15
	2665	SSH_FX_UNKNOWN_PRINCIPAL 16
	2666	SSH_FX_LOCK_CONFLICT 17
	2667	SSH_FX_DIR_NOT_EMPTY 18
	2668	SSH_FX_NOT_A_DIRECTORY 19
	2669	SSH_FX_INVALID_FILENAME 20
	2670	SSH_FX_LINK_LOOP 21
	2671	SSH_FX_CANNOT_DELETE 22
	2672	SSH_FX_INVALID_PARAMETER 23
	2673	SSH_FX_FILE_IS_A_DIRECTORY 24
	2674	SSH_FX_BYTE_RANGE_LOCK_CONFLICT 25
	2675	SSH_FX_BYTE_RANGE_LOCK_REFUSED 26
	2676	SSH_FX_DELETE_PENDING 27
	2677	SSH_FX_FILE_CORRUPT 28
	2678	SSH_FX_OWNER_INVALID 29
	2679	SSH_FX_GROUP_INVALID 30
	2680
	2681
	2682
	2683
	2684
	2685
	2686
	2687	Galbraith & Saarenmaa Expires July 29, 2006 [Page 48]
	2688
	2689	Internet-Draft SSH File Transfer Protocol January 2006
	2690
	2691
	2692	SSH_FX_OK
	2693	Indicates successful completion of the operation.
	2694
	2695	SSH_FX_EOF
	2696	An attempt to read past the end-of-file was made; or, there are no
	2697	more directory entries to return.
	2698
	2699	SSH_FX_NO_SUCH_FILE
	2700	A reference was made to a file which does not exist.
	2701
	2702	SSH_FX_PERMISSION_DENIED
	2703	The user does not have sufficient permissions to perform the
	2704	operation.
	2705
	2706	SSH_FX_FAILURE
	2707	An error occurred, but no specific error code exists to describe
	2708	the failure.
	2709
	2710	This error message SHOULD always have meaningful text in the the
	2711	'error message' field.
	2712
	2713	SSH_FX_BAD_MESSAGE
	2714	A badly formatted packet or other SFTP protocol incompatibility
	2715	was detected.
	2716
	2717	SSH_FX_NO_CONNECTION
	2718	There is no connection to the server. This error MAY be used
	2719	locally, but MUST NOT be return by a server.
	2720
	2721	SSH_FX_CONNECTION_LOST
	2722	The connection to the server was lost. This error MAY be used
	2723	locally, but MUST NOT be return by a server.
	2724
	2725	SSH_FX_OP_UNSUPPORTED
	2726	An attempted operation could not be completed by the server
	2727	because the server does not support the operation.
	2728
	2729	This error MAY be generated locally by the client if e.g. the
	2730	version number exchange indicates that a required feature is not
	2731	supported by the server, or it may be returned by the server if
	2732	the server does not implement an operation.
	2733
	2734	SSH_FX_INVALID_HANDLE
	2735	The handle value was invalid.
	2736
	2737
	2738
	2739
	2740
	2741
	2742
	2743	Galbraith & Saarenmaa Expires July 29, 2006 [Page 49]
	2744
	2745	Internet-Draft SSH File Transfer Protocol January 2006
	2746
	2747
	2748	SSH_FX_NO_SUCH_PATH
	2749	The file path does not exist or is invalid.
	2750
	2751	SSH_FX_FILE_ALREADY_EXISTS
	2752	The file already exists.
	2753
	2754	SSH_FX_WRITE_PROTECT
	2755	The file is on read-only media, or the media is write protected.
	2756
	2757	SSH_FX_NO_MEDIA
	2758	The requested operation cannot be completed because there is no
	2759	media available in the drive.
	2760
	2761	SSH_FX_NO_SPACE_ON_FILESYSTEM
	2762	The requested operation cannot be completed because there is no
	2763	free space on the filesystem.
	2764
	2765	SSH_FX_QUOTA_EXCEEDED
	2766	The operation cannot be completed because it would exceed the
	2767	user's storage quota.
	2768
	2769	SSH_FX_UNKNOWN_PRINCIPAL
	2770	A principal referenced by the request (either the 'owner',
	2771	'group', or 'who' field of an ACL), was unknown. The error
	2772	specific data contains the problematic names. The format is one
	2773	or more:
	2774
	2775	string unknown-name
	2776
	2777	Each string contains the name of a principal that was unknown.
	2778
	2779	SSH_FX_LOCK_CONFLICT
	2780	The file could not be opened because it is locked by another
	2781	process.
	2782
	2783	SSH_FX_DIR_NOT_EMPTY
	2784	The directory is not empty.
	2785
	2786	SSH_FX_NOT_A_DIRECTORY
	2787	The specified file is not a directory.
	2788
	2789	SSH_FX_INVALID_FILENAME
	2790	The filename is not valid.
	2791
	2792
	2793
	2794
	2795
	2796
	2797
	2798
	2799	Galbraith & Saarenmaa Expires July 29, 2006 [Page 50]
	2800
	2801	Internet-Draft SSH File Transfer Protocol January 2006
	2802
	2803
	2804	SSH_FX_LINK_LOOP
	2805	Too many symbolic links encountered.
	2806
	2807	SSH_FX_CANNOT_DELETE
	2808	The file cannot be deleted. One possible reason is that the
	2809	advisory READONLY attribute-bit is set.
	2810
	2811	SSH_FX_INVALID_PARAMETER
	2812	On of the parameters was out of range, or the parameters specified
	2813	cannot be used together.
	2814
	2815	SSH_FX_FILE_IS_A_DIRECTORY
	2816	The specified file was a directory in a context where a directory
	2817	cannot be used.
	2818
	2819	SSH_FX_BYTE_RANGE_LOCK_CONFLICT
	2820	A read or write operation failed because another process's
	2821	mandatory byte-range lock overlaps with the request.
	2822
	2823	SSH_FX_BYTE_RANGE_LOCK_REFUSED
	2824	A request for a byte range lock was refused.
	2825
	2826	SSH_FX_DELETE_PENDING
	2827	An operation was attempted on a file for which a delete operation
	2828	is pending.
	2829
	2830	SSH_FX_FILE_CORRUPT
	2831	The file is corrupt; an filesystem integrity check should be run.
	2832
	2833	SSH_FX_OWNER_INVALID
	2834	The principal specified can not be assigned as an owner of a file.
	2835
	2836	SSH_FX_GROUP_INVALID
	2837	The principal specified can not be assigned as the primary group
	2838	of a file.
	2839
	2840
	2841	9.2. Handle Response
	2842
	2843	The SSH_FXP_HANDLE response has the following format:
	2844
	2845	byte SSH_FXP_HANDLE
	2846	uint32 request-id
	2847	string handle
	2848
	2849
	2850
	2851
	2852
	2853
	2854
	2855	Galbraith & Saarenmaa Expires July 29, 2006 [Page 51]
	2856
	2857	Internet-Draft SSH File Transfer Protocol January 2006
	2858
	2859
	2860	'handle'
	2861	An arbitrary string that identifies an open file or directory on
	2862	the server. The handle is opaque to the client; the client MUST
	2863	NOT attempt to interpret or modify it in any way. The length of
	2864	the handle string MUST NOT exceed 256 data bytes.
	2865
	2866
	2867	9.3. Data Response
	2868
	2869	The SSH_FXP_DATA response has the following format:
	2870
	2871	byte SSH_FXP_DATA
	2872	uint32 request-id
	2873	string data
	2874	bool end-of-file [optional]
	2875
	2876	data
	2877	'data' is an arbitrary byte string containing the requested data.
	2878	The data string may be at most the number of bytes requested in a
	2879	SSH_FXP_READ request, but may also be shorter. (See
	2880	Section 8.2.1.)
	2881
	2882	end-of-file
	2883	This field is optional. If it is present in the packet, it MUST
	2884	be true, and it indicates that EOF was reached during this read.
	2885	This can help the client avoid a round trip to determine whether a
	2886	short read was normal (due to EOF) or some other problem (limited
	2887	server buffer for example.)
	2888
	2889
	2890	9.4. Name Response
	2891
	2892	The SSH_FXP_NAME response has the following format:
	2893
	2894	byte SSH_FXP_NAME
	2895	uint32 request-id
	2896	uint32 count
	2897	repeats count times:
	2898	string filename [UTF-8]
	2899	ATTRS attrs
	2900	bool end-of-list [optional]
	2901
	2902	count
	2903	The number of names returned in this response, and the 'filename'
	2904	and 'attrs' field repeat 'count' times.
	2905
	2906
	2907
	2908
	2909
	2910
	2911	Galbraith & Saarenmaa Expires July 29, 2006 [Page 52]
	2912
	2913	Internet-Draft SSH File Transfer Protocol January 2006
	2914
	2915
	2916	filename
	2917	A file name being returned (for SSH_FXP_READDIR, it will be a
	2918	relative name within the directory, without any path components;
	2919	for SSH_FXP_REALPATH it will be an absolute path name.)
	2920
	2921	attrs
	2922	The attributes of the file as described in Section ''File
	2923	Attributes''.
	2924
	2925	end-of-list
	2926	If this field is present and true, there are no more entries to be
	2927	read.
	2928
	2929
	2930	9.5. Attrs Response
	2931
	2932	The SSH_FXP_ATTRS response has the following format:
	2933
	2934	byte SSH_FXP_ATTRS
	2935	uint32 request-id
	2936	ATTRS attrs
	2937
	2938	attrs
	2939	The returned file attributes as described in Section ''File
	2940	Attributes''.
	2941
	2942
	2943
	2944	10. Extensions
	2945
	2946	The SSH_FXP_EXTENDED request provides a generic extension mechanism
	2947	for adding additional commands.
	2948
	2949	byte SSH_FXP_EXTENDED
	2950	uint32 request-id
	2951	string extended-request
	2952	... any request-specific data ...
	2953
	2954	request-id
	2955	Identifier to be returned from the server with the response.
	2956
	2957	extended-request
	2958	A string naming the extension, following the the DNS extensibility
	2959	naming convention outlined in [RFC4251], or defined by IETF
	2960	consensus.
	2961
	2962
	2963
	2964
	2965
	2966
	2967	Galbraith & Saarenmaa Expires July 29, 2006 [Page 53]
	2968
	2969	Internet-Draft SSH File Transfer Protocol January 2006
	2970
	2971
	2972	request-specific data
	2973	The rest of the request is defined by the extension; servers
	2974	SHOULD NOT attempt to interpret it if they do not recognize the
	2975	'extended-request' name.
	2976
	2977	The server may respond to such requests using any of the response
	2978	packets defined in Section ''Responses from the Server to the
	2979	Client''. Additionally, the server may also respond with a
	2980	SSH_FXP_EXTENDED_REPLY packet, as defined below. If the server does
	2981	not recognize the 'extended-request' name, then the server MUST
	2982	respond with SSH_FXP_STATUS with error/status set to
	2983	SSH_FX_OP_UNSUPPORTED.
	2984
	2985	The SSH_FXP_EXTENDED_REPLY packet can be used to carry arbitrary
	2986	extension-specific data from the server to the client. It is of the
	2987	following format:
	2988
	2989	byte SSH_FXP_EXTENDED_REPLY
	2990	uint32 request-id
	2991	... any request-specific data ...
	2992
	2993	There is a range of packet types reserved for use by extensions. In
	2994	order to avoid collision, extensions that that use additional packet
	2995	types should determine those numbers dynamically.
	2996
	2997	The suggested way of doing this is have an extension request from the
	2998	client to the server that enables the extension; the extension
	2999	response from the server to the client would specify the actual type
	3000	values to use, in addition to any other data.
	3001
	3002	Extension authors should be mindful of the limited range of packet
	3003	types available (there are only 45 values available) and avoid
	3004	requiring a new packet type where possible.
	3005
	3006
	3007	11. Implementation Considerations
	3008
	3009	In order for this protocol to perform well, especially over high
	3010	latency networks, multiple read and write requests should be queued
	3011	to the server.
	3012
	3013	The data size of requests should match the maximum packet size for
	3014	the next layer up in the protocol chain.
	3015
	3016	When implemented over ssh, the best performance should be achieved
	3017	when the data size matches the channel's max packet, and the channel
	3018	window is a multiple of the channel packet size.
	3019
	3020
	3021
	3022
	3023	Galbraith & Saarenmaa Expires July 29, 2006 [Page 54]
	3024
	3025	Internet-Draft SSH File Transfer Protocol January 2006
	3026
	3027
	3028	Implementations MUST be aware that requests do not have to be
	3029	satisfied in the order issued. (See Request Synchronization and
	3030	Reordering (Section 4.1).)
	3031
	3032	Implementations MUST also be aware that read requests may not return
	3033	all the requested data, even if the data is available.
	3034
	3035
	3036	12. IANA Considerations
	3037
	3038	An IANA registry needs to be created containing:
	3039	o The packet types define defined in Section 4.3
	3040	o The extension specified in this draft, which are: 'text-seek',
	3041	'supported2', 'acl-supported', 'newline', 'versions', 'version-
	3042	select', 'filename-charset', 'filename-translation-control'
	3043
	3044
	3045	13. Security Considerations
	3046
	3047	It is assumed that both ends of the connection have been
	3048	authenticated and that the connection has privacy and integrity
	3049	features. Such security issues are left to the underlying transport
	3050	protocol, except to note that if this is not the case, an attacker
	3051	could manipulate files on the server at will and thus wholly
	3052	compromise the server.
	3053
	3054	This protocol provides file system access to arbitrary files on the
	3055	server (constrained only by the server implementation). It is the
	3056	responsibility of the server implementation to enforce any access
	3057	controls that may be required to limit the access allowed for any
	3058	particular user (the user being authenticated externally to this
	3059	protocol, typically using [RFC4252].
	3060
	3061	Extreme care must be used when interpreting file handle strings. In
	3062	particular, care must be taken that a file handle string is valid in
	3063	the context of a given 'file-share' session. For example, the 'file-
	3064	share' server daemon may have files which it has opened for its own
	3065	purposes, and the client must not be able to access these files by
	3066	specifying an arbitrary file handle string.
	3067
	3068	The permission field of the attrib structure (Section 7.6) may
	3069	include the SUID, SGID, and SVTX (sticky) bits. Clients should use
	3070	extreme caution when setting these bits on either remote or local
	3071	files. (I.e., just because a file was SUID on the remote system does
	3072	not necessarily imply that it should be SUID on the local system.)
	3073
	3074	Filesystems often contain entries for objects that are not files at
	3075	all, but are rather devices. For example, it may be possible to
	3076
	3077
	3078
	3079	Galbraith & Saarenmaa Expires July 29, 2006 [Page 55]
	3080
	3081	Internet-Draft SSH File Transfer Protocol January 2006
	3082
	3083
	3084	access serial ports, tape devices, or named pipes using this
	3085	protocol. Servers should exercise caution when granting access to
	3086	such resources. In addition to the dangers inherent in allowing
	3087	access to such a device, some devices may be 'slow', and could cause
	3088	denial of service by causing the server to block for a long period of
	3089	time while I/O is performed to such a device.
	3090
	3091	Servers should take care that file-system quotas are respected for
	3092	users. In addition, implementations should be aware that attacks may
	3093	be possible, or facilitated, by filling a filesystem. For example,
	3094	filling the filesystem where event logging and auditing occurs may,
	3095	at best, cause the system to crash, or at worst, allow the attacker
	3096	to take untraceable actions in the future.
	3097
	3098	Servers should take care that filenames are in their appropriate
	3099	canonical form, and to ensure that filenames not in canonical form
	3100	cannot be used to bypass access checks or controls.
	3101
	3102	If the server implementation limits access to certain parts of the
	3103	file system, extra care must be taken in parsing file names which
	3104	contain the '..' path element, and when following symbolic links,
	3105	shortcuts, or other filesystem objects which might transpose the path
	3106	to refer to an object outside of the restricted area. There have
	3107	been numerous reported security bugs where a ".." in a path name has
	3108	allowed access outside the intended area.
	3109
	3110
	3111	14. Changes from Previous Protocol Versions
	3112
	3113	RFC EDITOR: PLEASE REMOVE ENTIRE SECTION BEFORE PUBLISHING
	3114
	3115	Please refer to the following web page for pervious versions of the
	3116	protocol:
	3117
	3118	http://tools.ietf.org/wg/secsh/draft-ietf-secsh-filexfer/
	3119
	3120	RFC EDITOR: END PLEASE REMOVE ENTIRE SECTION BEFORE PUBLISHING
	3121
	3122
	3123	15. References
	3124
	3125	15.1. Normative References
	3126
	3127	[RFC3010] Shepler, S., Callaghan, B., Robinson, D., Thurlow, R.,
	3128	Beame, C., Eisler, M., and D. Noveck, "NFS version 4
	3129	Protocol", RFC 3010, December 2000.
	3130
	3131	[RFC4251] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH)
	3132
	3133
	3134
	3135	Galbraith & Saarenmaa Expires July 29, 2006 [Page 56]
	3136
	3137	Internet-Draft SSH File Transfer Protocol January 2006
	3138
	3139
	3140	Protocol Architecture", RFC 4251, January 2006.
	3141
	3142	[RFC4253] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH)
	3143	Transport Layer Protocol", RFC 4253, January 2006.
	3144
	3145	[RFC4254] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH)
	3146	Connection Protocol", RFC 4254, January 2006.
	3147
	3148	[IEEE.1003-1.1996]
	3149	Institute of Electrical and Electronics Engineers,
	3150	"Information Technology - Portable Operating System
	3151	Interface (POSIX) - Part 1: System Application Program
	3152	Interface (API) [C Language]", IEEE Standard 1003.2, 1996.
	3153
	3154	15.2. Informative References
	3155
	3156	[RFC1521] Borenstein, N. and N. Freed, "MIME (Multipurpose Internet
	3157	Mail Extensions) Part One: Mechanisms for Specifying and
	3158	Describing the Format of Internet Message Bodies",
	3159	RFC 1521, September 1993.
	3160
	3161	[RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0",
	3162	RFC 2246, January 1999.
	3163
	3164	[RFC2277] Alvestrand, H., "IETF Policy on Character Sets and
	3165	Languages", BCP 18, RFC 2277, January 1998.
	3166
	3167	[RFC4252] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH)
	3168	Authentication Protocol", RFC 4252, January 2006.
	3169
	3170	Trademark notice
	3171
	3172	"ssh" is a registered trademark in the United States and/or other
	3173	countries.
	3174
	3175
	3176
	3177
	3178
	3179
	3180
	3181
	3182
	3183
	3184
	3185
	3186
	3187
	3188
	3189
	3190
	3191	Galbraith & Saarenmaa Expires July 29, 2006 [Page 57]
	3192
	3193	Internet-Draft SSH File Transfer Protocol January 2006
	3194
	3195
	3196	Authors' Addresses
	3197
	3198	Joseph Galbraith
	3199	VanDyke Software
	3200	4848 Tramway Ridge Blvd
	3201	Suite 101
	3202	Albuquerque, NM 87111
	3203	US
	3204
	3205	Phone: +1 505 332 5700
	3206	Email: galb-list@vandyke.com
	3207
	3208
	3209	Oskari Saarenmaa
	3210	F-Secure
	3211	Tammasaarenkatu 7
	3212	Helsinki 00180
	3213	FI
	3214
	3215	Email: oskari.saarenmaa@f-secure.com
	3216
	3217
	3218
	3219
	3220
	3221
	3222
	3223
	3224
	3225
	3226
	3227
	3228
	3229
	3230
	3231
	3232
	3233
	3234
	3235
	3236
	3237
	3238
	3239
	3240
	3241
	3242
	3243
	3244
	3245
	3246
	3247	Galbraith & Saarenmaa Expires July 29, 2006 [Page 58]
	3248
	3249	Internet-Draft SSH File Transfer Protocol January 2006
	3250
	3251
	3252	Intellectual Property Statement
	3253
	3254	The IETF takes no position regarding the validity or scope of any
	3255	Intellectual Property Rights or other rights that might be claimed to
	3256	pertain to the implementation or use of the technology described in
	3257	this document or the extent to which any license under such rights
	3258	might or might not be available; nor does it represent that it has
	3259	made any independent effort to identify any such rights. Information
	3260	on the procedures with respect to rights in RFC documents can be
	3261	found in BCP 78 and BCP 79.
	3262
	3263	Copies of IPR disclosures made to the IETF Secretariat and any
	3264	assurances of licenses to be made available, or the result of an
	3265	attempt made to obtain a general license or permission for the use of
	3266	such proprietary rights by implementers or users of this
	3267	specification can be obtained from the IETF on-line IPR repository at
	3268	http://www.ietf.org/ipr.
	3269
	3270	The IETF invites any interested party to bring to its attention any
	3271	copyrights, patents or patent applications, or other proprietary
	3272	rights that may cover technology that may be required to implement
	3273	this standard. Please address the information to the IETF at
	3274	ietf-ipr@ietf.org.
	3275
	3276
	3277	Disclaimer of Validity
	3278
	3279	This document and the information contained herein are provided on an
	3280	"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
	3281	OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
	3282	ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
	3283	INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
	3284	INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
	3285	WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
	3286
	3287
	3288	Copyright Statement
	3289
	3290	Copyright (C) The Internet Society (2006). This document is subject
	3291	to the rights, licenses and restrictions contained in BCP 78, and
	3292	except as set forth therein, the authors retain all their rights.
	3293
	3294
	3295	Acknowledgment
	3296
	3297	Funding for the RFC Editor function is currently provided by the
	3298	Internet Society.
	3299
	3300
	3301
	3302
	3303	Galbraith & Saarenmaa Expires July 29, 2006 [Page 59]
	3304
	3305

+674

-0

rfc/draft-ietf-secsh-filexfer-extensions-00.txt less more

	0
	1
	2
	3
	4	Secure Shell Working Group J. Galbraith
	5	Internet-Draft VanDyke Software
	6	Expires: July 22, 2006 O. Saarenmaa
	7	F-Secure
	8	January 18, 2006
	9
	10
	11	SSH File Transfer Protocol
	12	draft-ietf-secsh-filexfer-extensions-00.txt
	13
	14	Status of this Memo
	15
	16	By submitting this Internet-Draft, each author represents that any
	17	applicable patent or other IPR claims of which he or she is aware
	18	have been or will be disclosed, and any of which he or she becomes
	19	aware will be disclosed, in accordance with Section 6 of BCP 79.
	20
	21	Internet-Drafts are working documents of the Internet Engineering
	22	Task Force (IETF), its areas, and its working groups. Note that
	23	other groups may also distribute working documents as Internet-
	24	Drafts.
	25
	26	Internet-Drafts are draft documents valid for a maximum of six months
	27	and may be updated, replaced, or obsoleted by other documents at any
	28	time. It is inappropriate to use Internet-Drafts as reference
	29	material or to cite them other than as "work in progress."
	30
	31	The list of current Internet-Drafts can be accessed at
	32	http://www.ietf.org/ietf/1id-abstracts.txt.
	33
	34	The list of Internet-Draft Shadow Directories can be accessed at
	35	http://www.ietf.org/shadow.html.
	36
	37	This Internet-Draft will expire on July 22, 2006.
	38
	39	Copyright Notice
	40
	41	Copyright (C) The Internet Society (2006).
	42
	43	Abstract
	44
	45	The SSH File Transfer Protocol provides a rich infrastructure for
	46	sharing information about files. This document describes several
	47	optional extensions that build on this infrastructure.
	48
	49
	50
	51
	52
	53
	54
	55	Galbraith & Saarenmaa Expires July 22, 2006 [Page 1]
	56
	57	Internet-Draft SSH File Transfer Protocol January 2006
	58
	59
	60	Table of Contents
	61
	62	1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
	63	2. Vendor Id . . . . . . . . . . . . . . . . . . . . . . . . . . 3
	64	3. File Hashing . . . . . . . . . . . . . . . . . . . . . . . . . 4
	65	4. Querying Available Space . . . . . . . . . . . . . . . . . . . 6
	66	5. Querying User Home Directory . . . . . . . . . . . . . . . . . 7
	67	6. Copying Remote Files . . . . . . . . . . . . . . . . . . . . . 7
	68	7. Copying remote data . . . . . . . . . . . . . . . . . . . . . 7
	69	8. Temporary files & directories . . . . . . . . . . . . . . . . 8
	70	9. Security Considerations . . . . . . . . . . . . . . . . . . . 9
	71	10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 9
	72	10.1. Normative References . . . . . . . . . . . . . . . . . . 9
	73	10.2. Informative References . . . . . . . . . . . . . . . . . 9
	74	Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 11
	75	Intellectual Property and Copyright Statements . . . . . . . . . . 12
	76
	77
	78
	79
	80
	81
	82
	83
	84
	85
	86
	87
	88
	89
	90
	91
	92
	93
	94
	95
	96
	97
	98
	99
	100
	101
	102
	103
	104
	105
	106
	107
	108
	109
	110
	111	Galbraith & Saarenmaa Expires July 22, 2006 [Page 2]
	112
	113	Internet-Draft SSH File Transfer Protocol January 2006
	114
	115
	116	1. Introduction
	117
	118	This is a collection of optional extensions to the SSH File Transfer
	119	Protocol [I-D.ietf-secsh-filexfer]. This extensions make it possible
	120	for clients to query the server for additional information which may
	121	not be widely supported, but can increase the quality of the users
	122	experience when the server can support them.
	123
	124
	125	2. Vendor Id
	126
	127	It is often necessary to detect the version of the server so that
	128	bugs can be worked around. This extension allows the client to do
	129	so.
	130
	131	string "vendor-id"
	132	string vendor-structure
	133	string vendor-name [UTF-8]
	134	string product-name [UTF-8]
	135	string product-version [UTF-8]
	136	uint64 product-build-number
	137
	138	vendor-name
	139	Arbitrary name identifying the maker of the product.
	140
	141	product-name
	142	Arbitrary name identifying the product.
	143
	144	product-name
	145	Arbitrary string identifying the version of the product.
	146
	147	product-build-number
	148	A build-number for the product, such that if a bug is fixed in
	149	build-number 'x', it can be assumed that (barring regression in
	150	the product) it is fixed in all build-numbers > 'x'.
	151
	152
	153	This extension may also be sent by the client as a SSH_FXP_EXTENDED
	154	packet; in this case the contents of the vendor-structure become the
	155	extension-specific data:
	156
	157	byte SSH_FXP_EXTENDED
	158	uint32 request-id
	159	string "vendor-id"
	160	string vendor-name [UTF-8]
	161	string product-name [UTF-8]
	162	string product-version [UTF-8]
	163	uint64 product-build-number
	164
	165
	166
	167	Galbraith & Saarenmaa Expires July 22, 2006 [Page 3]
	168
	169	Internet-Draft SSH File Transfer Protocol January 2006
	170
	171
	172	The server responds to this request with a SSH_FXP_STATUS message.
	173	The status SHOULD be SSH_FX_OK.
	174
	175
	176	3. File Hashing
	177
	178	This extension allows a client to easily check if a file (or portion
	179	thereof) that it already has matches what is on the server.
	180
	181	byte SSH_FXP_EXTENDED
	182	uint32 request-id
	183	string "check-file-handle" / "check-file-name"
	184	string handle / name
	185	string hash-algorithm-list
	186	uint64 start-offset
	187	uint64 length
	188	uint32 block-size
	189
	190	handle
	191	For "check-file-handle", 'handle' is an open file handle returned
	192	by SSH_FXP_OPEN. If 'handle' is not a handle returned by
	193	SSH_FXP_OPEN, the server MUST return SSH_FX_INVALID_HANDLE. If
	194	ACE4_READ_DATA was not included when the file was opened, the
	195	server MUST return STATUS_PERMISSION_DENIED.
	196
	197	If this file handle was opened in SSH_FXF_ACCESS_TEXT_MODE mode,
	198	the check must be performed on the data as it would be sent on the
	199	wire.
	200
	201	name
	202	For "check-file-name", 'name' is the path to the file to check.
	203	If 'check-file-name' is a directory, SSH_FX_FILE_IS_A_DIRECTORY
	204	SHOULD be returned. If 'check-file-name' refers to a
	205	SSH_FILEXFER_TYPE_SYMLINK, the target should be opened. The
	206	results are undefined file types other than
	207	SSH_FILEXFER_TYPE_REGULAR.
	208
	209	The file MUST be opened without the SSH_FXF_ACCESS_TEXT_MODE
	210	access flag (in binary mode.)
	211
	212	hash-algorithm-list
	213	A comma separated list of hash algorithms the client is willing to
	214	accept for this operation. The server MUST pick the first hash on
	215	the list that it supports.
	216
	217
	218
	219
	220
	221
	222
	223	Galbraith & Saarenmaa Expires July 22, 2006 [Page 4]
	224
	225	Internet-Draft SSH File Transfer Protocol January 2006
	226
	227
	228	Currently defined algorithms are "md5", "sha1", "sha224",
	229	"sha256", "sha384", "sha512", and "crc32". Additional algorithms
	230	may be added by following the DNS extensibility naming convention
	231	outlined in [RFC4251].
	232
	233	MD5 is described in [RFC1321]. SHA-1, SHA-224, SHA-256, SHA-384,
	234	and SHA-512 are described in [FIPS-180-2]. [ISO.3309.1991]
	235	describes crc32, and is the same algorithm used in [RFC1510]
	236
	237	start-offset
	238	The starting offset of the data to include in the hash.
	239
	240	length
	241	The length of data to include in the hash. If length is zero, all
	242	the data from start-offset to the end-of-file should be included.
	243
	244	block-size
	245	An independent hash MUST be computed over every block in the file.
	246	The size of blocks is specified by block-size. The block-size
	247	MUST NOT be smaller than 256 bytes. If the block-size is 0, then
	248	only one hash, over the entire range, MUST be made.
	249
	250
	251	The response is either a SSH_FXP_STATUS packet, indicating an error,
	252	or the following extended reply packet:
	253
	254	This extension MUST be represented in the "supported2" extension as
	255	"check-file" and both version MUST either be support or neither.
	256
	257	byte SSH_FXP_EXTENDED_REPLY
	258	uint32 request-id
	259	string hash-algo-used
	260	byte hash[n][block-count]
	261
	262	hash-algo-used
	263	The hash algorithm that was actually used.
	264
	265	hash
	266	The computed hashes. The hash algorithm used determines the size
	267	of n. The number of block-size chunks of data in the file
	268	determines block-count. The hashes are placed in the packet one
	269	after another, with no decoration.
	270
	271	Note that if the length of the range is not an even multiple of
	272	block-size, the last hash will have been computed over only the
	273	remainder of the range instead of a full block.
	274
	275
	276
	277
	278
	279	Galbraith & Saarenmaa Expires July 22, 2006 [Page 5]
	280
	281	Internet-Draft SSH File Transfer Protocol January 2006
	282
	283
	284	4. Querying Available Space
	285
	286	The following extension provides a way to discover the available
	287	space for an arbitrary path.
	288
	289	byte SSH_FXP_EXTENDED
	290	uint32 request-id
	291	string "space-available"
	292	string path [UTF-8]
	293
	294	path
	295	'path' for which the available space should be reported. This
	296	'path' is not required to be the mount point path, but MAY be a
	297	directory or file contained within the mount.
	298
	299	The reply to the request is as follows:
	300
	301	byte SSH_FXP_EXTENDED_REPLY
	302	uint32 request-id
	303	uint64 bytes-on-device
	304	uint64 unused-bytes-on-device
	305	uint64 bytes-available-to-user
	306	uint64 unused-bytes-available-to-user
	307	uint32 bytes-per-allocation-unit
	308
	309	bytes-on-device
	310	The total number of bytes on the device which stores 'path', both
	311	used and unused, or 0 if unknown.
	312
	313	unused-bytes-on-device
	314	The total number of unused bytes available on the device which
	315	stores 'path', or 0 if unknown.
	316
	317	bytes-available-to-user
	318	The total number of bytes, both used and unused, available to the
	319	authenticated user on the device which stores 'path', or 0 if
	320	unknown.
	321
	322	unused-bytes-available-to-user
	323	The total number of unused bytes available to the authenticated
	324	user on the device which stores 'path', or 0 if unknown.
	325
	326	bytes-per-allocation-unit
	327	The number of bytes in each allocation unit on the device, or in
	328	other words, the minimum number of bytes that a file allocation
	329	size can grow or shrink by. If the server does not know this
	330	information, or the file-system in use does not use allocation
	331	blocks, this value MUST be 0.
	332
	333
	334
	335	Galbraith & Saarenmaa Expires July 22, 2006 [Page 6]
	336
	337	Internet-Draft SSH File Transfer Protocol January 2006
	338
	339
	340	5. Querying User Home Directory
	341
	342	Many users are used to being able to type '~' as an alias for their
	343	home directory, or ~username as an alias for another user's home
	344	directory. To support this feature, a server MAY support following
	345	extension.
	346
	347	byte SSH_FXP_EXTENDED
	348	uint32 request-id
	349	string "home-directory"
	350	string username [UTF-8]
	351
	352	username
	353	Username whose home directory path is being requested. An empty
	354	string implies the current user.
	355
	356	The reply to the request is either a SSH_FXP_STATUS packet or a
	357	SSH_FXP_NAME packet containing the absolute real-path of the home
	358	directory.
	359
	360
	361	6. Copying Remote Files
	362
	363	byte SSH_FXP_EXTENDED
	364	uint32 request-id
	365	string "copy-file"
	366	string source-file
	367	string destination-file
	368	bool overwrite-destination
	369
	370	This request copies a file from one location to another on the
	371	server. The server responds with SSH_FXP_STATUS.
	372
	373
	374	7. Copying remote data
	375
	376	byte SSH_FXP_EXTENDED
	377	uint32 request-id
	378	string "copy-data"
	379	string read-from-handle
	380	uint64 read-from-offset
	381	uint64 read-data-length
	382	string write-to-handle
	383	uint64 write-to-offset
	384
	385	Copy data from one handle to another on the server. The server
	386	responds with SSH_FXP_STATUS.
	387
	388
	389
	390
	391	Galbraith & Saarenmaa Expires July 22, 2006 [Page 7]
	392
	393	Internet-Draft SSH File Transfer Protocol January 2006
	394
	395
	396	The server MUST copy the data exactly as if the client had issued a
	397	series of SSH_FXP_READ requests on the read-from-handle starting at
	398	read-from-offset and totaling read-data-length bytes, and issued a
	399	series of SSH_FXP_WRITE packets on the write-to-handle, starting at
	400	the write-from-offset, and totaling the total number of bytes read by
	401	the SSH_FXP_READ packets.
	402
	403	If one of the files is open using SSH_FXF_TEXT_MODE, then operation
	404	on that handle honors all of the SSH_FXF_TEXT_MODE behaviors.
	405
	406	The server SHOULD allow 'read-from-handle' and 'write-to-handle' to
	407	be the same handle as long as the range of data is not overlapping.
	408	This allows data to efficiently be moved within a file. The server
	409	MUST fail the request with a SSH_FX_INVALID_PARAMETER if the range is
	410	overlapping and it doesn't correctly handle this case. The server is
	411	not required to detect overlapping ranges if read-from-handle and
	412	write-to-handle are different handles referring to the same file.
	413
	414	If 'data-length' is 0, this imples data should be read until EOF is
	415	encountered.
	416
	417	There are no protocol restictions on this operation; however, the
	418	server MUST ensure that the user does not exceed quota, etc. The
	419	server is, as always, free to complete this operation out of order if
	420	it is too large to complete immediately, or to refuse a request that
	421	is too large.
	422
	423
	424	8. Temporary files & directories
	425
	426	byte SSH_FXP_EXTENDED
	427	uint32 request-id
	428	string "get-temp-folder"
	429
	430	Retrieves the users preferred location for temporary files and
	431	folders. The server responds with SSH_FXP_STATUS or SSH_FXP_NAME
	432	containing the realpath of the preferred location.
	433
	434	byte SSH_FXP_EXTENDED
	435	uint32 request-id
	436	string "make-temp-folder"
	437
	438	Requests that the server create a folder in the users preferred
	439	location for temporary files and folders for use by the client. The
	440	server responds with SSH_FXP_STATUS or SSH_FXP_NAME containing the
	441	realpath of the new folder.
	442
	443	It is the clients responsibility to cleanup and remove the folder
	444
	445
	446
	447	Galbraith & Saarenmaa Expires July 22, 2006 [Page 8]
	448
	449	Internet-Draft SSH File Transfer Protocol January 2006
	450
	451
	452	when it is done with it. However, the server MAY remove the folder
	453	and it's contents when the client closes the connection.
	454
	455
	456	9. Security Considerations
	457
	458	The home directory extension could be used to discover whether a
	459	given user is valid; however, since users are assumed to be
	460	authenticated by the underlying protocol, this is probably not
	461	significant in most situations. If a server would not normally allow
	462	an authenticated user to query the existance of another user, the
	463	server MUST NOT allow the "home-directory" extension.
	464
	465
	466	10. References
	467
	468	10.1. Normative References
	469
	470	[RFC1321] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321,
	471	April 1992.
	472
	473	[RFC1510] Kohl, J. and B. Neuman, "The Kerberos Network
	474	Authentication Service (V5)", RFC 1510, September 1993.
	475
	476	[RFC4251] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH)
	477	Protocol Architecture", RFC 4251, January 2006.
	478
	479	[I-D.ietf-secsh-filexfer]
	480	Galbraith, J. and O. Saarenmaa, "SSH File Transfer
	481	Protocol", draft-ietf-secsh-filexfer-10 (work in
	482	progress), October 2005.
	483
	484	[FIPS-180-2]
	485	National Institute of Standards and Technology, "Secure
	486	Hash Standard (SHS)", Federal Information Processing
	487	Standards Publication 180-2, August 2002.
	488
	489	[ISO.3309.1991]
	490	International Organization for Standardization,
	491	"Information Technology - Telecommunications and
	492	information exchange between systems - High-level data
	493	link control (HDLC) procedures - Frame structure",
	494	ISO Standard 3309, June 1991.
	495
	496	10.2. Informative References
	497
	498	Trademark notice
	499
	500
	501
	502
	503	Galbraith & Saarenmaa Expires July 22, 2006 [Page 9]
	504
	505	Internet-Draft SSH File Transfer Protocol January 2006
	506
	507
	508	"ssh" is a registered trademark in the United States and/or other
	509	countries.
	510
	511
	512
	513
	514
	515
	516
	517
	518
	519
	520
	521
	522
	523
	524
	525
	526
	527
	528
	529
	530
	531
	532
	533
	534
	535
	536
	537
	538
	539
	540
	541
	542
	543
	544
	545
	546
	547
	548
	549
	550
	551
	552
	553
	554
	555
	556
	557
	558
	559	Galbraith & Saarenmaa Expires July 22, 2006 [Page 10]
	560
	561	Internet-Draft SSH File Transfer Protocol January 2006
	562
	563
	564	Authors' Addresses
	565
	566	Joseph Galbraith
	567	VanDyke Software
	568	4848 Tramway Ridge Blvd
	569	Suite 101
	570	Albuquerque, NM 87111
	571	US
	572
	573	Phone: +1 505 332 5700
	574	Email: galb-list@vandyke.com
	575
	576
	577	Oskari Saarenmaa
	578	F-Secure
	579	Tammasaarenkatu 7
	580	Helsinki 00180
	581	FI
	582
	583	Email: oskari.saarenmaa@f-secure.com
	584
	585
	586
	587
	588
	589
	590
	591
	592
	593
	594
	595
	596
	597
	598
	599
	600
	601
	602
	603
	604
	605
	606
	607
	608
	609
	610
	611
	612
	613
	614
	615	Galbraith & Saarenmaa Expires July 22, 2006 [Page 11]
	616
	617	Internet-Draft SSH File Transfer Protocol January 2006
	618
	619
	620	Intellectual Property Statement
	621
	622	The IETF takes no position regarding the validity or scope of any
	623	Intellectual Property Rights or other rights that might be claimed to
	624	pertain to the implementation or use of the technology described in
	625	this document or the extent to which any license under such rights
	626	might or might not be available; nor does it represent that it has
	627	made any independent effort to identify any such rights. Information
	628	on the procedures with respect to rights in RFC documents can be
	629	found in BCP 78 and BCP 79.
	630
	631	Copies of IPR disclosures made to the IETF Secretariat and any
	632	assurances of licenses to be made available, or the result of an
	633	attempt made to obtain a general license or permission for the use of
	634	such proprietary rights by implementers or users of this
	635	specification can be obtained from the IETF on-line IPR repository at
	636	http://www.ietf.org/ipr.
	637
	638	The IETF invites any interested party to bring to its attention any
	639	copyrights, patents or patent applications, or other proprietary
	640	rights that may cover technology that may be required to implement
	641	this standard. Please address the information to the IETF at
	642	ietf-ipr@ietf.org.
	643
	644
	645	Disclaimer of Validity
	646
	647	This document and the information contained herein are provided on an
	648	"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
	649	OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
	650	ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
	651	INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
	652	INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
	653	WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
	654
	655
	656	Copyright Statement
	657
	658	Copyright (C) The Internet Society (2006). This document is subject
	659	to the rights, licenses and restrictions contained in BCP 78, and
	660	except as set forth therein, the authors retain all their rights.
	661
	662
	663	Acknowledgment
	664
	665	Funding for the RFC Editor function is currently provided by the
	666	Internet Society.
	667
	668
	669
	670
	671	Galbraith & Saarenmaa Expires July 22, 2006 [Page 12]
	672
	673

-13

samples/capture_stderr.pl less more

4	4
5	5	use Net::SFTP::Foreign;
6	6	use File::Temp;
7		use IPC::Open3;
8		use IPC::Open2;
9		use Fcntl qw(:mode O_NONBLOCK F_SETFL F_GETFL);
10	7
11		my $hostname = 'localhost';
	8	my $hostname = shift // 'localhost';
12	9
13		my $ssherr = File::Temp->new
14		or die "tempfile failed";
	10	my $ssherr = File::Temp->new or die "tempfile failed";
15	11
16		open my $stderr_save, '>&STDERR' or die "unable to dup STDERR";
17		open STDERR, '>&'.fileno($ssherr);
18
19		my $sftp = Net::SFTP::Foreign->new($hostname, more => qw(-v));
20
21		open STDERR, '>&'.fileno($stderr_save);
	12	my $sftp = Net::SFTP::Foreign->new($hostname, more => qw(-v), stderr_fh => $ssherr);
22	13
23	14	if ($sftp->error) {
24	15	print "sftp error: ".$sftp->error."\n";
25	16	seek($ssherr, 0, 0);
26	17	while (<$ssherr>) {
27		print "error: $_";
	18	print " ssh error: $_";
28	19	}
29	20	}
30	21

-0

samples/psftp less more

0	0	#!/usr/bin/perl
	1
	2	# This script has not being updated and still uses the Net::SFTP API
	3	# available from the adapter module Net::SFTP::Foreign::Compat.
1	4
2	5	use strict;
3	6	use warnings;

+78

-0

samples/resume_put.pl less more

	0	#!/usr/bin/perl
	1
	2	#
	3	# this script is used to test the resume feature of the put method
	4	#
	5
	6	use strict;
	7	use warnings;
	8
	9	@ARGV == 2 or die "Usage:\n resume_put.pl file_len gpg_id\n\n";
	10	my ($len, $id) = @ARGV;
	11
	12	use Net::SFTP::Foreign;
	13
	14	my $base;
	15
	16	our ($a, $b);
	17
	18	use File::Slurp;
	19
	20	sub reset_local {
	21	create_file(@_);
	22	}
	23
	24	sub create_file {
	25	my ($len) = @_;
	26	$base = join '', map { chr rand 256 } 0..100000;
	27	open my $fh, '>', "local.txt";
	28	binmode $fh;
	29	while ($len > 0) {
	30	print $fh substr $base, 0, $len;
	31	$len -= length $base
	32	}
	33	close $fh;
	34	unlink 'local.txt.gpg';
	35	system 'gpg', '--encrypt', '--recipient', $id, 'local.txt';
	36	read_file("local.txt.gpg", binmode => ':raw');
	37	}
	38
	39	open STDERR, ">", "Net-SFTP-Foreign.debug";
	40	$Net::SFTP::Foreign::debug = 3+32+128+4096+16384;
	41
	42	$\| = 1;
	43	my $pwd = `pwd`;
	44	chomp $pwd;
	45	my $i = 1;
	46	eval {
	47	while (1) {
	48	my $s;
	49	my $content = create_file(1 + int rand $len);
	50	my $gpg_len = length $content;
	51	for (1..100) {
	52	my $remote = 1 + int rand length $content;
	53	print STDERR "\n\n############################## ${i}:$remote/$gpg_len ################################\n\n";
	54	print " ${i}:$remote/$gpg_len";
	55	$i++;
	56	$s //= Net::SFTP::Foreign->new('localhost');
	57	$s->setcwd($pwd);
	58
	59	write_file("remote.txt.gpg", {binmode => ':raw'}, substr($content, 0, $remote));
	60	$s->put("local.txt.gpg", "remote.txt.gpg", resume => 1);
	61	if ($s->error) {
	62	print $s->error . "!";
	63	undef $s;
	64	next;
	65	}
	66	my $rcontent = read_file("remote.txt.gpg", binary => ':raw');
	67	unless ($content eq $rcontent and
	68	(stat "remote.txt.gpg")[7] == (stat "local.txt.gpg")[7]) {
	69	die "\ndifferent contents\n";
	70	}
	71	}
	72	}
	73	};
	74	if ($@) {
	75	print $@;
	76	die $@;
	77	}

-1

t/1_run.t less more

128	128	unlink $dlfn1;
129	129	unlink $drfn_l;
130	130	unlink $dlfn;
131
132	131	}
133	132
134	133	# mkdir and rmdir