TLS Probe Go Package

github.com/olelbis/tlsanalyzer/tlsprobe exposes the raw TLS 1.3 cipher probe used by tlsanalyzer.

The package is intentionally small and preview-level. It sends minimal TLS 1.3 ClientHello messages, offers one cipher suite at a time and classifies the first useful server response. It is not a TLS implementation and it does not complete full TLS handshakes.

Install

go get github.com/olelbis/tlsanalyzer@v0.31.3

Example

package main

import (
	"context"
	"fmt"
	"net"
	"time"

	"github.com/olelbis/tlsanalyzer/tlsprobe"
)

func main() {
	results, err := tlsprobe.ProbeTLS13CipherSuites(context.Background(), tlsprobe.Options{
		Address:    net.JoinHostPort("example.com", "443"),
		ServerName: "example.com",
		Timeout:    5 * time.Second,
		ALPN:           []string{"h2", "http/1.1"},
		KeyShareGroups: tlsprobe.SupportedKeyShareGroups(),
	}, tlsprobe.SupportedTLS13CipherSuites())
	if err != nil {
		panic(err)
	}

	for _, result := range results {
		fmt.Printf("%s: %s (%s)\n", result.Name, result.Status, result.EvidenceLevel)
	}
}

API Contract

Public entry points:

Configuration errors are returned as *tlsprobe.ConfigError. Network and TLS protocol outcomes are normally returned as Result values with a Status.

Consumers should rely on Status, EvidenceLevel, CompletedHandshake and ErrorCode values for automation. Result.Error is human-readable diagnostic detail and may change while the package remains under v0.x.

Result also includes optional evidence metadata:

Options.DialContext can be set by embedded callers that need custom network behavior, tests, proxy integration or connection instrumentation. When it is nil, the package uses net.Dialer.

Summarize returns status counts for a result set so callers do not need to duplicate basic aggregation logic.

Status Values

Status Meaning
supported The server selected the offered TLS 1.3 cipher suite.
rejected The server replied with ServerHello but selected another cipher suite.
hello-retry-request The server sent HelloRetryRequest and the probe could not complete a retry.
alert The server returned a TLS alert.
timeout Connect, write or read exceeded the configured timeout.
closed The peer closed the connection before a supported/rejected decision.
inconclusive The response could not be classified deterministically.

Evidence Values

Evidence level Meaning
clienthello-only The probe sent a raw ClientHello and classified the first useful server response. It did not complete a full TLS handshake.

Current Limits