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