Table of Contents

Restrict editing

Word's Restrict Editing marks a document read-only, comments-only, tracked-changes-only or forms-only, optionally behind a password. DocWright starts and stops that protection as one undoable edit, writes what Word writes, and checks the password a document records.

The code

using DocWright;
using DocWright.Cryptography;
using DocWright.Dom;
using DocWright.Dom.Editing;

using var document = new WordDocument();
Paragraph first = document.AppendParagraph("Minutes of the meeting, as agreed.");
DocumentPosition at = DocumentPosition.StartOf(first);

// Start enforcing protection: no changes (read only), stopped by a password. One undoable edit.
DocumentEdit started = document.SetDocumentProtection(at, protection =>
    DocumentProtectionHash.StartEnforcing(protection, DocumentEditRestriction.ReadOnly, "open sesame"));

var converter = new DocWrightConverter();
using (FileStream output = File.Create("restricted.docx"))
{
    converter.Save(document, output);
}

Console.WriteLine("Saved: " + Element("restricted.docx"));

// Someone asks to stop it: check the password the document records, then stop.
using FileStream input = File.OpenRead("restricted.docx");
using WordDocument reopened = converter.Load(input);
DocumentProtection recorded = reopened.Settings.Protection;
Console.WriteLine($"Restriction: {recorded.Edit}, enforced: {recorded.Enforcement}");
Console.WriteLine($"\"guess\" stops it: {DocumentProtectionHash.VerifyDocumentProtection(recorded, "guess")}");
Console.WriteLine($"\"open sesame\" stops it: {DocumentProtectionHash.VerifyDocumentProtection(recorded, "open sesame")}");

Paragraph paragraph = reopened.Sections[0].Blocks.OfType<Paragraph>().First();
reopened.SetDocumentProtection(DocumentPosition.StartOf(paragraph), DocumentProtectionHash.StopEnforcing);
using (FileStream output = File.Create("open.docx"))
{
    converter.Save(reopened, output);
}

Console.WriteLine("Stopped: " + Element("open.docx"));

// Undo takes the protection off the first document again, password and all.
started.Undo();
Console.WriteLine($"Undone: protected = {document.Settings.Protection.HasDocumentProtection}");

Output

Saved: <w:documentProtection w:edit="readOnly" w:enforcement="1" w:cryptProviderType="rsaAES" w:cryptAlgorithmClass="hash" w:cryptAlgorithmType="typeAny" w:cryptAlgorithmSid="14" w:cryptSpinCount="100000" w:hash="…" w:salt="…" />
Restriction: ReadOnly, enforced: True
"guess" stops it: False
"open sesame" stops it: True
Stopped: (none)
Undone: protected = False

Start and stop

SetDocumentProtection(at, change) hands your code a copy of the document's protection settings, and puts the changed copy in their place as a DocumentEdit. Undo restores the settings there were, password included.

Inside it, DocumentProtectionHash.StartEnforcing(protection, restriction, password) makes the settings what Word's "Yes, Start Enforcing Protection" makes them, and StopEnforcing(protection) what "Stop Protection" leaves: nothing. The restrictions are ReadOnly, Comments, TrackedChanges and Forms. Leave the password out for protection anyone can stop.

The password

A protection password is recorded as a salted, iterated hash. Word does not hash the password itself: it hashes a 32-bit key it derives from the password's first fifteen characters, a leftover of its binary formats. StartEnforcing records that hash, so Word accepts the password you set, and VerifyDocumentProtection checks it, so the password someone set in Word is the one that verifies. A hash of the password itself, which some programs write and Word also accepts, verifies too.

Because only fifteen characters count, a longer password is no stronger, and two passwords that share their first fifteen characters are the same password.

What it is not

  • It is not enforced. DocWright models protection and never refuses an edit because of it. If your application should honour a restriction, check document.Settings.Protection (Edit, Enforcement) and decide yourself, and ask for the password with VerifyDocumentProtection before you stop it.
  • It is not encryption. The text is readable by anything that opens the file. To keep a document secret, encrypt it.
  • There is no password recovery in DocWright, and none will be added.

What to know

  • A document states its own iteration count, so a hostile file can ask for a great many. Verification runs under ResourceLimits.MaxKeyDerivationSpinCount; pass your own limits as the third argument.
  • StartEnforcing replaces any password the document had and keeps a formatting restriction and the "open read-only" recommendation as they are.
  • The edit changes no paragraph: a layout session has nothing to lay out again.