build: add LIBSSH2_NO_DEPRECATED option (#1266)

The following APIs have been deprecated for over 10 years and
use `LIBSSH2_NO_DEPRECATED` to mark them as deprecated:

libssh2_session_startup()
libssh2_banner_set()
libssh2_channel_receive_window_adjust()
libssh2_channel_handle_extended_data()
libssh2_scp_recv()

Add these options to disable them:
- autotools: `--disable-deprecated`
- cmake: `-DLIBSSH2_NO_DEPRECATED=ON`
- `CPPFLAGS`: `-DLIBSSH2_NO_DEPRECATED`

Fixes #1259
Replaces #1260
Co-authored-by: Viktor Szakats
Closes #1267

.github/workflows/ci.yml

@@ -383,6 +383,7 @@ jobs:
             # template to windres. Reset it to the windres template manually:
             rcopts='<CMAKE_RC_COMPILER> -O coff <DEFINES> <INCLUDES> <FLAGS> <SOURCE> <OBJECT>'
           elif [ '${{ matrix.test }}' = 'no-options' ]; then
+            options="${options} -DLIBSSH2_NO_DEPRECATED=ON"
             cflags='-DLIBSSH2_NO_MD5 -DLIBSSH2_NO_MD5_PEM -DLIBSSH2_NO_HMAC_RIPEMD -DLIBSSH2_NO_DSA -DLIBSSH2_NO_AES_CBC -DLIBSSH2_NO_AES_CTR -DLIBSSH2_NO_BLOWFISH -DLIBSSH2_NO_RC4 -DLIBSSH2_NO_CAST -DLIBSSH2_NO_3DES'
           else
             cflags=''

CMakeLists.txt

@@ -160,6 +160,12 @@ if(ENABLE_DEBUG_LOGGING)
   add_definitions("-DLIBSSH2DEBUG")
 endif()
 
+option(LIBSSH2_NO_DEPRECATED "Build without deprecated APIs" OFF)
+add_feature_info("Without deprecated APIs" LIBSSH2_NO_DEPRECATED "")
+if(LIBSSH2_NO_DEPRECATED)
+  add_definitions("-DLIBSSH2_NO_DEPRECATED")
+endif()
+
 # Auto-detection
 
 # Prefill values with known detection results

configure.ac

@@ -242,6 +242,17 @@ AS_HELP_STRING([--disable-hidden-symbols],[Leave all symbols with default visibi
        AC_MSG_RESULT(no)
 )
 
+dnl Build without deprecated APIs?
+AC_ARG_ENABLE([deprecated],
+  [AS_HELP_STRING([--disable-deprecated], [Build without deprecated APIs @<:@default=no@:>@])],
+  [case "$enableval" in
+    *)
+      with_deprecated="no"
+      CPPFLAGS="$CPPFLAGS -DLIBSSH2_NO_DEPRECATED"
+      ;;
+  esac],
+  [with_deprecated="yes"])
+
 # Build tests?
 AC_ARG_ENABLE([tests],
   [AS_HELP_STRING([--disable-tests], [Disable tests @<:@default=enabled@:>@])],
@@ -427,6 +438,7 @@ AC_MSG_NOTICE([summary of build options:
   Crypto library:   ${found_crypto_str}
   zlib compression: ${found_libz}
   Clear memory:     $enable_clear_memory
+  Deprecated APIs:  $with_deprecated
   Debug build:      $enable_debug
   Build examples:   $build_examples
   Run Docker tests: $run_docker_tests

include/libssh2.h

@@ -618,10 +618,12 @@ LIBSSH2_API void *libssh2_session_callback_set(LIBSSH2_SESSION *session,
                                                int cbtype, void *callback);
 LIBSSH2_API int libssh2_session_banner_set(LIBSSH2_SESSION *session,
                                            const char *banner);
+#ifndef LIBSSH2_NO_DEPRECATED
 LIBSSH2_API int libssh2_banner_set(LIBSSH2_SESSION *session,
                                    const char *banner);
 
 LIBSSH2_API int libssh2_session_startup(LIBSSH2_SESSION *session, int sock);
+#endif
 LIBSSH2_API int libssh2_session_handshake(LIBSSH2_SESSION *session,
                                           libssh2_socket_t sock);
 LIBSSH2_API int libssh2_session_disconnect_ex(LIBSSH2_SESSION *session,
@@ -908,12 +910,13 @@ libssh2_channel_window_read_ex(LIBSSH2_CHANNEL *channel,
 #define libssh2_channel_window_read(channel) \
     libssh2_channel_window_read_ex((channel), NULL, NULL)
 
+#ifndef LIBSSH2_NO_DEPRECATED
 /* libssh2_channel_receive_window_adjust() is DEPRECATED, do not use! */
 LIBSSH2_API unsigned long
 libssh2_channel_receive_window_adjust(LIBSSH2_CHANNEL *channel,
                                       unsigned long adjustment,
                                       unsigned char force);
-
+#endif
 LIBSSH2_API int
 libssh2_channel_receive_window_adjust2(LIBSSH2_CHANNEL *channel,
                                        unsigned long adjustment,
@@ -952,12 +955,15 @@ LIBSSH2_API void libssh2_session_set_read_timeout(LIBSSH2_SESSION* session,
                                                   long timeout);
 LIBSSH2_API long libssh2_session_get_read_timeout(LIBSSH2_SESSION* session);
 
+#ifndef LIBSSH2_NO_DEPRECATED
 /* libssh2_channel_handle_extended_data() is DEPRECATED, do not use! */
 LIBSSH2_API void libssh2_channel_handle_extended_data(LIBSSH2_CHANNEL *channel,
                                                       int ignore_mode);
+#endif
 LIBSSH2_API int libssh2_channel_handle_extended_data2(LIBSSH2_CHANNEL *channel,
                                                       int ignore_mode);
 
+#ifndef LIBSSH2_NO_DEPRECATED
 /* libssh2_channel_ignore_extended_data() is defined below for BC with version
  * 0.1
  *
@@ -970,6 +976,7 @@ LIBSSH2_API int libssh2_channel_handle_extended_data2(LIBSSH2_CHANNEL *channel,
     libssh2_channel_handle_extended_data((channel), (ignore) ?                \
                                        LIBSSH2_CHANNEL_EXTENDED_DATA_IGNORE : \
                                        LIBSSH2_CHANNEL_EXTENDED_DATA_NORMAL)
+#endif
 
 #define LIBSSH2_CHANNEL_FLUSH_EXTENDED_DATA     -1
 #define LIBSSH2_CHANNEL_FLUSH_ALL               -2
@@ -994,10 +1001,12 @@ LIBSSH2_API int libssh2_channel_close(LIBSSH2_CHANNEL *channel);
 LIBSSH2_API int libssh2_channel_wait_closed(LIBSSH2_CHANNEL *channel);
 LIBSSH2_API int libssh2_channel_free(LIBSSH2_CHANNEL *channel);
 
+#ifndef LIBSSH2_NO_DEPRECATED
 /* libssh2_scp_recv is DEPRECATED, do not use! */
 LIBSSH2_API LIBSSH2_CHANNEL *libssh2_scp_recv(LIBSSH2_SESSION *session,
                                               const char *path,
                                               struct stat *sb);
+#endif
 /* Use libssh2_scp_recv2() for large (> 2GB) file support on windows */
 LIBSSH2_API LIBSSH2_CHANNEL *libssh2_scp_recv2(LIBSSH2_SESSION *session,
                                                const char *path,

src/channel.c

@@ -1930,6 +1930,7 @@ _libssh2_channel_receive_window_adjust(LIBSSH2_CHANNEL * channel,
     return 0;
 }
 
+#ifndef LIBSSH2_NO_DEPRECATED
 /*
  * libssh2_channel_receive_window_adjust
  *
@@ -1963,6 +1964,7 @@ libssh2_channel_receive_window_adjust(LIBSSH2_CHANNEL *channel,
        kept for backwards compatibility */
     return rc ? (unsigned long)rc : window;
 }
+#endif
 
 /*
  * libssh2_channel_receive_window_adjust2
@@ -2038,6 +2040,7 @@ libssh2_channel_handle_extended_data2(LIBSSH2_CHANNEL *channel,
     return rc;
 }
 
+#ifndef LIBSSH2_NO_DEPRECATED
 /*
  * libssh2_channel_handle_extended_data
  *
@@ -2054,7 +2057,7 @@ libssh2_channel_handle_extended_data(LIBSSH2_CHANNEL *channel,
 {
     (void)libssh2_channel_handle_extended_data2(channel, ignore_mode);
 }
-
+#endif
 
 
 /*

src/libssh2_priv.h

@@ -489,7 +489,7 @@ struct _LIBSSH2_CHANNEL
     size_t flush_refund_bytes;
     size_t flush_flush_bytes;
 
-    /* State variables used in libssh2_channel_receive_window_adjust() */
+    /* State variables used in libssh2_channel_receive_window_adjust2() */
     libssh2_nonblocking_states adjust_state;
     unsigned char adjust_adjust[9];     /* packet_type(1) + channel(4) +
                                            adjustment(4) */
@@ -744,7 +744,8 @@ struct _LIBSSH2_SESSION
     int socket_state;
     int socket_block_directions;
     int socket_prev_blockstate; /* stores the state of the socket blockiness
-                                   when libssh2_session_startup() is called */
+                                   when libssh2_session_handshake()
+                                   is called */
 
     /* Error tracking */
     const char *err_msg;
@@ -770,7 +771,7 @@ struct _LIBSSH2_SESSION
     unsigned char *kexinit_data;
     size_t kexinit_data_len;
 
-    /* State variables used in libssh2_session_startup() */
+    /* State variables used in libssh2_session_handshake() */
     libssh2_nonblocking_states startup_state;
     unsigned char *startup_data;
     size_t startup_data_len;
@@ -903,7 +904,7 @@ struct _LIBSSH2_SESSION
     size_t sftpInit_sent; /* number of bytes from the buffer that have been
                              sent */
 
-    /* State variables used in libssh2_scp_recv() / libssh_scp_recv2() */
+    /* State variables used in libssh2_scp_recv2() */
     libssh2_nonblocking_states scpRecv_state;
     unsigned char *scpRecv_command;
     size_t scpRecv_command_len;

src/scp.c

@@ -792,6 +792,7 @@ scp_recv_error:
     return NULL;
 }
 
+#ifndef LIBSSH2_NO_DEPRECATED
 /*
  * libssh2_scp_recv
  *
@@ -828,6 +829,7 @@ libssh2_scp_recv(LIBSSH2_SESSION *session, const char *path, struct stat *sb)
 
     return ptr;
 }
+#endif
 
 /*
  * libssh2_scp_recv2

src/session.c

@@ -418,6 +418,7 @@ libssh2_session_banner_set(LIBSSH2_SESSION * session, const char *banner)
     return 0;
 }
 
+#ifndef LIBSSH2_NO_DEPRECATED
 /* libssh2_banner_set
  * Set the local banner. DEPRECATED VERSION
  */
@@ -426,6 +427,7 @@ libssh2_banner_set(LIBSSH2_SESSION * session, const char *banner)
 {
     return libssh2_session_banner_set(session, banner);
 }
+#endif
 
 /*
  * libssh2_session_init_ex
@@ -831,6 +833,7 @@ libssh2_session_handshake(LIBSSH2_SESSION *session, libssh2_socket_t sock)
     return rc;
 }
 
+#ifndef LIBSSH2_NO_DEPRECATED
 /*
  * libssh2_session_startup
  *
@@ -847,6 +850,7 @@ libssh2_session_startup(LIBSSH2_SESSION *session, int sock)
 {
     return libssh2_session_handshake(session, (libssh2_socket_t) sock);
 }
+#endif
 
 /*
  * session_free