From fccdc29287d3828221e085eab3cf3a05df1007db Mon Sep 17 00:00:00 2001 From: Richard Levitte Date: Fri, 19 May 2023 14:02:34 +0200 Subject: [PATCH] Reorganize the release HOWTO This splits up HOWTO-make-a-release.md into two new documents that reflect the fact that *staging* and *publishing* a release are really two separate things. This also reflects that we're working towards full automation for staging releases. Reviewed-by: Paul Dale Reviewed-by: Matt Caswell Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/tools/pull/145) --- HOWTO-make-a-release.md | 419 +++++-------------------------------- HOWTO-publish-a-release.md | 343 ++++++++++++++++++++++++++++++ HOWTO-stage-a-release.md | 167 +++++++++++++++ 3 files changed, 560 insertions(+), 369 deletions(-) create mode 100644 HOWTO-publish-a-release.md create mode 100644 HOWTO-stage-a-release.md diff --git a/HOWTO-make-a-release.md b/HOWTO-make-a-release.md index 6cecb85..a102f19 100644 --- a/HOWTO-make-a-release.md +++ b/HOWTO-make-a-release.md @@ -1,36 +1,21 @@ # 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. +This file documents the overall OpenSSL release process. Some parts of this +process is documented in other files that go into deeper detail. # 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) - - [Prepare your repository checkouts](#prepare-your-repository-checkouts) + - [A method for reviewing](#a-method-for-reviewing) +- [Preparation tasks](#preparation-tasks) - [Freeze the source repository](#freeze-the-source-repository) [three business days before release] - [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 release data locally](#update-the-release-data-locally) - [do not push] +- [Stage the release](#stage-the-release) - [Publish the release](#publish-the-release) - - [Updating the release data](#updating-the-release-data) -- [Post-publishing tasks](#post-publishing-tasks) - - [Check the website](#check-the-website) [only for public releases] - - [Send the announcement mail](#send-the-announcement-mail) - - [Send out the Security Advisory](#send-out-the-security-advisory) +- [Post-releasing tasks](#post-publishing-tasks) - [Unfreeze the source repository](#unfreeze-the-source-repository) - - [Security fixes](#security-fixes) - [Keep in touch](#keep-in-touch) @@ -41,9 +26,7 @@ and additional tester. 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) @@ -52,94 +35,42 @@ programs in you `$PATH`: You must have access to the following repositories: -- `git@github.openssl.org:openssl/openssl.git` or - `git@github.openssl.org:openssl/premium.git` - - `openssl/openssl` is the public source repository, while - `openssl/premium` is the premium release repository. - -- `git@github.openssl.org:otc/tools.git` - - This contains certain common tools - -- `git@github.openssl.org:omc/data.git` - - This contains files to be updated as part of any release - -## PGP / GnuPG key +- `git@github.openssl.org:openssl/openssl.git` -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. + This is the public source repository, so is only necessary to stage + a public release, which are those that haven't reached End-Of-Life + yet. -## SSH access +- `git@github.openssl.org:openssl/security.git` -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: + This is the security source repository, where security fixes are + staged before being publically released. It is used as source + repository instead of `openssl/openssl` to stage a security + release. - ssh dev.openssl.org +- `git@github.openssl.org:openssl/premium.git` -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 + This is the source repository for premium customers, used for both + security and non-security releases. ## 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. +In some parts of the release process, peer review may apply. The review +methods are specified in more detail in those parts. -The release person and the reviewer must have a conversation to confirm or -figure out how the review shall be done. - -# Pre-publishing tasks +# Preparation tasks Some of the actions in this section need to be repeated for each OpenSSL version released. ## Prepare your repository checkouts -You will need to checkout at least three working trees: - -- one for extra tools - - git clone git@github.openssl.org:otc/tools.git tools +- For each release to be staged, you need to checkout its source + repository, which is one of: - The resulting directory will be referred to as `$TOOLS` - -- one for release data - - git clone git@github.openssl.org:omc/data.git data - -- At least one for openssl source - - git clone git@github.openssl.org:openssl/openssl.git - - or - - git clone git@github.openssl.org:openssl/premium.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) + - `git clone git@github.openssl.org:openssl/openssl.git` + - `git clone git@github.openssl.org:openssl/security.git` + - `git clone git@github.openssl.org:openssl/premium.git` ## Freeze the source repository @@ -151,7 +82,7 @@ doing any pushes. Someone other than the person doing the release should run the command. This must be done from a checkout of that source repository, so for public -releases: +as well as security releases: git push git@github.openssl.org:openssl/openssl.git HEAD:refs/frozen/NAME @@ -165,18 +96,19 @@ Note: it currently doesn't matter what source branch is used when pushing, the whole repository is frozen either way. The example above uses whatever branch you happen to have checked out. +Note: `git@github.openssl.org:openssl/security.git` is derived from +`git@github.openssl.org:openssl/openssl.git`, so when freezing the latter, +it's implied that the former is frozen as well. + ## 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. +For security releases, merge all applicable and approved security PRs. -*NOTE: the files CHANGES and NEWS are called CHANGES.md and NEWS.md in -OpenSSL versions from version 3.0 and on* +*NOTE: the files CHANGES.md and NEWS.md are called CHANGES and NEWS in +OpenSSL versions before version 3.0* -For each source checkout, make sure that the CHANGES and NEWS files have -been updated and reviewed. +For each source checkout, make sure that the CHANGES.md and NEWS.md 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. @@ -184,269 +116,27 @@ 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 Release and -Reviewed-By trailers as required. - -*Do* send the auto-generated commits to the reviewer and await their -approval. - -*Do not push* changes to the source repo at this stage. -(the source repo being one of `git@github.openssl.org:openssl/openssl.git` -or `git@github.openssl.org:openssl/premium.git`) +# Stage the release -## Generate the tarball and announcement text +See [HOWTO-stage-a-release.md](HOWTO-stage-a-release.md), which describes +this in detail. -*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 source repo at this stage. -(the source repo being one of `git@github.openssl.org:openssl/openssl.git` -or `git@github.openssl.org:openssl/premium.git`) - -The release generating script is in the OpenSSL source checkout, and is -generally called like this: - - $TOOLS/release-tools/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: - - $TOOLS/release-tools/release.sh --help - -- To get a man-page: - - $TOOLS/release-tools/release.sh --manual - -## Update the release data locally - -*The changes in this section should be made in your clone of the release -data repo* - -- Newsflash *[only for public releases]* - - Update the 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. - -- Security advisory *[both public and premium releases]* - - Update the vulnerabilities.xml file if appropriate. - - If there is a Security Advisory then copy it into the secadv directory. - -Make a pull request from your changes, against the release data repo (the -release data repo being `git@github.openssl.org:omc/data.git`). - -*Do not merge the pull request at this point*, even if the reviewer already -approved it. - -*Do* send the commits to the reviewer and await their approval. It's -advisable to use this command to get a copy of those commits: - - git format-patch +This may be done independently of [publishing the release](#publish-the-release). +However, if done manually, the same person should stage and publish the +release, as doing it this way depends on that person's local clones and +checkouts. # 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 "upload" 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. +See [HOWTO-publish-a-release.md](HOWTO-publish-a-release.md), which +describes this in detail. -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. +This may be done independently of [staging the release](#stage-the-release). +However, if done manually, the same person should stage and publish the +release, as doing it this way depends on that person's local clones and +checkouts. -For public releases, verify that the tarballs are available via FTP: - - ls /srv/ftp/source - -For premium releases, verify that the tarballs are available via SFTP: - - ls /srv/premium - -*For OpenSSL 3.0 and on*, push your local changes to the appropriate source -repo as instructed by `$TOOLS/release-tools/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 appropriate -source repo, and please do remember to push the release tags as well. You -may want to sanity check the pushes by inserting the `-n` (dry-run) -option. You must specify the repository / remote and tag to be pushed: - - git push - -Upload the release files to the "Releases" section on github. Visit this URL: - -https://github.com/openssl/openssl/releases - -Click the "Draft a new release" button. Give the release a title, e.g. -"OpenSSL 3.1.0". Give it a description. Typically this will be the same text -that was used in the newsflash.txt file to announce the release. Upload the -four release files, e.g. - -openssl-3.1.0.tar.gz -openssl-3.1.0.tar.gz.asc -openssl-3.1.0.tar.gz.sha1 -openssl-3.1.0.tar.gz.sha256 - -If this is not the latest stable release, uncheck the "Set as the latest release" -checkbox. If this is an alpha or beta release check the "Set as a pre-release" -checkbox. Finally click "Publish release". - -## Updating the release data - -If there is a PR against the release repo to be merged, perform the merge -now. - -When you do this for a public release, the website will get updated and a -script to flush the Akamai CDN cache will be run. - -You can look at to see the automation -builds in action. The builder called `web` is of particular interest. - -You can also look at the result at ; the -CDN-hosted www.openssl.org should get updated withing minutes later. - -# Post-publishing tasks - -## Check the website - -*NOTE: This is **only** for public releases* - -Verify that the release notes, which are built from the CHANGES.md file -in the release, have been updated. This is done automatically by OpenSSL -automation; if you see a problem, check if the web build job has been -performed yet, you may have to wait a few minutes before it kicks in. - -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. They -should be sent from the account of the person that owns the key used for -signing the release announcement. Ensure that mutt is configured correctly - -send a test email first if necessary. - -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 \ - 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 release data repo, up in the section -[Update the release data locally](#update-the-release-data-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 user that signed the advisory. - -For all releases, send it to the default set of public mailing lists: - - REPLYTO="openssl@openssl.org" mutt -s "OpenSSL Security Advisory" \ - openssl-project openssl-users openssl-announce \ - -and approve the messages. - -For premium releases, approve the support-announce email as well. Go to - and approve the -messages. - -Check that the mailing list messages have arrived. +# Post-releasing tasks ## Unfreeze the source repository. @@ -460,17 +150,8 @@ or: git push --delete git@github.openssl.org:openssl/premium.git \ refs/frozen/NAME -## 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/HOWTO-publish-a-release.md b/HOWTO-publish-a-release.md new file mode 100644 index 0000000..9b7280e --- /dev/null +++ b/HOWTO-publish-a-release.md @@ -0,0 +1,343 @@ +# HOW TO PUBLISH A RELEASE + +This file documents how to publish an OpenSSL release. Please fix any errors +you find while doing, or just after, your next release! + +Releases are staged by another procedure, separate from this. + +# Table of contents + +- [Prerequisites](#prerequisites) + - [Software](#software) + - [Repositories](#repositories) + - [SSH access](#check-your-access) +- [Publish the release](#publish-the-release) + - [Update the source repositories](#update-the-source-repositories) + - [Upload release files to OpenSSL downloads](#upload-release-files-to-openssl-downloads) [only public releases] + - [Upload release files to Github](#upload-release-files-to-github) + - [Web method](#web-method) + - [GH CLI method](#gh-cli-method) + - [Update the release metadata](#update-the-release-metadata) +- [Post-publishing tasks](#post-publishing-tasks) + - [Check automations](#check-automations) + - [Check the website](#check-the-website) + - [Send the announcement mail](#send-the-announcement-mail) + - [Send out the Security Advisory](#send-out-the-security-advisory) + - [MITRE / CVE.org](#mitre-cve-org) + +# Prerequisites + +## Software + +Apart from the basic operating system utilities, you must have the following +programs in you `$PATH`: + +- ssh +- git + +(note: this may not be a complete list) + +## Repositories + +You must have access to the following repositories: + +- `git@github.openssl.org:omc/data.git` + + This contains files to be updated as part of any release. + +- Any of: + + - `git@github.openssl.org:openssl/openssl.git` + + This is the public source repository, so is only necessary to stage + a public release, which are those that haven't reached End-Of-Life + yet. + + - `git@github.openssl.org:openssl/security.git` + + This is the security source repository, where security fixes are + staged before being publically released. It is used as source + repository instead of `openssl/openssl` to stage a security + release. + + - `git@github.openssl.org:openssl/premium.git` + + This is the source repository for premium customers, used for both + security and non-security releases. + +## 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 + +# Publish the release + +## Update the source repositories + +Finish up by pushing your local changes to the appropriate source repo as +instructed by `$TOOLS/release-tools/stage-release.sh`, which was performed +when [staging the releases](HOWTO-stage-a-release.md). You may want to +sanity check the pushes by inserting the `-n` (dry-run) option. + +## Upload release files to OpenSSL downloads + +*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. + +*NOTE* This section should only be performed for public releases, i.e. +releases made from `git@github.openssl.org:openssl/openssl.git` or +`git@github.openssl.org:openssl/security.git`. + +Everything in this section is to be done as the `openssl` user on +`dev.openssl.org`, so if you haven't done that yet, you now *must* perform +the steps described in [SSH access](#ssh-access) above. + +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 `upload` 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: + + 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 for download: + + ls /srv/ftp/source + +## Upload release files to Github + +Upload the release files to the "Releases" section on github. Do this by +visiting the release URL that corresponds to the source repository that the +release was made from, or by using [the Github CLI tool](https://cli.github.com/]: + +- For releases from `git@github.openssl.org:openssl/openssl.git` or + `git@github.openssl.org:openssl/security.git`: + + URL: https://github.com/openssl/openssl/releases + + GH CLI `--repo`: github.com/openssl/openssl + +- For releases from `git@github.openssl.org:openssl/premium.git`: + + URL: https://github.openssl.org/openssl/extended-releases/releases + + GH CLI `--repo`: github.openssl.org/openssl/openssl + +In both tools, you will need to make a title and a short description. + +For the title, use something like "OpenSSL 3.1.0". + +For the release notes [^1], we currently use the same text as is added in the +`newsflash.txt` file to announce the release +(see [Update the release data locally](#update-the-release-data-locally) below) + +[^1]: The release notes field has previously been described as "description" + +### Web method + +Click the "Draft a new release" button. Give the release a title and a +release note as recommended above. Upload the four release files, e.g. + +- `openssl-3.1.0.tar.gz` +- `openssl-3.1.0.tar.gz.asc` +- `openssl-3.1.0.tar.gz.sha1` +- `openssl-3.1.0.tar.gz.sha256` + +If this is an alpha or beta release, check the "Set as a pre-release" +checkbox. + +If this is the latest release version, check the "Set as the latest release" +checkbox. + +Finish up by clicking "Publish release". + +### GH CLI method + +This is an example: + + gh release create \ + --repo github.com/openssl/openssl --verify-tag --draft \ + --title "OpenSSL 3.1.0" \ + --notes "Final version of OpenSSL 3.1.0 is now available: please download and upgrade!" + openssl-3.1.0 \ + openssl-3.1.0.tar.gz \ + openssl-3.1.0.tar.gz.asc \ + openssl-3.1.0.tar.gz.sha1 \ + openssl-3.1.0.tar.gz.sha256 \ + +The first non-option argument `openssl-3.1.0` is the tag, the rest are the +files to upload. + +If this is an alpha or beta release, additionally use the option `--prerelease`. + +If this is the latest release version, additionally use `--latest`. + +## Update the release metadata + +*The changes in this section should be made in your clone of the release +data repo* + +- Newsflash *[only for public releases]* + + Update the 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. + +- Security advisory *[both public and premium releases]* + + Update the vulnerabilities.xml file if appropriate. + + If there is a Security Advisory then copy it into the secadv directory. + +Make a pull request from your changes, against the release metadata repo +(the release metadata repo being `git@github.openssl.org:omc/data.git`). +Await approval from reviewers, then merge the pull request. + +# Post-publishing tasks + +## Check automations + +The updates performed when [publishing the releases](#publish-the-release), +automations on should kick in. Typically, +the builders named "doc" and "web" should be seen working within minutes +(pending other builder that mirror the repositories that have been updated). + +These builders update different aspects of the web site, and will finish off +by invalidating the corresponding pages in the CDN cache, to ensure that +they are reloaded by the CDN. + +You can also look at the result at . + +## 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 OpenSSL +automation; if you see a problem, check if the web build job has been +performed yet, you may have to wait a few minutes before it kicks in. + +Wait for a while for the CDN 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. They +should be sent from the account of the person that owns the key used for +signing the release announcement. Ensure that mutt is configured correctly - +send a test email first if necessary. + +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 \ + 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 release data repo, up in the section +[Update the release data locally](#update-the-release-data-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 user that signed the advisory. + +For all releases, send it to the default set of public mailing lists, +replacing `YOU@openssl.org` with your email address: + + EMAIL="YOU@openssl.org" REPLYTO="openssl@openssl.org" \ + mutt -s "OpenSSL Security Advisory" \ + openssl-project openssl-users openssl-announce \ + +and approve the messages. + +For premium releases, approve the support-announce email as well. Go to + and approve the +messages. + +Check that the mailing list messages have arrived. + +## MITRE / CVE.org + +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 +`otc/security`. + +Close the github advisory without pushing to github and remove the private +github fork if there was one. diff --git a/HOWTO-stage-a-release.md b/HOWTO-stage-a-release.md new file mode 100644 index 0000000..184d2d7 --- /dev/null +++ b/HOWTO-stage-a-release.md @@ -0,0 +1,167 @@ +# HOW TO STAGE 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! + +Anyone with access to the necessary resources may stage a release. Reviews +for doing so isn't necessary, that's done "naturally" as part of publishing, +see [HOWTO-publish-a-release.md](HOWTO-publish-a-release.md). + +# Automation + +**Staging releases is becoming automated**, so this document will soon only +be interesting to know how to perform this manually, should the need arise +(automation failure, or to stage releases that automation isn't prepared +for). + +This automation is currently still undergoing tests, and isn't quite +reflected in [HOWTO-publish-a-release.md](HOWTO-publish-a-release.md). +Updates pending! + +# Table of contents + +- [Prerequisites](#prerequisites) + - [Software](#software) + - [Repositories](#repositories) + - [PGP / GnuPG key](#pgp-gnupg-key) + - [SFTP access](#check-your-access) + - [Prepare your repository checkouts](#prepare-your-repository-checkouts) +- [Staging tasks](#staging-tasks) + + - [Generate the tarball and announcement text](#generating-the-tarball-and-announcement-text) + - [Remember the results](#remember-the-results) + +# Prerequisites + +## Software + +Apart from the basic operating system utilities, you must have the following +programs in you `$PATH`: + +- openssl +- gpg +- git +- ssh +- sftp + +(note: this may not be a complete list) + +## Repositories + +You must have access to the following repositories: + +- `git@github.openssl.org:otc/tools.git` + + This contains the release staging tool. + +- Any of: + + - `git@github.openssl.org:openssl/openssl.git` + + This is the public source repository, so is only necessary to stage + a public release, which are those that haven't reached End-Of-Life + yet. + + - `git@github.openssl.org:openssl/security.git` + + This is the security source repository, where security fixes are + staged before being publically released. It is used as source + repository instead of `openssl/openssl` to stage a security + release. + + - `git@github.openssl.org:openssl/premium.git` + + This is the source repository for premium customers, used for both + security and non-security releases. + +## PGP / GnuPG key + +You must have OpenSSL's team key: + + $ gpg --list-secret-key EFC0A467D613CB83C7ED6D30D894E2CE8B3D79F5 + sec rsa4096 2014-10-04 [SC] [expires: 2027-03-09] + EFC0A467D613CB83C7ED6D30D894E2CE8B3D79F5 + uid [ultimate] OpenSSL Security + uid [ultimate] OpenSSL security team + uid [ultimate] OpenSSL OMC + ssb rsa4096 2014-10-04 [E] [expires: 2024-01-30] + +If you don't have it and think you should, get an export from someone on the +team that has it. + +## SFTP access + +To stage a release, you must have appropriate access to OpenSSL's upload +address, `upload@dev.openssl.org`. To test this, try to log in with sftp: + + sftp upload@dev.openssl.org + +## Prepare your repository checkouts + +- To stage a release, you need to checkout the release staging tool + + git clone git@github.openssl.org:otc/tools.git tools + + The resulting directory will be referred to as `$TOOLS` + +- For each release to be staged, you need to checkout its source + repository, which is one of: + + - `git clone git@github.openssl.org:openssl/openssl.git` + - `git clone git@github.openssl.org:openssl/security.git` + - `git clone git@github.openssl.org:openssl/premium.git` + +- If you're staging multiple releases from one repository 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) + +# Staging tasks + +## Generate the tarball and announcement text + +*The changes in this section should be made in your clone of the openssl +source repo* + +To generate and stage a release tarball and announcement text, there is a +script `$TOOLS/release-tools/stage-release.sh`. It's expected to be run +while standing in the worktree of an OpenSSL source repository, and the +expects the checked out branch to be the branch to stage the release from, +matching one of OpenSSL release branch patterns. + +The stage-release script has a multitude of other options that are useful +for specific cases, and is also self-documented: + +- To get a quick usage reminder: + + $TOOLS/release-tools/stage-release.sh --help + +- To get a man-page: + + $TOOLS/release-tools/stage-release.sh --manual + +It is generally called like this: + + $TOOLS/release-tools/stage-release.sh --reviewer=NAME \ + --local-user=EFC0A467D613CB83C7ED6D30D894E2CE8B3D79F5 + +This scripts will perform a number of preparatory tasks, such as updating +the copyright year, running `make update`, update release dates, and move +the branch to the next development version. This results not only in a +staged release tarball and announcement text, but also in a set of commits. + +After having run the stage-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. +Check the data left in the metadata .dat file. + +*Do not push* the local commits to the source repo at this stage. + +## Remember the results + +*Make sure to take note of all the instructions the stage-release script gave +you at the end. They will be needed when +[publishing the release](HOWTO-publish-a-release.md).* -- 2.34.1