openssl
/
tools
mirror of https://github.com/openssl/tools
1
0
Fork 0
Code Issues Releases Wiki Activity

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 <pauli@openssl.org>
Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/tools/pull/145)
This commit is contained in:
Richard Levitte 2023-05-19 14:02:34 +02:00 committed by Tomas Mraz
parent b6c9089c4c
commit fccdc29287
3 changed files with 560 additions and 369 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

419
HOWTO-make-a-release.md
View File

@ -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`
- `git@github.openssl.org:openssl/openssl.git`
`openssl/openssl` is the public source repository, while
`openssl/premium` is the premium release repository.
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:otc/tools.git`
- `git@github.openssl.org:openssl/security.git`
This contains certain common tools
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:omc/data.git`
- `git@github.openssl.org:openssl/premium.git`
This contains files to be updated as part of any release
## 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
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.
In some parts of the release process, peer review may apply. The review
methods are specified in more detail in those parts.
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]:
<https://docs.github.com/en/free-pro-team@latest/github/managing-security-vulnerabilities/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
# 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:
- For each release to be staged, you need to checkout its source
repository, which is one of:
- one for extra tools
git clone git@github.openssl.org:otc/tools.git tools
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.
# Stage the release
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):
See [HOWTO-stage-a-release.md](HOWTO-stage-a-release.md), which describes
this in detail.
$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`)
## 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 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.
See [HOWTO-publish-a-release.md](HOWTO-publish-a-release.md), which
describes this in detail.
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.
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.
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.
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 <repository> <tagname>
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 <https://automation.openssl.org/> to see the automation
builds in action. The builder called `web` is of particular interest.
You can also look at the result at <https://www-origin.openssl.org>; 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:
- <https://www.openssl.org/>
- <https://www.openssl.org/news/>
Check the download page has updated properly:
- <https://www.openssl.org/source/>
Check the notes look sensible at:
- <https://www.openssl.org/news/newslog.html>
Also check the notes here:
- <https://www.openssl.org/news/openssl-1.0.2-notes.html>
- <https://www.openssl.org/news/openssl-1.1.0-notes.html>
- <https://www.openssl.org/news/openssl-1.1.1-notes.html>
## 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 \
</tmp/secadv_FILENAME.txt.asc
We also send it separately to oss-security (to avoid cross-posting with our
own lists):
REPLYTO="openssl@openssl.org" mutt -s "OpenSSL Security Advisory" \
oss-security@lists.openwall.com \
</tmp/secadv_FILENAME.txt.asc
Finally we also, send it to support-announce as well *and separately*. We always
do this, even if a premium release has not been affected:
REPLYTO="openssl@openssl.org" mutt -s "OpenSSL Security Advisory" \
support-announce </tmp/secadv_FILENAME.txt.asc
When done, remove the email file:
rm /tmp/secadv_FILENAME.txt.asc
Approve the openssl-announce email. Go to
<https://mta.openssl.org/mailman/admindb/openssl-announce>
and approve the messages.
For premium releases, approve the support-announce email as well. Go to
<https://mta.openssl.org/mailman/admindb/support-announce> 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.

343
HOWTO-publish-a-release.md Normal file
View File

@ -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 <https://automation.openssl.org/> 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 <https://www-origin.openssl.org>.
## 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:
- <https://www.openssl.org/>
- <https://www.openssl.org/news/>
Check the download page has updated properly:
- <https://www.openssl.org/source/>
Check the notes look sensible at:
- <https://www.openssl.org/news/newslog.html>
Also check the notes here:
- <https://www.openssl.org/news/openssl-1.0.2-notes.html>
- <https://www.openssl.org/news/openssl-1.1.0-notes.html>
- <https://www.openssl.org/news/openssl-1.1.1-notes.html>
- <https://www.openssl.org/news/openssl-3.0-notes.html>
- <https://www.openssl.org/news/openssl-3.1-notes.html>
## 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 \
</tmp/secadv_FILENAME.txt.asc
Finally, We also send it separately to oss-security (to avoid cross-posting
with our own lists), remember to replace `YOU@openssl.org` with your email
address:
EMAIL="YOU@openssl.org" REPLYTO="openssl@openssl.org" \
mutt -s "OpenSSL Security Advisory" \
oss-security@lists.openwall.com \
</tmp/secadv_FILENAME.txt.asc
For premium releases, send them to support-announce as well *and
separately*, remember to replace `YOU@openssl.org` with your email
address:
EMAIL="YOU@openssl.org" REPLYTO="openssl@openssl.org" \
mutt -s "OpenSSL Security Advisory" \
support-announce </tmp/secadv_FILENAME.txt.asc
When done, remove the email file:
rm /tmp/secadv_FILENAME.txt.asc
Approve the openssl-announce email. Go to
<https://mta.openssl.org/mailman/admindb/openssl-announce>
and approve the messages.
For premium releases, approve the support-announce email as well. Go to
<https://mta.openssl.org/mailman/admindb/support-announce> 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.

167
HOWTO-stage-a-release.md Normal file
View File

@ -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 <openssl-security@openssl.org>
uid [ultimate] OpenSSL security team <openssl-security@openssl.org>
uid [ultimate] OpenSSL OMC <openssl-omc@openssl.org>
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).*