sftp: add users-groups-by-id@openssh.com extension for client

Signed-off-by: Praneeth Sarode <praneethsarode@gmail.com>
Reviewed-by: Jakub Jelen <jjelen@redhat.com>
Reviewed-by: Eshan Kelkar <eshankelkar@galorithm.com>

include/libssh/sftp.h

@@ -79,6 +79,7 @@ typedef struct sftp_status_message_struct* sftp_status_message;
 typedef struct sftp_statvfs_struct* sftp_statvfs_t;
 typedef struct sftp_limits_struct* sftp_limits_t;
 typedef struct sftp_aio_struct* sftp_aio;
+typedef struct sftp_name_id_map_struct *sftp_name_id_map;
 
 struct sftp_session_struct {
     ssh_session session;
@@ -213,6 +214,22 @@ struct sftp_limits_struct {
     uint64_t max_open_handles;    /** maximum number of active handles allowed by server */
 };
 
+/**
+ * @brief SFTP names map structure to store the mapping between ids and names.
+ *
+ * This is mainly for the use of sftp_get_users_groups_by_id() function.
+ */
+struct sftp_name_id_map_struct {
+    /** @brief Count of name-id pairs in the map */
+    uint32_t count;
+
+    /** @brief Array of ids, ids[i] mapped to names[i] */
+    uint32_t *ids;
+
+    /** @brief Array of names, names[i] mapped to ids[i] */
+    char **names;
+};
+
 /**
  * @brief Creates a new sftp session.
  *
@@ -1194,6 +1211,58 @@ LIBSSH_API char *sftp_expand_path(sftp_session sftp, const char *path);
  */
 LIBSSH_API char *sftp_home_directory(sftp_session sftp, const char *username);
 
+/**
+ * @brief Create a new sftp_name_id_map struct.
+ *
+ * @param count         The number of ids/names to store in the map.
+ *
+ * @return              A pointer to the newly allocated sftp_name_id_map
+ * struct.
+ */
+LIBSSH_API sftp_name_id_map sftp_name_id_map_new(uint32_t count);
+
+/**
+ * @brief Free the memory of an allocated `sftp_name_id_map` struct.
+ *
+ * @param  map          A pointer to the `sftp_name_id_map` struct to free.
+ */
+LIBSSH_API void sftp_name_id_map_free(sftp_name_id_map map);
+
+/**
+ * @brief Retrieves usernames and group names based on provided user and group
+ *        IDs.
+ *
+ * The retrieved names are stored in the `names` field of the
+ * `sftp_name_id_map` structure. In case a uid or gid is not found, an empty
+ * string is stored.
+ *
+ * This calls the "users-groups-by-id@openssh.com" extension.
+ * You should check if the extension is supported using:
+ *
+ * @code
+ * int supported = sftp_extension_supported(sftp,
+ * "users-groups-by-id@openssh.com", "1");
+ * @endcode
+ *
+ * @param sftp           The SFTP session handle.
+ *
+ * @param users_map      A pointer to a `sftp_name_id_map` struct with the user
+ *                       IDs. Can be NULL if only group names are needed.
+ *
+ * @param groups_map     A pointer to a `sftp_name_id_map` struct with the group
+ *                       IDs. Can be NULL if only user names are needed.
+ *
+ * @return               0 on success, < 0 on error with ssh and sftp error set.
+ *
+ * @note                 The caller needs to free the memory used for
+ *                       the maps later using `sftp_name_id_map_free()`.
+ *
+ * @see sftp_get_error()
+ */
+LIBSSH_API int sftp_get_users_groups_by_id(sftp_session sftp,
+                                           sftp_name_id_map users_map,
+                                           sftp_name_id_map groups_map);
+
 #ifdef WITH_SERVER
 /**
  * @brief Create a new sftp server session.