Merge commit 'dkg/master'
[monkeysphere.git] / man / man1 / pem2openpgp.1
1 .\"  -*- nroff -*-
2 .Dd $Mdocdate: January 25, 2009 $
3 .Dt PEM2OPENPGP 1
4 .Os
5 .Sh NAME
6 pem2openpgp
7 .Nd translate PEM-encoded RSA keys to OpenPGP certificates
8 .Sh SYNOPSIS
9 .Nm pem2openpgp "$USERID" < mykey.pem | gpg --import
10 .Pp
11 .Nm PEM2OPENPGP_EXPIRATION=$((86400 * $DAYS)) PEM2OPENPGP_USAGE_FLAGS=authentication,certify pem2openpgp "$USERID" <mykey.pem
12 .Sh DESCRIPTION
13 .Nm
14 is a low-level utility for transforming raw, PEM-encoded RSA secret
15 keys into OpenPGP-formatted certificates.  The generated certificates
16 include the secret key material, so they should be handled carefully.
17 .Pp
18 It works as an element within a pipeline: feed it the raw key on
19 stdin, supply the desired User ID as a command line argument.  Note
20 that you may need to quote the string to ensure that it is entirely in
21 a single argument.
22 .Pp
23 Other choices about how to generate the new OpenPGP certificate are
24 governed by environment variables.
25 .Sh ENVIRONMENT
26 The following environment variables influence the behavior of
27 .Nm :
28 .Pp
29 .ti 3
30 \fBPEM2OPENPGP_TIMESTAMP\fP controls the timestamp (measured in
31 seconds since the UNIX epoch) indicated as the creation time (a.k.a
32 "not valid before") of the generated certificate.  By default,
33 .Nm
34 uses the current time.
35 .Pp
36 .ti 3
37 \fBPEM2OPENPGP_USAGE_FLAGS\fP should contain a comma-separated list of
38 valid OpenPGP usage flags (see section 5.2.3.21 of RFC 4880 for what
39 these mean).  The available choices are: certify, sign, encrypt_comms,
40 encrypt_storage, encrypt (this means both encrypt_comms and
41 encrypt_storage), authenticate, split, shared.  By default, 
42 .Nm
43 only sets the certify flag.
44 .Pp
45 .ti 3
46 \fBPEM2OPENPGP_EXPIRATION\fP sets an expiration (measured in seconds
47 after the creation time of the key) in each self-signature packet.  By
48 default, no expiration subpacket is included.
49 .Pp
50 .ti 3
51 \fBPEM2OPENPGP_NEWKEY\fP indicates that
52 .Nm
53 should ignore stdin, and instead generate a new key internally and
54 build the certificate based on this new key.  Set this variable to the
55 number of bits for the new key (e.g. 2048).  By default (when this is
56 unset), 
57 .Nm
58 will read the key from stdin.
59 .Sh AUTHOR
60 .Nm
61 and this man page were written by Daniel Kahn Gillmor
62 <dkg@fifthhorseman.net>.
63 .Sh BUGS
64 Only handles RSA keys at the moment.  It would be nice to handle DSA
65 keys as well.
66 .Pp
67 Currently only creates certificates with a single User ID.  Should be
68 able to create certificates with multiple User IDs.
69 .Pp
70 Currently only accepts unencrypted RSA keys.  It should be able to
71 deal with passphrase-locked key material.
72 .Pp
73 Currently outputs OpenPGP certificates with cleartext secret key
74 material.  It would be good to be able to lock the output with a
75 passphrase.
76 .Pp
77 If you find other bugs, please report them at
78 https://labs.riseup.net/code/projects/show/monkeysphere
79 .Sh SEE ALSO
80 .Xr openpgp2ssh 1,
81 .Xr monkeysphere 1 ,
82 .Xr monkeysphere 7 ,
83 .Xr ssh 1 ,
84 .Xr monkeysphere-host 8 ,
85 .Xr monkeysphere-authentication 8