crypto/openssl/FREEBSD-upgrade

   1             FreeBSD maintainer's guide to OpenSSL
   2             =====================================
   3
   4     These instructions assume you have a clone of the FreeBSD git repo
   5     main branch in src/freebsd/main, and will store vendor trees under
   6     src/freebsd/vendor/. In addition, this assumes there is a "freebsd"
   7     origin pointing to git(repo).freebsd.org/src.git.
   8
   9 01) Switch to the vendor branch:
  10
  11     $ cd src/freebsd/main
  12     $ git worktree add ../vendor/openssl-X.Y freebsd/vendor/openssl-X.Y
  13     $ cd ../vendor/openssl-X.Y
  14
  15 02) Download the latest OpenSSL tarball and signature from the official
  16     website (https://www.openssl.org/source/).
  17
  18     $ (cd .. && fetch https://openssl.org/source/openssl-X.Y.Z.tar.gz)
  19     $ (cd .. && fetch https://openssl.org/source/openssl-X.Y.Z.tar.gz.asc)
  20
  21 03) Verify the signature:
  22
  23     $ gpg --verify ../openssl-X.Y.Z.tar.gz.asc ../openssl-X.Y.Z.tar.gz
  24
  25 04) Unpack the OpenSSL tarball to the parent directory:
  26
  27     $ tar -x -X FREEBSD-Xlist -f ../openssl-X.Y.Z.tar.gz -C ..
  28
  29 05) Copy to the vendor branch:
  30
  31     $ rsync --exclude FREEBSD.* --delete -av ../openssl-X.Y.Z/* .
  32
  33 06) Take care of added / deleted files:
  34
  35     $ git add -A
  36
  37 07) Commit:
  38
  39     $ git commit -m "openssl: Vendor import of OpenSSL X.Y.Z"
  40
  41 08) Tag:
  42
  43     $ git tag -a -m "Tag OpenSSL X.Y.Z" vendor/openssl/X.Y.Z
  44
  45     At this point the vendor branch can be pushed to the FreeBSD repo via:
  46
  47     $ git push freebsd vendor/openssl-X.Y
  48     $ git push freebsd vendor/openssl/X.Y.Z
  49
  50     Note the second "git push" command is used to push the tag, which is
  51     not pushed by default.
  52
  53     It is also possible to push the branch and tag together, but use
  54     --dry-run first to ensure that no undesired tags will be pushed:
  55
  56     $ git push --dry-run --follow-tags freebsd vendor/openssl-X.Y
  57     $ git push --follow-tags freebsd vendor/openssl-X.Y
  58
  59     The update and tag could instead be pushed later, along with the merge
  60     to main, but pushing now allows others to collaborate.
  61
  62 09) Merge from the vendor branch:
  63
  64     $ git subtree merge -P crypto/openssl vendor/openssl-X.Y
  65
  66     A number of files have been deleted from FreeBSD's copy of OpenSSL.
  67     If git prompts for these deleted files during the merge, choose 'd'
  68     (leaving them deleted).
  69
  70 10) Resolve conflicts. Remember to bump the version and date in
  71     secure/lib/libcrypto/Makefile.inc and
  72     crypto/openssl/include/openssl/opensslv.h.
  73
  74 11) Diff against the vendor branch:
  75
  76     $ git diff --diff-filter=M vendor/openssl/X.Y.Z HEAD:crypto/openssl
  77
  78     Review the diff for any unexpected changes.
  79
  80 12) Re-generate the assembly files:
  81
  82     $ cd secure/lib/libcrypto
  83     $ make cleanasm buildasm
  84
  85 13) Update the appropriate makefiles to reflect changes in the vendor's
  86     build.info files. This is especially important if source files have
  87     been added or removed. Keep in mind that the assembly files generated
  88     belong to sys/crypto/openssl, and will therefore affect the kernel as
  89     well.
  90
  91 14) If symbols have been added or removed, update the appropriate
  92     Version.map to reflect these changes.
  93
  94 15) Compare compilation flags, the list of files built and included, the
  95     list of symbols generated with the corresponding port if available.
  96
  97 16) Re-generate the manual files:
  98
  99     $ tar xzf openssl-X.Y.Z.tar.gz
 100     $ (cd openssl-X.Y.Z && ./Configure --prefix=/usr --openssldir=/etc/ssl &&
 101        make build_man_docs)
 102     [...]
 103     $ find openssl-X.Y.Z/doc/man/man1 -name '*.1' -exec cp {} secure/usr.bin/openssl/man/ \;
 104     $ find openssl-X.Y.Z/doc/man/man3 -name '*.3' -exec cp {} secure/lib/libcrypto/man/man3/ \;
 105     $ find openssl-X.Y.Z/doc/man/man5 -name '*.5' -exec cp {} secure/lib/libcrypto/man/man5/ \;
 106     $ find openssl-X.Y.Z/doc/man/man7 -name '*.7' -exec cp {} secure/lib/libcrypto/man/man7/ \;
 107     $ grep -nrF usr/local secure/lib/libcrypto/man secure/usr.bin/openssl/man
 108     [correct the references to the prefix and OpenSSL directories]
 109     $ git commit --amend secure/lib/libcrypto/man secure/usr.bin/openssl/man
 110
 111     Review the diff and tree status for anything requiring attention.
 112
 113 16) Build and install world, reboot, test.
 114
 115 17) Test the legacy and fips providers as well: (here with "test" as the password)
 116
 117     $ echo test | openssl rc4 -provider legacy -e -a -pbkdf2
 118     enter RC4 encryption password:
 119     Verifying - enter RC4 encryption password:
 120     U2FsdGVkX1+JvhqxLMOvlxvTi1/h
 121
 122     # openssl fipsinstall -out /etc/ssl/fipsmodule.cnf -module /usr/lib/ossl-modules/fips.so
 123     INSTALL PASSED
 124     # vi /etc/ssl/openssl.cnf
 125     [enable the FIPS module]
 126     # echo test | openssl aes-256-cbc -provider fips -e -a -pbkdf2
 127     U2FsdGVkX19lTexiYsnMX83ZLSojBOFwv7GB0Plhgmw=
 128
 129 18) Commit and hope you did not miss anything.
 130