kgess-mirror/freebsd-src
1
0
Fork 0
mirror of https://git.freebsd.org/src.git synced 2026-01-11 19:57:22 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

crypto/openssl: update vendor update instructions

Browse source 
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
This commit is contained in:
Enji Cooper 2025-10-11 14:12:55 -07:00
parent 8df2e54214
commit 08cdcff58a
2 changed files with 202 additions and 122 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

122
crypto/openssl/FREEBSD-upgrade
View file

@ -1,122 +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 -b vendor/openssl-X.Y ../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://github.com/openssl/openssl/releases/download/openssl-X.Y.Z/openssl-X.Y.Z.tar.gz)
$ (cd .. && fetch https://github.com/openssl/openssl/releases/download/openssl-X.Y.Z/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 xf ../openssl-X.Y.Z.tar.gz -C ..
05) Copy to the vendor branch:
$ rsync --exclude .git --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 provider 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
18) Commit and hope you did not miss anything.

202
crypto/openssl/FREEBSD-upgrade.md Normal file
View file

@ -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