feat: support key algorithms and add support for der/pem in PublicKey

Author: divarvel

biscuit_auth.pyi

@@ -33,6 +33,9 @@ PublicKeyProvider: TypeAlias = Union[
     Callable[[], PublicKey], Callable[[int], PublicKey]
 ]
 
+class Algorithm:
+    pass
+
 class BiscuitBuilder:
     # Create a builder from a datalog snippet and optional parameter values
     #
@@ -406,12 +409,6 @@ class PublicKey:
     # :rtype: list
     def to_bytes(self) -> bytes: ...
 
-    # Serializes a public key to a hexadecimal string
-    #
-    # :return: the public key bytes (hex-encoded)
-    # :rtype: str
-    def to_hex(self) -> str: ...
-
     # Deserializes a public key from raw bytes
     #
     # :param data: the raw bytes
@@ -428,7 +425,7 @@ class PublicKey:
     # :return: the public key
     # :rtype: PublicKey
     @classmethod
-    def from_hex(cls, data: str) -> PublicKey: ...
+    def __new__(cls, data: str) -> PublicKey: ...
 
 # ed25519 private key
 class PrivateKey:
@@ -438,12 +435,6 @@ class PrivateKey:
     # :rtype: list
     def to_bytes(self) -> bytes: ...
 
-    # Serializes a private key to a hexadecimal string
-    #
-    # :return: the private key bytes (hex-encoded)
-    # :rtype: str
-    def to_hex(self) -> str: ...
-
     # Deserializes a private key from raw bytes
     #
     # :param data: the raw bytes
@@ -460,7 +451,7 @@ class PrivateKey:
     # :return: the private key
     # :rtype: PrivateKey
     @classmethod
-    def from_hex(cls, data: str) -> PrivateKey: ...
+    def __new__(cls, data: str) -> PrivateKey: ...
 
 # A single datalog Fact
 #

biscuit_test.py

@@ -4,7 +4,7 @@
 
 import pytest
 
-from biscuit_auth import KeyPair, Authorizer, AuthorizerBuilder, Biscuit, BiscuitBuilder, BlockBuilder, Check, Fact, KeyPair, Policy, PrivateKey, PublicKey, Rule, UnverifiedBiscuit
+from biscuit_auth import Algorithm, KeyPair, Authorizer, AuthorizerBuilder, Biscuit, BiscuitBuilder, BlockBuilder, Check, Fact, KeyPair, Policy, PrivateKey, PublicKey, Rule, UnverifiedBiscuit
 
 def test_fact():
     fact = Fact('fact(1, true, "", "Test", hex:aabbcc, 2023-04-29T01:00:00Z)')
@@ -13,7 +13,7 @@ def test_fact():
 
 def test_biscuit_builder():
     kp = KeyPair()
-    pubkey = PublicKey.from_hex("acdd6d5b53bfee478bf689f8e012fe7988bf755e3d7c5152947abc149bc20189")
+    pubkey = PublicKey("ed25519/acdd6d5b53bfee478bf689f8e012fe7988bf755e3d7c5152947abc149bc20189")
 
     builder = BiscuitBuilder(
       """
@@ -81,7 +81,7 @@ def test_biscuit_builder():
     assert True
 
 def test_block_builder():
-    pubkey = PublicKey.from_hex("acdd6d5b53bfee478bf689f8e012fe7988bf755e3d7c5152947abc149bc20189")
+    pubkey = PublicKey("ed25519/acdd6d5b53bfee478bf689f8e012fe7988bf755e3d7c5152947abc149bc20189")
     builder = BlockBuilder(
       """
         string({str});
@@ -134,7 +134,7 @@ def test_block_builder():
 """
 
 def test_authorizer_builder():
-    pubkey = PublicKey.from_hex("acdd6d5b53bfee478bf689f8e012fe7988bf755e3d7c5152947abc149bc20189")
+    pubkey = PublicKey("ed25519/acdd6d5b53bfee478bf689f8e012fe7988bf755e3d7c5152947abc149bc20189")
     builder = AuthorizerBuilder(
       """
         string({str});
@@ -207,7 +207,7 @@ def test_authorizer_limits():
 
 
 def test_key_selection():
-    private_key = PrivateKey.from_hex("473b5189232f3f597b5c2f3f9b0d5e28b1ee4e7cce67ec6b7fbf5984157a6b97")
+    private_key = PrivateKey("ed25519/473b5189232f3f597b5c2f3f9b0d5e28b1ee4e7cce67ec6b7fbf5984157a6b97")
     root = KeyPair.from_private_key(private_key)
     other_root = KeyPair()
 
@@ -238,7 +238,7 @@ def choose_key(kid):
       pass
 
 def test_complete_lifecycle():
-    private_key = PrivateKey.from_hex("473b5189232f3f597b5c2f3f9b0d5e28b1ee4e7cce67ec6b7fbf5984157a6b97")
+    private_key = PrivateKey("ed25519/473b5189232f3f597b5c2f3f9b0d5e28b1ee4e7cce67ec6b7fbf5984157a6b97")
     root = KeyPair.from_private_key(private_key)
 
     biscuit_builder = BiscuitBuilder("user({id})", { 'id': "1234" })
@@ -267,7 +267,7 @@ def test_complete_lifecycle():
     assert facts[0].terms == ["1234"]
 
 def test_snapshot():
-    private_key = PrivateKey.from_hex("473b5189232f3f597b5c2f3f9b0d5e28b1ee4e7cce67ec6b7fbf5984157a6b97")
+    private_key = PrivateKey("ed25519/473b5189232f3f597b5c2f3f9b0d5e28b1ee4e7cce67ec6b7fbf5984157a6b97")
     root = KeyPair.from_private_key(private_key)
 
     biscuit_builder = BiscuitBuilder("user({id})", { 'id': "1234" })
@@ -318,46 +318,46 @@ def test_snapshot():
 
 def test_public_keys():
     # Happy path (hex to bytes and back)
-    public_key_from_hex = PublicKey.from_hex("acdd6d5b53bfee478bf689f8e012fe7988bf755e3d7c5152947abc149bc20189")
+    public_key_from_hex = PublicKey("ed25519/acdd6d5b53bfee478bf689f8e012fe7988bf755e3d7c5152947abc149bc20189")
     public_key_bytes = bytes(public_key_from_hex.to_bytes())
-    public_key_from_bytes = PublicKey.from_bytes(public_key_bytes)
-    assert public_key_from_bytes.to_hex() == "acdd6d5b53bfee478bf689f8e012fe7988bf755e3d7c5152947abc149bc20189"
+    public_key_from_bytes = PublicKey.from_bytes(public_key_bytes, Algorithm.Ed25519)
+    assert repr(public_key_from_bytes) == "ed25519/acdd6d5b53bfee478bf689f8e012fe7988bf755e3d7c5152947abc149bc20189"
 
     # Not valid hex
     with pytest.raises(ValueError):
-        PublicKey.from_hex("notarealkey")
+        PublicKey("notarealkey")
 
     # Valid hex, but too short
     with pytest.raises(ValueError):
-        PublicKey.from_hex("deadbeef1234")
+        PublicKey("ed25519/deadbeef1234")
 
     # Not enough bytes
     with pytest.raises(ValueError):
-        PublicKey.from_bytes(b"1230fw9ia3")
+        PublicKey.from_bytes(b"1230fw9ia3", Algorithm.Ed25519)
 
 def test_private_keys():
     # Happy path (hex to bytes and back)
-    private_key_from_hex = PrivateKey.from_hex("12aca40167fbdd1a11037e9fd440e3d510d9d9dea70a6646aa4aaf84d718d75a")
+    private_key_from_hex = PrivateKey("ed25519/12aca40167fbdd1a11037e9fd440e3d510d9d9dea70a6646aa4aaf84d718d75a")
     private_key_bytes = bytes(private_key_from_hex.to_bytes())
-    private_key_from_bytes = PrivateKey.from_bytes(private_key_bytes)
-    assert private_key_from_bytes.to_hex() == "12aca40167fbdd1a11037e9fd440e3d510d9d9dea70a6646aa4aaf84d718d75a"
+    private_key_from_bytes = PrivateKey.from_bytes(private_key_bytes, Algorithm.Ed25519)
+    assert repr(private_key_from_bytes) == "ed25519/12aca40167fbdd1a11037e9fd440e3d510d9d9dea70a6646aa4aaf84d718d75a"
 
     # Not valid hex
     with pytest.raises(ValueError):
-        PrivateKey.from_hex("notarealkey")
+        PrivateKey("notarealkey")
 
     # Valid hex, but too short
     with pytest.raises(ValueError):
-        PrivateKey.from_hex("deadbeef1234")
+        PrivateKey("ed25519/deadbeef1234")
 
     # Not enough bytes
     with pytest.raises(ValueError):
-        PrivateKey.from_bytes(b"1230fw9ia3")
+        PrivateKey.from_bytes(b"1230fw9ia3", Algorithm.Ed25519)
 
 
 def test_biscuit_inspection():
     kp = KeyPair()
-    pubkey = PublicKey.from_hex("acdd6d5b53bfee478bf689f8e012fe7988bf755e3d7c5152947abc149bc20189")
+    pubkey = PublicKey("ed25519/acdd6d5b53bfee478bf689f8e012fe7988bf755e3d7c5152947abc149bc20189")
 
     builder = BiscuitBuilder(
       """
@@ -391,7 +391,7 @@ def test_biscuit_inspection():
     assert utoken2.block_source(1) == "test(false);\n"
 
 def test_biscuit_revocation_ids():
-    public_key = PublicKey.from_hex("acdd6d5b53bfee478bf689f8e012fe7988bf755e3d7c5152947abc149bc20189")
+    public_key = PublicKey("ed25519/acdd6d5b53bfee478bf689f8e012fe7988bf755e3d7c5152947abc149bc20189")
 
     token = Biscuit.from_base64("Ep8BCjUKB3VzZXJfaWQKBWFsaWNlCgVmaWxlMRgDIgoKCAiACBIDGIEIIg4KDAgHEgMYgQgSAxiCCBIkCAASINFHns5iUW6aZiXA0GoqXyrpvFXrquiRGBZjPy3VJPoHGkAC0oew5bIngBkvg1FThYPBf30CAOBksyofzweJnmT_sQ5N4yT1xevHLImmPkJDFyJs9VXrQtroGy_UY5z3WREIGsgBCl4KATAKATEYAyouCgsIBBIDCIMIEgIYABIHCAISAwiDCBIICIAIEgMIhAgSDAgHEgMIhAgSAwiDCDIkCiIKAggbEgcIAhIDCIMIEgYIAxICGAASCwgEEgMIgwgSAhgAEiQIABIg2QCord1Cw30xC2Oea3AuAOPZ2Mvm9-EQmV3zN7zXwQEaQCLnXqIAz3srYrOJKY_g3slzt_nH5U52w8QYEdcuqCxoInvJB5t9BZht4X75MBzM3Aj1AjRVOGmH0ebuQ5GxnwYagwEKGQoFZmlsZTIYAyIOCgwIBxIDGIEIEgMYhQgSJAgAEiAMOoeV68xL1RTh_y4VeK3DUDBP_gnlPSsckzo87Pf7ihpAFAo2Mf7K5VC1HlC5uCK5R_tIXIAHCzRIL6EWzepWAUAWSh0KlZtA_tinJ-L2LAtXY1dgxIjIvw7agO5ZFVjECSIiCiBuSznFYC0NJn8VmDlZmiq1GpBSOERAwHjLZoQJG_24NA==", public_key)
     utoken = UnverifiedBiscuit.from_base64("Ep8BCjUKB3VzZXJfaWQKBWFsaWNlCgVmaWxlMRgDIgoKCAiACBIDGIEIIg4KDAgHEgMYgQgSAxiCCBIkCAASINFHns5iUW6aZiXA0GoqXyrpvFXrquiRGBZjPy3VJPoHGkAC0oew5bIngBkvg1FThYPBf30CAOBksyofzweJnmT_sQ5N4yT1xevHLImmPkJDFyJs9VXrQtroGy_UY5z3WREIGsgBCl4KATAKATEYAyouCgsIBBIDCIMIEgIYABIHCAISAwiDCBIICIAIEgMIhAgSDAgHEgMIhAgSAwiDCDIkCiIKAggbEgcIAhIDCIMIEgYIAxICGAASCwgEEgMIgwgSAhgAEiQIABIg2QCord1Cw30xC2Oea3AuAOPZ2Mvm9-EQmV3zN7zXwQEaQCLnXqIAz3srYrOJKY_g3slzt_nH5U52w8QYEdcuqCxoInvJB5t9BZht4X75MBzM3Aj1AjRVOGmH0ebuQ5GxnwYagwEKGQoFZmlsZTIYAyIOCgwIBxIDGIEIEgMYhQgSJAgAEiAMOoeV68xL1RTh_y4VeK3DUDBP_gnlPSsckzo87Pf7ihpAFAo2Mf7K5VC1HlC5uCK5R_tIXIAHCzRIL6EWzepWAUAWSh0KlZtA_tinJ-L2LAtXY1dgxIjIvw7agO5ZFVjECSIiCiBuSznFYC0NJn8VmDlZmiq1GpBSOERAwHjLZoQJG_24NA==")
@@ -408,7 +408,7 @@ def test_biscuit_revocation_ids():
     ]
 
 def test_unverified_biscuit_signature_check():
-    public_key = PublicKey.from_hex("acdd6d5b53bfee478bf689f8e012fe7988bf755e3d7c5152947abc149bc20189")
+    public_key = PublicKey("ed25519/acdd6d5b53bfee478bf689f8e012fe7988bf755e3d7c5152947abc149bc20189")
 
     utoken = UnverifiedBiscuit.from_base64("Ep8BCjUKB3VzZXJfaWQKBWFsaWNlCgVmaWxlMRgDIgoKCAiACBIDGIEIIg4KDAgHEgMYgQgSAxiCCBIkCAASINFHns5iUW6aZiXA0GoqXyrpvFXrquiRGBZjPy3VJPoHGkAC0oew5bIngBkvg1FThYPBf30CAOBksyofzweJnmT_sQ5N4yT1xevHLImmPkJDFyJs9VXrQtroGy_UY5z3WREIGsgBCl4KATAKATEYAyouCgsIBBIDCIMIEgIYABIHCAISAwiDCBIICIAIEgMIhAgSDAgHEgMIhAgSAwiDCDIkCiIKAggbEgcIAhIDCIMIEgYIAxICGAASCwgEEgMIgwgSAhgAEiQIABIg2QCord1Cw30xC2Oea3AuAOPZ2Mvm9-EQmV3zN7zXwQEaQCLnXqIAz3srYrOJKY_g3slzt_nH5U52w8QYEdcuqCxoInvJB5t9BZht4X75MBzM3Aj1AjRVOGmH0ebuQ5GxnwYagwEKGQoFZmlsZTIYAyIOCgwIBxIDGIEIEgMYhQgSJAgAEiAMOoeV68xL1RTh_y4VeK3DUDBP_gnlPSsckzo87Pf7ihpAFAo2Mf7K5VC1HlC5uCK5R_tIXIAHCzRIL6EWzepWAUAWSh0KlZtA_tinJ-L2LAtXY1dgxIjIvw7agO5ZFVjECSIiCiBuSznFYC0NJn8VmDlZmiq1GpBSOERAwHjLZoQJG_24NA==")
 
@@ -423,13 +423,13 @@ def test_append_on_unverified():
 
 def test_keypair_from_private_key_der():
     private_key_der = bytes.fromhex("302e020100300506032b6570042204200499694d0da05dcac40052663e71d50c1539465f8926dfe92033cf7aaad53d65")
-    private_key_hex = "0499694d0da05dcac40052663e71d50c1539465f8926dfe92033cf7aaad53d65"
-    kp = KeyPair.from_private_key_der(der=private_key_der)
-    assert kp.private_key.to_hex() == private_key_hex
+    private_key_hex = "ed25519/0499694d0da05dcac40052663e71d50c1539465f8926dfe92033cf7aaad53d65"
+    kp = KeyPair.from_private_key(PrivateKey.from_der(der=private_key_der))
+    assert repr(kp.private_key) == private_key_hex
 
 
 def test_keypair_from_private_key_pem():
     private_key_pem = "-----BEGIN PRIVATE KEY-----\nMC4CAQAwBQYDK2VwBCIEIASZaU0NoF3KxABSZj5x1QwVOUZfiSbf6SAzz3qq1T1l\n-----END PRIVATE KEY-----"
-    private_key_hex = "0499694d0da05dcac40052663e71d50c1539465f8926dfe92033cf7aaad53d65"
-    kp = KeyPair.from_private_key_pem(pem=private_key_pem)
-    assert kp.private_key.to_hex() == private_key_hex
+    private_key_hex = "ed25519/0499694d0da05dcac40052663e71d50c1539465f8926dfe92033cf7aaad53d65"
+    kp = KeyPair.from_private_key(PrivateKey.from_pem(pem=private_key_pem))
+    assert repr(kp.private_key) == private_key_hex

docs/basic-use.rst

@@ -11,23 +11,23 @@ Create and manage keypairs
 >>> # random keypair
 >>> keypair = KeyPair()
 >>> # serialize a keypair to hexadecimal strings
->>> private_key_str = keypair.private_key.to_hex()
->>> public_key_str = keypair.public_key.to_hex()
+>>> private_key_str = repr(keypair.private_key)
+>>> public_key_str = repr(keypair.public_key)
 >>> # parse a private key from an hex string
->>> parsed_private_key = PrivateKey.from_hex("23d9d45b32899eefd4cde9a2caecdd41f0449c95ee1e4c6b53ef38cb957dd690")
+>>> parsed_private_key = PrivateKey("ed25519/23d9d45b32899eefd4cde9a2caecdd41f0449c95ee1e4c6b53ef38cb957dd690")
 >>> # parse a public key from an hex string
->>> parsed_public_key = PublicKey.from_hex("9e124fbb46ff99a87219aef4b09f4f6c3b7fd96b7bd279e38af3ef429a101c69")
+>>> parsed_public_key = PublicKey("ed25519/9e124fbb46ff99a87219aef4b09f4f6c3b7fd96b7bd279e38af3ef429a101c69")
 >>> # build a keypair from a private key
 >>> parsed_keypair = KeyPair.from_private_key(parsed_private_key)
->>> parsed_keypair.private_key.to_hex()
-'23d9d45b32899eefd4cde9a2caecdd41f0449c95ee1e4c6b53ef38cb957dd690'
->>> parsed_keypair.public_key.to_hex()
-'9e124fbb46ff99a87219aef4b09f4f6c3b7fd96b7bd279e38af3ef429a101c69'
+>>> parsed_keypair.private_key
+ed25519/23d9d45b32899eefd4cde9a2caecdd41f0449c95ee1e4c6b53ef38cb957dd690
+>>> parsed_keypair.public_key
+ed25519/9e124fbb46ff99a87219aef4b09f4f6c3b7fd96b7bd279e38af3ef429a101c69
 
 Build a biscuit token
 ---------------------
 
->>> private_key = PrivateKey.from_hex("23d9d45b32899eefd4cde9a2caecdd41f0449c95ee1e4c6b53ef38cb957dd690")
+>>> private_key = PrivateKey("ed25519/23d9d45b32899eefd4cde9a2caecdd41f0449c95ee1e4c6b53ef38cb957dd690")
 >>> token = BiscuitBuilder("""
 ... user({user_id});
 ... check if time($time), $time < {expiration};
@@ -41,7 +41,7 @@ Build a biscuit token
 
 Biscuit tokens can carry a root key identifier, helping the verifying party select the correct public key amongst several valid keys. This is especially useful when performing key rotation, when multiple keys are active at the same time.
 
->>> private_key = PrivateKey.from_hex("00731a0f129f088e069d8a8b3523a724bc48136bfc22c916cb754adbf503ad5e")
+>>> private_key = PrivateKey("ed25519/00731a0f129f088e069d8a8b3523a724bc48136bfc22c916cb754adbf503ad5e")
 >>> builder = BiscuitBuilder("""
 ... user({user_id});
 ... check if time($time), $time < {expiration};
@@ -70,7 +70,7 @@ Append a block to a biscuit token
 Parse and authorize a biscuit token
 -----------------------------------
 
->>> public_key = PublicKey.from_hex("9e124fbb46ff99a87219aef4b09f4f6c3b7fd96b7bd279e38af3ef429a101c69")
+>>> public_key = PublicKey("ed25519/9e124fbb46ff99a87219aef4b09f4f6c3b7fd96b7bd279e38af3ef429a101c69")
 >>> token = Biscuit.from_base64("En0KEwoEMTIzNBgDIgkKBwgKEgMYgAgSJAgAEiCp8D9laR_CXmFmiUlo6zi8L63iapXDxX1evELp4HVaBRpAx3Mkwu2f2AcNq48IZwu-pxACq1stL76DSMGEugmiduuTVwMqLmgKZ4VFgzeydCrYY_Id3MkxgTgjXzEHUH4DDSIiCiB55I7ykL9wQXHRDqUnSgZwCdYNdO7c8LZEj0VH5sy3-Q==", public_key)
 >>> authorizer = AuthorizerBuilder( """ time({now}); allow if user($u); """, { 'now': datetime.now(tz = timezone.utc)} ).build(token)
 >>> authorizer.authorize()
@@ -80,9 +80,9 @@ In order to help with key rotation, biscuit tokens can optionally carry a root k
 
 >>> def public_key_fn(kid):
 ...   if kid is None:
-...     return PublicKey.from_hex("9e124fbb46ff99a87219aef4b09f4f6c3b7fd96b7bd279e38af3ef429a101c69")
+...     return PublicKey("ed25519/9e124fbb46ff99a87219aef4b09f4f6c3b7fd96b7bd279e38af3ef429a101c69")
 ...   elif kid == 1:
-...     return PublicKey.from_hex("1d211ddaf521cc45b620431817ba4fe0457be467ba4d724ecf514db3070b53cc")
+...     return PublicKey("ed25519/1d211ddaf521cc45b620431817ba4fe0457be467ba4d724ecf514db3070b53cc")
 ...   else:
 ...     raise Exception("unknown key identifier")
 >>> token = Biscuit.from_base64("CAESfQoTCgQxMjM0GAMiCQoHCAoSAxiACBIkCAASII5WVsvM52T91C12wnzButmyzmtGSX_rbM6hCSIJihX2GkDwAcVxTnY8aeMLm-i2R_VzTfIMQZya49ogXO2h2Fg2TJsDcG3udIki9il5PA05lKUwrfPNroS7Qg5e04AyLLcHIiIKII5rh75jrCrgE6Rzw6GVYczMn1IOo287uO4Ef5wp7obY", public_key_fn)

docs/datalog.rst

@@ -34,7 +34,7 @@ Rules, checks and policies can also contain parameters for public keys. Those ar
 ... check if admin({user}) trusting {rights_service_pubkey}
 ... """,
 ... {'user': "abcd" },
-... {'rights_service_pubkey': PublicKey.from_hex("9e124fbb46ff99a87219aef4b09f4f6c3b7fd96b7bd279e38af3ef429a101c69") })
+... {'rights_service_pubkey': PublicKey("ed25519/9e124fbb46ff99a87219aef4b09f4f6c3b7fd96b7bd279e38af3ef429a101c69") })
 check if admin("abcd") trusting ed25519/9e124fbb46ff99a87219aef4b09f4f6c3b7fd96b7bd279e38af3ef429a101c69;
 <BLANKLINE>