diff options
author | Gustaf Neumann <neumann@wu-wien.ac.at> | 2020-07-17 12:31:26 +0200 |
---|---|---|
committer | Dr. Matthias St. Pierre <matthias.st.pierre@ncp-e.com> | 2020-07-22 09:15:00 +0200 |
commit | 490c87110cc1fd673604fa1b94d5538f9fd852bb (patch) | |
tree | 3edd4a289e298a405dd7785fd1b21e81e8cd55e0 | |
parent | bf19b64aaeeddd5463d911823f9e2c3c40091005 (diff) | |
download | openssl-490c87110cc1fd673604fa1b94d5538f9fd852bb.zip openssl-490c87110cc1fd673604fa1b94d5538f9fd852bb.tar.gz openssl-490c87110cc1fd673604fa1b94d5538f9fd852bb.tar.bz2 |
Align documentation with recommendations of Linux Documentation Project
This change applies the recommendation of the Linux Documentation Project
to the documentation files of OpenSSL. Additionally, util/find-doc-nits
was updated accordingly.
The change follows a suggestion of mspncp on https://github.com/openssl/openssl/pull/12370
and incoporates the requested changes on the pull request
Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
(Merged from https://github.com/openssl/openssl/pull/12460)
51 files changed, 108 insertions, 100 deletions
diff --git a/doc/internal/man3/ossl_method_construct.pod b/doc/internal/man3/ossl_method_construct.pod index f3d7a64..fa151bb 100644 --- a/doc/internal/man3/ossl_method_construct.pod +++ b/doc/internal/man3/ossl_method_construct.pod @@ -35,9 +35,9 @@ OSSL_METHOD_CONSTRUCT_METHOD, ossl_method_construct =head1 DESCRIPTION -All libcrypto sub-systems that want to create their own methods based +All libcrypto subsystems that want to create their own methods based on provider dispatch tables need to do so in exactly the same way. -ossl_method_construct() does this while leaving it to the sub-systems +ossl_method_construct() does this while leaving it to the subsystems to define more precisely how the methods are created, stored, etc. It's important to keep in mind that a method is identified by three things: @@ -56,18 +56,18 @@ It's important to keep in mind that a method is identified by three things: ossl_method_construct() creates a method by asking all available providers for a dispatch table given an I<operation_id>, and then -calling the appropriate functions given by the sub-system specific +calling the appropriate functions given by the subsystem specific method creator through I<mcm> and the data in I<mcm_data> (which is passed by ossl_method_construct()). -This function assumes that the sub-system method creator implements +This function assumes that the subsystem method creator implements reference counting and acts accordingly (i.e. it will call the -sub-system destruct() method to decrement the reference count when +subsystem destruct() method to decrement the reference count when appropriate). =head2 Structures -A central part of constructing a sub-system specific method is to give +A central part of constructing a subsystem specific method is to give ossl_method_construct a set of functions, all in the B<OSSL_METHOD_CONSTRUCT_METHOD> structure, which holds the following function pointers: @@ -90,7 +90,7 @@ Remove a temporary store. Look up an already existing method from a store by name. The store may be given with I<store>. -NULL is a valid value and means that a sub-system default store +NULL is a valid value and means that a subsystem default store must be used. This default store should be stored in the library context I<libctx>. @@ -107,7 +107,7 @@ Places the I<method> created by the construct() function (see below) in a store. The store may be given with I<store>. -NULL is a valid value and means that a sub-system default store +NULL is a valid value and means that a subsystem default store must be used. This default store should be stored in the library context I<libctx>. @@ -120,11 +120,11 @@ This function is expected to increment the I<method>'s reference count. =item construct() -Constructs a sub-system method for the given I<name> and the given +Constructs a subsystem method for the given I<name> and the given dispatch table I<fns>. The associated provider object I<prov> is passed as well, to make -it possible for the sub-system constructor to keep a reference, which +it possible for the subsystem constructor to keep a reference, which is recommended. If such a reference is kept, the I<provider object> reference counter must be incremented, using ossl_provider_up_ref(). diff --git a/doc/man1/openssl-cmp.pod.in b/doc/man1/openssl-cmp.pod.in index 6ed11f4..216db0c 100644 --- a/doc/man1/openssl-cmp.pod.in +++ b/doc/man1/openssl-cmp.pod.in @@ -859,7 +859,7 @@ Act as CMP HTTP server mock-up listening on the given port. =item B<-max_msgs> I<number> Maximum number of CMP (request) messages the CMP HTTP server mock-up -should handle, which must be non-negative. +should handle, which must be nonnegative. The default value is 0, which means that no limit is imposed. In any case the server terminates on internal errors, but not when it detects a CMP-level error that it can successfully answer with an error message. diff --git a/doc/man1/openssl-s_client.pod.in b/doc/man1/openssl-s_client.pod.in index 78f4cc6..6d8cb5a 100644 --- a/doc/man1/openssl-s_client.pod.in +++ b/doc/man1/openssl-s_client.pod.in @@ -478,11 +478,11 @@ File to send output of B<-msg> or B<-trace> to, default standard output. =item B<-nbio_test> -Tests non-blocking I/O +Tests nonblocking I/O =item B<-nbio> -Turns on non-blocking I/O +Turns on nonblocking I/O =item B<-crlf> diff --git a/doc/man1/openssl-ts.pod.in b/doc/man1/openssl-ts.pod.in index 7a1ed41..d653637 100644 --- a/doc/man1/openssl-ts.pod.in +++ b/doc/man1/openssl-ts.pod.in @@ -90,8 +90,8 @@ value that it had sent to the TSA. =back -There is one DER encoded protocol data unit defined for transporting a time -stamp request to the TSA and one for sending the timestamp response +There is one DER encoded protocol data unit defined for transporting a +timestamp request to the TSA and one for sending the timestamp response back to the client. This command has three main functions: creating a timestamp request based on a data file, creating a timestamp response based on a request, verifying if a @@ -294,8 +294,8 @@ instead of DER. (Optional) =head2 Timestamp Response verification -The B<-verify> command is for verifying if a timestamp response or time -stamp token is valid and matches a particular timestamp request or +The B<-verify> command is for verifying if a timestamp response or +timestamp token is valid and matches a particular timestamp request or data file. The B<-verify> command does not use the configuration file. =over 4 diff --git a/doc/man1/openssl.pod b/doc/man1/openssl.pod index f075e21..791bc52 100644 --- a/doc/man1/openssl.pod +++ b/doc/man1/openssl.pod @@ -612,7 +612,7 @@ Note that the parsing is simple and might fail to parse some legal data. =back The options to specify the format are as follows. Refer to the individual -manpage to see which options are accepted. +man page to see which options are accepted. =over 4 diff --git a/doc/man3/ASYNC_WAIT_CTX_new.pod b/doc/man3/ASYNC_WAIT_CTX_new.pod index c95ceb7..f1d6a02 100644 --- a/doc/man3/ASYNC_WAIT_CTX_new.pod +++ b/doc/man3/ASYNC_WAIT_CTX_new.pod @@ -130,7 +130,7 @@ descriptor is not appropriate. ASYNC_WAIT_CTX_set_callback() sets the callback and the callback argument. The callback will be called to notify user code when an engine completes a cryptography operation. It is a requirement that the callback function is small -and non-blocking as it will be run in the context of a polling mechanism or an +and nonblocking as it will be run in the context of a polling mechanism or an interrupt. ASYNC_WAIT_CTX_get_callback() returns the callback set in the B<ASYNC_WAIT_CTX> diff --git a/doc/man3/BIO_connect.pod b/doc/man3/BIO_connect.pod index 9e0d972..3d51720 100644 --- a/doc/man3/BIO_connect.pod +++ b/doc/man3/BIO_connect.pod @@ -55,7 +55,7 @@ Enables regular sending of keep-alive messages. =item BIO_SOCK_NONBLOCK -Sets the socket to non-blocking mode. +Sets the socket to nonblocking mode. =item BIO_SOCK_NODELAY diff --git a/doc/man3/BIO_f_ssl.pod b/doc/man3/BIO_f_ssl.pod index 61d23c9..6a21e0c 100644 --- a/doc/man3/BIO_f_ssl.pod +++ b/doc/man3/BIO_f_ssl.pod @@ -102,7 +102,7 @@ If domain name resolution yields multiple IP addresses all of them are tried after connect() failures. The function returns 1 if the connection was established successfully. A zero or negative value is returned if the connection could not be established. -The call BIO_should_retry() should be used for non-blocking connect BIOs +The call BIO_should_retry() should be used for nonblocking connect BIOs to determine if the call should be retried. If a connection has already been established this call has no effect. diff --git a/doc/man3/BIO_read.pod b/doc/man3/BIO_read.pod index 293c130..ccd1651 100644 --- a/doc/man3/BIO_read.pod +++ b/doc/man3/BIO_read.pod @@ -55,7 +55,7 @@ NUL is not included in the length returned by BIO_gets(). =head1 NOTES A 0 or -1 return is not necessarily an indication of an error. In -particular when the source/sink is non-blocking or of a certain type +particular when the source/sink is nonblocking or of a certain type it may merely be an indication that no data is currently available and that the application should retry the operation later. diff --git a/doc/man3/BIO_s_accept.pod b/doc/man3/BIO_s_accept.pod index e6ad95b..6c091bb 100644 --- a/doc/man3/BIO_s_accept.pod +++ b/doc/man3/BIO_s_accept.pod @@ -143,7 +143,7 @@ however because the accept BIO will still accept additional incoming connections. This can be resolved by using BIO_pop() (see above) and freeing up the accept BIO after the initial connection. -If the underlying accept socket is non-blocking and BIO_do_accept() is +If the underlying accept socket is nonblocking and BIO_do_accept() is called to await an incoming connection it is possible for BIO_should_io_special() with the reason BIO_RR_ACCEPT. If this happens then it is an indication that an accept attempt would block: the application diff --git a/doc/man3/BIO_s_bio.pod b/doc/man3/BIO_s_bio.pod index cf25538..653fe47 100644 --- a/doc/man3/BIO_s_bio.pod +++ b/doc/man3/BIO_s_bio.pod @@ -167,7 +167,7 @@ without having to go through the SSL-interface. ... As the BIO pair will only buffer the data and never directly access the -connection, it behaves non-blocking and will return as soon as the write +connection, it behaves nonblocking and will return as soon as the write buffer is full or the read buffer is drained. Then the application has to flush the write buffer and/or fill the read buffer. diff --git a/doc/man3/BIO_socket_wait.pod b/doc/man3/BIO_socket_wait.pod index b00a878..f1050f8 100644 --- a/doc/man3/BIO_socket_wait.pod +++ b/doc/man3/BIO_socket_wait.pod @@ -34,7 +34,7 @@ Via B<nap_milliseconds> the caller determines the polling granularity. BIO_do_connect_retry() connects via the given B<bio>. It retries BIO_do_connect() as far as needed to reach a definite outcome, i.e., connection succeeded, timeout has been reached, or an error occurred. -For non-blocking and potentially even non-socket BIOs it polls +For nonblocking and potentially even non-socket BIOs it polls every B<nap_milliseconds> and sleeps in between using BIO_wait(). If B<nap_milliseconds> is < 0 then a default value of 100 ms is used. If the B<timeout> parameter is > 0 this indicates the maximum number of seconds diff --git a/doc/man3/BN_add.pod b/doc/man3/BN_add.pod index 1fae2ee..6f9b923 100644 --- a/doc/man3/BN_add.pod +++ b/doc/man3/BN_add.pod @@ -68,16 +68,16 @@ For division by powers of 2, use BN_rshift(3). BN_mod() corresponds to BN_div() with I<dv> set to B<NULL>. -BN_nnmod() reduces I<a> modulo I<m> and places the non-negative +BN_nnmod() reduces I<a> modulo I<m> and places the nonnegative remainder in I<r>. -BN_mod_add() adds I<a> to I<b> modulo I<m> and places the non-negative +BN_mod_add() adds I<a> to I<b> modulo I<m> and places the nonnegative result in I<r>. BN_mod_sub() subtracts I<b> from I<a> modulo I<m> and places the -non-negative result in I<r>. +nonnegative result in I<r>. -BN_mod_mul() multiplies I<a> by I<b> and finds the non-negative +BN_mod_mul() multiplies I<a> by I<b> and finds the nonnegative remainder respective to modulus I<m> (C<r=(a*b) mod m>). I<r> may be the same B<BIGNUM> as I<a> or I<b>. For more efficient algorithms for repeated computations using the same modulus, see diff --git a/doc/man3/BN_generate_prime.pod b/doc/man3/BN_generate_prime.pod index cdd7ed0..9827499 100644 --- a/doc/man3/BN_generate_prime.pod +++ b/doc/man3/BN_generate_prime.pod @@ -148,7 +148,7 @@ BN_is_prime_fasttest() and BN_is_prime() behave just like BN_is_prime_fasttest_ex() and BN_is_prime_ex() respectively, but with the old style call back. -B<ctx> is a pre-allocated B<BN_CTX> (to save the overhead of allocating and +B<ctx> is a preallocated B<BN_CTX> (to save the overhead of allocating and freeing the structure in a loop), or B<NULL>. If the trial division is done, and no divisors are found and B<cb> diff --git a/doc/man3/BN_mod_mul_montgomery.pod b/doc/man3/BN_mod_mul_montgomery.pod index 5cb2c2c..24109e2 100644 --- a/doc/man3/BN_mod_mul_montgomery.pod +++ b/doc/man3/BN_mod_mul_montgomery.pod @@ -49,7 +49,7 @@ the result in I<r>. BN_from_montgomery() performs the Montgomery reduction I<r> = I<a>*R^-1. BN_to_montgomery() computes Mont(I<a>,R^2), i.e. I<a>*R. -Note that I<a> must be non-negative and smaller than the modulus. +Note that I<a> must be nonnegative and smaller than the modulus. For all functions, I<ctx> is a previously allocated B<BN_CTX> used for temporary variables. diff --git a/doc/man3/BN_set_bit.pod b/doc/man3/BN_set_bit.pod index 24f7723..323eb7d 100644 --- a/doc/man3/BN_set_bit.pod +++ b/doc/man3/BN_set_bit.pod @@ -37,11 +37,11 @@ BN_mask_bits() truncates B<a> to an B<n> bit number shorter than B<n> bits. BN_lshift() shifts B<a> left by B<n> bits and places the result in -B<r> (C<r=a*2^n>). Note that B<n> must be non-negative. BN_lshift1() shifts +B<r> (C<r=a*2^n>). Note that B<n> must be nonnegative. BN_lshift1() shifts B<a> left by one and places the result in B<r> (C<r=2*a>). BN_rshift() shifts B<a> right by B<n> bits and places the result in -B<r> (C<r=a/2^n>). Note that B<n> must be non-negative. BN_rshift1() shifts +B<r> (C<r=a/2^n>). Note that B<n> must be nonnegative. BN_rshift1() shifts B<a> right by one and places the result in B<r> (C<r=a/2>). For the shift functions, B<r> and B<a> may be the same variable. diff --git a/doc/man3/DTLSv1_listen.pod b/doc/man3/DTLSv1_listen.pod index aa20918..13f6f1f 100644 --- a/doc/man3/DTLSv1_listen.pod +++ b/doc/man3/DTLSv1_listen.pod @@ -98,7 +98,7 @@ will be set up ready to continue the handshake. the B<peer> value will also be filled in. A return value of 0 indicates a non-fatal error. This could (for -example) be because of non-blocking IO, or some invalid message having been +example) be because of nonblocking IO, or some invalid message having been received from a peer. Errors may be placed on the OpenSSL error queue with further information if appropriate. Typically user code is expected to retry the call to DTLSv1_listen() in the event of a non-fatal error. diff --git a/doc/man3/ERR_new.pod b/doc/man3/ERR_new.pod index e1c71be..ada27ed 100644 --- a/doc/man3/ERR_new.pod +++ b/doc/man3/ERR_new.pod @@ -49,7 +49,7 @@ do not return any values. =head1 NOTES The library number is unique to each unit that records errors. -OpenSSL has a number of pre-allocated ones for its own uses, but +OpenSSL has a number of preallocated ones for its own uses, but others may allocate their own library number dynamically with L<ERR_get_next_error_library(3)>. diff --git a/doc/man3/EVP_PKEY_gen.pod b/doc/man3/EVP_PKEY_gen.pod index 212ea2a..979de86 100644 --- a/doc/man3/EVP_PKEY_gen.pod +++ b/doc/man3/EVP_PKEY_gen.pod @@ -75,7 +75,7 @@ generation callback. The function EVP_PKEY_CTX_get_keygen_info() returns parameters associated with the generation operation. If I<idx> is -1 the total number of parameters available is returned. Any non negative value returns the value of -that parameter. EVP_PKEY_CTX_gen_keygen_info() with a non-negative value for +that parameter. EVP_PKEY_CTX_gen_keygen_info() with a nonnegative value for I<idx> should only be called within the generation callback. If the callback returns 0 then the key generation operation is aborted and an diff --git a/doc/man3/OPENSSL_init_crypto.pod b/doc/man3/OPENSSL_init_crypto.pod index 0b8f901..bed722a 100644 --- a/doc/man3/OPENSSL_init_crypto.pod +++ b/doc/man3/OPENSSL_init_crypto.pod @@ -40,13 +40,13 @@ needs so no explicit initialisation is required. Similarly it will also automatically deinitialise as required. However, there may be situations when explicit initialisation is desirable or -needed, for example when some non-default initialisation is required. The +needed, for example when some nondefault initialisation is required. The function OPENSSL_init_crypto() can be used for this purpose for libcrypto (see also L<OPENSSL_init_ssl(3)> for the libssl equivalent). Numerous internal OpenSSL functions call OPENSSL_init_crypto(). -Therefore, in order to perform non-default initialisation, +Therefore, in order to perform nondefault initialisation, OPENSSL_init_crypto() MUST be called by application code prior to any other OpenSSL function calls. @@ -105,7 +105,7 @@ used by calling OPENSSL_config(). This is a default option. Note that in OpenSSL 1.1.1 this was the default for libssl but not for libcrypto (see L<OPENSSL_init_ssl(3)> for further details about libssl initialisation). -In OpenSSL 1.1.0 this was a non-default option for both libssl and libcrypto. +In OpenSSL 1.1.0 this was a nondefault option for both libssl and libcrypto. See the description of OPENSSL_INIT_new(), below. =item OPENSSL_INIT_NO_LOAD_CONFIG @@ -241,10 +241,10 @@ The filename, application name, and flags can be customized by providing a non-null B<OPENSSL_INIT_SETTINGS> object. The object can be allocated via B<OPENSSL_INIT_new()>. The B<OPENSSL_INIT_set_config_filename()> function can be used to specify a -non-default filename, which is copied and need not refer to persistent storage. +nondefault filename, which is copied and need not refer to persistent storage. Similarly, OPENSSL_INIT_set_config_appname() can be used to specify a -non-default application name. -Finally, OPENSSL_INIT_set_file_flags can be used to specify non-default flags. +nondefault application name. +Finally, OPENSSL_INIT_set_file_flags can be used to specify nondefault flags. If the B<CONF_MFLAGS_IGNORE_RETURN_CODES> flag is not included, any errors in the configuration file will cause an error return from B<OPENSSL_init_crypto> or indirectly L<OPENSSL_init_ssl(3)>. diff --git a/doc/man3/OPENSSL_init_ssl.pod b/doc/man3/OPENSSL_init_ssl.pod index d5a771b..ce6f230 100644 --- a/doc/man3/OPENSSL_init_ssl.pod +++ b/doc/man3/OPENSSL_init_ssl.pod @@ -23,14 +23,14 @@ needs so no explicit initialisation is required. Similarly it will also automatically deinitialise as required. However, there may be situations when explicit initialisation is desirable or -needed, for example when some non-default initialisation is required. The +needed, for example when some nondefault initialisation is required. The function OPENSSL_init_ssl() can be used for this purpose. Calling this function will explicitly initialise BOTH libcrypto and libssl. To explicitly initialise ONLY libcrypto see the L<OPENSSL_init_crypto(3)> function. Numerous internal OpenSSL functions call OPENSSL_init_ssl(). -Therefore, in order to perform non-default initialisation, +Therefore, in order to perform nondefault initialisation, OPENSSL_init_ssl() MUST be called by application code prior to any other OpenSSL function calls. diff --git a/doc/man3/OSSL_CMP_CTX_new.pod b/doc/man3/OSSL_CMP_CTX_new.pod index e8237b4..cb2d68a 100644 --- a/doc/man3/OSSL_CMP_CTX_new.pod +++ b/doc/man3/OSSL_CMP_CTX_new.pod @@ -579,7 +579,7 @@ X.509 certificates received in the caPubs field of last received certificate response message IP/CP/KUP. OSSL_CMP_CTX_get1_extraCertsIn() returns a pointer to a duplicate of the stack -of X.509 certificates received in the last received non-empty extraCerts field. +of X.509 certificates received in the last received nonempty extraCerts field. Returns an empty stack if no extraCerts have been received in the current transaction. diff --git a/doc/man3/OSSL_CRMF_MSG_get0_tmpl.pod b/doc/man3/OSSL_CRMF_MSG_get0_tmpl.pod index b760db1..8e8bd72 100644 --- a/doc/man3/OSSL_CRMF_MSG_get0_tmpl.pod +++ b/doc/man3/OSSL_CRMF_MSG_get0_tmpl.pod @@ -59,7 +59,7 @@ OSSL_CRMF_MSG_get_certReqId() retrieves the certReqId of B<crm>. =head1 RETURN VALUES OSSL_CRMF_MSG_get_certReqId() returns the certificate request ID as a -non-negative integer or -1 on error. +nonnegative integer or -1 on error. All other functions return a pointer with the intended result or NULL on error. diff --git a/doc/man3/RAND_load_file.pod b/doc/man3/RAND_load_file.pod index cf46776..a5e146c 100644 --- a/doc/man3/RAND_load_file.pod +++ b/doc/man3/RAND_load_file.pod @@ -17,7 +17,7 @@ RAND_load_file, RAND_write_file, RAND_file_name - PRNG seed file =head1 DESCRIPTION RAND_load_file() reads a number of bytes from file B<filename> and -adds them to the PRNG. If B<max_bytes> is non-negative, +adds them to the PRNG. If B<max_bytes> is nonnegative, up to B<max_bytes> are read; if B<max_bytes> is -1, the complete file is read. Do not load the same file multiple times unless its contents have diff --git a/doc/man3/RSA_blinding_on.pod b/doc/man3/RSA_blinding_on.pod index db06b2f..cd57839 100644 --- a/doc/man3/RSA_blinding_on.pod +++ b/doc/man3/RSA_blinding_on.pod @@ -19,7 +19,7 @@ measure the time of RSA decryption or signature operations, blinding must be used to protect the RSA operation from that attack. RSA_blinding_on() turns blinding on for key B<rsa> and generates a -random blinding factor. B<ctx> is B<NULL> or a pre-allocated and +random blinding factor. B<ctx> is B<NULL> or a preallocated and initialized B<BN_CTX>. RSA_blinding_off() turns blinding off and frees the memory used for diff --git a/doc/man3/SSL_CTX_dane_enable.pod b/doc/man3/SSL_CTX_dane_enable.pod index f5bd8a4..4ca9e97 100644 --- a/doc/man3/SSL_CTX_dane_enable.pod +++ b/doc/man3/SSL_CTX_dane_enable.pod @@ -122,7 +122,7 @@ SSL_get0_dane_tlsa() can be used to retrieve the fields of the TLSA record that matched the peer certificate chain. The return value indicates the match depth or failure to match just as with SSL_get0_dane_authority(). -When the return value is non-negative, the storage pointed to by the B<usage>, +When the return value is nonnegative, the storage pointed to by the B<usage>, B<selector>, B<mtype> and B<data> parameters is updated to the corresponding TLSA record fields. The B<data> field is in binary wire form, and is therefore not NUL-terminated, @@ -173,7 +173,7 @@ certificate or a public key that fails to parse. The functions SSL_get0_dane_authority() and SSL_get0_dane_tlsa() return a negative value when DANE authentication failed or was not enabled, a -non-negative value indicates the chain depth at which the TLSA record matched a +nonnegative value indicates the chain depth at which the TLSA record matched a chain certificate, or the depth of the top-most certificate, when the TLSA record is a full public key that is its signer. diff --git a/doc/man3/SSL_CTX_set_alpn_select_cb.pod b/doc/man3/SSL_CTX_set_alpn_select_cb.pod index 9a7a934..62da53c 100644 --- a/doc/man3/SSL_CTX_set_alpn_select_cb.pod +++ b/doc/man3/SSL_CTX_set_alpn_select_cb.pod @@ -114,7 +114,7 @@ provided by the callback. =head1 NOTES The protocol-lists must be in wire-format, which is defined as a vector of -non-empty, 8-bit length-prefixed, byte strings. The length-prefix byte is not +nonempty, 8-bit length-prefixed, byte strings. The length-prefix byte is not included in the length. Each string is limited to 255 bytes. A byte-string length of 0 is invalid. A truncated byte-string is invalid. The length of the vector is not in the vector itself, but in a separate variable. diff --git a/doc/man3/SSL_CTX_set_info_callback.pod b/doc/man3/SSL_CTX_set_info_callback.pod index 399a83c..19973b2 100644 --- a/doc/man3/SSL_CTX_set_info_callback.pod +++ b/doc/man3/SSL_CTX_set_info_callback.pod @@ -64,7 +64,7 @@ per state in some situations. Callback has been called to indicate exit of a handshake function. This will happen after the end of a handshake, but may happen at other times too such as -on error or when IO might otherwise block and non-blocking is being used. +on error or when IO might otherwise block and nonblocking is being used. =item SSL_CB_READ diff --git a/doc/man3/SSL_CTX_set_max_cert_list.pod b/doc/man3/SSL_CTX_set_max_cert_list.pod index 5b82cda..9f44673 100644 --- a/doc/man3/SSL_CTX_set_max_cert_list.pod +++ b/doc/man3/SSL_CTX_set_max_cert_list.pod @@ -39,7 +39,7 @@ received from a faulty or malicious peer, a maximum size for the certificate chain is set. The default value for the maximum certificate chain size is 100kB (30kB -on the 16bit DOS platform). This should be sufficient for usual certificate +on the 16-bit DOS platform). This should be sufficient for usual certificate chains (OpenSSL's default maximum chain length is 10, see L<SSL_CTX_set_verify(3)>, and certificates without special extensions have a typical size of 1-2kB). diff --git a/doc/man3/SSL_CTX_set_mode.pod b/doc/man3/SSL_CTX_set_mode.pod index 6cdf836..160110f 100644 --- a/doc/man3/SSL_CTX_set_mode.pod +++ b/doc/man3/SSL_CTX_set_mode.pod @@ -50,8 +50,8 @@ the behaviour of write(). Make it possible to retry SSL_write_ex() or SSL_write() with changed buffer location (the buffer contents must stay the same). This is not the default to -avoid the misconception that non-blocking SSL_write() behaves like -non-blocking write(). +avoid the misconception that nonblocking SSL_write() behaves like +nonblocking write(). =item SSL_MODE_AUTO_RETRY @@ -64,9 +64,9 @@ If such a non-application data record was processed, the flag B<SSL_MODE_AUTO_RETRY> causes it to try to process the next record instead of returning. -In a non-blocking environment applications must be prepared to handle +In a nonblocking environment applications must be prepared to handle incomplete read/write operations. -Setting B<SSL_MODE_AUTO_RETRY> for a non-blocking B<BIO> will process +Setting B<SSL_MODE_AUTO_RETRY> for a nonblocking B<BIO> will process non-application data records until either no more data is available or an application data record has been processed. diff --git a/doc/man3/SSL_CTX_set_options.pod b/doc/man3/SSL_CTX_set_options.pod index adc646d..68a1552 100644 --- a/doc/man3/SSL_CTX_set_options.pod +++ b/doc/man3/SSL_CTX_set_options.pod @@ -272,7 +272,7 @@ application data in a static buffer until it is overwritten by the next portion of data. When enabling SSL_OP_CLEANSE_PLAINTEXT deciphered application data is cleansed by calling OPENSSL_cleanse(3) after passing data to the application. Data is also cleansed when -releasing the connection (eg. L<SSL_free(3)>). +releasing the connection (e.g. L<SSL_free(3)>). Since OpenSSL only cleanses internal buffers, the application is still responsible for cleansing all other buffers. Most notably, this diff --git a/doc/man3/SSL_CTX_set_read_ahead.pod b/doc/man3/SSL_CTX_set_read_ahead.pod index 97343b9..0990079 100644 --- a/doc/man3/SSL_CTX_set_read_ahead.pod +++ b/doc/man3/SSL_CTX_set_read_ahead.pod @@ -21,7 +21,7 @@ SSL_CTX_get_default_read_ahead =head1 DESCRIPTION SSL_CTX_set_read_ahead() and SSL_set_read_ahead() set whether we should read as -many input bytes as possible (for non-blocking reads) or not. For example if +many input bytes as possible (for nonblocking reads) or not. For example if B<x> bytes are currently required by OpenSSL, but B<y> bytes are available from the underlying BIO (where B<y> > B<x>), then OpenSSL will read all B<y> bytes into its buffer (providing that the buffer is large enough) if reading ahead is diff --git a/doc/man3/SSL_CTX_set_srp_password.pod b/doc/man3/SSL_CTX_set_srp_password.pod index 4d806bc..347bb3b 100644 --- a/doc/man3/SSL_CTX_set_srp_password.pod +++ b/doc/man3/SSL_CTX_set_srp_password.pod @@ -46,7 +46,7 @@ SSL_get_srp_userinfo =head1 DESCRIPTION These functions provide access to SRP (Secure Remote Password) parameters, -an alternate authentication mechanism for TLS. SRP allows the use of user names +an alternate authentication mechanism for TLS. SRP allows the use of usernames and passwords over unencrypted channels without revealing the password to an eavesdropper. SRP also supplies a shared secret at the end of the authentication sequence that can be used to generate encryption keys. diff --git a/doc/man3/SSL_accept.pod b/doc/man3/SSL_accept.pod index eda0a35..8577cc8 100644 --- a/doc/man3/SSL_accept.pod +++ b/doc/man3/SSL_accept.pod @@ -23,14 +23,14 @@ The behaviour of SSL_accept() depends on the underlying BIO. If the underlying BIO is B<blocking>, SSL_accept() will only return once the handshake has been finished or an error occurred. -If the underlying BIO is B<non-blocking>, SSL_accept() will also return +If the underlying BIO is B<nonblocking>, SSL_accept() will also return when the underlying BIO could not satisfy the needs of SSL_accept() to continue the handshake, indicating the problem by the return value -1. In this case a call to SSL_get_error() with the return value of SSL_accept() will yield B<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after taking appropriate action to satisfy the needs of SSL_accept(). -The action depends on the underlying BIO. When using a non-blocking socket, +The action depends on the underlying BIO. When using a nonblocking socket, nothing is to be done, but select() can be used to check for the required condition. When using a buffering BIO, like a BIO pair, data must be written into or retrieved out of the BIO before being able to continue. @@ -57,7 +57,7 @@ established. The TLS/SSL handshake was not successful because a fatal error occurred either at the protocol level or a connection failure occurred. The shutdown was not clean. It can also occur if action is needed to continue the operation -for non-blocking BIOs. Call SSL_get_error() with the return value B<ret> +for nonblocking BIOs. Call SSL_get_error() with the return value B<ret> to find out the reason. =back diff --git a/doc/man3/SSL_alloc_buffers.pod b/doc/man3/SSL_alloc_buffers.pod index 4f98543..d27da05 100644 --- a/doc/man3/SSL_alloc_buffers.pod +++ b/doc/man3/SSL_alloc_buffers.pod @@ -22,7 +22,7 @@ control when buffers are freed and allocated. After freeing the buffers, the buffers are automatically reallocated upon a new read or write. The SSL_alloc_buffers() does not need to be called, but -can be used to make sure the buffers are pre-allocated. This can be used to +can be used to make sure the buffers are preallocated. This can be used to avoid allocation during data processing or with CRYPTO_set_mem_functions() to control where and how buffers are allocated. diff --git a/doc/man3/SSL_connect.pod b/doc/man3/SSL_connect.pod index b74aa1d..4e9bd9c 100644 --- a/doc/man3/SSL_connect.pod +++ b/doc/man3/SSL_connect.pod @@ -23,14 +23,14 @@ The behaviour of SSL_connect() depends on the underlying BIO. If the underlying BIO is B<blocking>, SSL_connect() will only return once the handshake has been finished or an error occurred. -If the underlying BIO is B<non-blocking>, SSL_connect() will also return +If the underlying BIO is B<nonblocking>, SSL_connect() will also return when the underlying BIO could not satisfy the needs of SSL_connect() to continue the handshake, indicating the problem by the return value -1. In this case a call to SSL_get_error() with the return value of SSL_connect() will yield B<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after taking appropriate action to satisfy the needs of SSL_connect(). -The action depends on the underlying BIO. When using a non-blocking socket, +The action depends on the underlying BIO. When using a nonblocking socket, nothing is to be done, but select() can be used to check for the required condition. When using a buffering BIO, like a BIO pair, data must be written into or retrieved out of the BIO before being able to continue. @@ -72,7 +72,7 @@ established. The TLS/SSL handshake was not successful, because a fatal error occurred either at the protocol level or a connection failure occurred. The shutdown was not clean. It can also occur if action is needed to continue the operation -for non-blocking BIOs. Call SSL_get_error() with the return value B<ret> +for nonblocking BIOs. Call SSL_get_error() with the return value B<ret> to find out the reason. =back diff --git a/doc/man3/SSL_do_handshake.pod b/doc/man3/SSL_do_handshake.pod index 55a11cc..819576b 100644 --- a/doc/man3/SSL_do_handshake.pod +++ b/doc/man3/SSL_do_handshake.pod @@ -25,13 +25,13 @@ The behaviour of SSL_do_handshake() depends on the underlying BIO. If the underlying BIO is B<blocking>, SSL_do_handshake() will only return once the handshake has been finished or an error occurred. -If the underlying BIO is B<non-blocking>, SSL_do_handshake() will also return +If the underlying BIO is B<nonblocking>, SSL_do_handshake() will also return when the underlying BIO could not satisfy the needs of SSL_do_handshake() to continue the handshake. In this case a call to SSL_get_error() with the return value of SSL_do_handshake() will yield B<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after taking appropriate action to satisfy the needs of SSL_do_handshake(). -The action depends on the underlying BIO. When using a non-blocking socket, +The action depends on the underlying BIO. When using a nonblocking socket, nothing is to be done, but select() can be used to check for the required condition. When using a buffering BIO, like a BIO pair, data must be written into or retrieved out of the BIO before being able to continue. @@ -58,7 +58,7 @@ established. The TLS/SSL handshake was not successful because a fatal error occurred either at the protocol level or a connection failure occurred. The shutdown was not clean. It can also occur if action is needed to continue the operation -for non-blocking BIOs. Call SSL_get_error() with the return value B<ret> +for nonblocking BIOs. Call SSL_get_error() with the return value B<ret> to find out the reason. =back diff --git a/doc/man3/SSL_get_error.pod b/doc/man3/SSL_get_error.pod index 0f2b109..c52fd04 100644 --- a/doc/man3/SSL_get_error.pod +++ b/doc/man3/SSL_get_error.pod @@ -61,7 +61,7 @@ is set. See L<SSL_CTX_set_options(3)> for more details. The operation did not complete and can be retried later. B<SSL_ERROR_WANT_READ> is returned when the last operation was a read -operation from a non-blocking B<BIO>. +operation from a nonblocking B<BIO>. It means that not enough data was available at this time to complete the operation. If at a later time the underlying B<BIO> has data available for reading the same @@ -73,7 +73,7 @@ for a blocking B<BIO>. See L<SSL_read(3)> for more information. B<SSL_ERROR_WANT_WRITE> is returned when the last operation was a write -to a non-blocking B<BIO> and it was unable to sent all data to the B<BIO>. +to a nonblocking B<BIO> and it was unable to sent all data to the B<BIO>. When the B<BIO> is writable again, the same function can be called again. Note that the retry may again lead to an B<SSL_ERROR_WANT_READ> or diff --git a/doc/man3/SSL_read.pod b/doc/man3/SSL_read.pod index 3cbab30..0bfc2a4 100644 --- a/doc/man3/SSL_read.pod +++ b/doc/man3/SSL_read.pod @@ -72,7 +72,7 @@ not set. Note that if B<SSL_MODE_AUTO_RETRY> is set and only non-application data is available the call will hang. -If the underlying BIO is B<non-blocking>, a read function will also return when +If the underlying BIO is B<nonblocking>, a read function will also return when the underlying BIO could not satisfy the needs of the function to continue the operation. In this case a call to L<SSL_get_error(3)> with the @@ -83,7 +83,7 @@ a read function can also cause write operations. The calling process then must repeat the call after taking appropriate action to satisfy the needs of the read function. The action depends on the underlying BIO. -When using a non-blocking socket, nothing is to be done, but select() can be +When using a nonblocking socket, nothing is to be done, but select() can be used to check for the required condition. When using a buffering BIO, like a BIO pair, data must be written into or retrieved out of the BIO before being able to continue. diff --git a/doc/man3/SSL_set1_host.pod b/doc/man3/SSL_set1_host.pod index 1ceb5dd..6278f89 100644 --- a/doc/man3/SSL_set1_host.pod +++ b/doc/man3/SSL_set1_host.pod @@ -21,7 +21,7 @@ These functions configure server hostname checks in the SSL client. SSL_set1_host() sets the expected DNS hostname to B<name> clearing any previously specified hostname. If B<name> is NULL or the empty string, the list of hostnames is cleared and name -checks are not performed on the peer certificate. When a non-empty +checks are not performed on the peer certificate. When a nonempty B<name> is specified, certificate verification automatically checks the peer hostname via L<X509_check_host(3)> with B<flags> as specified via SSL_set_hostflags(). Clients that enable DANE TLSA authentication diff --git a/doc/man3/SSL_set_async_callback.pod b/doc/man3/SSL_set_async_callback.pod index 5a0bd2b..9de735f 100644 --- a/doc/man3/SSL_set_async_callback.pod +++ b/doc/man3/SSL_set_async_callback.pod @@ -87,7 +87,7 @@ a parameter. =item 7. The callback function should then run. Note: it is a requirement that the -callback function is small and non-blocking as it will be run in the context of +callback function is small and nonblocking as it will be run in the context of a polling mechanism or an interrupt. =item 8. diff --git a/doc/man3/SSL_set_bio.pod b/doc/man3/SSL_set_bio.pod index 90dfcc9..d88e683 100644 --- a/doc/man3/SSL_set_bio.pod +++ b/doc/man3/SSL_set_bio.pod @@ -16,7 +16,7 @@ SSL_set_bio, SSL_set0_rbio, SSL_set0_wbio - connect the SSL object with a BIO SSL_set0_rbio() connects the BIO B<rbio> for the read operations of the B<ssl> object. The SSL engine inherits the behaviour of B<rbio>. If the BIO is -non-blocking then the B<ssl> object will also have non-blocking behaviour. This +nonblocking then the B<ssl> object will also have nonblocking behaviour. This function transfers ownership of B<rbio> to B<ssl>. It will be automatically freed using L<BIO_free_all(3)> when the B<ssl> is freed. On calling this function, any existing B<rbio> that was previously set will also be freed via a diff --git a/doc/man3/SSL_set_fd.pod b/doc/man3/SSL_set_fd.pod index 42d0f78..01c3623 100644 --- a/doc/man3/SSL_set_fd.pod +++ b/doc/man3/SSL_set_fd.pod @@ -20,8 +20,8 @@ socket file descriptor of a network connection. When performing the operation, a B<socket BIO> is automatically created to interface between the B<ssl> and B<fd>. The BIO and hence the SSL engine -inherit the behaviour of B<fd>. If B<fd> is non-blocking, the B<ssl> will -also have non-blocking behaviour. +inherit the behaviour of B<fd>. If B<fd> is nonblocking, the B<ssl> will +also have nonblocking behaviour. If there was already a BIO connected to B<ssl>, BIO_free() will be called (for both the reading and writing side, if different). diff --git a/doc/man3/SSL_shutdown.pod b/doc/man3/SSL_shutdown.pod index 34469ba..6797006 100644 --- a/doc/man3/SSL_shutdown.pod +++ b/doc/man3/SSL_shutdown.pod @@ -54,13 +54,13 @@ The behaviour of SSL_shutdown() additionally depends on the underlying BIO. If the underlying BIO is B<blocking>, SSL_shutdown() will only return once the handshake step has been finished or an error occurred. -If the underlying BIO is B<non-blocking>, SSL_shutdown() will also return +If the underlying BIO is B<nonblocking>, SSL_shutdown() will also return when the underlying BIO could not satisfy the needs of SSL_shutdown() to continue the handshake. In this case a call to SSL_get_error() with the return value of SSL_shutdown() will yield B<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after taking appropriate action to satisfy the needs of SSL_shutdown(). -The action depends on the underlying BIO. When using a non-blocking socket, +The action depends on the underlying BIO. When using a nonblocking socket, nothing is to be done, but select() can be used to check for the required condition. When using a buffering BIO, like a BIO pair, data must be written into or retrieved out of the BIO before being able to continue. @@ -150,7 +150,7 @@ and the peer's close_notify alert was received. The shutdown was not successful. Call L<SSL_get_error(3)> with the return value B<ret> to find out the reason. -It can occur if an action is needed to continue the operation for non-blocking +It can occur if an action is needed to continue the operation for nonblocking BIOs. It can also occur when not all data was read using SSL_read(). diff --git a/doc/man3/SSL_state_string.pod b/doc/man3/SSL_state_string.pod index 2d49409..465e425 100644 --- a/doc/man3/SSL_state_string.pod +++ b/doc/man3/SSL_state_string.pod @@ -26,11 +26,11 @@ maintained. Querying the state information is not very informative before or when a connection has been established. It however can be of significant interest during the handshake. -When using non-blocking sockets, the function call performing the handshake +When using nonblocking sockets, the function call performing the handshake may return with SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE condition, so that SSL_state_string[_long]() may be called. -For both blocking or non-blocking sockets, the details state information +For both blocking or nonblocking sockets, the details state information can be used within the info_callback function set with the SSL_set_info_callback() call. diff --git a/doc/man3/SSL_want.pod b/doc/man3/SSL_want.pod index 6fce429..65f056f 100644 --- a/doc/man3/SSL_want.pod +++ b/doc/man3/SSL_want.pod @@ -33,7 +33,7 @@ return values are similar to that of L<SSL_get_error(3)>. Unlike L<SSL_get_error(3)>, which also evaluates the error queue, the results are obtained by examining an internal state flag only. The information must therefore only be used for normal operation under -non-blocking I/O. Error conditions are not handled and must be treated +nonblocking I/O. Error conditions are not handled and must be treated using L<SSL_get_error(3)>. The result returned by SSL_want() should always be consistent with diff --git a/doc/man3/SSL_write.pod b/doc/man3/SSL_write.pod index 56a8c8b..ef1193c 100644 --- a/doc/man3/SSL_write.pod +++ b/doc/man3/SSL_write.pod @@ -45,7 +45,7 @@ before the first call to a write function. If the underlying BIO is B<blocking>, the write functions will only return, once the write operation has been finished or an error occurred. -If the underlying BIO is B<non-blocking> the write functions will also return +If the underlying BIO is B<nonblocking> the write functions will also return when the underlying BIO could not satisfy the needs of the function to continue the operation. In this case a call to L<SSL_get_error(3)> with the return value of the write function will yield B<SSL_ERROR_WANT_READ> @@ -53,7 +53,7 @@ or B<SSL_ERROR_WANT_WRITE>. As at any time a re-negotiation is possible, a call to a write function can also cause read operations! The calling process then must repeat the call after taking appropriate action to satisfy the needs of the write function. The action depends on the underlying BIO. When using a -non-blocking socket, nothing is to be done, but select() can be used to check +nonblocking socket, nothing is to be done, but select() can be used to check for the required condition. When using a buffering BIO, like a BIO pair, data must be written into or retrieved out of the BIO before being able to continue. diff --git a/doc/man3/X509_STORE_CTX_get_error.pod b/doc/man3/X509_STORE_CTX_get_error.pod index 474dd4d..e6a6b6b 100644 --- a/doc/man3/X509_STORE_CTX_get_error.pod +++ b/doc/man3/X509_STORE_CTX_get_error.pod @@ -38,7 +38,7 @@ it might be used in a verification callback to set an error based on additional checks. X509_STORE_CTX_get_error_depth() returns the B<depth> of the error. This is a -non-negative integer representing where in the certificate chain the error +nonnegative integer representing where in the certificate chain the error occurred. If it is zero it occurred in the end entity certificate, one if it is the certificate which signed the end entity certificate and so on. @@ -79,7 +79,7 @@ verification error B<n>. X509_STORE_CTX_get_error() returns B<X509_V_OK> or an error code. -X509_STORE_CTX_get_error_depth() returns a non-negative error depth. +X509_STORE_CTX_get_error_depth() returns a nonnegative error depth. X509_STORE_CTX_get_current_cert() returns the certificate which caused the error or B<NULL> if no certificate is relevant to the error. diff --git a/doc/man3/X509_check_host.pod b/doc/man3/X509_check_host.pod index 3c4ef8b..b541901 100644 --- a/doc/man3/X509_check_host.pod +++ b/doc/man3/X509_check_host.pod @@ -24,8 +24,8 @@ The validity of the certificate and its trust level has to be checked by other means. X509_check_host() checks if the certificate Subject Alternative -Name (SAN) or Subject CommonName (CN) matches the specified host -name, which must be encoded in the preferred name syntax described +Name (SAN) or Subject CommonName (CN) matches the specified hostname, +which must be encoded in the preferred name syntax described in section 3.5 of RFC 1034. By default, wildcards are supported and they match only in the left-most label; but they may match part of that label with an explicit prefix or suffix. For example, diff --git a/doc/man5/x509v3_config.pod b/doc/man5/x509v3_config.pod index 45c4d92..a16f862 100644 --- a/doc/man5/x509v3_config.pod +++ b/doc/man5/x509v3_config.pod @@ -105,7 +105,7 @@ They do not define the semantics of the extension. This is a multi-valued extension which indicates whether a certificate is a CA certificate. The first value is B<CA> followed by B<TRUE> or B<FALSE>. If B<CA> is B<TRUE> then an optional B<pathlen> name followed by a -non-negative value can be included. +nonnegative value can be included. For example: diff --git a/util/find-doc-nits b/util/find-doc-nits index 3558180..031076f 100755 --- a/util/find-doc-nits +++ b/util/find-doc-nits @@ -596,6 +596,7 @@ sub functionname_check { # This is from http://man7.org/linux/man-pages/man7/man-pages.7.html my %preferred_words = ( + '16bit' => '16-bit', 'a.k.a.' => 'aka', 'bitmask' => 'bit mask', 'builtin' => 'built-in', @@ -606,33 +607,40 @@ my %preferred_words = ( 'i-node' => 'inode', 'lower case' => 'lowercase', 'lower-case' => 'lowercase', + 'manpage' => 'man page', + 'non-blocking' => 'nonblocking', + 'non-default' => 'nondefault', + 'non-empty' => 'nonempty', + 'non-negative' => 'nonnegative', 'non-zero' => 'nonzero', 'path name' => 'pathname', + 'pre-allocated' => 'preallocated', 'pseudo-terminal' => 'pseudoterminal', - 'reserved port' => 'privileged port', - 'system port' => 'privileged port', - 'realtime' => 'real-time', 'real time' => 'real-time', + 'realtime' => 'real-time', + 'reserved port' => 'privileged port', 'runtime' => 'run time', 'saved group ID'=> 'saved set-group-ID', 'saved set-GID' => 'saved set-group-ID', - 'saved user ID' => 'saved set-user-ID', 'saved set-UID' => 'saved set-user-ID', + 'saved user ID' => 'saved set-user-ID', 'set-GID' => 'set-group-ID', - 'setgid' => 'set-group-ID', 'set-UID' => 'set-user-ID', + 'setgid' => 'set-group-ID', 'setuid' => 'set-user-ID', - 'super user' => 'superuser', - 'super-user' => 'superuser', + 'sub-system' => 'subsystem', 'super block' => 'superblock', 'super-block' => 'superblock', + 'super user' => 'superuser', + 'super-user' => 'superuser', + 'system port' => 'privileged port', 'time stamp' => 'timestamp', 'time zone' => 'timezone', 'upper case' => 'uppercase', 'upper-case' => 'uppercase', 'useable' => 'usable', - 'userspace' => 'user space', 'user name' => 'username', + 'userspace' => 'user space', 'zeroes' => 'zeros' ); |