EVP digest list: one hash algorithm per file, synchronize EVP list, o… #4628

ronaldtse · 2017-10-31T07:54:15Z

As described by @levitte in #4564 and #4616 , this is similar work to break up the EVP digest list into individual pages.

Specifically:

Added documentation for the missing SHAKE, WHIRLPOOL, MD4 hash algorithms
Added the SSL-specific MD5-SHA1 hash algorithm
Split all digests into separate files

This is a contribution from Ribose Inc..

Checklist

documentation is added or updated

…verall cleanup.

levitte · 2017-10-31T08:12:48Z

doc/man3/EVP_blake2b512.pod

+
+=head1 CONFORMING TO
+
+N/A.


In a case like this, I think it would be preferable to remove this section. What's your motivation for keeping it?

Just for consistency among all the files. We can remove it alright if it is preferred.

It is at least my preference. I don't think we've ever had a N/A section before, so this is a new situation for us. What says the rest of @openssl/omc and @openssl/committers ?

How about referring to https://tools.ietf.org/html/rfc7693 ?

Good call @bernd-edlinger , thank you! Maybe the answer to @levitte is : there can always be a reference...

FWIW I write man pages in my other life as a FreeBSD documentation committer, and CONFORMING TO is not a required section, so it should be omitted when empty.

yes, but it would normally be the case that it conforms to something, like an RFC or something.

levitte · 2017-10-31T09:49:43Z

doc/man3/EVP_mdc2.pod

+
+=head1 CONFORMING TO
+
+N/A.


Here's another one.

I heard your argument about having this as a placeholder, in case we find a reference later on... Unfortunately, placeholders aren't in our habits. As a matter of fact, we have had some, but removed them all at some point.

I did check to see if I could quickly find something to put here. Alas...

The answer is actually in MDC2_Init.pod, the reference is ISO/IEC 10118-2 👍

Feel free :-)

I'm still trying to find out which exact algorithm it is in that document... one sec 😄

levitte · 2017-10-31T09:50:50Z

doc/man3/EVP_ripemd160.pod

+
+=head1 CONFORMING TO
+
+N/A.


ISO/IEC 10118-3:2016 Dedicated Hash-Function 1 (RIPEMD-160).

Do feel free :-)

levitte

Awesome

bernd-edlinger · 2017-10-31T10:59:01Z

doc/man3/EVP_DigestInit.pod

+
+=item EVP_md_null()
+
+Returns a pointer to the corresponding B<EVP_MD> structures.


I don't understand this sentence, is it in the wrong context.

@bernd-edlinger I think there's something wrong with the diff?

I'm seeing the right description here: https://github.com/openssl/openssl/pull/4628/files#diff-b285e033e98ee2d9eff6aec1a7bd6dbfR156

Yes, the description looks right, but under return values I see something like:

EVP_md_null() Returns a pointer to the corresponding EVP_MD structures

That sounds a bit funny I think you mean to say something about the return value of any
EVP_<digest> function here?

@bernd-edlinger in the diff the content is:
"A "null" message digest that does nothing: i.e. the hash it returns is of zero length."

No, I mean the return value section,
previously the text was:

EVP_md_null(), EVP_md2(), EVP_md5(), EVP_sha1(), EVP_mdc2(), EVP_ripemd160(), EVP_blake2b512(), and EVP_blake2s256() return pointers to the corresponding EVP_MD structures.

which made sense, but now it is:

EVP_md_null() Returns a pointer to the corresponding B<EVP_MD> structures.

So, unless I am completely mistaken,
the return value is the EVP_MD structure of the NULL MD or something.

Sorry I was entirely confused. I've now fixed hopefully the right issue 😉

bernd-edlinger

Thank you

ronaldtse · 2017-10-31T13:20:06Z

Thank you @bernd-edlinger !

levitte · 2017-10-31T14:09:27Z

Squashed and merged. bbda8ce

…verall cleanup. Reviewed-by: Bernd Edlinger <bernd.edlinger@hotmail.de> Reviewed-by: Richard Levitte <levitte@openssl.org> (Merged from #4628)

ronaldtse · 2017-11-02T09:28:30Z

Thank you @levitte !

EVP digest list: one hash algorithm per file, synchronize EVP list, o…

0d12d32

…verall cleanup.

levitte requested changes Oct 31, 2017

View reviewed changes

EVP digest list: update blake2 conformance reference

c945c76

levitte requested changes Oct 31, 2017

View reviewed changes

levitte approved these changes Oct 31, 2017

View reviewed changes

EVP digest list: provide correct references for RIPEMD160 and MDC-2

7289300

ronaldtse force-pushed the ronaldtse-update-evpdigestlist branch from 8d47c59 to 7289300 Compare October 31, 2017 10:19

bernd-edlinger reviewed Oct 31, 2017

View reviewed changes

ronaldtse added 2 commits October 31, 2017 19:03

EVP digest list: clean up headings

61d4514

EVP digest list: fix EVP_md_null return description

429612f

bernd-edlinger approved these changes Oct 31, 2017

View reviewed changes

levitte closed this Oct 31, 2017

ronaldtse deleted the ronaldtse-update-evpdigestlist branch November 2, 2017 09:28

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

EVP digest list: one hash algorithm per file, synchronize EVP list, o… #4628

EVP digest list: one hash algorithm per file, synchronize EVP list, o… #4628

ronaldtse commented Oct 31, 2017

levitte Oct 31, 2017

ronaldtse Oct 31, 2017

levitte Oct 31, 2017

bernd-edlinger Oct 31, 2017

ronaldtse Oct 31, 2017

ronaldtse Oct 31, 2017

kaduk Oct 31, 2017

bernd-edlinger Oct 31, 2017

levitte Oct 31, 2017

ronaldtse Oct 31, 2017

levitte Oct 31, 2017

ronaldtse Oct 31, 2017

ronaldtse Oct 31, 2017

levitte Oct 31, 2017

ronaldtse Oct 31, 2017

levitte Oct 31, 2017

ronaldtse Oct 31, 2017

levitte left a comment

bernd-edlinger Oct 31, 2017

ronaldtse Oct 31, 2017

bernd-edlinger Oct 31, 2017 •

edited

ronaldtse Oct 31, 2017

bernd-edlinger Oct 31, 2017

ronaldtse Oct 31, 2017

bernd-edlinger left a comment

ronaldtse commented Oct 31, 2017

levitte commented Oct 31, 2017

ronaldtse commented Nov 2, 2017


		=item EVP_md_null()

		Returns a pointer to the corresponding B<EVP_MD> structures.


		=head1 CONFORMING TO

		N/A.


		=head1 CONFORMING TO

		N/A.


		=head1 CONFORMING TO

		N/A.

EVP digest list: one hash algorithm per file, synchronize EVP list, o… #4628

EVP digest list: one hash algorithm per file, synchronize EVP list, o… #4628

Conversation

ronaldtse commented Oct 31, 2017

Checklist

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

levitte left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bernd-edlinger Oct 31, 2017 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bernd-edlinger left a comment

Choose a reason for hiding this comment

ronaldtse commented Oct 31, 2017

levitte commented Oct 31, 2017

ronaldtse commented Nov 2, 2017

bernd-edlinger Oct 31, 2017 •

edited