Merge pull request #184 from minvws/issue-149

Updated docs and some tests routes

Author: jaytaph

README.md

@@ -102,44 +102,46 @@ docker run -ti --rm -p 6502:6502 \
 
 This system uses OPRF for pseudonym generation. To test this, there are some available endpoints:
 
-- '/test/oprf/gen_rsa_key' - Generate a new RSA keypair for OPRF (small 1024 bit for testing)
 - '/test/oprf/oprf/client' - Emulates a client that generates OPRF information for a given input
 - '/test/oprf/oprf/receiver' - Emulates the receiver of the pseudonym and returns diagnostic information
 
 To use this system:
 
-1. First, generate a new keypair that will be used for a test organization with `/test/oprf/gen_rsa_key`.
-   ```shell
-    POST /test/oprf/gen_rsa_key 
-   
-    200 OK
-    {
-      "private_key_pem": "-----BEGIN PRIVATE KEY-----\nMIICdwIBA....neDKJ0DsvA5vfpt0=\n-----END PRIVATE KEY-----\n",
-      "public_key_pem": "-----BEGIN PUBLIC KEY-----\nMIGfMA0GCSqG....uDQIDAQAB\n-----END PUBLIC KEY-----\n",
-      "public_key_kid": "ajGAx_LKNrJ8vqdahWlSJvOznBi6lnFfSOw72Z4R4uU"
-    } 
-   ```
+1. You will need a generated UZI Server certificate (https://www.uziregister.nl/servercertificaat) or create a 
+   self-signed certificate for testing purposes.
+
+   Since the system uses mTLS, you can either setup a mTLS setup (caddy, apache, etc), or enable the override in the
+    app.conf file:
+  
+    ```
+    [app]
+    mtls_override_cert=./secrets/self-signed-uzi-server-cert.crt
  
-2. Create a new organization into the key resolver with a POST to `/keys`. Add your organization name like 
-   `ura:12345678`, and you can use scope `test` for testing. Add the **PUBLIC key** to the `public_key` field.
+2. Insert a new organization via a POST to `/orgs`. The organization ura should be the URA of the uzi certificate you 
+   will be testing with.
 
-    ```shell
-    POST /keys
-    {
-      "organization": "ura:12345678",
-      "scope": "test",
-      "public_key": "-----BEGIN PUBLIC KEY-----\nMIGfMA0GCSqG....uDQIDAQAB\n-----END PUBLIC KEY\n",
-    }
+   Note: there is no mTLS check here. You can add multiple organizations with different URA values for testing. 
+
+3. Next, you will need to register your public key to the key services. You can do this by calling `/register/certificate` with a JSON body like:
    
-    201 Created
-    ```
+   ```shell
+   POST /register/certificate
+   {
+     "scope": [
+        "nvi",
+     ]
+   }
+   ```
+   
+   This will take the public key from the uzi server certificate using in this mTLS connection, and register it for the given scope.
 
-3. Emulate a client wanting to send a pseudonym over to a receiver by calling `/test/oprf/client` with a JSON body like:
+
+4. Emulate a client wanting to send a pseudonym over to a receiver by calling `/test/oprf/client` with a JSON body like:
 
    ```shell
    POST /test/oprf/client
    {
-     "personalId": "testinput-like-a-bsn-number-or-other-id"
+     "personalId": "nl:bsn:950000012"
    }
 
    200 OK
@@ -149,7 +151,7 @@ To use this system:
    }
    ```
 
-   This returns the `blinded_input` that must be sent to the receiver, and the `blind_factor` that must be send to the
+   This returns the `blinded_input` that must be sent to the receiver, and the `blind_factor` that must be sent to the
    receiver after the server has evaluated the blinded input.
 
 4. Now we can call the "real" OPRF function `/oprf/eval` with the blinded input, the organization name and scope:
@@ -172,13 +174,13 @@ To use this system:
    is encrypted with the public key of the organization. At this point, the client is 
    not able to decrypt this information. It can only forward this to the receiver.
 
-5. Now emulate the receiver by calling `/test/oprf/receiver` with a JSON body like:
+5. Now emulate the receiving party by calling `/test/oprf/receiver` with a JSON body like:
    ```shell   
     POST /test/oprf/receiver
     {
       "blind_factor": "eNf80WNHbImaUNU-kokBr7ocELBjMtHcy0re_RKBPQ8=",
       "jwe": "eyJraWQiOiA...SzZbJUqbbSUIjqiw",
-      "priv_key_pem": "-----BEGIN RSA PRIVATE KEY-----\nMIICXAIB...oCfe0=\n-----END RSA PRIVATE KEY-----\n"
+      "priv_key_pem": "-----BEGIN RSA PRIVATE KEY----- MIICXAIB...oCfe0= -----END RSA PRIVATE KEY-----"
     }
    ```
 
@@ -190,7 +192,7 @@ To use this system:
     ```json
     {
       "jwe_data": "eyJraWQiOiAi...zZbJUqbbSUIjqiw",
-      "priv_key_pem": "-----BEGIN RSA PRIVATE KEY-----\nMIICXAIBAAKBgH6gmpXpdhtiE...UpWRvoCfe0=\n-----END RSA PRIVATE KEY-----\n",
+      "priv_key_pem": "-----BEGIN RSA PRIVATE KEY----- MIICXAIBAAKBgH6gmpXpdhtiE...UpWRvoCfe0= -----END RSA PRIVATE KEY-----",
       "priv_key_kid": "rNv1O_mXgxF6QEMfaQGvjev7RbT1FG3sJXxxsu_KHbM",
       "blind_factor": "eNf80WNHbImaUNU-kokBr7ocELBjMtHcy0re_RKBPQ8=",
       "jwe": {
@@ -216,3 +218,21 @@ To use this system:
 
     The `final_pseudonym` is the actual pseudonym that can be stored by the receiver. Note that this pseudonym is deterministic
     for the same input, organization and scope. However, it is not possible to reverse this into a BSN.
+
+
+
+# max-key-usage
+
+The max-key-usage is a property that defines what kind of pseudonyms an organization can create and reverse.
+
+There are 3 levels of max_key_usage:
+
+- BSN - can create reversible and irreversible pseudonyms, and can reverse reversible pseudonyms back to BSN
+- RP (Reversible Pseudonym) - can create reversible and irreversible pseudonyms, but cannot reverse any pseudonyms
+- IRP (Irreversible Pseudonym) - can only create irreversible pseudonyms, and cannot reverse any pseudonyms
+
+The "RP" level is mainly intended for organizations that need to create reversible pseudonyms for other organizations, 
+but is not allowed to reverse them back to BSN itself.
+
+The "IRP" level is intended for organizations that only need to create irreversible pseudonyms, and do not have access to 
+BSN information at all.

app.conf.example

@@ -1,6 +1,8 @@
 [app]
 loglevel=debug
 mtls_allow_override_cert=
+# Enable the /test routes
+enable_test_routes=True
 
 [database]
 dsn=postgresql+psycopg://postgres:postgres@postgres:5432/postgres

app.test.conf

@@ -2,6 +2,7 @@
 [app]
 loglevel=debug
 mtls_allow_override_cert=
+enable_test_routes=True
 
 [database]
 dsn=postgresql+psycopg://postgres:postgres@localhost/testing

app/application.py

@@ -72,7 +72,10 @@ def setup_fastapi() -> FastAPI:
         FastAPI(
             docs_url=config.uvicorn.docs_url,
             redoc_url=config.uvicorn.redoc_url,
-            title="PRS API",
+            title="Pseudoniemendienst API",
+            summary="API for the Pseudoniemendienst",
+            description="Provides endpoints for OPRF, key management, organization management, and RID exchange.",
+
         ) if config.uvicorn.swagger_enabled else FastAPI(
             docs_url=None,
             redoc_url=None
@@ -83,11 +86,13 @@ def setup_fastapi() -> FastAPI:
         default_router,
         health_router,
         oprf_router,
-        test_oprf_router,
         key_router,
         exchange_router,
         org_router,
     ]
+    if config.app.enable_test_routes:
+        routers.append(test_oprf_router)
+
     for router in routers:
         fastapi.include_router(router)
 

app/config.py

@@ -22,6 +22,7 @@ class LogLevel(str, Enum):
 class ConfigApp(BaseModel):
     loglevel: LogLevel = Field(default=LogLevel.info)
     mtls_override_cert: str | None = Field(default=None)
+    enable_test_routes: bool = Field(default=False)
 
 class ConfigDatabase(BaseModel):
     dsn: str

app/routers/exchange.py

@@ -37,7 +37,7 @@ def __init__(self, ura: str, scope: str) -> None:
         super().__init__(status_code=404, detail=f"No public key found for organization '{ura}' and scope '{scope}'")
 
 
-@router.post("/receive", summary="Receive and decrypt RID")
+@router.post("/receive", summary="Receive and decrypt RID", tags=["Exchange Services"])
 def receive(
     req: RidReceiveRequest,
     key_resolver: KeyResolver = Depends(container.get_key_resolver),
@@ -136,7 +136,7 @@ def receive(
     return JSONResponse(content={"pseudonym": value, "type": req.pseudonymType})
 
 
-@router.post("/exchange/rid", summary="Exchange RID")
+@router.post("/exchange/rid", summary="Exchange RID", tags=["Exchange Services"])
 def exchange_rid(
     req: RidExchangeRequest,
     key_resolver: KeyResolver = Depends(container.get_key_resolver),
@@ -180,7 +180,7 @@ def exchange_rid(
 
     return Response(status_code=201, content=jwe, headers={"Content-Type": "application/jwe"})
 
-@router.post("/exchange/pseudonym", summary="Exchange pseudonym")
+@router.post("/exchange/pseudonym", summary="Exchange pseudonym", tags=["Exchange Services"])
 def exchange_pseudonym(
     req: ExchangeRequest,
     request: Request,

app/routers/key.py

@@ -14,7 +14,7 @@
 logger = logging.getLogger(__name__)
 router = APIRouter()
 
-@router.post("/register/certificate", summary="Insert public key information for an organization", tags=["key-service"])
+@router.post("/register/certificate", summary="Insert public key information for an organization", tags=["Key Registration Services"])
 def post_key(
     req: RegisterRequest,
     request: Request,
@@ -38,7 +38,7 @@ def post_key(
     return JSONResponse(status_code=201, content={"message": "Key created successfully"})
 
 
-@router.get("/keys/{ura}", summary="List public key information for an organization", tags=["key-service"])
+@router.get("/keys/{ura}", summary="List public key information for an organization", tags=["Key Registration Services"])
 def list_keys_for_org(
     ura: str,
     key_resolver: KeyResolver = Depends(container.get_key_resolver),
@@ -55,7 +55,7 @@ def list_keys_for_org(
     return JSONResponse(status_code=200, content=[e.to_dict() for e in entries])
 
 
-@router.put("/keys/{key_id}", summary="Update specific key for key/scope", tags=["key-service"])
+@router.put("/keys/{key_id}", summary="Update specific key for key/scope", tags=["Key Registration Services"])
 def put_key(
     key_id: str,
     req: KeyRequest,
@@ -79,7 +79,7 @@ def put_key(
     return JSONResponse(status_code=200, content=updated_entry.to_dict())
 
 
-@router.delete("/keys/{key_id}", summary="Delete specific key for key/scope", tags=["key-service"])
+@router.delete("/keys/{key_id}", summary="Delete specific key for key/scope", tags=["Key Registration Services"])
 def delete_key(
     key_id: str,
     key_resolver: KeyResolver = Depends(container.get_key_resolver),

app/routers/oprf.py

@@ -11,7 +11,7 @@
 logger = logging.getLogger(__name__)
 router = APIRouter()
 
-@router.post("/oprf/eval", summary="Evaluate OPRF blind and returns an encrypted JWE for the organization", tags=["oprf"])
+@router.post("/oprf/eval", summary="Evaluate OPRF blind and returns an encrypted JWE for the organization", tags=["OPRF Services"])
 def post_eval(
     req: BlindRequest,
     key_resolver: KeyResolver = Depends(container.get_key_resolver),

app/routers/org.py

@@ -12,7 +12,7 @@
 logger = logging.getLogger(__name__)
 router = APIRouter()
 
-@router.post("/orgs", summary="Create new organization", tags=["org-service"])
+@router.post("/orgs", summary="Create new organization", tags=["Organizational Services"])
 def post_org(
     req: OrgRequest,
     org_service: OrgService = Depends(container.get_org_service),
@@ -28,7 +28,7 @@ def post_org(
     return JSONResponse(status_code=201, content={"message": "Org created successfully"})
 
 
-@router.get("/org/{ura}", summary="List organization", tags=["org-service"])
+@router.get("/org/{ura}", summary="List organization", tags=["Organizational Services"])
 def list_keys_for_org(
     ura: str,
     org_service: OrgService = Depends(container.get_org_service),
@@ -40,7 +40,7 @@ def list_keys_for_org(
     return JSONResponse(status_code=200, content=org.to_dict())
 
 
-@router.put("/org/{ura}", summary="Update specific org", tags=["org-service"])
+@router.put("/org/{ura}", summary="Update specific org", tags=["Organizational Services"])
 def put_org(
     ura: str,
     req: OrgRequest,
@@ -62,7 +62,7 @@ def put_org(
     return JSONResponse(status_code=200, content=updated_entry.to_dict())
 
 
-@router.delete("/org/{ura}", summary="Delete specific org", tags=["org-service"])
+@router.delete("/org/{ura}", summary="Delete specific org", tags=["Organizational Services"])
 def delete_org(
     ura: str,
     org_service: OrgService = Depends(container.get_org_service),