If your organization has messages in another service or in another encryption format, then as an administrator, you can migrate those messages to Gmail as client-side encrypted messages in the S/MIME format.
Migrated messages that include a digital signature and encryption will render safely in Gmail with inline images, hyperlinks, and attachments visible.
Some services may allow users to create S/MIME messages without a digital signature and have publicly-known vulnerabilities. When those “encrypt-only” messages are imported into Gmail, the messages are displayed in a safe format that suppresses possible exploits. This means that Gmail client-side encryption (CSE) will not display inline images, hyperlinks, or attachments in the user interface, although the underlying message continues to retain all of its content.
Migrating S/MIME-encrypted messages
Gmail CSE natively supports the standard S/MIME message encryption format that is also used by Microsoft and other email services. If you are migrating encrypted S/MIME messages from a Microsoft service into Gmail, then you can migrate encrypted messages unchanged.
For Gmail CSE to decrypt and display S/MIME messages that were previously in a Microsoft service, the user accounts with Gmail must be configured with the same S/MIME user certificates that were used in the Microsoft environment. You must also set up the Gmail API and Gmail CSE for your users using the same certificates present in the Microsoft service. For details, see Gmail only: Upload encryption keys for client-side encryption.
After the Gmail accounts are configured with the S/MIME certificates, you can migrate messages from the Microsoft service into Gmail. For details, see Migrate your data to Google Workspace.
Migrating non-S/MIME formats and plain text archives
If your organization has messages that are encrypted in a non-S/MIME format, or has plain text archives that you'd like to encrypt before migrating, use the Gmail CSE Migration Utility to convert messages into the S/MIME format used by Gmail CSE.
To use the migration utility to transfer your messages:
- Export the encrypted messages from your service provider.
- If the messages are encrypted, decrypt the mail messages to plaintext using the tooling provided by your non-S/MIME encryption vendor.
- After the messages are decrypted into plaintext, use the Gmail CSE Migration Utility to encrypt your messages locally and migrate them to Gmail CSE.
If you’re using Gmail
To use the migration utility to transfer your messages, export your encrypted messages from Gmail using Google Takeout or Google Workspace Vault. Use the tooling provided by your non-S/MIME encryption vendor to decrypt the mail messages to plaintext.
The Gmail CSE Migration Utility operates over the plaintext messages. When exporting the messages via Google Vault, make sure that your export uses the mbox file format. The PST files generated by Vault contain insufficient information to allow message reinsertion back into Gmail.
For each imported message, the Gmail CSE Migration Utility will add an S/MIME-encrypted copy of the message in addition to the original message. Each user account with Gmail must have sufficient free space to allow for message copies to be inserted.
System requirements
- Windows 10/11 x86_64
- Linux x86_64
- macOS 12+ x86_64 or M
Supported file formats
The Gmail CSE Migration Utility operates over the plaintext messages. Make sure your messages are in one of the following file formats:
- PST
- Mbox
The Gmail CSE Migration Utility does not currently support the MSG file format. For details on the supported formats, refer to the file format documentation.
Before you begin
Before you can use the migration utility to migrate your messages, set up the Gmail API and Gmail CSE for your users. For details, see Gmail only: Upload encryption keys for client-side encryption.
Migration will re-use the Google service account API credential that you used during Gmail CSE setup.
Download the Gmail CSE Migration Utility
- Download the Gmail CSE migrator utility to your device.
Run the Gmail CSE Migration Utility
To use the migration utility, enter the following command in a terminal or command prompt. Replace the placeholders with your flags and filenames.
Windows
> gmail-cse-migrate.exe [Optional flags] -api-credential=<filename> -input=<filename>
For example, to migrate email messages from a file named input.pst into Gmail CSE, enter the following command:
> gmail-cse-migrate.exe -api-credential=my-api-credential.json -input=input.pst
Linux, macOS
$ ./gmail-cse-migrate [Optional flags] -api-credential=<filename> -input=<filename>
For example, to migrate email messages from a file named input.pst into Gmail CSE, enter the following command:
$ ./gmail-cse-migrate -api-credential=my-api-credential.json -input=input.pst
Notes:
- Provide following required flags when you run the command:
-api-credential=<filename> and -input=<filename> - For detailed information about the functions of the required flags, enter gmail-migrate.exe -help.
- The migration utility can operate on both single input files and directories.
- For an input directory, the migration utility recursively traverses the directory to search for files with the extensions .pst and .mbox.
- You can specify multiple input files and directories in a single execution.
Test the migration
We strongly recommend performing a dry run of the migration process before adding messages to the Gmail storage. This helps you identify and correct any potential issues that could cause the migration to fail. For example, if you do not have any configured CSE keypairs, some messages may fail to encrypt during the migration. A dry run will help you identify this issue before it causes the migration to fail.
To perform a dry run, use the -dryrun flag. For example, if your Google service account private key is located at c:\my_svc_acct.json2, enter the following command:
gmail-migrate.exe -input user1.pst -input user2.pst -api-credential c:\my_svc_acct.json -dryrun
This example performs a dry run of the migration process on the two input files user1.pst and user2.pst. The dry run verifies the following:
- The messages from the files can be parsed.
- The messages can be encrypted in preparation for migration.
Complete the migration
After the dry run, enter the following command to complete the migration.
gmail-migrate.exe -input user1.pst -input user2.pst -api-credential c:\my_svc_acct.json
Verify the migration
When a message migration is successful, an S/MIME-encrypted copy of the message is inserted into the message owner’s Gmail account alongside the original message encrypted in the non-S/MIME format. The migration utility does not delete the original message.
When inspection of the user account shows that the S/MIME copies are usable by Gmail CSE, then the account owner or the enterprise admin can delete the original messages that were encrypted in the non-S/MIME format. To help you find these messages, the Gmail CSE migration utility will add a custom user label named “Gmail CSE Migration Source Messages” to each original message.
Be careful when deleting messages using the Gmail UI. The default interface aggregates messages into threads or conversations, and deletion of a single message will delete the entire conversation, including unencrypted messages and the inserted CSE message copies. Users should first disable conversation view via the Gmail settings pane so that deletion applies to individual messages rather than threads.
If the migration is unsuccessful…
- To identify the cause of the failure, do the following:
- Review the log file for error messages.
- Ensure that the migrator has the necessary permissions to access the PST files and the Gmail account.
- Verify that the API credentials are valid.
- Confirm that the PST files are not corrupt or damaged.
- Make the necessary changes to address the cause of the unsuccessful migration.
- Re-run the migration command.
Note: The migration utility skips messages that were successfully migrated in the previous attempt.
Migrator flags
Migrator flags can be specified using one or two leading hyphens, not slashes. For example, on Windows, you can specify the flag for displaying help information with either of the following:
-help
--help
For flags that accept a string argument, you can specify them with either an equals sign or a space to define the argument. For example, the following flags are equivalent:
-input=filename.pst
-input filename.pst
Help flags
| Flag | Description |
|---|---|
| -version |
Prints the version string. If you contact support, provide the version you’re having issues with. |
| -help | Prints a usage screen of all flags. |
| -logfile |
Specifies the output file where execution logs will be written. If the special text TIMESTAMP is present in the filename, |
Migration flags
| Flag | Description |
|---|---|
| input <directory_or_file> | Required. Specifies the input directory or mail file. |
| -api-credential <file> | Required. Specifies a JSON file containing the private key to a Google service account delegated domain-wide access. |
| -dryrun | Optional. Specified to verify that the migrator can process the mail message files and prepare the messages for migration. |
