include: add deprecated attributes where missing, related doc updates

- `libssh2_knownhost_add()`.
- `libssh2_poll_channel_read()`.
  Follow-up to 2b8038e175
- `libssh2_sftp_seek()`.
  Follow-up to 6875285b71
- `libssh2_sftp_tell()`.
  Follow-up to 8eba2961ac
- 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 (bab3a30220), 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

@@ -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.

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.

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

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.

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()

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,

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

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;

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
  */

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