1# FreeBSD maintainer's guide to OpenSSL 2 3## Assumptions 4 5These instructions assume the following: 6 7- A git clone of FreeBSD will be available at `$GIT_ROOT/src/freebsd/main` with 8 an origin named `freebsd`. Example: 9 `git clone -o freebsd git@gitrepo.freebsd.org:src.git "$GIT_ROOT/src/freebsd/main"` 10- The vendor trees will be stored under `$GIT_ROOT/src/freebsd/vendor/`. 11 12## Software requirements 13 14The following additional software must be installed from ports: 15 16- lang/perl5 17- lang/python 18- net/rsync 19- security/gnupg 20 21## Warning 22 23This is a long and complicated process, in part because OpenSSL is a large, 24complex, and foundational software component in the FreeBSD distribution. A 25lot of the overall process has been automated to reduce potential human error, 26but some rough edges still exist. These rough edges have been highlighted in 27the directions. 28 29## Process 30 31### Notes 32 33The following directions use X.Y.Z to describe the major, minor, subminor 34versions, respectively for the OpenSSL release. Please substitute the values as 35appropriate in the directions below. 36 37All single commands are prefixed with `%`. 38 39### Variables 40 41``` 42% OPENSSL_VER_MAJOR_MINOR=X.Y 43% OPENSSL_VER_FULL=X.Y.Z 44% RELEASE_TARFILE="openssl-${OPENSSL_VER_FULL}.tar.gz" 45% BASE_URL="https://github.com/openssl/openssl/releases/download/openssl-${OPENSSL_VER_FULL}/${RELEASE_TARFILE}" 46``` 47 48### Switch to the vendor branch 49 50``` 51% cd "$GIT_ROOT/src/freebsd/main" 52% git worktree add -b vendor/openssl-${OPENSSL_VER_MAJOR_MINOR} \ 53 ../vendor/openssl-${OPENSSL_VER_MAJOR_MINOR} \ 54 freebsd/vendor/openssl-${OPENSSL_VER_MAJOR_MINOR} 55% cd "$GIT_ROOT/src/freebsd/vendor/openssl-${OPENSSL_VER_MAJOR_MINOR} 56``` 57 58### Download the latest OpenSSL release 59 60The following instructions demonstrate how to fetch a recent OpenSSL release 61and its corresponding artifacts (release SHA256 checksum; release PGP 62signature) from the [official website](https://www.openssl.org/source/). 63 64``` 65% (cd .. && fetch ${BASE_URL} ${BASE_URL}.asc ${BASE_URL}.sha256) 66``` 67 68### Verify the release authenticity and integrity 69 70**NOTE**: this step requires importing the project author's PGP keys beforehand. 71See the [sources webpage](https://openssl-library.org/source/) for more 72details. 73 74This step uses the PGP signature and SHA256 checksum files to verify the release 75authenticity and integrity, respectively. 76 77``` 78% (cd .. && sha256sum -c ${RELEASE_TARFILE}.sha256) 79% (cd .. && gpg --verify ${RELEASE_TARFILE}.asc) 80``` 81 82### Unpack the OpenSSL tarball to the parent directory 83 84``` 85% (cd .. && tar xf ../${RELEASE_TARFILE}) 86``` 87 88### Update the sources in the vendor branch 89 90**IMPORTANT**: the trailing slash in the source directory is required! 91 92``` 93% rsync --exclude .git --delete -av ../openssl-${OPENSSL_VER_FULL}/ . 94``` 95 96### Take care of added / deleted files 97 98``` 99% git add -A 100``` 101 102### Commit, tag, and push 103 104``` 105% git commit -m "openssl: Vendor import of OpenSSL ${OPENSSL_VER_FULL}" 106% git tag -a -m "Tag OpenSSL ${OPENSSL_VER_FULL}" vendor/openssl/${OPENSSL_VER_FULL} 107``` 108 109The update and tag could instead be pushed later, along with the merge 110to main, but pushing now allows others to collaborate. 111 112#### Push branch update and tag separately 113 114At this point the vendor branch can be pushed to the FreeBSD repo via: 115``` 116% git push freebsd vendor/openssl-${OPENSSL_VER_MAJOR_MINOR} 117% git push freebsd vendor/openssl/${OPENSSL_VER_FULL} 118``` 119 120**NOTE**: the second "git push" command is used to push the tag, which is not 121pushed by default. 122 123#### Push branch update and tag simultaneously 124 125It is also possible to push the branch and tag together, but use 126`--dry-run` first to ensure that no undesired tags will be pushed: 127 128``` 129% git push --dry-run --follow-tags freebsd vendor/openssl-${OPENSSL_VER_MAJOR_MINOR} 130% git push --follow-tags freebsd vendor/openssl-${OPENSSL_VER_MAJOR_MINOR} 131``` 132 133### Remove any existing patches and generated files. 134 135``` 136% make clean 137``` 138 139Please note that this step does not remove any generated manpages: this happens 140in a later step. 141 142### Merge from the vendor branch and resolve conflicts 143 144``` 145% git subtree merge -P crypto/openssl vendor/openssl-${OPENSSL_VER_MAJOR_MINOR} 146``` 147 148**NOTE**: Some files may have been deleted from FreeBSD's copy of OpenSSL. 149If git prompts for these deleted files during the merge, choose 'd' 150(leaving them deleted). 151 152### Patch, configure, and regenerate all files 153 154The following commands turn the crank associated with the vendor release 155update: 156 157``` 158% make patch 159% make configure 160% make all 161``` 162 163This process updates all generated files, syncs the manpages with the new release, 164regenerates assembly files, etc. 165 166For now, any build-related changes, e.g., a assembly source was removed, a manpage 167was added, etc, will require makefile updates. 168 169### Diff against the vendor branch 170 171Review the diff for any unexpected changes: 172 173``` 174% git diff --diff-filter=M vendor/openssl/${OPENSSL_VER_FULL} HEAD:crypto/openssl 175``` 176 177The net-result should be just the applied patches from the freebsd/ directory. 178 179### Make build-related changes 180 181**IMPORTANT**: manual adjustments/care needed here. 182 183Update the appropriate makefiles to reflect changes in the vendor's 184`build.info` metadata file. This is especially important if source files have 185been added or removed. Keep in mind that the assembly files generated belong in 186`sys/crypto/openssl`, and will therefore affect the kernel as well. 187 188If symbols have been added or removed, update the appropriate `Version.map` to 189reflect these changes. Please try to stick to the new versioning scheme in the 190target OpenSSL release to improve interoperability with binaries compiled 191dynamically against the ports version of OpenSSL, for instance. 192 193Compare compilation flags, the list of files built and included, the list of 194symbols generated with the corresponding port if available. 195 196### Build, install, and test 197 198Build and install a new version of world and the kernel with the newer release 199of OpenSSL. Reboot the test host and run any appropriate tests using kyua, 200`make checkworld`, etc. 201 202### Commit and push 203