From: Alan T. DeKok Date: Sun, 11 May 2025 13:03:54 +0000 (-0400) Subject: move hmac to its own file X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=6b2a1807b4a48f9c8e4a67223d0899e7dcbc2c31;p=thirdparty%2Ffreeradius-server.git move hmac to its own file --- diff --git a/doc/antora/modules/reference/nav.adoc b/doc/antora/modules/reference/nav.adoc index 6c0b92cf348..f524e794cac 100644 --- a/doc/antora/modules/reference/nav.adoc +++ b/doc/antora/modules/reference/nav.adoc @@ -84,7 +84,8 @@ **** xref:xlat/file/tail.adoc[tail] *** xref:xlat/function.adoc[Function Syntax] -*** xref:xlat/hash.adoc[Hashing] +*** xref:xlat/hash.adoc[Hash / Digests] +*** xref:xlat/hmac.adoc[HMAC] *** xref:xlat/interpreter.adoc[Interpreter State and Debugging] *** xref:xlat/log.adoc[Logging Functions] diff --git a/doc/antora/modules/reference/pages/xlat/all.adoc b/doc/antora/modules/reference/pages/xlat/all.adoc index 296bcb1286b..f8f9d4b14a2 100644 --- a/doc/antora/modules/reference/pages/xlat/all.adoc +++ b/doc/antora/modules/reference/pages/xlat/all.adoc @@ -1,6 +1,17 @@ = Summary of Dynamic Expansions +.File Handling Functions +[options="headers, autowidth] +|=== +| *Function* | *Description* +| xref:reference:xlat/file/escape.adoc[escape] | Returns an escaped or safe version of the input string. +| xref:xlat/file/exists.adoc[exists] | Checks to see if a file exists on the filesystem. +| xref:xlat/file/head.adoc[head] | Returns the first line of the file. +| xref:xlat/file/rm.adoc[rm] | Removes a file from the filesystem. +| xref:xlat/file/size.adoc[remove] | Returns the size of a file. +| xref:xlat/file/tail.adoc[tail] | Return the last line of a file or the last number(n) of lines of a file. +|=== == Miscellaneous Functions @@ -15,19 +26,6 @@ | xref:xlat/misc/rand.adoc[rand] | random integers |=== - -.File Handling Functions -[options="headers, autowidth] -|=== -| *Function* | *Description* -| xref:reference:xlat/file/escape.adoc[escape] | Returns an escaped or safe version of the input string. -| xref:xlat/file/exists.adoc[exists] | Checks to see if a file exists on the filesystem. -| xref:xlat/file/head.adoc[head] | Returns the first line of the file. -| xref:xlat/file/rm.adoc[rm] | Removes a file from the filesystem. -| xref:xlat/file/size.adoc[remove] | Returns the size of a file. -| xref:xlat/file/tail.adoc[tail] | Return the last line of a file or the last number(n) of lines of a file. -|=== - == String Manipulation .String manipulation diff --git a/doc/antora/modules/reference/pages/xlat/hash.adoc b/doc/antora/modules/reference/pages/xlat/hash.adoc index 5492ffb6020..8feb417c039 100644 --- a/doc/antora/modules/reference/pages/xlat/hash.adoc +++ b/doc/antora/modules/reference/pages/xlat/hash.adoc @@ -2,108 +2,26 @@ The following functions perform hashing. -Note that the server supports insecure hashing methods such as MD5 and -SHA1. These functions are here for historical compatibility and -completeness. +Note that the server supports insecure hashing methods such as MD4, +MD5 and SHA1. These functions are here for historical compatibility +and completeness. They should not be used. -== %hmac.md5(, ) +All of the hash functions take arbitrary data, and turn binary data as +`octet`s. -Generate `HMAC-MD5` of string. +== List of Hash Functions -.Return: _octal_ +The following hashes are supported: -.Example - -[source,unlang] ----- -control.Tmp-String-0 := "mykey" -control.Tmp-String-1 := "Caipirinha" -reply.control.Tmp-Octets-0 := "%hmac.md5(%{control.Tmp-String-0} %{control.Tmp-String-1})" - -reply += { - Reply-Message = "The HMAC-MD5 of %{control.Tmp-String-1} in octets is %{control.Tmp-Octets-0}" - Reply-Message = "The HMAC-MD5 of %{control.Tmp-String-1} in hex is %hex(control.Tmp-Octets-0)" -} ----- - -.Output - -``` -The HMAC-MD5 of Caipirinha in octets is \317}\264@K\216\371\035\304\367\202,c\376\341\203 -The HMAC-MD5 of Caipirinha in hex is 636f6e74726f6c3a546d702d4f63746574732d30 -``` - -== %hmac.sha1(, ) - -Generate `HMAC-SHA1` of string. - -.Return: _octal_ - -.Example - -[source,unlang] ----- -control.Tmp-String-0 := "mykey" -control.Tmp-String-1 := "Caipirinha" -control.Tmp-Octets-0 := "%hmac.sha1(%{control.Tmp-String-0}, %{control.Tmp-String-1})" - -reply += { - Reply-Message = "The HMAC-SHA1 of %{control.Tmp-String-1} in octets is %{control.Tmp-Octets-0}" - Reply-Message = "The HMAC-SHA1 of %{control.Tmp-String-1} in hex is %hex(control.Tmp-Octets-0}" -} ----- - -.Output - -``` -The HMAC-SHA1 of Caipirinha in octets is \311\007\212\234j\355\207\035\225\256\372ʙ>R\"\341\351O) -The HMAC-SHA1 of Caipirinha in hex is 636f6e74726f6c3a546d702d4f63746574732d30 -``` - -== %hash.md5( ... ) - -Dynamically expands the string and performs an MD5 hash on it. The -result is binary data. - -.Return: _binary data_ - -.Example - -[source,unlang] ----- -control.Tmp-String-0 := "Caipirinha" -reply += { - Reply-Message = "md5 of %{control.Tmp-String-0} is octal=%hash.md5(%{control.Tmp-String-0})" - Reply-Message = "md5 of %{control.Tmp-String-0} is hex=%hex(%hash.md5(%{control.Tmp-String-0}))" -} ----- - -.Output - -``` -md5 of Caipirinha is octal=\024\204\013md||\230\243\3472\3703\330n\251 -md5 of Caipirinha is hex=14840b6d647c7c98a3e732f833d86ea9 -``` - -=== Other Hashing Functions - -The following hashes are supported for all versions of OpenSSL. - -* `%md2( ... }` -* `%hash.md4( ... }` -* `%hash.md5( ... }` -* `%sha1( ... }` -* `%sha224( ... }` -* `%sha256( ... }` -* `%sha384( ... }` -* `%sha512( ... }` - -The following hashes are supported for when OpenSSL 1.1.1 or greater -is installed. This version adds support for the `sha3` and `blake` -families of digest functions. - -* `%hash.blake2s_256( ... )` * `%hash.blake2b_512( ... )` +* `%hash.blake2s_256( ... )` +* `%hash.md4(...)` +* `%hash.md5(...)` +* `%hash.sha1( ... }` +* `%hash.sha224( ... }` +* `%hash.sha256( ... }` +* `%hash.sha384( ... }` +* `%hash.sha512( ... }` * `%hash.sha2_224( ... )` * `%hash.sha2_256( ... )` * `%hash.sha2_384( ... )` @@ -113,16 +31,16 @@ families of digest functions. * `%hash.sha3_384( ... )` * `%hash.sha3_512( ... )` -.Return: _octal_ +.Return: _octets_ .Example - [source,unlang] ---- -control.Tmp-String-0 := "Caipirinha" +User-Name := "Caipirinha" + reply += { - Reply-Message = "The md5 of %{control.Tmp-String-0} in octal is %hash.md5(%{control.Tmp-String-0}}" - Reply-Message = "The md5 of %{control.Tmp-String-0} in hex is %hex(%hash.md5(%{control.Tmp-String-0}}}" + Reply-Message = "The md5 of %{User-Name} in octal is %hash.md5(User-Name)" + Reply-Message = "The md5 of %{User-Name} in hex is %hex(%hash.md5(User-Name))" } ---- @@ -133,6 +51,5 @@ The md5 of Caipirinha in octal is \024\204\013md||\230\243\3472\3703\330n\251 The md5 of Caipirinha in hex is 14840b6d647c7c98a3e732f833d86ea9 ``` - // Copyright (C) 2025 Network RADIUS SAS. Licenced under CC-by-NC 4.0. // This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/reference/pages/xlat/hmac.adoc b/doc/antora/modules/reference/pages/xlat/hmac.adoc new file mode 100644 index 00000000000..ae0f22caedf --- /dev/null +++ b/doc/antora/modules/reference/pages/xlat/hmac.adoc @@ -0,0 +1,62 @@ += HMAC + +The following functions perform HMAC calculations. + +All of the hash functions take a key, along with arbitrary data, and turn binary data as `octet`s. + += %hmac.md5(, ) + +Generate `HMAC-MD5` of string. + +.Return: _octal_ + +.Example + +[source,unlang] +---- +control.Tmp-String-0 := "mykey" +control.Tmp-String-1 := "Caipirinha" +reply.control.Tmp-Octets-0 := %hmac.md5(control.Tmp-String-0, control.Tmp-String-1) + +reply += { + Reply-Message = "The HMAC-MD5 of %{control.Tmp-String-1} in octets is %{control.Tmp-Octets-0}" + Reply-Message = "The HMAC-MD5 of %{control.Tmp-String-1} in hex is %hex(control.Tmp-Octets-0)" +} +---- + +.Output + +``` +The HMAC-MD5 of Caipirinha in octets is \317}\264@K\216\371\035\304\367\202,c\376\341\203 +The HMAC-MD5 of Caipirinha in hex is 636f6e74726f6c3a546d702d4f63746574732d30 +``` + +== %hmac.sha1(, ) + +Generate `HMAC-SHA1` of string. + +.Return: _octal_ + +.Example + +[source,unlang] +---- +control.Tmp-String-0 := "mykey" +control.Tmp-String-1 := "Caipirinha" +control.Tmp-Octets-0 := %hmac.sha1(control.Tmp-String-0, control.Tmp-String-1) + +reply += { + Reply-Message = "The HMAC-SHA1 of %{control.Tmp-String-1} in octets is %{control.Tmp-Octets-0}" + Reply-Message = "The HMAC-SHA1 of %{control.Tmp-String-1} in hex is %hex(control.Tmp-Octets-0}" +} +---- + +.Output + +``` +The HMAC-SHA1 of Caipirinha in octets is \311\007\212\234j\355\207\035\225\256\372ʙ>R\"\341\351O) +The HMAC-SHA1 of Caipirinha in hex is 636f6e74726f6c3a546d702d4f63746574732d30 +``` + +// Copyright (C) 2025 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// This documentation was developed by Network RADIUS SAS.