update HOWTOs

Reviewed-by: Tomas Mraz <[email protected]>
(Merged from #218)

Author: quarckster

HOWTO-handle-security-issue.md

@@ -382,13 +382,13 @@ References
 ==========
 
 URL for this Security Advisory:
-https://www.openssl.org/news/secadv/{YYYYMMDD}.txt
+https://openssl-library.org/news/secadv/{YYYYMMDD}.txt
 
 Note: the online version of the advisory may be updated with additional details
 over time.
 
 For details of OpenSSL severity classifications please see:
-https://www.openssl.org/policies/general/security-policy.html
+https://openssl-library.org/policies/general/security-policy
 ```
 
 Where:
@@ -603,7 +603,7 @@ Finish by publishing all the applicable
 `vulnerabilities-json/CVE-YYYY-NNNN.json` as instructed in [private cvepool.md].
 
 [public openssl/openssl repository]: https://github.com/openssl/openssl
-[Security Policy]: https://www.openssl.org/policies/general/security-policy.html
+[Security Policy]: https://openssl-library.org/policies/general/security-policy
 [GitHub Security Advisory]: https://docs.github.com/en/code-security/security-advisories/repository-security-advisories/about-repository-security-advisories
 [HOWTO-make-a-release.md]: ./HOWTO-make-a-release.md
 

HOWTO-make-a-release.md

@@ -103,7 +103,7 @@ it's implied that the former is frozen as well.
 
 ## Notify comitters and platform owners of the freeze
 
-When the tree is frozen, an email should be sent to [email protected], as well as to the community platform owners (documented [here](https://www.openssl.org/policies/general-supplemental/platforms.html))indicating that the tree is frozen, and how long the freeze is expected to last.  It should also indicate to the community platform owners that additional, more frequent testing during the freeze would be appreciated, as community platforms are not all in our CI system.  This will help mitigate inadvertent breakage during the freeze period on platforms we do not consistently test against.
+When the tree is frozen, an email should be sent to [email protected], as well as to the community platform owners (documented [here](https://openssl-library.org/policies/platforms/))indicating that the tree is frozen, and how long the freeze is expected to last.  It should also indicate to the community platform owners that additional, more frequent testing during the freeze would be appreciated, as community platforms are not all in our CI system.  This will help mitigate inadvertent breakage during the freeze period on platforms we do not consistently test against.
 
 
 ## Make sure that the openssl source is up to date

HOWTO-publish-a-release.md

@@ -13,10 +13,7 @@ Releases are staged by another procedure, separate from this.
     -   [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)
+    -   [Publish GitHub release](#publish-github-release)
     -   [Update the release metadata](#update-the-release-metadata)
 -   [Post-publishing tasks](#post-publishing-tasks)
     -   [Check automations](#check-automations)
@@ -87,82 +84,18 @@ 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
+## Publish GitHub 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.
-
-*NOTE*  This section should only be performed for public releases, i.e.
-releases made from `[email protected]:openssl/openssl.git` or
-`[email protected]: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 `[email protected]:openssl/openssl.git` or
-    `[email protected]:openssl/security.git`:
-
-    URL: https://github.com/openssl/openssl/releases
-
-    GH CLI `--repo`: github.com/openssl/openssl
-
--   For releases from `[email protected]: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".
+When a tag is pushed to the GitHub repository the automation creates a draft
+release in https://github.com/openssl/openssl/releases. Check the signed
+announcement .asc file. Check that the tarball length and hashes match in
+the .md5, .sha1, .sha256.
 
 For the release notes [^1], we currently use the same text as is added in the
-`newsflash.md` file to announce the release
-(see [Update the release data locally](#update-the-release-data-locally) below)
+`newsflash.md` file to announce the release.
 
 [^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.
 
@@ -171,27 +104,6 @@ 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
@@ -216,19 +128,6 @@ 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
@@ -237,49 +136,34 @@ 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/>
+-   <https://openssl-library.org/source>
 
 Check the notes look sensible at:
 
--   <https://www.openssl.org/news/newslog.html>
+-   <https://openssl-library.org/news/newslog>
 
 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>
+-   <https://openssl-library.org/news/openssl-3.0-notes>
+-   <https://openssl-library.org/news/openssl-3.1-notes>
+-   <https://openssl-library.org/news/openssl-3.2-notes>
+-   <https://openssl-library.org/news/openssl-3.3-notes>
 
 ## 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
+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
+signing the release announcement.
 
 ## 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)*
+that you copied into the release data repo*
 
 *This section is only applicable if this is a security release*
 
@@ -323,14 +207,6 @@ 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

HOWTO-stage-a-release.md

@@ -24,11 +24,9 @@ Updates pending!
     -   [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)
+    -   [Generate the announcement text](#generating-the-tarball-and-announcement-text)
     -   [Remember the results](#remember-the-results)
 
 # Prerequisites
@@ -41,8 +39,6 @@ programs in you `$PATH`:
 - openssl
 - gpg
 - git
-- ssh
-- sftp
 
 (note: this may not be a complete list)
 
@@ -86,13 +82,6 @@ You must have OpenSSL's team key:
 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, `[email protected]`.  To test this, try to log in with sftp:
-
-    sftp [email protected]
-
 ## Prepare your repository checkouts
 
 -   To stage a release, you need to checkout the release staging tool
@@ -117,13 +106,13 @@ address, `[email protected]`.  To test this, try to log in with sftp:
 
 # Staging tasks
 
-## Generate the tarball and announcement text
+## Generate the 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
+To generate and stage 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.
@@ -147,13 +136,11 @@ It is generally called like this:
 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.
+staged 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.
+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.