Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

doc: better description of KECCAK-KMAC XOF #22755

Closed
wants to merge 2 commits into from
Closed

doc: better description of KECCAK-KMAC XOF #22755

wants to merge 2 commits into from

Conversation

jamuir
Copy link
Member

@jamuir jamuir commented Nov 16, 2023 •
edited by t8m

KECCAK-KMAC-128 and KECCAK-KMAC-256 are extendable output functions that have been defined because they are convenient for implementing KMAC. Give definitions for them so that users aren't left to figure that out themselves. KECCAK-KMAC-128 is very similar to SHAKE-128, and KECCAK-KMAC-256 is very similar to SHAKE-256.

Related to #22619.

Checklist
  • documentation is added or updated

doc: better description of KECCAK-KMAC XOF
b5b9401 
KECCAK-KMAC-128 and KECCAK-KMAC-256 are extendable output functions
that have been defined because they are convenient for implementing
KMAC.  Give definitions for them so that users aren't left to figure
that out themselves.  KECCAK-KMAC-128 is very similar to SHAKE-128,
and KECCAK-KMAC-256 is very similar to SHAKE-256.

Related to openssl#22619.
@jamuir jamuir added branch: master Merge to master branch approval: review pending This pull request needs review by a committer approval: otc review pending This pull request needs review by an OTC member triaged: documentation The issue/pr deals with documentation (errors) branch: 3.0 Merge to openssl-3.0 branch branch: 3.1 Merge to openssl-3.1 branch: 3.2 Merge to openssl-3.2 tests: exempted The PR is exempt from requirements for testing labels Nov 16, 2023
@jamuir jamuir self-assigned this Nov 16, 2023
nhorman
nhorman approved these changes Nov 16, 2023
View reviewed changes
Copy link
Contributor

@nhorman nhorman left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

slontis
slontis reviewed Nov 17, 2023
View reviewed changes
Copy link
Member

@slontis slontis left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See https://nvlpubs.nist.gov/nistpubs/specialpublications/nist.sp.800-185.pdf

@jamuir
Copy link
Member Author

jamuir commented Nov 17, 2023

See https://nvlpubs.nist.gov/nistpubs/specialpublications/nist.sp.800-185.pdf

was there something in particular from SP 800-185 that you wanted to point out?

KMAC128 and KMAC256 are defined in SP 800-185, but it is not obvious what KECCAK-KMAC-128 and KECCAK-KMAC-256 are.

@slontis
Copy link
Member

slontis commented Nov 17, 2023

Appendix A is where it comes from..

@jamuir
Copy link
Member Author

jamuir commented Nov 17, 2023

agreed.

And if someone reads Appendix A, then they can come up with some guesses for how KECCAK-KMAC-128 and KECCAK-KMAC-256 might be defined. But I think it is better to give the definition explicitly in the docs and avoid the guesswork.

Would you be able to provide a review/approval here?

@slontis
Copy link
Member

slontis commented Nov 17, 2023

To me this is not clear.
You half explain this by pointing to the one document,, Where the '00' part comes from is the other document.
So I am suggesting adding something like. (Refer also to the KECCAK[] function used by KMAC in NIST SP800-185 Appendix A).

@jamuir
Copy link
Member Author

jamuir commented Nov 18, 2023

thanks. I will add a reference to SP 800-185.

@jamuir jamuir removed the approval: otc review pending This pull request needs review by an OTC member label Nov 18, 2023
@t8m t8m added approval: done This pull request has the required number of approvals and removed approval: review pending This pull request needs review by a committer labels Nov 20, 2023
@openssl-machine openssl-machine added approval: ready to merge The 24 hour grace period has passed, ready to merge and removed approval: done This pull request has the required number of approvals labels Nov 21, 2023
@openssl-machine
Copy link
Collaborator

This pull request is ready to merge

@levitte
Copy link
Member

levitte commented Nov 22, 2023

Merged

master:
f1bea88 doc: better description of KECCAK-KMAC XOF

3.2:
09adcb0 doc: better description of KECCAK-KMAC XOF

3.1:
d06153a doc: better description of KECCAK-KMAC XOF

3.0:
28b3955 doc: better description of KECCAK-KMAC XOF

@levitte levitte closed this Nov 22, 2023
openssl-machine pushed a commit that referenced this pull request Nov 22, 2023
@levitte
doc: better description of KECCAK-KMAC XOF
f1bea88 
KECCAK-KMAC-128 and KECCAK-KMAC-256 are extendable output functions
that have been defined because they are convenient for implementing
KMAC.  Give definitions for them so that users aren't left to figure
that out themselves.  KECCAK-KMAC-128 is very similar to SHAKE-128,
and KECCAK-KMAC-256 is very similar to SHAKE-256.

Related to #22619.

Reviewed-by: Neil Horman <nhorman@openssl.org>
Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from #22755)
openssl-machine pushed a commit that referenced this pull request Nov 22, 2023
@levitte
doc: better description of KECCAK-KMAC XOF
d06153a 
KECCAK-KMAC-128 and KECCAK-KMAC-256 are extendable output functions
that have been defined because they are convenient for implementing
KMAC.  Give definitions for them so that users aren't left to figure
that out themselves.  KECCAK-KMAC-128 is very similar to SHAKE-128,
and KECCAK-KMAC-256 is very similar to SHAKE-256.

Related to #22619.

Reviewed-by: Neil Horman <nhorman@openssl.org>
Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from #22755)

(cherry picked from commit f1bea88)
openssl-machine pushed a commit that referenced this pull request Nov 22, 2023
@levitte
doc: better description of KECCAK-KMAC XOF
09adcb0 
KECCAK-KMAC-128 and KECCAK-KMAC-256 are extendable output functions
that have been defined because they are convenient for implementing
KMAC.  Give definitions for them so that users aren't left to figure
that out themselves.  KECCAK-KMAC-128 is very similar to SHAKE-128,
and KECCAK-KMAC-256 is very similar to SHAKE-256.

Related to #22619.

Reviewed-by: Neil Horman <nhorman@openssl.org>
Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from #22755)

(cherry picked from commit f1bea88)
openssl-machine pushed a commit that referenced this pull request Nov 22, 2023
@levitte
doc: better description of KECCAK-KMAC XOF
28b3955 
KECCAK-KMAC-128 and KECCAK-KMAC-256 are extendable output functions
that have been defined because they are convenient for implementing
KMAC.  Give definitions for them so that users aren't left to figure
that out themselves.  KECCAK-KMAC-128 is very similar to SHAKE-128,
and KECCAK-KMAC-256 is very similar to SHAKE-256.

Related to #22619.

Reviewed-by: Neil Horman <nhorman@openssl.org>
Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from #22755)

(cherry picked from commit f1bea88)
wanghao75 pushed a commit to openeuler-mirror/openssl that referenced this pull request Nov 25, 2023
doc: better description of KECCAK-KMAC XOF
d30cec4 
KECCAK-KMAC-128 and KECCAK-KMAC-256 are extendable output functions
that have been defined because they are convenient for implementing
KMAC.  Give definitions for them so that users aren't left to figure
that out themselves.  KECCAK-KMAC-128 is very similar to SHAKE-128,
and KECCAK-KMAC-256 is very similar to SHAKE-256.

Related to #22619.

Reviewed-by: Neil Horman <nhorman@openssl.org>
Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from openssl/openssl#22755)

Signed-off-by: fly2x <fly2x@hitls.org>
wanghao75 pushed a commit to openeuler-mirror/openssl that referenced this pull request Nov 25, 2023
doc: better description of KECCAK-KMAC XOF
0219c76 
KECCAK-KMAC-128 and KECCAK-KMAC-256 are extendable output functions
that have been defined because they are convenient for implementing
KMAC.  Give definitions for them so that users aren't left to figure
that out themselves.  KECCAK-KMAC-128 is very similar to SHAKE-128,
and KECCAK-KMAC-256 is very similar to SHAKE-256.

Related to #22619.

Reviewed-by: Neil Horman <nhorman@openssl.org>
Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from openssl/openssl#22755)

(cherry picked from commit f1bea887ef17802a2d83e9289e812c00fd0f0523)
Signed-off-by: fly2x <fly2x@hitls.org>
wanghao75 pushed a commit to openeuler-mirror/openssl that referenced this pull request Nov 25, 2023
doc: better description of KECCAK-KMAC XOF
873d20c 
KECCAK-KMAC-128 and KECCAK-KMAC-256 are extendable output functions
that have been defined because they are convenient for implementing
KMAC.  Give definitions for them so that users aren't left to figure
that out themselves.  KECCAK-KMAC-128 is very similar to SHAKE-128,
and KECCAK-KMAC-256 is very similar to SHAKE-256.

Related to #22619.

Reviewed-by: Neil Horman <nhorman@openssl.org>
Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from openssl/openssl#22755)

(cherry picked from commit f1bea887ef17802a2d83e9289e812c00fd0f0523)
Signed-off-by: fly2x <fly2x@hitls.org>
wanghao75 pushed a commit to openeuler-mirror/openssl that referenced this pull request Nov 25, 2023
doc: better description of KECCAK-KMAC XOF
9f35fca 
KECCAK-KMAC-128 and KECCAK-KMAC-256 are extendable output functions
that have been defined because they are convenient for implementing
KMAC.  Give definitions for them so that users aren't left to figure
that out themselves.  KECCAK-KMAC-128 is very similar to SHAKE-128,
and KECCAK-KMAC-256 is very similar to SHAKE-256.

Related to #22619.

Reviewed-by: Neil Horman <nhorman@openssl.org>
Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from openssl/openssl#22755)

(cherry picked from commit f1bea887ef17802a2d83e9289e812c00fd0f0523)
Signed-off-by: fly2x <fly2x@hitls.org>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@nhorman nhorman nhorman approved these changes

@t8m t8m t8m approved these changes

@slontis slontis slontis approved these changes

Assignees

@jamuir jamuir

Labels
approval: ready to merge The 24 hour grace period has passed, ready to merge branch: master Merge to master branch branch: 3.0 Merge to openssl-3.0 branch branch: 3.1 Merge to openssl-3.1 branch: 3.2 Merge to openssl-3.2 tests: exempted The PR is exempt from requirements for testing triaged: documentation The issue/pr deals with documentation (errors)
Projects
Project Board
Status: Done
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

None yet
6 participants
@jamuir @slontis @openssl-machine @levitte @nhorman @t8m