.\"  -*- nroff -*-
.Dd $Mdocdate: Jan 22, 2019 $
.Dt PEM2OPENPGP 1
.Os
.Sh NAME
pem2openpgp
.Nd translate PEM-encoded RSA keys to OpenPGP certificates
.Sh SYNOPSIS
.Nm pem2openpgp "$USERID" < mykey.pem | gpg \-\-import
.Pp
.Nm PEM2OPENPGP_EXPIRATION=$((86400 * $DAYS)) PEM2OPENPGP_USAGE_FLAGS=authenticate,certify pem2openpgp "$USERID" <mykey.pem
.Sh DESCRIPTION
.Nm
is a low-level utility for transforming raw, PEM-encoded RSA secret
keys into OpenPGP-formatted certificates.  The generated certificates
include the secret key material, so they should be handled carefully.
.Pp
It works as an element within a pipeline: feed it the raw key on
stdin, supply the desired User ID as a command line argument.  Note
that you may need to quote the string to ensure that it is entirely in
a single argument.
.Pp
Other choices about how to generate the new OpenPGP certificate are
governed by environment variables.
.Sh ENVIRONMENT
The following environment variables influence the behavior of
.Nm :
.Pp
.ti 3
\fBPEM2OPENPGP_TIMESTAMP\fP controls the timestamp (measured in
seconds since the UNIX epoch) indicated as the creation time (a.k.a
"not valid before") of the generated certificate (self-signature) and
the key itself.  By default,
.Nm
uses the current time.
.Pp
.ti 3
\fBPEM2OPENPGP_KEY_TIMESTAMP\fP controls the timestamp (measured in
seconds since the UNIX epoch) indicated as the creation time of just
the key itself (not the self-signature).  By default,
.Nm
uses the value from PEM2OPENPGP_TIMESTAMP.
.Pp
.ti 3
\fBPEM2OPENPGP_USAGE_FLAGS\fP should contain a comma-separated list of
valid OpenPGP usage flags (see section 5.2.3.21 of RFC 4880 for what
these mean).  The available choices are: certify, sign, encrypt_comms,
encrypt_storage, encrypt (this means both encrypt_comms and
encrypt_storage), authenticate, split, shared.  By default, 
.Nm
only sets the certify flag.
.Pp
.ti 3
\fBPEM2OPENPGP_EXPIRATION\fP sets an expiration (measured in seconds
after the creation time of the key) in each self-signature packet.  By
default, no expiration subpacket is included.
.Pp
.ti 3
\fBPEM2OPENPGP_NEWKEY\fP indicates that
.Nm
should ignore stdin, and instead generate a new key internally and
build the certificate based on this new key.  Set this variable to the
number of bits for the new RSA key (e.g. 3072).  By default (when this is
unset), 
.Nm
will read the key from stdin.
.Sh AUTHOR
.Nm
and this man page were written by Daniel Kahn Gillmor
<dkg@fifthhorseman.net>.
.Sh BUGS
Only handles RSA keys at the moment.  It might be nice to handle DSA
keys as well.
.Pp
Currently only creates certificates with a single User ID.  Should be
able to create certificates with multiple User IDs.
.Pp
Currently only accepts unencrypted RSA keys.  It should be able to
deal with passphrase-locked key material.
.Pp
Currently outputs OpenPGP certificates with cleartext secret key
material.  It would be good to be able to lock the output with a
passphrase.
.Pp
If you find other bugs, please report them at
https://labs.riseup.net/code/projects/show/monkeysphere
.Sh SEE ALSO
.Xr openpgp2ssh 1 ,
.Xr monkeysphere 1 ,
.Xr monkeysphere 7 ,
.Xr ssh 1 ,
.Xr monkeysphere\-host 8 ,
.Xr monkeysphere\-authentication 8