Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[#726] feat(doc): Add document on how to sign and verify releases #729

Merged
merged 4 commits into from
Nov 16, 2023
Merged

[#726] feat(doc): Add document on how to sign and verify releases #729

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
a92778b
Add document on how to sign and verify releases
justinmclean Nov 13, 2023
8910a30
fix prerequisites
justinmclean Nov 13, 2023
5c3b974
add platform support note
justinmclean Nov 13, 2023
bca6521
expand instructions
justinmclean Nov 15, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 78 additions & 0 deletions docs/how-to-sign-releases.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
---
title: "How to Sign and Verify a Gravitino Releases"
date: 2023-11-01T014:00:00+11:00
license: "Copyright 2023 Datastrato.
This software is licensed under the Apache License version 2."
---
## How to Sign and Verify a Gravitino Releases

## Prerequisites

+ PGP
yuqi1129 marked this conversation as resolved.
Show resolved Hide resolved
+ Release artifacts

## Signing a release

1. If GPG or GnuPG is not installed, install it. This only needs to be done once.

```shell
brew install gpg
yuqi1129 marked this conversation as resolved.
Show resolved Hide resolved
```

2. Create a public/private key pair. This only needs to be done once. It recommended to set the expiry to 5 years and not enter a comment, all other defaults are fine.

```shell
gpg --full-generate-key
```

Be sure to keep your private key secure. Do not forget your password and also record it securely somewhere.

3. To sign a release:

```shell
gpg --detach-sign —armor <filename>.[zip|tar.gz]
```

If you have more than one release file, sign each separately.

4. Generate hashes for a release:

```shell
shasum -a 512 <filename>.[zip|tar.gz] > <filename>.[zip|tar.gz].sha512
```
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

AFAIK, we don't need step 2-4 to sign a release binary, our gradle assembleDistribution will automatically generate a sha256 file corresponding to the release binary.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A hash is not a signature. Hashes can be used to verify the release contents, but a signature can be used to verify release authenticity and contents.

Copy link
Member Author

@justinmclean justinmclean Nov 13, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The assembleDistribution only produces a ".tar.gz", we have both a "zip" and a ".tar.gz" in GitHub, and both will need hashes and signatures. Any reason why sha256 rather than sha512 was selected?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The assembleDistribution only produces a ".tar.gz", we have both a "zip" and a ".tar.gz" in GitHub, and both will need hashes and signatures.

If desired, we can support the generation of both tar.gz and .zip files with a few code changes in the build.gradle.kts script.

Any reason why sha256 rather than sha512 was selected?

There is no particular reason to choose sha256, we can change it to sha512 if needed


5. Copy your public KEY to the KEYS file. This only needs to be done once.

```shell
gpg --output KEY --armor --export <youremail>
cat KEY >> KEYS
```

6. Publish hashes and signatures.

Upload the generated .sig and .sha512 files along with the release artifacts and KEYS files.

## Verifying a Release

1. Import the public KEYS used to sign releases.

```shell
gpg --import KEYS
```

2. Verify the signature.

```shell
gpg --verify <filename>.[zip|tar.gz].asc
```

The output should contain the text "Good signature from ..."


3. Verify the hashes.

```shell
diff -u <filename>.[zip|tar.gz]sha512 <(shasum -a 512 <filename>.[zip|tar.gz])
```

The signatures should match and there be no differences.