{"id":485,"date":"2026-07-10T23:23:02","date_gmt":"2026-07-10T23:23:02","guid":{"rendered":"https:\/\/www.tb-software.ch\/ai\/systemlocker\/restapi\/"},"modified":"2026-07-10T23:23:02","modified_gmt":"2026-07-10T23:23:02","slug":"restapi","status":"publish","type":"page","link":"https:\/\/www.tb-software.ch\/ai\/en\/systemlocker\/restapi\/","title":{"rendered":"SystemLocker, REST-API"},"content":{"rendered":"
\n\n \n
\n
\n

The key to your PC.<\/p>\n

SystemLocker<\/h2>\n

Passwordless Windows login and data protection via a physical USB dongle. When the dongle is plugged in, the PC automatically logs in to the correct user account, without entering a password. If the dongle is missing, the account and work data remain encrypted and inaccessible.<\/p>\n <\/div>\n

\n \"SystemLocker\n <\/div>\n <\/section>\n\n
\n
\n \"\"\n
Passwordless & convenient<\/strong>
The dongle replaces password entry and selects the correct profile.<\/div>\n <\/div>\n
\n \"\"\n
Fully encrypted<\/strong>
System and work data protected with BitLocker, no boot password required.<\/div>\n <\/div>\n
\n \"\"\n
Role-based<\/strong>
Different dongles open different accounts and data areas, cryptographically separated.<\/div>\n <\/div>\n
\n \"\"\n
Securely secured<\/strong>
Central recovery of the dongles via this REST API. Copies for emergencies.<\/div>\n <\/div>\n <\/section>\n\n
\n

This is how it works in 3 steps<\/h3>\n \"Workflow:\n <\/section>\n\n
\n

Screenshots from the running application<\/h3>\n
\n
\n \"Assistent:\n
Assistant: Welcome<\/figcaption>\n <\/figure>\n
\n \"Assistent:\n
Assistant: Dongle management with Finance role, provisioned<\/figcaption>\n <\/figure>\n
\n \"Simulierter\n
Simulated start with dongle, login successful<\/figcaption>\n <\/figure>\n
\n \"Simulierter\n
Simulated start without dongle, disguised error message<\/figcaption>\n <\/figure>\n
\n \"Assistent:\n
Assistant: Summary<\/figcaption>\n <\/figure>\n <\/div>\n

All visible values (role, account TB\\tboehme<\/code>, serial) are demo data, not real secrets.<\/p>\n <\/section>\n\n

\n\n

REST API for the wizard<\/h2>\n

\n Central REST API for the SystemLocker WPF wizard<\/strong>. Stores dongle material\n (client-side AES-256-GCM encrypted), PCs, metrics, audit log in the Linkwerk database.\n Namespace: systemlocker\/v1<\/code>. Base URL:\n https:\/\/www.tb-software.ch\/ai\/wp-json\/systemlocker\/v1\/<\/code>.\n <\/p>\n\n

\n JSON UTF-8<\/span>\n HTTPS only<\/span>\n HMAC signature per request<\/span>\n Master key server-side, encrypted escrow<\/span>\n <\/div>\n\n

. Auth model<\/h2>\n

Two auth classes:<\/p>\n

    \n
  1. Wizard (HMAC)<\/strong>: each request is signed with the installation's own\n apiKey<\/code> . No token, no session. Header:\n X-SL-Installation<\/code>, X-SL-Timestamp<\/code>, X-SL-Nonce<\/code>,\n X-SL-Signature<\/code>.<\/li>\n
  2. Admin<\/strong>: either WP-Admin-Login<\/em> with manage_options<\/code>-right (Cookies) or header X-SL-Admin-Secret<\/code> with the value from\n SL_ADMIN_SECRET<\/code> in wp-config.php<\/code>.<\/li>\n <\/ol>\n\n

    .1 calculate HMAC signature (two formats supported in parallel)<\/h3>\n

    The server accepts both formats. New wizards use v2<\/strong>, older v1<\/strong>.<\/p>\n\n

    v2 \u2014 Spec 2.0 (recommended, corresponds to HmacRequestSigner.cs<\/code>)<\/h4>\n
    timestamp = ISO-8601 UTC (\"2026-07-11T00:00:00Z\")\nnonce     = zufaellig, mind. 16 Byte\npath      = \"\/dongles\"                             # ab Namespace\nbody_hex  = hex(SHA256(body))                      # leerer Body: SHA256(\"\")\ncanonical = f\"{METHOD}\\n{path}\\n{timestamp}\\n{nonce}\\n{body_hex}\"\nsignature = base64(HMAC-SHA256(key=apiKey, msg=canonical))\n\nHeaders:\n  X-SL-Installation : <installationId>\n  X-SL-Timestamp    : <timestamp ISO-8601>\n  X-SL-Nonce        : <nonce>\n  X-SL-Signature    : <signature base64>\n<\/code><\/pre>\n\n  
    v1 \u2014 Legacy (dot-format)<\/h4>\n
    timestamp = int(Unix-Sekunden UTC)\nnonce     = hex(random_bytes(16))\ncanonical = f\"{timestamp}.{nonce}.{METHOD}.{fullpath}.{body}\"\n# fullpath = \"\/systemlocker\/v1\/dongles\"  (mit Namespace-Prefix)\n# body     = raw request body (leerer String bei GET)\nsignature = HMAC-SHA256(key=apiKey, msg=canonical).hex()\n<\/code><\/pre>\n\n  
    Server verification:<\/p>\n  
      \n    
    • |now - timestamp| \u2264 300s<\/code> (Clock drift tolerance)<\/li>\n    
    • Nonce not in replay cache (transient, 5-6 min)<\/li>\n    
    • hash_equals(expected, signature)<\/code><\/li>\n  <\/ul>\n\n  
      . Endpoint overview<\/h2>\n  \n    \n      
      Method<\/th>Path<\/th>Auth<\/th>Purpose<\/th><\/tr><\/thead>\n    
      GET   <\/td>\/version<\/code>                                              <\/td>\u2014     <\/td>Server version, HMAC formats, feature flags, known metric types<\/td><\/tr>\n      
      POST  <\/td>\/installations<\/code>                                        <\/td>Admin <\/td>Create new installation (gives apiKey<\/em> + restorePassword<\/em> ONCE back)<\/td><\/tr>\n      
      GET   <\/td>\/installations<\/code>                                        <\/td>Admin <\/td>List all installations (without secrets)<\/td><\/tr>\n      
      DELETE<\/td>\/installations\/{id}<\/code>                                   <\/td>Admin <\/td>Delete installation (Audit)<\/td><\/tr>\n      
      GET   <\/td>\/installations\/{id}\/restore-password<\/code>                  <\/td>Admin <\/td>Retrieve plaintext password (Audit + Reveal warning)<\/td><\/tr>\n      
      POST  <\/td>\/installations\/{id}\/restore-password\/verify<\/code>           <\/td>HMAC  <\/td>Verify restore password without revealing it<\/td><\/tr>\n      
      POST  <\/td>\/installations\/{id}\/rotate-api-key<\/code>                    <\/td>Admin <\/td>Generate new apiKey, invalidate old one<\/td><\/tr>\n      
      POST  <\/td>\/pcs<\/code>                                                  <\/td>HMAC  <\/td>Register\/update PC (pcId = SHA-256 of hardwareId)<\/td><\/tr>\n      
      POST  <\/td>\/dongles<\/code>                                              <\/td>HMAC  <\/td>Save dongle record (material already encrypted)<\/td><\/tr>\n      
      GET   <\/td>\/dongles<\/code>                                              <\/td>HMAC  <\/td>Dongles of own installation (Query: pcId, role, withMaterial)<\/td><\/tr>\n      
      GET   <\/td>\/dongles\/{dongleId}<\/code>                                   <\/td>HMAC  <\/td>Load single dongle including material ciphertext<\/td><\/tr>\n      
      DELETE<\/td>\/dongles\/{dongleId}<\/code>                                   <\/td>Admin <\/td>Delete dongle record (audit)<\/td><\/tr>\n      
      POST  <\/td>\/metrics<\/code>                                              <\/td>HMAC  <\/td>Ingest metric or batch<\/td><\/tr>\n      
      GET   <\/td>\/metrics<\/code>                                              <\/td>HMAC\/Admin<\/td>Query metrics (pcId, type, fromUtc, toUtc)<\/td><\/tr>\n      
      GET   <\/td>\/audit<\/code>                                                <\/td>Admin <\/td>Read audit log (filter: installationId)<\/td><\/tr>\n    <\/tbody>\n  <\/table>\n\n  
      . Data models<\/h2>\n\n  
      3.1 Installation<\/h3>\n
      {\n  \"installationId\": \"b3f1a2c4-...\",\n  \"customerName\":   \"Muster AG\",\n  \"createdUtc\":     \"2026-07-09T10:00:00Z\"\n}<\/code><\/pre>\n  
      Additionally in the response when creating (ONCE, never retrievable in plain text):<\/p>\n
      {\n  \"apiKey\":          \"sl_...\",     \/\/ Wizard-Secret fuer HMAC\n  \"restorePassword\": \"A7fH3...\",   \/\/ 32 Zeichen, wird gebraucht wenn kein DPAPI-Cache\n}<\/code><\/pre>\n\n  
      3.2 PC<\/h3>\n
      Request POST \/pcs:\n{ \"hostname\": \"TBS-PC01\", \"os\": \"Windows 10 19045\",\n  \"machineGuid\": \"...\", \"hardwareId\": \"...\" }\n\nResponse:\n{ \"pcId\": \"sha256-...\" }<\/code><\/pre>\n\n  
      3.3 DongleRecord<\/h3>\n
      {\n  \"dongleId\":     \"d1a2...\",           \/\/ Server-vergeben\n  \"installationId\":\"b3f1...\",\n  \"role\":         \"Main | Backup1 | ...\",\n  \"serialNumber\": 1364915896,\n  \"account\":      { \"userName\": \"timo\", \"domain\": \".\", \"profileId\": \"S-1-5-21-...\" },\n  \"pcId\":         \"sha256-...\",\n  \"sessionId\":    \"...\",\n  \"material\": {\n    \"algo\":       \"AES-256-GCM\",\n    \"kdf\":        \"Argon2id\",\n    \"salt\":       \"base64\",\n    \"nonce\":      \"base64\",\n    \"tag\":        \"base64\",\n    \"ciphertext\": \"base64\"\n  },\n  \"createdUtc\":   \"2026-07-09T10:06:00Z\",\n  \"version\":      1\n}<\/code><\/pre>\n  
      Important:<\/strong> K_d<\/code>, S<\/code> and the Windows password is ONLY stored in the material.ciphertext<\/code>, encrypted with the restore key from\n    Argon2id(restorePassword, salt)<\/code>. The server never sees them in plain text.<\/p>\n\n  
      3.4 Metric<\/h3>\n
      {\n  \"type\":         \"login_success | login_denied | dongle_removed | heartbeat | custom\",\n  \"value\":        1,\n  \"pcId\":         \"sha256-...\",\n  \"dongleId\":     \"d1a2-... | null\",\n  \"data\":         { \"beliebig\": \"json\" },\n  \"timestampUtc\": \"2026-07-09T10:07:00Z\"\n}<\/code><\/pre>\n\n  
      . Examples<\/h2>\n\n  
      .1 Create installation (Admin, curl)<\/h3>\n
      curl -X POST \"https:\/\/www.tb-software.ch\/ai\/wp-json\/systemlocker\/v1\/installations\" \\\n     -H \"X-SL-Admin-Secret: $SL_ADMIN_SECRET\" \\\n     -H \"Content-Type: application\/json\" \\\n     -d '{\"customerName\":\"Muster AG\"}'\n\n{\n  \"installationId\": \"b3f1a2c4-...\",\n  \"customerName\":   \"Muster AG\",\n  \"apiKey\":         \"sl_a1b2c3...\",     <- unbedingt sichern\n  \"restorePassword\":\"A7fHmKq2X8...\",    <- unbedingt sichern\n  \"createdUtc\":     \"2026-07-09T10:00:00Z\"\n}<\/code><\/pre>\n\n  
      .2 Wizard: Save dongle (HMAC)<\/h3>\n
      import time, secrets, hmac, hashlib, json, urllib.request\n\ninstallation = \"b3f1a2c4-...\"\napi_key      = \"sl_a1b2c3...\"\nbody_obj     = { \"role\":\"Main\", \"serialNumber\":1364915896, \"account\":{...},\n                 \"pcId\":\"sha256-...\", \"sessionId\":\"...\", \"material\":{...},\n                 \"version\":1 }\nbody = json.dumps(body_obj, separators=(\",\",\":\"))\nts   = str(int(time.time()))\nnonce= secrets.token_hex(16)\npath = \"\/systemlocker\/v1\/dongles\"\ncanonical = f\"{ts}.{nonce}.POST.{path}.{body}\"\nsig  = hmac.new(api_key.encode(), canonical.encode(), hashlib.sha256).hexdigest()\n\nreq = urllib.request.Request(\n    \"https:\/\/www.tb-software.ch\/ai\/wp-json\/systemlocker\/v1\/dongles\",\n    data=body.encode(),\n    headers={\n      \"X-SL-Installation\": installation,\n      \"X-SL-Timestamp\":    ts,\n      \"X-SL-Nonce\":        nonce,\n      \"X-SL-Signature\":    sig,\n      \"Content-Type\":      \"application\/json\",\n    },\n    method=\"POST\",\n)\nprint(urllib.request.urlopen(req).read())\n# -> 201 {\"dongleId\":\"d1a2...\"}<\/code><\/pre>\n\n  
      .3 Wizard: Verify restore password (no plain text reveal)<\/h3>\n
      POST https:\/\/www.tb-software.ch\/ai\/wp-json\/systemlocker\/v1\/installations\/{id}\/restore-password\/verify\nHeaders: X-SL-*\nBody:    { \"restorePassword\":\"A7fHmKq2X8...\" }\nResponse: 200 { \"valid\": true|false }<\/code><\/pre>\n\n  
      .4 Retrieve restore password (Admin, with audit)<\/h3>\n
      curl \"https:\/\/www.tb-software.ch\/ai\/wp-json\/systemlocker\/v1\/installations\/{id}\/restore-password\" \\\n     -H \"X-SL-Admin-Secret: $SL_ADMIN_SECRET\"\n\n{\n  \"installationId\":  \"b3f1...\",\n  \"restorePassword\": \"A7fHmKq2X8...\",\n  \"issuedUtc\":       \"2026-07-09T10:22:00Z\",\n  \"auditId\":         \"...\"\n}\n<\/code><\/pre>\n\n  
      . C# Client (WPF Wizard)<\/h2>\n  
      Copy-paste-ready reference implementation for .NET 6+\/WPF Wizard.\n     HMAC via System.Security.Cryptography.HMACSHA256<\/code>, JSON via\n     System.Text.Json<\/code>, no third-party Nugets required.<\/p>\n\n  
      .1 HMAC client class<\/h3>\n
      using System.Net.Http;\nusing System.Net.Http.Headers;\nusing System.Security.Cryptography;\nusing System.Text;\nusing System.Text.Json;\n\npublic sealed class SystemLockerClient\n{\n    private readonly HttpClient _http = new();\n    private readonly string _base;      \/\/ \"https:\/\/tb-software.ch\/ai\/wp-json\/systemlocker\/v1\"\n    private readonly string _installationId;\n    private readonly string _apiKey;\n\n    public SystemLockerClient(string baseUrl, string installationId, string apiKey)\n    {\n        _base = baseUrl.TrimEnd('\/');\n        _installationId = installationId;\n        _apiKey = apiKey;\n    }\n\n    private HttpRequestMessage Sign(HttpMethod method, string routePath, string body = \"\")\n    {\n        \/\/ routePath MUSS mit Namespace-Prefix beginnen: \"\/systemlocker\/v1\/dongles\"\n        var ts    = ((long)(DateTime.UtcNow - DateTime.UnixEpoch).TotalSeconds).ToString();\n        var nonce = Convert.ToHexString(RandomNumberGenerator.GetBytes(16)).ToLower();\n        var canonical = $\"{ts}.{nonce}.{method.Method}.{routePath}.{body}\";\n        using var h = new HMACSHA256(Encoding.UTF8.GetBytes(_apiKey));\n        var sig = Convert.ToHexString(h.ComputeHash(Encoding.UTF8.GetBytes(canonical))).ToLower();\n\n        var req = new HttpRequestMessage(method, _base + routePath.Substring(\"\/systemlocker\/v1\".Length));\n        req.Headers.Add(\"X-SL-Installation\", _installationId);\n        req.Headers.Add(\"X-SL-Timestamp\",    ts);\n        req.Headers.Add(\"X-SL-Nonce\",        nonce);\n        req.Headers.Add(\"X-SL-Signature\",    sig);\n        if (!string.IsNullOrEmpty(body))\n            req.Content = new StringContent(body, Encoding.UTF8, \"application\/json\");\n        return req;\n    }\n\n    public async Task<JsonElement> PostAsync(string route, object payload)\n    {\n        var body = JsonSerializer.Serialize(payload, new JsonSerializerOptions{ WriteIndented = false });\n        using var req = Sign(HttpMethod.Post, route, body);\n        using var r   = await _http.SendAsync(req);\n        var text = await r.Content.ReadAsStringAsync();\n        return JsonDocument.Parse(text).RootElement.Clone();\n    }\n\n    public async Task<JsonElement> GetAsync(string route)\n    {\n        using var req = Sign(HttpMethod.Get, route);\n        using var r   = await _http.SendAsync(req);\n        var text = await r.Content.ReadAsStringAsync();\n        return JsonDocument.Parse(text).RootElement.Clone();\n    }\n}<\/code><\/pre>\n\n  
      .2 Register PC + save dongle<\/h3>\n
      var sl = new SystemLockerClient(\n    \"https:\/\/www.tb-software.ch\/ai\/wp-json\/systemlocker\/v1\",\n    installationId: \"b3f1a2c4-...\",\n    apiKey:         \"sl_a1b2c3...\");\n\n\/\/ PC upsert\nvar pc = await sl.PostAsync(\"\/systemlocker\/v1\/pcs\", new {\n    hostname    = Environment.MachineName,\n    os          = Environment.OSVersion.VersionString,\n    machineGuid = ReadRegistryMachineGuid(),\n    hardwareId  = ComputeHardwareFingerprint(),\n});\nstring pcId = pc.GetProperty(\"pcId\").GetString();\n\n\/\/ Material clientseitig verschluesseln (Argon2id KDF, AES-256-GCM)\n\/\/ -> siehe SystemLocker.Crypto.PackDongleMaterial(...)\nvar material = SystemLocker.Crypto.PackDongleMaterial(\n    Kd, S, account, credentialBlob, restorePassword, installationId, dongleId);\n\n\/\/ Dongle speichern (Server sieht Chiffrat, NIE Klartext)\nvar d = await sl.PostAsync(\"\/systemlocker\/v1\/dongles\", new {\n    role         = \"Main\",\n    serialNumber = donglePcsc.Serial,\n    account      = new { userName = \"timo\", domain = \".\", profileId = \"S-1-5-...\" },\n    pcId         = pcId,\n    sessionId    = Guid.NewGuid().ToString(),\n    material     = material,   \/\/ { algo, kdf, salt, nonce, tag, ciphertext }\n    version      = 1,\n});\nstring dongleId = d.GetProperty(\"dongleId\").GetString();<\/code><\/pre>\n\n  
      .3 Verify restore password (no plaintext reveal)<\/h3>\n
      var v = await sl.PostAsync(\n    $\"\/systemlocker\/v1\/installations\/{installationId}\/restore-password\/verify\",\n    new { restorePassword = enteredPassword });\nbool valid = v.GetProperty(\"valid\").GetBoolean();<\/code><\/pre>\n\n  
      .4 Ingest metrics (batch)<\/h3>\n
      await sl.PostAsync(\"\/systemlocker\/v1\/metrics\", new [] {\n    new { type = \"login_success\", value = 1, pcId = pcId, timestampUtc = DateTime.UtcNow.ToString(\"O\") },\n    new { type = \"heartbeat\",     value = 1, pcId = pcId, timestampUtc = DateTime.UtcNow.ToString(\"O\") },\n});<\/code><\/pre>\n\n  
      .5 Error handling<\/h3>\n
      if (r.StatusCode == HttpStatusCode.Unauthorized) {\n    var err = json.GetProperty(\"error\").GetProperty(\"message\").GetString();\n    \/\/ Moegliche Werte: missing_hmac_headers, bad_timestamp, nonce_reused,\n    \/\/                  bad_signature, unknown_installation, api_key_decrypt_failed\n    throw new SystemLockerAuthException(err);\n}<\/code><\/pre>\n\n  
      . Security model (summary)<\/h2>\n  
        \n    
      • The server sees Metadata<\/strong> in plain text (customer, PC, role, timestamp).<\/li>\n    
      • The server sees Dongle material ONLY as ciphertext<\/strong> under the client-side restore key.<\/li>\n    
      • The server sees the restore password<\/strong> in plain text during creation (it generated it)  \n        and afterwards only encrypted with SL_MASTER_KEY<\/code>. The master key is located in\n        wp-config.php<\/code> outside the DB.<\/li>\n    
      • Vendor-Escrow (Variant A)<\/strong>Admin can restore restore passwords.\n        Each output is audited (tb_sl_audit<\/code>).<\/li>\n    
      • Sensitive actions run via X-SL-Admin-Secret<\/code> OR WP-Admin session.<\/li>\n    
      • All Wizard requests are HMAC-signed. Replay protection via Nonce transient + 5-min window.<\/li>\n  <\/ul>\n\n  
        . Error format<\/h2>\n
        { \"error\": { \"code\": \"unauthorized\", \"message\": \"bad_signature\" } }<\/code><\/pre>\n  
        HTTP codes: 200<\/code> OK \u00b7 201<\/code> Created \u00b7\n     202<\/code> Accepted \u00b7 204<\/code> No Content \u00b7\n     400<\/code> Bad Request \u00b7 401<\/code> Unauthorized \u00b7\n     403<\/code> Forbidden \u00b7 404<\/code> Not Found \u00b7\n     409<\/code> Conflict.<\/p>\n<\/article>\n    \n","protected":false},"excerpt":{"rendered":"","protected":false},"author":0,"featured_media":0,"parent":473,"menu_order":0,"comment_status":"closed","ping_status":"closed","template":"","meta":{"footnotes":""},"class_list":["post-485","page","type-page","status-publish","hentry"],"_links":{"self":[{"href":"https:\/\/www.tb-software.ch\/ai\/index.php?rest_route=\/wp\/v2\/pages\/485","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.tb-software.ch\/ai\/index.php?rest_route=\/wp\/v2\/pages"}],"about":[{"href":"https:\/\/www.tb-software.ch\/ai\/index.php?rest_route=\/wp\/v2\/types\/page"}],"replies":[{"embeddable":true,"href":"https:\/\/www.tb-software.ch\/ai\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=485"}],"version-history":[{"count":0,"href":"https:\/\/www.tb-software.ch\/ai\/index.php?rest_route=\/wp\/v2\/pages\/485\/revisions"}],"up":[{"embeddable":true,"href":"https:\/\/www.tb-software.ch\/ai\/index.php?rest_route=\/wp\/v2\/pages\/473"}],"wp:attachment":[{"href":"https:\/\/www.tb-software.ch\/ai\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=485"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}