diff --git a/Project.toml b/Project.toml index f411014..217ad9d 100644 --- a/Project.toml +++ b/Project.toml @@ -42,7 +42,8 @@ Chairmarks = "0ca39b1e-fe0b-4e98-acfc-b1656634c4de" Harbor = "af79dbb9-1a80-47ad-8928-192a4af69376" Logging = "56ddb016-857b-54e1-b83d-db4d58db5568" Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7" +Sockets = "6462fe0b-24de-5631-8697-dd941f90decc" Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40" [targets] -test = ["Chairmarks", "Harbor", "Logging", "Printf", "Test"] +test = ["Chairmarks", "Harbor", "Logging", "Printf", "Sockets", "Test"] diff --git a/README.md b/README.md index 6c55b10..afb00e1 100644 --- a/README.md +++ b/README.md @@ -64,8 +64,8 @@ client certificates), option files (`option_file`, `read_default_file`), timeout (`connect_timeout`, `read_timeout`, `write_timeout`), `reconnect`, `multi_statements`, `init_command`, decoding policies (`zero_dates`, `time_type`), and memory limits (`max_buffered_bytes`); see the -[documentation](https://mysql.juliadatabases.org/dev/). The transport is TCP or TLS -(Unix sockets, named pipes, and compression are not supported yet and raise clear errors). +[documentation](https://mysql.juliadatabases.org/dev/). The transport is TCP, TLS, or a Unix +socket (named pipes and compression are not supported yet and raise clear errors). Results use the JuliaData value types: text and BLOB columns are zero-copy [DataStrings.jl](https://github.com/JuliaData/DataStrings.jl) `DataString`/`DataBytes` diff --git a/docs/src/index.md b/docs/src/index.md index ced5f3b..50fcbc6 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -23,7 +23,8 @@ using MySQL, DBInterface, Dates # MySQL re-exports Durations.Timestamp conn = DBInterface.connect(MySQL.Connection, "localhost", "user", "password"; db="mydb") ``` -Every host, `"localhost"` included, is dialed over TCP (port 3306 unless `port` is given). +Hosts are dialed over TCP (port 3306 unless `port` is given). To use a local server's Unix +socket, pass its path as `unix_socket` with host `"localhost"`. TLS is used whenever the server offers it (`ssl_mode=:preferred`); see [Connection options](@ref) for the full keyword list. @@ -136,7 +137,8 @@ raise `ArgumentError` unless their value is `nothing` or `false`. |---|---|---| | `db` | `""` | default database (`USE`) | | `port` | `3306` | TCP port; omitted/`nothing` uses file or opt-in environment defaults; `0` explicitly selects 3306 | -| `protocol` | `:default` | `:tcp`, or the deferred `:socket`/`:pipe` (they raise a clear error) | +| `protocol` | `:default` | `:tcp`, `:socket` (a Unix socket for host `"localhost"`, `/tmp/mysql.sock` without `unix_socket`), or the deferred `:pipe` (it raises a clear error) | +| `unix_socket` | `nothing` | Unix socket path, used instead of TCP when the host is `"localhost"` (not on Windows); TLS is not available over a socket | | `bind` | `nothing` | local interface/address to connect from | | `connect_timeout` | `nothing` | positive integer seconds for the whole establishment (dial, TLS, authentication, charset bootstrap) | | `read_timeout`, `write_timeout` | `nothing` | positive integer seconds per transport read/write; expiry closes the connection | @@ -179,7 +181,7 @@ raise `ArgumentError` unless their value is `nothing` or `false`. | keyword | default | meaning | |---|---|---| | `default_auth` | supported server default, else `caching_sha2_password` | plugin to answer the handshake with; an auth switch selects the account's plugin | -| `get_server_public_key` | `false` | fetch the server's RSA key for `caching_sha2`/`sha256` full authentication over plain TCP | +| `get_server_public_key` | `false` | fetch the server's RSA key for `caching_sha2`/`sha256` full authentication without TLS | | `server_public_key` | `nothing` | path of that key in PEM form | | `enable_cleartext_plugin` | `false` | allow `mysql_clear_password` (PAM/LDAP accounts); `default_auth="mysql_clear_password"` also enables it | | `insecure_cleartext_auth` | `false` | allow cleartext authentication without `:verify_identity` | @@ -226,7 +228,7 @@ ignored. This is a subset of the [MySQL option-file format](https://dev.mysql.co Supported file keys are `host`, `user`, `password`, `port`, `database`, `connect-timeout`, `default-character-set`, `protocol`, `bind-address`, `socket`, `tls-version`, `ssl-mode`, `ssl-ca`, `ssl-capath`, `ssl-cert`, and `ssl-key`. Underscores can replace hyphens. -`socket` is accepted but unused. `ssl-cipher`, `ssl-crl`, and `ssl-crlpath` raise an error +`socket` gives the Unix socket path for host `localhost`. `ssl-cipher`, `ssl-crl`, and `ssl-crlpath` raise an error because these settings are unavailable. `compress` also raises an error unless its value is `0`, `OFF`, or `FALSE` (case-insensitive). diff --git a/docs/src/migration.md b/docs/src/migration.md index d6a2e92..0cfaeea 100644 --- a/docs/src/migration.md +++ b/docs/src/migration.md @@ -44,11 +44,16 @@ MySQL.jl 2.0 requires **Julia 1.10 or later**. `"stmt1; stmt2"` by default (an `if/elseif` bug made 1.x enable it silently). 4. **Enum-valued options**: pass Symbols — `ssl_mode=:required` (was `MySQL.API.SSL_MODE_REQUIRED`), `protocol=:tcp` (was `MySQL.API.MYSQL_PROTOCOL_TCP`). -5. **Local servers**: every host, `"localhost"` and `""` included, is dialed over TCP (the - Connector/C rule that turned `localhost` into a Unix socket is gone). The socket and - named-pipe transports are not implemented yet: `protocol=:socket`/`:pipe` or - `named_pipe=true` raise a clear error (an explicit `protocol=:tcp` overrides - `named_pipe`). A `unix_socket` path is accepted but unused. +5. **Local servers**: `"localhost"` and `""` are dialed over TCP unless a socket path is + given. With a path (the `unix_socket` keyword, `socket` in an option file, or + `MYSQL_UNIX_PORT` with `read_env=true`), `localhost` connects through that Unix socket, + as with Connector/C. Without a path, Connector/C used `/tmp/mysql.sock`; MySQL.jl uses + TCP. On Windows, `localhost` always uses TCP. `protocol=:socket` uses a socket, at + `/tmp/mysql.sock` when no path is given, and requires host `localhost`. TLS is not + available over a socket: `ssl_mode=:preferred` connects without it, and a mode or CA + option that requires TLS raises an `ArgumentError`. Named pipes are not + implemented yet: `protocol=:pipe` or `named_pipe=true` raise a clear error (an explicit + `protocol=:tcp` overrides `named_pipe`). TCP access also needs a matching account grant. With `skip_name_resolve`, a `'user'@'localhost'` grant need not cover `127.0.0.1` or `::1`; see [MySQL's host-resolution rules](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_skip_name_resolve). @@ -228,10 +233,9 @@ either `:verify_identity` or `insecure_cleartext_auth=true`. Documented gaps, planned for later 2.x releases — attempting to use them raises a clear error rather than misbehaving: -- **Unix sockets and Windows named pipes** (transport is TCP/TLS). Every host, including - `"localhost"`, is dialed over TCP; asking for the local transport explicitly - (`protocol=:socket`/`:pipe`, or `named_pipe=true` without `protocol=:tcp`) raises a clear error, and a `unix_socket` - path (keyword or option file) is accepted but unused until the transport exists. +- **Windows named pipes** and **TLS over a Unix socket**. `protocol=:pipe`, or + `named_pipe=true` without `protocol=:tcp`, raises a clear error, and so does a TLS + requirement on a socket connection. - **Compression** (`compress=true` is an `ArgumentError`), server cursors / `COM_STMT_FETCH`, query attributes, `COM_STMT_BULK_EXECUTE` - MariaDB `client_ed25519` / PARSEC / `dialog` (PAM) authentication (`UnsupportedAuthError`) diff --git a/src/Protocol/auth.jl b/src/Protocol/auth.jl index 3ef3df3..7b900d6 100644 --- a/src/Protocol/auth.jl +++ b/src/Protocol/auth.jl @@ -1,12 +1,12 @@ # Authentication plugins and the authentication exchange. # -# Per-plugin transport-security rules (TCP only; Unix sockets/named pipes are deferred): +# Per-plugin transport-security rules, as the server applies them: # -# | plugin step | TLS (any mode) | plain TCP | -# |--------------------------------------|----------------------------------------|----------------------| -# | caching_sha2 full auth (cleartext) | allowed | RSA path (opt-in) | -# | sha256 full auth (cleartext) | allowed | RSA path (opt-in) | -# | mysql_clear_password | :verify_identity only, else opt-in | opt-in only | +# | plugin step | TLS (any mode) | Unix socket | plain TCP | +# |------------------------------------|------------------------------------|-------------------|-------------------| +# | caching_sha2 full auth (cleartext) | allowed | allowed | RSA path (opt-in) | +# | sha256 full auth (cleartext) | allowed | RSA path (opt-in) | RSA path (opt-in) | +# | mysql_clear_password | :verify_identity only, else opt-in | opt-in only | opt-in only | # # The RSA path needs `server_public_key` (PEM) or `get_server_public_key=true`; the cleartext # plugin needs explicit enablement (`enable_cleartext_plugin` or `default_auth`). @@ -14,10 +14,12 @@ """ AuthPolicy(; secure_transport=false, identity_verified=false, server_public_key=nothing, get_server_public_key=false, enable_cleartext_plugin=false, - insecure_cleartext_auth=false) + insecure_cleartext_auth=false, local_socket=false) Connection-level facts and user policy the plugins consult. `secure_transport` is true on -TLS (any mode); `identity_verified` only under `ssl_mode = :verify_identity`. +TLS (any mode); `identity_verified` only under `ssl_mode = :verify_identity`. `local_socket` +is true on a Unix socket, which the server counts as secure for `caching_sha2_password` +only; `sha256_password` still requires TLS for a cleartext password. """ struct AuthPolicy secure_transport::Bool @@ -26,11 +28,12 @@ struct AuthPolicy get_server_public_key::Bool enable_cleartext_plugin::Bool insecure_cleartext_auth::Bool + local_socket::Bool end -function AuthPolicy(; secure_transport::Bool=false, identity_verified::Bool=false, server_public_key::Union{Nothing, AbstractVector{UInt8}, AbstractString}=nothing, get_server_public_key::Bool=false, enable_cleartext_plugin::Bool=false, insecure_cleartext_auth::Bool=false) +function AuthPolicy(; secure_transport::Bool=false, identity_verified::Bool=false, server_public_key::Union{Nothing, AbstractVector{UInt8}, AbstractString}=nothing, get_server_public_key::Bool=false, enable_cleartext_plugin::Bool=false, insecure_cleartext_auth::Bool=false, local_socket::Bool=false) pem = server_public_key === nothing ? nothing : server_public_key isa AbstractString ? Vector{UInt8}(codeunits(server_public_key)) : Vector{UInt8}(server_public_key) - return AuthPolicy(secure_transport, identity_verified, pem, get_server_public_key, enable_cleartext_plugin, insecure_cleartext_auth) + return AuthPolicy(secure_transport, identity_verified, pem, get_server_public_key, enable_cleartext_plugin, insecure_cleartext_auth, local_socket) end abstract type AuthPlugin end @@ -177,7 +180,7 @@ cleartext_password(password::AbstractVector{UInt8}) = return nul_terminated_pass # ---- policy ---- -@noinline rsa_unavailable(plugin::String) = return throw(AuthError("$plugin requires a secure connection for full authentication; over plain TCP pass `server_public_key=` or `get_server_public_key=true` to use RSA password exchange, or connect with `ssl_mode=:required`")) +@noinline rsa_unavailable(plugin::String) = return throw(AuthError("$plugin requires a secure connection for full authentication; without TLS pass `server_public_key=` or `get_server_public_key=true` to use RSA password exchange, or connect over TCP with `ssl_mode=:required`")) function require_cleartext_allowed(policy::AuthPolicy) policy.enable_cleartext_plugin || throw(AuthError("the server requested mysql_clear_password, which is disabled; pass `enable_cleartext_plugin=true` (or `default_auth=\"mysql_clear_password\"`)")) @@ -253,7 +256,7 @@ function step!(::CachingSha2Password, state::AuthState, data::AbstractVector{UIn end data[1] == CACHING_SHA2_PERFORM_FULL_AUTH || protocol_error("unexpected caching_sha2_password status byte 0x$(string(data[1], base=16, pad=2))") state.full_auth = true - policy.secure_transport && return cleartext_password(password) + (policy.secure_transport || policy.local_socket) && return cleartext_password(password) policy.server_public_key === nothing || return rsa_encrypt_password(password, state.nonce, policy.server_public_key) if policy.get_server_public_key state.awaiting_public_key = true @@ -281,7 +284,7 @@ function trace_event(state::AuthState, data::AbstractVector{UInt8}, policy::Auth isempty(data) && return :continue data[1] == CACHING_SHA2_FAST_AUTH_SUCCESS && return :fast_auth data[1] == CACHING_SHA2_PERFORM_FULL_AUTH || return :continue - policy.secure_transport && return :full_auth_cleartext + (policy.secure_transport || policy.local_socket) && return :full_auth_cleartext state.awaiting_public_key && return :rsa_request return :full_auth_rsa end diff --git a/src/Protocol/tls.jl b/src/Protocol/tls.jl index 6452e54..d1c96c1 100644 --- a/src/Protocol/tls.jl +++ b/src/Protocol/tls.jl @@ -118,6 +118,7 @@ end raw_tcp(t::Reseau.TCP.Conn) = return t raw_tcp(t::FaultTransport) = return t.inner isa Reseau.TCP.Conn ? t.inner : throw(ArgumentError("STARTTLS needs a TCP transport")) +raw_tcp(::Reseau.Unix.Conn) = throw(ArgumentError("STARTTLS needs a TCP transport")) raw_tcp(::Reseau.TLS.Conn) = return throw(ArgumentError("the session is already on TLS")) function socket_fd(tcp::Reseau.TCP.Conn) @@ -142,7 +143,7 @@ function has_pending_tcp_bytes(tcp::Reseau.TCP.Conn) end is_secure_transport(t::Reseau.TLS.Conn) = return true -is_secure_transport(t::Reseau.TCP.Conn) = return false +is_secure_transport(t::Union{Reseau.TCP.Conn, Reseau.Unix.Conn}) = return false is_secure_transport(t::FaultTransport) = return t.inner isa Reseau.TLS.Conn is_secure_transport(s::Session) = return is_secure_transport(s.transport) diff --git a/src/Protocol/transport.jl b/src/Protocol/transport.jl index 2ce7853..6580e4f 100644 --- a/src/Protocol/transport.jl +++ b/src/Protocol/transport.jl @@ -1,6 +1,5 @@ # Transports the session can own. A concrete union keeps the packet hot path an `isa` split -# (no abstract-typed field). Unix sockets / named pipes are deferred, so there is no -# `Sockets` dependency. +# (no abstract-typed field). """ FaultTransport(inner; fail_read_at=-1, fail_write_at=-1, read_error, write_error, after_write_error=nothing, discard_writes=false) @@ -18,8 +17,8 @@ Test-only transport wrapper that injects faults at byte offsets: Byte counters are plain integers (a `FaultTransport` is used from one task); `close_count` is atomic because the reaper's timer task may race an explicit close in tests. """ -mutable struct FaultTransport{T <: IO} <: IO - inner::T +mutable struct FaultTransport <: IO + inner::Union{IOBuffer, Reseau.TCP.Conn} read_bytes::Int write_bytes::Int fail_read_at::Int @@ -32,14 +31,15 @@ mutable struct FaultTransport{T <: IO} <: IO @atomic close_count::Int end -function FaultTransport(inner::IO; fail_read_at::Integer=-1, fail_write_at::Integer=-1, read_error::Exception=EOFError(), write_error::Exception=EOFError(), after_write_error::Union{Nothing, Exception}=nothing, discard_writes::Bool=false) - return FaultTransport{typeof(inner)}(inner, 0, 0, Int(fail_read_at), Int(fail_write_at), read_error, write_error, after_write_error, false, discard_writes, 0) +function FaultTransport(inner::Union{IOBuffer, Reseau.TCP.Conn}; fail_read_at::Integer=-1, fail_write_at::Integer=-1, read_error::Exception=EOFError(), write_error::Exception=EOFError(), after_write_error::Union{Nothing, Exception}=nothing, discard_writes::Bool=false) + return FaultTransport(inner, 0, 0, Int(fail_read_at), Int(fail_write_at), read_error, write_error, after_write_error, false, discard_writes, 0) end -# A closed union of concrete types: the packet hot path stays an `isa` split, `--trim=safe` -# can resolve every transport operation statically, and no transport type (so no `close` -# method) can be defined after the reaper's timer task fixes its world age. -const Transport = Union{Reseau.TCP.Conn, Reseau.TLS.Conn, FaultTransport{IOBuffer}, FaultTransport{Reseau.TCP.Conn}} +# A closed union of four concrete types, Julia's limit for splitting a union into static +# calls: the packet hot path stays an `isa` split, `--trim=safe` can resolve every transport +# operation statically, and no transport type (so no `close` method) can be defined after the +# reaper's timer task fixes its world age. +const Transport = Union{Reseau.TCP.Conn, Reseau.TLS.Conn, Reseau.Unix.Conn, FaultTransport} function Base.unsafe_read(ft::FaultTransport, ptr::Ptr{UInt8}, nbytes::UInt) n = Int(nbytes) @@ -95,7 +95,7 @@ end # Whether the packet reader may batch reads through its read buffer (Reseau's `unsafe_read` # costs one `recv` per call, so per-packet exact reads dominate large scans; §8.9). The # test-only `FaultTransport` stays byte-exact so fault byte offsets remain deterministic. -supports_buffered_reads(::Union{Reseau.TCP.Conn, Reseau.TLS.Conn}) = return true +supports_buffered_reads(::Union{Reseau.TCP.Conn, Reseau.Unix.Conn, Reseau.TLS.Conn}) = return true supports_buffered_reads(::FaultTransport) = return false # A socket error on an open connection (a reset or broken pipe; under TLS the cause of a @@ -108,7 +108,7 @@ supports_buffered_reads(::FaultTransport) = return false end # Reads 1..n available bytes into `buf[offset:end]` (one transport read); 0 means EOF. -function transport_read_some!(t::Union{Reseau.TCP.Conn, Reseau.TLS.Conn}, buf::Vector{UInt8}, offset::Int, n::Int) +function transport_read_some!(t::Union{Reseau.TCP.Conn, Reseau.Unix.Conn, Reseau.TLS.Conn}, buf::Vector{UInt8}, offset::Int, n::Int) try return Base.readbytes!(t, view(buf, offset:lastindex(buf)), n; all=false) catch err @@ -152,6 +152,11 @@ function set_read_deadline!(t::Reseau.TCP.Conn, deadline_ns::Integer) return nothing end +function set_read_deadline!(t::Reseau.Unix.Conn, deadline_ns::Integer) + Reseau.Unix.set_read_deadline!(t, deadline_ns) + return nothing +end + function set_read_deadline!(t::Reseau.TLS.Conn, deadline_ns::Integer) Reseau.TLS.set_read_deadline!(t, deadline_ns) return nothing @@ -167,6 +172,11 @@ function set_write_deadline!(t::Reseau.TCP.Conn, deadline_ns::Integer) return nothing end +function set_write_deadline!(t::Reseau.Unix.Conn, deadline_ns::Integer) + Reseau.Unix.set_write_deadline!(t, deadline_ns) + return nothing +end + function set_write_deadline!(t::Reseau.TLS.Conn, deadline_ns::Integer) Reseau.TLS.set_write_deadline!(t, deadline_ns) return nothing diff --git a/src/connect.jl b/src/connect.jl index eab298c..18adf02 100644 --- a/src/connect.jl +++ b/src/connect.jl @@ -142,7 +142,18 @@ function dial_with_bind(address::String, deadline::Int64, bind::String, local_ad throw(first_err::Exception) end +function dial_unix(path::String, deadline::Int64) + try + deadline == 0 && return Reseau.Unix.connect(path) + return Reseau.Unix.connect(path; timeout_ns=remaining_ns(deadline)) + catch err + P.is_deadline_error(err) && throw(P.TimeoutError("connect_timeout expired while connecting to $path")) + rethrow() + end +end + function dial(opts::ConnectOptions, deadline::Int64) + opts.unix_socket === nothing || return dial_unix(opts.unix_socket, deadline) address = hostport(opts.host, opts.port) try local_addrs = resolve_bind(opts.bind, deadline) @@ -296,14 +307,14 @@ everything up to the bootstrap as a single deadline; afterwards `read_timeout` a """ function connect(opts::ConnectOptions) deadline = deadline_from(opts.connect_timeout) - tcp = dial(opts, deadline) - s = P.Session(tcp; limits=opts.limits, capabilities=opts.client_flags, debug=opts.debug) + conn = dial(opts, deadline) + s = P.Session(conn; limits=opts.limits, capabilities=opts.client_flags, debug=opts.debug) try - deadline == 0 || apply_deadline!(tcp, deadline) + deadline == 0 || apply_deadline!(conn, deadline) P.read_greeting!(s) secure = P.starttls!(s, opts.tls, opts.host; handshake_timeout_ns=deadline == 0 ? 0 : remaining_ns(deadline)) (secure && deadline != 0) && apply_deadline!(s.transport, deadline) - policy = P.AuthPolicy(opts.auth.secure_transport || secure, secure && opts.tls.mode == P.SSL_VERIFY_IDENTITY, opts.auth.server_public_key, opts.auth.get_server_public_key, opts.auth.enable_cleartext_plugin, opts.auth.insecure_cleartext_auth) + policy = P.AuthPolicy(opts.auth.secure_transport || secure, secure && opts.tls.mode == P.SSL_VERIFY_IDENTITY, opts.auth.server_public_key, opts.auth.get_server_public_key, opts.auth.enable_cleartext_plugin, opts.auth.insecure_cleartext_auth, opts.unix_socket !== nothing) trace = Symbol[] ok = P.authenticate!(s, opts.user, opts.password, policy; db=opts.db, attrs=opts.attrs, default_auth=opts.default_auth, trace=trace) bootstrapped = try diff --git a/src/options.jl b/src/options.jl index 9c41e82..de823e7 100644 --- a/src/options.jl +++ b/src/options.jl @@ -2,6 +2,8 @@ # keywords, the ssl conflict table, option files, and the opt-in environment defaults. const DEFAULT_PORT = 3306 +# Connector/C's default Unix socket path (`MYSQL_UNIX_ADDR`). +const DEFAULT_SOCKET = "/tmp/mysql.sock" const UTF8MB4 = "utf8mb4" # Concrete box for the user-supplied `local_infile_handler` callable: the field type stays @@ -19,6 +21,7 @@ Validated, fully resolved connection parameters (see `ConnectOptions(host, user, struct ConnectOptions host::String port::Int + unix_socket::Union{Nothing, String} # the socket path; `nothing` dials TCP user::String password::Union{Nothing, String} db::String @@ -72,8 +75,7 @@ const DEPRECATED_KEYWORDS = Dict{Symbol, String}( ) const DEFERRED_KEYWORDS = Dict{Symbol, String}( - :unix_socket => "Unix-domain sockets are not supported yet (TCP only; `localhost` is dialed over TCP)", - :named_pipe => "named pipes are not supported yet (TCP only; `localhost` is dialed over TCP)", + :named_pipe => "named pipes are not supported yet; use TCP or, outside Windows, a Unix socket", ) const KNOWN_KEYWORDS = Set{Symbol}([ @@ -189,23 +191,22 @@ end return p end -# Transport selection. Every host, `localhost` included, is dialed over TCP (or TLS on TCP): -# the local transports are chosen only by an explicit request — `protocol=:socket`/`:pipe` -# or `named_pipe=true` — and, being deferred, that request is an error that says so. (A -# `unix_socket` path is accepted and reserved for the socket transport; Connector/C also -# ignored it for TCP hosts.) -function select_transport(protocol; named_pipe::Bool=false) - kind = protocol_kind(protocol) - kind == :default || return kind - return named_pipe ? :pipe : :tcp -end - -function require_tcp_transport(protocol; named_pipe::Bool=false) - transport = select_transport(protocol; named_pipe=named_pipe) - transport == :tcp && return nothing - transport == :socket && deferred_keyword(:unix_socket) - transport == :pipe && deferred_keyword(:named_pipe) - throw(ArgumentError("the `$transport` protocol is not available: the native backend currently supports TCP only")) +# Transport selection, as in Connector/C. A Unix socket reaches only the local server, so it +# needs host `localhost`. `protocol=:socket` uses one, and with the default protocol +# `localhost` uses one when a socket path is given: the `unix_socket` keyword, `socket` in an +# option file, or `MYSQL_UNIX_PORT` with `read_env=true`. Every other host, `localhost` +# without a path, and any default-protocol connection on Windows are dialed over TCP. +# Returns the socket path, or `nothing` for TCP. +function socket_path(kind::Symbol, named_pipe::Bool, host::String, unix_socket::Union{Nothing, String}, read_env::Bool)::Union{Nothing, String} + (kind == :default && named_pipe) && (kind = :pipe) + kind == :pipe && deferred_keyword(:named_pipe) + kind == :memory && throw(ArgumentError("the `memory` protocol (shared memory) is not available in the native backend")) + kind == :tcp && return nothing + path = unix_socket !== nothing ? unix_socket : read_env ? get(ENV, "MYSQL_UNIX_PORT", nothing) : nothing + (kind == :default && (Sys.iswindows() || host != "localhost" || path === nothing)) && return nothing + Sys.iswindows() && throw(ArgumentError("Unix sockets are not available on Windows; use protocol=:tcp")) + host == "localhost" || throw(ArgumentError("protocol=:socket connects to the local server, so the host must be \"localhost\", not $(repr(host))")) + return path === nothing ? DEFAULT_SOCKET : path end # ---- ssl conflict table ---- @@ -491,13 +492,15 @@ function ConnectOptions(host::AbstractString, user::AbstractString, password::Un pick(k) = return haskey(kwd, k) && kwd[k] !== nothing ? kwd[k] : get(file, k, nothing) host_s = String(host) host_s == "" && haskey(file, :host) && (host_s = file[:host]) - require_tcp_transport(protocol_kind(pick(:protocol)); named_pipe=option_bool_or(get(kwd, :named_pipe, nothing), "named_pipe", false)) isempty(host_s) && (host_s = "localhost") + read_env = option_bool_or(get(kwd, :read_env, nothing), "read_env", false) + unix_socket = socket_path(protocol_kind(pick(:protocol)), option_bool_or(get(kwd, :named_pipe, nothing), "named_pipe", false), host_s, + option_string_or_nothing(pick(:unix_socket), "unix_socket"), read_env) user_s = String(user) user_s == "" && haskey(file, :user) && (user_s = file[:user]) pw = password === nothing ? (haskey(file, :password) ? file[:password] : nothing) : String(password) port_raw = pick(:port) - if port_raw === nothing && option_bool_or(get(kwd, :read_env, nothing), "read_env", false) && haskey(ENV, "MYSQL_TCP_PORT") + if port_raw === nothing && read_env && haskey(ENV, "MYSQL_TCP_PORT") port_raw = ENV["MYSQL_TCP_PORT"] end port = port_raw === nothing ? DEFAULT_PORT : option_integer(port_raw, "port") @@ -518,6 +521,13 @@ function ConnectOptions(host::AbstractString, user::AbstractString, password::Un enforce_raw !== nothing, enforce_raw === nothing ? false : enforce_raw, verify_raw !== nothing, verify_raw === nothing ? false : verify_raw, ca_file !== nothing) + if unix_socket !== nothing + # Reseau runs TLS over TCP only. A local socket needs no encryption, so `:preferred` + # connects without TLS, as Connector/C does over a socket. + mode == P.SSL_PREFERRED && (mode = P.SSL_DISABLED) + mode == P.SSL_DISABLED || throw(ArgumentError("TLS is not available over a Unix socket; use protocol=:tcp for ssl_mode, ssl_ca, or ssl_capath")) + pick(:bind) === nothing || throw(ArgumentError("bind applies only to TCP connections, not to a Unix socket")) + end min_version, max_version = parse_tls_version(option_string_or_nothing(pick(:tls_version), "tls_version")) tls = P.TLSOptions(; mode=mode, ca_file=ca_file, ca_dir=ca_dir, cert_file=option_string_or_nothing(pick(:ssl_cert), "ssl_cert"), @@ -590,6 +600,7 @@ function ConnectOptions(host::AbstractString, user::AbstractString, password::Un return ConnectOptions( host_s, port, + unix_socket, user_s, pw, db, diff --git a/src/precompile.jl b/src/precompile.jl index 13606ed..991ba52 100644 --- a/src/precompile.jl +++ b/src/precompile.jl @@ -1,7 +1,7 @@ # Precompile workload: drives the whole driver stack — greeting, authentication, the charset # bootstrap, text and binary result sets (buffered and streaming), prepared statements, DML, # ping, transactions, close — against a canned MySQL 8 transcript on the in-memory -# `FaultTransport{IOBuffer}` (the client's writes are discarded), so a session's first +# `FaultTransport` over an `IOBuffer` (the client's writes are discarded), so a session's first # connect and query do not pay for compiling the driver. No sockets, tasks, or timers are # involved (the reaper is never started); Reseau precompiles the transport paths itself. using PrecompileTools: @setup_workload, @compile_workload diff --git a/test/behavior_manifest.jl b/test/behavior_manifest.jl index 41351eb..794a501 100644 --- a/test/behavior_manifest.jl +++ b/test/behavior_manifest.jl @@ -575,8 +575,8 @@ const SURFACE_ROWS = SurfaceRow[ (make, password, _) -> option_database_surface(make, password), "manifest"), SurfaceRow(167, "localhost is dialed over TCP (with and without protocol=:tcp)", (make, _, _) -> transport_surface(make), (:ok, :ok)), - SurfaceRow(168, "a unix_socket path is accepted and reserved; TCP is used", - (make, _, _) -> connection_outcome(make; host="localhost", unix_socket="/nonexistent/mysql.sock"), :ok), + SurfaceRow(168, "a unix_socket path for localhost selects the socket", + (make, _, _) -> connection_outcome(make; host="localhost", unix_socket="/nonexistent/mysql.sock"), :SystemError), SurfaceRow(169, "multi-statements are disabled by default", (make, _, _) -> multi_statement_surface(make), :Error), SurfaceRow(170, "unknown connection keywords", @@ -632,7 +632,7 @@ const SURFACE_ROWS = SurfaceRow[ SurfaceRow(208, "connection serialization across tasks", (make, _, _) -> native_thread_surface(make), [1, 2]), SurfaceRow(209, "deferred transport fails explicitly", - (make, _, _) -> connection_outcome(make; protocol=:socket), :ArgumentError), + (make, _, _) -> connection_outcome(make; protocol=:pipe), :ArgumentError), SurfaceRow(210, "Julia 1.10 compatibility floor", (make, _, _) -> (VERSION >= v"1.10", string(query_value(make, "SELECT 1 AS value"))), (true, "1")), ] diff --git a/test/protocol/live_tests.jl b/test/protocol/live_tests.jl index f6cb1a6..11d0b6a 100644 --- a/test/protocol/live_tests.jl +++ b/test/protocol/live_tests.jl @@ -58,7 +58,12 @@ function run_live_lane(ref::String; soak::Bool=false, manifest::Bool=false) port = pick_port() command = mysql ? ["--mysql-native-password=ON"] : nothing env = Dict("MYSQL_ROOT_PASSWORD" => ROOT_PW, "MARIADB_ROOT_PASSWORD" => ROOT_PW) - Harbor.with_container(image; tag=tag, ports=Dict(3306 => port), environment=env, command=command, wait_strategy=(port=3306,), wait_timeout=180.0) do _ + # On Linux the server's socket directory is shared with the host, so a test can connect + # through the socket. (Docker Desktop cannot pass a Unix socket through to macOS.) + sockdir = mktempdir() + chmod(sockdir, 0o777) + volumes = Sys.islinux() ? Dict("/var/run/mysqld" => sockdir) : Dict{String, String}() + Harbor.with_container(image; tag=tag, ports=Dict(3306 => port), volumes=volumes, environment=env, command=command, wait_strategy=(port=3306,), wait_timeout=180.0) do _ @testset "$ref" begin root = wait_for_native(port) @test root.session.server.kind == (mysql ? :mysql : :mariadb) @@ -71,6 +76,24 @@ function run_live_lane(ref::String; soak::Bool=false, manifest::Bool=false) h = N.connect("127.0.0.1", "root", ROOT_PW; port=port, ssl_mode=:disabled, connect_timeout=10) @test !P.is_secure_transport(h.session) && h.auth_trace[end] == :ok N.close!(h) + if Sys.islinux() + # A new caching_sha2 account has no cached hash, so MySQL asks for full + # authentication, which a local socket answers with the cleartext password. + exec!(root, "CREATE USER 'sockuser'@'localhost' IDENTIFIED BY 'sockpw'") + h = N.connect("localhost", "sockuser", "sockpw"; unix_socket=joinpath(sockdir, "mysqld.sock"), connect_timeout=10) + @test h.session.transport isa P.Reseau.Unix.Conn && h.auth_trace[end] == :ok + mysql && @test :full_auth_cleartext in h.auth_trace + @test select_strings(h, "SELECT CURRENT_USER()")[1][1] == "sockuser@localhost" + N.close!(h) + if mysql + # sha256_password accepts a cleartext password only over TLS, so over a + # socket the client must use the server's RSA key. + exec!(root, "CREATE USER 'shauser'@'localhost' IDENTIFIED WITH sha256_password BY 'shapw'") + h = N.connect("localhost", "shauser", "shapw"; unix_socket=joinpath(sockdir, "mysqld.sock"), get_server_public_key=true, connect_timeout=10) + @test :rsa_response in h.auth_trace && h.auth_trace[end] == :ok + N.close!(h) + end + end rows = select_strings(root, "SELECT @@character_set_client, @@character_set_connection, @@character_set_results, @@version") @test rows[1][1:3] == ["utf8mb4", "utf8mb4", "utf8mb4"] @test select_strings(root, "SELECT 'héllo wörld 🐘'")[1][1] == "héllo wörld 🐘" diff --git a/test/protocol/native_tests.jl b/test/protocol/native_tests.jl index 3e52601..971220c 100644 --- a/test/protocol/native_tests.jl +++ b/test/protocol/native_tests.jl @@ -8,6 +8,32 @@ struct LocalInfileFunctor end @test isempty(Test.detect_unbound_args(MySQL)) end +@testset "Unix socket transport selection" begin + # a socket reaches only the local server + @test_throws ArgumentError N.ConnectOptions("h", "u"; protocol=:socket) + @test_throws ArgumentError N.ConnectOptions("127.0.0.1", "u"; protocol="socket", unix_socket="/tmp/x.sock") + if Sys.iswindows() + # as with Connector/C, `localhost` with a socket path stays on TCP on Windows + @test N.ConnectOptions("localhost", "u"; unix_socket="/tmp/x.sock").unix_socket === nothing + @test_throws ArgumentError N.ConnectOptions("localhost", "u"; protocol=:socket) + else + @test N.ConnectOptions("localhost", "u"; unix_socket="/tmp/x.sock").unix_socket == "/tmp/x.sock" + @test N.ConnectOptions("", "u"; unix_socket="/tmp/x.sock").unix_socket == "/tmp/x.sock" + @test N.ConnectOptions("localhost", "u"; protocol=:socket).unix_socket == N.DEFAULT_SOCKET + @test N.ConnectOptions("localhost", "u"; protocol="socket", unix_socket="/tmp/x.sock").unix_socket == "/tmp/x.sock" + withenv("MYSQL_UNIX_PORT" => "/tmp/env.sock") do + @test N.ConnectOptions("localhost", "u"; read_env=true).unix_socket == "/tmp/env.sock" + @test N.ConnectOptions("localhost", "u").unix_socket === nothing + end + # a socket carries no TLS: `:preferred` connects without it, and TLS requirements fail + @test N.ConnectOptions("localhost", "u"; unix_socket="/tmp/x.sock").tls.mode == P.SSL_DISABLED + @test N.ConnectOptions("localhost", "u"; unix_socket="/tmp/x.sock", ssl_mode=:disabled).tls.mode == P.SSL_DISABLED + for kw in ((; ssl_mode=:required), (; ssl_mode=:verify_identity), (; ssl_ca="/tmp/ca.pem"), (; bind="127.0.0.1")) + @test_throws ArgumentError N.ConnectOptions("localhost", "u"; unix_socket="/tmp/x.sock", kw...) + end + end +end + @testset "Native options truth table" begin @test_throws ArgumentError N.ConnectOptions("h", "u"; bogus=1) for (name, value) in ((:ssl_cipher, "AES"), (:ssl_crl, "/x"), @@ -18,24 +44,22 @@ end @test_throws ArgumentError N.ConnectOptions("h", "u"; plugin_dir="/x") @test N.ConnectOptions("h", "u"; compress=false) isa N.ConnectOptions @test_logs (:warn, r"deprecated") N.ConnectOptions("h", "u"; data_truncation=true) - @test N.ConnectOptions("h", "u"; unix_socket="/tmp/mysql.sock").host == "h" + # a socket path applies only to `localhost`; other hosts are dialed over TCP + @test N.ConnectOptions("h", "u"; unix_socket="/tmp/mysql.sock").unix_socket === nothing @test_throws ArgumentError N.ConnectOptions("h", "u"; named_pipe=true) @test N.ConnectOptions("h", "u"; named_pipe=nothing, protocol=:tcp).host == "h" - @test_throws ArgumentError N.ConnectOptions("h", "u"; protocol=:socket) @test N.ConnectOptions("h", "u"; named_pipe=true, protocol=:tcp).host == "h" - # every host is dialed over TCP; only an explicit local-transport request is (deferred) error @test N.ConnectOptions("", "u").host == "localhost" @test N.ConnectOptions("localhost", "u").host == "localhost" @test N.ConnectOptions("localhost", "u"; protocol=:default).host == "localhost" @test N.ConnectOptions("localhost", "u"; protocol="default").host == "localhost" @test N.ConnectOptions(".", "u").host == "." - @test N.ConnectOptions("localhost", "u"; unix_socket="/tmp/mysql.sock").host == "localhost" - @test_throws ArgumentError N.ConnectOptions("localhost", "u"; protocol=:socket) + @test N.ConnectOptions("localhost", "u").unix_socket === nothing + @test N.ConnectOptions("localhost", "u"; unix_socket="/tmp/x.sock", protocol=:tcp).unix_socket === nothing @test_throws ArgumentError N.ConnectOptions("localhost", "u"; protocol=:pipe) @test_throws ArgumentError N.ConnectOptions("localhost", "u"; protocol=:memory) @test N.ConnectOptions("h", "u"; protocol=:tcp).port == 3306 @test N.ConnectOptions("h", "u"; protocol="tcp").port == 3306 - @test_throws ArgumentError N.ConnectOptions("h", "u"; protocol="socket") @test_throws ArgumentError N.ConnectOptions("h", "u"; charset_name="latin1") @test N.ConnectOptions("h", "u"; charset_name="UTF8MB4").port == 3306 both = N.ConnectOptions("h", "u"; ssl_ca="a", ssl_capath="b").tls @@ -219,13 +243,18 @@ end @test_throws ArgumentError N.ConnectOptions("h", "u"; option_file=bad) socket_protocol = joinpath(dir, "socket.cnf") write(socket_protocol, "[client]\nprotocol=socket\n") - @test_throws ArgumentError N.ConnectOptions("h", "u"; option_file=socket_protocol) - @test N.ConnectOptions("h", "u"; option_file=socket_protocol, protocol=:tcp).host == "h" - # a `socket=` path in the file (the stock my.cnf) never selects the deferred transport + @test N.ConnectOptions("h", "u"; option_file=socket_protocol, protocol=:tcp).unix_socket === nothing + # a `socket=` path in the file (the stock my.cnf) selects the socket for `localhost` socket_path = joinpath(dir, "socket-path.cnf") write(socket_path, "[client]\nhost=localhost\nsocket=/tmp/mysql-option.sock\n") - @test N.ConnectOptions("", "u"; option_file=socket_path).host == "localhost" - @test N.ConnectOptions("", "u"; option_file=socket_path, protocol=:tcp).host == "localhost" + @test N.ConnectOptions("", "u"; option_file=socket_path, protocol=:tcp).unix_socket === nothing + @test_throws ArgumentError N.ConnectOptions("h", "u"; option_file=socket_protocol) + if Sys.iswindows() + @test N.ConnectOptions("", "u"; option_file=socket_path).unix_socket === nothing + else + @test N.ConnectOptions("localhost", "u"; option_file=socket_protocol).unix_socket == N.DEFAULT_SOCKET + @test N.ConnectOptions("", "u"; option_file=socket_path).unix_socket == "/tmp/mysql-option.sock" + end # A missing explicitly requested file is an error; default locations may be absent. @test_throws ArgumentError N.ConnectOptions("h", "u"; option_file=joinpath(dir, "missing.cnf")) login = joinpath(dir, ".mylogin.cnf") @@ -288,7 +317,7 @@ end function synthetic_reap_entries(n::Int) entries = N.ReapEntry[] - counters = P.FaultTransport{IOBuffer}[] + counters = P.FaultTransport[] refs = WeakRef[] for _ in 1:n transport = P.FaultTransport(IOBuffer()) diff --git a/test/protocol/runtests.jl b/test/protocol/runtests.jl index 26738ba..59e4bf6 100644 --- a/test/protocol/runtests.jl +++ b/test/protocol/runtests.jl @@ -24,6 +24,7 @@ empty!(P.COVERAGE) include("crypto_tests.jl") include("auth_tests.jl") include("tls_tests.jl") + include("unix_socket_tests.jl") include("native_tests.jl") include("cursor_tests.jl") include("binary_tests.jl") diff --git a/test/protocol/unix_socket_tests.jl b/test/protocol/unix_socket_tests.jl new file mode 100644 index 0000000..35613cd --- /dev/null +++ b/test/protocol/unix_socket_tests.jl @@ -0,0 +1,62 @@ +# Connections over a Unix socket against the fake peer, served by `Sockets.listen(path)`. +using Sockets: Sockets + +function with_unix_server(f::Function, handler::Function) + path = joinpath(mktempdir(), "mysql.sock") + server = Sockets.listen(path) + err = Ref{Any}(nothing) + task = Threads.@spawn try + conn = Sockets.accept(server) + try + handler(conn) + finally + close(conn) + end + catch e + err[] = e + end + try + return f(path) + finally + close(server) + wait(task) + err[] === nothing || throw(err[]) + end +end + +# caching_sha2_password full authentication: over a secure transport the client sends the +# password in clear text instead of asking for the server's RSA key. +function socket_peer_connect!(conn) + send_packet(conn, 0, greeting(; scramble=collect(UInt8, 101:120))) + seq, response = read_packet(conn) + length(response) == 32 && error("unexpected SSLRequest over a Unix socket") + send_packet(conn, seq + 1, UInt8[0x01, P.CACHING_SHA2_PERFORM_FULL_AUTH]) + seq, reply = read_packet(conn) + reply == vcat(Vector{UInt8}(codeunits("pw")), 0x00) || error("expected the cleartext password over the socket") + send_packet(conn, seq + 1, ok_payload(; status=P.SERVER_STATUS_AUTOCOMMIT | P.SERVER_SESSION_STATE_CHANGED, state=utf8mb4_state(), track=true)) + stall_until_eof(conn) + return nothing +end + +Sys.iswindows() || @testset "Unix socket transport" begin + for kw in ((;), (; protocol=:socket)) + with_unix_server(socket_peer_connect!) do path + h = N.connect("localhost", "root", "pw"; unix_socket=path, connect_timeout=10, kw...) + @test h.session.transport isa Reseau.Unix.Conn + @test !P.is_secure_transport(h.session) && :full_auth_cleartext in h.auth_trace + N.close!(h) + end + end + missing_path = joinpath(mktempdir(), "missing.sock") + @test_throws SystemError N.connect("localhost", "root", "pw"; unix_socket=missing_path, connect_timeout=10) +end + +@testset "a Unix socket is secure for caching_sha2_password only" begin + # The server accepts a cleartext password over a socket for caching_sha2_password, but + # sha256_password requires TLS, so it still asks for the server's RSA key. + pw = Vector{UInt8}(codeunits("pw")) + nonce = collect(UInt8, 1:20) + socket = P.AuthPolicy(; local_socket=true, get_server_public_key=true) + @test P.step!(P.AuthState(P.CachingSha2Password(), nonce), UInt8[P.CACHING_SHA2_PERFORM_FULL_AUTH], pw, socket) == vcat(pw, 0x00) + @test P.initial_response(P.Sha256Password(), pw, nonce, socket) == [P.SHA256_REQUEST_PUBLIC_KEY] +end