Github user alopresto commented on a diff in the pull request:

    https://github.com/apache/nifi-site/pull/27#discussion_r201761256
  
    --- Diff: src/pages/markdown/gpg.md ---
    @@ -0,0 +1,524 @@
    +---
    +title: GPG (Gnu Privacy Guard / Open PGP) Signatures
    +---
    +
    +# Apache NiFi Release Signatures and Code Signing
    +
    +The purpose of this document is to capture and describe the steps involved 
in generating and verifying cryptographic signatures of official releases of 
Apache NiFi, as well as configuring cryptographic signatures of individual code 
commits.  It is written for contributors, committers, and users of Apache NiFi 
(and related applications).  
    +
    +## <a name="table-of-contents">Table of Contents</a>
    +  * [The Objective](#the-objective)
    +  * [Background Material](#background-material)
    +  * [Terms](#terms)
    +  * [Variable Reference Substitutions](#variable-reference-substitutions)
    +  * [Download GPG](#download-gpg)
    +  * [Set up a GPG key](#set-up-a-gpg-key)
    +  * [Sign your GPG key](#sign-your-gpg-key)
    +  * [Publish your key](#publish-your-key)
    +  * [Import another GPG key](#import-another-gpg-key)
    +  * [Verify a key](#verify-a-key)
    +  * [Sign an external key](#sign-an-external-key)
    +  * [Web of trust](#web-of-trust)
    +  * [Set up git with your key](#set-up-git-with-your-key)
    +  * [Signing code](#signing-code)
    +  * [Verifying a signature](#verifying-a-signature)
    +  * [Set up GitHub with your key](#set-up-github-with-your-key)
    +  * [Signing a release artifact](#signing-a-release-artifact)
    +  * [Verifying a release signature](#verifying-a-release-signature)
    +
    +## <a name="the-objective">The Objective</a>
    +
    +Our aim is to instruct users on how to sign their commits, verify other's 
signatures, and do the same for official releases of Apache NiFi. 
    +  
    +## <a name="background-material">Background Material</a>
    +
    +  - These documents are helpful for general environmental setup to perform 
GPG signing and signature verification
    +    - [Apache PGP Info][apache-pgp]
    +    - [Apache Release Signing][apache-release-signing]
    +    - [Git Ready: Signing Releases with GPG][git-sign-tag-instructs]
    +    - [RFC 4880: IETF Standard Spec for OpenPGP][rfc-4880]
    +    - [GitHub Blog: GPG Signature Verification][github-gpg-signing]
    +    - [Git Ready: gpg-sign releases][git-sign-tag-instructs]
    +    - [GitHub Help: Signing Commits Using GPG][github-help-gpg]
    +    - [GitHub Help: Telling Git About Your GPG Key][git-config-gpg]
    +    - [Git Docs: Git Tools Signing Your Work][git-gpg]
    +    - [PGP Web of Trust][web-of-trust]
    +
    +## <a name="terms">Terms</a>
    +
    + * **Asymmetric Cryptography** - a type of cryptography which relies on 
*key pairs* -- a *public* and *private* key which are mathematically-related 
such that no other component key matches. This cryptography offers the 
following actions: **encrypt**, **decrypt**, **sign**, and **verify**
    + * **Cryptographic Signature** - a series of bytes which are the result of 
a signing operation such that only the possessor of a specific private key 
could have generated this signature. A valid signature indicates that the 
possessor of said key performed the operation (non-repudiable)
    +
    +## <a name="variable-reference-substitutions">Variable Reference 
Substitutions</a>
    +
    +Throughout this guide, references must be made to names and values that 
will vary from release to release.  For clarity
    +those variable values have been written like Bash variable references.  
When a term like
    +"```/tmp/src/nifi-${NIFI_VERSION}```" is seen in an instruction or email 
template it should be replaced with
    +"```/tmp/src/nifi-1.7.0```" when working the release of "Apache NiFi 
1.7.0".
    +
    + * Substitutions used in tasks and email templates
    +    <pre>
    +    Reference            Example value       Description
    +    =========            ==============      ===========
    +    ${BRANCH}            master              the development branch on 
which the release is based.
    +    ${NIFI_VERSION}      1.7.0               the version currently in 
development on the release branch.
    +    ${NEXT_VERSION}      1.8.0-SNAPSHOT      the future version for 
development on the release branch.
    +    ${JIRA_TICKET}       NIFI-2112           the JIRA ticket created by 
the release manager for the release tasks.
    +    ${RC}                2                   the Release Candidate index 
start at 1 for the first release candidate.
    +    ${RC_TAG_COMMIT_ID}                      the 40 byte commit ID of the 
RC tag created during the Maven release process.
    +    ${STAGING_REPO_ID}   orgapachenifi-1088  the temporary repository ID 
where staged artifacts have been placed.
    +    ${RM_USERID}         johndoe             the Apache account ID of 
Release Manager.
    +    ${RELEASE_TAG}       rel/nifi-1.7.0      the Git repository tag for 
the source code as released.
    +    ${VOTE_THREAD_URL}   [1.7.0 vote thread][070-rc2-vote]   the URL for 
the Apache Pony Mail archive of the release vote thread.
    +    </pre>
    +
    +    _To be practical but avoid confusion with future release details, 
these example values reflect the previous release
    +NiFi 1.7.0 RC2 release details._
    +
    +NOTE: The next version should be the next minor version if the release is 
based on a major version development branch (e.g master
    +or 0.x). The next version should be the next incremental version if the 
release is based on a minor version development branch (e.g
    +support/nifi-1.1.x or support/nifi-0.7.4). If this is the first 
incremental release (e.g. 1.2.1) for a minor release line the support
    +branch may need to be created.
    +
    +## <a name="download-gpg">Download GPG</a>
    +
    +To get started, you should download the appropriate software for your 
operating system (links and version compatibility as of July 10, 2018). Follow 
the configuration instructions that come with your tool of choice:
    +
    +### Mac OS X / macOS
    +
    +* [GPG Suite][gpg-suite] -- macOS 10.9+ -- a GUI-based suite of GPG tools 
including command-line tool, Mail client integration, etc. 
    +* gpg via brew -- distribution of [GnuPG][gnupg] command-line tool via 
[brew][brew]. Install via `brew update && brew install gpg2`. You may also need 
`gpg-agent` depending on your system. 
    +
    +### Linux
    +* Redhat/CentOS -- `yum install gnupg`
    +* Debian/Ubuntu -- `apt-get install gnupg`
    +
    +### Windows
    +* [Gpg4win][gpg4win] -- Windows 7+ -- a GUI-based suite of GPG tools
    +
    +## <a name="setting-up-your-key">Setting up your key</a>
    +
    +*All following commands will use the command-line syntax to perform these 
operations unless otherwise noted. For instructions on performing these 
operations in a GUI-environment, refer to the resources listed above.*
    +
    +To begin, run the `gpg` command with the `--gen-key` or 
`--full-generate-key` flag. You will be prompted for various information, and 
can accept the defaults other than **name** and **email**. The tool will prompt 
for a passphrase, and the key pair will be identified by the **user id** 
(**name** + **email**) and a **key fingerprint**. 
    +
    +Example:
    +
    +```
    +# Generate the key
    +🔓 0s @ 15:06:19 $ gpg --gen-key
    +Note: Use "gpg --full-generate-key" for a full featured key generation 
dialog.
    +
    +GnuPG needs to construct a user ID to identify your key.
    +
    +Real name: NiFi Test User
    +Email address: t...@nifi.apache.org
    +You selected this USER-ID:
    +    "NiFi Test User <t...@nifi.apache.org>"
    +
    +Change (N)ame, (E)mail, or (O)kay/(Q)uit? o
    +We need to generate a lot of random bytes. It is a good idea to perform
    +some other action (type on the keyboard, move the mouse, utilize the
    +disks) during the prime generation; this gives the random number
    +generator a better chance to gain enough entropy.
    +We need to generate a lot of random bytes. It is a good idea to perform
    +some other action (type on the keyboard, move the mouse, utilize the
    +disks) during the prime generation; this gives the random number
    +generator a better chance to gain enough entropy.
    +gpg: key 71456940555DB64A marked as ultimately trusted
    +gpg: revocation certificate stored as 
'/Users/alopresto/.gnupg/openpgp-revocs.d/718FAE8D4F81CDED06EA652271456940555DB64A.rev'
    +public and secret key created and signed.
    +
    +pub   rsa2048 2018-07-10 [SC] [expires: 2020-07-09]
    +      718FAE8D4F81CDED06EA652271456940555DB64A
    +uid                      NiFi Test User <t...@nifi.apache.org>
    +sub   rsa2048 2018-07-10 [E] [expires: 2020-07-09]
    +
    +# List all keys in the key ring
    +🔓 38s @ 15:07:11 $ gpg -k
    +gpg: checking the trustdb
    +gpg: marginals needed: 3  completes needed: 1  trust model: pgp
    +gpg: depth: 0  valid:   6  signed:   4  trust: 0-, 0q, 0n, 0m, 0f, 6u
    +gpg: depth: 1  valid:   4  signed:  10  trust: 3-, 0q, 0n, 0m, 1f, 0u
    +gpg: depth: 2  valid:  10  signed:   1  trust: 8-, 0q, 0n, 0m, 2f, 0u
    +gpg: next trustdb check due at 2018-08-19
    +/Users/alopresto/.gnupg/pubring.gpg
    +-----------------------------------
    +pub   dsa2048 2010-08-19 [SC] [expires: 2018-08-19]
    +      85E38F69046B44C1EC9FB07B76D78F0500D026C4
    +uid           [ultimate] GPGTools Team <t...@gpgtools.org>
    +uid           [ultimate] GPGMail Project Team (Official OpenPGP Key) 
<gpgmail-de...@lists.gpgmail.org>
    +uid           [ultimate] GPGTools Project Team (Official OpenPGP Key) 
<gpgtools-...@lists.gpgtools.org>
    +uid           [ultimate] [jpeg image of size 5871]
    +sub   elg2048 2010-08-19 [E] [expires: 2018-08-19]
    +sub   rsa4096 2014-04-08 [S] [expires: 2024-01-02]
    +
    +...
    +
    +pub   rsa2048 2018-07-10 [SC] [expires: 2020-07-09]
    +      718FAE8D4F81CDED06EA652271456940555DB64A
    +uid           [ultimate] NiFi Test User <t...@nifi.apache.org>
    +sub   rsa2048 2018-07-10 [E] [expires: 2020-07-09]
    +
    +# List a specific key with (formatted) fingerprint
    +🔓 0s @ 15:11:37 $ gpg --fingerprint 0x555DB64A
    +pub   rsa2048 2018-07-10 [SC] [expires: 2020-07-09]
    +      718F AE8D 4F81 CDED 06EA  6522 7145 6940 555D B64A
    +uid           [ultimate] NiFi Test User <t...@nifi.apache.org>
    +sub   rsa2048 2018-07-10 [E] [expires: 2020-07-09]
    +
    +```
    +
    +You now have a key generated for your identity. Some Apache users will 
include "(CODE SIGNING KEY)" after their name to separate this key from other 
keys they use. This is optional. By default, keys use 2048 bit length. You can 
increase this to 4096 bits by using the `--full-generate-key` or 
`--default-new-key-algo rsa4096` flags when generating. 
    +
    +The **key fingerprint** can be referred to by the last 8 hex digits 
(**short ID**) or last 16 hex digits (**long ID**), so for the remainder of 
this guide, our example key will have the **long ID** `7145 6940 555D B64A` 
(spaces optional) and **short ID** `555D B64A`, which we can reference in 
commands as `0x555DB64A`.  
    +
    +### Trust vs. Validity
    +
    +It is important to understand the difference between two closely related 
concepts -- **ownertrust** and **validity**. Validity is how much *you* trust a 
*key*; that is *how well you have verified the key represents who it claims*. 
Ownertrust is how much transitive trust you give to that entity; how well do 
you believe *Person X* verifies keys that *they* sign? 
    +
    +There are four levels of **ownertrust** and five levels of **validity**. 
    +
    +**Trust**
    +1. `unknown` -- you do not know how well the owner verifies keys
    +1. `none` -- you do not trust the owner to verify keys
    +1. `marginal` -- you trust the owner to verify keys
    +1. `full` -- you trust the owner to verify keys as well or better than you 
do
    +
    +**Validity** 
    +1. `unknown` -- you do not know whether to trust this key
    +1. `never`/`none` -- you do not trust this key
    +1. `marginal` -- you have lightly verified that this key belongs to the 
owner
    +1. `full` -- you have verified that this key belongs to the owner
    +1. `ultimate` -- you have no doubt that this key belongs to the owner 
(likely because you generated it)
    +
    +Your generated key is granted `ultimate` ownertrust by default, because 
you just generated it. See [Web of Trust][web-of-trust] and [GNU Privacy 
Handbook][gnu-privacy-handbook] for more information and good diagrams. 
    +
    +## <a name="publish-your-key">Publish your key</a>
    +
    +To allow other users to encrypt data with your key, verify signatures made 
by your key, etc., you should publish your **PUBLIC** key. *Never share your 
**PRIVATE** (sometimes referred to as **SECRET**) key*. You can publish your 
public key to a *key server*, post it on your website, etc. The tools provide 
multiple ways to perform this task via `--export` and `--send-keys`. Refer to 
the references above for more information on this process. 
    +
    +```
    +# Send the public key to a remote key server
    +🔓 0s @ 15:20:53 $ gpg --send-keys 0x555DB64A
    +gpg: sending key 71456940555DB64A to hkps://hkps.pool.sks-keyservers.net
    +```
    +
    +## <a name="import-another-gpg-key">Import another GPG key</a>
    +
    +For the key ecosystem to function, you'll want to import other public 
keys. These can come from key servers, public keys encoded as ASCII sent 
directly to you, or `KEYS` files posted on servers (such as 
[https://dist.apache.org/repos/dist/release/nifi/KEYS](https://dist.apache.org/repos/dist/release/nifi/KEYS)).
 
    +
    +```
    +# Download the KEYS file
    +🔓 4s @ 15:21:35 $ wget https://archive.apache.org/dist/nifi/KEYS
    +--2018-07-10 15:26:24--  https://archive.apache.org/dist/nifi/KEYS
    +...
    +
    +# Import the KEYS file keys
    +🔓 1s @ 15:26:27 $ gpg -v --import KEYS
    +gpg: armor header: Version: GnuPG v1
    +gpg: armor header: Version: GnuPG v2.0.22 (GNU/Linux)
    +gpg: pub  rsa4096/9C4F7E9D98B1CC53 2010-10-23  Benson Margulies 
<bimargul...@apache.org>
    +gpg: using pgp trust model
    +gpg: key 9C4F7E9D98B1CC53: public key "Benson Margulies 
<bimargul...@apache.org>" imported
    +...
    +gpg: Total number processed: 17
    +gpg:               imported: 16
    +gpg:              unchanged: 1
    +gpg: 23 keys processed (26 validity counts cleared)
    +gpg: public key of ultimately trusted key 71456940555DB64A not found
    +gpg: public key of ultimately trusted key D735933E0D99CDD3 not found
    +gpg: public key of ultimately trusted key AFF2B36823B944E9 not found
    +gpg: public key of ultimately trusted key 6EC293152D90B61D not found
    +gpg: public key of ultimately trusted key 125A4E6851BF2B79 not found
    +gpg: public key of ultimately trusted key 76D78F0500D026C4 not found
    +gpg: marginals needed: 3  completes needed: 1  trust model: pgp
    +gpg: depth: 0  valid:   6  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 6u
    +```
    +
    +## <a name="verify-a-key">Verify a key</a>
    +
    +When you first import an external key, the key is untrusted (**validity** 
level `never`). To mark a key as trusted, you will perform *key verification*, 
either *directly* or via *web of trust*. 
    +
    +### Direct Verification
    +
    +For entities you can contact directly via a trusted mechanism (voice call, 
in-person, etc.), you can exchange the **key fingerprint** personally and 
verify that the fingerprint they present matches what you have imported. Once 
verified, you can sign the key. Here I am imitating another user, using a 
previously-generated key (`0x2F7DEF69`) to sign the "imported" key that was 
generated above. 
    +
    +```
    +# Signing an imported key with your own key
    +🔓 132s @ 15:36:12 $ gpg -v --sign-key 0x555DB64A
    +
    +gpg: using pgp trust model
    +sec  rsa2048/71456940555DB64A
    +     created: 2018-07-10  expires: 2020-07-09  usage: SC
    +     trust: ultimate      validity: unknown
    +ssb  rsa2048/4FC72361977CEC0A
    +     created: 2018-07-10  expires: 2020-07-09  usage: E
    +[ unknown] (1). NiFi Test User <t...@nifi.apache.org>
    +
    +gpg: using "70ECB3E598A65A3FD3C4BACE3C6EF65B2F7DEF69" as default secret 
key for signing
    +
    +sec  rsa2048/71456940555DB64A
    +     created: 2018-07-10  expires: 2020-07-09  usage: SC
    +     trust: ultimate      validity: unknown
    + Primary key fingerprint: 718F AE8D 4F81 CDED 06EA  6522 7145 6940 555D 
B64A
    +
    +     NiFi Test User <t...@nifi.apache.org>
    +
    +This key is due to expire on 2020-07-09.
    +Are you sure that you want to sign this key with your
    +key "Andy LoPresto <alopre...@apache.org>" (3C6EF65B2F7DEF69)
    +
    +Really sign? (y/N) y
    +gpg: RSA/SHA512 signature from: "3C6EF65B2F7DEF69 Andy LoPresto 
<alopre...@apache.org>"
    +```
    +
    +### Web of Trust
    +
    +If it is infeasible to directly contact the key bearer directly, you can 
delegate that trust to a third-party who you already trust. For example, if you 
cannot directly contact Joe Witt, but you already trust Andy LoPresto (i.e. you 
have verified Andy's key and believe Andy would verify keys he trusts), you can 
sign Joe's key if Andy has already done so. You can choose to employ a lower 
level of validity (`marginal` vs. `full`) in that case depending on your 
transitive **ownertrust** in Andy's verification. See [Web of 
Trust][web-of-trust] and [GNU Privacy Handbook][gnu-privacy-handbook] for more 
information and good diagrams. 
    --- End diff --
    
    Repeated "directly". 


---

Reply via email to