summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorRich Salz <rsalz@openssl.org>2017-04-03 15:39:09 -0400
committerRich Salz <rsalz@openssl.org>2017-04-07 14:51:18 -0400
commit74c29dc6eac1f6f8a8c2ca28f8c01a43beb8c15b (patch)
treeef4e887705d8a933c44e42bdc5ade8306da3d9de /doc
parentae9b7e02ecb06def1ccc1d132bd9ba7de1347518 (diff)
Standardize on =over 4 and check for it.
(cherry picked from commit dfc63ccebd8262648640fc6e35fffa132102b967) Reviewed-by: Richard Levitte <levitte@openssl.org> (Merged from https://github.com/openssl/openssl/pull/3117)
Diffstat (limited to 'doc')
-rw-r--r--doc/apps/dgst.pod38
-rw-r--r--doc/apps/openssl.pod43
-rw-r--r--doc/apps/rehash.pod2
-rw-r--r--doc/crypto/ASN1_generate_nconf.pod6
-rw-r--r--doc/crypto/BIO_set_callback.pod2
-rw-r--r--doc/crypto/CT_POLICY_EVAL_CTX_new.pod36
-rw-r--r--doc/crypto/EVP_CIPHER_meth_new.pod2
-rw-r--r--doc/crypto/OPENSSL_ia32cap.pod4
-rw-r--r--doc/crypto/SCT_new.pod55
-rw-r--r--doc/crypto/SCT_validate.pod14
-rw-r--r--doc/crypto/d2i_X509.pod6
-rw-r--r--doc/crypto/des_modes.pod19
-rw-r--r--doc/crypto/evp.pod2
13 files changed, 88 insertions, 141 deletions
diff --git a/doc/apps/dgst.pod b/doc/apps/dgst.pod
index 3f1b02ca51..677f2b21ef 100644
--- a/doc/apps/dgst.pod
+++ b/doc/apps/dgst.pod
@@ -59,34 +59,34 @@ supported digests, use the command I<list --digest-commands>.
=item B<-c>
-print out the digest in two digit groups separated by colons, only relevant if
+Print out the digest in two digit groups separated by colons, only relevant if
B<hex> format output is used.
=item B<-d>
-print out BIO debugging information.
+Print out BIO debugging information.
=item B<-hex>
-digest is to be output as a hex dump. This is the default case for a "normal"
+Digest is to be output as a hex dump. This is the default case for a "normal"
digest as opposed to a digital signature. See NOTES below for digital
signatures using B<-hex>.
=item B<-binary>
-output the digest or signature in binary form.
+Output the digest or signature in binary form.
=item B<-r>
-output the digest in the "coreutils" format used by programs like B<sha1sum>.
+Output the digest in the "coreutils" format used by programs like B<sha1sum>.
=item B<-out filename>
-filename to output to, or standard output by default.
+Filename to output to, or standard output by default.
=item B<-sign filename>
-digitally sign the digest using the private key in "filename".
+Digitally sign the digest using the private key in "filename".
=item B<-keyform arg>
@@ -98,32 +98,31 @@ and ENGINE formats are supported.
Pass options to the signature algorithm during sign or verify operations.
Names and values of these options are algorithm-specific.
-
=item B<-passin arg>
-the private key password source. For more information about the format of B<arg>
+The private key password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
=item B<-verify filename>
-verify the signature using the public key in "filename".
+Verify the signature using the public key in "filename".
The output is either "Verification OK" or "Verification Failure".
=item B<-prverify filename>
-verify the signature using the private key in "filename".
+Verify the signature using the private key in "filename".
=item B<-signature filename>
-the actual signature to verify.
+The actual signature to verify.
=item B<-hmac key>
-create a hashed MAC using "key".
+Create a hashed MAC using "key".
=item B<-mac alg>
-create MAC (keyed Message Authentication Code). The most popular MAC
+Create MAC (keyed Message Authentication Code). The most popular MAC
algorithm is HMAC (hash-based MAC), but there are other MAC algorithms
which are not based on hash, for instance B<gost-mac> algorithm,
supported by B<ccgost> engine. MAC keys and other options should be set
@@ -134,7 +133,7 @@ via B<-macopt> parameter.
Passes options to MAC algorithm, specified by B<-mac> key.
Following options are supported by both by B<HMAC> and B<gost-mac>:
-=over 8
+=over 4
=item B<key:string>
@@ -152,7 +151,7 @@ for example exactly 32 chars for gost-mac.
=item B<-rand file(s)>
-a file or files containing random data used to seed the random number
+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
@@ -160,8 +159,7 @@ all others.
=item B<-fips-fingerprint>
-compute HMAC using a specific key
-for certain OpenSSL-FIPS operations.
+Compute HMAC using a specific key for certain OpenSSL-FIPS operations.
=item B<-engine id>
@@ -177,7 +175,7 @@ engine B<id> for digest operations.
=item B<file...>
-file or files to digest. If no files are specified then standard input is
+File or files to digest. If no files are specified then standard input is
used.
=back
@@ -230,7 +228,7 @@ The FIPS-related options were removed in OpenSSL 1.1.0
=head1 COPYRIGHT
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
diff --git a/doc/apps/openssl.pod b/doc/apps/openssl.pod
index da07cd5caf..7fc53c9bae 100644
--- a/doc/apps/openssl.pod
+++ b/doc/apps/openssl.pod
@@ -75,7 +75,7 @@ B<list>, or B<no->I<XXX> itself.)
=head2 Standard Commands
-=over 10
+=over 4
=item L<B<asn1parse>|asn1parse(1)>
@@ -91,7 +91,7 @@ Cipher Suite Description Determination.
=item L<B<cms>|cms(1)>
-CMS (Cryptographic Message Syntax) utility
+CMS (Cryptographic Message Syntax) utility.
=item L<B<crl>|crl(1)>
@@ -113,8 +113,7 @@ Obsoleted by L<B<dhparam>|dhparam(1)>.
=item L<B<dhparam>|dhparam(1)>
Generation and Management of Diffie-Hellman Parameters. Superseded by
-L<B<genpkey>|genpkey(1)> and L<B<pkeyparam>|pkeyparam(1)>
-
+L<B<genpkey>|genpkey(1)> and L<B<pkeyparam>|pkeyparam(1)>.
=item L<B<dsa>|dsa(1)>
@@ -123,15 +122,15 @@ DSA Data Management.
=item L<B<dsaparam>|dsaparam(1)>
DSA Parameter Generation and Management. Superseded by
-L<B<genpkey>|genpkey(1)> and L<B<pkeyparam>|pkeyparam(1)>
+L<B<genpkey>|genpkey(1)> and L<B<pkeyparam>|pkeyparam(1)>.
=item L<B<ec>|ec(1)>
-EC (Elliptic curve) key processing
+EC (Elliptic curve) key processing.
=item L<B<ecparam>|ecparam(1)>
-EC parameter manipulation and generation
+EC parameter manipulation and generation.
=item L<B<enc>|enc(1)>
@@ -153,7 +152,7 @@ Obsoleted by L<B<dhparam>|dhparam(1)>.
=item L<B<gendsa>|gendsa(1)>
Generation of DSA Private Key from Parameters. Superseded by
-L<B<genpkey>|genpkey(1)> and L<B<pkey>|pkey(1)>
+L<B<genpkey>|genpkey(1)> and L<B<pkey>|pkey(1)>.
=item L<B<genpkey>|genpkey(1)>
@@ -165,7 +164,7 @@ Generation of RSA Private Key. Superseded by L<B<genpkey>|genpkey(1)>.
=item L<B<nseq>|nseq(1)>
-Create or examine a Netscape certificate sequence
+Create or examine a Netscape certificate sequence.
=item L<B<ocsp>|ocsp(1)>
@@ -211,7 +210,7 @@ RSA key management.
=item L<B<rsautl>|rsautl(1)>
RSA utility for signing, verification, encryption, and decryption. Superseded
-by L<B<pkeyutl>|pkeyutl(1)>
+by L<B<pkeyutl>|pkeyutl(1)>.
=item L<B<s_client>|s_client(1)>
@@ -247,11 +246,11 @@ Algorithm Speed Measurement.
=item L<B<spkac>|spkac(1)>
-SPKAC printing and generating utility
+SPKAC printing and generating utility.
=item L<B<ts>|ts(1)>
-Time Stamping Authority tool (client/server)
+Time Stamping Authority tool (client/server).
=item L<B<verify>|verify(1)>
@@ -269,7 +268,7 @@ X.509 Certificate Data Management.
=head2 Message Digest Commands
-=over 10
+=over 4
=item B<md2>
@@ -315,7 +314,7 @@ SHA-512 Digest
=head2 Encoding and Cipher Commands
-=over 10
+=over 4
=item B<base64>
@@ -366,7 +365,7 @@ This section describes some common options with common behavior.
=head2 Common Options
-=over 10
+=over 4
=item B<-help>
@@ -384,23 +383,23 @@ password argument is given and a password is required then the user is
prompted to enter one: this will typically be read from the current
terminal with echoing turned off.
-=over 10
+=over 4
=item B<pass:password>
-the actual password is B<password>. Since the password is visible
+The actual password is B<password>. Since the password is visible
to utilities (like 'ps' under Unix) this form should only be used
where security is not important.
=item B<env:var>
-obtain the password from the environment variable B<var>. Since
+Obtain the password from the environment variable B<var>. Since
the environment of other processes is visible on certain platforms
(e.g. ps under certain Unix OSes) this option should be used with caution.
=item B<file:pathname>
-the first line of B<pathname> is the password. If the same B<pathname>
+The first line of B<pathname> is the password. If the same B<pathname>
argument is supplied to B<-passin> and B<-passout> arguments then the first
line will be used for the input password and the next line for the output
password. B<pathname> need not refer to a regular file: it could for example
@@ -408,12 +407,12 @@ refer to a device or named pipe.
=item B<fd:number>
-read the password from the file descriptor B<number>. This can be used to
+Read the password from the file descriptor B<number>. This can be used to
send the data via a pipe for example.
=item B<stdin>
-read the password from standard input.
+Read the password from standard input.
=back
@@ -441,7 +440,7 @@ manual pages.
=head1 COPYRIGHT
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
diff --git a/doc/apps/rehash.pod b/doc/apps/rehash.pod
index 936fda6180..1dca9b5341 100644
--- a/doc/apps/rehash.pod
+++ b/doc/apps/rehash.pod
@@ -107,7 +107,7 @@ By default, B<rehash> only lists each directory as it is processed.
=head1 ENVIRONMENT
-=over
+=over 4
=item B<OPENSSL>
diff --git a/doc/crypto/ASN1_generate_nconf.pod b/doc/crypto/ASN1_generate_nconf.pod
index 92f624fa24..bf29af62f7 100644
--- a/doc/crypto/ASN1_generate_nconf.pod
+++ b/doc/crypto/ASN1_generate_nconf.pod
@@ -30,7 +30,7 @@ The actual data encoded is determined by the string B<str> and
the configuration information. The general format of the string
is:
-=over 2
+=over 4
=item B<[modifier,]type[:value]>
@@ -45,7 +45,7 @@ B<value> and B<modifier> are explained below.
The supported types are listed below. Unless otherwise specified
only the B<ASCII> format is permissible.
-=over 2
+=over 4
=item B<BOOLEAN>, B<BOOL>
@@ -126,7 +126,7 @@ add EXPLICIT or IMPLICIT tagging, add wrappers or to change
the string format of the final type and value. The supported
formats are documented below.
-=over 2
+=over 4
=item B<EXPLICIT>, B<EXP>
diff --git a/doc/crypto/BIO_set_callback.pod b/doc/crypto/BIO_set_callback.pod
index ed395fa0ab..3d15859406 100644
--- a/doc/crypto/BIO_set_callback.pod
+++ b/doc/crypto/BIO_set_callback.pod
@@ -52,7 +52,7 @@ BIO_callback_fn_ex() is the type of the callback function and BIO_callback_fn()
is the type of the old format callback function. The meaning of each argument
is described below:
-=over
+=over 4
=item B<b>
diff --git a/doc/crypto/CT_POLICY_EVAL_CTX_new.pod b/doc/crypto/CT_POLICY_EVAL_CTX_new.pod
index 4d0cae3bbf..7839fd393a 100644
--- a/doc/crypto/CT_POLICY_EVAL_CTX_new.pod
+++ b/doc/crypto/CT_POLICY_EVAL_CTX_new.pod
@@ -32,23 +32,15 @@ This policy may be, for example, that at least one valid SCT is available. To
determine this, an SCT's timestamp and signature must be verified.
This requires:
-=over 2
+=over 4
-=item *
+=item * the public key of the log that issued the SCT
-the public key of the log that issued the SCT
+=item * the certificate that the SCT was issued for
-=item *
+=item * the issuer certificate (if the SCT was issued for a pre-certificate)
-the certificate that the SCT was issued for
-
-=item *
-
-the issuer certificate (if the SCT was issued for a pre-certificate)
-
-=item *
-
-the current time
+=item * the current time
=back
@@ -57,30 +49,22 @@ The above requirements are met using the setters described below.
CT_POLICY_EVAL_CTX_new() creates an empty policy evaluation context. This
should then be populated using:
-=over 2
+=over 4
-=item *
-
-CT_POLICY_EVAL_CTX_set1_cert() to provide the certificate the SCTs were issued for
+=item * CT_POLICY_EVAL_CTX_set1_cert() to provide the certificate the SCTs were issued for
Increments the reference count of the certificate.
-=item *
-
-CT_POLICY_EVAL_CTX_set1_issuer() to provide the issuer certificate
+=item * CT_POLICY_EVAL_CTX_set1_issuer() to provide the issuer certificate
Increments the reference count of the certificate.
-=item *
-
-CT_POLICY_EVAL_CTX_set_shared_CTLOG_STORE() to provide a list of logs that are trusted as sources of SCTs
+=item * CT_POLICY_EVAL_CTX_set_shared_CTLOG_STORE() to provide a list of logs that are trusted as sources of SCTs
Holds a pointer to the CTLOG_STORE, so the CTLOG_STORE must outlive the
CT_POLICY_EVAL_CTX.
-=item *
-
-CT_POLICY_EVAL_CTX_set_time() to set the time SCTs should be compared with to determine if they are valid
+=item * CT_POLICY_EVAL_CTX_set_time() to set the time SCTs should be compared with to determine if they are valid
The SCT timestamp will be compared to this time to check whether the SCT was
issued in the future. RFC6962 states that "TLS clients MUST reject SCTs whose
diff --git a/doc/crypto/EVP_CIPHER_meth_new.pod b/doc/crypto/EVP_CIPHER_meth_new.pod
index 6e18ed5412..ef47f0fdb3 100644
--- a/doc/crypto/EVP_CIPHER_meth_new.pod
+++ b/doc/crypto/EVP_CIPHER_meth_new.pod
@@ -82,7 +82,7 @@ With the exception of cipher modes, of which only one may be present,
several flags can be or'd together.
The available flags are:
-=over
+=over 4
=item EVP_CIPH_STREAM_CIPHER, EVP_CIPH_ECB_MODE EVP_CIPH_CBC_MODE,
EVP_CIPH_CFB_MODE, EVP_CIPH_OFB_MODE, EVP_CIPH_CTR_MODE, EVP_CIPH_GCM_MODE,
diff --git a/doc/crypto/OPENSSL_ia32cap.pod b/doc/crypto/OPENSSL_ia32cap.pod
index 7ea70c0fae..b0ab0ce551 100644
--- a/doc/crypto/OPENSSL_ia32cap.pod
+++ b/doc/crypto/OPENSSL_ia32cap.pod
@@ -19,7 +19,7 @@ between different code paths to provide optimal performance across wide
range of processors. For the moment of this writing following bits are
significant:
-=over
+=over 4
=item bit #4 denoting presence of Time-Stamp Counter.
@@ -86,7 +86,7 @@ are applied, most notably in AES assembler module.
The capability vector is further extended with EBX value returned by
CPUID with EAX=7 and ECX=0 as input. Following bits are significant:
-=over
+=over 4
=item bit #64+3 denoting availability of BMI1 instructions, e.g. ANDN;
diff --git a/doc/crypto/SCT_new.pod b/doc/crypto/SCT_new.pod
index e85b21ca1b..23595e1056 100644
--- a/doc/crypto/SCT_new.pod
+++ b/doc/crypto/SCT_new.pod
@@ -84,45 +84,31 @@ An internal representation of an SCT can be created in one of two ways.
The first option is to create a blank SCT, using SCT_new(), and then populate
it using:
-=over 2
+=over 4
-=item *
-
-SCT_set_version() to set the SCT version.
+=item * SCT_set_version() to set the SCT version.
Only SCT_VERSION_V1 is currently supported.
-=item *
-
-SCT_set_log_entry_type() to set the type of certificate the SCT was issued for:
+=item * SCT_set_log_entry_type() to set the type of certificate the SCT was issued for:
B<CT_LOG_ENTRY_TYPE_X509> for a normal certificate.
B<CT_LOG_ENTRY_TYPE_PRECERT> for a pre-certificate.
-=item *
-
-SCT_set0_log_id() or SCT_set1_log_id() to set the LogID of the CT log that the SCT came from.
+=item * SCT_set0_log_id() or SCT_set1_log_id() to set the LogID of the CT log that the SCT came from.
The former takes ownership, whereas the latter makes a copy.
See RFC 6962, Section 3.2 for the definition of LogID.
-=item *
-
-SCT_set_timestamp() to set the time the SCT was issued (epoch time in milliseconds).
-
-=item *
-
-SCT_set_signature_nid() to set the NID of the signature.
+=item * SCT_set_timestamp() to set the time the SCT was issued (epoch time in milliseconds).
-=item *
+=item * SCT_set_signature_nid() to set the NID of the signature.
-SCT_set0_signature() or SCT_set1_signature() to set the raw signature value.
+=item * SCT_set0_signature() or SCT_set1_signature() to set the raw signature value.
The former takes ownership, whereas the latter makes a copy.
-=item *
-
-SCT_set0_extensions() or B<SCT_set1_extensions> to provide SCT extensions.
+=item * SCT_set0_extensions() or B<SCT_set1_extensions> to provide SCT extensions.
The former takes ownership, whereas the latter makes a copy.
@@ -131,33 +117,22 @@ The former takes ownership, whereas the latter makes a copy.
Alternatively, the SCT can be pre-populated from the following data using
SCT_new_from_base64():
-=over 2
-
-=item *
-
-The SCT version (only SCT_VERSION_V1 is currently supported).
+=over 4
-=item *
+=item * The SCT version (only SCT_VERSION_V1 is currently supported).
-The LogID (see RFC 6962, Section 3.2), base64 encoded.
+=item * The LogID (see RFC 6962, Section 3.2), base64 encoded.
-=item *
+=item * The type of certificate the SCT was issued for:
-The type of certificate the SCT was issued for:
B<CT_LOG_ENTRY_TYPE_X509> for a normal certificate.
B<CT_LOG_ENTRY_TYPE_PRECERT> for a pre-certificate.
-=item *
-
-The time that the SCT was issued (epoch time in milliseconds).
-
-=item *
-
-The SCT extensions, base64 encoded.
+=item * The time that the SCT was issued (epoch time in milliseconds).
-=item *
+=item * The SCT extensions, base64 encoded.
-The SCT signature, base64 encoded.
+=item * The SCT signature, base64 encoded.
=back
diff --git a/doc/crypto/SCT_validate.pod b/doc/crypto/SCT_validate.pod
index 5ff0e8c459..3c03e97287 100644
--- a/doc/crypto/SCT_validate.pod
+++ b/doc/crypto/SCT_validate.pod
@@ -31,26 +31,20 @@ SCT_get_validation_status().
A CT_POLICY_EVAL_CTX must be provided that specifies:
-=over 2
+=over 4
-=item *
-
-The certificate the SCT was issued for.
+=item * The certificate the SCT was issued for.
Failure to provide the certificate will result in the validation status being
SCT_VALIDATION_STATUS_UNVERIFIED.
-=item *
-
-The issuer of that certificate.
+=item * The issuer of that certificate.
This is only required if the SCT was issued for a pre-certificate
(see RFC 6962). If it is required but not provided, the validation status will
be SCT_VALIDATION_STATUS_UNVERIFIED.
-=item *
-
-A CTLOG_STORE that contains the CT log that issued this SCT.
+=item * A CTLOG_STORE that contains the CT log that issued this SCT.
If the SCT was issued by a log that is not in this CTLOG_STORE, the validation
status will be SCT_VALIDATION_STATUS_UNKNOWN_LOG.
diff --git a/doc/crypto/d2i_X509.pod b/doc/crypto/d2i_X509.pod
index 06546a4875..f78d02065c 100644
--- a/doc/crypto/d2i_X509.pod
+++ b/doc/crypto/d2i_X509.pod
@@ -349,10 +349,10 @@ i2d_X509_SIG,
i2d_X509_VAL,
- convert objects from/to ASN.1/DER representation
-=for comment generic
-
=head1 SYNOPSIS
+=for comment generic
+
TYPE *d2i_TYPE(TYPE **a, unsigned char **pp, long length);
TYPE *d2i_TYPE_bio(BIO *bp, TYPE **a);
TYPE *d2i_TYPE_fp(FILE *fp, TYPE **a);
@@ -436,7 +436,7 @@ another will be processed after it.
The following points about the data types might be useful:
-=over
+=over 4
=item B<ASN1_OBJECT>
diff --git a/doc/crypto/des_modes.pod b/doc/crypto/des_modes.pod
index 5107b77c8d..7c1796980b 100644
--- a/doc/crypto/des_modes.pod
+++ b/doc/crypto/des_modes.pod
@@ -1,5 +1,4 @@
=pod
-
=for comment openssl_manual_section:7
=head1 NAME
@@ -18,7 +17,7 @@ other things.
Normally, this is found as the function I<algorithm>_ecb_encrypt().
-=over 2
+=over 4
=item *
@@ -45,7 +44,7 @@ Normally, this is found as the function I<algorithm>_cbc_encrypt().
Be aware that des_cbc_encrypt() is not really DES CBC (it does
not update the IV); use des_ncbc_encrypt() instead.
-=over 2
+=over 4
=item *
@@ -77,7 +76,7 @@ An error will affect the current and the following ciphertext blocks.
Normally, this is found as the function I<algorithm>_cfb_encrypt().
-=over 2
+=over 4
=item *
@@ -124,7 +123,7 @@ An error will affect the current and the following ciphertext variables.
Normally, this is found as the function I<algorithm>_ofb_encrypt().
-=over 2
+=over 4
=item *
@@ -185,7 +184,7 @@ susceptible to a 'known plaintext' attack.
Normally, this is found as the function I<algorithm>_ecb3_encrypt().
-=over 2
+=over 4
=item *
@@ -220,8 +219,7 @@ ecb mode.
Normally, this is found as the function I<algorithm>_ede3_cbc_encrypt().
-=over 2
-
+=over 4
=item *
@@ -248,12 +246,11 @@ it to:
=head1 SEE ALSO
-L<blowfish(3)>, L<des(3)>, L<idea(3)>,
-L<rc2(3)>
+L<BF_encrypt(3)>, L<DES_crypt(3)>
=head1 COPYRIGHT
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
diff --git a/doc/crypto/evp.pod b/doc/crypto/evp.pod
index 31f459084d..02051df6bc 100644
--- a/doc/crypto/evp.pod
+++ b/doc/crypto/evp.pod
@@ -38,7 +38,7 @@ L<EVP_PKEY_print_private(3)>.
The EVP_PKEY functions support the full range of asymmetric algorithm operations:
-=over
+=over 4
=item For key agreement see L<EVP_PKEY_derive(3)>