Prior to this patch, the documentation stated that the `.text` buffers
filled by the API caller are "free(3)d" by libssh2, referring to the
default system deallocator. In reality however, libssh2 was using
`SSH2_FREE*()` to free these buffers, respecting custom allocators, if
set by the user via `libssh2_session_init_ex()`.
libssh2 behaved this way since the initial implementation committed in
da653774aa 2005-06-11, v0.11
Later, examples were added that use `strdup()` to allocate, which was
(and is) accurate because they do not use a custom allocator:
9a1ce06e31 2007-07-22
Then, when the documentation landed, it incorrectly documented
`free(3)`, perhaps basing it on the examples added earlier:
d4aa801f6f 2008-03-08
I assume that callers overriding the custom allocators are more likely
to have fixed their code to adhere with how libssh2 actually behaved,
rather than believing the documentation and live with an allocator
mismatch for all these years.
Therefore I think this is a documentation error, and this patch
addresses this.
Reported-by: Makise Kurisu
Fixes GHSA-p6p8-66vc-3f24
Reverts ce631aafe1#2659
Follow-up to d4aa801f6f
Follow-up to da653774aaCloses#2661
`SSH2_ALLOC()` (or formerly `LIBSSH2_ALLOC()`) is an internal macro, not
available for API users. Mention `LIBSSH2_ALLOC_FUNC` instead to refer
to the custom allocator set via `libssh2_session_init_ex()`. If no
custom allocator was set, it means the default system allocator.
Follow-up to ed439a29bb#698Closes#2660
Plain known-host entries are currently compared as text, so equivalent
expanded and compressed IPv6 literals do not match.
This change keeps the existing exact-string fast path and compares two
valid plain IPv6 literals by their 128-bit address. It also supports
bracketed IPv6 host-and-port entries while requiring the port suffix to
match exactly.
No DNS lookup is performed. Hostname matching and the CUSTOM and hashed
known-host paths remain unchanged.
Reported-by: Krisscut on github
Fixes#1398Closes#2568
`libssh2_channel_get_exit_status()` returns 0 both for a real exit
status of 0 and for a channel that never received an `exit-status`
request. A server that force-closes a session, like OpenSSH under
`ChannelTimeout`, makes a still-running command look like a clean exit
0. Reproduction with the stock `example/ssh2_exec` is in #2515.
This adds `libssh2_channel_has_exit_status()`, returning 1 once the
request arrived, the name you suggested.
The new field sits in `_LIBSSH2_CHANNEL` in `libssh2_priv.h` and callers
only ever hold a pointer, so no ABI change.
`libssh2_channel_get_exit_signal()` already lets a caller see whether
that request arrived by leaving the pointer NULL, exit-status was the
odd one out.
Man page and a `test_exit_status` covering both states are included.
Follow-up to 77bd3c1215Fixes#2515Closes#2516
Drop autotools option `--disable-clear-memory`, CMake option
`-DCLEAR_MEMORY=NO`.
Keep this option always enabled. If there is not API support, use the
local fallback.
Introduce a temporary CPPFLAG to disable system memory clearing
functions, in case they cause a build issue.
Follow-up to a0e424a51c#810Closes#2454
Emails became practically unmanageable. There are many duplicate
reports, often reporting multiple issues per email. Figuring out who
reported what in what order is a challenge, and easy to confuse or miss.
It's also next to impossible to track the status and progress of each
reported issue.
Closes#2413
To have the same root name and same length, to match terms used
elsewhere in the code. To make it easy to identify them in pairs and by
suffix.
Also: move passphrase arg _after_ key source, where missing.
Closes#2362
Replacing various stray error codes and/or calling `ssh2_err()` with
the NULL `session`, resulting in a NULL pointer dereference.
Also:
- return it from `libssh2_trace()` and `libssh2_trace_sethandler()`.
Ref: #2282Closes#2283
To make it easier to keep it in sync with the internals, by being in
scope when grepping src.
Also:
- re-sync for some missed src updates.
- update hash/hmac sections.
- markdownify.
Closes#2268
Returning for example (without newlines):
```
crypto:LibreSSL MD5:off MD5-PEM:off RIPEMD160:off DSA:off
RSA:on RSA-SHA1:on ECDSA:on ED25519:on ML-KEM:off
AES-CTR:on AES-CBC:on BLOWFISH:off RC4:off CAST:off
3DES:off zlib:on clear-memory:on debug-logging:on
```
To allow library users to find out these details, and add a searchable
static string to binaries with this information.
Possible values for `crypto`: `AWS-LC`, `BoringSSL`, `Libgcrypt`,
`LibreSSL`, `mbedTLS`, `OpenSSL`, `OpenSSL/1.1.1`, `OS400QC3`, `WinCNG`,
`wolfSSL`.
Also:
- replace manual translation of crypto engine enum to name in CMake
integration test snippet with the new API.
Fixes#2161Closes#2178
Prior to this patch all per-hash context types in all crypto backends
mapped to the same type per backend. Simplify by replacing per-hash type
with a single type. Aligning this with the hash primitives that were
previously unified everywhere.
If there ever arises a need to support a new crypto backend that only
supports separate types, it can be done by adding a holder type with
unions for example. The general direction of crypto backends though is
to unify hash functions. All currently supported backends do.
Also: scope variables in `KEX_METHOD_SHA_VALUE_HASH()`, fix `{}` nit.
Closes#2163
To allow definining them globally, and avoid reusing macros names
originally defined by OpenSSL.
- rename `<name>_DIGEST_LENGTH` to `SSH2_<name>_DIG_LEN`.
To move to the libssh2 namespace.
- rename `SSH2_SHA_DIG_LEN` to `SSH2_SHA1_DIG_LEN`,
and drop no longer necessary local trick from kex.c.
- deduplicate definitions into `crypto.h`.
- add `SSH2_RIPEMD160_DIG_LEN` and use it.
- mac: replace magic numbers with these macros, where missing.
Closes#2131
To enable support AES-GCM for both, and ed25519 for LibreSSL.
wolfSSL requires this version for AES-GCM due to bug:
https://github.com/wolfSSL/wolfssl/pull/5205
(Before this, libssh2 tests crash with AES-GCM enabled)
Also:
- openssl: add in-source version check for LibreSSL, OpenSSL and
wolfSSL.
- openssl: include `openssl/opensslv.h` to rely on other headers pulling
it in.
- cmake: add version check for wolfSSL.
- mbedtls: do the in-source version check earlier. To match openssl.
- sync up wording for #error messages
Follow-up to 16ef3a2720#2008Closes#2073
- man pages: grammar
- examples: add missing parentheses to macro values
- examples: replace `write()` with `_write()` on Windows.
(to avoid warnings.)
- examples, tests: drop redundant NULL assigments.
- examples: fix to cleanup on error in ssh2_echo, ssh2_exec.
- libssh2.rpgle.in: make hex notation consistent in comment.
- chacha, session.h: avoid comparison with literal NULL.
- prefer 'unrecognized' vs 'unknown' in error messages.
- mbedtls: sync a code pattern with others in the code in
`ssh2_rsa_new()`.
- openssl: declutter and update comment for wolfSSL `HMAC_Update()`
exception. Also drop FIXME as the upstream incompatibility seems
intentional.
- pem, userauth, wincng: fix, clarify error messages.
- wincng: add explanation for `NOLINT` exception, reword another
comment.
(suggested by Copilot)
- misc: drop redundant parentheses.
- test_read: fix a type mismatch.
- openssl: use indexed syntax for readability.
- vms/man2help: fix tool name is help text.
- formatting: reflow, newlines, spaces, comment typos.
Some of these reported by GitHub Code Quality / Copilot.
Closes#2042
- configure: use `dnl`-style comments consistently (where possible).
- configure: drop stray spaces.
- wincng: replace Windows-specific type in `memcpy()` casts.
- drop FIXME added incorrectly in a recent commit.
Follow-up to ecf39b3634#1984
Follow-up to ff50682c23#1679
- replace more synonyms with 'null-terminated'.
- unfold strings, comments and code lines.
- reflow lines, fix indent.
Closes#1995
- fix typos in comments and documentation.
- fix references to non-existing functions in comments.
- libssh2_session_free: fix see-also reference on man page.
- libssh2_scp_recv2: fix typo in prototype on man page.
- man2help: use increment operator.
- badwords: extend with new words and an exclusion.
- userauth: unfold string.
- clang-format and manual formatting.
Closes#1988
- `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
From `_libssh2_*` to `ssh2_*`, `LIBSSH2_*` -> `SSH2_*`. To make the code
easier to read, write, to fit more into the maximum line width without
folding, and to avoid using reserved namespace (`_*`).
Namespacing after this patch:
- `libssh2_`, `LIBSSH2_` (rarely preceded with `_`): public API.
- `ssh2_`, `SSH2_`: private API.
- `ssh2_<crypto-backend>_`: non-static crypto functions.
where `<crypto-backend>` is: lgcr, mbed, ossl, wcng, os400qc3
- local macros and static functions try to be short, descriptive of
their scope, without strict namespacing. They also avoid namespaces
used above for clarity.
Also:
- reflow using clang-format (and manually where necessary.)
- merge split error strings where possible (manually).
- shorten `_libssh2_debug()` to `ssh2_deb()`.
- shorten `_libssh2_error()` to `ssh2_err()`.
- move `libssh2_*` internal symbols to the `ssh2_*` namespace.
- shorten local macro/enum prefixes from `LIBSSH2_` to `SSH2_`.
- mbedtls, wincng: move static functions to the local namespace, where
missing.
- drop stray no-op `ssh2_init_aes_ctr()` symbols (libgcrypt, mbedtls).
- move crypto primitives to crypto-local namespace
`ssh2_(lgcr|mbed|ossl|wcng)_`, where missing.
- normalize crypo-local and crypto-static function namespace to:
`mbed_*`, `ssh2_mbed_,*` `wcng_*`, `ssh2_wcng_*`.
- `LIBSSH2_CIPHER_T()` -> `SSH2_CIPHER_T()`
Follow-up to 689b202320#1923
- rename `ssh2_store_bignum2_bytes()` -> `ssh2_store_bignum_bytes()`.
- drop redundant `void *` cast from `SSH2_UNCONST()` values.
- os400qc3: drop unused static `ssh2_bn_from_bn()`.
- os400qc3: move static `ssh2_bn_resize()` off the ssh2 namespace.
- libssh2.rpgle.in: drop private macros `LIBSSH2_DH_GEX*`.
- rename `ARRAY_SIZE()` to `SSH2_ARRAYSIZE()` for uniqueness.
- agent: drop unused/commented `SSH_AGENTC_*` protocol 1 macros.
- fix stray symbol references found in comments.
- minor whitespace fixes along the way.
Note:
- `ssh2` as a namespace has the minor downside of potential confusion
with SSH protocol 2 (vs 1). In practice I think this is fine.
- `SSH2_` prefix has been used in two places before this patch:
4 `SSH2_AGENT*` macros in `agent.c` and 2 `SSH2_MSG_KEX_ECDH_*` macros
in `libssh2_priv.h`. The latter is coming from
https://datatracker.ietf.org/doc/html/rfc9941. If this ever creates
confusion they can be moved under an `IETF_` namespace for example.
- libssh2_userauth_publickey_sk: the public man page says the callbacks
needs to be using `LIBSSH2_ALLOC()` for allocation and responsible for
freeing. It's an internal macro and should not be mentioned or
necessary in public docs.
Ref: ed439a29bb#698
Follow-up to 8c9b7771ee#1931
Follow-up to 689b202320#1923
Ref: #1949Closes#1961
Based on it having a public man page, it was likely meant to be a public
function. Mark it `LIBSSH2_API` to export it from the DLL on Windows.
Also move its public prototype next to userauth functions, since its
implemented in userauth.c (though not using the namespace).
Follow-up to ed439a29bb#698Closes#1965
Checker script and wordlist comes from curl.
Also:
- checksrc.pl: sync up with curl.
- unfold an IETF URL.
- update all IETF URLs where missing.
Closes#1959
- move return type inline with the declaration.
(for statics and public APIs)
- move `LIBSSH2_API` attribute to distinct lines in definitions.
(This attribute is redundant here and can be deleted in a future commit)
- delete copy of function name from function top comments.
- os400qc3: drop 'libssh2' prefixes for statics.
- move an author name from comment to `AUTHORS`.
- misc formatting fixes along the way.
Closes#1935
To make the code easier to read and write.
Also rename special type macro `_libssh2_cipher_type()` to
`LIBSSH2_CIPHER_T()` for a more macro-like name.
Closes#1923
Notably drop support for Windows XP and older, for old-mingw,
mingw-w64 <=v2.0, and ancient zlib, old Libgrcypt and wolfSSL.
To align with curl, more modern envs, more recent cryptography
implementations, a pending PR, and to reduce the compatibility mix.
Document existing minimums (and maximums) for:
LibreSSL, mbedTLS, OpenSSL, MSVC, CMake
Bump/set minimums for:
- Libgcrypt -> 1.8 (2017-07-18)
Ref: https://www.gnupg.org/download/index.html#end-of-life
Older versions may work.
- mingw-w64 -> 3.0 (2013-09-20) (was: old-mingw and all mingw-w64)
- wolfSSL -> 5.0.0 (2021-11-01)
Older versions may work.
- Windows -> Vista (2006-11-08 - 2012-04-10)
Before this patch, it was undocumented, though wincng internally set
the target version to Vista, when undefined.
Pending patch requiring Vista:
https://github.com/libssh2/libssh2/pull/1893
- zlib -> 1.2.5.2 (2011-12-11)
Document minimums for (adopted from curl):
- clang-tidy
- GNU autotools
- Perl
Also:
- comp: drop zlib compatibility with old versions, require `z_const`.
- wincng: document cutuff versions for compatibility fallbacks.
- wincng: drop support for old-mingw, mingw-w64 <3 and VS2008.
- mingw-w64: always set `_FILE_OFFSET_BITS=64`.
Closes#1919
