| blob | 279d27d67efb3c23563f7b31511838ccee93e640 |
1 '\" te
2 .\" Copyright 2009, Sun Microsystems, Inc. All Rights Reserved
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced
6 .\" with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
7 .TH ELFSIGN 1 "April 9, 2016"
8 .SH NAME
9 elfsign \- sign binaries
10 .SH SYNOPSIS
11 .LP
12 .nf
13 \fB/usr/bin/elfsign\fR sign [\fB-a\fR] [\fB-v\fR] \fB-k\fR \fIprivate_key\fR \fB-c\fR \fIcertificate_file\fR
14 \fB-e\fR \fIelf_object\fR [\fB-F\fR \fIformat\fR] [file]...
15 .fi
17 .LP
18 .nf
19 \fB/usr/bin/elfsign\fR sign [\fB-a\fR] [\fB-v\fR] \fB-c\fR \fIcertificate_file\fR
20 \fB-e\fR \fIelf_object\fR \fB-T\fR \fItoken_label\fR [\fB-P\fR \fIpin_file\fR] [\fB-F\fR \fIformat\fR] [file]...
21 .fi
23 .LP
24 .nf
25 \fB/usr/bin/elfsign\fR verify [\fB-c\fR \fIcertificate_file\fR]
26 [\fB-v\fR] \fB-e\fR \fIelf_object\fR [file]...
27 .fi
29 .LP
30 .nf
31 \fB/usr/bin/elfsign\fR request \fB-r\fR \fIcertificate_request_file\fR
32 {\fB-k\fR \fIprivate_key\fR | \fB-T\fR \fItoken_label\fR}
33 .fi
35 .LP
36 .nf
37 \fB/usr/bin/elfsign\fR \fIlist\fR \fB-f\fR \fIfield\fR \fB-c\fR \fIcertificate_file\fR
38 .fi
40 .LP
41 .nf
42 \fB/usr/bin/elfsign\fR \fIlist\fR \fB-f\fR \fIfield\fR \fB-e\fR \fIelf_object\fR
43 .fi
45 .SH DESCRIPTION
46 .ne 2
47 .na
48 \fB\fBlist\fR\fR
49 .ad
50 .RS 11n
51 Lists on standard output information from a single certificate file or signed
52 elf object. The selected field appears on a single line. If the field specified
53 does not apply to the named file, the command terminates with no standard
54 output. This output of this subcommand is intended for use in scripts and by
55 other commands.
56 .RE
58 .sp
59 .ne 2
60 .na
61 \fB\fBrequest\fR\fR
62 .ad
63 .RS 11n
64 Generates a private key and a PKCS#10 certificate request. The PKCS#10
65 certificate request for use with the Solaris Cryptographic Framework. If the
66 private key is to be created in a token device, elfsign prompts for the PIN
67 required to update the token device. The PKCS#10 certificate request should be
68 sent to the email address \fIsolaris-crypto-req@sun.com\fR to obtain a
69 Certificate.
70 .sp
71 Users of \fBelfsign\fR must first generate a certificate request and obtain a
72 certificate before signing binaries for use with the Solaris Cryptographic
73 Framework.
74 .RE
76 .sp
77 .ne 2
78 .na
79 \fB\fBsign\fR\fR
80 .ad
81 .RS 11n
82 Signs the elf object, using the given private key and certificate file.
83 .RE
85 .sp
86 .ne 2
87 .na
88 \fB\fBverify\fR\fR
89 .ad
90 .RS 11n
91 Verifies an existing signed object. Uses the certificate given or searches for
92 an appropriate certificate in \fB/etc/crypto/certs\fR if \fB-c\fR is not given.
93 .RE
95 .SH OPTIONS
96 .LP
97 The following options are supported:
98 .sp
99 .ne 2
100 .na
101 \fB\fB-a\fR\fR
102 .ad
103 .sp .6
104 .RS 4n
105 Generates a signed \fBELF\fR Sign Activation (\fB\&.esa\fR) file. This option
106 is used when a cryptographic provider has nonretail export approval for
107 unrestricted use and desires retail approval by restricting which export
108 sensitive callers (for example, IPsec) can use the provider. This option
109 assumes that the provider binary has previously been signed with a restricted
110 certificate.
111 .RE
113 .sp
114 .ne 2
115 .na
116 \fB\fB-c\fR \fIcertificate_file\fR\fR
117 .ad
118 .sp .6
119 .RS 4n
120 Specifies the path to an X.509 certificate in PEM/PKCS#7 or ASN.1 BER format.
121 .RE
123 .sp
124 .ne 2
125 .na
126 \fB\fB-e\fR \fIelf_object\fR\fR
127 .ad
128 .sp .6
129 .RS 4n
130 Specifies the path to the object to be signed or verified.
131 .sp
132 The \fB-e\fR option can be specified multiple times for signing or verifying
133 multiple objects.
134 .RE
136 .sp
137 .ne 2
138 .na
139 \fB\fB-F\fR \fIformat\fR\fR
140 .ad
141 .sp .6
142 .RS 4n
143 For the \fBsign\fR subcommand, specifies the format of the signature. The valid
144 format options are
145 .sp
146 .ne 2
147 .na
148 \fB\fBrsa_md5_sha1\fR\fR
149 .ad
150 .RS 16n
151 Default format Solaris 10 and updates, The \fBrsa_md5_sha1\fR format is
152 Obsolete.
153 .RE
155 .sp
156 .ne 2
157 .na
158 \fB\fBrsa_sha1\fR\fR
159 .ad
160 .RS 16n
161 Default format for this release.
162 .RE
164 Formats other than \fBrsa_md5_sha1\fR include an informational timestamp with
165 the signature indicating when the signature was applied. This timestamp is not
166 cryptographically secure, nor is it used as part of verification.
167 .RE
169 .sp
170 .ne 2
171 .na
172 \fB\fB-f\fR \fIfield\fR\fR
173 .ad
174 .sp .6
175 .RS 4n
176 For the \fBlist\fR subcommand, specifies what field should appear in the
177 output.
178 .sp
179 The valid field specifiers for a certifiicate file are:
180 .sp
181 .ne 2
182 .na
183 \fBsubject\fR
184 .ad
185 .RS 11n
186 Subject DN (Distinguished Name)
187 .RE
189 .sp
190 .ne 2
191 .na
192 \fBissuer\fR
193 .ad
194 .RS 11n
195 Issuer DN
196 .RE
198 The valid field specifiers for an elf object are:
199 .sp
200 .ne 2
201 .na
202 \fBformat\fR
203 .ad
204 .RS 10n
205 Format of the signature
206 .RE
208 .sp
209 .ne 2
210 .na
211 \fBsigner\fR
212 .ad
213 .RS 10n
214 Subject DN of the certificate used to sign the object
215 .RE
217 .sp
218 .ne 2
219 .na
220 \fBtime\fR
221 .ad
222 .RS 10n
223 Time the signature was applied, in the locale's default format
224 .RE
226 .RE
228 .sp
229 .ne 2
230 .na
231 \fB\fB-k\fR \fIprivate_key\fR\fR
232 .ad
233 .sp .6
234 .RS 4n
235 Specifies the location of the private key file when not using a PKCS#11 token.
236 This file is an RSA Private key file in a Solaris specific format. When used
237 with the \fBrequest\fR subcommand, this is the ouput file for the newly
238 generated key.
239 .sp
240 It is an error to specify both the \fB-k\fR and \fB-T\fR options.
241 .RE
243 .sp
244 .ne 2
245 .na
246 \fB\fB-P\fR \fIpin_file\fR\fR
247 .ad
248 .sp .6
249 .RS 4n
250 Specifies the file which holds the PIN for accessing the token device. If the
251 PIN is not provided in a \fIpin_file\fR, \fBelfsign\fR prompts for the PIN.
252 .sp
253 It is an error to specify the \fB-P\fR option without the \fB-T\fR option.
254 .RE
256 .sp
257 .ne 2
258 .na
259 \fB\fB-r\fR \fIcertificate_request_file\fR\fR
260 .ad
261 .sp .6
262 .RS 4n
263 Specifies the path to the certificate request file, which is in PKCS#10 format.
264 .RE
266 .sp
267 .ne 2
268 .na
269 \fB\fB-T\fR \fItoken_label\fR\fR
270 .ad
271 .sp .6
272 .RS 4n
273 Specifies the label of the PCKS#11 token device, as provided by \fBpktool\fR,
274 which holds the private key.
275 .sp
276 It is an error to specify both the \fB-T\fR and \fB-k\fR options.
277 .RE
279 .sp
280 .ne 2
281 .na
282 \fB\fB-v\fR\fR
283 .ad
284 .sp .6
285 .RS 4n
286 Requests more detailed information. The additional output includes the signer
287 and, if the signature format contains it, the time the object was signed. This
288 is not stable parsable output.
289 .RE
291 .SH OPERANDS
292 .LP
293 The following operand is supported:
294 .sp
295 .ne 2
296 .na
297 \fB\fIfile\fR\fR
298 .ad
299 .RS 8n
300 One or more elf objects to be signed or verified. At least one elf object must
301 be specified either via the -e option or after all other options.
302 .RE
304 .SH EXAMPLES
305 .LP
306 \fBExample 1 \fRSigning an ELF Object Using a Key/Certificate in a File
307 .sp
308 .in +2
309 .nf
310 example$ elfsign sign -k myprivatekey -c mycert -e lib/libmylib.so.1
311 .fi
312 .in -2
313 .sp
315 .LP
316 \fBExample 2 \fRVerifying an \fBelf\fR Object's Signature
317 .sp
318 .in +2
319 .nf
320 example$ elfsign verify -c mycert -e lib/libmylib.so.1
321 elfsign: verification of lib/libmylib.so.1 passed
322 .fi
323 .in -2
324 .sp
326 .LP
327 \fBExample 3 \fRGenerating a Certificate Request
328 .sp
329 .in +2
330 .nf
331 example$ elfsign request -k mykey -r req.pkcs10
332 Enter Company Name / Stock Symbol or some other globally
333 unique identifier.
334 This will be the prefix of the Certificate DN: SUNW
336 The government of the United States of America restricts the export of
337 "open cryptographic interfaces", also known as "crypto-with-a-hole".
338 Due to this restriction, all providers for the Solaris cryptographic
339 framework must be signed, regardless of the country of origin.
341 The terms "retail" and "non-retail" refer to export classifications for
342 products manufactured in the USA. These terms define the portion of the
343 world where the product may be shipped.) Roughly speaking, "retail" is
344 worldwide (minus certain excluded nations) and "non-retail" is domestic
345 only (plus some highly favored nations).
346 If your provider is subject to USA export control, then you
347 must obtain an export approval (classification)
348 from the government of the USA before exporting your provider.
349 It is critical that you specify the obtained (or expected, when
350 used during development) classification to the following questions
351 so that your provider will be appropriately signed.
353 Do you have retail export approval for use without restrictions
354 based on the caller (for example, IPsec)? [Yes/No] \fBNo\fR
356 If you have non-retail export approval for unrestricted use of your
357 provider by callers, are you also planning to receive retail
358 approval by restricting which export sensitive callers
359 (for example, IPsec) may use your provider? [Yes/No] \fBNo\fR
361 [...]
362 .fi
363 .in -2
364 .sp
366 .LP
367 \fBExample 4 \fRDetermining Information About an Object
368 .sp
369 .in +2
370 .nf
371 example$ elfsign list -f format -e lib/libmylib.so.1
372 rsa_md5_sha1
374 example$ elfsign list -f signer -e lib/libmylib.so.1
375 CN=VENDOR, OU=Software Development, O=Vendor Inc.
376 .fi
377 .in -2
378 .sp
380 .SH EXIT STATUS
381 .LP
382 The following exit values are returned:
383 .sp
385 .sp
386 .TS
387 c c c
388 l l l .
389 VALUE MEANING SUBCOMMAND
390 \fB0\fR Operation successful sign/verify/request
391 \fB1\fR Invalid arguments
392 \fB2\fR Failed to verify ELF object verify
393 3 Unable to open ELF object sign/verify
394 4 Unable to load or invalid certificate sign/verify
395 5 T{
396 Unable to load private key, private key is invalid, or token label is invalid
397 T} sign
398 6 Failed to add signature sign
399 7 T{
400 Attempt to verify unsigned object or object not an ELF file
401 T} verify
402 .TE
404 .SH FILES
405 .ne 2
406 .na
407 \fB\fB/etc/crypto/certs\fR\fR
408 .ad
409 .RS 21n
410 Directory searched for the \fBverify\fR subcommand if the \fB-c\fR flag is not
411 used
412 .RE
414 .SH ATTRIBUTES
415 .LP
416 See \fBattributes\fR(5) for descriptions of the following attributes:
417 .sp
419 .sp
420 .TS
421 box;
422 c | c
423 l | l .
424 ATTRIBUTE TYPE ATTRIBUTE VALUE
425 _
426 Interface Stability See below.
427 .TE
429 .sp
430 .LP
431 The \fBelfsign\fR command and subcommands are Committed. While applications
432 should not depend on the output format of \fBelfsign\fR, the output format of
433 the \fBlist\fR subcommand is Committed.
434 .SH SEE ALSO
435 .LP
436 \fBdate\fR(1), \fBpktool\fR(1), \fBcryptoadm\fR(8), \fBlibpkcs11\fR(3LIB),
437 \fBattributes\fR(5)