secure/usr.bin/openssl/man/pkcs8.1

   1 .rn '' }`
   2 ''' $RCSfile$$Revision$$Date$
   3 '''
   4 ''' $Log$
   5 '''
   6 .de Sh
   7 .br
   8 .if t .Sp
   9 .ne 5
  10 .PP
  11 \fB\\$1\fR
  12 .PP
  13 ..
  14 .de Sp
  15 .if t .sp .5v
  16 .if n .sp
  17 ..
  18 .de Ip
  19 .br
  20 .ie \\n(.$>=3 .ne \\$3
  21 .el .ne 3
  22 .IP "\\$1" \\$2
  23 ..
  24 .de Vb
  25 .ft CW
  26 .nf
  27 .ne \\$1
  28 ..
  29 .de Ve
  30 .ft R
  31
  32 .fi
  33 ..
  34 '''
  35 '''
  36 '''     Set up \*(-- to give an unbreakable dash;
  37 '''     string Tr holds user defined translation string.
  38 '''     Bell System Logo is used as a dummy character.
  39 '''
  40 .tr \(*W-|\(bv\*(Tr
  41 .ie n \{\
  42 .ds -- \(*W-
  43 .ds PI pi
  44 .if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  45 .if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
  46 .ds L" ""
  47 .ds R" ""
  48 '''   \*(M", \*(S", \*(N" and \*(T" are the equivalent of
  49 '''   \*(L" and \*(R", except that they are used on ".xx" lines,
  50 '''   such as .IP and .SH, which do another additional levels of
  51 '''   double-quote interpretation
  52 .ds M" """
  53 .ds S" """
  54 .ds N" """""
  55 .ds T" """""
  56 .ds L' '
  57 .ds R' '
  58 .ds M' '
  59 .ds S' '
  60 .ds N' '
  61 .ds T' '
  62 'br\}
  63 .el\{\
  64 .ds -- \(em\|
  65 .tr \*(Tr
  66 .ds L" ``
  67 .ds R" ''
  68 .ds M" ``
  69 .ds S" ''
  70 .ds N" ``
  71 .ds T" ''
  72 .ds L' `
  73 .ds R' '
  74 .ds M' `
  75 .ds S' '
  76 .ds N' `
  77 .ds T' '
  78 .ds PI \(*p
  79 'br\}
  80 .\"     If the F register is turned on, we'll generate
  81 .\"     index entries out stderr for the following things:
  82 .\"             TH      Title
  83 .\"             SH      Header
  84 .\"             Sh      Subsection
  85 .\"             Ip      Item
  86 .\"             X<>     Xref  (embedded
  87 .\"     Of course, you have to process the output yourself
  88 .\"     in some meaninful fashion.
  89 .if \nF \{
  90 .de IX
  91 .tm Index:\\$1\t\\n%\t"\\$2"
  92 ..
  93 .nr % 0
  94 .rr F
  95 .\}
  96 .TH PKCS8 1 "0.9.7d" "2/Sep/2004" "OpenSSL"
  97 .UC
  98 .if n .hy 0
  99 .if n .na
 100 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
 101 .de CQ          \" put $1 in typewriter font
 102 .ft CW
 103 'if n "\c
 104 'if t \\&\\$1\c
 105 'if n \\&\\$1\c
 106 'if n \&"
 107 \\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
 108 '.ft R
 109 ..
 110 .\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
 111 .       \" AM - accent mark definitions
 112 .bd B 3
 113 .       \" fudge factors for nroff and troff
 114 .if n \{\
 115 .       ds #H 0
 116 .       ds #V .8m
 117 .       ds #F .3m
 118 .       ds #[ \f1
 119 .       ds #] \fP
 120 .\}
 121 .if t \{\
 122 .       ds #H ((1u-(\\\\n(.fu%2u))*.13m)
 123 .       ds #V .6m
 124 .       ds #F 0
 125 .       ds #[ \&
 126 .       ds #] \&
 127 .\}
 128 .       \" simple accents for nroff and troff
 129 .if n \{\
 130 .       ds ' \&
 131 .       ds ` \&
 132 .       ds ^ \&
 133 .       ds , \&
 134 .       ds ~ ~
 135 .       ds ? ?
 136 .       ds ! !
 137 .       ds /
 138 .       ds q
 139 .\}
 140 .if t \{\
 141 .       ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 142 .       ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 143 .       ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 144 .       ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 145 .       ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 146 .       ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
 147 .       ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
 148 .       ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 149 .       ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
 150 .\}
 151 .       \" troff and (daisy-wheel) nroff accents
 152 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 153 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 154 .ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
 155 .ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
 156 .ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
 157 .ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
 158 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 159 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 160 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 161 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 162 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 163 .ds ae a\h'-(\w'a'u*4/10)'e
 164 .ds Ae A\h'-(\w'A'u*4/10)'E
 165 .ds oe o\h'-(\w'o'u*4/10)'e
 166 .ds Oe O\h'-(\w'O'u*4/10)'E
 167 .       \" corrections for vroff
 168 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 169 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 170 .       \" for low resolution devices (crt and lpr)
 171 .if \n(.H>23 .if \n(.V>19 \
 172 \{\
 173 .       ds : e
 174 .       ds 8 ss
 175 .       ds v \h'-1'\o'\(aa\(ga'
 176 .       ds _ \h'-1'^
 177 .       ds . \h'-1'.
 178 .       ds 3 3
 179 .       ds o a
 180 .       ds d- d\h'-1'\(ga
 181 .       ds D- D\h'-1'\(hy
 182 .       ds th \o'bp'
 183 .       ds Th \o'LP'
 184 .       ds ae ae
 185 .       ds Ae AE
 186 .       ds oe oe
 187 .       ds Oe OE
 188 .\}
 189 .rm #[ #] #H #V #F C
 190 .SH "NAME"
 191 pkcs8 \- PKCS#8 format private key conversion tool
 192 .SH "SYNOPSIS"
 193 \fBopenssl\fR \fBpkcs8\fR
 194 [\fB\-topk8\fR]
 195 [\fB\-inform PEM|DER\fR]
 196 [\fB\-outform PEM|DER\fR]
 197 [\fB\-in filename\fR]
 198 [\fB\-passin arg\fR]
 199 [\fB\-out filename\fR]
 200 [\fB\-passout arg\fR]
 201 [\fB\-noiter\fR]
 202 [\fB\-nocrypt\fR]
 203 [\fB\-nooct\fR]
 204 [\fB\-embed\fR]
 205 [\fB\-nsdb\fR]
 206 [\fB\-v2 alg\fR]
 207 [\fB\-v1 alg\fR]
 208 [\fB\-engine id\fR]
 209 .SH "DESCRIPTION"
 210 The \fBpkcs8\fR command processes private keys in PKCS#8 format. It can handle
 211 both unencrypted PKCS#8 PrivateKeyInfo format and EncryptedPrivateKeyInfo
 212 format with a variety of PKCS#5 (v1.5 and v2.0) and PKCS#12 algorithms.
 213 .SH "COMMAND OPTIONS"
 214 .Ip "\fB\-topk8\fR" 4
 215 Normally a \s-1PKCS\s0#8 private key is expected on input and a traditional format
 216 private key will be written. With the \fB\-topk8\fR option the situation is
 217 reversed: it reads a traditional format private key and writes a \s-1PKCS\s0#8
 218 format key.
 219 .Ip "\fB\-inform \s-1DER\s0|\s-1PEM\s0\fR" 4
 220 This specifies the input format. If a \s-1PKCS\s0#8 format key is expected on input
 221 then either a \fB\s-1DER\s0\fR or \fB\s-1PEM\s0\fR encoded version of a \s-1PKCS\s0#8 key will be
 222 expected. Otherwise the \fB\s-1DER\s0\fR or \fB\s-1PEM\s0\fR format of the traditional format
 223 private key is used.
 224 .Ip "\fB\-outform \s-1DER\s0|\s-1PEM\s0\fR" 4
 225 This specifies the output format, the options have the same meaning as the
 226 \fB\-inform\fR option.
 227 .Ip "\fB\-in filename\fR" 4
 228 This specifies the input filename to read a key from or standard input if this
 229 option is not specified. If the key is encrypted a pass phrase will be
 230 prompted for.
 231 .Ip "\fB\-passin arg\fR" 4
 232 the input file password source. For more information about the format of \fBarg\fR
 233 see the \fB\s-1PASS\s0 \s-1PHRASE\s0 \s-1ARGUMENTS\s0\fR section in openssl(1).
 234 .Ip "\fB\-out filename\fR" 4
 235 This specifies the output filename to write a key to or standard output by
 236 default. If any encryption options are set then a pass phrase will be
 237 prompted for. The output filename should \fBnot\fR be the same as the input
 238 filename.
 239 .Ip "\fB\-passout arg\fR" 4
 240 the output file password source. For more information about the format of \fBarg\fR
 241 see the \fB\s-1PASS\s0 \s-1PHRASE\s0 \s-1ARGUMENTS\s0\fR section in openssl(1).
 242 .Ip "\fB\-nocrypt\fR" 4
 243 \s-1PKCS\s0#8 keys generated or input are normally \s-1PKCS\s0#8 EncryptedPrivateKeyInfo
 244 structures using an appropriate password based encryption algorithm. With
 245 this option an unencrypted PrivateKeyInfo structure is expected or output.
 246 This option does not encrypt private keys at all and should only be used
 247 when absolutely necessary. Certain software such as some versions of Java
 248 code signing software used unencrypted private keys.
 249 .Ip "\fB\-nooct\fR" 4
 250 This option generates \s-1RSA\s0 private keys in a broken format that some software
 251 uses. Specifically the private key should be enclosed in a \s-1OCTET\s0 \s-1STRING\s0
 252 but some software just includes the structure itself without the
 253 surrounding \s-1OCTET\s0 \s-1STRING\s0.
 254 .Ip "\fB\-embed\fR" 4
 255 This option generates \s-1DSA\s0 keys in a broken format. The \s-1DSA\s0 parameters are
 256 embedded inside the PrivateKey structure. In this form the \s-1OCTET\s0 \s-1STRING\s0
 257 contains an \s-1ASN1\s0 \s-1SEQUENCE\s0 consisting of two structures: a \s-1SEQUENCE\s0 containing
 258 the parameters and an \s-1ASN1\s0 \s-1INTEGER\s0 containing the private key.
 259 .Ip "\fB\-nsdb\fR" 4
 260 This option generates \s-1DSA\s0 keys in a broken format compatible with Netscape
 261 private key databases. The PrivateKey contains a \s-1SEQUENCE\s0 consisting of
 262 the public and private keys respectively.
 263 .Ip "\fB\-v2 alg\fR" 4
 264 This option enables the use of \s-1PKCS\s0#5 v2.0 algorithms. Normally \s-1PKCS\s0#8
 265 private keys are encrypted with the password based encryption algorithm
 266 called \fBpbeWithMD5AndDES\-\s-1CBC\s0\fR this uses 56 bit \s-1DES\s0 encryption but it
 267 was the strongest encryption algorithm supported in \s-1PKCS\s0#5 v1.5. Using
 268 the \fB\-v2\fR option \s-1PKCS\s0#5 v2.0 algorithms are used which can use any
 269 encryption algorithm such as 168 bit triple \s-1DES\s0 or 128 bit \s-1RC2\s0 however
 270 not many implementations support \s-1PKCS\s0#5 v2.0 yet. If you are just using
 271 private keys with OpenSSL then this doesn't matter.
 272 .Sp
 273 The \fBalg\fR argument is the encryption algorithm to use, valid values include
 274 \fBdes\fR, \fBdes3\fR and \fBrc2\fR. It is recommended that \fBdes3\fR is used.
 275 .Ip "\fB\-v1 alg\fR" 4
 276 This option specifies a \s-1PKCS\s0#5 v1.5 or \s-1PKCS\s0#12 algorithm to use. A complete
 277 list of possible algorithms is included below.
 278 .Ip "\fB\-engine id\fR" 4
 279 specifying an engine (by it's unique \fBid\fR string) will cause \fBreq\fR
 280 to attempt to obtain a functional reference to the specified engine,
 281 thus initialising it if needed. The engine will then be set as the default
 282 for all available algorithms.
 283 .SH "NOTES"
 284 The encrypted form of a PEM encode PKCS#8 files uses the following
 285 headers and footers:
 286 .PP
 287 .Vb 2
 288 \& -----BEGIN ENCRYPTED PRIVATE KEY-----
 289 \& -----END ENCRYPTED PRIVATE KEY-----
 290 .Ve
 291 The unencrypted form uses:
 292 .PP
 293 .Vb 2
 294 \& -----BEGIN PRIVATE KEY-----
 295 \& -----END PRIVATE KEY-----
 296 .Ve
 297 Private keys encrypted using PKCS#5 v2.0 algorithms and high iteration
 298 counts are more secure that those encrypted using the traditional
 299 SSLeay compatible formats. So if additional security is considered
 300 important the keys should be converted.
 301 .PP
 302 The default encryption is only 56 bits because this is the encryption
 303 that most current implementations of PKCS#8 will support.
 304 .PP
 305 Some software may use PKCS#12 password based encryption algorithms
 306 with PKCS#8 format private keys: these are handled automatically
 307 but there is no option to produce them.
 308 .PP
 309 It is possible to write out DER encoded encrypted private keys in
 310 PKCS#8 format because the encryption details are included at an ASN1
 311 level whereas the traditional format includes them at a PEM level.
 312 .SH "PKCS#5 v1.5 and PKCS#12 algorithms."
 313 Various algorithms can be used with the \fB\-v1\fR command line option,
 314 including PKCS#5 v1.5 and PKCS#12. These are described in more detail
 315 below.
 316 .Ip "\fB\s-1PBE\s0\-\s-1MD2-DES\s0 \s-1PBE\s0\-\s-1MD5-DES\s0\fR" 4
 317 These algorithms were included in the original \s-1PKCS\s0#5 v1.5 specification.
 318 They only offer 56 bits of protection since they both use \s-1DES\s0.
 319 .Ip "\fB\s-1PBE\s0\-\s-1SHA1-RC2-64\s0 \s-1PBE\s0\-\s-1MD2-RC2-64\s0 \s-1PBE\s0\-\s-1MD5-RC2-64\s0 \s-1PBE\s0\-\s-1SHA1-DES\s0\fR" 4
 320 These algorithms are not mentioned in the original \s-1PKCS\s0#5 v1.5 specification
 321 but they use the same key derivation algorithm and are supported by some
 322 software. They are mentioned in \s-1PKCS\s0#5 v2.0. They use either 64 bit \s-1RC2\s0 or
 323 56 bit \s-1DES\s0.
 324 .Ip "\fB\s-1PBE\s0\-\s-1SHA1-RC4-128\s0 \s-1PBE\s0\-\s-1SHA1-RC4-40\s0 \s-1PBE\s0\-\s-1SHA1-3DES\s0 \s-1PBE\s0\-\s-1SHA1-2DES\s0 \s-1PBE\s0\-\s-1SHA1-RC2-128\s0 \s-1PBE\s0\-\s-1SHA1-RC2-40\s0\fR" 4
 325 These algorithms use the \s-1PKCS\s0#12 password based encryption algorithm and
 326 allow strong encryption algorithms like triple \s-1DES\s0 or 128 bit \s-1RC2\s0 to be used.
 327 .SH "EXAMPLES"
 328 Convert a private from traditional to PKCS#5 v2.0 format using triple
 329 DES:
 330 .PP
 331 .Vb 1
 332 \& openssl pkcs8 -in key.pem -topk8 -v2 des3 -out enckey.pem
 333 .Ve
 334 Convert a private key to PKCS#8 using a PKCS#5 1.5 compatible algorithm
 335 (DES):
 336 .PP
 337 .Vb 1
 338 \& openssl pkcs8 -in key.pem -topk8 -out enckey.pem
 339 .Ve
 340 Convert a private key to PKCS#8 using a PKCS#12 compatible algorithm
 341 (3DES):
 342 .PP
 343 .Vb 1
 344 \& openssl pkcs8 -in key.pem -topk8 -out enckey.pem -v1 PBE-SHA1-3DES
 345 .Ve
 346 Read a DER unencrypted PKCS#8 format private key:
 347 .PP
 348 .Vb 1
 349 \& openssl pkcs8 -inform DER -nocrypt -in key.der -out key.pem
 350 .Ve
 351 Convert a private key from any PKCS#8 format to traditional format:
 352 .PP
 353 .Vb 1
 354 \& openssl pkcs8 -in pk8.pem -out key.pem
 355 .Ve
 356 .SH "STANDARDS"
 357 Test vectors from this PKCS#5 v2.0 implementation were posted to the
 358 pkcs-tng mailing list using triple DES, DES and RC2 with high iteration
 359 counts, several people confirmed that they could decrypt the private
 360 keys produced and Therefore it can be assumed that the PKCS#5 v2.0
 361 implementation is reasonably accurate at least as far as these
 362 algorithms are concerned.
 363 .PP
 364 The format of PKCS#8 DSA (and other) private keys is not well documented:
 365 it is hidden away in PKCS#11 v2.01, section 11.9. OpenSSL's default DSA
 366 PKCS#8 private key format complies with this standard.
 367 .SH "BUGS"
 368 There should be an option that prints out the encryption algorithm
 369 in use and other details such as the iteration count.
 370 .PP
 371 PKCS#8 using triple DES and PKCS#5 v2.0 should be the default private
 372 key format for OpenSSL: for compatibility several of the utilities use
 373 the old format at present.
 374 .SH "SEE ALSO"
 375 dsa(1), rsa(1), genrsa(1),
 376 gendsa(1)
 377
 378 .rn }` ''
 379 .IX Title "PKCS8 1"
 380 .IX Name "pkcs8 - PKCS#8 format private key conversion tool"
 381
 382 .IX Header "NAME"
 383
 384 .IX Header "SYNOPSIS"
 385
 386 .IX Header "DESCRIPTION"
 387
 388 .IX Header "COMMAND OPTIONS"
 389
 390 .IX Item "\fB\-topk8\fR"
 391
 392 .IX Item "\fB\-inform \s-1DER\s0|\s-1PEM\s0\fR"
 393
 394 .IX Item "\fB\-outform \s-1DER\s0|\s-1PEM\s0\fR"
 395
 396 .IX Item "\fB\-in filename\fR"
 397
 398 .IX Item "\fB\-passin arg\fR"
 399
 400 .IX Item "\fB\-out filename\fR"
 401
 402 .IX Item "\fB\-passout arg\fR"
 403
 404 .IX Item "\fB\-nocrypt\fR"
 405
 406 .IX Item "\fB\-nooct\fR"
 407
 408 .IX Item "\fB\-embed\fR"
 409
 410 .IX Item "\fB\-nsdb\fR"
 411
 412 .IX Item "\fB\-v2 alg\fR"
 413
 414 .IX Item "\fB\-v1 alg\fR"
 415
 416 .IX Item "\fB\-engine id\fR"
 417
 418 .IX Header "NOTES"
 419
 420 .IX Header "PKCS#5 v1.5 and PKCS#12 algorithms."
 421
 422 .IX Item "\fB\s-1PBE\s0\-\s-1MD2-DES\s0 \s-1PBE\s0\-\s-1MD5-DES\s0\fR"
 423
 424 .IX Item "\fB\s-1PBE\s0\-\s-1SHA1-RC2-64\s0 \s-1PBE\s0\-\s-1MD2-RC2-64\s0 \s-1PBE\s0\-\s-1MD5-RC2-64\s0 \s-1PBE\s0\-\s-1SHA1-DES\s0\fR"
 425
 426 .IX Item "\fB\s-1PBE\s0\-\s-1SHA1-RC4-128\s0 \s-1PBE\s0\-\s-1SHA1-RC4-40\s0 \s-1PBE\s0\-\s-1SHA1-3DES\s0 \s-1PBE\s0\-\s-1SHA1-2DES\s0 \s-1PBE\s0\-\s-1SHA1-RC2-128\s0 \s-1PBE\s0\-\s-1SHA1-RC2-40\s0\fR"
 427
 428 .IX Header "EXAMPLES"
 429
 430 .IX Header "STANDARDS"
 431
 432 .IX Header "BUGS"
 433
 434 .IX Header "SEE ALSO"
 435