Update files for OpenSSL-1.0.0f import.
[dragonfly.git] / secure / usr.bin / openssl / man / ec.1
CommitLineData
e3261593 1.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.19)
a561f9ff
SS
2.\"
3.\" Standard preamble:
4.\" ========================================================================
a561f9ff
SS
5.de Sp \" Vertical space (when we can't use .PP)
6.if t .sp .5v
7.if n .sp
8..
9.de Vb \" Begin verbatim text
10.ft CW
11.nf
12.ne \\$1
13..
14.de Ve \" End verbatim text
15.ft R
16.fi
17..
18.\" Set up some character translations and predefined strings. \*(-- will
19.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
e257b235
PA
20.\" double quote, and \*(R" will give a right double quote. \*(C+ will
21.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
22.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
23.\" nothing in troff, for use with C<>.
24.tr \(*W-
a561f9ff
SS
25.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
26.ie n \{\
27. ds -- \(*W-
28. ds PI pi
29. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
31. ds L" ""
32. ds R" ""
33. ds C` ""
34. ds C' ""
35'br\}
36.el\{\
37. ds -- \|\(em\|
38. ds PI \(*p
39. ds L" ``
40. ds R" ''
41'br\}
42.\"
e257b235
PA
43.\" Escape single quotes in literal strings from groff's Unicode transform.
44.ie \n(.g .ds Aq \(aq
45.el .ds Aq '
46.\"
a561f9ff 47.\" If the F register is turned on, we'll generate index entries on stderr for
01185282 48.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
a561f9ff
SS
49.\" entries marked with X<> in POD. Of course, you'll have to process the
50.\" output yourself in some meaningful fashion.
e257b235 51.ie \nF \{\
a561f9ff
SS
52. de IX
53. tm Index:\\$1\t\\n%\t"\\$2"
54..
55. nr % 0
56. rr F
57.\}
e257b235
PA
58.el \{\
59. de IX
60..
61.\}
aac4ff6f 62.\"
a561f9ff
SS
63.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
64.\" Fear. Run. Save yourself. No user-serviceable parts.
65. \" fudge factors for nroff and troff
66.if n \{\
67. ds #H 0
68. ds #V .8m
69. ds #F .3m
70. ds #[ \f1
71. ds #] \fP
72.\}
73.if t \{\
74. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
75. ds #V .6m
76. ds #F 0
77. ds #[ \&
78. ds #] \&
79.\}
80. \" simple accents for nroff and troff
81.if n \{\
82. ds ' \&
83. ds ` \&
84. ds ^ \&
85. ds , \&
86. ds ~ ~
87. ds /
88.\}
89.if t \{\
90. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
91. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
92. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
93. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
94. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
95. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
96.\}
97. \" troff and (daisy-wheel) nroff accents
98.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
99.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
100.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
101.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
102.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
103.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
104.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
105.ds ae a\h'-(\w'a'u*4/10)'e
106.ds Ae A\h'-(\w'A'u*4/10)'E
107. \" corrections for vroff
108.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
109.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
110. \" for low resolution devices (crt and lpr)
111.if \n(.H>23 .if \n(.V>19 \
112\{\
113. ds : e
114. ds 8 ss
115. ds o a
116. ds d- d\h'-1'\(ga
117. ds D- D\h'-1'\(hy
118. ds th \o'bp'
119. ds Th \o'LP'
120. ds ae ae
121. ds Ae AE
122.\}
123.rm #[ #] #H #V #F C
124.\" ========================================================================
125.\"
126.IX Title "EC 1"
e3261593 127.TH EC 1 "2012-01-04" "1.0.0f" "OpenSSL"
e257b235
PA
128.\" For nroff, turn off justification. Always turn off hyphenation; it makes
129.\" way too many mistakes in technical documents.
130.if n .ad l
131.nh
a561f9ff
SS
132.SH "NAME"
133ec \- EC key processing
134.SH "SYNOPSIS"
135.IX Header "SYNOPSIS"
136\&\fBopenssl\fR \fBec\fR
137[\fB\-inform PEM|DER\fR]
138[\fB\-outform PEM|DER\fR]
139[\fB\-in filename\fR]
140[\fB\-passin arg\fR]
141[\fB\-out filename\fR]
142[\fB\-passout arg\fR]
143[\fB\-des\fR]
144[\fB\-des3\fR]
145[\fB\-idea\fR]
146[\fB\-text\fR]
147[\fB\-noout\fR]
148[\fB\-param_out\fR]
149[\fB\-pubin\fR]
150[\fB\-pubout\fR]
151[\fB\-conv_form arg\fR]
152[\fB\-param_enc arg\fR]
153[\fB\-engine id\fR]
154.SH "DESCRIPTION"
155.IX Header "DESCRIPTION"
156The \fBec\fR command processes \s-1EC\s0 keys. They can be converted between various
157forms and their components printed out. \fBNote\fR OpenSSL uses the
158private key format specified in '\s-1SEC\s0 1: Elliptic Curve Cryptography'
159(http://www.secg.org/). To convert a OpenSSL \s-1EC\s0 private key into the
160PKCS#8 private key format use the \fBpkcs8\fR command.
161.SH "COMMAND OPTIONS"
162.IX Header "COMMAND OPTIONS"
163.IP "\fB\-inform DER|PEM\fR" 4
164.IX Item "-inform DER|PEM"
165This specifies the input format. The \fB\s-1DER\s0\fR option with a private key uses
166an \s-1ASN\s0.1 \s-1DER\s0 encoded \s-1SEC1\s0 private key. When used with a public key it
167uses the SubjectPublicKeyInfo structur as specified in \s-1RFC\s0 3280.
168The \fB\s-1PEM\s0\fR form is the default format: it consists of the \fB\s-1DER\s0\fR format base64
169encoded with additional header and footer lines. In the case of a private key
170PKCS#8 format is also accepted.
171.IP "\fB\-outform DER|PEM\fR" 4
172.IX Item "-outform DER|PEM"
173This specifies the output format, the options have the same meaning as the
174\&\fB\-inform\fR option.
175.IP "\fB\-in filename\fR" 4
176.IX Item "-in filename"
177This specifies the input filename to read a key from or standard input if this
178option is not specified. If the key is encrypted a pass phrase will be
179prompted for.
180.IP "\fB\-passin arg\fR" 4
181.IX Item "-passin arg"
182the input file password source. For more information about the format of \fBarg\fR
183see the \fB\s-1PASS\s0 \s-1PHRASE\s0 \s-1ARGUMENTS\s0\fR section in \fIopenssl\fR\|(1).
184.IP "\fB\-out filename\fR" 4
185.IX Item "-out filename"
186This specifies the output filename to write a key to or standard output by
187is not specified. If any encryption options are set then a pass phrase will be
188prompted for. The output filename should \fBnot\fR be the same as the input
189filename.
190.IP "\fB\-passout arg\fR" 4
191.IX Item "-passout arg"
192the output file password source. For more information about the format of \fBarg\fR
193see the \fB\s-1PASS\s0 \s-1PHRASE\s0 \s-1ARGUMENTS\s0\fR section in \fIopenssl\fR\|(1).
194.IP "\fB\-des|\-des3|\-idea\fR" 4
195.IX Item "-des|-des3|-idea"
196These options encrypt the private key with the \s-1DES\s0, triple \s-1DES\s0, \s-1IDEA\s0 or
197any other cipher supported by OpenSSL before outputting it. A pass phrase is
198prompted for.
199If none of these options is specified the key is written in plain text. This
200means that using the \fBec\fR utility to read in an encrypted key with no
201encryption option can be used to remove the pass phrase from a key, or by
202setting the encryption options it can be use to add or change the pass phrase.
203These options can only be used with \s-1PEM\s0 format output files.
204.IP "\fB\-text\fR" 4
205.IX Item "-text"
206prints out the public, private key components and parameters.
207.IP "\fB\-noout\fR" 4
208.IX Item "-noout"
209this option prevents output of the encoded version of the key.
210.IP "\fB\-modulus\fR" 4
211.IX Item "-modulus"
212this option prints out the value of the public key component of the key.
213.IP "\fB\-pubin\fR" 4
214.IX Item "-pubin"
215by default a private key is read from the input file: with this option a
216public key is read instead.
217.IP "\fB\-pubout\fR" 4
218.IX Item "-pubout"
219by default a private key is output. With this option a public
220key will be output instead. This option is automatically set if the input is
221a public key.
222.IP "\fB\-conv_form\fR" 4
223.IX Item "-conv_form"
224This specifies how the points on the elliptic curve are converted
225into octet strings. Possible values are: \fBcompressed\fR (the default
226value), \fBuncompressed\fR and \fBhybrid\fR. For more information regarding
227the point conversion forms please read the X9.62 standard.
228\&\fBNote\fR Due to patent issues the \fBcompressed\fR option is disabled
229by default for binary curves and can be enabled by defining
230the preprocessor macro \fB\s-1OPENSSL_EC_BIN_PT_COMP\s0\fR at compile time.
231.IP "\fB\-param_enc arg\fR" 4
232.IX Item "-param_enc arg"
233This specifies how the elliptic curve parameters are encoded.
234Possible value are: \fBnamed_curve\fR, i.e. the ec parameters are
235specified by a \s-1OID\s0, or \fBexplicit\fR where the ec parameters are
236explicitly given (see \s-1RFC\s0 3279 for the definition of the
237\&\s-1EC\s0 parameters structures). The default value is \fBnamed_curve\fR.
238\&\fBNote\fR the \fBimplicitlyCA\fR alternative ,as specified in \s-1RFC\s0 3279,
239is currently not implemented in OpenSSL.
240.IP "\fB\-engine id\fR" 4
241.IX Item "-engine id"
01185282 242specifying an engine (by its unique \fBid\fR string) will cause \fBec\fR
a561f9ff
SS
243to attempt to obtain a functional reference to the specified engine,
244thus initialising it if needed. The engine will then be set as the default
245for all available algorithms.
246.SH "NOTES"
247.IX Header "NOTES"
248The \s-1PEM\s0 private key format uses the header and footer lines:
249.PP
250.Vb 2
e257b235
PA
251\& \-\-\-\-\-BEGIN EC PRIVATE KEY\-\-\-\-\-
252\& \-\-\-\-\-END EC PRIVATE KEY\-\-\-\-\-
a561f9ff
SS
253.Ve
254.PP
255The \s-1PEM\s0 public key format uses the header and footer lines:
256.PP
257.Vb 2
e257b235
PA
258\& \-\-\-\-\-BEGIN PUBLIC KEY\-\-\-\-\-
259\& \-\-\-\-\-END PUBLIC KEY\-\-\-\-\-
a561f9ff
SS
260.Ve
261.SH "EXAMPLES"
262.IX Header "EXAMPLES"
263To encrypt a private key using triple \s-1DES:\s0
264.PP
265.Vb 1
e257b235 266\& openssl ec \-in key.pem \-des3 \-out keyout.pem
a561f9ff
SS
267.Ve
268.PP
e257b235 269To convert a private key from \s-1PEM\s0 to \s-1DER\s0 format:
a561f9ff
SS
270.PP
271.Vb 1
e257b235 272\& openssl ec \-in key.pem \-outform DER \-out keyout.der
a561f9ff
SS
273.Ve
274.PP
275To print out the components of a private key to standard output:
276.PP
277.Vb 1
e257b235 278\& openssl ec \-in key.pem \-text \-noout
a561f9ff
SS
279.Ve
280.PP
281To just output the public part of a private key:
282.PP
283.Vb 1
e257b235 284\& openssl ec \-in key.pem \-pubout \-out pubkey.pem
a561f9ff
SS
285.Ve
286.PP
287To change the parameters encoding to \fBexplicit\fR:
288.PP
289.Vb 1
e257b235 290\& openssl ec \-in key.pem \-param_enc explicit \-out keyout.pem
a561f9ff
SS
291.Ve
292.PP
293To change the point conversion form to \fBcompressed\fR:
294.PP
295.Vb 1
e257b235 296\& openssl ec \-in key.pem \-conv_form compressed \-out keyout.pem
a561f9ff
SS
297.Ve
298.SH "SEE ALSO"
299.IX Header "SEE ALSO"
300\&\fIecparam\fR\|(1), \fIdsa\fR\|(1), \fIrsa\fR\|(1)
301.SH "HISTORY"
302.IX Header "HISTORY"
303The ec command was first introduced in OpenSSL 0.9.8.
304.SH "AUTHOR"
305.IX Header "AUTHOR"
306Nils Larsch for the OpenSSL project (http://www.openssl.org).