f347031b4a522e10fa20677d94199234459175cc
[strongswan.git] / src / pki / man / pki.1.in
1 .TH PKI 1 "2013-07-31" "@PACKAGE_VERSION@" "strongSwan"
2 .
3 .SH "NAME"
4 .
5 pki \- Simple public key infrastructure (PKI) management tool
6 .
7 .SH "SYNOPSIS"
8 .
9 .SY "pki"
10 .I command
11 .RI [ option\~ .\|.\|.]
12 .YS
13 .
14 .SY "pki"
15 .B \-h
16 |
17 .B \-\-help
18 .YS
19 .
20 .SH "DESCRIPTION"
21 .
22 .B pki
23 is a suite of commands that allow you to manage a simple public key
24 infrastructure (PKI).
25 .P
26 Generate RSA and ECDSA key pairs, create PKCS#10 certificate requests
27 containing subjectAltNames, create X.509 self-signed end-entity and root CA
28 certificates, issue end-entity and intermediate CA certificates signed by the
29 private key of a CA and containing subjectAltNames, CRL distribution points
30 and URIs of OCSP servers. You can also extract raw public keys from private
31 keys, certificate requests and certificates and compute two kinds of SHA-1-based
32 key IDs.
33 .
34 .SH "COMMANDS"
35 .
36 .TP
37 .B "\-h, \-\-help"
38 Prints usage information and a short summary of the available commands.
39 .TP
40 .B "\-g, \-\-gen"
41 Generate a new private key.
42 .TP
43 .B "\-s, \-\-self"
44 Create a self-signed certificate.
45 .TP
46 .B "\-i, \-\-issue"
47 Issue a certificate using a CA certificate and key.
48 .TP
49 .B "\-c, \-\-signcrl"
50 Issue a CRL using a CA certificate and key.
51 .TP
52 .B "\-z, \-\-acert"
53 Issue an attribute certificate.
54 .TP
55 .B "\-r, \-\-req"
56 Create a PKCS#10 certificate request.
57 .TP
58 .B "\-7, \-\-pkcs7"
59 Provides PKCS#7 wrap/unwrap functions.
60 .TP
61 .B "\-k, \-\-keyid"
62 Calculate key identifiers of a key or certificate.
63 .TP
64 .B "\-a, \-\-print"
65 Print a credential (key, certificate etc.) in human readable form.
66 .TP
67 .B "\-p, \-\-pub"
68 Extract a public key from a private key or certificate.
69 .TP
70 .B "\-v, \-\-verify"
71 Verify a certificate using a CA certificate.
72 .
73 .SH "EXAMPLES"
74 .
75 .SS "Generating a CA Certificate"
76 .
77 The first step is to generate a private key using the
78 .B \-\-gen
79 command. By default this generates a 2048-bit RSA key.
80 .PP
81 .EX
82   pki \-\-gen > ca_key.der
83 .EE
84 .PP
85 This key is used to create the self-signed CA certificate, using the
86 .B \-\-self
87 command. The distinguished name should be adjusted to your needs.
88 .PP
89 .EX
90   pki \-\-self \-\-ca \-\-in ca_key.der \\
91       \-\-dn "C=CH, O=strongSwan, CN=strongSwan CA" > ca_cert.der
92 .EE
93 .PP
94 .
95 .SS "Generating End-Entity Certificates"
96 .
97 With the root CA certificate and key at hand end-entity certificates for clients
98 and servers can be issued. Similarly intermediate CA certificates can be issued,
99 which in turn can issue other certificates.
100 To generate a certificate for a server, we start by generating a private key.
101 .PP
102 .EX
103   pki \-\-gen > server_key.der
104 .EE
105 .PP
106 The public key will be included in the certificate so lets extract that from the
107 private key.
108 .PP
109 .EX
110   pki \-\-pub \-\-in server_key.der > server_pub.der
111 .EE
112 .PP
113 The following command will use the CA certificate and private key to issue the
114 certificate for this server. Adjust the distinguished name, subjectAltName(s)
115 and flags as needed (check
116 .BR pki\ \-\-issue (8)
117 for more options).
118 .PP
119 .EX
120   pki \-\-issue \-\-in server_pub.der \-\-cacert ca_cert.der \\
121       \-\-cakey ca_key.der \-\-dn "C=CH, O=strongSwan, CN=VPN Server" \\
122       \-\-san vpn.strongswan.org \-\-flag serverAuth > server_cert.der
123 .EE
124 .PP
125 Instead of storing the public key in a separate
126 file, the output of
127 .B \-\-pub
128 may also be piped directly into the above command.
129 .
130 .SS "Generating Certificate Revocation Lists (CRL)"
131 .
132 If end-entity certificates have to be revoked, CRLs may be generated using
133 the
134 .B \-\-signcrl
135 command.
136 .PP
137 .EX
138   pki \-\-signcrl \-\-cacert ca_cert.der \-\-cakey ca_key.der \\
139       \-\-reason superseded \-\-cert server_cert.der > crl.der
140 .EE
141 .PP
142 The certificate given with \-\-cacert must be either a CA certificate or a
143 certificate with the
144 .I crlSign
145 extended key usage (\-\-flag crlSign). URIs to CRLs may be included in issued
146 certificates with the \-\-crl option.
147 .
148 .SH "SEE ALSO"
149 .
150 .BR pki\ \-\-gen (1),
151 .BR pki\ \-\-self (1),
152 .BR pki\ \-\-issue (1),
153 .BR pki\ \-\-signcrl (1),
154 .BR pki\ \-\-acert (1),
155 .BR pki\ \-\-req (1),
156 .BR pki\ \-\-pkcs7 (1),
157 .BR pki\ \-\-keyid (1),
158 .BR pki\ \-\-print (1),
159 .BR pki\ \-\-pub (1),
160 .BR pki\ \-\-verify (1)