From 8d92311c50e58dee074bbbf7fa390e592ee8df77 Mon Sep 17 00:00:00 2001 From: Rich Salz Date: Sat, 11 Mar 2017 08:56:44 -0500 Subject: [PATCH] Fix many doc L<> errors Add 2017 copyright year Add missing typedef to NAME Remove ec(7) and bn(7) doc links Remove .pod link errors, bogus links, make a few typo corrections Fix some typo's in links and some missing items. Don't link to C runtime functions (See OPENSSL_malloc for example/precedent) Document ASN1_tag2str(), add a few typedef's that were missing from NAME Update doc-nits target; addresses https://github.com/openssl/openssl/pull/1900#issuecomment-259943891, Merge check-doc-links into find-doc-nits; if run regularly, would have found https://github.com/openssl/openssl/pull/2825 Reviewed-by: Richard Levitte (Merged from https://github.com/openssl/openssl/pull/2862) (cherry picked from commit 9e183d2271653cbba2d9cf56d40c1356705207aa) --- Configurations/unix-Makefile.tmpl | 6 +- doc/crypto/ASN1_STRING_print_ex.pod | 8 +- doc/crypto/BN_BLINDING_new.pod | 6 +- doc/crypto/BN_CTX_new.pod | 4 +- doc/crypto/BN_add.pod | 4 +- doc/crypto/BN_add_word.pod | 4 +- doc/crypto/BN_bn2bin.pod | 4 +- doc/crypto/BN_cmp.pod | 6 +- doc/crypto/BN_copy.pod | 4 +- doc/crypto/BN_generate_prime.pod | 4 +- doc/crypto/BN_mod_inverse.pod | 4 +- doc/crypto/BN_mod_mul_montgomery.pod | 4 +- doc/crypto/BN_mod_mul_reciprocal.pod | 4 +- doc/crypto/BN_new.pod | 4 +- doc/crypto/BN_num_bytes.pod | 4 +- doc/crypto/BN_rand.pod | 5 +- doc/crypto/BN_set_bit.pod | 4 +- doc/crypto/BN_swap.pod | 4 +- doc/crypto/BN_zero.pod | 4 +- doc/crypto/CONF_modules_load_file.pod | 3 +- doc/crypto/CRYPTO_get_ex_new_index.pod | 3 +- doc/crypto/ECPKParameters_print.pod | 4 +- doc/crypto/EC_GFp_simple_method.pod | 4 +- doc/crypto/EC_GROUP_copy.pod | 4 +- doc/crypto/EC_GROUP_new.pod | 4 +- doc/crypto/EC_KEY_get_enc_flags.pod | 4 +- doc/crypto/EC_KEY_new.pod | 4 +- doc/crypto/EC_POINT_add.pod | 4 +- doc/crypto/EC_POINT_new.pod | 4 +- doc/crypto/OPENSSL_init_crypto.pod | 4 +- doc/crypto/SCT_new.pod | 6 +- doc/crypto/SMIME_read_PKCS7.pod | 6 +- doc/crypto/UI_new.pod | 8 +- doc/crypto/X509_LOOKUP_hash_dir.pod | 7 +- doc/crypto/X509_digest.pod | 2 +- doc/crypto/ct.pod | 8 +- doc/crypto/d2i_PrivateKey.pod | 6 +- doc/crypto/x509.pod | 10 +- .../SSL_CTX_set_ct_validation_callback.pod | 7 +- doc/ssl/SSL_CTX_set_verify.pod | 14 +- doc/ssl/SSL_set_bio.pod | 18 +- doc/ssl/ssl.pod | 22 +- util/{find-doc-nits.pl => find-doc-nits} | 198 ++++++++++++++++-- 43 files changed, 311 insertions(+), 130 deletions(-) rename util/{find-doc-nits.pl => find-doc-nits} (54%) diff --git a/Configurations/unix-Makefile.tmpl b/Configurations/unix-Makefile.tmpl index 27b34b9824..6df1cce5a6 100644 --- a/Configurations/unix-Makefile.tmpl +++ b/Configurations/unix-Makefile.tmpl @@ -284,7 +284,7 @@ clean: libclean -$(RM) `find . -name '*{- $depext -}' -a \! -path "./.git/*"` -$(RM) `find . -name '*{- $objext -}' -a \! -path "./.git/*"` $(RM) core - $(RM) tags TAGS + $(RM) tags TAGS doc-nits $(RM) test/.rnd $(RM) openssl.pc libcrypto.pc libssl.pc -$(RM) `find . -type l -a \! -path "./.git/*"` @@ -581,6 +581,10 @@ update: generate errors ordinals generate: generate_apps generate_crypto_bn generate_crypto_objects \ generate_crypto_conf generate_crypto_asn1 +doc-nits: + (cd $(SRCDIR); $(PERL) util/find-doc-nits.pl -n ) >doc-nits + if [ -s doc-nits ] ; then cat doc-nits; rm doc-nits ; exit 1; fi + # Test coverage is a good idea for the future #coverage: $(PROGRAMS) $(TESTPROGRAMS) # ... diff --git a/doc/crypto/ASN1_STRING_print_ex.pod b/doc/crypto/ASN1_STRING_print_ex.pod index d2bf538f6b..a521f78ea9 100644 --- a/doc/crypto/ASN1_STRING_print_ex.pod +++ b/doc/crypto/ASN1_STRING_print_ex.pod @@ -2,7 +2,8 @@ =head1 NAME -ASN1_STRING_print_ex, ASN1_STRING_print_ex_fp, ASN1_STRING_print - ASN1_STRING output routines +ASN1_tag2str, ASN1_STRING_print_ex, ASN1_STRING_print_ex_fp, ASN1_STRING_print +- ASN1_STRING output routines =head1 SYNOPSIS @@ -12,6 +13,7 @@ ASN1_STRING_print_ex, ASN1_STRING_print_ex_fp, ASN1_STRING_print - ASN1_STRING o int ASN1_STRING_print_ex_fp(FILE *fp, const ASN1_STRING *str, unsigned long flags); int ASN1_STRING_print(BIO *out, const ASN1_STRING *str); + const char *ASN1_tag2str(int tag); =head1 DESCRIPTION @@ -26,6 +28,8 @@ ASN1_STRING_print() prints B to B but using a different format to ASN1_STRING_print_ex(). It replaces unprintable characters (other than CR, LF) with '.'. +ASN1_tag2str() returns a human-readable name of the specified ASN.1 B. + =head1 NOTES ASN1_STRING_print() is a legacy function which should be avoided in new applications. @@ -91,7 +95,7 @@ L =head1 COPYRIGHT -Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2002-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/BN_BLINDING_new.pod b/doc/crypto/BN_BLINDING_new.pod index 5f56aa3fc9..4229e754a1 100644 --- a/doc/crypto/BN_BLINDING_new.pod +++ b/doc/crypto/BN_BLINDING_new.pod @@ -105,10 +105,6 @@ BN_BLINDING_get_flags() returns the currently set B flags BN_BLINDING_create_param() returns the newly created B parameters or NULL on error. -=head1 SEE ALSO - -L - =head1 HISTORY BN_BLINDING_thread_id() was first introduced in OpenSSL 1.0.0, and it @@ -116,7 +112,7 @@ deprecates BN_BLINDING_set_thread_id() and BN_BLINDING_get_thread_id(). =head1 COPYRIGHT -Copyright 2005-2016 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2005-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/BN_CTX_new.pod b/doc/crypto/BN_CTX_new.pod index ca54590517..623fcd5692 100644 --- a/doc/crypto/BN_CTX_new.pod +++ b/doc/crypto/BN_CTX_new.pod @@ -57,7 +57,7 @@ replace use of BN_CTX_init with BN_CTX_new instead: =head1 SEE ALSO -L, L, L, +L, L, L =head1 HISTORY @@ -66,7 +66,7 @@ BN_CTX_init() was 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/crypto/BN_add.pod b/doc/crypto/BN_add.pod index 72cc09f67a..db3b0d45b4 100644 --- a/doc/crypto/BN_add.pod +++ b/doc/crypto/BN_add.pod @@ -112,12 +112,12 @@ The error codes can be obtained by L. =head1 SEE ALSO -L, L, L, +L, L, L, L =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/BN_add_word.pod b/doc/crypto/BN_add_word.pod index 35bdcf45c6..6c69bc485f 100644 --- a/doc/crypto/BN_add_word.pod +++ b/doc/crypto/BN_add_word.pod @@ -47,11 +47,11 @@ B<(BN_ULONG)-1> if an error occurred. =head1 SEE ALSO -L, L, L +L, L =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/BN_bn2bin.pod b/doc/crypto/BN_bn2bin.pod index b272010ba0..9e16c0d239 100644 --- a/doc/crypto/BN_bn2bin.pod +++ b/doc/crypto/BN_bn2bin.pod @@ -100,13 +100,13 @@ The error codes can be obtained by L. =head1 SEE ALSO -L, L, L, +L, L, L, L =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/BN_cmp.pod b/doc/crypto/BN_cmp.pod index ec005718a1..95d162ff29 100644 --- a/doc/crypto/BN_cmp.pod +++ b/doc/crypto/BN_cmp.pod @@ -35,13 +35,9 @@ of B and B. BN_is_zero(), BN_is_one() BN_is_word() and BN_is_odd() return 1 if the condition is true, 0 otherwise. -=head1 SEE ALSO - -L - =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/BN_copy.pod b/doc/crypto/BN_copy.pod index b044b98a0b..500f4b2ee5 100644 --- a/doc/crypto/BN_copy.pod +++ b/doc/crypto/BN_copy.pod @@ -55,11 +55,11 @@ by L. =head1 SEE ALSO -L, L +L =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/BN_generate_prime.pod b/doc/crypto/BN_generate_prime.pod index 0472b9b829..a4ef2302f6 100644 --- a/doc/crypto/BN_generate_prime.pod +++ b/doc/crypto/BN_generate_prime.pod @@ -175,7 +175,7 @@ Instead applications should create a BN_GENCB structure using BN_GENCB_new: =head1 SEE ALSO -L, L, L +L, L =head1 HISTORY @@ -184,7 +184,7 @@ and BN_GENCB_get_arg() were added 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/crypto/BN_mod_inverse.pod b/doc/crypto/BN_mod_inverse.pod index b4792add82..cb84a14098 100644 --- a/doc/crypto/BN_mod_inverse.pod +++ b/doc/crypto/BN_mod_inverse.pod @@ -27,11 +27,11 @@ NULL on error. The error codes can be obtained by L. =head1 SEE ALSO -L, L, L +L, L =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/BN_mod_mul_montgomery.pod b/doc/crypto/BN_mod_mul_montgomery.pod index bf1ef343cd..81056c76ac 100644 --- a/doc/crypto/BN_mod_mul_montgomery.pod +++ b/doc/crypto/BN_mod_mul_montgomery.pod @@ -71,7 +71,7 @@ outside the expected range. =head1 SEE ALSO -L, L, L, +L, L, L =head1 HISTORY @@ -80,7 +80,7 @@ BN_MONT_CTX_init() was 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/crypto/BN_mod_mul_reciprocal.pod b/doc/crypto/BN_mod_mul_reciprocal.pod index d0536cd95b..d480fed2d0 100644 --- a/doc/crypto/BN_mod_mul_reciprocal.pod +++ b/doc/crypto/BN_mod_mul_reciprocal.pod @@ -57,7 +57,7 @@ The error codes can be obtained by L. =head1 SEE ALSO -L, L, L, +L, L, L =head1 HISTORY @@ -66,7 +66,7 @@ BN_RECP_CTX_init() was 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/crypto/BN_new.pod b/doc/crypto/BN_new.pod index 0277614276..36bd00da28 100644 --- a/doc/crypto/BN_new.pod +++ b/doc/crypto/BN_new.pod @@ -44,7 +44,7 @@ BN_clear(), BN_free() and BN_clear_free() have no return values. =head1 SEE ALSO -L, L +L =head1 HISTORY @@ -52,7 +52,7 @@ BN_init() was removed in OpenSSL 1.1.0; use BN_new() instead. =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/BN_num_bytes.pod b/doc/crypto/BN_num_bytes.pod index 4680cf7a71..9e0465de54 100644 --- a/doc/crypto/BN_num_bytes.pod +++ b/doc/crypto/BN_num_bytes.pod @@ -46,12 +46,12 @@ more probability). =head1 SEE ALSO -L, L, L, +L, L, L =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/BN_rand.pod b/doc/crypto/BN_rand.pod index ae15ada7e5..7ae8e625f9 100644 --- a/doc/crypto/BN_rand.pod +++ b/doc/crypto/BN_rand.pod @@ -53,12 +53,11 @@ The error codes can be obtained by L. =head1 SEE ALSO -L, L, L, -L, L +L, L, L =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/BN_set_bit.pod b/doc/crypto/BN_set_bit.pod index 363227ade3..af02983c8f 100644 --- a/doc/crypto/BN_set_bit.pod +++ b/doc/crypto/BN_set_bit.pod @@ -55,11 +55,11 @@ can be obtained by L. =head1 SEE ALSO -L, L, L +L, L =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/BN_swap.pod b/doc/crypto/BN_swap.pod index fe7cc8482b..9f77f22744 100644 --- a/doc/crypto/BN_swap.pod +++ b/doc/crypto/BN_swap.pod @@ -14,11 +14,9 @@ BN_swap - exchange BIGNUMs BN_swap() exchanges the values of I and I. -L - =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/BN_zero.pod b/doc/crypto/BN_zero.pod index fadc21b7fd..91d48aad88 100644 --- a/doc/crypto/BN_zero.pod +++ b/doc/crypto/BN_zero.pod @@ -53,11 +53,11 @@ unsigned long but this value is also returned on error. =head1 SEE ALSO -L, L +L =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/CONF_modules_load_file.pod b/doc/crypto/CONF_modules_load_file.pod index 1149142210..4f02f52f6a 100644 --- a/doc/crypto/CONF_modules_load_file.pod +++ b/doc/crypto/CONF_modules_load_file.pod @@ -121,8 +121,7 @@ return value of the failing module (this will always be zero or negative). =head1 SEE ALSO -L, L, -L +L, L =head1 COPYRIGHT diff --git a/doc/crypto/CRYPTO_get_ex_new_index.pod b/doc/crypto/CRYPTO_get_ex_new_index.pod index 98085f525b..ede5fc14ce 100644 --- a/doc/crypto/CRYPTO_get_ex_new_index.pod +++ b/doc/crypto/CRYPTO_get_ex_new_index.pod @@ -52,6 +52,7 @@ The specific structures are: RSA ENGINE UI + UI_METHOD BIO Each is identified by an B define in the B @@ -151,7 +152,7 @@ dup_func() should return 0 for failure and 1 for success. =head1 COPYRIGHT -Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2015-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/ECPKParameters_print.pod b/doc/crypto/ECPKParameters_print.pod index c9c362835e..24b6bb9e04 100644 --- a/doc/crypto/ECPKParameters_print.pod +++ b/doc/crypto/ECPKParameters_print.pod @@ -28,13 +28,13 @@ return 1 for success and 0 if an error occurs. =head1 SEE ALSO -L, L, L, L, +L, L, L, L, L, L, L, =head1 COPYRIGHT -Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2013-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/EC_GFp_simple_method.pod b/doc/crypto/EC_GFp_simple_method.pod index 89c590eb2a..f283d8e71e 100644 --- a/doc/crypto/EC_GFp_simple_method.pod +++ b/doc/crypto/EC_GFp_simple_method.pod @@ -52,14 +52,14 @@ EC_METHOD_get_field_type returns an integer that identifies the type of field th =head1 SEE ALSO -L, L, L, L, +L, L, L, L, L, L, L, L =head1 COPYRIGHT -Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2013-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/EC_GROUP_copy.pod b/doc/crypto/EC_GROUP_copy.pod index 6b398dfefc..fd5f58c919 100644 --- a/doc/crypto/EC_GROUP_copy.pod +++ b/doc/crypto/EC_GROUP_copy.pod @@ -190,13 +190,13 @@ trinomial or pentanomial respectively. Alternatively in the event of an error a =head1 SEE ALSO -L, L, L, +L, L, L, L, L, L, L =head1 COPYRIGHT -Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2013-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/EC_GROUP_new.pod b/doc/crypto/EC_GROUP_new.pod index 25129100b6..2f658dc2c3 100644 --- a/doc/crypto/EC_GROUP_new.pod +++ b/doc/crypto/EC_GROUP_new.pod @@ -104,13 +104,13 @@ EC_GROUP_set_curve_GFp, EC_GROUP_get_curve_GFp, EC_GROUP_set_curve_GF2m, EC_GROU =head1 SEE ALSO -L, L, L, +L, L, L, L, L, L, L =head1 COPYRIGHT -Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2013-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/EC_KEY_get_enc_flags.pod b/doc/crypto/EC_KEY_get_enc_flags.pod index abc55c148f..4f73a1d59d 100644 --- a/doc/crypto/EC_KEY_get_enc_flags.pod +++ b/doc/crypto/EC_KEY_get_enc_flags.pod @@ -40,7 +40,7 @@ EC_KEY. =head1 SEE ALSO -L, L, L, +L, L, L, L, L, L, @@ -49,7 +49,7 @@ L =head1 COPYRIGHT -Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2015-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/EC_KEY_new.pod b/doc/crypto/EC_KEY_new.pod index 83a2c6d097..591529fd47 100644 --- a/doc/crypto/EC_KEY_new.pod +++ b/doc/crypto/EC_KEY_new.pod @@ -165,7 +165,7 @@ of the buffer or 0 on error. =head1 SEE ALSO -L, L, L, +L, L, L, L, L, L, @@ -173,7 +173,7 @@ L =head1 COPYRIGHT -Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2013-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/EC_POINT_add.pod b/doc/crypto/EC_POINT_add.pod index c029de42b1..6f3e2308bd 100644 --- a/doc/crypto/EC_POINT_add.pod +++ b/doc/crypto/EC_POINT_add.pod @@ -64,13 +64,13 @@ EC_GROUP_have_precompute_mult return 1 if a precomputation has been done, or 0 i =head1 SEE ALSO -L, L, L, L, +L, L, L, L, L, L, L =head1 COPYRIGHT -Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2013-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/EC_POINT_new.pod b/doc/crypto/EC_POINT_new.pod index 206648c83b..3358a08d8b 100644 --- a/doc/crypto/EC_POINT_new.pod +++ b/doc/crypto/EC_POINT_new.pod @@ -180,13 +180,13 @@ error. =head1 SEE ALSO -L, L, L, L, +L, L, L, L, L, L, L =head1 COPYRIGHT -Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2013-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/OPENSSL_init_crypto.pod b/doc/crypto/OPENSSL_init_crypto.pod index 1989880752..f0b3c8aa8d 100644 --- a/doc/crypto/OPENSSL_init_crypto.pod +++ b/doc/crypto/OPENSSL_init_crypto.pod @@ -162,7 +162,7 @@ The OPENSSL_cleanup() function deinitialises OpenSSL (both libcrypto and libssl). All resources allocated by OpenSSL are freed. Typically there should be no need to call this function directly as it is initiated automatically on application exit. This is done via the standard C library -L function. In the event that the application will close in a manner +atexit() function. In the event that the application will close in a manner that will not call the registered atexit() handlers then the application should call OPENSSL_cleanup() directly. Developers of libraries using OpenSSL are discouraged from calling this function and should instead, typically, rely @@ -235,7 +235,7 @@ and OPENSSL_INIT_free() functions were added in OpenSSL 1.1.0. =head1 COPYRIGHT -Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2016-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/SCT_new.pod b/doc/crypto/SCT_new.pod index 4ee41a6d41..698ee271f6 100644 --- a/doc/crypto/SCT_new.pod +++ b/doc/crypto/SCT_new.pod @@ -174,8 +174,8 @@ B returns 1 on success, 0 otherwise. =head1 SEE ALSO -L, -L, +L, +L, L =head1 HISTORY @@ -184,7 +184,7 @@ These functions were added in OpenSSL 1.1.0. =head1 COPYRIGHT -Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2016-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/SMIME_read_PKCS7.pod b/doc/crypto/SMIME_read_PKCS7.pod index 86d5cc3048..3eb8bbc9a0 100644 --- a/doc/crypto/SMIME_read_PKCS7.pod +++ b/doc/crypto/SMIME_read_PKCS7.pod @@ -30,7 +30,7 @@ signed. B<*bcont> can then be passed to PKCS7_verify() with the B flag set. Otherwise the type of the returned structure can be determined -using PKCS7_type(). +using PKCS7_type_is_enveloped(), etc. To support future functionality if B is not B B<*bcont> should be initialized to B. For example: @@ -61,14 +61,14 @@ is an error occurred. The error can be obtained from ERR_get_error(3). =head1 SEE ALSO -L, L +L, L, L, L, L L =head1 COPYRIGHT -Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2002-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/UI_new.pod b/doc/crypto/UI_new.pod index 5ab1a9fac5..037e8bf10e 100644 --- a/doc/crypto/UI_new.pod +++ b/doc/crypto/UI_new.pod @@ -9,7 +9,7 @@ UI_dup_input_boolean, UI_add_info_string, UI_dup_info_string, UI_add_error_string, UI_dup_error_string, UI_construct_prompt, UI_add_user_data, UI_get0_user_data, UI_get0_result, UI_process, UI_ctrl, UI_set_default_method, UI_get_default_method, UI_get_method, -UI_set_method, UI_OpenSSL, - user interface +UI_set_method, UI_OpenSSL, UI_null - user interface =head1 SYNOPSIS @@ -58,6 +58,7 @@ UI_set_method, UI_OpenSSL, - user interface const UI_METHOD *UI_set_method(UI *ui, const UI_METHOD *meth); UI_METHOD *UI_OpenSSL(void); + const UI_METHOD *UI_null(void); =head1 DESCRIPTION @@ -177,9 +178,12 @@ UI_set_method() changes the UI method associated with a given UI. UI_OpenSSL() is the default OpenSSL UI method for prompting passphrases on the command line. +UI_null() is a UI method that does nothing. Its use is to avoid +getting internal defaults for passed UI_METHOD pointers. + =head1 COPYRIGHT -Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2001-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/X509_LOOKUP_hash_dir.pod b/doc/crypto/X509_LOOKUP_hash_dir.pod index 08fa731238..5f8dfa93b0 100644 --- a/doc/crypto/X509_LOOKUP_hash_dir.pod +++ b/doc/crypto/X509_LOOKUP_hash_dir.pod @@ -108,20 +108,19 @@ Note that the hash algorithm used for subject name hashing changed in OpenSSL 1.0.0, and all certificate stores have to be rehashed when moving from OpenSSL 0.9.8 to 1.0.0. -OpenSSL includes a L utility which creates symlinks with correct +OpenSSL includes a L utility which creates symlinks with correct hashed names for all files with .pem suffix in a given directory. =head1 SEE ALSO L, -L, L, -L, +L, L, =head1 COPYRIGHT -Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2015-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/X509_digest.pod b/doc/crypto/X509_digest.pod index 267e7bd2a6..07cfda4908 100644 --- a/doc/crypto/X509_digest.pod +++ b/doc/crypto/X509_digest.pod @@ -51,7 +51,7 @@ All functions described here return 1 for success and 0 for failure. =head1 SEE ALSO -L +L =head1 COPYRIGHT diff --git a/doc/crypto/ct.pod b/doc/crypto/ct.pod index bdcda98618..355204d2a6 100644 --- a/doc/crypto/ct.pod +++ b/doc/crypto/ct.pod @@ -1,7 +1,5 @@ =pod -=for comment openssl_manual_section:7 - =head1 NAME ct - Certificate Transparency @@ -34,9 +32,9 @@ L, L, L, L, -L, L, -L, +L, +L, L =head1 HISTORY @@ -45,7 +43,7 @@ This library was added in OpenSSL 1.1.0. =head1 COPYRIGHT -Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2016-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/d2i_PrivateKey.pod b/doc/crypto/d2i_PrivateKey.pod index 6b12ad9eab..30caeebcb5 100644 --- a/doc/crypto/d2i_PrivateKey.pod +++ b/doc/crypto/d2i_PrivateKey.pod @@ -56,12 +56,12 @@ L. =head1 SEE ALSO -L, -L +L, +L =head1 COPYRIGHT -Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. +Copyright 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/x509.pod b/doc/crypto/x509.pod index 8319b15270..06584e3ae7 100644 --- a/doc/crypto/x509.pod +++ b/doc/crypto/x509.pod @@ -1,7 +1,5 @@ =pod -=for comment openssl_manual_section:7 - =head1 NAME x509 - X.509 certificate handling @@ -12,7 +10,7 @@ x509 - X.509 certificate handling =head1 DESCRIPTION -A X.509 certificate is a structured grouping of information about +An X.509 certificate is a structured grouping of information about an individual, a device, or anything one can imagine. A X.509 CRL (certificate revocation list) is a tool to help determine if a certificate is still valid. The exact definition of those can be @@ -60,12 +58,12 @@ L, L, L, L, -L, -L +L, +L =head1 COPYRIGHT -Copyright 2003-2016 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2003-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/ssl/SSL_CTX_set_ct_validation_callback.pod b/doc/ssl/SSL_CTX_set_ct_validation_callback.pod index d818e00fc5..afa45dc93f 100644 --- a/doc/ssl/SSL_CTX_set_ct_validation_callback.pod +++ b/doc/ssl/SSL_CTX_set_ct_validation_callback.pod @@ -2,6 +2,7 @@ =head1 NAME +ssl_ct_validation_cb, SSL_enable_ct, SSL_CTX_enable_ct, SSL_disable_ct, SSL_CTX_disable_ct, SSL_set_ct_validation_callback, SSL_CTX_set_ct_validation_callback, SSL_ct_is_enabled, SSL_CTX_ct_is_enabled - @@ -11,6 +12,9 @@ control Certificate Transparency policy #include + typedef int (*ssl_ct_validation_cb)(const CT_POLICY_EVAL_CTX *ctx, + const STACK_OF(SCT) *scts, void *arg); + int SSL_enable_ct(SSL *s, int validation_mode); int SSL_CTX_enable_ct(SSL_CTX *ctx, int validation_mode); int SSL_set_ct_validation_callback(SSL *s, ssl_ct_validation_cb callback, @@ -127,12 +131,11 @@ L, L, L, L, -L, L =head1 COPYRIGHT -Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2016-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/ssl/SSL_CTX_set_verify.pod b/doc/ssl/SSL_CTX_set_verify.pod index ccfe94cd18..c2077bbb46 100644 --- a/doc/ssl/SSL_CTX_set_verify.pod +++ b/doc/ssl/SSL_CTX_set_verify.pod @@ -2,6 +2,7 @@ =head1 NAME +SSL_get_ex_data_X509_STORE_CTX_idx, SSL_CTX_set_verify, SSL_set_verify, SSL_CTX_set_verify_depth, SSL_set_verify_depth, SSL_verify_cb @@ -13,9 +14,12 @@ SSL_verify_cb void SSL_CTX_set_verify(SSL_CTX *ctx, int mode, SSL_verify_cb verify_callback); void SSL_set_verify(SSL *s, int mode, SSL_verify_cb verify_callback); + SSL_get_ex_data_X509_STORE_CTX_idx(void); + void SSL_CTX_set_verify_depth(SSL_CTX *ctx, int depth); void SSL_set_verify_depth(SSL *s, int depth); + typedef int (*SSL_verify_cb)(int preverify_ok, X509_STORE_CTX *x509_ctx); =head1 DESCRIPTION @@ -30,7 +34,9 @@ shall be specified, the NULL pointer can be used for B. In this case last B set specifically for this B remains. If no special B was set before, the default callback for the underlying B is used, that was valid at the time B was created with -L. +L. Within the callback function, +B can be called to get the data index +of the current SSL object that is doing the verification. SSL_CTX_set_verify_depth() sets the maximum B for the certificate chain verification that shall be allowed for B. (See the BUGS section.) @@ -171,7 +177,7 @@ certificates. The example makes use of the ex_data technique to store application data into/retrieve application data from the SSL structure -(see L, +(see L, L). ... @@ -284,11 +290,11 @@ L, L, L, L, -L +L =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/ssl/SSL_set_bio.pod b/doc/ssl/SSL_set_bio.pod index e8e55f4648..bdee438c02 100644 --- a/doc/ssl/SSL_set_bio.pod +++ b/doc/ssl/SSL_set_bio.pod @@ -39,41 +39,41 @@ used in preference. The ownership rules are as follows: =over 4 -=item +=item * If neither the rbio or wbio have changed from their previous values then nothing is done. -=item +=item * If the rbio and wbio parameters are different and both are different to their previously set values then one reference is consumed for the rbio and one reference is consumed for the wbio. -=item +=item * If the rbio and wbio parameters are the same and the rbio is not the same as the previously set value then one reference is consumed. -=item +=item * If the rbio and wbio parameters are the same and the rbio is the same as the previously set value, then no additional references are consumed. -=item +=item * If the rbio and wbio parameters are different and the rbio is the same as the previously set value then one reference is consumbed for the wbio and no references are consumed for the rbio. -=item +=item * If the rbio and wbio parameters are different and the wbio is the same as the previously set value and the old rbio and wbio values were the same as each other then one reference is consumed for the rbio and no references are consumed for the wbio. -=item +=item * If the rbio and wbio parameters are different and the wbio is the same as the previously set value and the old rbio and wbio values were different to each @@ -90,7 +90,7 @@ SSL_set_bio(), SSL_set_rbio() and SSL_set_wbio() cannot fail. L, L, L, -L, L, L +L, L, L =head1 HISTORY @@ -98,7 +98,7 @@ SSL_set0_rbio() and SSL_set0_wbio() were added 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/ssl/ssl.pod b/doc/ssl/ssl.pod index 960f0690d6..391dc705d9 100644 --- a/doc/ssl/ssl.pod +++ b/doc/ssl/ssl.pod @@ -1,10 +1,8 @@ =pod -=for comment openssl_manual_section:7 - =head1 NAME -SSL - OpenSSL SSL/TLS library +ssl - OpenSSL SSL/TLS library =head1 SYNOPSIS @@ -30,8 +28,8 @@ connection with the object. Then the TLS/SSL handshake is performed using L or L respectively. -L and L are used -to read and write data on the TLS/SSL connection. +L and L are +used to read and write data on the TLS/SSL connection. L can be used to shut down the TLS/SSL connection. @@ -322,6 +320,8 @@ protocol context defined in the B structure. =item void B(SSL_CTX *ctx, X509_STORE *cs); +=item void B(SSL_CTX *ctx, X509_STORE *cs); + =item void B(SSL_CTX *ctx, int (*cb)(), char *arg) =item int B(SSL_CTX *ctx, char *str); @@ -496,8 +496,6 @@ in multiple SSL connections, and then duplicate it prior to initiating each connection with the duplicated handle. Use of SSL_dup() avoids the need to repeat the configuration of the handles for each connection. -This is used internally by L to construct -per-connection SSL handles after L. For SSL_dup() to work, the connection MUST be in its initial state and MUST NOT have not yet have started the SSL handshake. @@ -552,6 +550,8 @@ fresh handle for each connection. =item void (*B(const SSL *ssl);)() +=item int B(SSL *s); + =item STACK *B(const SSL *ssl); =item X509 *B(const SSL *ssl); @@ -600,6 +600,8 @@ fresh handle for each connection. =item int B(SSL *ssl); +=item int B(SSL *s, int updatetype); + =item STACK *B(const char *file); =item SSL *B(SSL_CTX *ctx); @@ -736,7 +738,7 @@ See the individual manual pages for details. =head1 SEE ALSO -L, L, +L, L, L, L, L, L, @@ -793,6 +795,7 @@ L, L, L, L, +L, L, L, L, @@ -804,6 +807,7 @@ L, L, L, L, +L, L, L, L, @@ -823,7 +827,7 @@ 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/util/find-doc-nits.pl b/util/find-doc-nits similarity index 54% rename from util/find-doc-nits.pl rename to util/find-doc-nits index 74bf2469f8..0b855154c1 100755 --- a/util/find-doc-nits.pl +++ b/util/find-doc-nits @@ -13,9 +13,30 @@ use strict; use Pod::Checker; use File::Find; use File::Basename; +use File::Spec::Functions; use Getopt::Std; +use lib catdir(dirname($0), "perl"); +use OpenSSL::Util::Pod; +# Options. our($opt_s); +our($opt_u); +our($opt_h); +our($opt_n); +our($opt_l); + +sub help() +{ + print < [ 'SYNOPSIS', 'RETURN VALUES' ], 5 => [ ], 7 => [ ] ); -my %default_sections = - ( apps => 1, - crypto => 3, - ssl => 3 ); # Cross-check functions in the NAME and SYNOPSIS section. sub name_synopsis() @@ -119,8 +136,7 @@ sub check() &name_synopsis($id, $filename, $contents) unless $contents =~ /=for comment generic/ - or $contents =~ /=for comment openssl_manual_section:7/ - or $filename =~ m@/apps/@; + or $filename =~ m@man[157]/@; print "$id doesn't start with =pod\n" if $contents !~ /^=pod/; @@ -163,10 +179,8 @@ sub check() # Find what section this page is in. If run from "." assume # section 3. - my $section = $default_sections{$dirname} || 3; - if ($contents =~ /^=for\s+comment\s+openssl_manual_section:\s*(\d+)\s*$/m) { - $section = $1; - } + my $section = 3; + $section = $1 if $dirname =~ /man([1-9])/; foreach ((@{$mandatory_sections{'*'}}, @{$mandatory_sections{$section}})) { print "$id: missing $_ head1 section\n" @@ -187,10 +201,168 @@ sub check() unlink $temp || warn "Can't remove $temp, $!"; } -getopts('s'); +my %dups; + +sub parsenum() +{ + my $file = shift; + my @apis; + + open my $IN, '<', $file + or die "Can't open $file, $!, stopped"; + + while ( <$IN> ) { + next if /\bNOEXIST\b/; + next if /\bEXPORT_VAR_AS_FUNC\b/; + push @apis, $1 if /([^\s]+).\s/; + } + + close $IN; + + print "# Found ", scalar(@apis), " in $file\n"; + return sort @apis; +} + +sub getdocced() +{ + my $dir = shift; + my %return; + + foreach my $pod ( glob("$dir/*.pod") ) { + my %podinfo = extract_pod_info($pod); + foreach my $n ( @{$podinfo{names}} ) { + $return{$n} = $pod; + print "# Duplicate $n in $pod and $dups{$n}\n" + if defined $dups{$n} && $dups{$n} ne $pod; + $dups{$n} = $pod; + } + } + + return %return; +} + +my %docced; + +sub printem() +{ + my $libname = shift; + my $numfile = shift; + my $count = 0; -foreach (@ARGV ? @ARGV : glob('doc/*/*.pod')) { - &check($_); + foreach my $func ( &parsenum($numfile) ) { + next if $docced{$func}; + + # Skip ASN1 utilities + next if $func =~ /^ASN1_/; + + print "$libname:$func\n"; + $count++; + } + print "# Found $count missing from $numfile\n\n"; +} + + +# Collection of links in each POD file. +# filename => [ "foo(1)", "bar(3)", ... ] +my %link_collection = (); +# Collection of names in each POD file. +# "name(s)" => filename +my %name_collection = (); + +sub collectnames { + my $filename = shift; + $filename =~ m|man(\d)/|; + my $section = $1; + my $simplename = basename($filename, ".pod"); + my $id = "${filename}:1:"; + + my $contents = ''; + { + local $/ = undef; + open POD, $filename or die "Couldn't open $filename, $!"; + $contents = ; + close POD; + } + + $contents =~ /=head1 NAME([^=]*)=head1 /ms; + my $tmp = $1; + unless (defined $tmp) { + print "$id weird name section\n"; + return; + } + $tmp =~ tr/\n/ /; + $tmp =~ s/-.*//g; + + my @names = map { s/\s+//g; $_ } split(/,/, $tmp); + unless (grep { $simplename eq $_ } @names) { + print "$id missing $simplename\n"; + push @names, $simplename; + } + foreach my $name (@names) { + next if $name eq ""; + my $name_sec = "$name($section)"; + if (! exists $name_collection{$name_sec}) { + $name_collection{$name_sec} = $filename; + } else { #elsif ($filename ne $name_collection{$name_sec}) { + print "$id $name_sec also in $name_collection{$name_sec}\n"; + } + } + + my @foreign_names = + map { map { s/\s+//g; $_ } split(/,/, $_) } + $contents =~ /=for\s+comment\s+foreign\s+manuals:\s*(.*)\n\n/; + foreach (@foreign_names) { + $name_collection{$_} = undef; # It still exists! + } + + my @links = $contents =~ /L< + # if the link is of the form L, + # then remove 'something'. Note that 'something' + # may contain POD codes as well... + (?:(?:[^\|]|<[^>]*>)*\|)? + # we're only interested in referenses that have + # a one digit section number + ([^\/>\(]+\(\d\)) + /gx; + $link_collection{$filename} = [ @links ]; +} + +sub checklinks { + foreach my $filename (sort keys %link_collection) { + foreach my $link (@{$link_collection{$filename}}) { + print "${filename}:1: reference to non-existing $link\n" + unless exists $name_collection{$link}; + } + } +} + +getopts('lnshu'); + +&help() if ( $opt_h ); + +die "Need one of -l -n -s or -u flags.\n" + unless $opt_l or $opt_n or $opt_s or $opt_u; + +if ( $opt_n or $opt_s ) { + foreach (@ARGV ? @ARGV : glob('doc/*/*.pod')) { + &check($_); + } +} + +if ( $opt_l ) { + foreach (@ARGV ? @ARGV : glob('doc/*/*.pod')) { + collectnames($_); + } + checklinks(); +} + +if ( $opt_u ) { + my %temp = &getdocced('doc/man3'); + foreach ( keys %temp ) { + $docced{$_} = $temp{$_}; + } + &printem('crypto', 'util/libcrypto.num'); + &printem('ssl', 'util/libssl.num'); } exit; -- 2.40.0