pki: Add a note about constructing RFC 3779 compliant certificates to manpage
[strongswan.git] / src / pki / man / pki---issue.1.in
1 .TH "PKI \-\-ISSUE" 1 "2016-12-13" "@PACKAGE_VERSION@" "strongSwan"
2 .
3 .SH "NAME"
4 .
5 pki \-\-issue \- Issue a certificate using a CA certificate and key
6 .
7 .SH "SYNOPSIS"
8 .
9 .SY pki\ \-\-issue
10 .OP \-\-in file
11 .OP \-\-type type
12 .BI \-\-cakey\~ file |\-\-cakeyid\~ hex
13 .BI \-\-cacert\~ file
14 .OP \-\-dn subject-dn
15 .OP \-\-san subjectAltName
16 .OP \-\-lifetime days
17 .OP \-\-not-before datetime
18 .OP \-\-not-after datetime
19 .OP \-\-serial hex
20 .OP \-\-flag flag
21 .OP \-\-digest digest
22 .OP \-\-ca
23 .OP \-\-crl uri\ \fR[\fB\-\-crlissuer\ \fIissuer\fR]
24 .OP \-\-ocsp uri
25 .OP \-\-pathlen len
26 .OP \-\-nc-permitted name
27 .OP \-\-addrblock block
28 .OP \-\-nc-excluded name
29 .OP \-\-policy\-mapping mapping
30 .OP \-\-policy\-explicit len
31 .OP \-\-policy\-inhibit len
32 .OP \-\-policy\-any len
33 .OP \-\-cert\-policy oid\ \fR[\fB\-\-cps\-uri\ \fIuri\fR]\ \fR[\fB\-\-user\-notice\ \fItext\fR]
34 .OP \-\-outform encoding
35 .OP \-\-debug level
36 .YS
37 .
38 .SY pki\ \-\-issue
39 .BI \-\-options\~ file
40 .YS
41 .
42 .SY "pki \-\-issue"
43 .B \-h
44 |
45 .B \-\-help
46 .YS
47 .
48 .SH "DESCRIPTION"
49 .
50 This sub-command of
51 .BR pki (1)
52 is used to issue a certificate using a CA certificate and private key.
53 .
54 .SH "OPTIONS"
55 .
56 .TP
57 .B "\-h, \-\-help"
58 Print usage information with a summary of the available options.
59 .TP
60 .BI "\-v, \-\-debug " level
61 Set debug level, default: 1.
62 .TP
63 .BI "\-+, \-\-options " file
64 Read command line options from \fIfile\fR.
65 .TP
66 .BI "\-i, \-\-in " file
67 Public key or PKCS#10 certificate request file to issue. If not given the
68 key/request is read from \fISTDIN\fR.
69 .TP
70 .BI "\-t, \-\-type " type
71 Type of the input. One of \fIpub\fR (public key), \fIpriv\fR (private key),
72 \fIrsa\fR (RSA private key), \fIecdsa\fR (ECDSA private key),
73 \fIed25519\fR (Ed25519 private key) \fIbliss\fR (BLISS private key) or
74 \fIpkcs10\fR (PKCS#10 certificate request), defaults to \fIpub\fR.
75 .TP
76 .BI "\-k, \-\-cakey " file
77 CA private key file. Either this or
78 .B \-\-cakeyid
79 is required.
80 .TP
81 .BI "\-x, \-\-cakeyid " hex
82 Key ID of a CA private key on a smartcard. Either this or
83 .B \-\-cakey
84 is required.
85 .TP
86 .BI "\-c, \-\-cacert " file
87 CA certificate file. Required.
88 .TP
89 .BI "\-d, \-\-dn " subject-dn
90 Subject distinguished name (DN) of the issued certificate.
91 .TP
92 .BI "\-a, \-\-san " subjectAltName
93 subjectAltName extension to include in certificate. Can be used multiple times.
94 .TP
95 .BI "\-l, \-\-lifetime " days
96 Days the certificate is valid, default: 1095. Ignored if both
97 an absolute start and end time are given.
98 .TP
99 .BI "\-F, \-\-not-before " datetime
100 Absolute time when the validity of the certificate begins. The datetime format
101 is defined by the
102 .B \-\-dateform
103 option.
104 .TP
105 .BI "\-T, \-\-not-after " datetime
106 Absolute time when the validity of the certificate ends. The datetime format is
107 defined by the
108 .B \-\-dateform
109 option.
110 .TP
111 .BI "\-D, \-\-dateform " form
112 strptime(3) format for the
113 .B \-\-not\-before
114 and
115 .B \-\-not\-after
116 options, default:
117 .B %d.%m.%y %T
118 .TP
119 .BI "\-s, \-\-serial " hex
120 Serial number in hex. It is randomly allocated by default.
121 .TP
122 .BI "\-e, \-\-flag " flag
123 Add extendedKeyUsage flag. One of \fIserverAuth\fR, \fIclientAuth\fR,
124 \fIcrlSign\fR, or \fIocspSigning\fR. Can be used multiple times.
125 .TP
126 .BI "\-g, \-\-digest " digest
127 Digest to use for signature creation. One of \fImd5\fR, \fIsha1\fR,
128 \fIsha224\fR, \fIsha256\fR, \fIsha384\fR, or \fIsha512\fR.  The default is
129 determined based on the type and size of the signature key.
130 .TP
131 .BI "\-f, \-\-outform " encoding
132 Encoding of the created certificate file. Either \fIder\fR (ASN.1 DER) or
133 \fIpem\fR (Base64 PEM), defaults to \fIder\fR.
134 .TP
135 .BI "\-b, \-\-ca"
136 Include CA basicConstraint extension in certificate.
137 .TP
138 .BI "\-u, \-\-crl " uri
139 CRL distribution point URI to include in certificate. Can be used multiple
140 times.
141 .TP
142 .BI "\-I, \-\-crlissuer " issuer
143 Optional CRL issuer for the CRL at the preceding distribution point.
144 .TP
145 .BI "\-o, \-\-ocsp " uri
146 OCSP AuthorityInfoAccess URI to include in certificate. Can be used multiple
147 times.
148 .TP
149 .BI "\-p, \-\-pathlen " len
150 Set path length constraint.
151 .TP
152 .BI "\-B, \-\-addrblock " block
153 RFC 3779 address block to include in certificate. \fIblock\fR is either a
154 CIDR subnet (such as \fI10.0.0.0/8\fR) or an arbitrary address range
155 (\fI192.168.1.7-192.168.1.13\fR). Can be repeated to include multiple blocks.
156 Please note that the supplied blocks are included in the certificate as is,
157 so for standards compliance, multiple blocks must be supplied in correct
158 order and adjacent blocks must be combined. Refer to RFC 3779 for details.
159 .TP
160 .BI "\-n, \-\-nc-permitted " name
161 Add permitted NameConstraint extension to certificate. For DNS or email
162 constraints, the identity type is not always detectable by the given name. Use
163 the
164 .B dns:
165 or
166 .B email:
167 prefix to force a constraint type.
168 .TP
169 .BI "\-N, \-\-nc-excluded " name
170 Add excluded NameConstraint extension to certificate. For DNS or email
171 constraints, the identity type is not always detectable by the given name. Use
172 the
173 .B dns:
174 or
175 .B email:
176 prefix to force a constraint type.
177 .TP
178 .BI "\-M, \-\-policy-mapping " issuer-oid:subject-oid
179 Add policyMapping from issuer to subject OID.
180 .TP
181 .BI "\-E, \-\-policy-explicit " len
182 Add requireExplicitPolicy constraint.
183 .TP
184 .BI "\-H, \-\-policy-inhibit " len
185 Add inhibitPolicyMapping constraint.
186 .TP
187 .BI "\-A, \-\-policy-any " len
188 Add inhibitAnyPolicy constraint.
189 .PP
190 .SS "Certificate Policy"
191 Multiple certificatePolicy extensions can be added. Each with the following
192 information:
193 .TP
194 .BI "\-P, \-\-cert-policy " oid
195 OID to include in certificatePolicy extension. Required.
196 .TP
197 .BI "\-C, \-\-cps-uri " uri
198 Certification Practice statement URI for certificatePolicy.
199 .TP
200 .BI "\-U, \-\-user-notice " text
201 User notice for certificatePolicy.
202 .
203 .SH "EXAMPLES"
204 .
205 To save repetitive typing, command line options can be stored in files.
206 Lets assume
207 .I pki.opt
208 contains the following contents:
209 .PP
210 .EX
211   --cacert ca_cert.der --cakey ca_key.der --digest sha256
212   --flag serverAuth --lifetime 1460 --type pkcs10
213 .EE
214 .PP
215 Then the following command can be used to issue a certificate based on a
216 given PKCS#10 certificate request and the options above:
217 .PP
218 .EX
219   pki --issue --options pki.opt --in req.der > cert.der
220 .EE
221 .PP
222 .
223 .SH "SEE ALSO"
224 .
225 .BR pki (1)