Title: Signing Releases
Notice: Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
.
http://www.apache.org/licenses/LICENSE-2.0
.
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
# Abstract # {#abstract}
This document gives a basic primer on the wide subject of release signing. See under [Further reading](#reading) for links to
authoritative sources of deeper information.
Release managers are the target audience.
This document is informative and does not constitute policy.
# Important # {#note}
All new **RSA** keys generated should be at least **4096** bits. **Do not**
generate new **DSA** keys.
Recent research has revealed weaknesses in SHA-1, and thus in the DSA and
1024 bit RSA OpenPGP keys which must use this algorithm. Though no
realistic attacks have been made public, experience with similar weaknesses
in MD5 suggests that further advances may well lead to practical attacks
within the next few years. This accords with current NIST guidance on DSA.
The future impact of this weakness on Apache can be mitigated by action
now. What needs to be done is a little involved. So, complete instructions
have been prepared. Please read and follow them.
- Committers without a code signing key should read this document and
follow these [instructions](openpgp.html#generate-key).
- Committers with a DSA key or an RSA key of length less than 2048 bits
should generate a new key for signing releases. The original key does not
need to be revoked yet. Follow this [guide](key-transition.html).
- Committers with RSA keys of length 2048 or more do not need to generate a
new key yet. They should reconfigure their client to avoid the weakness by
following these [instructions](openpgp.html#sha1) and wait for the next
major OpenPGP revision.
How to find the length of your key is described [here](#key-length-how-to).
# Contents #
[TOC]
# Help Wanted! # {#help}
Help to finish this document by [contributing documentation
patches](infra-site.html) ! If the information you seek isn't in this
document, then please submit a patch once the infrastructure folks have
answered your question.
# Further Reading # {#reading}
- The [Guide](openpgp.html#gnupg) to using GnuPG at Apache
- The [Apache Key Transition Guide](key-transition.html)
- RFC [1321](http://www.ietf.org/rfc/rfc1321.txt) MD5 Message-Digest
Algorithm
- RFC [2440](http://www.ietf.org/rfc/rfc2440.txt) OpenPGP Message Format
- RFC [3174](http://www.ietf.org/rfc/rfc3174.txt) Secure Hash Algorithm 1
(SHA1)
- The GNU Privacy Guard project
[documentation](http://www.gnupg.org/documentation/)
- An introduction to [PGP public key
cryptography](http://www.pgpi.org/doc/pgpintro/)
- [Applied Cryptography](http://www.schneier.com/book-applied.html) by
Bruce Schneier
- Windows centric [PGP FAQ](http://www.mccune.cc/PGPpage2.htm) by Tom
McCune
- Henk Penning's Apache [home page](http://people.apache.org/~henkp/)
**Note** this is not normative
# Basic facts # {#basic-facts}
Every artifact distributed by the Apache Software Foundation *must* be
accompanied by one file containing an [OpenPGP
compatible ASCII armored detached signature](#openpgp-ascii-detach-sig) and
another file containing an [MD5 checksum](#md5). The names of these files
*must* be formed by adding to the name of the artifact the following
suffixes:
- the signature by suffixing `.asc`
- the checksum by suffixing `.md5`
An [SHA](#sha-checksum) checksum *should* also be created and *must* be
suffixed `.sha`.
Release managers *must not* store private keys used to sign Apache releases
on ASF hardware.
# The KEYS File # {#keys-policy}
The KEYS file is a plain text file containing the public key signatures of
the release managers (and optionally other committers) for the project. For
example, [Apache Ant KEYS](http://www.apache.org/dist/ant/KEYS). It is
traditional to include the following header (which explains its usage):
**Note:** this system will be replaced by a better process in the near
future. In preparation, please ensure that public keys are connected as
strongly as possible to the Apache [web of trust](#web-of-trust) and are
available from the major [public key servers](#keyserver).
[Applied cryptography](#pke) is a subject that has considerable depth.
Luckily, it's possible to get started signing releases without being an
expert. Just remember that (from time to time) you will encounter
situations that will require research and learning. Hopefully the
[FAQ](#faq) will be a reasonable first port of call.
You will need an [application](#openpgp-applications) to manage keys and
create signatures. [GNU Privacy Guard](http://www.gnupg.org/) is
recommended and the Apache documentation generally assumes that's what
you're using. (Documentation patches for other tools welcomed.) Read the
[Apache usage guide](openpgp.html#gnupg) and keep the
[manual](http://www.gnupg.org/gph/en/manual.html) handy. Note that GnuPG
can handle MD5 and SHA checksums as well as PGP signatures. It is your
one-stop shop, cross-platform tool for release signing and verification.
It can be hard for newbies to be confident that they have executed
operations correctly. Consider doing some [practice](#safe-practice) first.
# Why We Sign Releases # {#motivation}
A signature allows anyone to verify that a file is identical to the one
created by the Apache release manager. Using a signature:
- users can make sure that what they received has not been modified in any
way, either accidentally via a faulty transmission channel, or
intentionally (with or without malicious intent)
- the Apache infrastructure team can verify the identity of a file
[OpenPGP](#openpgp) [signatures](#verifying-signature) confer the usual
advantages of digital signatures: [authentication, integrity and
non-repudiation](http://www.pgpi.org/doc/pgpintro/#p12). [MD5](#md5) and
[SHA](#sha-checksum) checksums only provide the integrity part as they are
not encrypted.
# Security Basics # {#security-basics}
- [Protect](#private-key-protection) your [private key](#public-private)
- Choose a [good passphrase](#passphrase)
- Opt for a reasonably [long key length](#key-length)
# Key Basics # {#key-basics}
To sign releases, you need to [generate](#generate) a new master key-pair
for code signing. Follow these [instructions](openpgp.html#generate-key).
# Signing Basics # {#signing-basics}
Signatures should be [ASCII armored and
detached](#openpgp-ascii-detach-sig).
Your [public key](#public-private) should be [exported](#export) and the
result appended to the appropriate
This file contains the PGP keys of various developers.
Users: pgp < KEYS
gpg --import KEYS
Developers:
pgp -kxa <your name> and append it to this file.
(pgpk -ll <your name> && pgpk -xa <your name>)
>> this file.
(gpg --list-sigs <your name>
&& gpg --armor --export <your name>) >>
this file.
[KEYS](#keys-policy)
file(s).
That's all you need to know to sign a release.
# How Do I Sign A Release? # {#sign-release}
Create a [OpenPGP compatible ASCII armored detached
signature](#openpgp-ascii-detach-sig) for the released artifact. Upload the
signature with the released artifact.
See [here](#basics) for a basic overview.
# What Is an OpenPGP Compatible ASCII Armored Detached Signature? # {#openpgp-ascii-detach-sig}
It is an [OpenPGP](#openpgp) compatible [ASCII armored](#ascii) [detached
signature](#detach-sig).
To create one using [GNU Privacy Guard](http://www.gnupg.org) for file
`foo.tar.gz` type:
# What Is OpenPGP? # {#openpgp}
[OpenPGP](http://www.openpgp.org/) is an
[RFC](http://www.ietf.org/rfc/rfc2440.txt) describing a system for
interoperable [public key cryptography](#pke). Various implementations
exist. Apache recommends *GNU Privacy Guard*.
[GNU Privacy Guard](http://www.gnupg.org/) (GnuPG) is an open source
OpenPGP compatible implementation. It comes with [good
documentation](http://www.gnupg.org/(en)/documentation/guides.html)
describing not just GnuPG but also giving a good general introduction to
public key cryptography. A guide to using GnuPG at Apache is
[available](openpgp.html#gnupg ).
# What Is Public Key Cryptography? # {#pke}
Public key cryptography is asymmetric. One key can be used to encrypt a
message which only the other key can decrypt. Knowledge of the first key
can be made public without compromising the security of the second key. One
key is therefore called the public key and one the private key.
When using public key cryptography, the public key can be freely
distributed but the private key must be secret. It is vital that private
key files are [protected](#private-key-protection). Private keys are
typically stored in files protected by symmetric encryption. Strong
[passphrases](#passphrase) must be chosen to protect them.
# What Is An Detached Signature? # {#detach-sig}
A digital signature is created from an original document using a [private
key](#pke). Possession of the corresponding public key allows verification
that a given file is identical to the original document. An attached
signature is attached to the document whereas a detached signature is
contained in a separate file.
# What Is ASCII Armoring? # {#ascii}
An encoding format that converts a binary file into a string of ASCII
characters. This format is more human readable and more portable.
# What Is An MD5 Checksum? # {#md5}
MD5 is a [well known](http://www.faqs.org/rfcs/rfc1321.html) [message
digest algorithm](#message-digest).
Many tools are available to calculate these sums. For example,
[OpenSSL](http://www.openssl.org/) can be used:
$ gpg --armor --output foo.tar.gz.asc --detach-sig foo.tar.gz
Platform specific applications are also common. For example `md5sum` on
linux:
$ openssl md5 < file
With GnuPG:
$ md5sum file
Please run the command in the same directory as the file so the output only contains
the file name with no directory prefixes.
Please note that the security of MD5 is now [questionable](#md5-security)
and is only useful as part of a defense in depth.
# What is a SHA checksum? # {#sha-checksum}
Like [MD5](#md5) , [SHA](http://www.ietf.org/rfc/rfc3174.txt) is another
[message digest](#message-digest) algorithm.
Using GnuPG, you can create a SHA1 signature as follows:
$ gpg --print-md MD5 [fileName] > [fileName].md5
Please note that further use of `SHA-1` should be [avoided](#sha1).
`SHA256` and `SHA512` use the same `SHA` algorithm family with longer hash
lengths (256 and 512 bits respectively). These longer variations are less
vulnerable to the weaknesses found in the algorithm family than `SHA1`.
SHA512 is [recommended](#sha1).
To create a `SHA512` checksum use:
$ gpg --print-md SHA1 [fileName] > [fileName].sha
Please run the command in the same directory as the file so the output only contains
the file name with no directory prefixes.
Other members of the `SHA` family (with different hash lengths) are rarely
used.
This family of algorithms will be retired once [SHA3](#sha3) is available.
# What Is A Message Digest Algorithm? # {#message-digest}
A message digest algorithm takes a document and produces a much smaller
hash of that document. A good algorithm will produce different digests for
very similar documents. A good algorithm makes it [infeasible](#infeasible)
to create a message matching a given hash.
A trusted digest for a document can be used to verify the contents of an
untrusted file. The small size of the digest allows it to be delivered over
a secure but expensive channel whilst the untrusted file is delivered over
an insecure but inexpensive one. This is useful when distributing releases.
# What Is A Web Of Trust? # {#web-of-trust}
It is difficult to personally verify the identity of all useful [public
keys](#pke). However, having verified the identity of only a small number
of public keys it is possible to deduce the identity of public keys trusted
by the owners of these keys. This process can be repeated. This extended
graph of trusted identities is termed a [web of
trust](http://en.wikipedia.org/wiki/Web_of_trust).
Webs of trust can be used to solve the problem of verifying the identity of
public keys.
**Note:** in order to take full advantage of a web of trust, it is
important to actively build your web of trust into the major public webs of
trust. Conferences are an ideal opportunity but you must come
[prepared](#link-into-wot).
For more information read [Henk Penning's Apache home
page](http://people.apache.org/~henkp/) and the [GNU Privacy Guard User
Guide](http://www.gnupg.org/(en)/documentation/guides.html).
# How Do I Link Into A Public Web of Trust? # {#link-into-wot}
By an existing member of that [web of trust](#web-of-trust) signing your
public key to verify your identity. See Henk Penning's [Key Signing
HOWTO](http://people.apache.org/~henkp/sig/pgp-key-signing.txt)
A short guide is [available](openpgp.html#wot).
# What Is A Key Signing Party? # {#key-signing-party}
A key signing party is a meeting organised to allow the exchange of public
keys and so extension of the [web of trust](#web-of-trust).
See the [Keysigning Party
HOWTO](http://www.cryptnet.net/fdp/crypto/keysigning_party/en/keysigning_party.html)
and Henk Penning's [Key Signing
HOWTO](http://people.apache.org/~henkp/sig/pgp-key-signing.txt)
# How Can I Link My Key Into The Apache Web of Trust? # {#apache-wot}
By meeting other Apache committers face-to-face and [exchanging public
keys](#link-into-wot). There are several ways to achieve this:
- [Key signing parties](#key-signing-party) are organised at each
[ApacheCon](http://www.apachecon.com).
- If you are not able to attend (or the conference is a long way off) then
consider organising a face-to-face meeting of [local
committers](http://people.apache.org/map.html).
- Subscribe to the `party` list and when you visit a new city, see if
committers want to meet up.
See Henk Penning's [Key Signing
HOWTO](http://people.apache.org/~henkp/sig/pgp-key-signing.txt)
# What Does Verifying A Signature Mean? # {#verifying-signature}
[Public key cryptography](#pke) can be used to test whether a particular
file is identical (in content) to an original by verifying a
[signature](#detach-sig). The signature file is a [digest](#message-digest)
of the original file signed by a public key which attests to the digest's
authenticity.
For example, when using [GNU Privacy Guard](http://www.gnupg.org/) you
verify the signature `foo-1.0.tar.gz.asc` for release `foo-1.0.tar.gz`
using the following command:
$ gpg --print-md SHA512 [fileName] > [fileName].sha
Trust is required in the identity of the public key that made the signature
and that the signature is for the original in question (and not some other
file). When verifying a release from an untrusted source (for example, over
P2P file sharing or from a mirror) it is therefore important to download
the signature from a trusted source. Signatures for all Apache releases are
available directly from `www.apache.org` and should be downloaded from
there.
# How Can I Check The Integrity Of A Release? # {#check-integrity}
[MD5](#md5) and [SHA](#sha-checksum) checksums provide a simple, means of
verifying the integrity of a download. You can simply create a checksum (in
the same way as the release manager) after download, and compare the result
to the checksum downloaded from the main Apache site. Obviously, this
process does not provide for [authentication and
non-repudiation](http://www.pgpi.org/doc/pgpintro/#p12) as anybody can
create the same checksum.
The integrity of a release can also be checked by [verifying the
signature](#verifying-signature). More knowledge is required to correctly
interpret the result but it does provide authentication and
non-repudiation. If you are connected to the Apache [web of
trust](#web-of-trust) then this also offers superior security.
# What Does 'Public Key Not Found' Mean (When Verifying A Signature)? # {#public-key-not-found}
Before a signature can be verified, the public key is required.
For example, when using [GNU Privacy Guard](http://www.gnupg.org/) if you
have never imported the appropriate public key a message similar to the
following will be displayed:
$ gpg --verify foo-1.0.tar.gz.asc foo-1.0.tar.gz
Unknown keys can often be downloaded from [public key servers](#keyserver).
However, these should only be [trusted](#trust) through a [web of
trust](#web-of-trust).
Apache projects normally keep the developers' public keys in a file called
`KEYS`. You may be able to find that file on the project's website, or in
their code repository. Use
$ gpg --verify foo-1.0.tar.gz.asc foo-1.0.tar.gz
gpg: Signature made Mon Sep 26 22:26:18 2005 BST using RSA key ID 00000000
gpg: Can't check signature: public key not found
to import the public keys.
# What is a Trusted Key? # {#trust}
[OpenPGP](#openpgp) uses a [web of trust](#web-of-trust). The owner of a
public key who trusts the identity of a second key may mark this key as
trusted by signing it. This has several major effects:
- In future, no [untrusted key warning will be
issued](#valid-untrusted-vs-invalid-trusted) when a valid signature for
this key is verified.
- Keys trusted by the owner of the key may also become trusted. In other
words, a key whose identity has been confirmed by the owner of a key whose
identity you trust may be automatically trusted. This behavior is typically
configurable.
- The next time you export your key, those who trust your key may start to
trust the identity of the trusted key.
The transitive nature of the web of trust places a responsibility on the
owner to verify the identity of the owner of those keys marked as trusted.
For more information read [Henk Penning's Apache home
page](http://people.apache.org/~henkp/) and the [GNU Privacy Guard User
Guide](http://www.gnupg.org/(en)/documentation/guides.html).
# What Is The Difference Between A Valid Signature from an Untrusted Key And An Invalid Signature from an Untrusted Key? # {#valid-untrusted-vs-invalid-trusted}
Trustfulness and validity are different concepts. You may elect to trust
the identity of a key to various degrees (or not at all). For a particular
key, a particular signature for a particular file may be valid (in other
words, created by the private key from an identical file) or invalid
(either corrupt or created from a different file).
You should not trust a file with an invalid signature. You can trust a file
with a valid signature as much as you trust the identity of key that was
used to verify the signature.
For example, when using [GNU Privacy Guard](http://www.gnupg.org/) a
message similar to the following indicates that the signature is invalid:
$ gpg --import KEYS
whereas a message similar to the following indicates that the signature is
valid but for an untrusted key:
$ gpg --verify foo-1.0.tar.gz.asc foo-1.0.tar.gz
gpg: Signature made Mon Sep 26 22:26:18 2005 BST using RSA key ID 00000000
gpg: BAD signature from "someone@example.org"
The [fingerprint](#fingerprint) may be used to ascertain the appropriate
level of trust to assign to the key.
# What Is A Public Key Fingerprint? # {#fingerprint}
Public keys are long and even when [ASCII armored](#ascii) are not very
easy for humans to understand or compare. A fingerprint is a shorter
[digest](#message-digest) of the key formatted in a way that makes it
easier for humans to read and compare.
# Why Infeasible And Not Impossible? # {#infeasible}
Responsible cryptography talks about infeasible cracks (rather than
impossible ones) since this is more accurate. All current practical methods
can be subjected to brute force attacks and so can be cracked. So, a good
question is whether attacks are feasible given the current state of the
art.
# Where Should I Create The Signatures? # {#where}
Creating signatures requires the private key. Limited copies should be kept
of the private key and all must be kept confidential. Though the file used
to store the private key is typically protected by encryption, it is
vulnerable to dictionary attacks on the [passphrase](#passphrase). This
file must therefore be kept secret. So, signatures should be created on the
machine used to store the private key.
It is important that the private key is stored on secure hardware with
limited read permissions and is protected by a good
[passphrase](#passphrase). Consider using removable media or an [isolated
installation](#isolated-installation).
A master private key used to sign Apache artifacts (or to secure
communications with the ASF) is particularly valuable. If you want or need
to be able to create signatures for other purposes (for example, signing
email messages) in other (less secure) locations it is recommended that you
create [multiple sub keys](#email-subkey) and use sub keys for signing in
less secure locations.
The private key *must not* be store on any ASF machine. So, signatures
*must not* be created on ASF machines.
# What Is 'Insecure Memory' And Should I Be Worried? # {#insecure-memory}
When you use [GNU Privacy Guard](http://www.gnupg.org) you may see a
warning similar to:
$ gpg --verify foo-1.0.tar.gz.asc foo-1.0.tar.gz
gpg: Signature made Mon Sep 26 22:05:28 2005 BST using RSA key ID 00000000
gpg: Good signature from "someone@example.org"
gpg: aka "someone@anotherdomain.org"
gpg: checking the trustdb
gpg: checking at depth 0 signed=1 ot(-/q/n/m/f/u)=0/0/0/0/0/1
gpg: checking at depth 1 signed=0 ot(-/q/n/m/f/u)=1/0/0/0/0/0
gpg: WARNING: This key is not certified with a trusted signature!
gpg: There is no indication that the signature belongs to the
owner.
Primary key fingerprint: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
If you are using GnuPG on Apache hardware, please read [this](#where).
Sensitive operations using a private key *must not* be executed on ASF
hardware.
If you encounter this issue elsewhere then it indicates that GnuPG cannot
lock memory pages which means they may be swapped out to disc. It would
then be feasible for an attacker who had gained access to the machine to
read the private key from the swap file. For more details, read the
[FAQ](http://www.gnupg.org/faq.html).
# What is a Passphrase? # {#passphrase}
The term *passphrase* is often used in cryptography for what might be
better known as a password in other contexts. For example, an
[OpenPGP](#openpgp) private key is typically stored to disc in an file
encrypted by a symmetric cypher keyed by a passphrase. This passphrase is
one of the weakest elements in the system: should anyone else gain access
to the file then a dictionary attack will be feasible on a weak passphrase.
So, choosing a strong passphrase is very important.
Passphrases are (unlike passwords) typically unlimited in length. Long
passphrases are recommended. This allows sequences of (at least seven)
unrelated words to be used as well as more conventional mixtures of symbols
and alphanumerics.
Note that even a good passphrase will offer only limited protection. Given
the encrypted file and enough time, a determined cracker will be able to
break any passphrase. A good passphrase will buy important time in the
event of a compromise but is no substitute for keeping the private key
[safe and secure](#safe-and-secure) in the first place.
# What Is A Revocation Certificate? # {#revocation-cert}
[OpenPGP](#openpgp) defines a special type of signed message called a
*revocation certificate*. This message indicates that the signer believes
that the key is no longer trustworthy. Typically, the revocation
certificate will be signed by the key to be revoked (though the key may
specify that other keys should be trusted for revocation). The type of
revocation and the comment included may be used to judge how much trust to
place in a good signature by a revoked key.
A revocation certificate should be generated for each public key used.
These should be stored safely, securely and separately from the public key.
Each revocation certificates has a type specifying a general (machine
readable) reason for the revocation:
- No reason specified
- Key has been compromised
- Key is superseded
- Key is no longer used
It is recommended that certificates are created to cover the first two
cases. Note that if a key is lost or can no longer be accessed (due to
media failure, say) it is best to assume that the key has been potentially
compromised. It is recommended that revocation certificates are printed and
stored safely to guard against media failure.
An [ASCII armored](#ascii) revocation certificate for key `bob` can be
generated and saved to `revoke.asc` using [GNU Privacy
Guard](http://www.gnupg.org) as follows:
gpg: WARNING: using insecure memory!
gpg: please see http://www.gnupg.org/faq.html for more information
The certificate produced should be [securely
stored](#revocation-certificate-storage).
If you are preparing a revocation certificate for future use, it is
recommended that you test it. See [safe practice](#safe-practice).
# How Do I Revoke A Key? # {#revoke-key}
To revoke a key (given a certificate) using [GNU Privacy
Guard](http://www.gnupg.org) import the [revocation
certificate](#revocation-cert) :
$ gpg --output revoke.asc --armor --gen-revoke bob
# Where Should A Revocation Certificate Be Stored? # {#revocation-certificate-storage}
The revocation certificate should be stored securely and separately from
the key it revokes. Burning onto CDROM or printing out onto hard copy are
good solutions.
# How Do I Distribute A Revocation Certificate? # {#revoke-cert}
In the event of a compromise, a [revocation certificate](#revocation-cert)
needs to be distributed to those using the key. This process needs to be a
mirror of the process by which the original key was distributed.
- The Apache infrastructure team should be informed by a post containing
the revocation certificate
- The KEYS files containing the original key should be updated with the
revocation certificate
- The revocation certificate should be uploaded to the major keyserver
networks
- An announcement should be posted to the appropriate lists with the
revocation certificate attached
# What Is The Difference Between Deleting And Revoking A Key? # {#delete-vs-revoke}
When a key is deleted from a keyring, it is simply removed. It can be added
again later.
When a key is revoked, the key is marked in the key ring. Whenever a
message signed by this key is verified in the future, the user will be
warned that the key has been revoked.
For example, when verifying a revoked key, [GNU Privacy
Guard](http://www.gnupg.org) issues the following comment:
$ gpg --import revoke.asc
gpg: key 4A03679A: "Some User <someuser@example.org>" revocation
certificate imported
gpg: Total number processed: 1
gpg: new key revocations: 1
# Can I Mark A Key As Locally Trusted? # {#local-sig}
On occasion, a key may be trusted by the user (who understands the risks)
but is not considered trustworthy enough to be exported to the [web of
trust](#web-of-trust).
[OpenPGP](#openpgp) allows keys to be signed as local only. These trust
relationships will not be exported to the public web of trust but will be
treated as trusted when the key ring is used locally.
For example, with [GNU Privacy Guard](http://www.gnupg.org) use:
$ gpg --verify message.asc.message
gpg: Signature made Sat Apr 8 09:28:31 2006 BST using DSA key ID 4A03679A
gpg: Good signature from "Some User <someuser@example.org>"
gpg: checking the trustdb
gpg: checking at depth 0 signed=0 ot(-/q/n/m/f/u)=0/0/0/0/0/1
gpg: WARNING: This key has been revoked by its owner!
gpg: This could mean that the signature is forgery.
gpg: reason for revocation: Key has been compromised
gpg: revocation comment:
gpg: WARNING: This key is not certified with a trusted signature!
gpg: There is no indication that the signature belongs to the
owner.
Primary key fingerprint: 82D1 169B E6F1 9D14 DA76 A5DD 968E 66E4 4A03 679A
# How Can I Safely Practice Using OpenPGP? # {#safe-practice}
Use separate environments each with a different practice keyring.
For example, using [GNU Privacy Guard](http://www.gnupg.org) :
- *(First time only)* Create a directory to contain the keyring
- Open the shell to be configured to use this keyring
- Change to the directory
- *(First time only)* `$ mkdir -m 700.gnupg`
- Setup environment `$ export GNUPGHOME=.gnupg`
# What Is The Difference Between A Public And A Private Key? # {#public-private}
A public key is used for verifying signatures and encrypting messages, a
private key for generating signatures and decrypting messages. Public keys
can be freely distributed safely whereas private keys must be kept
[protected](#safe-and-secure). More details [here](#pke).
# How Should My Code Signing Private Key Be Protected? # {#private-key-protection}
Anyone who possesses a copy of a [private key](#public-private) used to
[sign](#sign-release) releases can create doctored releases with valid
signatures. If this person intends harm then the consequences could be
serious indeed.
It is therefore very important that this private key is kept secret.
- Only sign releases on a [secure machine](#secure-machine).
- Keep your [signing application](#openpgp-applications) fully patched.
- Keep the key file [safe and secret](#safe-and-secure).
- Choose a good [passphrase](#passphrase).
# How Secure Does The Machine Used To Sign Releases Need To Be? # {#secure-machine}
If the code signing machine is
[owned](http://www.catb.org/~esr/jargon/html/O/owned.html) then it is only
a matter of time before the key is compromised.
At a minimum, the machine should well maintained (kept up to date with
security patches, use appropriate anti-virus and firewall software). The
ideal is an isolated, well maintained installation used only for creating
releases. This can be achieved with a little effort by creating an
[isolated installation](#isolated-installation) on a separate hard disc
(which is physically disconnected when not in use signing releases) or a
live CD.
# Which Applications Create OpenPGP Compatible Signatures? # {#openpgp-applications}
There are many applications available (some commercial, some freeware, some
software libre). Whichever one you choose, please subscribe to the
appropriate security lists and keep the application fully patched.
Here are some used by ASF release managers:
- **Recommended** [GNU Privacy Guard](http://www.gnupg.org) *Software
Libre*
# How Safe Does The Private Key Need To Be? # {#safe-and-secure}
It is vital that the private key is kept safe and secure. Though the file
is encrypted using a [passphrase](#passphrase) , given enough time any
determined cracker will be able to break that encryption. It is therefore
essential that the private key file is kept safe and secure.
Basic precautions should include ensuring that the directories are readable
only by the user.
However, it is recommended that for code signing keys additional measures
are taken. The window of opportunity can be reduced by either using a
[isolated installation](#isolated-installation) or by storing the private
key on removable media (which should be removed to secure storage when not
being used to sign releases).
# What Does 'Isolated Installation' Mean? # {#isolated-installation}
An installation which is inaccessible when not being used to sign releases.
For example, create an installation on a separate hard disc or use a live
CD.
# What Key Length Is Recommended? # {#key-length}
There is no good, simple answer to this question.
The number of operations required to break a key by brute force increases
with key size. However, the cost of using the key also rises. So, the
planned usage of the key must be a consideration. Keys used for code
signing will only be used rarely and in situations where performance is not
the main concern. This is a reason to err in favor of long key lengths.
Over time, the practice cost of attacking a key (of a given length) by
brute force falls as computing power increases. So, a key whose length
seems adequate today may be seem too short in a few years time. This is a
significant issue for long-lived keys such as those used to sign ASF
releases. Again, this is a reason to err in the favor of longer key
lengths.
Now that there is doubt about the medium term security of [SHA-1](#sha1) ,
the DSA keys and 1024 bit RSA keys (which depend on this algorithm) should
be avoided for new keys. It is uncertain whether 2048 bit RSA keys will be
strong enough to remain secure until [SHA3](#sha3) (and the next generation
of standards) arrives. It is therefore recommended that new keys should be
at least 4096 bit RSA (the longest widely supported key length).
# Is MD5 Still Secure? # {#md5-security}
There is no good, simple answer to this question.
Though [feasible](#infeasible) collision attacks are known, they are still
computationally expensive. MD5 may still be useful as an additional layer
in a defense in depth. Not recommended.
# Is SHA-1 Still Secure? # {#sha1}
There is no good, simple answer to this question.
Research has revealed weaknesses in this algorithm. Though there are no
practical attacks known at the time of writing, experiences with similar
weaknesses in [MD5](#md5-security) suggest that efforts should be made now
to move away from this algorithm.
Breaking the longest members of this family ( `SHA512` and `SHA256` ) is
still considered [infeasible](#infeasible). Until [SHA-3](#sha3) is
available, new uses of SHA-1 should be avoided and SHA512 (or SHA256) used
instead.
Configuration instructions for GnuPG can be found
[here](openpgp.html#sha1).
# What is SHA-3? # {#sha3}
SHA-3 is the designation for a new [cryptographic hash
algorithm](#message-digest) to replace the SHA family. A public
[competition](http://csrc.nist.gov/groups/ST/hash/sha-3/index.html) is
currently ongoing.
# Which Standard Crytographic Hash Algorithms Are Secure? # {#secure-hash-algorithms}
There is no good, simple answer to this question.
[Feasible](#infeasible) - though expensive - attacks on MD5 have been made
public. Similar weaknesses have been found in the SHA family of hashes
though practical attacks are not yet publically known. However, longer hash
sizes offer considerable protection. So, larger members of the SHA family
still look likely to be secure enough for a number of years.
RIPE has not been as well studied as either SHA or MD5. It is likely to
offer no more security than SHA.
SHA512 is the strongest well studied widely used cryptographic hash. It is
therefore the best recommendation until [SHA3](#sha3) is available.
# How Do You Generate A Code Signing Key? # {#generate}
The exact mechanics are [application](#openpgp-applications) dependent. For
GnuPG (recommended), follow the [strong key generation
instructions](openpgp.html#generate-key). Please think about the [right key
length](#key-length) , configure the tool to [avoid SHA-1](#sha1) and
choose a good [passphrase](#passphrase). Use the recommended [id](#user-id)
and [comment](#key-comment).
# What OpenPGP User-ID Should I Choose For My Code Signing Key? # {#user-id}
It is recommended that your Apache email address is used as the primary
`User-ID` for the code signing key. For example, `rdonkin@apache.org`.
# What OpenPGP Comment Should I Choose For My Code Signing Key? # {#key-comment}
It is recommended that the comment includes *CODE SIGNING KEY*. This makes
clear the primary use for this key. This can be helpful if you later
generate keys for other uses.
It is recommended that keys generated for other purposes include in the
comment *NOT FOR CODE SIGNING*.
# What Is A Public Key Server? # {#keyserver}
A public key server manages [public keys](#public-private). Available
functions may vary but typically include [upload](#keyserver-upload) ,
search and download.
Public key servers exist to distribute public keys. They do not vouch for
the actual identity of the owner of each key. This must be established
either directly or through a [web of trust](#web-of-trust). Do not trust a
key just because it has been downloaded from a key server.
The major public key servers synchronize their records regularly so a key
uploaded to one should be disseminated to the rest.
Some well known public key servers:
- [MIT](http://pgp.mit.edu)
- [PGP Global Directory](http://keyserver.pgp.com/)
# How Do You Upload A Key To A Public Key Server? # {#keyserver-upload}
There are two common ways to upload a key to a [public key
server](#keyserver) :
- Most key servers allow [exports](#export) to be uploaded through the
website
- By using automatic facilities built into most [OpenPGP](#openpgp)
[implementations](#openpgp-applications)
For example using [GNU Privacy Guard](http://www.gnupg.org) , the key with
[ID](#key-id) B1313DE2 can be exported to the default public key server by:
$ gpg --lsign-key someuser
Note that each changed key must be exported separately.
# How Can I Ensure My Local Web Of Trust Is Up To Date? # {#update-web-of-trust}
The public web of trust grows constantly as people sign new keys and upload
the new signatures onto the network of [public key servers](#keyserver).
Public keys should be periodically refreshed to ensure that your local web
of trust is as full as possible. Many [OpenPGP](#openpgp)
[clients](#openpgp-applications) allow keys to be easily refreshed by
querying a public key server.
For example, to refresh all keys using [GNU Privacy
Guard](http://www.gnupg.org) use:
$ gpg --send-key B13131DE2
# How Do You Export A Key? # {#export}
A public key can be exported using [OpenPGP](http://www.gnupg.org) by using
`--export`. Typically, the export should be ASCII armored. For example, to
export all public keys to the command line use:
$ gpg --refresh-keys
gpg --export --armorIn most cases, it is better to export all keys - this ensures that signatures made on other keys will be exported. However, it is possible to export just one key by specifying it on the command line. Secret keys can also be exported. However, exporting secret keys poses a security risk and there are better solutions for most common use cases. For example, copying the `GNUPGHOME` directory (typically `~/.gnupg` ) is a better way to transfer an [OpenPGP](http://www.gnupg.org) keyring from one machine to another. # What Is A Key ID? # {#key-id} A key ID is similar to a [fingerprint](#fingerprint) but is much smaller in length. There is no guarantee that key IDs are unique. Consequently, it is strongly recommended that the fingerprint is checked before signing a key. The key ID is typically used for locating keys and identifying keys already contained within the keyring. For these use cases, key ID should be unique enough in practice. A short guide to discovering the key ID for a key is [available](openpgp.html#find-key-id). # What Is A Sub Key? # {#subkey} Each [OpenPGP](#openpgp) keyring has a single master key. This key is signing only. It may also optionally have a number of sub keys (for encryption and signing). If you wish to sign emails using a key related to that used to sign code, it is recommended that a signing sub key is [used](#email-subkey). # How Do I A Use Sub Key To Sign Emails? # {#email-subkey} To keep a code signing key [safe and secure](#safe-and-secure) it is recommended that the key is not kept on a hard disc on a regular development machine. This means that the master key should not be used directly to sign emails. However, there are occasions when digitally signed emails are desirable. The recommended approach is to create a sub key for email signing and export it to the regular machine. The master key can then be kept safely offline. For more details, read: - [Subkey cross certification](http://www.gnupg.org/(en)/faq/subkey-cross-certify.html) - [Signing Subkey HOWTO](http://fortytwo.ch/gpg/subkeys) Note that some [public key servers](#keyserver) do not handle sub keys correctly. It may be necessary to use one on the [SKS](http://www.nongnu.org/sks/) network. # How Can I Find Out More? # {#more-information} See [this](#reading). # Is There A Quick Way To Sign Several Distributions? # {#quick-signing} The private `https://svn.apache.org/repos/private/committers` repository contains scripts that assist with batch signing several distributions. # How Can I Transfer A Secret Key? # {#transfer-secret-keys} This is application dependent. Instructions for GnuPG are [available](openpgp.html#secret-key-transfer). # Why Do Some People Have Two Keys? # {#two-keys} When switching from an uncompromised key to another (typically stronger) one, it is convenient to use a [transition period](#transition). During a transition, both keys are trustworthy but only (the newer) one is actively used to sign documents and certify links in the [web of trust](#web-of-trust). # What Is A Transition Period (For Keys)? # {#transition} When replacing one uncompromised key with a newer (typically longer) one, a transition period where both keys are trustworthy and participate in the [web of trust](#web-of-trust) allows - by [trust transitivity](#web-of-trust) - links to the old key to be used to trust signatures and links created by the new key. During a transition, both keys are trustworthy but only (the newer) one is actively used to sign documents and certify links in the [web of trust](#web-of-trust). # How Should I Transition From A Short To A Longer Key? # {#how-to-transition} If you have a short but uncompromised key and would like to [transition](#transition) to a longer one, follow these [instructions](key-transition.html). If your key has been compromised then you **MUST NOT** transition but [revoke](#revoke-key) the old key and replace with a new one immediately. **DO NOT** use a transition period. # I Have A New Key. Which Apache Documents Need To Be Updated? # {#update-document} A number of Apache documents need to be updated. Follow these [instructions](openpgp.html#update). # What Is RSA? # {#rsa} RSA is a well known public key cryptography algorithm which supports signing and encryption. See [further reading](#reading) for more details. # How Do I Find The Length Of A Key? # {#key-length-how-to} The easiest way to discover the length of a key (with id `KEYID` ) is to use `gpg --list-keys KEYID`. This will print basic information about the key. The first line will include the size in the second column just before the id. For example:
$ gpg --list-keys B1313DE2 pub 1024D/B1313DE2 2003-01-15 uid Robert Burrell Donkin (CODE SIGNING KEY) <rdonkin@apache.org> uid Robert Burrell Donkin <robertburrelldonkin@gmail.com> uid Robert Burrell Donkin <robertburrelldonkin@blueyonder.co.uk> sub 4096R/40A882CB 2009-06-18 [expires: 2010-06-18] $ gpg --list-keys A6EE6908 pub 8192R/A6EE6908 2009-08-07 uid Robert Burrell Donkin (CODE SIGNING KEY) <rdonkin@apache.org> sub 8192R/B800EFC1 2009-08-07shows that key B1313DE2 has length 1024 and A6EE6908 length 8192.