Cmdlet

Protect-OfficeDocument

Module: PSWriteOffice
Inputs: System.IDisposable System.String[]
Outputs: System.IO.FileInfo OfficeIMO.Word.WordDocument OfficeIMO.Excel.ExcelDocument OfficeIMO.PowerPoint.PowerPointDocument OfficeIMO.Pdf.PdfDocument
Source: ProtectOfficeDocumentCommand.cs:42 Edit on GitHub

Adds native password encryption or editing restrictions to a document.

Syntax

Protect-OfficeDocument
[-Encrypt]
[-Options <Object[]>]
[-OutputPath <String>]
[-PassThru]
[-Password <SecureString>]
[-Path] <String[]>
[-Restriction <OfficeProtectionRestriction[]>]
[-RestrictionPassword <SecureString>]
[<CommonParameters>]

Parameter set: Path

Protect-OfficeDocument
[-Encrypt]
-LiteralPath <String[]>
[-Options <Object[]>]
[-OutputPath <String>]
[-PassThru]
[-Password <SecureString>]
[-Restriction <OfficeProtectionRestriction[]>]
[-RestrictionPassword <SecureString>]
[<CommonParameters>]

Parameter set: LiteralPath

Protect-OfficeDocument
[-Document] <IDisposable>
[-Encrypt]
[-Options <Object[]>]
[-OutputPath <String>]
[-PassThru]
[-Password <SecureString>]
[-Restriction <OfficeProtectionRestriction[]>]
[-RestrictionPassword <SecureString>]
[<CommonParameters>]

Parameter set: Document

Description

Supports PDF and Open XML Word, Excel and PowerPoint packages. Path input is saved in place unless OutputPath names a protected copy. File inputs must be unencrypted: this command has no CurrentPassword parameter. Live Word/Excel restrictions may remain in memory; encryption requires OutputPath or a native associated file path. Encryption is a one-time export, not a stored password setting on the live input. PDF protection returns a new native document with preservation proof, leaving the original live PDF intact. Without Encrypt, PDF restrictions use Password or RestrictionPassword as the owner password and allow opening without a password. With Encrypt, a separate owner password keeps the open password from authorizing permission changes. Unsupported restrictions produce warnings; an entirely unsupported request writes nothing. Safe native signature and preservation policies remain in force.

Examples

Encrypt a workbook using a secure password.

Get-ChildItem ./Payroll -Filter *.xlsx | Protect-OfficeDocument -Encrypt -Password (Read-Host -AsSecureString) -PassThru

Restrict Word editing without encrypting the file.

Protect-OfficeDocument -Path ./policy.docx -Restriction ReadOnly -Password (Read-Host -AsSecureString)

Withhold PDF copying with separate open and owner passwords.

Protect-OfficeDocument -Path ./board.pdf -Encrypt -Password $openPassword -Restriction Copy -RestrictionPassword $ownerPassword -OutputPath ./protected.pdf

Withhold PDF copying while allowing readers to open without a password.

Protect-OfficeDocument -Path ./board.pdf -Restriction Copy -Password $ownerPassword -OutputPath ./restricted.pdf

Parameters

-Encrypt SwitchParameter optional: Encrypt the saved artifact using its native engine.
-Options Object[] optional: Excel tables accept LegacyPasswordHash, ModifyPasswordHash and ReservedBy; native workbook and reservation property tables are also accepted. PDF tables accept Algorithm, EncryptMetadata, Permissions or AllowedPermissions, and AesCryptographyProvider. Supply PDF passwords through Password and RestrictionPassword. Typed native PDF options retain their owner password, permission mask, algorithm, metadata setting and AES provider.
-OutputPath String optional: Protected file destination; accepts exactly one input when supplied.
-PassThru SwitchParameter optional: Emit FileInfo for file input, or the protected native document for Document input.
-Password SecureString optional: Open password with Encrypt; otherwise the restriction password. Accepts a credential or warned plain text.
-Path String[] requiredposition: 0pipeline: True (ByValue)sets: Path: Files to protect, in pipeline and provider match order.
-Restriction OfficeProtectionRestriction[] optional: Word editing mode, Excel protection/reservation, or PDF permissions to withhold.; Possible values: ReadOnly, Comments, TrackedChanges, Forms, Structure, Windows, ReadOnlyRecommended, Print, Copy, Modify, Annotate, FillForms, Assemble
-RestrictionPassword SecureString optional: Restriction password, separate from the open password when Encrypt is used; PDF owner password.
-LiteralPath String[] requiredpipeline: True (ByPropertyName)aliases: FullName, PSPathsets: LiteralPath: Literal files, including FileInfo.FullName and provider PSPath properties.
-Document IDisposable requiredposition: 0pipeline: True (ByValue)sets: Document: Caller-owned native Word, Excel, PowerPoint or PDF document.

Common Parameters

This command supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable.

For more information, see about_CommonParameters.