Protect-RMSFile

Syntax

Protect-RMSFile
       [-File <String>]
       [-Folder <String>]
       [-InPlace]
       [-Recurse]
       [-TemplateID <String>]
       [-License <SafeInformationProtectionLicenseHandle>]
       [-DoNotPersistEncryptionKey <String>]
       [-OutputFolder <String>]
       [-OwnerEmail <String>]
       [<CommonParameters>]

Description

The Protect-RMSFile cmdlet protects a file or all files in a specified folder by using Azure RMS or AD RMS. If the file was previously protected, it will be protected again, to apply any changes such as those that might be made to the template that is being used to protect the file.

Multiple file types can be protected in the same way that the Azure Information Protection client can protect files when you use the "Classify and protect" right-click option from File Explorer.

Different levels of protection are automatically applied (native or generic), depending on the file type. You can change the level of protection by editing the registry. In addition, some files change their file name extension after they are protected by Rights Management. For more information, see the File types supported for protection section from the Azure Information Protection client admin guide.

Before you run this cmdlet, you must run Get-RMSTemplate to download the templates onto your computer. If the template that you want to use has been modified since you ran this cmdlet, run it again with the -force parameter to download the revised template.

When you run this cmdlet, you have the following options:

• The file is protected in the current location, replacing the original file that was unprotected.

• The original file remains unprotected and a protected version of the file is created in another location.

• All files in the specified folder are protected in the current location, replacing the original files that were unprotected.

• All files in the specified folder remains unprotected and a protected version of each file is created in another location.

You cannot run this command concurrently but must wait for the original command to complete before running it again. If you try to run it again before the previous command has finished, the new command will fail.

This cmdlet writes to the following log files: Success.log, Failure.log, and Debug.log in %localappdata%\Microsoft\MSIPC\pscmdlet\Logs\\<GUID>.

Examples

Example 1: Protect and replace a single file by using a template

PS C:\>Protect-RMSFile -File "C:\Test.docx" -InPlace -TemplateID 82bf3474-6efe-4fa1-8827-d1bd93339119
InputFile             EncryptedFile
---------             -------------
C:\Test.docx          C:\Test.docx

This command protects a single file named Test.docx by using a template, and replaces the original unprotected file. The Rights Management owner of the file, and the email address that might be displayed to users when they access the protected file, is automatically set as the email address for the account running the command.

Example 2: Create a protected copy of a single file by using a template

PS C:\>Protect-RMSFile -File "Test.docx" -TemplateID 82bf3474-6efe-4fa1-8827-d1bd93339119
InputFile             EncryptedFile
---------             -------------
C:\Test.docx          C:\Test-Copy.docx

This command is the same as the previous example, except that it doesn't use the InPlace parameter. Because it also doesn't use the OutputFolder parameter, the protected file is created in the current folder with "-Copy" appended to the file name. The original, unprotected file remains in the current folder.

Example 3: Create a protected version of a file by using a template

PS C:\>Protect-RMSFile -File "C:\Test.docx" -OutputFolder "C:\Temp" -TemplateID e6ee2481-26b9-45e5-b34a-f744eacd53b0 -OwnerEmail "[email protected]"

InputFile             EncryptedFile
---------             -------------
C:\Test.txt           C:\Temp\Test.ptxt

This command protects a single file named Test.docx by using a template and places this protected version of the file in C:\Temp, leaving the original file unprotected in the root of the C: drive. The Rights Management owner of the file, and the email address that might be displayed to users when they access the protected file, is for the administrator.

Example 4: Protected all files in a folder by using a template

PS C:\>Protect-RMSFile -Folder "\\server1\Docs" -InPlace -DoNotPersistEncryptionKey All -TemplateID e6ee2481-26b9-45e5-b34a-f744eacd53b0 -OwnerEmail "[email protected]"

InputFile                        EncryptedFile

----------                       -------------
\\server1\Docs\Feb2015.docx      \\server1\Docs\Feb2015.docx

\\server1\Docs\Feb2015.txt       \\server1\Docs\Feb2015.ptxt

\\server1\Docs\Jan2015.docx      \\server1\Docs\Jan2015.docx

\\server1\Docs\Jan2015.txt       \\server1\Docs\Jan2015.ptxt

This command protects all files in a server share (single folder only, not subfolders), replacing the unprotected files. The email address that is displayed to users when they do not have access, is for the IT department group and this group is granted Full Control usage rights in the template so that they can change the usage rights for the protected files.

Because this scenario is protecting files on behalf of others, the DoNotPersistEncryptionKey parameter is used for maximum performance and to prevent unused files from being saved to disk.

Example 5: Protected files with a specific file name extension in a folder by using a template

PS C:\>foreach ($file in (Get-ChildItem -Path \\server1\Docs -Recurse -Force | where {!$_.PSIsContainer} | Where-Object {$_.Extension -eq ".docx"})) {Protect-RMSFile -File $file.PSPath -InPlace -DoNotPersistEncryptionKey All -TemplateID "e6ee2481-26b9-45e5-b34a-f744eacd53b0" -OwnerEmail "[email protected]"}


InputFile                                   EncryptedFile

---------                                   -------------
\\server1\Docs\Feb2015.docx                 \\server1\Docs\Feb2015.docx

\\server1\Docs\Jan2015.docx                 \\server1\Docs\Jan2015.docx

\\server1\Docs\Reports\Feb2015.docx         \\server1\Docs\Reports\Feb2015.docx

\\server1\Docs\Reports\Jan2015.docx         \\server1\Docs\Reports\Jan2015.docx

This command protects only files that have a .docx file name extension in a folder (and all subfolders) on a server share, replacing the unprotected files. As in the previous example, the email address that is displayed to users when they do not have access, is for the IT department.

Although the Protect-RMSFile command does not natively support wildcards, you can use Windows PowerShell to achieve this, and change the file name extension in the example, as required.

Example 6: Protect a single file by using an ad-hoc rights policy

PS C:\>$License = New-RMSProtectionLicense -UserEmail '[email protected]' -Permission EDIT
PS C:\> Protect-RMSFile -License $License -File "C:\Test.txt" -InPlace
InputFile             EncryptedFile
---------             -------------
C:\Test.txt           C:\Test.ptxt

The first command creates an ad-hoc rights policy that grants Edit rights to [email protected].

The second command protects a single file named Test.txt by using this ad-hoc rights policy just created, and replaces the original unprotected file.

Note that unless your email address is [email protected], you will not be able to unprotect this file after the command completes because you do not have any rights to it and you are not the Rights Management owner.

If you need to be able to unprotect this file later, you can add your name and grant the user and yourself either the EXTRACT or OWNER right in the ad-hoc rights policy in the first command. Or if you do not want the user to be able to unprotect the file, add -OwnerEmail <your email address> to the end of the second command.

Parameters

-DoNotPersistEncryptionKey

-File

-Folder

-InPlace

-License

-OutputFolder

-OwnerEmail

-Recurse

-TemplateID

Related Links

• Get-RMSTemplate
• Get-RMSFileStatus
• New-RMSProtectionLicense
• Unprotect-RMSFile