sftp: implement posix-rename@openssh.com

Add a new function `libssh2_sftp_posix_rename_ex()` and
`libssh2_sftp_posix_rename()`, which implement
the posix-rename@openssh.com extension.

If the server does not support this extension, the function returns
`LIBSSH2_FX_OP_UNSUPPORTED` and it's up to the user to recover, possibly
by calling `libssh2_sftp_rename()`.

Co-authored-by: Viktor Szakats (bump to size_t)
Closes #1386

docs/Makefile.am

@@ -144,6 +144,8 @@ dist_man_MANS = \
   libssh2_sftp_open_ex_r.3 \
   libssh2_sftp_open_r.3 \
   libssh2_sftp_opendir.3 \
+  libssh2_sftp_posix_rename.3 \
+  libssh2_sftp_posix_rename_ex.3 \
   libssh2_sftp_read.3 \
   libssh2_sftp_readdir.3 \
   libssh2_sftp_readdir_ex.3 \

docs/libssh2_sftp_posix_rename.3

@@ -0,0 +1,24 @@
+.\" Copyright (C) The libssh2 project and its contributors.
+.\" SPDX-License-Identifier: BSD-3-Clause
+.TH libssh2_sftp_posix_rename 3 "9 May 2024" "libssh2 1.11.1" "libssh2"
+.SH NAME
+libssh2_sftp_rename - convenience macro for \fIlibssh2_sftp_posix_rename_ex(3)\fP calls
+.SH SYNOPSIS
+.nf
+#include <libssh2.h>
+#include <libssh2_sftp.h>
+
+int
+libssh2_sftp_posix_rename(LIBSSH2_SFTP *sftp,
+                          const char *source_filename,
+                          const char *destination_filename);
+.fi
+.SH DESCRIPTION
+This is a macro defined in a public libssh2 header file that is using the
+underlying function \fIlibssh2_sftp_posix_rename_ex(3)\fP.
+.SH RETURN VALUE
+See \fIlibssh2_sftp_posix_rename_ex(3)\fP
+.SH ERRORS
+See \fIlibssh2_sftp_posix_rename_ex(3)\fP
+.SH SEE ALSO
+.BR libssh2_sftp_posix_rename_ex(3)

docs/libssh2_sftp_posix_rename_ex.3

@@ -0,0 +1,58 @@
+.\" Copyright (C) The libssh2 project and its contributors.
+.\" SPDX-License-Identifier: BSD-3-Clause
+.TH libssh2_sftp_posix_rename_ex 3 "9 May 2024" "libssh2 1.11.1" "libssh2"
+.SH NAME
+libssh2_sftp_posix_rename_ex - rename an SFTP file using POSIX semantics
+.SH SYNOPSIS
+.nf
+#include <libssh2.h>
+#include <libssh2_sftp.h>
+
+int
+libssh2_sftp_posix_rename_ex(LIBSSH2_SFTP *sftp,
+                             const char *source_filename,
+                             size_t source_filename_len,
+                             const char *dest_filename,
+                             size_t dest_filename_len);
+.fi
+.SH DESCRIPTION
+\fIsftp\fP - SFTP instance as returned by
+.BR libssh2_sftp_init(3)
+
+\fIsourcefile\fP - Path and name of the existing filesystem entry
+
+\fIsourcefile_len\fP - Length of the path and name of the existing
+filesystem entry
+
+\fIdestfile\fP - Path and name of the target filesystem entry
+
+\fIdestfile_len\fP - Length of the path and name of the target
+filesystem entry
+
+This function implements the posix-rename@openssh.com extension, which is
+useful when, for example, moving files across filesystems on a remote server.
+SSH_FXP_RENAME does not specify a specific implementation, but many servers
+will attempt to user hard links when moving files using SSH_FXP_RENAME.
+
+If the server does not support posix-rename@openssh.com, this function will
+return LIBSSH2_FX_OP_UNSUPPORTED and you can call libssh2_sftp_rename_ex (3) as
+a backup.
+.SH RETURN VALUE
+Return 0 on success or negative on failure. It returns
+LIBSSH2_ERROR_EAGAIN when it would otherwise block. While
+LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se.
+.SH ERRORS
+\fILIBSSH2_FX_OP_UNSUPPORTED\fP - Server does not support
+posix-rename@openssh.com
+
+\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed.
+
+\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket.
+
+\fILIBSSH2_ERROR_SOCKET_TIMEOUT\fP -
+
+\fILIBSSH2_ERROR_SFTP_PROTOCOL\fP - An invalid SFTP protocol response was
+received on the socket, or an SFTP operation caused an errorcode to
+be returned by the server.
+.SH SEE ALSO
+.BR libssh2_sftp_init(3)

include/libssh2_sftp.h

@@ -303,6 +303,15 @@ LIBSSH2_API int libssh2_sftp_rename_ex(LIBSSH2_SFTP *sftp,
                            LIBSSH2_SFTP_RENAME_ATOMIC | \
                            LIBSSH2_SFTP_RENAME_NATIVE)
 
+LIBSSH2_API int libssh2_sftp_posix_rename_ex(LIBSSH2_SFTP *sftp,
+                                             const char *source_filename,
+                                             size_t srouce_filename_len,
+                                             const char *dest_filename,
+                                             size_t dest_filename_len);
+#define libssh2_sftp_posix_rename(sftp, sourcefile, destfile) \
+    libssh2_sftp_posix_rename_ex((sftp), (sourcefile), strlen(sourcefile), \
+                                 (destfile), strlen(destfile))
+
 LIBSSH2_API int libssh2_sftp_unlink_ex(LIBSSH2_SFTP *sftp,
                                        const char *filename,
                                        unsigned int filename_len);

src/sftp.c

@@ -47,6 +47,7 @@
 #include "sftp.h"
 
 #include <assert.h>
+#include <stdlib.h>  /* strtol() */
 
 /* This release of libssh2 implements Version 5 with automatic downgrade
  * based on server's declaration
@@ -988,20 +989,42 @@ static LIBSSH2_SFTP *sftp_init(LIBSSH2_SESSION *session)
                    sftp_handle->version));
     while(buf.dataptr < endp) {
         unsigned char *extname, *extdata;
+        size_t extname_len, extdata_len;
+        uint32_t extversion = 0;
 
-        if(_libssh2_get_string(&buf, &extname, NULL)) {
+        if(_libssh2_get_string(&buf, &extname, &extname_len)) {
             LIBSSH2_FREE(session, data);
             _libssh2_error(session, LIBSSH2_ERROR_BUFFER_TOO_SMALL,
                            "Data too short when extracting extname");
             goto sftp_init_error;
         }
 
-        if(_libssh2_get_string(&buf, &extdata, NULL)) {
+        if(_libssh2_get_string(&buf, &extdata, &extdata_len)) {
             LIBSSH2_FREE(session, data);
             _libssh2_error(session, LIBSSH2_ERROR_BUFFER_TOO_SMALL,
                            "Data too short when extracting extdata");
             goto sftp_init_error;
         }
+
+        if(extdata_len > 0) {
+            char *extversion_str;
+            extversion_str = (char *)LIBSSH2_ALLOC(session, extdata_len + 1);
+            if(!extversion_str) {
+                _libssh2_error(session, LIBSSH2_ERROR_ALLOC,
+                               "Unable to allocate memory for SSH_FXP_VERSION "
+                               "packet");
+                goto sftp_init_error;
+            }
+            memcpy(extversion_str, extdata, extdata_len);
+            extversion_str[extdata_len] = '\0';
+            extversion = (uint32_t)strtol(extversion_str, NULL, 10);
+            LIBSSH2_FREE(session, extversion_str);
+        }
+        if(extname_len == 24
+           && strncmp("posix-rename@openssh.com", (char *)extname, 24) == 0) {
+            sftp_handle->posix_rename_version = extversion;
+        }
+
     }
     LIBSSH2_FREE(session, data);
 
@@ -3015,6 +3038,136 @@ libssh2_sftp_rename_ex(LIBSSH2_SFTP *sftp, const char *source_filename,
     return rc;
 }
 
+static int
+sftp_posix_rename(LIBSSH2_SFTP *sftp, const char *source_filename,
+                  size_t source_filename_len,
+                  const char *dest_filename,
+                  size_t dest_filename_len)
+{
+    LIBSSH2_CHANNEL *channel = sftp->channel;
+    LIBSSH2_SESSION *session = channel->session;
+    uint32_t packet_len;
+    size_t data_len = 0;
+    unsigned char *packet, *s, *data = NULL;
+    ssize_t rc;
+    uint32_t retcode;
+
+    if(sftp->posix_rename_version != 1) {
+        return _libssh2_error(session, LIBSSH2_FX_OP_UNSUPPORTED,
+                              "Server does not support"
+                              "posix-rename@openssh.com");
+    }
+
+    if(source_filename_len > UINT32_MAX ||
+       dest_filename_len > UINT32_MAX ||
+       45 + source_filename_len + dest_filename_len > UINT32_MAX) {
+        return _libssh2_error(session, LIBSSH2_ERROR_OUT_OF_BOUNDARY,
+                              "Input too large"
+                              "posix-rename@openssh.com");
+    }
+
+    packet_len = (uint32_t)(45 + source_filename_len + dest_filename_len);
+
+    /* 45 = packet_len(4) + packet_type(1) + request_id(4) +
+       string_len(4) + strlen("posix-rename@openssh.com")(24) +
+       oldpath_len(4) + source_filename_len +
+       newpath_len(4) + dest_filename_len */
+
+    if(sftp->posix_rename_state == libssh2_NB_state_idle) {
+        _libssh2_debug((session, LIBSSH2_TRACE_SFTP,
+                       "Issuing posix_rename command"));
+        s = packet = LIBSSH2_ALLOC(session, packet_len);
+        if(!packet) {
+            return _libssh2_error(session, LIBSSH2_ERROR_ALLOC,
+                                  "Unable to allocate memory for FXP_EXTENDED "
+                                  "packet");
+        }
+
+        _libssh2_store_u32(&s, packet_len - 4);
+        *(s++) = SSH_FXP_EXTENDED;
+        sftp->posix_rename_request_id = sftp->request_id++;
+        _libssh2_store_u32(&s, sftp->posix_rename_request_id);
+        _libssh2_store_str(&s, "posix-rename@openssh.com", 24);
+        _libssh2_store_str(&s, source_filename, source_filename_len);
+        _libssh2_store_str(&s, dest_filename, dest_filename_len);
+
+        sftp->posix_rename_state = libssh2_NB_state_created;
+    }
+    else {
+        packet = sftp->posix_rename_packet;
+    }
+
+    if(sftp->posix_rename_state == libssh2_NB_state_created) {
+        rc = _libssh2_channel_write(channel, 0, packet, packet_len);
+        if(rc == LIBSSH2_ERROR_EAGAIN ||
+            (0 <= rc && rc < (ssize_t)packet_len)) {
+            sftp->posix_rename_packet = packet;
+            return LIBSSH2_ERROR_EAGAIN;
+        }
+
+        LIBSSH2_FREE(session, packet);
+        sftp->posix_rename_packet = NULL;
+
+        if(rc < 0) {
+            sftp->posix_rename_state = libssh2_NB_state_idle;
+            return _libssh2_error(session, LIBSSH2_ERROR_SOCKET_SEND,
+                                  "_libssh2_channel_write() failed");
+        }
+        sftp->posix_rename_state = libssh2_NB_state_sent;
+    }
+
+    rc = sftp_packet_require(sftp, SSH_FXP_STATUS,
+                             sftp->posix_rename_request_id,
+                             &data, &data_len, 9);
+    if(rc == LIBSSH2_ERROR_EAGAIN) {
+        return (int)rc;
+    }
+    else if(rc == LIBSSH2_ERROR_BUFFER_TOO_SMALL) {
+        if(data_len > 0) {
+            LIBSSH2_FREE(session, data);
+        }
+        return _libssh2_error(session, LIBSSH2_ERROR_SFTP_PROTOCOL,
+                              "SFTP posix_rename packet too short");
+    }
+    else if(rc) {
+        sftp->posix_rename_state = libssh2_NB_state_idle;
+        return (int)_libssh2_error(session, (int)rc,
+                                   "Error waiting for FXP EXTENDED REPLY");
+    }
+
+    sftp->posix_rename_state = libssh2_NB_state_idle;
+
+    retcode = _libssh2_ntohu32(data + 5);
+    LIBSSH2_FREE(session, data);
+
+    if(retcode != LIBSSH2_FX_OK) {
+        sftp->last_errno = retcode;
+        return _libssh2_error(session, LIBSSH2_ERROR_SFTP_PROTOCOL,
+                              "posix_rename failed");
+    }
+
+    return 0;
+}
+
+/* libssh2_sftp_posix_rename_ex
+ * Rename a file on the remote server using the posix-rename@openssh.com
+ * extension.
+ */
+LIBSSH2_API int
+libssh2_sftp_posix_rename_ex(LIBSSH2_SFTP *sftp, const char *source_filename,
+                             size_t source_filename_len,
+                             const char *dest_filename,
+                             size_t dest_filename_len)
+{
+    int rc;
+    if(!sftp)
+        return LIBSSH2_ERROR_BAD_USE;
+    BLOCK_ADJUST(rc, sftp->channel->session,
+                 sftp_posix_rename(sftp, source_filename, source_filename_len,
+                                   dest_filename, dest_filename_len));
+    return rc;
+}
+
 /* sftp_fstatvfs
  * Get file system statistics
  */

src/sftp.h

@@ -137,7 +137,7 @@ struct _LIBSSH2_SFTP
 {
     LIBSSH2_CHANNEL *channel;
 
-    uint32_t request_id, version;
+    uint32_t request_id, version, posix_rename_version;
 
     struct list_head packets;
 
@@ -202,6 +202,11 @@ struct _LIBSSH2_SFTP
     unsigned char *rename_s;
     uint32_t rename_request_id;
 
+    /* State variables used in libssh2_sftp_posix_rename_ex() */
+    libssh2_nonblocking_states posix_rename_state;
+    unsigned char *posix_rename_packet;
+    uint32_t posix_rename_request_id;
+
     /* State variables used in libssh2_sftp_fstatvfs() */
     libssh2_nonblocking_states fstatvfs_state;
     unsigned char *fstatvfs_packet;