From: Alan T. DeKok <aland@freeradius.org>
Date: Tue, 10 Aug 2021 18:45:45 +0000 (-0400)
Subject: document new encoders
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=c2712f89ffa8deae50e8dce889a630349ce908f0;p=thirdparty%2Ffreeradius-server.git

document new encoders
---

diff --git a/doc/antora/modules/reference/pages/xlat/builtin.adoc b/doc/antora/modules/reference/pages/xlat/builtin.adoc
index dea42ee4cb2..d7aa20cf879 100644
--- a/doc/antora/modules/reference/pages/xlat/builtin.adoc
+++ b/doc/antora/modules/reference/pages/xlat/builtin.adoc
@@ -164,6 +164,87 @@ update reply {
 The string value of 0x7465737431 is test1
 ```
 
+== Encoders and Decoders
+
+The server supports manual encoding and decoding of a variety of
+protocols.  These expansions can be used to manually encode and decode
+raw data.
+
+In general, however, we recommend updating the dictionaries to
+automatically handle the relevant data.  The dictionaries support
+structures, bit fields, and many many more features than previous
+versions of FreeRADIUS.  There are few situations where manual
+encoding and decoding is necessary.
+
+That being said, the main use of these expansions is for the
+"internal" protocol.  This is a virtual protocol which can encode and
+decode any attribute from any protocol.
+
+If you need to store attributes in an external database, then it is
+possible to encode them via `%(encode.internal:...)`.  The result will
+be an opaque hex string which can be treated as an opaque blob, and
+stored externally.  Then, when the data is needed again, it can be
+turned back into attributes via `%(decode.internal:...)`.
+
+=== %(decode.PROTO:<hex>)
+
+Decodes _hex_ as the named protocol.  The _hex_ string can be an expansion, too.
+
+The `decode.PROTO` expansion is automatically registered for every
+protocol which is used by the server.
+
+Note that the output attributes _must_ come from the same dictionary
+as the `request` they are being added to.  For example, you cannot use
+`decode.dhcpv4` inside of a virtual server which has `namespace =
+radius`.  Doing so would result in DHCPv4 attributes being inside of a
+RADIUS virtual server, which is not allowed.
+
+.Return: _integer_
+
+It returns the number of attributes which were decoded.
+
+.Example
+
+[source,unlang]
+----
+%(decode.dhcpv4:0x520d0103abcdef0206010203040506)
+%(decode.radius:0x010641424344)
+----
+
+.Output
+
+```
+&Relay-Agent-Information.Circuit-Id = 0xabcdef, &Relay-Agent-Information.Remote-Id = 0x010203040506
+&User-Name = "ABCD"
+```
+
+=== %(encode.PROTO:<list>)
+
+Encodes _list_ as the named protocol.  The _list_ can also be a series of attributes.
+
+The `encode.PROTO` expansion is automatically registered for every
+protocol which is used by the server.
+
+.Return: _octets_
+
+It returns the raw encoded data
+
+.Example
+
+[source,unlang]
+----
+%(encode.dhcpv4:&Relay-Agent-Information.Circuit-Id = 0xabcdef  &Relay-Agent-Information.Remote-Id = 0x010203040506)
+%(encode.radius:&User-Name = "ABCD")
+----
+
+.Output
+
+```
+0x520d0103abcdef0206010203040506
+0x010641424344
+```
+
+
 == Server Manipulation
 
 === %(config:<key>)