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