From 2b2664bfd4401bebc3e2d82a8b79a34941da3b0a Mon Sep 17 00:00:00 2001 From: Viktor Szakats Date: Fri, 5 Jun 2026 01:37:59 +0200 Subject: [PATCH] include: add deprecated attributes where missing, related doc updates - `libssh2_knownhost_add()`. - `libssh2_poll_channel_read()`. Follow-up to 2b8038e175e030113a0a75592a69cb4f98c23fe1 - `libssh2_sftp_seek()`. Follow-up to 6875285b7184c72184a6d39b1aaed97dd6486661 - `libssh2_sftp_tell()`. Follow-up to 8eba2961acdf223d456172d3034f21865df060c4 - exclude `LIBSSH2_KNOWNHOST_KEY_SSHDSS` and `LIBSSH2_HOSTKEY_TYPE_DSS` macros when `LIBSSH2_NO_DEPRECATED` is set. They are both documented as deprecated in man pages. - disable the above two features when building libssh2 with `LIBSSH2_NO_DEPRECATED`. - TODO: add `libssh2_sign_sk()` for a future rename to `libssh2_userauth_sign_sk()`. - TODO: add remark for `libssh2_session_flag()`. Also considered `libssh2_session_flag()` which is marked for removal in TODO (bab3a30220a49cca25554ea7cd183ff49077e660), but it's the only way to enable compression, which is also used by curl. It needs an API replacement to control compression, or perhaps only deprecate the rest of flags. Closes #1977 --- docs/TODO.md | 7 ++++--- docs/libssh2_poll_channel_read.md | 4 ++++ docs/libssh2_sftp_seek.md | 4 ++++ docs/libssh2_sftp_tell.md | 4 ++++ include/libssh2.h | 10 ++++++++++ include/libssh2_sftp.h | 6 +++++- src/hostkey.c | 4 ++-- src/knownhost.c | 10 +++++----- src/session.c | 4 +++- src/sftp.c | 6 ++++++ 10 files changed, 47 insertions(+), 12 deletions(-) diff --git a/docs/TODO.md b/docs/TODO.md index 5315aeae..0fbe4296 100644 --- a/docs/TODO.md +++ b/docs/TODO.md @@ -45,7 +45,7 @@ SPDX-License-Identifier: BSD-3-Clause * remove the following functions from the API/ABI: ``` libssh2_base64_decode() - libssh2_session_flag() + libssh2_session_flag() (needs replacement for LIBSSH2_FLAG_COMPRESS support) libssh2_channel_handle_extended_data() libssh2_channel_receive_window_adjust() libssh2_poll() @@ -58,8 +58,9 @@ SPDX-License-Identifier: BSD-3-Clause * Rename a few functions: ``` - libssh2_hostkey_hash => libssh2_session_hostkey_hash - libssh2_banner_set => libssh2_session_banner_set + libssh2_hostkey_hash() => libssh2_session_hostkey_hash() + libssh2_banner_set() => libssh2_session_banner_set() + libssh2_sign_sk() => libssh2_userauth_sign_sk() ``` * change `int` to `libssh2_socket_t` in the public API for sockets. diff --git a/docs/libssh2_poll_channel_read.md b/docs/libssh2_poll_channel_read.md index 10ada95b..1a4fd4c7 100644 --- a/docs/libssh2_poll_channel_read.md +++ b/docs/libssh2_poll_channel_read.md @@ -29,6 +29,10 @@ This function is deprecated. Do note use. packets are available to be processed. For full polling support, use *libssh2_poll(3)*. +# AVAILABILITY + +Marked as deprecated since 1.2.0 + # RETURN VALUE Returns 1 when data is available and 0 otherwise. diff --git a/docs/libssh2_sftp_seek.md b/docs/libssh2_sftp_seek.md index 082f86b4..965cfd1a 100644 --- a/docs/libssh2_sftp_seek.md +++ b/docs/libssh2_sftp_seek.md @@ -36,3 +36,7 @@ Note that libssh2 implements file pointers as a localized concept to make file access appear more POSIX like. No packets are exchanged with the server during a seek operation. The localized file pointer is used as a convenience offset during read/write operations. + +# AVAILABILITY + +Marked as deprecated since 1.2.8 diff --git a/docs/libssh2_sftp_tell.md b/docs/libssh2_sftp_tell.md index 4db92874..666b2504 100644 --- a/docs/libssh2_sftp_tell.md +++ b/docs/libssh2_sftp_tell.md @@ -29,6 +29,10 @@ size_t libssh2_sftp_tell(LIBSSH2_SFTP_HANDLE *handle); Returns the current offset of the file handle's internal pointer. Note that this is now deprecated. Use the newer **libssh2_sftp_tell64(3)** instead! +# AVAILABILITY + +Marked as deprecated since 1.0 + # RETURN VALUE Current offset from beginning of file in bytes. diff --git a/include/libssh2.h b/include/libssh2.h index 3df4ca14..f933263d 100644 --- a/include/libssh2.h +++ b/include/libssh2.h @@ -428,7 +428,9 @@ typedef struct _LIBSSH2_POLLFD { /* Hostkey Types */ #define LIBSSH2_HOSTKEY_TYPE_UNKNOWN 0 #define LIBSSH2_HOSTKEY_TYPE_RSA 1 +#ifndef LIBSSH2_NO_DEPRECATED #define LIBSSH2_HOSTKEY_TYPE_DSS 2 /* deprecated */ +#endif #define LIBSSH2_HOSTKEY_TYPE_ECDSA_256 3 #define LIBSSH2_HOSTKEY_TYPE_ECDSA_384 4 #define LIBSSH2_HOSTKEY_TYPE_ECDSA_521 5 @@ -887,8 +889,11 @@ LIBSSH2_API ssize_t libssh2_channel_read_ex(LIBSSH2_CHANNEL *channel, libssh2_channel_read_ex(channel, SSH_EXTENDED_DATA_STDERR, \ buf, buflen) +#ifndef LIBSSH2_NO_DEPRECATED +LIBSSH2_DEPRECATED(1.2.0, "") LIBSSH2_API int libssh2_poll_channel_read(LIBSSH2_CHANNEL *channel, int extended); +#endif LIBSSH2_API unsigned long libssh2_channel_window_read_ex( LIBSSH2_CHANNEL *channel, @@ -1089,19 +1094,24 @@ LIBSSH2_API LIBSSH2_KNOWNHOSTS *libssh2_knownhost_init( #define LIBSSH2_KNOWNHOST_KEY_SHIFT 18 #define LIBSSH2_KNOWNHOST_KEY_RSA1 (1<<18) #define LIBSSH2_KNOWNHOST_KEY_SSHRSA (2<<18) +#ifndef LIBSSH2_NO_DEPRECATED #define LIBSSH2_KNOWNHOST_KEY_SSHDSS (3<<18) /* deprecated */ +#endif #define LIBSSH2_KNOWNHOST_KEY_ECDSA_256 (4<<18) #define LIBSSH2_KNOWNHOST_KEY_ECDSA_384 (5<<18) #define LIBSSH2_KNOWNHOST_KEY_ECDSA_521 (6<<18) #define LIBSSH2_KNOWNHOST_KEY_ED25519 (7<<18) #define LIBSSH2_KNOWNHOST_KEY_UNKNOWN (15<<18) +#ifndef LIBSSH2_NO_DEPRECATED +LIBSSH2_DEPRECATED(1.2.5, "Use libssh2_knownhost_addc()") LIBSSH2_API int libssh2_knownhost_add(LIBSSH2_KNOWNHOSTS *hosts, const char *host, const char *salt, const char *key, size_t keylen, int typemask, struct libssh2_knownhost **store); +#endif /* * libssh2_knownhost_addc() diff --git a/include/libssh2_sftp.h b/include/libssh2_sftp.h index c6967ff3..65878405 100644 --- a/include/libssh2_sftp.h +++ b/include/libssh2_sftp.h @@ -265,12 +265,16 @@ LIBSSH2_API int libssh2_sftp_close_handle(LIBSSH2_SFTP_HANDLE *handle); #define libssh2_sftp_close(handle) libssh2_sftp_close_handle(handle) #define libssh2_sftp_closedir(handle) libssh2_sftp_close_handle(handle) +#ifndef LIBSSH2_NO_DEPRECATED +LIBSSH2_DEPRECATED(1.2.8, "Use libssh2_sftp_seek64()") LIBSSH2_API void libssh2_sftp_seek(LIBSSH2_SFTP_HANDLE *handle, size_t offset); +LIBSSH2_DEPRECATED(1.0, "Use libssh2_sftp_tell64()") +LIBSSH2_API size_t libssh2_sftp_tell(LIBSSH2_SFTP_HANDLE *handle); +#endif LIBSSH2_API void libssh2_sftp_seek64(LIBSSH2_SFTP_HANDLE *handle, libssh2_uint64_t offset); #define libssh2_sftp_rewind(handle) libssh2_sftp_seek64(handle, 0) -LIBSSH2_API size_t libssh2_sftp_tell(LIBSSH2_SFTP_HANDLE *handle); LIBSSH2_API libssh2_uint64_t libssh2_sftp_tell64(LIBSSH2_SFTP_HANDLE *handle); LIBSSH2_API int libssh2_sftp_fstat_ex(LIBSSH2_SFTP_HANDLE *handle, diff --git a/src/hostkey.c b/src/hostkey.c index ea90b949..d005f683 100644 --- a/src/hostkey.c +++ b/src/hostkey.c @@ -1327,7 +1327,7 @@ static int hostkey_type(const unsigned char *hostkey, size_t len) static const unsigned char rsa[] = { 0, 0, 0, 0x07, 's', 's', 'h', '-', 'r', 's', 'a' }; -#if LIBSSH2_DSA +#if LIBSSH2_DSA && !defined(LIBSSH2_NO_DEPRECATED) static const unsigned char dss[] = { 0, 0, 0, 0x07, 's', 's', 'h', '-', 'd', 's', 's' }; @@ -1354,7 +1354,7 @@ static int hostkey_type(const unsigned char *hostkey, size_t len) if(!memcmp(rsa, hostkey, 11)) return LIBSSH2_HOSTKEY_TYPE_RSA; -#if LIBSSH2_DSA +#if LIBSSH2_DSA && !defined(LIBSSH2_NO_DEPRECATED) if(!memcmp(dss, hostkey, 11)) return LIBSSH2_HOSTKEY_TYPE_DSS; #endif diff --git a/src/knownhost.c b/src/knownhost.c index 7a67528b..f2d04c80 100644 --- a/src/knownhost.c +++ b/src/knownhost.c @@ -265,8 +265,9 @@ error: return rc; } +#ifndef LIBSSH2_NO_DEPRECATED /* - * libssh2_knownhost_add + * DEPRECATED, DO NOT USE! * * Add a host and its associated key to the collection of known hosts. * @@ -294,10 +295,9 @@ int libssh2_knownhost_add(LIBSSH2_KNOWNHOSTS *hosts, return knownhost_add(hosts, host, salt, NULL, 0, key, keylen, NULL, 0, typemask, store); } +#endif /* - * libssh2_knownhost_addc - * * Add a host and its associated key to the collection of known hosts. * * Takes a comment argument that may be NULL. A NULL comment indicates @@ -766,7 +766,7 @@ static int hostline(LIBSSH2_KNOWNHOSTS *hosts, key_type = LIBSSH2_KNOWNHOST_KEY_ECDSA_521; else if(!strncmp(key_type_name, "ssh-rsa", key_type_len)) key_type = LIBSSH2_KNOWNHOST_KEY_SSHRSA; -#if LIBSSH2_DSA +#if LIBSSH2_DSA && !defined(LIBSSH2_NO_DEPRECATED) else if(!strncmp(key_type_name, "ssh-dss", key_type_len)) key_type = LIBSSH2_KNOWNHOST_KEY_SSHDSS; #endif @@ -986,7 +986,7 @@ static int knownhost_writeline(LIBSSH2_KNOWNHOSTS *hosts, key_type_name = "ssh-rsa"; key_type_len = 7; break; -#if LIBSSH2_DSA +#if LIBSSH2_DSA && !defined(LIBSSH2_NO_DEPRECATED) case LIBSSH2_KNOWNHOST_KEY_SSHDSS: key_type_name = "ssh-dss"; key_type_len = 7; diff --git a/src/session.c b/src/session.c index c6c5b6f3..7cc2b972 100644 --- a/src/session.c +++ b/src/session.c @@ -1449,7 +1449,10 @@ long libssh2_session_get_read_timeout(LIBSSH2_SESSION *session) return session->packet_read_timeout; } +#ifndef LIBSSH2_NO_DEPRECATED /* + * DEPRECATED, DO NOT USE! + * * Returns 0 if no data is waiting on channel, * non-0 if data is available */ @@ -1506,7 +1509,6 @@ static inline int poll_listener_queued(LIBSSH2_LISTENER *listener) return ssh2_list_first(&listener->queue) ? 1 : 0; } -#ifndef LIBSSH2_NO_DEPRECATED /* * Poll sockets, channels, and listeners for activity */ diff --git a/src/sftp.c b/src/sftp.c index 10941dbb..2eef3879 100644 --- a/src/sftp.c +++ b/src/sftp.c @@ -2525,7 +2525,10 @@ void libssh2_sftp_seek64(LIBSSH2_SFTP_HANDLE *handle, libssh2_uint64_t offset) handle->u.file.eof = FALSE; } +#ifndef LIBSSH2_NO_DEPRECATED /* + * DEPRECATED, DO NOT USE! + * * Set the read/write pointer to an arbitrary position within the file */ void libssh2_sftp_seek(LIBSSH2_SFTP_HANDLE *handle, size_t offset) @@ -2534,6 +2537,8 @@ void libssh2_sftp_seek(LIBSSH2_SFTP_HANDLE *handle, size_t offset) } /* + * DEPRECATED, DO NOT USE! + * * Return the current read/write pointer's offset */ size_t libssh2_sftp_tell(LIBSSH2_SFTP_HANDLE *handle) @@ -2546,6 +2551,7 @@ size_t libssh2_sftp_tell(LIBSSH2_SFTP_HANDLE *handle) should use */ return (size_t)(handle->u.file.offset); } +#endif /* * Return the current read/write pointer's offset