Title: How To Transition To A Longer Key
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.
# Status # {#status}
This document explains how to create a new PGP key and break it in, gradually
having it replace the old key. It is here for the information of committers
who wish to change the PGP key they use at Apache (for example to [sign
releases](release#what-must-every-release-contain) with).
# Contents
[TOC]
# Important Note # {#important}
If your key has been compromised, you **MUST NOT** use a transition period.
You should immediately [revoke](release-signing.html#revoke-key) the
compromised key and [create a new one](openpgp.html#generate-key). All [web
of trust](release-signing.html#web-of-trust) links signed by the old key
should be regarded as suspect. A completely new set of links **MUST** be
re-established by meeting [in
person](release-signing.html#key-signing-party).
# Motivation # {#motivation}
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](release-signing.html#web-of-trust) allows - by [trust
transitivity](release-signing.html#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](release-signing.html#web-of-trust).
This document describes how to use [GnuPG](http://www.gnupg.org) to create
a new key and manage the keys during this transition period.
# Using A Single Keyring For Two Keys # {#single-keyring}
It is best to use a single keyring containing both keys.
## Generate New Key ## {#generate-new-key}
The new key should be generated either:
- directly in the keyring containing the old key
- in a new keyring and then transferred to the keyring containing the old
key
To generate a strong [RSA](release-signing.html#rsa) key follow these
[instructions](http://www.apache.org/dev/openpgp.html#generate-key). If a
separate keyring is used then follow these
[instructions](openpgp.html#secret-key-transfer) to transfer it.
Both new and old keys should now be contained in the same keyring. Verify
this by:
$ gpg --list-secret-keys
alice/secring.gpg
-----------------
sec 1024D/AD741727 2009-08-20
uid Alice Example (EXAMPLE OF OLD KEY) <alice@example.org>
ssb 1024g/268883A9 2009-08-20
sec 4096R/E2B054B8 2009-08-20
uid Alice Example (EXAMPLE NEW KEY) <alice@example.org>
ssb 4096R/4A6D5217 2009-08-20
Both new and old keys should be listed.
## Open Interative Edit ## {#open-interaction-edit}
Now a number of operations need to be performed on the new key. Though it's
possible to perform them individually (saving and closing after each one)
it is more convenient to use the interactive edit mode.
Start by opening an edit session on the new key, for example `E2B054B8`
$ gpg --edit-key E2B054B8
gpg (GnuPG) 1.4.9; Copyright (C) 2008 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Secret key is available.
pub 4096R/E2B054B8 created: 2009-08-20 expires: never usage: SC
trust: unknown validity: unknown
sub 4096R/4A6D5217 created: 2009-08-20 expires: never usage: E
[ unknown] (1). Alice Example (EXAMPLE NEW KEY) <alice@example.org>
Command>
## Trust The New Key ## {#trust-new-key}
The new key needs to be marked as ultimately trusted in this keyring. This
will ensure that the [web of trust](release-signing.html#web-of-trust)
links signed by this key will be trusted automatically.
Command> trust
pub 4096R/E2B054B8 created: 2009-08-20 expires: never usage: SC
trust: unknown validity: unknown
sub 4096R/4A6D5217 created: 2009-08-20 expires: never usage: E
[ unknown] (1). Alice Example (EXAMPLE NEW KEY) <alice@example.org>
Please decide how far you trust this user to correctly verify other users'
keys
(by looking at passports, checking fingerprints from different sources,
etc.)
1 = I don't know or won't say
2 = I do NOT trust
3 = I trust marginally
4 = I trust fully
5 = I trust ultimately
m = back to the main menu
Your decision? 5
Do you really want to set this key to ultimate trust? (y/N) y
pub 4096R/E2B054B8 created: 2009-08-20 expires: never usage: SC
trust: ultimate validity: unknown
sub 4096R/4A6D5217 created: 2009-08-20 expires: never usage: E
[ unknown] (1). Alice Example (EXAMPLE NEW KEY) <alice@example.org>
Please note that the shown key validity is not necessarily correct
unless you restart the program.
## Sign New Key With Old ## {#sign-new-key}
The new key should be signed with the old key (AD741727, say):
Command> sign AD741727
pub 4096R/E2B054B8 created: 2009-08-20 expires: never usage: SC
trust: ultimate validity: ultimate
Primary key fingerprint: FF96 6261 C995 1DDE BF34 5150 D5D2 BDB5 E2B0 54B8
Alice Example (EXAMPLE NEW KEY) <alice@example.org>
Are you sure that you want to sign this key with your
key "Alice Example (EXAMPLE OF OLD KEY) <alice@example.org>"
(AD741727)
Really sign? (y/N) y
You need a passphrase to unlock the secret key for
user: "Alice Example (EXAMPLE OF OLD KEY) <alice@example.org>"
1024-bit DSA key, ID AD741727, created 2009-08-20
## Check Preferences ## {#check-sha}
Check that [check that SHA-1 is avoided](openpgp.html#sha1) in the [key
preferences](openpgp.html#key-prefs) of both the new and old keys.
## Complete Edit ## {#finish-off}
It is convenient to add secondary user ids (for current email accounts)
now.
Save changes (which exits edit mode):
Command> save
## Whether To Sign The Old Key With The New ## {#sign-old-with-new}
Arguments can be made for and against signing the old key with the new. The
old key is less trustworthy now and will be revoked in future so signing it
may be misleading for those unaware of the potential weaknesses. However,
without this signature, signers of the new key will not receive the
transitive benefit of the links made from the old key. Anyone who chooses
not to sign the old key with the new should made efforts to resign links
made by the old key with the new key.
## Set Default To New Key ## {#set-default-to-new}
Next, the default key on the keyring needs to be changed from the old key
to the new. This will ensure that all future signatures will - by default -
use the new key. Though the old key can still be used for signing by
explicitly specifying it, this use should be avoided since the signatures
will be weak.
To make the new key the default, set the `default-key` in the
[gpg.conf](openpgp.html#configuration) configuration file. For example, to
set the default to `E2B054B8` add:
default-key E2B054B8
This setting can be tested by creating a test signature:
$ gpg --detach-sig --armor document
You need a passphrase to unlock the secret key for
user: "Alice Example (EXAMPLE NEW KEY) <alice@example.org>"
4096-bit RSA key, ID E2B054B8, created 2009-08-20
Verify that the new key has been chosen by default.
## Upload Both Keys ## {#update-keys}
Finish the process by uploading the new and old keys to the keyserver:
$ gpg --send-keys E2B054B8 AD741727
## Create Backups ## {#backups}
Follow these [instructions](openpgp.html#backup).
## Generate And Store Revocation Certificates ## {#revocation-certificates}
Follow these [instructions](openpgp.html#revocation-certs) to create and
securely store generic [revocation
certificates](release-signing.html#revocation-cert) for the new key.
## Update Documents ## {#update-documents}
The final stage in the process is to update documents containing references
to the old key so that they contain both the new and old keys. For Apache
documents, follow this [checklist](openpgp.html#update) opting for the
instructions appropriate for a transition (when given a choice).
For other documents:
- Those containing an [export](release-signing.html#export) , should be
updated with a [dual export](#transition-export)
- Those containing a [fingerprint](release-signing.html#fingerprint) should
be updated with [both fingerprints](#transition-fingerprints)
## Web Of Trust ## {#wot}
Read this [guide](openpgp.html#wot) to the Apache use of the [web of
trust](release-signing.html#web-of-trust) and make arrangements for your
new key to be included at the earliest opportunity.
# How To Export Both New And Old Keys # {#transition-export}
During a transition period, a single export containing both new and old
public keys should be used whenever an export is needed. To create a
suitable export, supply both key IDs on the command line.
For example, to export keys `AD741727` (old) and `E2B054B8` (new) to
*FILENAME* use:
$ gpg --export --armor --output FILENAME AD741727 E2B054B8
This exports only the public keys, and so isn't confidential. Everywhere
the old public key was published should be replaced by this dual export.
# How To Fingerprint New And Old Keys # {#transition-fingerprints}
During the transitions, both fingerprints should be used. For example, to
fingerprint old key AD741727 and new key E2B054B8, use:
$ gpg --fingerprint AD741727 E2B054B8
pub 1024D/AD741727 2009-08-20
Key fingerprint = CD0C 5281 D0A9 E963 19AF F365 AD81 612A AD74 1727
uid Alice Example (EXAMPLE OF OLD KEY) <alice@example.org>
sub 1024g/268883A9 2009-08-20
pub 4096R/E2B054B8 2009-08-20
Key fingerprint = FF96 6261 C995 1DDE BF34 5150 D5D2 BDB5 E2B0 54B8
uid Alice Example (EXAMPLE NEW KEY) <alice@example.org>
sub 4096R/4A6D5217 2009-08-20
So the fingerprints are:
- `CD0C 5281 D0A9 E963 19AF F365 AD81 612A AD74 1727` for AD741727
- `FF96 6261 C995 1DDE BF34 5150 D5D2 BDB5 E2B0 54B8` for E2B054B8
(For every fingerprint, the last 8 digits are the key ID.)