diff options
author | Rich Salz <rsalz@openssl.org> | 2016-05-20 08:11:46 -0400 |
---|---|---|
committer | Rich Salz <rsalz@openssl.org> | 2016-05-20 08:11:46 -0400 |
commit | 1bc74519a2a57ef8e67484ca92890fa94d3dd66f (patch) | |
tree | e6f9e69d03548ad1e73bf805957a46dec95853b1 /doc/apps | |
parent | e990ec5234d9daad66359833c40e4536d7fce499 (diff) |
Fix nits in pod files.
Add doc-nit-check to help find future issues.
Make podchecker be almost clean.
Remove trailing whitespace.
Tab expansion
Reviewed-by: Richard Levitte <levitte@openssl.org>
Diffstat (limited to 'doc/apps')
37 files changed, 251 insertions, 265 deletions
diff --git a/doc/apps/CA.pl.pod b/doc/apps/CA.pl.pod index be56e0adf4..a84083af0b 100644 --- a/doc/apps/CA.pl.pod +++ b/doc/apps/CA.pl.pod @@ -1,4 +1,3 @@ - =pod =head1 NAME @@ -103,7 +102,7 @@ B<cessationOfOperation>, B<certificateHold>, or B<removeFromCRL>. =item B<-verify> verifies certificates against the CA certificate for "demoCA". If no certificates -are specified on the command line it tries to verify the file "newcert.pem". +are specified on the command line it tries to verify the file "newcert.pem". =item B<files> @@ -148,7 +147,7 @@ enter cacert.pem when prompted for the CA file name. Create a DSA certificate request and private key (a different set of parameters can optionally be created first): - openssl req -out newreq.pem -newkey dsa:dsap.pem + openssl req -out newreq.pem -newkey dsa:dsap.pem Sign the request: @@ -169,7 +168,7 @@ be wrong. In this case the command: perl -S CA.pl -can be used and the B<OPENSSL_CONF> environment variable changed to point to +can be used and the B<OPENSSL_CONF> environment variable changed to point to the correct path of the configuration file "openssl.cnf". The script is intended as a simple front end for the B<openssl> program for use diff --git a/doc/apps/asn1parse.pod b/doc/apps/asn1parse.pod index cd30797eb9..e231a93548 100644 --- a/doc/apps/asn1parse.pod +++ b/doc/apps/asn1parse.pod @@ -92,7 +92,7 @@ L<ASN1_generate_nconf(3)> format. If B<file> only is present then the string is obtained from the default section using the name B<asn1>. The encoded data is passed through the ASN1 parser and printed out as though it came from a file, the contents can thus be examined and written to a -file using the B<out> option. +file using the B<out> option. =item B<-strictpem> @@ -108,20 +108,20 @@ END marker in a PEM file. The output will typically contain lines like this: - 0:d=0 hl=4 l= 681 cons: SEQUENCE + 0:d=0 hl=4 l= 681 cons: SEQUENCE ..... 229:d=3 hl=3 l= 141 prim: BIT STRING - 373:d=2 hl=3 l= 162 cons: cont [ 3 ] - 376:d=3 hl=3 l= 159 cons: SEQUENCE - 379:d=4 hl=2 l= 29 cons: SEQUENCE + 373:d=2 hl=3 l= 162 cons: cont [ 3 ] + 376:d=3 hl=3 l= 159 cons: SEQUENCE + 379:d=4 hl=2 l= 29 cons: SEQUENCE 381:d=5 hl=2 l= 3 prim: OBJECT :X509v3 Subject Key Identifier - 386:d=5 hl=2 l= 22 prim: OCTET STRING - 410:d=4 hl=2 l= 112 cons: SEQUENCE + 386:d=5 hl=2 l= 22 prim: OCTET STRING + 410:d=4 hl=2 l= 112 cons: SEQUENCE 412:d=5 hl=2 l= 3 prim: OBJECT :X509v3 Authority Key Identifier - 417:d=5 hl=2 l= 105 prim: OCTET STRING - 524:d=4 hl=2 l= 12 cons: SEQUENCE + 417:d=5 hl=2 l= 105 prim: OCTET STRING + 524:d=4 hl=2 l= 12 cons: SEQUENCE ..... @@ -133,27 +133,27 @@ the contents octets. The B<-i> option can be used to make the output more readable. -Some knowledge of the ASN.1 structure is needed to interpret the output. +Some knowledge of the ASN.1 structure is needed to interpret the output. In this example the BIT STRING at offset 229 is the certificate public key. The contents octets of this will contain the public key information. This can be examined using the option B<-strparse 229> to yield: - 0:d=0 hl=3 l= 137 cons: SEQUENCE + 0:d=0 hl=3 l= 137 cons: SEQUENCE 3:d=1 hl=3 l= 129 prim: INTEGER :E5D21E1F5C8D208EA7A2166C7FAF9F6BDF2059669C60876DDB70840F1A5AAFA59699FE471F379F1DD6A487E7D5409AB6A88D4A9746E24B91D8CF55DB3521015460C8EDE44EE8A4189F7A7BE77D6CD3A9AF2696F486855CF58BF0EDF2B4068058C7A947F52548DDF7E15E96B385F86422BEA9064A3EE9E1158A56E4A6F47E5897 135:d=1 hl=2 l= 3 prim: INTEGER :010001 =head1 NOTES If an OID is not part of OpenSSL's internal table it will be represented in -numerical form (for example 1.2.3.4). The file passed to the B<-oid> option +numerical form (for example 1.2.3.4). The file passed to the B<-oid> option allows additional OIDs to be included. Each line consists of three columns, the first column is the OID in numerical format and should be followed by white space. The second column is the "short name" which is a single word followed by white space. The final column is the rest of the line and is the "long name". B<asn1parse> displays the long name. Example: -C<1.2.3.4 shortName A long name> +C<1.2.3.4 shortName A long name> =head1 EXAMPLES diff --git a/doc/apps/ca.pod b/doc/apps/ca.pod index 6c2948501c..de3744e302 100644 --- a/doc/apps/ca.pod +++ b/doc/apps/ca.pod @@ -1,4 +1,3 @@ - =pod =head1 NAME @@ -101,7 +100,7 @@ section for information on the required input and output format. =item B<-infiles> if present this should be the last option, all subsequent arguments -are taken as the names of files containing certificate requests. +are taken as the names of files containing certificate requests. =item B<-out filename> @@ -195,7 +194,7 @@ need this option. =item B<-preserveDN> Normally the DN order of a certificate is the same as the order of the -fields in the relevant policy section. When this option is set the order +fields in the relevant policy section. When this option is set the order is the same as the request. This is largely for compatibility with the older IE enrollment control which would only accept certificates if their DNs match the order of the request. This is not needed for Xenroll. @@ -245,7 +244,7 @@ characters may be escaped by \ (backslash), no spaces are skipped. =item B<-utf8> -this option causes field values to be interpreted as UTF8 strings, by +this option causes field values to be interpreted as UTF8 strings, by default they are interpreted as ASCII. This means that the field values, whether prompted from a terminal or obtained from a configuration file, must be valid UTF8 strings. @@ -366,7 +365,7 @@ any) used. This specifies a file containing additional B<OBJECT IDENTIFIERS>. Each line of the file should consist of the numerical form of the object identifier followed by white space then the short name followed -by white space and finally the long name. +by white space and finally the long name. =item B<oid_section> @@ -398,7 +397,7 @@ an EGD socket (see L<RAND_egd(3)>). =item B<default_days> the same as the B<-days> option. The number of days to certify -a certificate for. +a certificate for. =item B<default_startdate> @@ -521,7 +520,7 @@ this can be regarded more of a quirk than intended behaviour. The input to the B<-spkac> command line option is a Netscape signed public key and challenge. This will usually come from -the B<KEYGEN> tag in an HTML form to create a new private key. +the B<KEYGEN> tag in an HTML form to create a new private key. It is however possible to create SPKACs using the B<spkac> utility. The file should contain the variable SPKAC set to the value of @@ -581,18 +580,18 @@ A sample configuration file with the relevant sections for B<ca>: [ ca ] default_ca = CA_default # The default ca section - + [ CA_default ] dir = ./demoCA # top dir database = $dir/index.txt # index file. - new_certs_dir = $dir/newcerts # new certs dir - + new_certs_dir = $dir/newcerts # new certs dir + certificate = $dir/cacert.pem # The CA cert serial = $dir/serial # serial no file private_key = $dir/private/cakey.pem# CA private key RANDFILE = $dir/private/.rand # random number file - + default_days = 365 # how long to certify for default_crl_days= 30 # how long before next CRL default_md = md5 # md to use @@ -600,9 +599,9 @@ A sample configuration file with the relevant sections for B<ca>: policy = policy_any # default policy email_in_dn = no # Don't add the email into cert DN - name_opt = ca_default # Subject name display option - cert_opt = ca_default # Certificate display option - copy_extensions = none # Don't copy extensions from request + name_opt = ca_default # Subject name display option + cert_opt = ca_default # Certificate display option + copy_extensions = none # Don't copy extensions from request [ policy_any ] countryName = supplied @@ -636,7 +635,7 @@ be overridden by the B<-config> command line option. =head1 RESTRICTIONS -The text database index file is a critical part of the process and +The text database index file is a critical part of the process and if corrupted it can be difficult to fix. It is theoretically possible to rebuild the index file from all the issued certificates and a current CRL: however there is no option to do this. @@ -704,7 +703,7 @@ then even if a certificate is issued with CA:TRUE it will not be valid. =head1 SEE ALSO L<req(1)>, L<spkac(1)>, L<x509(1)>, L<CA.pl(1)>, -L<config(5)>, L<x509v3_config(5)> +L<config(5)>, L<x509v3_config(5)> =cut diff --git a/doc/apps/cms.pod b/doc/apps/cms.pod index 4876ef1521..2552f220ba 100644 --- a/doc/apps/cms.pod +++ b/doc/apps/cms.pod @@ -186,13 +186,13 @@ B<EncrytedData> type and output the content. =item B<-sign_receipt> -Generate and output a signed receipt for the supplied message. The input +Generate and output a signed receipt for the supplied message. The input message B<must> contain a signed receipt request. Functionality is otherwise similar to the B<-sign> operation. =item B<-verify_receipt receipt> -Verify a signed receipt in filename B<receipt>. The input message B<must> +Verify a signed receipt in filename B<receipt>. The input message B<must> contain the original receipt request. Functionality is otherwise similar to the B<-verify> operation. @@ -256,7 +256,7 @@ is S/MIME and it uses the multipart/signed MIME content type. this option adds plain text (text/plain) MIME headers to the supplied message if encrypting or signing. If decrypting or verifying it strips -off text headers: if the decrypted or verified message is not of MIME +off text headers: if the decrypted or verified message is not of MIME type text/plain then an error occurs. =item B<-noout> @@ -298,11 +298,11 @@ default digest algorithm for the signing key will be used (usually SHA1). the encryption algorithm to use. For example triple DES (168 bits) - B<-des3> or 256 bit AES - B<-aes256>. Any standard algorithm name (as used by the -EVP_get_cipherbyname() function) can also be used preceded by a dash, for +EVP_get_cipherbyname() function) can also be used preceded by a dash, for example B<-aes-128-cbc>. See L<B<enc>|enc(1)> for a list of ciphers supported by your version of OpenSSL. -If not specified triple DES is used. Only used with B<-encrypt> and +If not specified triple DES is used. Only used with B<-encrypt> and B<-EncryptedData_create> commands. =item B<-nointern> @@ -408,7 +408,7 @@ address where receipts should be supplied. =item B<-receipt_request_to emailaddress> -Add an explicit email address where signed receipts should be sent to. This +Add an explicit email address where signed receipts should be sent to. This option B<must> but supplied if a signed receipt it requested. =item B<-receipt_request_print> @@ -436,7 +436,7 @@ B<KEKRecipientInfo> structures. set the encapsulated content type to B<type> if not supplied the B<Data> type is used. The B<type> argument can be any valid OID name in either text or -numerical format. +numerical format. =item B<-inkey file> @@ -469,7 +469,7 @@ all others. =item B<cert.pem...> one or more certificates of message recipients: used when encrypting -a message. +a message. =item B<-to, -from, -subject> @@ -534,7 +534,7 @@ attempt is made to locate the recipient by trying each potential recipient in turn using the supplied private key. To thwart the MMA attack (Bleichenbacher's attack on PKCS #1 v1.5 RSA padding) all recipients are tried whether they succeed or not and if no recipients match the message -is "decrypted" using a random key which will typically output garbage. +is "decrypted" using a random key which will typically output garbage. The B<-debug_decrypt> option can be used to disable the MMA attack protection and return an error if no recipient can be found: this option should be used with caution. For a fuller description see L<CMS_decrypt(3)>). @@ -598,29 +598,29 @@ be processed by the older B<smime> command. Create a cleartext signed message: openssl cms -sign -in message.txt -text -out mail.msg \ - -signer mycert.pem + -signer mycert.pem Create an opaque signed message openssl cms -sign -in message.txt -text -out mail.msg -nodetach \ - -signer mycert.pem + -signer mycert.pem Create a signed message, include some additional certificates and read the private key from another file: openssl cms -sign -in in.txt -text -out mail.msg \ - -signer mycert.pem -inkey mykey.pem -certfile mycerts.pem + -signer mycert.pem -inkey mykey.pem -certfile mycerts.pem Create a signed message with two signers, use key identifier: openssl cms -sign -in message.txt -text -out mail.msg \ - -signer mycert.pem -signer othercert.pem -keyid + -signer mycert.pem -signer othercert.pem -keyid Send a signed message under Unix directly to sendmail, including headers: openssl cms -sign -in in.txt -text -signer mycert.pem \ - -from steve@openssl.org -to someone@somewhere \ - -subject "Signed message" | sendmail someone@somewhere + -from steve@openssl.org -to someone@somewhere \ + -subject "Signed message" | sendmail someone@somewhere Verify a message and extract the signer's certificate if successful: @@ -629,15 +629,15 @@ Verify a message and extract the signer's certificate if successful: Send encrypted mail using triple DES: openssl cms -encrypt -in in.txt -from steve@openssl.org \ - -to someone@somewhere -subject "Encrypted message" \ - -des3 user.pem -out mail.msg + -to someone@somewhere -subject "Encrypted message" \ + -des3 user.pem -out mail.msg Sign and encrypt mail: openssl cms -sign -in ml.txt -signer my.pem -text \ - | openssl cms -encrypt -out mail.msg \ - -from steve@openssl.org -to someone@somewhere \ - -subject "Signed and Encrypted message" -des3 user.pem + | openssl cms -encrypt -out mail.msg \ + -from steve@openssl.org -to someone@somewhere \ + -subject "Signed and Encrypted message" -des3 user.pem Note: the encryption command does not include the B<-text> option because the message being encrypted already has MIME headers. @@ -654,7 +654,7 @@ it with: -----BEGIN PKCS7----- -----END PKCS7----- -and using the command, +and using the command, openssl cms -verify -inform PEM -in signature.pem -content content.txt @@ -673,17 +673,17 @@ Add a signer to an existing message: Sign mail using RSA-PSS: openssl cms -sign -in message.txt -text -out mail.msg \ - -signer mycert.pem -keyopt rsa_padding_mode:pss + -signer mycert.pem -keyopt rsa_padding_mode:pss Create encrypted mail using RSA-OAEP: openssl cms -encrypt -in plain.txt -out mail.msg \ - -recip cert.pem -keyopt rsa_padding_mode:oaep + -recip cert.pem -keyopt rsa_padding_mode:oaep Use SHA256 KDF with an ECDH certificate: openssl cms -encrypt -in plain.txt -out mail.msg \ - -recip ecdhcert.pem -keyopt ecdh_kdf_md:sha256 + -recip ecdhcert.pem -keyopt ecdh_kdf_md:sha256 =head1 BUGS @@ -715,7 +715,7 @@ The B<keyopt> option was first added in OpenSSL 1.1.0 The use of B<-recip> to specify the recipient when encrypting mail was first added to OpenSSL 1.1.0 -Support for RSA-OAEP and RSA-PSS was first added to OpenSSL 1.1.0. +Support for RSA-OAEP and RSA-PSS was first added to OpenSSL 1.1.0. The use of non-RSA keys with B<-encrypt> and B<-decrypt> was first added to OpenSSL 1.1.0. diff --git a/doc/apps/config.pod b/doc/apps/config.pod index baa886b5ae..499bc9e11a 100644 --- a/doc/apps/config.pod +++ b/doc/apps/config.pod @@ -1,4 +1,3 @@ - =pod =for comment openssl_manual_section:5 @@ -63,14 +62,14 @@ functionality: any sub command uses the master OpenSSL configuration file unless an option is used in the sub command to use an alternative configuration file. -To enable library configuration the default section needs to contain an +To enable library configuration the default section needs to contain an appropriate line which points to the main configuration section. The default name is B<openssl_conf> which is used by the B<openssl> utility. Other applications may use an alternative name such as B<myapplicaton_conf>. The configuration section should consist of a set of name value pairs which contain specific module configuration information. The B<name> represents -the name of the I<configuration module> the meaning of the B<value> is +the name of the I<configuration module> the meaning of the B<value> is module specific: it may, for example, represent a further configuration section containing configuration module specific information. E.g. @@ -102,7 +101,7 @@ B<all> the B<openssl> utility sub commands can see the new objects as well as any compliant applications. For example: [new_oids] - + some_new_oid = 1.2.3.4 some_other_oid = 1.2.3.5 @@ -141,7 +140,7 @@ For example: [bar_section] ... "bar" ENGINE specific commands ... -The command B<engine_id> is used to give the ENGINE name. If used this +The command B<engine_id> is used to give the ENGINE name. If used this command must be first. For example: [engine_section] @@ -168,7 +167,7 @@ The command B<default_algorithms> sets the default algorithms an ENGINE will supply using the functions ENGINE_set_default_string(). If the name matches none of the above command names it is assumed to be a -ctrl command which is sent to the ENGINE. The value of the command is the +ctrl command which is sent to the ENGINE. The value of the command is the argument to the ctrl command. If the value is the string B<EMPTY> then no value is sent to the command. @@ -266,7 +265,7 @@ Here is a sample configuration file using some of the features mentioned above. # This is the default section. - + HOME=/temp RANDFILE= ${ENV::HOME}/.rnd configdir=$ENV::HOME/config @@ -296,7 +295,7 @@ the B<TEMP> or B<TMP> environment variables but they may not be set to any value at all. If you just include the environment variable names and the variable doesn't exist then this will cause an error when an attempt is made to load the configuration file. By making use of the -default section both values can be looked up with B<TEMP> taking +default section both values can be looked up with B<TEMP> taking priority and B</tmp> used if neither is defined: TMP=/tmp diff --git a/doc/apps/crl.pod b/doc/apps/crl.pod index bb1092c750..cb5969ad83 100644 --- a/doc/apps/crl.pod +++ b/doc/apps/crl.pod @@ -42,7 +42,7 @@ the DER form with header and footer lines. =item B<-outform DER|PEM> -This specifies the output format, the options have the same meaning as the +This specifies the output format, the options have the same meaning as the B<-inform> option. =item B<-in filename> diff --git a/doc/apps/crl2pkcs7.pod b/doc/apps/crl2pkcs7.pod index f32940273d..26ec889549 100644 --- a/doc/apps/crl2pkcs7.pod +++ b/doc/apps/crl2pkcs7.pod @@ -74,8 +74,8 @@ Create a PKCS#7 structure from a certificate and CRL: Creates a PKCS#7 structure in DER format with no CRL from several different certificates: - openssl crl2pkcs7 -nocrl -certfile newcert.pem - -certfile demoCA/cacert.pem -outform DER -out p7.der + openssl crl2pkcs7 -nocrl -certfile newcert.pem + -certfile demoCA/cacert.pem -outform DER -out p7.der =head1 NOTES diff --git a/doc/apps/dgst.pod b/doc/apps/dgst.pod index ce26a5607d..75b8ad9b1e 100644 --- a/doc/apps/dgst.pod +++ b/doc/apps/dgst.pod @@ -156,7 +156,7 @@ a file or files containing random data used to seed the random number generator, or an EGD socket (see L<RAND_egd(3)>). Multiple files can be specified separated by an OS-dependent character. The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for -all others. +all others. =item B<-fips-fingerprint> diff --git a/doc/apps/dhparam.pod b/doc/apps/dhparam.pod index b72ca7ec14..771ef1b0ad 100644 --- a/doc/apps/dhparam.pod +++ b/doc/apps/dhparam.pod @@ -44,7 +44,7 @@ additional header and footer lines. =item B<-outform DER|PEM> -This specifies the output format, the options have the same meaning as the +This specifies the output format, the options have the same meaning as the B<-inform> option. =item B<-in> I<filename> @@ -123,7 +123,7 @@ for all available algorithms. The program B<dhparam> combines the functionality of the programs B<dh> and B<gendh> in previous versions of OpenSSL. The B<dh> and B<gendh> -programs are retained for now but may have different purposes in future +programs are retained for now but may have different purposes in future versions of OpenSSL. =head1 NOTES diff --git a/doc/apps/dsa.pod b/doc/apps/dsa.pod index 1f0e5ddc42..3a244cf3b0 100644 --- a/doc/apps/dsa.pod +++ b/doc/apps/dsa.pod @@ -59,7 +59,7 @@ PKCS#8 format is also accepted. =item B<-outform DER|PEM> -This specifies the output format, the options have the same meaning as the +This specifies the output format, the options have the same meaning as the B<-inform> option. =item B<-in filename> @@ -149,7 +149,7 @@ To encrypt a private key using triple DES: openssl dsa -in key.pem -des3 -out keyout.pem -To convert a private key from PEM to DER format: +To convert a private key from PEM to DER format: openssl dsa -in key.pem -outform DER -out keyout.der diff --git a/doc/apps/dsaparam.pod b/doc/apps/dsaparam.pod index 0a3727a32b..753f3b19d5 100644 --- a/doc/apps/dsaparam.pod +++ b/doc/apps/dsaparam.pod @@ -41,7 +41,7 @@ of the B<DER> format base64 encoded with additional header and footer lines. =item B<-outform DER|PEM> -This specifies the output format, the options have the same meaning as the +This specifies the output format, the options have the same meaning as the B<-inform> option. =item B<-in filename> diff --git a/doc/apps/ec.pod b/doc/apps/ec.pod index 738b718dfd..c1b6bb0714 100644 --- a/doc/apps/ec.pod +++ b/doc/apps/ec.pod @@ -31,7 +31,7 @@ B<openssl> B<ec> =head1 DESCRIPTION The B<ec> command processes EC keys. They can be converted between various -forms and their components printed out. B<Note> OpenSSL uses the +forms and their components printed out. B<Note> OpenSSL uses the private key format specified in 'SEC 1: Elliptic Curve Cryptography' (http://www.secg.org/). To convert an OpenSSL EC private key into the PKCS#8 private key format use the B<pkcs8> command. @@ -55,7 +55,7 @@ PKCS#8 format is also accepted. =item B<-outform DER|PEM> -This specifies the output format, the options have the same meaning as the +This specifies the output format, the options have the same meaning as the B<-inform> option. =item B<-in filename> @@ -83,7 +83,7 @@ see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>. =item B<-des|-des3|-idea> -These options encrypt the private key with the DES, triple DES, IDEA or +These options encrypt the private key with the DES, triple DES, IDEA or any other cipher supported by OpenSSL before outputting it. A pass phrase is prompted for. If none of these options is specified the key is written in plain text. This @@ -130,7 +130,7 @@ the preprocessor macro B<OPENSSL_EC_BIN_PT_COMP> at compile time. This specifies how the elliptic curve parameters are encoded. Possible value are: B<named_curve>, i.e. the ec parameters are specified by an OID, or B<explicit> where the ec parameters are -explicitly given (see RFC 3279 for the definition of the +explicitly given (see RFC 3279 for the definition of the EC parameters structures). The default value is B<named_curve>. B<Note> the B<implicitlyCA> alternative ,as specified in RFC 3279, is currently not implemented in OpenSSL. @@ -170,7 +170,7 @@ To encrypt a private key using triple DES: openssl ec -in key.pem -des3 -out keyout.pem -To convert a private key from PEM to DER format: +To convert a private key from PEM to DER format: openssl ec -in key.pem -outform DER -out keyout.der diff --git a/doc/apps/ecparam.pod b/doc/apps/ecparam.pod index fb0181ff95..a41e005625 100644 --- a/doc/apps/ecparam.pod +++ b/doc/apps/ecparam.pod @@ -41,12 +41,12 @@ Print out a usage message. This specifies the input format. The B<DER> option uses an ASN.1 DER encoded form compatible with RFC 3279 EcpkParameters. The PEM form is the default -format: it consists of the B<DER> format base64 encoded with additional |