Hoe gebruiken we de JWE-indeling

Dit gedeelte beschrijft hoe we verwachten dat het JWE zal worden gemaakt als invoer voor de apparaten, zodat u uw eigen tool kunt maken om de certificaten en sleutels te maken.

Raadpleeg JSON-webcodering (JWE) https://datatracker.ietf.org/doc/html/rfc7516 en JSON-webhandtekening (JWS) https://datatracker.ietf.org/doc/html/rfc7515.

We gebruiken de Compact Serialization van een JSON-document om JWE-blobs te creëren. De parameters die u moet opnemen bij het maken van de JWE-blobs zijn:

• JOSE-koptekst (beschermd). In de koptekst JSON-objectondertekening en -codering moet u de volgende sleutelwaardeparen opnemen:

  • "alg":"dir"

    Het directe algoritme is het enige dat we ondersteunen voor de versleuteling van de payload. U moet het initiale client geheim van het apparaat gebruiken.

  • "ENC":"A128GCM" of "enc":"A650 GCM"

    We ondersteunen deze twee coderingsalgoritmen.

  • "cisco-actie": "toevoegen" of "cisco-actie": "vullen" of "cisco-actie": "activeren" of "cisco-actie": "deactiveren"

    Dit is een eigen sleutel en deze kan vier waarden bevatten. We hebben deze sleutel geïntroduceerd om het doel van de gecodeerde gegevens aan te geven op het doelapparaat. De waarden worden genoemd naar de xAPI-opdrachten op het apparaat waar u de gecodeerde gegevens gebruikt.

    We noemden het cisco-actie om potentiële botsingen met toekomstige JWE-extensies te beperken.

  • "cisco kdf": { "version": "1", "salt": "base64URLEncodedRandom4+Bytes" }

    Een andere eigen sleutel. We gebruiken de waarden die u opgeef als invoer voor sleutelcodes op het apparaat. De versie moet 1 zijn (de versie van onze sleutelafleidingsfunctie). De waarde van salt moet een basis64 URL-gecodeerde reeks van minstens 4 bytes zijn, die u willekeurig moet kiezen.

• JWE-gecodeerde sleutel. Dit veld is leeg. Het apparaat is afgeleid van de eerste ClientSecret.

• JWE-initialisatievector. U moet een in base64url gecodeerde initialisatie vector invoeren voor het decoderen van de payload. De IV MOET een willekeurige waarde van 12 byte zijn (we gebruiken de AES-GCM-versleutelingsketen, waarvoor de IV 12 bytes lang moet zijn).

• JWE AAD (aanvullende geverifieerde gegevens). U moet dit veld weglaten omdat dit niet wordt ondersteund in de compacte serialisatie.

• JWE Ciphertext: Dit is de gecodeerde payload die u geheim wilt houden.

  De payload KAN leeg zijn. Als u bijvoorbeeld het clientgeheim wilt resetten, moet u het overschrijven met een lege waarde.

  Er zijn verschillende soorten payloads, afhankelijk van wat u probeert te doen op het apparaat. Verschillende xAPI-opdrachten verwachten verschillende payloads en u moet het doel van de payload als volgt opgeven met de cisco-action -sleutel:

  • Met "cisco-action":"populate" is de ciphertext de nieuwe ClientSecret.

  • Met ""cisco-action":"add" is de ciphertext een PEM blob met het certificaat en de eigen sleutel (concatenated).

  • Met ""cisco-action":"activate" is de ciphertext de vingerafdruk (hexadecimale weergave van sha-1) van het certificaat dat we activeren voor apparaatidentificatie verificatie.

  • Met ""cisco-actie":"deactiveren" is de ciphertext de vingerafdruk (hexadecimale weergave van sha-1) van het certificaat dat we deactiveren om te worden gebruikt voor apparaatidentiteitsverificatie.

• JWE-verificatie tag: Dit veld bevat de verificatietag om de integriteit van het gehele JWE-compact seriële codeer te bepalen

Hoe we de coderingssleutel uit het ClientSecret afleiden

Na de eerste inwoners van het geheim accepteren of output we deze geheim niet als platte tekst. Dit is om mogelijke woordenboekaanvallen te voorkomen door iemand die toegang heeft tot het apparaat.

De apparaatsoftware gebruikt het client geheim als invoer voor een sleutelversleutelingsfunctie (kdf) en gebruikt vervolgens de afgeleide sleutel voor inhoudsdecodering/-codering op het apparaat.

Wat dit voor u betekent, is dat uw tool voor het produceren van JWE-gegevens dezelfde procedure moet volgen om dezelfde codering/decoderingssleutel te afgeleid van het client geheim.

De apparaten gebruiken scrypten voor sleutelcodering (zie https://en.wikipedia.org/wiki/Scrypt), met de volgende parameters:

• CostFactor (N) is 32768

• BlockSizeFactor (r) is 8

• Parallelisatiefactor (p) is 1

• Zout is een willekeurige volgorde van ten minste 4 bytes; u moet hetzelfde zout leveren wanneer u de cisco-kdf -parameter specificeert.

• De sleutellengtes zijn 16 bytes (als u het AES-GCM 128-algoritme selecteert) of 32 bytes (als u het AES-GCM 256-algoritme selecteert)

• Max. geheugen cap is 64 MB

Deze set parameters is de enige configuratie van scrypt die compatibel is met de sleutelcodefunctie op de apparaten. Deze kdf op de apparaten heet "version":"1", wat de enige versie is die momenteel wordt gebruikt door de cisco-kdf parameter.

Voorbeeld gewerkt

Hier volgt u een voorbeeld om te controleren of uw JWE-coderingsproces hetzelfde werkt als het proces dat we op de apparaten hebben aangemaakt.

In het voorbeeldscenario wordt een PEM-certificaat aan het apparaat toegevoegd (nabootsen bij het toevoegen van een certificaat, met een zeer korte tekenreeks in plaats van een volledig cert + key). Het clientgeheim in het voorbeeld is ossifrage.

1. Kies een coderingscode. Dit voorbeeld maakt gebruik van A128GCM (AES met 128-bits toetsen in de Galois Counter Mode). Als u dat wenst, kan uw tool A31GCM gebruiken.

2. Kies eenje (moet een willekeurige volgorde zijn van ten minste 4 bytes). Dit voorbeeld gebruikt (hexadecimale bytes)E5 E6 53 08 03 F8 33 F6. Base64url codeert de reeks om 5eZTCAP4M_Y te krijgen (verwijder de base64-padding).

3. Hier volgt een voorbeeld van een scrypt -gesprek om de coderingssleutel voor inhoud (cek) te maken:

   cek=scrypt(password="ossifrage", salt=4-byte-sequentie, N=32768, r=8, p=1, keylength=16)

   De afgeleide sleutel moet als volgt 16 bytes (hex) zijn:95 9e ba 6d d1 22 01 05 78 fe 6a 9d 22 78 ff ac die basis64url codeert naar lZ66bdEiAQV4_mqdInj_rA.

4. Kies een willekeurige volgorde van 12 bytes om te gebruiken als initialisatie vector. Dit voorbeeld gebruikt (hex) 34 b3 5d dd 5f 53 7b af 2d 92 95 83 die basis64url codeert naar NLNd3V9Te68tkpWD.

5. Maak de JOSE-header met compacte serialisatie (volg de volgorde van de parameters die we hier gebruiken) en codeer deze vervolgens in basis64url:

   {"alg":"dir","cisco-actie":"add","cisco-kdf":{"salt":"5eZTCAP4M_Y","version":"1"},"enc":"A128GCM"}

   De basis64url gecodeerde JOSE-header is eyJhbGciOiJkaXIiLCJjaXNjby1hY3Rpb24iOiJhZGQiLCJjaXNjby1rZGYiOnsic2FsdCI6IjVlWlRDQVA0TV9ZIiwidmVyc2lvbiI6IjEifSwiZW5jIjoiQTEyOEdDTSJ9

   Dit is het eerste element van het JWE-bestand.

6. Het tweede element van het JWE-bestand is leeg, omdat we geen JWE-ruimte coderingssleutel.

7. Het derde element van de JWE-blob is de initialisatievector NLNd3V9Te68tkpWD.

8. Gebruik uw JWE-coderingstool om een gecodeerde payload en tag te produceren. In dit voorbeeld wordt de niet-versleutelde payload de valse PEM-blob dit is een PEM-bestand

   De coderingsparameters die u moet gebruiken zijn:

   • Payload is dit is een PEM-bestand

   • Coderingscode is AES 128 GCM

   • De base64url-koptekst van JOSE gecodeerd als Additional Authenticated Data (AAD)

   Base64url codeert de gecodeerde payload, wat moet resulteren in f5lLVuWNfKfmzYCo1YJfODhQ

   Dit is het vierde element (JWE Ciphertext) in het JWE-bestand.

9. Base64url codeert de tag die u hebt gemaakt in stap 8, wat moet resulteren in PE-wDFWGXFFBeo928cfZ1Q

   Dit is het vijfde element in het JWE-bestand.

10. De vijf elementen van het JWE- of het JWE- of de stippen samenvoegen met dots (OOK WELDE-header). IV.Ciphertext.Tag) voor het volgende:

    eyJhbGciOiJkaXIiLCJjaXNjby1hY3Rpb24iOiJhZGQiLCJjaXNjby1rZGYiOnsic2FsdCI6IjVlWlRDQVA0TV9ZIiwidmVyc2lvbiI6IjEifSwiZW5jIjoiQTEyOEdDTSJ..9NLNd3V9Te68tkpWD.f5lLVuWNfKfmzYCo1YJfODhQ.PE-wDFWGXFFBeo928cfZ1Q

11. Als u dezelfde base64url-gecodeerde waarden hebt afgeleid als wij hier met behulp van uw eigen tools, bent u klaar om deze te gebruiken om de E2E-codering en de geverifieerde identiteit van uw apparaten te beveiligen.

12. Dit voorbeeld werkt niet echt, maar binnen de volgende stap zou u het JWE-bericht moeten gebruiken dat u hierboven hebt gemaakt als invoer voor de xcommand op het apparaat waarin het certificaat is toegevoegd:

    xCommand Security Certificates Add eyJhbGciOiJkaXIiLCJjaXNjby1hY3Rpb24iOiJhZGQiLCJjaXNjby1rZGYiOnsic2FsdCI6IjVlWlRDQVA0TV9ZIiwidmVyc2lvbiI6IjEifSwiZW5jIjoiQTEyOEdDTSJ..9NLNd3V9Te68tkpWD.f5lLVuWNfKfmzYCo1YJfODhQ.PE-wDFWGXFFBeo928cfZ1Q