Skip to content

INSTALL.md

Latest commit

 

History

History
63 lines (41 loc) · 3.84 KB

INSTALL.md

File metadata and controls

63 lines (41 loc) · 3.84 KB

Installing and building legacytls

Downstream (importing this module)

The repository vendors a minimal OpenSSL 1.0.2u snapshot under deps/openssl-1.0.2u/: public headers plus static libssl.a and libcrypto.a, built for linux/amd64 (enable-ssl2, no-shared, -fPIC on CFLAG / ASFLAG).

The archives are position-independent so cgo can link them into go build -buildmode=plugin on linux/amd64. Non-PIC static OpenSSL libraries often fail the plugin link step with relocations such as R_X86_64_32S ... can not be used when making a shared object.

In another Go module you can depend on a semver tag and use SSLv3 (and other OpenSSL-backed protocols) without running this repo’s Makefile or bootstrap script:

# In your project (linux/amd64, gcc installed)
go get github.com/NetSPI/GoLegacySslTlsSupport@v0.1.5
CGO_ENABLED=1 go build ./...

Requirements:

  • GOOS=linux, GOARCH=amd64 for the vendored .a files; other targets will fail at link time until you supply matching libraries (or use build tags).
  • CGO enabled (default on typical Linux) and a C compiler (e.g. gcc).
  • TLS 1.3-only probes use crypto/tls and can work with CGO_ENABLED=0; OpenSSL-backed protocols (SSLv2 through TLS 1.2) need cgo.

Structured peer certificate fields (Options.CertificateDetail, Result.PeerCertificateInfo) are parsed in Go from the handshake chain; OpenSSL-backed probes still require cgo so the DER chain can be exported after the handshake.

Optional overrides: you can still set CGO_CFLAGS / CGO_LDFLAGS to use a different OpenSSL install; they are merged with the package #cgo directives.

Releasing (maintainers)

  1. Run ./scripts/check-vendored-openssl.sh so deps/openssl-1.0.2u is present and tracked. A common mistake is a .gitignore pattern like openssl-1.0.2u/ without a leading slash, which matches any path containing that name (including deps/openssl-1.0.2u/) and silently excludes the vendored tree from the module zip—downstream then fails cgo with errors such as “could not determine what C.SSL_library_init refers to”. This repo uses /openssl-1.0.2u/ to ignore only a tree at the repository root.

  2. Commit and push the default branch.

  3. Tag and push (example):

    git tag -a v0.1.5 -m "GoLegacySslTlsSupport v0.1.5 (PIC vendored OpenSSL for plugins)"
git push origin v0.1.5

  4. Downstream: go get github.com/NetSPI/GoLegacySslTlsSupport@v0.1.5.

To rebuild the vendored slice after changing bootstrap flags: ./scripts/refresh-vendored-openssl.sh (then commit deps/openssl-1.0.2u/).

Refreshing vendored OpenSSL (maintainers)

After rebuilding OpenSSL 1.0.2u from a full tree (e.g. at repo root), update the committed slice:

# Headers: OpenSSL’s include/openssl entries are symlinks; copy with dereference.
rm -rf deps/openssl-1.0.2u/include
cp -LR /path/to/openssl-1.0.2u/include deps/openssl-1.0.2u/

cp -a /path/to/openssl-1.0.2u/libssl.a /path/to/openssl-1.0.2u/libcrypto.a deps/openssl-1.0.2u/

Or run ./scripts/refresh-vendored-openssl.sh, which runs scripts/bootstrap-openssl.sh (PIC CFLAG/ASFLAG patch after ./config) and copies into deps/openssl-1.0.2u/. deps/openssl-1.0.2u-src/ and the tarball stay gitignored like .gitignore upstream.

Tarball URL used by the bootstrap script:
https://github.com/openssl/openssl/releases/download/OpenSSL_1_0_2u/openssl-1.0.2u.tar.gz
SHA-256 is checked in scripts/bootstrap-openssl.sh.

Local development

  • .gitignore uses /openssl-1.0.2u/ so only a full tree at the repository root is ignored; deps/openssl-1.0.2u remains tracked.
  • deps/openssl-1.0.2u.tar.gz is ignored if you keep a downloaded tarball next to the vendored tree.