Hi, Michael Reed wrote on Sat, Sep 19, 2015 at 05:01:38PM -0400:
> This was done with pod2mdoc This one was left unprocessed when we started the POD to mdoc conversion because in OpenBSD, we generally hate manual pages in the style of string(3) and curses(3). They tend to be incomplete and outdated. Given apropos(1), they are mostly useless. > + various manual tweaking. I couldn't find any tweaking; what you sent was exactly the output of pod2mdoc(1). Well, you forgot these two options: -d Mdocdate -s 3 > Besides the macro changes, there are few differences between the > original manual's text. This is done in order to ease review. > This is the reason why there are many references to non-existent > manuals, e.g., rc4(3), stack(3), and txt_db(3). > > If wanted, I'll remove the non-existent references. I tried to figure that out myself but failed, this doesn't look trivial. For example, looking just at the first two links: * blowfish(3) does exists - not in LibreSSL, but in libc. * cast(3) does not exist, but it looks like it's described in EVP_EncryptInit(3). No idea how to deal with that. * ... This needs the attention of a LibreSSL expert (Brent, maybe?) to update the content. As it stands, it is very confusing and probably mostly wrong. Alternatively, i propose to just delete the page without any replacement. Any OKs for deletion? Yours, Ingo > Index: src/lib/libcrypto/man/Makefile > =================================================================== > RCS file: /cvs/src/lib/libcrypto/man/Makefile,v > retrieving revision 1.24 > diff -u -p -r1.24 Makefile > --- src/lib/libcrypto/man/Makefile 17 Sep 2015 14:43:23 -0000 1.24 > +++ src/lib/libcrypto/man/Makefile 19 Sep 2015 20:41:54 -0000 > @@ -52,6 +52,7 @@ MAN= \ > BN_swap.3 \ > BN_zero.3 \ > BUF_MEM_new.3 \ > + crypto.3 \ > > GENMAN= \ > CONF_modules_free.3 \ > @@ -170,7 +171,6 @@ GENMAN= \ > X509_verify_cert.3 \ > bn.3 \ > bn_internal.3 \ > - crypto.3 \ > d2i_ASN1_OBJECT.3 \ > d2i_DHparams.3 \ > d2i_DSAPublicKey.3 \ > Index: src/lib/libcrypto/man/crypto.3 > =================================================================== > RCS file: src/lib/libcrypto/man/crypto.3 > diff -N src/lib/libcrypto/man/crypto.3 > --- /dev/null 1 Jan 1970 00:00:00 -0000 > +++ src/lib/libcrypto/man/crypto.3 19 Sep 2015 20:41:54 -0000 > @@ -0,0 +1,94 @@ > +.Dd September 19, 2015 > +.Dt CRYPTO 3 > +.Os > +.Sh NAME > +.Nm crypto > +.Nd OpenSSL cryptographic library > +.Sh DESCRIPTION > +The OpenSSL > +.Nm > +library implements a wide range of cryptographic algorithms used in various > +Internet standards. > +The services provided by this library are used by the OpenSSL implementations > +of SSL, TLS and S/MIME, and they have also been used to implement SSH, > +OpenPGP, and other cryptographic standards. > +.Sh OVERVIEW > +.Nm libcrypto > +consists of a number of sub-libraries that implement the individual > +algorithms. > +.Pp > +The functionality includes symmetric encryption, public key cryptography and > +key agreement, certificate handling, cryptographic hash functions and a > +cryptographic pseudo-random number generator. > +.Bl -tag -width 3n > +.It SYMMETRIC CIPHERS > +.Xr blowfish 3 , > +.Xr cast 3 , > +.Xr des 3 , > +.Xr idea 3 , > +.Xr rc2 3 , > +.Xr rc4 3 , > +.Xr rc5 3 > +.It PUBLIC KEY CRYPTOGRAPHY AND KEY AGREEMENT > +.Xr dsa 3 , > +.Xr dh 3 , > +.Xr rsa 3 > +.It CERTIFICATES > +.Xr x509 3 , > +.Xr x509v3 3 > +.It AUTHENTICATION CODES, HASH FUNCTIONS > +.Xr hmac 3 , > +.Xr md2 3 , > +.Xr md4 3 , > +.Xr md5 3 , > +.Xr ripemd 3 , > +.Xr sha 3 > +.It AUXILIARY FUNCTIONS > +.Xr err 3 , > +.Xr threads 3 , > +.Xr rand 3 , > +.Xr OPENSSL_VERSION_NUMBER 3 > +.It INPUT/OUTPUT, DATA ENCODING > +.Xr asn1 3 , > +.Xr bio 3 , > +.Xr evp 3 , > +.Xr pem 3 , > +.Xr pkcs7 3 , > +.Xr pkcs12 3 > +.It INTERNAL FUNCTIONS > +.Xr bn 3 , > +.Xr buffer 3 , > +.Xr ec 3 , > +.Xr lhash 3 , > +.Xr objects 3 , > +.Xr stack 3 , > +.Xr txt_db 3 > +.El > +.Sh NOTES > +Some of the newer functions follow a naming convention using the numbers > +0 and 1. > +For example the functions: > +.Bd -literal > +.Ft int > +.Fn X509_CRL_add0_revoked "X509_CRL *crl" "X509_REVOKED *rev" > +.Ft int > +.Fn X509_add1_trust_object "X509 *x" "ASN1_OBJECT *obj" > +.Ed > +.Pp > +The 0 version uses the supplied structure pointer directly in the parent and > +it will be freed up when the parent is freed. > +In the above example > +.Fa crl > +would be freed, but > +.Fa rev > +would not. > +.Pp > +The 1 version uses a copy of the supplied structure pointer (or in some cases > +increases its link count) in the parent and so both > +.Fa x > +and > +.Fa obj > +should be freed up. > +.Sh SEE ALSO > +.Xr openssl 1 , > +.Xr ssl 3 > Index: src/lib/libssl/src/doc/crypto/crypto.pod > =================================================================== > RCS file: src/lib/libssl/src/doc/crypto/crypto.pod > diff -N src/lib/libssl/src/doc/crypto/crypto.pod > --- src/lib/libssl/src/doc/crypto/crypto.pod 14 Sep 2015 01:45:03 -0000 > 1.10 > +++ /dev/null 1 Jan 1970 00:00:00 -0000 > @@ -1,85 +0,0 @@ > -=pod > - > -=head1 NAME > - > -crypto - OpenSSL cryptographic library > - > -=head1 SYNOPSIS > - > -=head1 DESCRIPTION > - > -The OpenSSL B<crypto> library implements a wide range of cryptographic > -algorithms used in various Internet standards. The services provided > -by this library are used by the OpenSSL implementations of SSL, TLS > -and S/MIME, and they have also been used to implement SSH, OpenPGP, and > -other cryptographic standards. > - > -=head1 OVERVIEW > - > -B<libcrypto> consists of a number of sub-libraries that implement the > -individual algorithms. > - > -The functionality includes symmetric encryption, public key > -cryptography and key agreement, certificate handling, cryptographic > -hash functions and a cryptographic pseudo-random number generator. > - > -=over 4 > - > -=item SYMMETRIC CIPHERS > - > -L<blowfish(3)|blowfish(3)>, L<cast(3)|cast(3)>, L<des(3)|des(3)>, > -L<idea(3)|idea(3)>, L<rc2(3)|rc2(3)>, L<rc4(3)|rc4(3)>, L<rc5(3)|rc5(3)> > - > -=item PUBLIC KEY CRYPTOGRAPHY AND KEY AGREEMENT > - > -L<dsa(3)|dsa(3)>, L<dh(3)|dh(3)>, L<rsa(3)|rsa(3)> > - > -=item CERTIFICATES > - > -L<x509(3)|x509(3)>, L<x509v3(3)|x509v3(3)> > - > -=item AUTHENTICATION CODES, HASH FUNCTIONS > - > -L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>, L<md4(3)|md4(3)>, > -L<md5(3)|md5(3)>, L<ripemd(3)|ripemd(3)>, > -L<sha(3)|sha(3)> > - > -=item AUXILIARY FUNCTIONS > - > -L<err(3)|err(3)>, L<threads(3)|threads(3)>, L<rand(3)|rand(3)>, > -L<OPENSSL_VERSION_NUMBER(3)|OPENSSL_VERSION_NUMBER(3)> > - > -=item INPUT/OUTPUT, DATA ENCODING > - > -L<asn1(3)|asn1(3)>, L<bio(3)|bio(3)>, L<evp(3)|evp(3)>, L<pem(3)|pem(3)>, > -L<pkcs7(3)|pkcs7(3)>, L<pkcs12(3)|pkcs12(3)> > - > -=item INTERNAL FUNCTIONS > - > -L<bn(3)|bn(3)>, L<buffer(3)|buffer(3)>, L<ec(3)|ec(3)>, L<lhash(3)|lhash(3)>, > -L<objects(3)|objects(3)>, L<stack(3)|stack(3)>, > -L<txt_db(3)|txt_db(3)> > - > -=back > - > -=head1 NOTES > - > -Some of the newer functions follow a naming convention using the numbers > -B<0> and B<1>. For example the functions: > - > - int X509_CRL_add0_revoked(X509_CRL *crl, X509_REVOKED *rev); > - int X509_add1_trust_object(X509 *x, ASN1_OBJECT *obj); > - > -The B<0> version uses the supplied structure pointer directly > -in the parent and it will be freed up when the parent is freed. > -In the above example B<crl> would be freed but B<rev> would not. > - > -The B<1> function uses a copy of the supplied structure pointer > -(or in some cases increases its link count) in the parent and > -so both (B<x> and B<obj> above) should be freed up. > - > -=head1 SEE ALSO > - > -L<openssl(1)|openssl(1)>, L<ssl(3)|ssl(3)> > - > -=cut
