From 76c90440b7a65d1ec43685a3b6c25facd11030b1 Mon Sep 17 00:00:00 2001
From: Vivien Kraus <vivien@planete-kraus.eu>
Date: Fri, 17 Sep 2021 22:21:05 +0200
Subject: JWK: serialize and deserialize to and from SXML

---
 doc/disfluid.texi | 26 ++++++++++++++++++++++++--
 1 file changed, 24 insertions(+), 2 deletions(-)

(limited to 'doc')

diff --git a/doc/disfluid.texi b/doc/disfluid.texi
index 6f76838..596566c 100644
--- a/doc/disfluid.texi
+++ b/doc/disfluid.texi
@@ -620,7 +620,8 @@ Key parameter getters.
 Return all the public keys used by @var{jwks}.
 @end deftypefn
 
-@deftypefn {Generic method} <undefined> check-key (@var{key} @code{<key>})
+@deftypefn {Generic method} <undefined> check-key (@var{key} @code{<public-key>})
+@deftypefnx {Generic method} <undefined> check-key (@var{key} @code{<private-key>})
 @deftypefnx {Generic method} <undefined> check-key (@var{key} @code{<key-pair>})
 Check that the @var{key} parameters are consistent.
 @end deftypefn
@@ -629,7 +630,8 @@ When exchanging keys, maybe you will have them in the form of a JWK:
 an alist from symbols to strings, as a representation for a JSON
 object.
 
-@deftypefn {Generic method} <list> key->jwk (@var{key} @code{<key>})
+@deftypefn {Generic method} <list> key->jwk (@var{key} @code{<public-key>})
+@deftypefnx {Generic method} <list> key->jwk (@var{key} @code{<private-key>})
 @deftypefnx {Generic method} <list> key->jwk (@var{key} @code{<key-pair>})
 Return an alist with known parameter names for JSON.
 @end deftypefn
@@ -638,6 +640,26 @@ Return an alist with known parameter names for JSON.
 Parse @var{jwk} as a key or a key pair.
 @end deffn
 
+It is also possible to serialize and deserialize the key to and from
+SXML.
+
+@deftypefn {Generic method} <list> ->sxml (@var{key} @code{<public-key>})
+@deftypefnx {Generic method} <list> ->sxml (@var{key} @code{<private-key>})
+@deftypefnx {Generic method} <list> ->sxml (@var{key} @code{<key-pair>})
+Convert @var{key} to an SXML representation that can be parsed back
+with @code{sxml->key}.
+@end deftypefn
+
+@deffn function sxml->key @var{sxml}
+Parse the @var{sxml} fragment back to a key or a key pair. For this to
+work, you need to not touch the
+@url{https://disfluid.planete-kraus.eu/Public_002dkey-cryptography.html#Public_002dkey-cryptography}
+prefix. So, if you pass a @code{jwk} element, it should be
+@code{https://disfluid.planete-kraus.eu/Public_002dkey-cryptography.html#Public_002dkey-cryptography:jwk},
+or @code{jwk} with an explicit @code{xmlns} attribute containing
+@url{https://disfluid.planete-kraus.eu/Public_002dkey-cryptography.html#Public_002dkey-cryptography}.
+@end deffn
+
 @deftypefn {Generic method} <symbol> kty (@var{key} @code{<rsa-key-pair>})
 @deftypefnx {Generic method} <symbol> kty (@var{key} @code{<rsa-public-key>})
 @deftypefnx {Generic method} <symbol> kty (@var{key} @code{<rsa-private-key>})
-- 
cgit v1.2.3