doc/apps/ec.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 ec - EC key processing
   6
   7 =head1 SYNOPSIS
   8
   9 B<openssl> B<ec>
  10 [B<-inform PEM|DER>]
  11 [B<-outform PEM|DER>]
  12 [B<-in filename>]
  13 [B<-passin arg>]
  14 [B<-out filename>]
  15 [B<-passout arg>]
  16 [B<-des>]
  17 [B<-des3>]
  18 [B<-idea>]
  19 [B<-text>]
  20 [B<-noout>]
  21 [B<-param_out>]
  22 [B<-pubin>]
  23 [B<-pubout>]
  24 [B<-conv_form arg>]
  25 [B<-param_enc arg>]
  26 [B<-no_public>]
  27 [B<-check>]
  28 [B<-engine id>]
  29
  30 =head1 DESCRIPTION
  31
  32 The B<ec> command processes EC keys. They can be converted between various
  33 forms and their components printed out. B<Note> OpenSSL uses the
  34 private key format specified in 'SEC 1: Elliptic Curve Cryptography'
  35 (http://www.secg.org/). To convert a OpenSSL EC private key into the
  36 PKCS#8 private key format use the B<pkcs8> command.
  37
  38 =head1 COMMAND OPTIONS
  39
  40 =over 4
  41
  42 =item B<-inform DER|PEM>
  43
  44 This specifies the input format. The B<DER> option with a private key uses
  45 an ASN.1 DER encoded SEC1 private key. When used with a public key it
  46 uses the SubjectPublicKeyInfo structure as specified in RFC 3280.
  47 The B<PEM> form is the default format: it consists of the B<DER> format base64
  48 encoded with additional header and footer lines. In the case of a private key
  49 PKCS#8 format is also accepted.
  50
  51 =item B<-outform DER|PEM>
  52
  53 This specifies the output format, the options have the same meaning as the
  54 B<-inform> option.
  55
  56 =item B<-in filename>
  57
  58 This specifies the input filename to read a key from or standard input if this
  59 option is not specified. If the key is encrypted a pass phrase will be
  60 prompted for.
  61
  62 =item B<-passin arg>
  63
  64 the input file password source. For more information about the format of B<arg>
  65 see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
  66
  67 =item B<-out filename>
  68
  69 This specifies the output filename to write a key to or standard output by
  70 is not specified. If any encryption options are set then a pass phrase will be
  71 prompted for. The output filename should B<not> be the same as the input
  72 filename.
  73
  74 =item B<-passout arg>
  75
  76 the output file password source. For more information about the format of B<arg>
  77 see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
  78
  79 =item B<-des|-des3|-idea>
  80
  81 These options encrypt the private key with the DES, triple DES, IDEA or
  82 any other cipher supported by OpenSSL before outputting it. A pass phrase is
  83 prompted for.
  84 If none of these options is specified the key is written in plain text. This
  85 means that using the B<ec> utility to read in an encrypted key with no
  86 encryption option can be used to remove the pass phrase from a key, or by
  87 setting the encryption options it can be use to add or change the pass phrase.
  88 These options can only be used with PEM format output files.
  89
  90 =item B<-text>
  91
  92 prints out the public, private key components and parameters.
  93
  94 =item B<-noout>
  95
  96 this option prevents output of the encoded version of the key.
  97
  98 =item B<-modulus>
  99
 100 this option prints out the value of the public key component of the key.
 101
 102 =item B<-pubin>
 103
 104 by default a private key is read from the input file: with this option a
 105 public key is read instead.
 106
 107 =item B<-pubout>
 108
 109 by default a private key is output. With this option a public
 110 key will be output instead. This option is automatically set if the input is
 111 a public key.
 112
 113 =item B<-conv_form>
 114
 115 This specifies how the points on the elliptic curve are converted
 116 into octet strings. Possible values are: B<compressed> (the default
 117 value), B<uncompressed> and B<hybrid>. For more information regarding
 118 the point conversion forms please read the X9.62 standard.
 119 B<Note> Due to patent issues the B<compressed> option is disabled
 120 by default for binary curves and can be enabled by defining
 121 the preprocessor macro B<OPENSSL_EC_BIN_PT_COMP> at compile time.
 122
 123 =item B<-param_enc arg>
 124
 125 This specifies how the elliptic curve parameters are encoded.
 126 Possible value are: B<named_curve>, i.e. the ec parameters are
 127 specified by a OID, or B<explicit> where the ec parameters are
 128 explicitly given (see RFC 3279 for the definition of the
 129 EC parameters structures). The default value is B<named_curve>.
 130 B<Note> the B<implicitlyCA> alternative ,as specified in RFC 3279,
 131 is currently not implemented in OpenSSL.
 132
 133 =item B<-no_public>
 134
 135 This option omits the public key components from the private key output.
 136
 137 =item B<-check>
 138
 139 this option checks the consistency of an EC private or public key.
 140
 141 =item B<-engine id>
 142
 143 specifying an engine (by its unique B<id> string) will cause B<ec>
 144 to attempt to obtain a functional reference to the specified engine,
 145 thus initialising it if needed. The engine will then be set as the default
 146 for all available algorithms.
 147
 148 =back
 149
 150 =head1 NOTES
 151
 152 The PEM private key format uses the header and footer lines:
 153
 154  -----BEGIN EC PRIVATE KEY-----
 155  -----END EC PRIVATE KEY-----
 156
 157 The PEM public key format uses the header and footer lines:
 158
 159  -----BEGIN PUBLIC KEY-----
 160  -----END PUBLIC KEY-----
 161
 162 =head1 EXAMPLES
 163
 164 To encrypt a private key using triple DES:
 165
 166  openssl ec -in key.pem -des3 -out keyout.pem
 167
 168 To convert a private key from PEM to DER format:
 169
 170  openssl ec -in key.pem -outform DER -out keyout.der
 171
 172 To print out the components of a private key to standard output:
 173
 174  openssl ec -in key.pem -text -noout
 175
 176 To just output the public part of a private key:
 177
 178  openssl ec -in key.pem -pubout -out pubkey.pem
 179
 180 To change the parameters encoding to B<explicit>:
 181
 182  openssl ec -in key.pem -param_enc explicit -out keyout.pem
 183
 184 To change the point conversion form to B<compressed>:
 185
 186  openssl ec -in key.pem -conv_form compressed -out keyout.pem
 187
 188 =head1 SEE ALSO
 189
 190 L<ecparam(1)>, L<dsa(1)>, L<rsa(1)>
 191
 192 =cut