From 9d1ebeea468e9820d0ac79a5d9c387ed7d40e0ca Mon Sep 17 00:00:00 2001 From: jmc Date: Sun, 28 Aug 2016 19:34:15 +0000 Subject: [PATCH] shorten the rsa text; of note, i've also reduced the description for -inform/-outform/-text and removed the oft-repeated header/footer blurb; --- usr.bin/openssl/openssl.1 | 322 ++++++-------------------------------- 1 file changed, 44 insertions(+), 278 deletions(-) diff --git a/usr.bin/openssl/openssl.1 b/usr.bin/openssl/openssl.1 index 7a416e74f2e..f804dcef830 100644 --- a/usr.bin/openssl/openssl.1 +++ b/usr.bin/openssl/openssl.1 @@ -1,4 +1,4 @@ -.\" $OpenBSD: openssl.1,v 1.63 2016/08/27 20:43:05 jmc Exp $ +.\" $OpenBSD: openssl.1,v 1.64 2016/08/28 19:34:15 jmc Exp $ .\" ==================================================================== .\" Copyright (c) 1998-2002 The OpenSSL Project. All rights reserved. .\" @@ -112,7 +112,7 @@ .\" .\" OPENSSL .\" -.Dd $Mdocdate: August 27 2016 $ +.Dd $Mdocdate: August 28 2016 $ .Dt OPENSSL 1 .Os .Sh NAME @@ -971,11 +971,6 @@ Cipher suites using SHA1. The .Nm crl command processes CRL files in DER or PEM format. -The PEM CRL format uses the header and footer lines: -.Bd -unfilled -offset indent ------BEGIN X509 CRL----- ------END X509 CRL----- -.Ed .Pp The options are as follows: .Bl -tag -width Ds @@ -1015,7 +1010,7 @@ The output file to write to, or standard output if not specified. .It Fl outform Cm der | pem The output format. .It Fl text -Print the CRL in text form. +Print the CRL in plain text. .El .Sh CRL2PKCS7 .nr nS 1 @@ -1048,7 +1043,7 @@ Read the CRL from .Ar file , or standard input if not specified. .It Fl inform Cm der | pem -Specify the CRL input format. +The input format. .It Fl nocrl Normally, a CRL is included in the output file. With this option, no CRL is @@ -1058,7 +1053,7 @@ Write the PKCS#7 structure to .Ar file , or standard output if not specified. .It Fl outform Cm der | pem -Specify the PKCS#7 structure output format. +The output format. .El .Sh DGST .nr nS 1 @@ -1227,17 +1222,6 @@ The input file to read from, or standard input if not specified. .It Fl inform Cm der | pem The input format. -.Cm der -uses an ASN1 DER-encoded form compatible with the PKCS#3 DHparameter -structure. -.Cm pem -is the default: -it consists of the DER format base64-encoded with -additional header and footer lines: -.Bd -unfilled -offset indent ------BEGIN DH PARAMETERS----- ------END DH PARAMETERS----- -.Ed .It Fl noout Do not output the encoded version of the parameters. .It Fl out Ar file @@ -1246,7 +1230,7 @@ or standard output if not specified. .It Fl outform Cm der | pem The output format. .It Fl text -Print the DH parameters in human readable form. +Print the DH parameters in plain text. .It Ar numbits Generate a parameter set of size .Ar numbits . @@ -1288,18 +1272,6 @@ newer applications should use the more secure PKCS#8 format using the .Nm pkcs8 command. .Pp -The PEM private key format uses the header and footer lines: -.Bd -unfilled -offset indent ------BEGIN DSA PRIVATE KEY----- ------END DSA PRIVATE KEY----- -.Ed -.Pp -The PEM public key format uses the header and footer lines: -.Bd -unfilled -offset indent ------BEGIN PUBLIC KEY----- ------END PUBLIC KEY----- -.Ed -.Pp The options are as follows: .Bl -tag -width Ds .It Xo @@ -1323,21 +1295,6 @@ or standard input if not specified. If the key is encrypted, a pass phrase will be prompted for. .It Fl inform Cm der | pem The input format. -.Cm der -with a private key uses an ASN1 DER-encoded form of an ASN.1 -SEQUENCE consisting of the values of version -.Pq currently zero , -P, Q, G, -and the public and private key components, respectively, as ASN.1 INTEGERs. -When used with a public key it uses a -.Em SubjectPublicKeyInfo -structure: it is an error if the key is not DSA. -.Pp -.Cm pem -is the default format: -it consists of the DER format base64-encoded with additional header and footer -lines. -In the case of a private key, PKCS#8 format is also accepted. .It Fl modulus Print the value of the public key component of the key. .It Fl noout @@ -1359,7 +1316,7 @@ Read in a public key, not a private key. Output a public key, not a private key. Automatically set if the input is a public key. .It Fl text -Print the public/private key components and parameters. +Print the public/private key in plain text. .El .Sh DSAPARAM .nr nS 1 @@ -1379,12 +1336,6 @@ The .Nm dsaparam command is used to manipulate or generate DSA parameter files. .Pp -PEM format DSA parameters use the header and footer lines: -.Bd -unfilled -offset indent ------BEGIN DSA PARAMETERS----- ------END DSA PARAMETERS----- -.Ed -.Pp The options are as follows: .Bl -tag -width Ds .It Fl C @@ -1403,14 +1354,6 @@ If the parameter is included, then this option is ignored. .It Fl inform Cm der | pem The input format. -.Cm der -uses an ASN1 DER-encoded form compatible with RFC 2459 -.Pq PKIX -DSS-Parms that is a SEQUENCE consisting of p, q and g, respectively. -.Cm pem -is the default format: -it consists of the DER format base64-encoded with additional header -and footer lines. .It Fl noout Do not output the encoded version of the parameters. .It Fl out Ar file @@ -1419,7 +1362,7 @@ or standard output if not specified. .It Fl outform Cm der | pem The output format. .It Fl text -Print the DSA parameters in human readable form. +Print the DSA parameters in plain text. .It Ar numbits Generate a parameter set of size .Ar numbits . @@ -1459,18 +1402,6 @@ EC private key into the PKCS#8 private key format use the .Nm pkcs8 command. .Pp -The PEM private key format uses the header and footer lines: -.Bd -literal -offset indent ------BEGIN EC PRIVATE KEY----- ------END EC PRIVATE KEY----- -.Ed -.Pp -The PEM public key format uses the header and footer lines: -.Bd -literal -offset indent ------BEGIN PUBLIC KEY----- ------END PUBLIC KEY----- -.Ed -.Pp The options are as follows: .Bl -tag -width Ds .It Fl conv_form Ar arg @@ -1510,17 +1441,6 @@ or standard input if not specified. If the key is encrypted a pass phrase will be prompted for. .It Fl inform Cm der | pem The input format. -.Cm der -with a private key uses -an ASN.1 DER-encoded SEC1 private key. -When used with a public key it -uses the SubjectPublicKeyInfo structure as specified in RFC 3280. -.Cm pem -is the default format: -it consists of the DER format base64-encoded -with additional header and footer lines. -In the case of a private key -PKCS#8 format is also accepted. .It Fl noout Do not output the encoded version of the key. .It Fl out Ar file @@ -1554,7 +1474,7 @@ Read in a public key, not a private key. Output a public key, not a private key. Automatically set if the input is a public key. .It Fl text -Print the public/private key components and parameters. +Print the public/private key in plain text. .El .Sh ECPARAM .nr nS 1 @@ -1583,12 +1503,6 @@ is not able to generate new groups so .Nm ecparam can only create EC parameters from known (named) curves. .Pp -PEM format EC parameters use the header and footer lines: -.Bd -literal -offset indent ------BEGIN EC PARAMETERS----- ------END EC PARAMETERS----- -.Ed -.Pp The options are as follows: .Bl -tag -width Ds .It Fl C @@ -1623,13 +1537,6 @@ The input file to read from, or standard input if not specified. .It Fl inform Cm der | pem The input format. -.Cm der -uses an ASN.1 DER-encoded -form compatible with RFC 3279 EcpkParameters. -.Cm pem -is the default format: -it consists of the DER format base64-encoded with additional -header and footer lines. .It Fl list_curves Print a list of all currently implemented EC parameter names and exit. @@ -1660,7 +1567,7 @@ Note: the alternative, as specified in RFC 3279, is currently not implemented. .It Fl text -Print the EC parameters in human readable form. +Print the EC parameters in plain text. .El .Sh ENC .nr nS 1 @@ -1986,8 +1893,7 @@ The value to use for the generator The EC curve to use. .El .It Fl text -Print an unencrypted text representation of private and public keys and -parameters along with the DER or PEM structure. +Print the private/public key in plain text. .El .Sh GENRSA .nr nS 1 @@ -2495,18 +2401,6 @@ command processes PKCS#7 files in DER or PEM format. The PKCS#7 routines only understand PKCS#7 v 1.5 as specified in RFC 2315. They cannot currently parse, for example, the new CMS as described in RFC 2630. .Pp -The PEM PKCS#7 format uses the header and footer lines: -.Bd -unfilled -offset indent ------BEGIN PKCS7----- ------END PKCS7----- -.Ed -.Pp -For compatibility with some CAs it will also accept: -.Bd -unfilled -offset indent ------BEGIN CERTIFICATE----- ------END CERTIFICATE----- -.Ed -.Pp The options are as follows: .Bl -tag -width Ds .It Fl in Ar file @@ -2514,11 +2408,6 @@ The input file to read from, or standard input if not specified. .It Fl inform Cm der | pem The input format. -.Cm der -format is a DER-encoded PKCS#7 v1.5 structure. -.Cm pem -(the default) -is a base64-encoded version of the DER form with header and footer lines. .It Fl noout Don't output the encoded version of the PKCS#7 structure (or certificates if @@ -2592,10 +2481,6 @@ or standard input if not specified. If the key is encrypted, a pass phrase will be prompted for. .It Fl inform Cm der | pem The input format. -If a PKCS#8 format key is expected on input, -then either a -DER- or PEM-encoded version of a PKCS#8 key will be expected. -Otherwise the DER or PEM format of the traditional format private key is used. .It Fl nocrypt Generate an unencrypted PrivateKeyInfo structure. This option does not encrypt private keys at all @@ -2908,8 +2793,7 @@ Read in a public key, not a private key. Output a public key, not a private key. Automatically set if the input is a public key. .It Fl text -Print out the various public or private key components in plain text -in addition to the encoded version. +Print the public/private key in plain text. .It Fl text_pub Print out only public key components even if a private key is being processed. @@ -2937,7 +2821,7 @@ Do not output the encoded version of the parameters. The output file to write to, or standard output if not specified. .It Fl text -Print the parameters in plain text, in addition to the encoded version. +Print the parameters in plain text. .El .Sh PKEYUTL .nr nS 1 @@ -3237,12 +3121,6 @@ and are not specified. .It Fl inform Cm der | pem The input format. -.Cm der -uses an ASN1 DER-encoded form compatible with the PKCS#10. -.Cm pem -is the default format: -it consists of the DER format base64-encoded with additional header and -footer lines. .It Fl key Ar keyfile The file to read the private key from. It also accepts PKCS#8 format private keys for PEM format files. @@ -3365,7 +3243,7 @@ Print the request subject (or certificate subject if .Fl x509 is specified). .It Fl text -Print the certificate request in text form. +Print the certificate request in plain text. .It Fl utf8 Interpret field values as UTF8 strings, not ASCII. .It Fl verbose @@ -3592,18 +3470,6 @@ options in the configuration file. Any additional fields will be treated as though they were a .Cm DirectoryString . .Pp -The header and footer lines in the PEM format are normally: -.Bd -unfilled -offset indent ------BEGIN CERTIFICATE REQUEST----- ------END CERTIFICATE REQUEST----- -.Ed -.Pp -Some software instead needs: -.Bd -unfilled -offset indent ------BEGIN NEW CERTIFICATE REQUEST----- ------END NEW CERTIFICATE REQUEST----- -.Ed -.Pp The following messages are frequently asked about: .Bd -unfilled -offset indent Using configuration from /some/path/openssl.cnf @@ -3633,24 +3499,17 @@ then the SET OF is missing and the encoding is technically invalid See the description .Fl asn1-kludge for more information. -.\" -.\" RSA -.\" .Sh RSA .nr nS 1 .Nm "openssl rsa" -.Bk -words -.Oo -.Fl aes128 | aes192 | aes256 | -.Fl des | des3 -.Oc +.Op Fl aes128 | aes192 | aes256 | des | des3 .Op Fl check .Op Fl in Ar file -.Op Fl inform Ar DER | NET | PEM +.Op Fl inform Cm der | net | pem .Op Fl modulus .Op Fl noout .Op Fl out Ar file -.Op Fl outform Ar DER | NET | PEM +.Op Fl outform Cm der | net | pem .Op Fl passin Ar arg .Op Fl passout Ar arg .Op Fl pubin @@ -3658,15 +3517,13 @@ for more information. .Op Fl sgckey .Op Fl text .nr nS 0 -.Ek .Pp The .Nm rsa command processes RSA keys. They can be converted between various forms and their components printed out. -.Pp -.Sy Note : -this command uses the traditional +.Nm rsa +uses the traditional .Nm SSLeay compatible format for private key encryption: newer applications should use the more secure PKCS#8 format using the @@ -3675,11 +3532,8 @@ utility. .Pp The options are as follows: .Bl -tag -width Ds -.It Xo -.Fl aes128 | aes192 | aes256 | -.Fl des | des3 -.Xc -These options encrypt the private key with the AES, DES, +.It Fl aes128 | aes192 | aes256 | des | des3 +Encrypt the private key with the AES, DES, or the triple DES ciphers, respectively, before outputting it. A pass phrase is prompted for. If none of these options are specified, the key is written in plain text. @@ -3690,128 +3544,39 @@ to remove the pass phrase from a key, or by setting the encryption options it can be used to add or change the pass phrase. These options can only be used with PEM format output files. .It Fl check -This option checks the consistency of an RSA private key. +Check the consistency of an RSA private key. .It Fl in Ar file -This specifies the input -.Ar file -to read a key from, or standard input if this -option is not specified. +The input file to read from, +or standard input if not specified. If the key is encrypted, a pass phrase will be prompted for. -.It Fl inform Ar DER | NET | PEM -This specifies the input format. -The -.Ar DER -argument -uses an ASN1 DER-encoded form compatible with the PKCS#1 -RSAPrivateKey or SubjectPublicKeyInfo format. -The -.Ar PEM -form is the default format: it consists of the DER format base64-encoded with -additional header and footer lines. -On input PKCS#8 format private keys are also accepted. -The -.Ar NET -form is a format described in the -.Sx RSA NOTES -section. +.It Fl inform Cm der | net | pem +The input format. .It Fl noout -This option prevents output of the encoded version of the key. +Do not output the encoded version of the key. .It Fl modulus -This option prints out the value of the modulus of the key. +Print the value of the modulus of the key. .It Fl out Ar file -This specifies the output -.Ar file -to write a key to, or standard output if this option is not specified. -If any encryption options are set, a pass phrase will be prompted for. -The output filename should -.Em not -be the same as the input filename. -.It Fl outform Ar DER | NET | PEM -This specifies the output format; the options have the same meaning as the -.Fl inform -option. +The output file to write to, +or standard output if not specified. +.It Fl outform Cm der | net | pem +The output format. .It Fl passin Ar arg The key password source. .It Fl passout Ar arg The output file password source. .It Fl pubin -By default, a private key is read from the input file; with this -option a public key is read instead. +Read in a public key, +not a private key. .It Fl pubout -By default, a private key is output; -with this option a public key will be output instead. -This option is automatically set if the input is a public key. +Output a public key, +not a private key. +Automatically set if the input is a public key. .It Fl sgckey -Use the modified -.Em NET -algorithm used with some versions of Microsoft IIS and SGC keys. +Use the modified NET algorithm used with some versions of Microsoft IIS +and SGC keys. .It Fl text -Prints out the various public or private key components in -plain text, in addition to the encoded version. +Print the public/private key components in plain text. .El -.Sh RSA NOTES -The PEM private key format uses the header and footer lines: -.Bd -unfilled -offset indent ------BEGIN RSA PRIVATE KEY----- ------END RSA PRIVATE KEY----- -.Ed -.Pp -The PEM public key format uses the header and footer lines: -.Bd -unfilled -offset indent ------BEGIN PUBLIC KEY----- ------END PUBLIC KEY----- -.Ed -.Pp -The -.Em NET -form is a format compatible with older Netscape servers -and Microsoft IIS .key files; this uses unsalted RC4 for its encryption. -It is not very secure and so should only be used when necessary. -.Pp -Some newer version of IIS have additional data in the exported .key files. -To use these with the -.Nm rsa -utility, view the file with a binary editor -and look for the string -.Qq private-key , -then trace back to the byte sequence 0x30, 0x82 -.Pq this is an ASN1 SEQUENCE . -Copy all the data from this point onwards to another file and use that as -the input to the -.Nm rsa -utility with the -.Fl inform Ar NET -option. -If there is an error after entering the password, try the -.Fl sgckey -option. -.Sh RSA EXAMPLES -To remove the pass phrase on an RSA private key: -.Pp -.Dl $ openssl rsa -in key.pem -out keyout.pem -.Pp -To encrypt a private key using triple DES: -.Pp -.Dl $ openssl rsa -in key.pem -des3 -out keyout.pem -.Pp -To convert a private key from PEM to DER format: -.Pp -.Dl $ openssl rsa -in key.pem -outform DER -out keyout.der -.Pp -To print out the components of a private key to standard output: -.Pp -.Dl $ openssl rsa -in key.pem -text -noout -.Pp -To just output the public part of a private key: -.Pp -.Dl $ openssl rsa -in key.pem -pubout -out pubkey.pem -.Sh RSA BUGS -The command line password arguments don't currently work with -.Em NET -format. -.Pp -There should be an option that automatically handles .key files, -without having to manually edit them. .\" .\" RSAUTL .\" @@ -7649,19 +7414,20 @@ This can be used to send the data via a pipe, for example. Read the password from standard input. .El .Pp -File formats, +Input/output formats, typically specified using .Fl inform and .Fl outform , -indicate the type of file being read from -or the file format to write. +indicate the format being read from or written to. The argument is case insensitive. .Pp .Bl -tag -width Ds -offset indent -compact .It Cm der Distinguished Encoding Rules (DER) is a binary format. +.It Cm net +Insecure legacy format. .It Cm pem Privacy Enhanced Mail (PEM) is base64-encoded. -- 2.20.1