Signing Releases - Apache Infrastructure

Signing Releases - Apache Infrastructure Website
Signing Releases
Introduction
The first part of this document gives release managers a basic introduction to release signing. See under
Further reading
for links to authoritative sources of deeper information.
The second part answers some frequently-asked questions from people who download releases from Apache projects.
This document is informative and does not constitute policy.
Contents
For release managers
Important notes
Basic facts
Signing basics
Keys basics
How can I safely practice using OpenPGP?
Web of Trust basics
What is a Passphrase?
Revocation Certificate basics
Automated Release Signing
Further Reading
FAQs from those downloading releases
What does verifying a signature mean?
How can I check the integrity of a release?
What is the difference between secure hardware and trusted hardware?
What does 'Public key not found' mean when verifying a signature?
What is a trusted key?
What is the difference between a valid signature from an untrusted key and an invalid signature from a trusted key?
What is a public key fingerprint?
Can I mark a key as locally trusted?
For release managers
Important notes
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 impact of this weakness on Apache can be mitigated by action now. What needs to be done is a little involved, so we have provided complete instructions.
Committers without a code signing key should read this document and follow these
instructions
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
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
and wait for the next major OpenPGP revision.
How to find the length of your key is described
here
The basics
Every artifact distributed by the Apache Software Foundation
must
be accompanied by one file containing an
OpenPGP-compatible ASCII armored detached signature
and another file containing a
SHA
or
MD5
) checksum.
MD5 hashes are
deprecated
; please use SHA for new releases.
Avoid
further use of
SHA-1
Form the names of these files by adding to the name of the artifact the following suffixes:
the signature by suffixing
.asc
the checksum by suffixing
.md5
or
.sha[1|256|512]
(as appropriate)
Release managers
must not
store private keys used to sign Apache releases on ASF hardware.
See the
release distribution policy
for details.
Why we sign releases
A signature allows anyone to verify that a file is identical to the one your project's release manager created. Since your project's release has 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
signatures
confer the usual advantages of digital signatures: authentication, integrity and non-repudiation.
MD5
and
SHA
checksums only provide the integrity part as they are not encrypted.
Security checklist
Protect
your
private key
Choose a
good passphrase
Opt for a reasonably
long key length
Signing basics
Signatures should be
ASCII armored and detached
You should
export
your
public key
and append the result to the appropriate
KEYS
file(s).
How do I sign a release?
Create a
OpenPGP compatible ASCII armored detached signature
for the released artifact. Upload the signature with the released artifact. See
here
for a basic overview.
What Is an OpenPGP compatible ASCII armored detached signature?
It is
an
OpenPGP
compatible
ASCII armored
detached signature
To create one using
GNU Privacy Guard
for file
foo.tar.gz
, type:
$ gpg --armor --output foo.tar.gz.asc --detach-sig foo.tar.gz
What is an MD5 checksum?
MD5 is a
well known
message
digest algorithm
. Many tools are available to calculate these sums. For example, you can use
OpenSSL
$ openssl md5 < file
Platform-specific applications are also common, such as
md5sum
on linux:
$ md5sum file
With GnuPG:
$ gpg --print-md MD5 [fileName] > [fileName].md5
Run the command in the same directory as the file so the output only contains the file name with no directory prefixes.
Note
that the security of MD5 is now
questionable
and is only useful as part of a defense in depth.
What is an SHA checksum?
Like
MD5
SHA
is a
message digest
algorithm. Using GnuPG, you can create a SHA1 signature as follows:
$ gpg --print-md SHA1 [fileName] > [fileName].sha1
Avoid
further use of
SHA-1
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
. Apache recommends using
SHA512
To create a
SHA512
checksum use:
$ sha512sum [fileName] > [fileName].sha512
Run the command in the same directory as the file so the output only contains the file name with no directory prefixes.
There are other members of the
SHA
family that are rarely used.
Message digest algorithms
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
to create a message matching a given hash.
You can use a trusted digest for a document can be used to verify the contents of an untrusted file. You can deliver the digest, which has a small size over a secure but expensive channel while delivering the untrusted file over an insecure but inexpensive one. This is useful when distributing releases.
Why infeasible and not impossible?
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 better question is whether attacks are feasible
given the current state of the art
Applications that create OpenPGP-compatible signatures
Many applications are available (some commercial, some freeware, some software libre) to help you sign releases. Whichever one you choose, please subscribe to the appropriate security lists and keep the application fully patched.
Apache recommends that ASF release managers use
GNU Privacy Guard
Where should I create the signatures?
Creating signatures requires the private key. Keep limited copies of the private key securely and confidentially. Though the file used
to store the private key is typically protected by encryption, it is vulnerable to dictionary attacks on the
passphrase
. So keep this file secret.
Create signatures on the machine where you store the private key, on secure hardware with limited read permissions, protected by a good
passphrase
. Consider using removable media or an
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, create multiple
sub keys
for these purposes.
Do
not
store your private key on any ASF machine. Do
not
create signatures on ASF machines.
What is 'insecure memory'?
When you use
GNU Privacy Guard
you may see a warning similar to:
gpg: WARNING: using insecure memory!
gpg: please see http://www.gnupg.org/faq.html for more information
If you are using GnuPG on Apache hardware, please read
this
. Do
not
carry out sensitive operations using a private key on ASF hardware.
If you encounter this issue elsewhere, it indicates that GnuPG cannot lock memory pages, so 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
How secure does the machine I use to sign releases need to be?
If the code signing machine is
owned
, 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 and with appropriate anti-virus and firewall software. The ideal is an isolated, well-maintained installation that you only use for creating releases. You can achieve this with a little effort by creating an
isolated installation
on a separate hard disc (which is physically disconnected when not in use signing releases) or a live CD.
Is MD5 still secure?
Though
feasible
collision attacks that can defeat MD5 are known, they are still computationally expensive. MD5 may still be useful as an additional layer in a defense in depth, but Apache does
not recommend
it as your single security option.
Is SHA-1 still secure?
Research has revealed weaknesses in this algorithm. Though there are no practical attacks known at the time of writing, experience with similar weaknesses in
MD5
suggest that code signers should move away from this algorithm.
Breaking the longest members of this family (
SHA512
and
SHA256
) is still considered
infeasible
. Until
SHA-3
is available, avoid new uses of
SHA-1
and use
SHA512
or
SHA256
instead.
What is SHA-3?
SHA-3 is the designation for a new
cryptographic hash algorithm
to replace the SHA family. The full standard was issued in 2015, but it hasn't yet been officially introduced into the OpenPGP standard. For that reason GnuPG doesn't support it yet.
Which standard cryptographic hash algorithms are secure?
Feasible
- 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 publicly 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.
SHA512 is the strongest well-studied, widely-used cryptographic hash. It is therefore the best recommendation until
SHA3
is available.
How to generate a code signing key
The exact mechanics are
application
-dependent. For GnuPG (recommended):
Follow the
strong key generation instructions
Decide on the
right key length
Configure the tool to
avoid SHA-1
Choose a good
passphrase
Use the recommended
id
and
comment
The OpenPGP User-ID to use for your code-signing key
We recommend that you use your Apache email address as the primary
User-ID
for the code signing key. For example,
rdonkin@apache.org
The OpenPGP comment to choose for your code-signing key
The comment should include
CODE SIGNING KEY
. This makes clear the primary use for this key. This can be helpful if you later
generate keys for other uses.
Include the comment
NOT FOR CODE SIGNING
for keys you generate for other purposes.
What is a public key server?
A public key server manages
public keys
. Available functions may vary but typically include
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. You must establish this either directly or through a
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 you only need to upload a key to one and rely on that server to disseminate it to the other key servers. We recommend using
OpenPGP Public Key Server
How to upload a key to a public key server
There are two common ways to upload a key to a
public key server
Most key servers let you upload
exports
through their websites
Use automatic facilities built into most
OpenPGP
implementations
For example, using
GNU Privacy Guard
, send the key with
ID
B1313DE2 to the default public key server by:
$ gpg --send-key B13131DE2
You must export each changed key separately.
How to make sure your local web of trust is up-to-date
The public web of trust grows constantly as people sign new keys and upload the new signatures onto the network of
public key servers
. You should refresh public keys periodically to make sure that your local web of trust is as full as possible. Many
OpenPGP
clients
make it easy to refresh keys by
querying a public key server. For example, to refresh all keys using
GNU Privacy Guard
, use:
$ gpg --refresh-keys
How to export a key
You can export a public key through
OpenPGP
by using
--export
. Typically, the export should be ASCII armored.
To export all public keys to the command line use:
gpg --export --armor
In 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.
You can export secret keys. However, this 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
keyring from one machine to another.
What a key ID is
A key ID is similar to a
fingerprint
but is much smaller in length. There is no guarantee that key IDs are unique. Consequently, we strongly recommend that you check the key's fingerprint before signing with it. People us key IDs for locating keys and identifying keys already contained within the keyring.
A short guide to discovering the key ID for a key is
available
What a sub key is
Each
OpenPGP
keyring has a single master key. This key is for signing only. It may also optionally have a number of sub keys for encryption and signing.
If you want to sign emails using a key related to one you use to sign code, we recommend that you use a signing
sub key
How to use a sub key to sign emails
To keep a code signing key
safe and secure
we recommend that you don't keep the key on a drive on a regular development machine. This means that you should not use the master key directly to sign emails. However, there are occasions when digitally signed emails are desirable.
To do that, create a sub key for email signing and export it to your regular machine. You can then keep the master key safely
offline. For more details, read
Subkey cross
certification
Note
that some
public key servers
do not handle sub keys correctly. It may be necessary to use one on the
SKS
network.
A quick way to sign several distributions
The private
repository contains scripts that assist with batch signing several distributions at one time.
How to transfer a secret key
The way to transfer secret keys depends on the application you are using. Instructions for GnuPG are
available
Why some people have two keys
When you switch from an uncompromised key to another, usually stronger, one, it is convenient to use a
transition period
. During a transition, both keys are trustworthy but you only use the newer one to sign documents and certify links in the
web of trust
What a transition period for keys is
When you replace one uncompromised key with a newer and usually larger one, a transition period during which both keys are trustworthy and participate in the
web of trust
allows - by
trust transitivity
- 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 you only use the newer oneto sign documents and certify links in the
web of trust
How to transition from a short to a longer key
If you have a short but uncompromised key and would like to
transition
to a longer one, follow these
instructions
If your key has been compromised then you
must not
transition.
Revoke
the old key and replace it with a new one immediately.
Do not
use a transition period.
I have a new key. What Apache documents do I have to update?
There are several Apache documents you have to update when you have a new key. Follow these
instructions
What RSA is
RSA is a well known public key cryptography algorithm which supports signing and encryption. See
further reading
for more details.
How to find the length of a key
The easiest way to discover the length of a key with id
KEYID
is to use
gpg --list-keys KEYID
. This prints basic information about the key. The first line includes 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)
uid Robert Burrell Donkin
uid Robert Burrell Donkin
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)
sub 8192R/B800EFC1 2009-08-07
shows that key
B1313DE2
has length 1024 and
A6EE6908
length 8192.
Key basics
To sign releases, you need to
generate
a new master key-pair for code signing. Follow these
instructions
The KEYS File
The KEYS file is a plain-text file containing the public key signatures of the release managers (and optionally other committers) for the project. A good example is the
Apache Ant KEYS file
It is traditional to include the following header to explain how to use the file. These commands generate a descriptive comment describing the key, followed by the key itself. Key handling software ignores the comments when importing a key file:
This file contains the PGP keys of various developers.

Users: pgp < KEYS
or
gpg --import KEYS