Merge pull request #129 from minvws/rid

Implemented RID exchange and receive

Author: jaytaph

.github/workflows/ci.yaml

@@ -99,6 +99,20 @@ jobs:
         name: Run the tests
         runs-on: ubuntu-24.04
         needs: build
+        services:
+          prs_db:
+            image: postgres:15
+            env:
+              POSTGRES_USER: postgres
+              POSTGRES_PASSWORD: postgres
+              POSTGRES_DB: testing
+            ports:
+              - 5432:5432
+            options: >-
+              --health-cmd pg_isready
+              --health-interval 10s
+              --health-timeout 5s
+              --health-retries 5
 
         steps:
             - name: Checkout repository
@@ -109,8 +123,25 @@ jobs:
               with:
                 python_version: "3.11"
 
+            - name: install dependencies
+              run: |
+                sudo apt update
+                sudo apt install -y libpq-dev build-essential postgresql-client
+
+            - name: install liboprf
+              run: |
+                sudo apt install -y libsodium-dev
+                git clone https://github.com/stef/liboprf.git
+                cd liboprf/src
+                make
+                sudo make install
+                sudo ldconfig
+
             - name: Run the tests
-              run: poetry run $(make test --just-print --silent)
+              run: |
+                sudo bash -c 'echo "127.0.0.1 prs_db" >> /etc/hosts'
+                ./tools/migrate_db.sh prs_db postgres postgres testing
+                poetry run $(make test --just-print --silent)
 
             - name: Upload coverage report
               uses: actions/upload-artifact@v4

Makefile

@@ -26,7 +26,7 @@ type-check: ## Check for typing errors
 	$(RUN_PREFIX) mypy app tests
 
 safety-check: ## Check for security vulnerabilities
-	$(RUN_PREFIX) pip-audit
+	$(RUN_PREFIX) pip-audit --ignore-vuln GHSA-4xh5-x5gv-qwph
 
 spelling-check: ## Check spelling mistakes
 	$(RUN_PREFIX) codespell .

app.conf.example

@@ -92,3 +92,5 @@ server_key_file=
 hmac_key=
 ; AES key for pseudonym encryption
 aes_key=
+; AES key for rid encryption
+rid_aes_key=

app/config.py

@@ -136,6 +136,7 @@ class ConfigOprf(BaseModel):
 class ConfigPseudonym(BaseModel):
     hmac_key: str | None = Field(default=None)
     aes_key: str | None = Field(default=None)
+    rid_aes_key: str | None = Field(default=None)
 
 
 class Config(BaseModel):

app/container.py

@@ -21,6 +21,7 @@
 from app.services.rid_cache import RidCache
 from app.services.rid_service import RidService
 from app.services.tls_service import TLSService
+from app.services.tmp_rid_service import TmpRidService
 
 
 def container_config(binder: inject.Binder) -> None:
@@ -96,6 +97,14 @@ def container_config(binder: inject.Binder) -> None:
     )
     binder.bind(PseudonymService, pseudonym_service)
 
+    tmp_rid_service = TmpRidService(
+        base64.urlsafe_b64decode(config.pseudonym.rid_aes_key or ""),
+    )
+    binder.bind(TmpRidService, tmp_rid_service)
+
+
+def get_tmp_rid_service() -> TmpRidService:
+    return inject.instance(TmpRidService)
 
 def get_pseudonym_service() -> PseudonymService:
     return inject.instance(PseudonymService)

app/db/entities/key_entry.py

@@ -14,11 +14,13 @@ class KeyEntry(Base):
     organization = Column(String, nullable=False)
     scope = Column(JSONB, nullable=False, server_default="{}")
     key = Column(Text, nullable=False)
+    max_rid_usage = Column(String, nullable=False)
 
     def to_dict(self) -> dict[str, Any]:
         return {
             "key_id": str(self.entry_id),
             "organization": self.organization,
             "scope": self.scope,
             "pub_key": self.key,
+            "max_rid_usage": self.max_rid_usage,
         }

app/db/repositories/key_entry_repository.py

@@ -42,20 +42,22 @@ def get_by_org(self, organization: str) -> Optional[Sequence[KeyEntry]]:
         query = select(KeyEntry).where(KeyEntry.organization == organization)
         return self.db_session.session.execute(query).scalars().all()
 
-    def create(self, organization: str, scope: list[str], pub_key: str) -> KeyEntry:
+    def create(self, organization: str, scope: list[str], pub_key: str, max_usage_level: str) -> KeyEntry:
         """
         Creates a new key entry.
         """
         entry = KeyEntry(
             organization=organization,
             scope=scope,
             key=pub_key,
+            max_rid_usage=max_usage_level,
         )
         self.db_session.session.add(entry)
+        self.db_session.session.flush()
 
         return entry
 
-    def update(self, entry_id: str, scope: list[str], pub_key: str) -> Optional[KeyEntry]:
+    def update(self, entry_id: str, scope: list[str], pub_key: str, max_usage_level: str) -> Optional[KeyEntry]:
         """
         Updates an existing key entry.
         """
@@ -65,5 +67,6 @@ def update(self, entry_id: str, scope: list[str], pub_key: str) -> Optional[KeyE
 
         entry.scope = scope # type: ignore
         entry.key = pub_key # type: ignore
+        entry.max_rid_usage = max_usage_level # type: ignore
         self.db_session.session.add(entry)
         return entry

app/models/requests.py

@@ -1,9 +1,37 @@
-from typing import Any
+from typing import Any, Literal
 
 from pydantic import BaseModel, ConfigDict, model_validator
 
 from app.personal_id import PersonalId
 from app.services.pseudonym_service import PseudonymType
+from app.rid import RidUsage
+
+class RidReceiveRequest(BaseModel):
+    rid: str
+    recipientOrganization: str
+    recipientScope: str
+    pseudonymType: Literal['rp', 'irp', 'bsn']
+
+class RidExchangeRequest(BaseModel):
+    personalId: Any
+    recipientOrganization: str
+    recipientScope: str
+    ridUsage: Any
+
+    @model_validator(mode="before")
+    @classmethod
+    def convert_personal_id(cls, data: dict[str, Any]) -> dict[str, Any]:
+        pid = data.get("personalId")
+        if isinstance(pid, str):
+            data["personalId"] = PersonalId.from_str(pid)
+        if isinstance(pid, dict):
+            data["personalId"] = PersonalId.from_dict(pid)
+
+        ridUsage = data.get("ridUsage")
+        if isinstance(ridUsage, str):
+            data["ridUsage"] = RidUsage(ridUsage)
+
+        return data
 
 
 class ExchangeRequest(BaseModel):

app/rid.py

@@ -0,0 +1,31 @@
+from enum import Enum
+from typing import Dict, Set
+
+# Define which pseudonym types are allowed for each RID usage
+ALLOWED_BY_RID_USAGE: Dict[str, Set[str]] = {
+    "bsn": {"bsn", "rp", "irp"},
+    "rp": {"rp", "irp"},
+    "irp": {"irp"},
+}
+
+# Define the minimum RID usage required for each pseudonym type
+REQUIRED_MIN_USAGE = {
+    "bsn": "Bsn",
+    "rp": "ReversiblePseudonym",
+    "irp": "IrreversiblePseudonym",
+}
+
+# Mapping of RID usage to their rank (higher number can exchange lowr number)
+USAGE_RANK = {
+    "IrreversiblePseudonym": 1,
+    "ReversiblePseudonym": 2,
+    "Bsn": 3,
+}
+
+class RidUsage(str, Enum):
+    Bsn = "bsn"
+    ReversiblePseudonym = "rp"
+    IrreversiblePseudonym = "irp"
+
+    def __str__(self) -> str:
+        return self.value

app/routers/exchange.py

@@ -1,16 +1,139 @@
+import json
 import logging
+from typing import Dict, Any
+
 from fastapi import APIRouter, Depends, HTTPException
 from starlette.responses import JSONResponse, Response
 
 from app import container
-from app.models.requests import ExchangeRequest
+from app.models.requests import ExchangeRequest, RidExchangeRequest, RidReceiveRequest
+from app.rid import ALLOWED_BY_RID_USAGE, REQUIRED_MIN_USAGE, USAGE_RANK
 from app.services.key_resolver import KeyResolver
 from app.services.oprf.jwe_token import BlindJwe
 from app.services.pseudonym_service import PseudonymService, PseudonymType
+from app.services.tmp_rid_service import TmpRidService
 
 logger = logging.getLogger(__name__)
 router = APIRouter()
 
+
+@router.post("/receive", summary="Receive and decrypt RID")
+def receive(
+    req: RidReceiveRequest,
+    key_resolver: KeyResolver = Depends(container.get_key_resolver),
+    rid_service: TmpRidService = Depends(container.get_tmp_rid_service),
+) -> Response:
+    """
+    Receive and decrypt a RID, validate it, and return a pseudonym of the requested type if allowed.
+    """
+    if not req.rid.startswith("rid:"):
+        raise HTTPException(status_code=400, detail="Invalid RID format")
+    rid = req.rid.removeprefix("rid:")
+
+    try:
+        plaintext = rid_service.decrypt_rid(rid)
+        if not plaintext:
+            raise Exception("Empty plaintext")
+    except Exception:
+        raise HTTPException(status_code=400, detail="Failed to decrypt RID")
+
+
+    try:
+        payload: Dict[str, Any] = json.loads(plaintext)
+    except json.JSONDecodeError:
+        raise HTTPException(status_code=400, detail="Malformed RID payload")
+
+    recipient_org = payload.get("recipient_organization")
+    recipient_scope = payload.get("recipient_scope")
+    rid_usage = payload.get("usage")
+
+    # Make sure the recipient org/scope matches what is in the RID
+    if recipient_org != req.recipientOrganization or recipient_scope != req.recipientScope:
+        raise HTTPException(
+            status_code=400,
+            detail="RID not intended for this organization and/or scope",
+        )
+
+    # Make sure we have got the correct permissions to exchange the requested pseudonym type
+    if rid_usage not in ALLOWED_BY_RID_USAGE:
+        raise HTTPException(status_code=400, detail="Unsupported RID usage")
+
+    if req.pseudonymType not in ALLOWED_BY_RID_USAGE[rid_usage]:
+        raise HTTPException(
+            status_code=400,
+            detail="Requested pseudonym type not allowed for this RID",
+        )
+
+    max_rid_usage = key_resolver.max_rid_usage(req.recipientOrganization, req.recipientScope)
+    if max_rid_usage is None:
+        raise HTTPException(
+            status_code=400,
+            detail="Organization / scope is not allowed to exchange RIDs",
+        )
+
+    required = REQUIRED_MIN_USAGE.get(req.pseudonymType)
+    if required is None:
+        raise HTTPException(status_code=400, detail="Unsupported pseudonym type")
+
+    if USAGE_RANK.get(max_rid_usage.name, 0) < USAGE_RANK[required]:
+        msg = {
+            "bsn": "BSNs",
+            "rp": "reversible pseudonyms or higher",
+            "irp": "irreversible pseudonyms or higher",
+        }[req.pseudonymType]
+        raise HTTPException(
+            status_code=400,
+            detail=f"Organization / scope is not allowed to exchange {msg}",
+        )
+
+    # TODO: Here we would generate the actual pseudonyms
+    if req.pseudonymType == "bsn":
+        value = "bsn:foobar"
+    elif req.pseudonymType == "rp":
+        value = "pseudonym:reversible:foobar"
+    else:
+        value = "pseudonym:irreversible:foobar"
+
+    return JSONResponse(content={"pseudonym": value, "type": req.pseudonymType})
+
+
+@router.post("/exchange/rid", summary="Exchange RID")
+def exchange_rid(
+    req: RidExchangeRequest,
+    key_resolver: KeyResolver = Depends(container.get_key_resolver),
+    rid_service: TmpRidService = Depends(container.get_tmp_rid_service),
+) -> Response:
+    """
+    Exchange a personal ID for a RID that can be used by the recipient organization/scope
+    """
+
+    rid_data = {
+        "usage": str(req.ridUsage),         # Maximum usage allowed for this RID (capped by the recipient org/scope)
+        "recipient_organization": req.recipientOrganization,
+        "recipient_scope": req.recipientScope,
+        "personal_id": req.personalId.as_str(),
+    }
+    rid_str = json.dumps(rid_data)
+    rid = rid_service.encrypt_rid(rid_str)
+
+    pub_key_jwk = key_resolver.resolve(req.recipientOrganization, req.recipientScope)
+    if pub_key_jwk is None:
+        return JSONResponse({"error": "No public key found for this organization and/or scope"}, status_code=404)
+
+    # Create a blind JWE token containing the RID
+    jwe = BlindJwe.build(
+        audience=req.recipientOrganization,
+        scope=req.recipientScope,
+        subject=f"rid:{rid}",
+        pub_key=pub_key_jwk,
+        extra_claims={
+            "ridUsage": rid_data['usage'],
+        }
+    )
+
+    return Response(status_code=201, content=jwe, headers={"Content-Type": "Multipart/Encrypted"})
+
+
 @router.post("/exchange/pseudonym", summary="Exchange pseudonym")
 def exchange_pseudonym(
     req: ExchangeRequest,