Technisch artikel

Agile-gecodeerde Excel-bestanden lezen in Delphi met HotXLS

Een klant uploadt een werkmap die op zijn bureau gewoon opent, en de importservice wijst hem af met een ZIP-fout. Een hexdump van de eerste acht bytes laat D0 CF 11 E0 A1 B1 1A E1 zien, de OLE Compound File-handtekening die een .xls uit 1997 meedraagt. Het bestand heeft de extensie .xlsx, komt uit een actuele Excel en is helemaal geen ZIP-pakket. Iemand heeft in het Save As-dialoogvenster een wachtwoord gezet

Daarmee is het hele raadsel opgelost. Als Excel een werkmap met een wachtwoord opslaat, versleutelt hij de echte .xlsx-ZIP en wikkelt het resultaat in een Compound File Binary (CFB)-container, met het Agile-schema uit [MS-OFFCRYPTO] §2.3.4.10 tot §2.3.4.15. Elke lader die bestanden op extensie classificeert, of die elke .xlsx rechtstreeks aan een ZIP-lezer doorgeeft, stuitert de upload terug naar een gebruiker die zich vanaf zijn kant van het scherm niets verkeerds heeft veroorloofd

Wat zit er in een Agile-versleutelde werkmap?

Een Agile-versleutelde werkmap is een CFB-container met twee streams die ertoe doen: EncryptionInfo, die beschrijft hoe de versleuteling is uitgevoerd, en EncryptedPackage, dat de oorspronkelijke ZIP als één ondoorzichtige, versleutelde blob bevat. HotXLS leest beide streams rechtstreeks uit de container, zonder Excel, COM of een externe crypto-DLL op de machine

Anatomie van het Agile-versleutelde werkboek dat HotXLS opent in Delphi: een CFB-container met een EncryptionInfo-descriptorstream en een EncryptedPackage-stream van AES-CBC-segmenten
HotXLS leest een Agile-versleutelde werkmap als een CFB-container met een zelfbeschrijvende EncryptionInfo-stream en de .xlsx-ZIP versleuteld als een ondoorzichtige EncryptedPackage-stream

Wat Agile onderscheidt van de oudere Standard Encryption is dat EncryptionInfo zichzelf beschrijft. Na een prefix van 8 bytes waarvan hoofd- en subversie allebei 4 zijn, is de stream een UTF-8 XML-descriptor. Een keyData-element benoemt de cipher (AES), de chaining-modus (ChainingModeCBC), het hash-algoritme, de sleutellengte in bits, de blokgrootte en een Base64-salt. De wachtwoord-keyEncryptor draagt zijn eigen salt, een spinCount en drie Base64-payloads: encryptedVerifierHashInput, encryptedVerifierHashValue en encryptedKeyValue. Een dataIntegrity-element voegt een versleutelde HMAC-key en HMAC-waarde toe voor manipulatiedetectie

Excel zelf schrijft AES-256, SHA-512 en een spin count van 100.000. De descriptor mag echter iets anders zeggen, en schrijvers van derden doen dat ook. HotXLS neemt keyBits uit de descriptor in plaats van 256 aan te nemen, dus bestanden met AES-128 en AES-192 decoderen op dezelfde manier, en hij accepteert hashAlgorithm="SHA256" naast SHA-512. Het eigen hash-attribuut van elk element bestuurt de stappen die bij hem horen: de keyEncryptor-hash stuurt de wachtwoordafleiding en -verificatie, terwijl de keyData-hash de segment-IVs en de integrity-HMAC stuurt. Een bestand dat de twee door elkaar gebruikt, gaat gewoon open

Het bestand openen: OpenEncrypted of Open met een wachtwoord

TXLSXWorkbook.OpenEncrypted neemt een bestandsnaam en een wachtwoord aan en geeft 1 terug bij succes, hetzelfde contract als Open. Hij snuffelt met CanReadEncrypted aan de eerste acht bytes. Een bestand zonder de CFB-handtekening gaat door het gewone Open-pad en het wachtwoord wordt genegeerd, dus een importeur die altijd OpenEncrypted aanroept heeft geen vertakking op de aanroepplek nodig. Een CFB-bestand wordt eerst als Standard Encryption geprobeerd, en wanneer het EncryptionInfo-prefix de Agile-versie 4.4 draagt, neemt de Agile-lezer het over. De gedecodeerde ZIP-bytes gaan daarna in het geheugen naar de gewone XLSX-lader

Beide toegangspunten nemen een bestandsnaam aan. Open(Stream) weigert een stream die met de CFB-handtekening begint en geeft een exception waarvan de melding naar OpenEncrypted wijst, dus een upload die in een TMemoryStream staat moet eerst naar een tijdelijk bestand

uses
  System.SysUtils, System.Classes, System.IOUtils, System.Variants, lxHandleX;

function ReadFirstCell(Upload: TMemoryStream;
  const Password: WideString): WideString;
var
  TempName: string;
  Wb: TXLSXWorkbook;
begin
  Result := '';
  // versleutelde pakketten worden vanuit een bestand geopend, dus schrijf de upload naar schijf
  TempName := TPath.GetTempFileName;
  Wb := TXLSXWorkbook.Create;
  try
    Upload.SaveToFile(TempName);
    // kale .xlsx, Standard-versleutelde en Agile-versleutelde bestanden werken hier allemaal
    if Wb.OpenEncrypted(TempName, Password) = 1 then
      Result := VarToWideStr(Wb.Sheets[1].Cells[1, 1].Value);
  finally
    Wb.Free;
    TFile.Delete(TempName);
  end;
end;

De overload met twee argumenten, Open(FileName, Password), bereikt dezelfde decryptiecode maar voegt één ding toe dat OpenEncrypted niet heeft: het event OnPassword. Als het opgegeven wachtwoord faalt, vuurt Open OnPassword, laat de handler een nieuw wachtwoord toekennen en Retry op True zetten, en vraagt opnieuw, tot drie keer toe. Een desktopapplicatie kan in die handler een wachtwoordprompt zetten. Een server kan hem voor iets anders gebruiken — daar komt de laatste sectie op terug

Hoe wordt een wachtwoord een AES-sleutel?

Het wachtwoord ontsleutelt nooit iets rechtstreeks. De eerste digest is SHA-512 over de keyEncryptor-salt gevolgd door de UTF-16LE-bytes van het wachtwoord; die digest wordt daarna spinCount keer opnieuw gehasht, waarbij elke ronde de 32-bits little-endian rondeteller vóór de vorige digest zet. Met de 100.000 ronden van Excel kost elke wachtwoordpoging honderdduizend seriële SHA-512-aanroepen. Dat is precies de bedoeling van de spin count. Een legitieme open betaalt hem één keer, en een dictionary-aanval betaalt hem voor elke gok

Hoe HotXLS Agile-versleutelingssleutels afleidt in Delphi: het wachtwoord wordt door 100.000 SHA-512-ronden gedraaid, daarna leveren drie vaste 8-byte bloksleutels de verifier- en pakketsleutels op
Het wachtwoord ontsleutelt nooit iets rechtstreeks: een SHA-512 spin-count-keten voedt drie bloksleutel-hashes die de verifier-sleutels opleveren en de willekeurige package key uitpakken

De keten is kort genoeg om na te bouwen, en dat is de snelste manier om op je eigen hardware te zien wat één gok kost. De schets hieronder volgt §2.3.4.11 voor een SHA-512-descriptor en gebruikt de publieke functie XlsSHA512 uit de unit lxXlsxAgileDecrypt

uses
  System.SysUtils, lxXlsxAgileDecrypt;

// H0 = SHA-512(salt + UTF-16LE(password))
// Hn = SHA-512(LE32(n - 1) + H(n-1)), repeated SpinCount times
function SpinHash(const Password: WideString; const Salt: TBytes;
  SpinCount: Integer): TBytes;
var
  Buf: TBytes;
  PwdLen, I: Integer;
begin
  PwdLen := Length(Password) * SizeOf(WideChar);
  SetLength(Buf, Length(Salt) + PwdLen);
  if Length(Salt) > 0 then
    Move(Salt[0], Buf[0], Length(Salt));
  if PwdLen > 0 then
    Move(Password[1], Buf[Length(Salt)], PwdLen);
  Result := XlsSHA512(Buf);
  SetLength(Buf, 4 + 64);
  for I := 0 to SpinCount - 1 do
  begin
    Buf[0] := Byte(I and $FF);           // rondeteller, little-endian
    Buf[1] := Byte((I shr 8) and $FF);
    Buf[2] := Byte((I shr 16) and $FF);
    Buf[3] := Byte((I shr 24) and $FF);
    Move(Result[0], Buf[4], 64);         // vorige digest
    Result := XlsSHA512(Buf);
  end;
end;

De gespinde hash is nog steeds geen sleutel. Drie sleutels komen eruit, elk door de gespinde waarde nog eens te hashen met een vaste bloksleutel van 8 bytes erachter geplakt: FE A7 D2 76 3B 4B 9E 79 voor de verifier-invoer, D7 AA 0F 6D 30 61 34 4E voor de verifier-hash, en 14 6E 0B E7 AB AC D0 D6 voor het uitpakken van de pakketsleutel. Elk resultaat wordt afgekapt tot de gedeclareerde sleutellengte, 32 bytes bij AES-256. De specificatie definieert ook wat er gebeurt wanneer een hash korter uitkomt dan de sleutel: opvullen met 0x36-bytes. Geen enkele AES-sleutelgrootte triggert dat daadwerkelijk bij SHA-256 of SHA-512, maar dezelfde 0x36-regel geldt wél wanneer de wachtwoordsalt tot de blokgrootte wordt uitgerekt om als CBC-IV te dienen

De spin count wordt uit het bestand gelezen, dus hij is ook een aanvalsoppervlak: een upload die een miljard ronden claimt, zou een CPU-kern vastpinnen voordat hij faalt. §2.3.4.11 kapt spinCount af op 10.000.000, en HotXLS meldt een grotere waarde als niet-ondersteunde descriptor voordat er iets wordt gehasht. Voor een publiek uploadendpoint is dat plafon de juiste default. De 100.000 van Excel zit ver daaronder

Wachtwoordverificatie en de saltSize-afkapvalkuil

HotXLS controleert het wachtwoord voordat hij het pakket aanraakt. Hij decodeert encryptedVerifierHashInput met de eerste afgeleide sleutel, hasht het resultaat, decodeert encryptedVerifierHashValue met de tweede sleutel en vergelijkt de twee digests over de volledige hashlengte zonder te stoppen bij de eerste afwijkende byte. Een mismatch beëindigt de open met een fout-wachtwoord-resultaat, en de pakketbody wordt nooit onder een slechte sleutel gedecodeerd. Een verkeerd wachtwoord kan dus geen werkmap vol aannemelijk afval opleveren

Eén zin in de specificatie wordt hier makkelijk verkeerd gelezen. §2.3.4.13 definieert de verifier als saltSize bytes aan willekeurige gegevens, waarbij saltSize de lengte is van de salt van de key encryptor. De gedecodeerde verifier komt terug opgevuld tot een veelvoud van het 16-byte AES-blok, dus hij moet vóór het hashen worden teruggekapt tot saltSize. Excel schrijft saltSize en blockSize altijd als 16, waardoor code die op de blokgrootte afkapt elke test tegen Excel-uitvoer haalt. En vervolgens keurt hij het juiste wachtwoord af op het eerste bestand van een producent die voor een salt van 32 bytes koos. HotXLS kapt af op de saltlengte, want dat is wat de tekst zegt, en dat de twee getallen in Excel-bestanden overeenkomen is toeval

Hoe wordt het EncryptedPackage gedecodeerd?

De pakketsleutel is willekeurig, niet van het wachtwoord afgeleid. De schrijver genereerde hem, versleutelde hem in encryptedKeyValue, en HotXLS pakt hem uit met de derde afgeleide sleutel, met evenveel bytes als keyData in keyBits declareert. Voordat hij één segment decodeert, controleert HotXLS dataIntegrity wanneer het bestand die draagt: de HMAC-key en -waarde worden met de pakketsleutel gedecodeerd, en een HMAC over de complete EncryptedPackage-stream, het grootteprefix inbegrepen, moet matchen met de opgeslagen waarde. Bestanden die zonder bruikbaar dataIntegrity-element zijn geschreven, slaan deze stap over en gaan toch open

HotXLS ontcijfert de EncryptedPackage-stream in Delphi segment voor segment, waarbij elke 4096-byte AES-CBC-segment-IV wordt afgeleid uit de keyData-salt en de segmentindex
Elk AES-CBC-segment van 4096 bytes ontsleutelt onafhankelijk onder zijn eigen salt-en-index-IV, en het resultaat wordt afgekapt op de gedeclareerde plaintext-grootte

De stream zelf begint met een little-endian plaintext-grootte van 8 bytes, gevolgd door cijfertekst in segmenten van 4096 bytes. Elk segment krijgt zijn eigen IV: de hash van de keyData-salt gevolgd door de 32-bits little-endian segmentindex, afgekapt tot de blokgrootte. Elk segment kan daardoor op zichzelf worden gedecodeerd, wat in principe random access zou toelaten; HotXLS decodeert het hele pakket naar het geheugen omdat de ZIP-lader toch het complete archief wil. De gedeclareerde grootte wordt gecontroleerd tegen de werkelijke streamlengte voordat de decryptie begint, dus een afgekapte upload of een opgeblazen grootteveld faalt netjes. Na het laatste segment wordt de buffer afgekapt tot de gedeclareerde grootte, waarmee de tot 15 bytes AES-opvulling verdwijnen, en wat overblijft is byte voor byte de ZIP die Excel heeft versleuteld

Een fout wachtwoord onderscheiden van een niet-ondersteund bestand

Elke versleutelingsfout in OpenEncrypted en Open geeft EXlsxEncryptionNotImplemented, en de melding zegt welk geval het is: het opgegeven wachtwoord is onjuist, of het bestand gebruikt een schema dat HotXLS niet leest. HotXLS leest de wachtwoord-key-encryptor met AES in CBC-modus en SHA-512- of SHA-256-hashing, wat dekt wat actuele Excel-versies schrijven; een container die alleen door een certificaat-key-encryptor is beveiligd, een descriptor die een andere cipher benoemt, of een CFB die noch Standard noch Agile is, zoals een hernoemde BIFF .xls, krijgt de niet-ondersteund-melding

Matchen op meldingstekst is broos, vooral als de resourcestrings ooit worden gelokaliseerd. Het event OnPassword geeft een schoner signaal: Open vuurt het alleen wanneer de verifier of de integriteitscontrole het wachtwoord afkeurt, nooit voor een niet-ondersteund schema. Voor een importservice: roep Open(FileName, Password) aan met een handler die de afkeuring registreert, in plaats van OpenEncrypted, dat zonder naar een event te kijken een exception geeft

type
  TUploadOutcome = (uoLoaded, uoPasswordRejected, uoUnreadable);

  TUploadLoader = class
  private
    FPasswordRejected: Boolean;
    procedure HandlePassword(Sender: TObject; var PassWord: WideString;
      var Retry: Boolean);
  public
    function Load(Wb: TXLSXWorkbook;
      const FileName, Password: WideString): TUploadOutcome;
  end;

procedure TUploadLoader.HandlePassword(Sender: TObject;
  var PassWord: WideString; var Retry: Boolean);
begin
  // wordt alleen gevuurd wanneer het wachtwoord (of de integrity-HMAC) werd afgekeurd
  FPasswordRejected := True;
  Retry := False;   // op een server is er niemand om te vragen; Open geeft daarna een exception
end;

function TUploadLoader.Load(Wb: TXLSXWorkbook;
  const FileName, Password: WideString): TUploadOutcome;
begin
  FPasswordRejected := False;
  Wb.OnPassword := HandlePassword;
  try
    if Wb.Open(FileName, Password) = 1 then
      Result := uoLoaded
    else
      Result := uoUnreadable;
  except
    on E: EXlsxEncryptionNotImplemented do
      if FPasswordRejected then
        Result := uoPasswordRejected   // veilig om de gebruiker opnieuw te vragen
      else
        Result := uoUnreadable;        // opnieuw proberen helpt niet; log E.Message
  end;
end;

Eén valkuil blijft bestaan, ook met deze scheiding. Een integriteitsmismatch wordt op dezelfde manier gemeld als een fout wachtwoord, dus een werkmap waarvan de cijfertekst onderweg werd beschadigd — door een proxy die de body herschreef of een upload die halverwege een segment werd afgebroken — komt terug als uoPasswordRejected, ook als de gebruiker het juiste wachtwoord intypte. Faalt dezelfde gebruiker twee keer met een wachtwoord waar hij van overtuigd is dat het klopt, vraag dan eerst opnieuw om het bestand voordat je opnieuw om het wachtwoord vraagt

De schrijfzijde gebruikt dezelfde machinerie in omgekeerde richting. SaveAsEncryptedAgile produceert een Agile-container met SHA-512-sleutelafleiding, 100.000 spinronden en AES-256-pakketversleuteling, SaveAsEncrypted produceert Standard Encryption, en VerifyEncryptedSave op True zetten laat beide aanroepen het bestand dat ze net schreven via het decryptiepad opnieuw openen en -1 teruggeven als dat faalt. Het Standard-pad wordt doorlopen in het artikel over het schrijven van AES-beveiligde XLSX-uitvoer, en de RC4- en XOR-schema's in legacy BIFF-bestanden worden behandeld in het ECB- en RC4-interopartikel

Voor een pijplijn die nooit vooraf weet of de volgende upload een wachtwoord meebrengt, is de hierboven beschreven lezer, samen met native XLS- en XLSX-lezing en -schrijving voor Delphi en C++Builder, onderdeel van de HotXLS Delphi Excel Component