Changelog

All notable changes to Corkscrew are documented here.

3.0 - 2026-10-23

This release hardens the CONNECT client and relay, adds command-line
compatibility options, and expands continuous integration.

Proxy and relay correctness

• Relay bytes that arrive coalesced with the proxy's CONNECT response instead
  of writing them to standard output during handshake setup.
• Preserve half-close semantics in both directions: a remote write shutdown
  no longer discards input that the caller has not finished sending.
• Apply bounded buffering and backpressure without resetting setup deadlines
  or deadlocking when either standard streams or the proxy socket stall.
• Parse bounded CONNECT responses incrementally, including fragmented status
  lines, split headers, repeated short reads, and interrupted system calls.
• Reject malformed, oversized, prematurely closed, and unsupported proxy
  responses before entering the relay.
• Validate proxy and destination host/port arguments, including bracketed
  IPv6 destinations, and bound TCP connect and handshake deadlines.

Descriptor and signal handling

• Never let the proxy socket alias standard input, standard output, or
  standard error. Reject closed stdin/stdout early and relocate low-numbered
  proxy sockets above the standard error descriptor.
• Handle SIGQUIT like SIGTERM, SIGINT, and SIGHUP. Handle SIGTSTP by restoring
  shared descriptor flags before stopping and reapplying nonblocking mode on
  resume.
• Centralize teardown so credentials, CONNECT request data, and open
  descriptors are cleared or closed on every normal exit path.

Authentication and credentials

• Require positional and --auth-file credential files to be regular files
  with no group or other permission bits.
• Read credentials without an uncleared stdio buffer and clear both the
  plaintext credentials and generated Base64 authorization material before
  the tunnel starts or the process exits.
• Preserve spaces and support LF or CRLF line endings in credential files.
• Add --auth-fd=FD for secret managers and supervisors that pass an
  inherited descriptor. Descriptor mode reads one line, closes the descriptor,
  and deliberately bypasses regular-file and permission checks because pipes
  and other secure descriptors are valid sources.

Command-line interface

• Add -h/--help, -V/--version, and -v/--verbose.
• Add --connect-timeout=SECONDS and --handshake-timeout=SECONDS; both
  default to 10 seconds while the old positional syntax remains unchanged.
• Add --auth-file=FILE as an alternative to the positional auth file.
• Add opt-in --http11 mode, which sends an HTTP/1.1 CONNECT request with
  Host and User-Agent: corkscrew/3.0 headers. The default remains
  HTTP/1.0 for older proxies.
• Reject unknown options, invalid values, duplicate authentication sources,
  and incorrect positional argument counts with exit status 2.

Build, portability, and testing

• Add a real-proxy integration test that uses tinyproxy on loopback when it is
  installed; Linux CI installs tinyproxy and runs the test.
• Add a Clang/libFuzzer harness for the CONNECT response parser, with seed
  inputs and sanitizer coverage in CI.
• Add macOS build and regression jobs; GNU linker fault-injection tests skip
  on platforms without ld --wrap, while portable suites still run.
• Keep GCC and Clang strict-warning builds, AddressSanitizer and
  UndefinedBehaviorSanitizer runs, make check, and make distcheck.
• Add regression coverage for CLI parsing, HTTP/1.1 request headers,
  inherited-descriptor authentication, auth-file options, real proxies,
  descriptor cleanup, handshake deadlines, backpressure, half-close, and
  signal cleanup.
• Install the corkscrew(1) manual page and include the tests, changelog, and
  documentation in source distributions.

Documentation

• Make README.md the canonical README and remove the duplicate legacy
  README.
• Document the complete CLI, authentication modes, timeout behavior,
  HTTP/1.1 compatibility mode, security model, portability status, and
  release tags.
• Add this changelog and update NEWS for the 3.0 release.

2.0 - baseline

The 2.0 tag records the pre-hardening release baseline. The changes above
describe the 3.0 release. The historical v2.0 tag is retained unchanged for
older release references.