1 files changed, 94 insertions, 0 deletions
diff --git a/debian/migrate-pubring-from-classic-gpg.1 b/debian/migrate-pubring-from-classic-gpg.1
new file mode 100644
index 0000000..7cbeec7
--- /dev/null
+++ b/debian/migrate-pubring-from-classic-gpg.1
@@ -0,0 +1,94 @@
+.TH "MIGRATE-PUBRING-FROM-CLASSIC-GPG" 1 "April 2016"
+
+.SH NAME
+migrate\-pubring\-from\-classic\-gpg \- Migrate a public keyring from "classic" to "modern" GnuPG
+
+.SH SYNOPSIS
+.B migrate\-pubring\-from\-classic\-gpg
+.RB "[ " GPGHOMEDIR " | "
+.IR \-\-default " ]"
+
+.SH DESCRIPTION
+
+.B migrate\-pubring\-from\-classic\-gpg
+migrates the public keyring in GnuPG home directory GPGHOMEDIR from
+the "classic" keyring format (pubring.gpg) to the "modern" keybox format using GnuPG
+versions 2.1 or 2.2 (pubring.kbx).
+
+Specifying
+.B \-\-default
+selects the standard GnuPG home directory (looking at $GNUPGHOME
+first, and falling back to ~/.gnupg if unset.
+
+.SH OPTIONS
+.BR \-h ", " \-\-help ", " \-\-usage
+Output a short usage information.
+
+.SH DIAGNOSTICS
+The program sends quite a bit of text (perhaps too much) to stderr.
+
+During a migration, the tool backs up several pieces of data in a
+timestamped subdirectory of the GPGHOMEDIR.
+
+.SH LIMITATIONS
+The keybox format rejects a number of OpenPGP certificates that the
+"classic" keyring format used to accept.  These filters are defensive,
+since the certificates rejected are unsafe -- either cryptographically
+unsound, or dangerously non-performant.  This means that some
+migrations may produce warning messages about the migration being
+incomplete.  This is generally a good thing!
+
+Known limitations:
+
+.B Flooded certificates
+.RS 4
+Some OpenPGP certificates have been flooded with bogus certifications
+as part of an attack on the SKS keyserver network (see
+https://tools.ietf.org/html/draft-dkg-openpgp-abuse-resistant-keystore-03#section-2.1).
+
+The keybox format rejects import of any OpenPGP certificate larger
+than 5MiB.  As of GnuPG 2.2.17, if gpg encounters such a flooded
+certificate will retry the import while stripping all third-party
+certifications (see "self-sigs-only" in gpg(1)).
+
+The typical error message when migrating a keyring with a flooded
+certificate will be something like:
+
+.RE
+.RS 8
+error writing keyring 'pubring.kbx': Provided object is too large
+.RE
+
+.B OpenPGPv3 public keys (a.k.a. "PGP-2" keys)
+.RS 4
+Modern OpenPGP implementations use so-called "OpenPGP v4" public keys.
+Older versions of the public key format have serious known problems.
+See https://tools.ietf.org/html/rfc4880#section-5.5.2 for more details
+about and reasons for v3 key deprecation.
+
+The keybox format skips v3 keys entirely during migration, and GnuPG
+will produce a message like:
+
+.RE
+.RS 8
+skipped PGP-2 keys: 1
+.RE
+
+.SH ENVIRONMENT VARIABLES
+
+.B GNUPGHOME
+Selects the GnuPG home directory when set and --default is given.
+
+.B GPG
+The name of the
+.B gpg
+executable (defaults to
+.B gpg
+).
+
+.SH SEE ALSO
+.BR gpg (1)
+
+.SH AUTHOR
+Copyright (C) 2016 Daniel Kahn Gillmor for the Debian project. Please
+report bugs via the Debian BTS.