From nobody Tue Feb 3 07:37:57 2026 X-Original-To: dev-commits-src-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4f4wLs34rZz6RMv0 for ; Tue, 03 Feb 2026 07:37:57 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R13" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4f4wLs0z5Hz45mc for ; Tue, 03 Feb 2026 07:37:57 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1770104277; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=3HDEYz5YluRNCXeJPBubLoxU7eGX+HwgtYVewo5K/04=; b=QAwiC1NvhMrms8fn3Me386cfFbQOjKPeEb0s06Mc/nFQrY/xuKRuGWZGAvJvsPxfxbGXMn ylm8kdDgixZmaHhEUJmIG8QGLEhtdLd87gH5DYBbt4ikRyq3+Q9p/rRojG1FpIGtvoeacp 7pPNy77ctELljeE3Lsxn3S4zCexjWmyGJDsr1FhuOEsCPO6TOAGKwuoshTaPGSjw0Fp/HI m46cIgwWZHe5jQAkHl9ntoDSZfMbH7VsRUZCYHqxW5itaS0LSnbHekhyRSHTYFVN+bJ8Mk vTdiv2G31cUVx9O9HjvXrJ+YyLR/v/iKqqbCWFbajVcfy5EaoqhXsZmiC3Mi+w== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1770104277; a=rsa-sha256; cv=none; b=eX0iPa25/JxdII/HNdxNoQmI6vfoEyJ2/INaYdLZzDsGb8O5Q8UIDFP5zpIuIFxdMdReqE B+cAGFYr56pVg35VYBMSYWGU6xAS8WajtYe2DDEqTqrpvW3oHActbtAoJO92zCWzf7AyLn u5lpBGFnaKeNS1mIYx8NcWc+wjFYbRp7WJ6M0gOnflcUh8XpEp4xvjy5sONnimJC8AwOES nzrFhvWU21p+vkulFRn20nur7rH+QOCzd0zyevNJBhLiyelBIHpo+/D5vMEqHU28J8s1Ch t3IEGgflkIaiVRC420+K7JE7uvobhkt4RUqiiN3Boi9T4dVQubKrK/ZTmY5PcA== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1770104277; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=3HDEYz5YluRNCXeJPBubLoxU7eGX+HwgtYVewo5K/04=; b=Qr+7heMBTOIfQ4tCPrCIggCiXWuu4jHjvuGQmYVOrq74pBfHB2CyAc2QnsTixxS21tjRSG 1xhjGcBbFMBEKdLXuHyFeIwXswC68D9c8KPpAP4XXPwi7HaQvjGEpbEhqo9SfX7m+S1EFz KydV/a3vTAg7e5uSUt5Y8TeMKKYk6qxf9j1Q8CCyL5yVfp3ujU8FLkAOimP5Kvp/gCVpi6 PQeS7M+VnE3SBuF5EYcMattbJ7m/frXGgutgtEqAhbEnITeju8o+Y6IVE6ZtU4nx5HaHd6 NDZyq1XgN7xeuF8ncK9a3bIT6D8nPH31yzILJyiiFJkpd9tVaJH2o6csQUNKEQ== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) by mxrelay.nyi.freebsd.org (Postfix) with ESMTP id 4f4wLs0K3Bz141G for ; Tue, 03 Feb 2026 07:37:57 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from git (uid 1279) (envelope-from git@FreeBSD.org) id 3249b by gitrepo.freebsd.org (DragonFly Mail Agent v0.13+ on gitrepo.freebsd.org); Tue, 03 Feb 2026 07:37:57 +0000 To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-branches@FreeBSD.org From: Enji Cooper Subject: git: 7752bb84c45d - stable/14 - crypto/openssl: update vendor update instructions List-Id: Commit messages for all branches of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-src-all@freebsd.org Sender: owner-dev-commits-src-all@FreeBSD.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: ngie X-Git-Repository: src X-Git-Refname: refs/heads/stable/14 X-Git-Reftype: branch X-Git-Commit: 7752bb84c45d39a266910f98f5cc097aa017a19c Auto-Submitted: auto-generated Date: Tue, 03 Feb 2026 07:37:57 +0000 Message-Id: <6981a5d5.3249b.3b581b15@gitrepo.freebsd.org> The branch stable/14 has been updated by ngie: URL: https://cgit.FreeBSD.org/src/commit/?id=7752bb84c45d39a266910f98f5cc097aa017a19c commit 7752bb84c45d39a266910f98f5cc097aa017a19c Author: Enji Cooper AuthorDate: 2025-10-11 21:12:55 +0000 Commit: Enji Cooper CommitDate: 2026-02-03 06:25:44 +0000 crypto/openssl: update vendor update instructions This change fills out the requirements for doing vendor updates, documents the new vendor update process, and guides whoever needs to do the next version update a bit better than the documentation did prior to this change so everyone can pitch in with version updates a bit better. Convert the document to Markdown while here to make it easier to render/print out the directions in a structured format. MFC after: 2 weeks Differential Revision: https://reviews.freebsd.org/D53190 Conflicts: crypto/openssl/FREEBSD-upgrade (cherry picked from commit 08cdcff58acb2aec881e42c7f097d6492d864898) --- crypto/openssl/FREEBSD-upgrade | 130 ------------------------ crypto/openssl/FREEBSD-upgrade.md | 202 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 202 insertions(+), 130 deletions(-) diff --git a/crypto/openssl/FREEBSD-upgrade b/crypto/openssl/FREEBSD-upgrade deleted file mode 100644 index 76943efdbde6..000000000000 --- a/crypto/openssl/FREEBSD-upgrade +++ /dev/null @@ -1,130 +0,0 @@ - FreeBSD maintainer's guide to OpenSSL - ===================================== - - These instructions assume you have a clone of the FreeBSD git repo - main branch in src/freebsd/main, and will store vendor trees under - src/freebsd/vendor/. In addition, this assumes there is a "freebsd" - origin pointing to git(repo).freebsd.org/src.git. - -01) Switch to the vendor branch: - - $ cd src/freebsd/main - $ git worktree add ../vendor/openssl-X.Y freebsd/vendor/openssl-X.Y - $ cd ../vendor/openssl-X.Y - -02) Download the latest OpenSSL tarball and signature from the official - website (https://www.openssl.org/source/). - - $ (cd .. && fetch https://openssl.org/source/openssl-X.Y.Z.tar.gz) - $ (cd .. && fetch https://openssl.org/source/openssl-X.Y.Z.tar.gz.asc) - -03) Verify the signature: - - $ gpg --verify ../openssl-X.Y.Z.tar.gz.asc ../openssl-X.Y.Z.tar.gz - -04) Unpack the OpenSSL tarball to the parent directory: - - $ tar -x -X FREEBSD-Xlist -f ../openssl-X.Y.Z.tar.gz -C .. - -05) Copy to the vendor branch: - - $ rsync --exclude FREEBSD.* --delete -av ../openssl-X.Y.Z/* . - -06) Take care of added / deleted files: - - $ git add -A - -07) Commit: - - $ git commit -m "openssl: Vendor import of OpenSSL X.Y.Z" - -08) Tag: - - $ git tag -a -m "Tag OpenSSL X.Y.Z" vendor/openssl/X.Y.Z - - At this point the vendor branch can be pushed to the FreeBSD repo via: - - $ git push freebsd vendor/openssl-X.Y - $ git push freebsd vendor/openssl/X.Y.Z - - Note the second "git push" command is used to push the tag, which is - not pushed by default. - - It is also possible to push the branch and tag together, but use - --dry-run first to ensure that no undesired tags will be pushed: - - $ git push --dry-run --follow-tags freebsd vendor/openssl-X.Y - $ git push --follow-tags freebsd vendor/openssl-X.Y - - The update and tag could instead be pushed later, along with the merge - to main, but pushing now allows others to collaborate. - -09) Merge from the vendor branch: - - $ git subtree merge -P crypto/openssl vendor/openssl-X.Y - - A number of files have been deleted from FreeBSD's copy of OpenSSL. - If git prompts for these deleted files during the merge, choose 'd' - (leaving them deleted). - -10) Resolve conflicts. Remember to bump the version and date in - secure/lib/libcrypto/Makefile.inc and - crypto/openssl/include/openssl/opensslv.h. - -11) Diff against the vendor branch: - - $ git diff --diff-filter=M vendor/openssl/X.Y.Z HEAD:crypto/openssl - - Review the diff for any unexpected changes. - -12) Re-generate the assembly files: - - $ cd secure/lib/libcrypto - $ make cleanasm buildasm - -13) Update the appropriate makefiles to reflect changes in the vendor's - build.info files. This is especially important if source files have - been added or removed. Keep in mind that the assembly files generated - belong to sys/crypto/openssl, and will therefore affect the kernel as - well. - -14) If symbols have been added or removed, update the appropriate - Version.map to reflect these changes. - -15) Compare compilation flags, the list of files built and included, the - list of symbols generated with the corresponding port if available. - -16) Re-generate the manual files: - - $ tar xzf openssl-X.Y.Z.tar.gz - $ (cd openssl-X.Y.Z && ./Configure --prefix=/usr --openssldir=/etc/ssl && - make build_man_docs) - [...] - $ find openssl-X.Y.Z/doc/man/man1 -name '*.1' -exec cp {} secure/usr.bin/openssl/man/ \; - $ find openssl-X.Y.Z/doc/man/man3 -name '*.3' -exec cp {} secure/lib/libcrypto/man/man3/ \; - $ find openssl-X.Y.Z/doc/man/man5 -name '*.5' -exec cp {} secure/lib/libcrypto/man/man5/ \; - $ find openssl-X.Y.Z/doc/man/man7 -name '*.7' -exec cp {} secure/lib/libcrypto/man/man7/ \; - $ grep -nrF usr/local secure/lib/libcrypto/man secure/usr.bin/openssl/man - [correct the references to the prefix and OpenSSL directories] - $ git commit --amend secure/lib/libcrypto/man secure/usr.bin/openssl/man - - Review the diff and tree status for anything requiring attention. - -16) Build and install world, reboot, test. - -17) Test the legacy and fips providers as well: (here with "test" as the password) - - $ echo test | openssl rc4 -provider legacy -e -a -pbkdf2 - enter RC4 encryption password: - Verifying - enter RC4 encryption password: - U2FsdGVkX1+JvhqxLMOvlxvTi1/h - - # openssl fipsinstall -out /etc/ssl/fipsmodule.cnf -module /usr/lib/ossl-modules/fips.so - INSTALL PASSED - # vi /etc/ssl/openssl.cnf - [enable the FIPS module] - # echo test | openssl aes-256-cbc -provider fips -e -a -pbkdf2 - U2FsdGVkX19lTexiYsnMX83ZLSojBOFwv7GB0Plhgmw= - -18) Commit and hope you did not miss anything. - diff --git a/crypto/openssl/FREEBSD-upgrade.md b/crypto/openssl/FREEBSD-upgrade.md new file mode 100644 index 000000000000..1fc38c4dd17f --- /dev/null +++ b/crypto/openssl/FREEBSD-upgrade.md @@ -0,0 +1,202 @@ +# FreeBSD maintainer's guide to OpenSSL + +## Assumptions + +These instructions assume the following: + +- A git clone of FreeBSD will be available at `$GIT_ROOT/src/freebsd/main` with + an origin named `freebsd`. Example: + `git clone -o freebsd git@gitrepo.freebsd.org:src.git "$GIT_ROOT/src/freebsd/main"` +- The vendor trees will be stored under `$GIT_ROOT/src/freebsd/vendor/`. + +## Software requirements + +The following additional software must be installed from ports: + +- lang/perl5 +- lang/python +- net/rsync +- security/gnupg + +## Warning + +This is a long and complicated process, in part because OpenSSL is a large, +complex, and foundational software component in the FreeBSD distribution. A +lot of the overall process has been automated to reduce potential human error, +but some rough edges still exist. These rough edges have been highlighted in +the directions. + +## Process + +### Notes + +The following directions use X.Y.Z to describe the major, minor, subminor +versions, respectively for the OpenSSL release. Please substitute the values as +appropriate in the directions below. + +All single commands are prefixed with `%`. + +### Variables + +``` +% OPENSSL_VER_MAJOR_MINOR=X.Y +% OPENSSL_VER_FULL=X.Y.Z +% RELEASE_TARFILE="openssl-${OPENSSL_VER_FULL}.tar.gz" +% BASE_URL="https://github.com/openssl/openssl/releases/download/openssl-${OPENSSL_VER_FULL}/${RELEASE_TARFILE}" +``` + +### Switch to the vendor branch + +``` +% cd "$GIT_ROOT/src/freebsd/main" +% git worktree add -b vendor/openssl-${OPENSSL_VER_MAJOR_MINOR} \ + ../vendor/openssl-${OPENSSL_VER_MAJOR_MINOR} \ + freebsd/vendor/openssl-${OPENSSL_VER_MAJOR_MINOR} +% cd "$GIT_ROOT/src/freebsd/vendor/openssl-${OPENSSL_VER_MAJOR_MINOR} +``` + +### Download the latest OpenSSL release + +The following instructions demonstrate how to fetch a recent OpenSSL release +and its corresponding artifacts (release SHA256 checksum; release PGP +signature) from the [official website](https://www.openssl.org/source/). + +``` +% (cd .. && fetch ${BASE_URL} ${BASE_URL}.asc ${BASE_URL}.sha256) +``` + +### Verify the release authenticity and integrity + +**NOTE**: this step requires importing the project author's PGP keys beforehand. +See the [sources webpage](https://openssl-library.org/source/) for more +details. + +This step uses the PGP signature and SHA256 checksum files to verify the release +authenticity and integrity, respectively. + +``` +% (cd .. && sha256sum -c ${RELEASE_TARFILE}.sha256) +% (cd .. && gpg --verify ${RELEASE_TARFILE}.asc) +``` + +### Unpack the OpenSSL tarball to the parent directory + +``` +% (cd .. && tar xf ../${RELEASE_TARFILE}) +``` + +### Update the sources in the vendor branch + +**IMPORTANT**: the trailing slash in the source directory is required! + +``` +% rsync --exclude .git --delete -av ../openssl-${OPENSSL_VER_FULL}/ . +``` + +### Take care of added / deleted files + +``` +% git add -A +``` + +### Commit, tag, and push + +``` +% git commit -m "openssl: Vendor import of OpenSSL ${OPENSSL_VER_FULL}" +% git tag -a -m "Tag OpenSSL ${OPENSSL_VER_FULL}" vendor/openssl/${OPENSSL_VER_FULL} +``` + +The update and tag could instead be pushed later, along with the merge +to main, but pushing now allows others to collaborate. + +#### Push branch update and tag separately + +At this point the vendor branch can be pushed to the FreeBSD repo via: +``` +% git push freebsd vendor/openssl-${OPENSSL_VER_MAJOR_MINOR} +% git push freebsd vendor/openssl/${OPENSSL_VER_FULL} +``` + +**NOTE**: the second "git push" command is used to push the tag, which is not +pushed by default. + +#### Push branch update and tag simultaneously + +It is also possible to push the branch and tag together, but use +`--dry-run` first to ensure that no undesired tags will be pushed: + +``` +% git push --dry-run --follow-tags freebsd vendor/openssl-${OPENSSL_VER_MAJOR_MINOR} +% git push --follow-tags freebsd vendor/openssl-${OPENSSL_VER_MAJOR_MINOR} +``` + +### Remove any existing patches and generated files. + +``` +% make clean +``` + +Please note that this step does not remove any generated manpages: this happens +in a later step. + +### Merge from the vendor branch and resolve conflicts + +``` +% git subtree merge -P crypto/openssl vendor/openssl-${OPENSSL_VER_MAJOR_MINOR} +``` + +**NOTE**: Some files may have been deleted from FreeBSD's copy of OpenSSL. +If git prompts for these deleted files during the merge, choose 'd' +(leaving them deleted). + +### Patch, configure, and regenerate all files + +The following commands turn the crank associated with the vendor release +update: + +``` +% make patch +% make configure +% make all +``` + +This process updates all generated files, syncs the manpages with the new release, +regenerates assembly files, etc. + +For now, any build-related changes, e.g., a assembly source was removed, a manpage +was added, etc, will require makefile updates. + +### Diff against the vendor branch + +Review the diff for any unexpected changes: + +``` +% git diff --diff-filter=M vendor/openssl/${OPENSSL_VER_FULL} HEAD:crypto/openssl +``` + +The net-result should be just the applied patches from the freebsd/ directory. + +### Make build-related changes + +**IMPORTANT**: manual adjustments/care needed here. + +Update the appropriate makefiles to reflect changes in the vendor's +`build.info` metadata file. This is especially important if source files have +been added or removed. Keep in mind that the assembly files generated belong in +`sys/crypto/openssl`, and will therefore affect the kernel as well. + +If symbols have been added or removed, update the appropriate `Version.map` to +reflect these changes. Please try to stick to the new versioning scheme in the +target OpenSSL release to improve interoperability with binaries compiled +dynamically against the ports version of OpenSSL, for instance. + +Compare compilation flags, the list of files built and included, the list of +symbols generated with the corresponding port if available. + +### Build, install, and test + +Build and install a new version of world and the kernel with the newer release +of OpenSSL. Reboot the test host and run any appropriate tests using kyua, +`make checkworld`, etc. + +### Commit and push