Page MenuHomeFreeBSD
Files F156533313

D53190.diff
No OneTemporary
Actions

D53190.diff
View Options

diff --git a/crypto/openssl/FREEBSD-upgrade b/crypto/openssl/FREEBSD-upgrade
deleted file mode 100644
--- a/crypto/openssl/FREEBSD-upgrade
+++ /dev/null
@@ -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.
diff --git a/crypto/openssl/FREEBSD-upgrade.md b/crypto/openssl/FREEBSD-upgrade.md
new file mode 100644
--- /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

File Metadata

Mime Type
text/plain
Expires
Fri, May 15, 12:01 PM (10 h, 8 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
33082762
Default Alt Text
D53190.diff (10 KB)

Event Timeline