8dfc53af39c0e5f3400bd4b2124ab6b45324a6e6
[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 "\-r, \-\-req"
53 Create a PKCS#10 certificate request.
54 .TP
55 .B "\-7, \-\-pkcs7"
56 Provides PKCS#7 wrap/unwrap functions.
57 .TP
58 .B "\-k, \-\-keyid"
59 Calculate key identifiers of a key or certificate.
60 .TP
61 .B "\-a, \-\-print"
62 Print a credential (key, certificate etc.) in human readable form.
63 .TP
64 .B "\-p, \-\-pub"
65 Extract a public key from a private key or certificate.
66 .TP
67 .B "\-v, \-\-verify"
68 Verify a certificate using a CA certificate.
69 .
70 .SH "EXAMPLES"
71 .
72 .SS "Generating a CA Certificate"
73 .
74 The first step is to generate a private key using the
75 .B \-\-gen
76 command. By default this generates a 2048-bit RSA key.
77 .PP
78 .EX
79   pki \-\-gen > ca_key.der
80 .EE
81 .PP
82 This key is used to create the self-signed CA certificate, using the
83 .B \-\-self
84 command. The distinguished name should be adjusted to your needs.
85 .PP
86 .EX
87   pki \-\-self \-\-ca \-\-in ca_key.der \\
88       \-\-dn "C=CH, O=strongSwan, CN=strongSwan CA" > ca_cert.der
89 .EE
90 .PP
91 .
92 .SS "Generating End-Entity Certificates"
93 .
94 With the root CA certificate and key at hand end-entity certificates for clients
95 and servers can be issued. Similarly intermediate CA certificates can be issued,
96 which in turn can issue other certificates.
97 To generate a certificate for a server, we start by generating a private key.
98 .PP
99 .EX
100   pki \-\-gen > server_key.der
101 .EE
102 .PP
103 The public key will be included in the certificate so lets extract that from the
104 private key.
105 .PP
106 .EX
107   pki \-\-pub \-\-in server_key.der > server_pub.der
108 .EE
109 .PP
110 The following command will use the CA certificate and private key to issue the
111 certificate for this server. Adjust the distinguished name, subjectAltName(s)
112 and flags as needed (check
113 .BR pki\ \-\-issue (8)
114 for more options).
115 .PP
116 .EX
117   pki \-\-issue \-\-in server_pub.der \-\-cacert ca_cert.der \\
118       \-\-cakey ca_key.der \-\-dn "C=CH, O=strongSwan, CN=VPN Server" \\
119       \-\-san vpn.strongswan.org \-\-flag serverAuth > server_cert.der
120 .EE
121 .PP
122 Instead of storing the public key in a separate
123 file, the output of
124 .B \-\-pub
125 may also be piped directly into the above command.
126 .
127 .SS "Generating Certificate Revocation Lists (CRL)"
128 .
129 If end-entity certificates have to be revoked, CRLs may be generated using
130 the
131 .B \-\-signcrl
132 command.
133 .PP
134 .EX
135   pki \-\-signcrl \-\-cacert ca_cert.der \-\-cakey ca_key.der \\
136       \-\-reason superseded \-\-cert server_cert.der > crl.der
137 .EE
138 .PP
139 The certificate given with \-\-cacert must be either a CA certificate or a
140 certificate with the
141 .I crlSign
142 extended key usage (\-\-flag crlSign). URIs to CRLs may be included in issued
143 certificates with the \-\-crl option.
144 .
145 .SH "SEE ALSO"
146 .
147 .BR pki\ \-\-gen (1),
148 .BR pki\ \-\-self (1),
149 .BR pki\ \-\-issue (1),
150 .BR pki\ \-\-signcrl (1),
151 .BR pki\ \-\-req (1),
152 .BR pki\ \-\-pkcs7 (1),
153 .BR pki\ \-\-keyid (1),
154 .BR pki\ \-\-print (1),
155 .BR pki\ \-\-pub (1),
156 .BR pki\ \-\-verify (1)