diff --git a/HOWTO-make-a-release.md b/HOWTO-make-a-release.md new file mode 100644 index 0000000..012256e --- /dev/null +++ b/HOWTO-make-a-release.md @@ -0,0 +1,400 @@ +# HOW TO MAKE A RELEASE + +This file documents how to make an OpenSSL release. Please fix any errors +you find while doing, or just after, your next release! + +Releases are done by one person, with a second person acting as the reviewer +and additional tester. + +# Table of contents + +- [Prerequisites](#prerequisites) + - [Software](#software) + - [Repositories](#repositories) + - [PGP / GnuPG key](#pgp-gnupg-key) + - [SSH access](#check-your-access) + - [A method for reviewing](#a-way-to-reviewing) +- [Pre-publishing tasks](#pre-publishing-tasks) + - [Freeze the source repository](#freeze-the-source-repository) [the day before release] + - [Prepare your repository checkouts](#prepare-your-repository-checkouts) + - [Make sure that the openssl source is up to date](#make-sure-that-the-openssl-source-is-up-to-date) + - [Generate the tarball and announcement text](#generating-the-tarball-and-announcement-text) + - [OpenSSL 3.0 and on](#openssl-3.0-and-on) + - [OpenSSL before 3.0](#openssl-before-3.0) + - [Update the website locally](#update-the-website-locally) [do not push] +- [Publish the release](#publish-the-release) +- [Post-publishing tasks](#post-publishing-tasks) + - [Check the website](#check-the-website) + - [Send the announcement mail](#send-the-announcement-mail) + - [Send out the Security Advisory](#send-out-the-security-advisory) + - [Unfreeze the source repository](#unfreeze-the-source-repository) + - [Security fixes](#security-fixes) + - [Keep in touch](#keep-in-touch) + + +# Prerequisites + +## Software + +Apart from the basic operating system utilities, you must have the following +programs in you `$PATH`: + +- openssl +- ssh +- gpg +- git + +(note: this may not be a complete list) + +## Repositories + +You must have access to the following repositories: + +- `openssl-git@git.openssl.org:openssl.git` + + This is the usual main source repository + +- `openssl-git@git.openssl.org:openssl-web.git` + + This is the website repository + +- `openssl-git@git.openssl.org:tools.git` + + This contains certain common tools + +## PGP / GnuPG key + +You must have a PGP / GnuPG key, and its fingerprint should be present in +the file `doc/fingerprints.txt` in the source of the immediately prior +OpenSSL release. + +## SSH access + +To perform a release, you must have appropriate access to OpenSSL's +development host, dev.openssl.org. To test this, try to log in with ssh: + + ssh dev.openssl.org + +You must also check that you can perform tasks as the user 'openssl' on +dev.openssl.org. When you have successfully logged in, test your access to +that user with sudo: + + sudo -u openssl id + +## A method for reviewing + +For reviewing to take place, the release person and the reviewer need a way +to share changes that are being applied. Most commonly, that's done as PRs +(for normal releases) or security advisories (for undisclosed security +fixes) through Github. + +Security advisories are created using the Github Security tab, and will +generate a private repository, to which you can add collaborators (the +reviewer, for instance), and use it to fix the issue via pull requests. +For more information, please read Github's [creating a security advisory], +including the "Next Steps" at the end of that page. + +[creating a security advisory]: + + +The release person and the reviewer are allowed to use other means to share +the commits to be reviewed if they desire. + +The release person and the reviewer must have a conversation to confirm or +figure out how the review shall be done. + +# Pre-publishing tasks + +Some of the actions in this section need to be repeated for each OpenSSL +version released. + +## Freeze the source repository + +The day before the release, freeze the main repository. This locks out +everyone but the named user, who is doing the release, from doing any +pushes. Someone other than the person doing the release should run the +command. For example: + + ssh openssl-git@git.openssl.org freeze openssl NAME + +## Prepare your repository checkouts + +You will need to checkout at least three working trees: + +- one for the website + + git clone openssl-git@git.openssl.org:openssl-web.git website + +- one for extra tools + + git clone openssl-git@git.openssl.org:tools.git tools + + The resulting directory will be referred to as `$TOOLS` + +- At least one for openssl source + + git clone openssl-git@git.openssl.org:openssl.git + + If you're doing multiple releases in one go, there are many ways to deal + with it. One possibility, available since git 2.5, is to use `git + worktree`: + + (cd openssl; + git worktree add ../openssl-1.1.1 OpenSSL_1_1_1-stable) + +## Make sure that the openssl source is up to date + +The person doing the release and the reviewer should both sanity-check the +source to be released at this point. Checks to consider include building +and verifying that make test passes on multiple plaforms - Linux, Windows, +etc. + +*NOTE: the files CHANGES and NEWS are called CHANGES.md and NEWS.md in +OpenSSL versions from version 3.0 and on* + +For each source checkout, make sure that the CHANGES and NEWS files have +been updated and reviewed. + +The NEWS file should contain a summary of any changes for the release; +for a security release, it's often simply a list of the CVEs addressed. +You should also update NEWS.md in the master branch to include details of +all releases. Only update the bullet points - do not change the release +date, keep it as **under development**. + +Add any security fixes to the tree and commit them. + +Make sure that the copyrights are updated. This script will update the +copyright markers and commit the changes (where $TOOLS stands for the +openssl-tools.git checkout directory): + + $TOOLS/release-tools/do-copyright-year + +Obtain approval for these commits from the reviewer and add the reviewed-by +headers as required. + +*Do* send the auto-generated commits to the reviewer and await their +approval. + +*Do not push* changes to the main source repo at this stage. +(the main source repo being `openssl-git@git.openssl.org:openssl.git`) + +## Generate the tarball and announcement text + +*The changes in this section should be made in your clone of the openssl +source repo* + +The method to generate a release tarball and announcement text has changed +with OpenSSL 3.0, so while we continue to make pre-3.0 OpenSSL releases, +there are two methods to be aware of. + +Both methods will leave a handful of files, most importantly the release +tarball. When they are done, they display a set of instructions on how to +perform the publishing tasks, *please take note of them*. + +After having run the release script, verify that its results are sensible. +Check the commits that were added, using for example `git log`. Check the +signed announcement .asc file. Check that the tarball length and hashes +match in the .md5, .sha1, .sha256, and review the announcment file. + +*Do* send the auto-generated commits to the reviewer and await their +approval. + +*Do not push* changes to the main source repo at this stage. +(the main source repo being `openssl-git@git.openssl.org:openssl.git`) + +### OpenSSL 3.0 and on + +The release generating script is in the OpenSSL source checkout, and is +generally called like this: + + dev/release.sh --reviewer=NAME + +This script has a multitude of other options that are useful for specific +cases, and is also self-documented: + +- To get a quick usage reminder: + + dev/release.sh --help + +- To get a man-page: + + dev/release.sh --manual + +### OpenSSL before 3.0 + +The release generating script is in the tools checkout, represented here +with $TOOLS, and is generally called like this: + + $TOOLS/release-tools/mkrelease.pl --reviewer=NAME + +The manual for that script is found in `$TOOLS/release-tools/MKRELEASE.md` + +## Update the website locally + +*The changes in this section should be made in your clone of the openssl +web repo* + +Update the news/newsflash.txt file. This normally is one or two lines. +Just copy and paste existing announcements making minor changes for the date +and version number as necessary. If there is an advisory then ensure you +include a link to it. + +Update the news/vulnerabilities.xml file if appropriate. + +If there is a Security Advisory then copy it into the news/secadv directory. + +*Do* send the commits to the reviewer and await their approval. + +Commit your changes, but *do not push* them to the website repo at this stage. +(the website repo being `openssl-git@git.openssl.org:openssl-web.git`) + +# Publish the release + +*BE CAREFUL* This section makes everything visible and is therefore largely +irreversible. If you are performing a dry run then DO NOT perform any steps +in this section. + +Check that the release has been uploaded properly. The release tarballs and +associated files should be in ~openssl/dist/new. They should be owned by +the openssl userid and world-readable. + +Copy the tarballs to appropriate directories. This can be done using the +do-release.pl script. See $TOOLS/release-tools/DO-RELEASE.md for a +description of the options. For example: + + sudo -u openssl perl ~openssl/do-release.pl --copy --move + +This will copy the relevant files to the website and move them from +`~openssl/dist/new` to `~openssl/dist/old` so they will not seen by a +subsequent release. Alternatively if you want to perform one release at a +time or copy/move the files manually, see below. + +The do-release.pl script will display the commands you will need to issue to +send the announcement emails later. Keep a note of those commands for +future reference. + +Verify that the tarballs are available via FTP: + + ftp://ftp.openssl.org/source/ + +And that they are ready for the website: + + ls /var/www/openssl/source + +*For OpenSSL 3.0 and on*, push your local changes to the main source repo as +instructed by `dev/release.sh`. You may want to sanity check the pushes by +inserting the `-n` (dry-run) option. + +*For OpenSSL before 3.0*, simply push your local changes to the main source +repo, and please do remember to push the release tags as well, which is done +separately with the `--tags` option. You may want to sanity check the +pushes by inserting the `-n` (dry-run) option. + +## Updating the website + +Push the website changes you made earlier to the OpenSSL website repo. When +you do this, the website will get updated and a script to flush the Akamai +CDN cache will be run. You can look at things on www-origin.openssl.org; +the CDN-hosted www.openssl.org should only be a few minutes delayed. + +# Post-publishing tasks + +## Check the website + +Verify that the release notes, which are built from the CHANGES.md file +in the release, have been updated. This is done automatically by the +commit-hook, but if you see a problem, try the following steps on +`dev.openssl.org`: + + cd /var/www/openssl + sudo -u openssl -H make relupd + sudo -u openssl -H ./bin/purge-one-hour + +Wait for a while for the Akamai flush to work (normally within a few minutes). +Have a look at the website and news announcement at: + +- +- + +Check the download page has updated properly: + +- + +Check the notes look sensible at: + +- + +Also check the notes here: + +- +- +- + +## Send the announcement mail + +Send out the announcements. Generic release announcement messages will be +created automatically by the build script and the commands you need to use +to send them were displayed when you executed do-release.pl above. +These should normally be sent from the openssl account. These are sent to +openssl-users, openssl-project, and openssl-announce. + +If do-release.pl was used with `--move` be sure to move the announcement +text files away from the staging directory after they have been sent. This +is done as follows (with VERSION replaced with the version of OpenSSL to +announce): + + sudo -u openssl \ + mutt -s "OpenSSL version VERSION published" \ + openssl-project openssl-users openssl-announce \ + < /home/openssl/dist/new/openssl-VERSION.txt.asc + sudo -u openssl \ + mv ~openssl/dist/new/openssl-VERSION.txt.asc ~openssl/dist/old + +## Send out the Security Advisory + +*The secadv file mentioned in this section is the Security Advisory +that you copied into the web repo, up in the section +[Update the website locally](#update-the-website-locally)* + +*This section is only applicable if this is a security release* + +Start with signing the Security Advisory as yourself: + + gpg --clearsign secadv_FILENAME.txt + +Then copy the result to the temporary directory on dev.openssl.org: + + scp secadv_FILENAME.txt.asc dev.openssl.org:/tmp + +To finish, log in on dev.openssl.org and send the signed Security +Advisory by email as the openssl user, and the remove it: + + sudo -u openssl mutt -s "OpenSSL Security Advisory" \ + openssl-project openssl-users openssl-announce \ + +and approve the messages. + +Check the mailing list messages have arrived. + +## Unfreeze the source repository. + + ssh openssl-git@git.openssl.org unfreeze openssl + +## Security fixes + +If this release includes security fixes with a CVE then you should inform +MITRE about them. See the instructions at the top of cvepool.txt in omc. + +Close the github advisory without pushing to github and remove the private +github fork if there was one. + +## Keep in touch + +Check mailing lists over the next few hours for reports of any success or +failure. If necessary fix these and in the worst case make another +release. + diff --git a/README b/README index 5aac518..1424950 100644 --- a/README +++ b/README @@ -1,3 +1,7 @@ -A collection of tools useful in OpenSSL development. +A collection of tools and instructions useful in OpenSSL development. -Each tool is in its own subdirectory and has its own README +Each set of tools is in its own subdirectory and has its own manuals +and READMEs. + +More generic instructions are in this top directory, called +HOWTO-something.md diff --git a/release-tools/mkrelease.pl b/release-tools/mkrelease.pl old mode 100644 new mode 100755