This article is for:
- Org Security Admins
Overview of Bring Your Own Key (BYOK)
Note: To use key management, it needs to be enabled for your organization. For more information, see the BYOK Overview page.
What is key management?
With Key Management, you can bring your own key (BYOK) to encrypt files and data. This allows you to retain control and management of your data by using your own encryption keys or the Wdesk key generator. By default, all files and data are encrypted, but some organizations prefer to manage and retain control of data encryption.
Who can use key management?
Only Org Security Admins are able to add or modify key settings. As a best practice, ensure only those you want to have access to keys are designated with this role.
To learn how to assign a role, see Update an Organization Role.
Does key management impact any other features?
The security requirements of key management and BYOK impact a few features in Workiva. The following features are impacted when you upload a key:
- Search Comments in Home - you can no longer search the contents of comments, so the option is disabled.
Which data is covered by BYOK?
Certain data in the Workiva platform is covered by BYOK, while some is excluded.
Workiva platform data covered by BYOK:
Workiva Documents, Spreadsheets, and Presentations:
- Table data
- Table cells (values and some metadata)
- Formulas
- Formatting
- Conditionals
- Filters
- Rich text in cells
- Wdata table data
- Linking data
- Linked values
- Structure of links
- Smart link names and descriptions
- Range-based linking structure
- Document data
- Bookmarks
- Document variables
- Outlines
- Content placeholders
- Table of contents
GRC:
- Graph database data
Sustainability:
- Metric details
- Metric values
Filing:
- Generated XBRL
- Section 16
- FERC
Platform productivity:
- Comments
- Comment content
- Comment original selection
- Attachments
- Uploaded attachment file
- Files uploaded from Home
Workiva platform data excluded from BYOK:
General:
- Metadata: Data that describes the content
- Any temporary or cached data stored at rest for less than 12 hours
- Identifiers or data relationships
- Search data
Workiva Documents, Spreadsheets, and Presentations:
- Document names
- Spreadsheets names
- Presentation names
Attachments:
- Attachment name
- Attachment usage name
Labels:
- Label names
Sustainability:
- Program name
- Metric name
- Topic name
Binders:
- Binder names
- Binder node labels
History:
- Milestone titles
- Remarks
Tasks:
- Task titles
- Task instructions
- Approver notes
Administration:
- Organization and workspace names
- Usernames
- Group names
- User profile fields
Reviews:
- Review names
Best practices
As you prepare to get started with key management, here are a few best practices:
- Start with your security requirements
Your company’s security requirements and processes determine how and when you interact with Bring Your Own Key. When uploading your own key encryption, plan on how you will store your key based on your security guidelines. Then, create a plan for how you will manage uploading, rotating, or removing your encryption key to ensure that you follow your organization's security requirements. -
Try out key management first
If you are interested in trying out Bring Your Own Key, contact your Customer Success Manager (CSM) before you add or generate a key for your organization. We can create a place for you to test generating and adding a key so you can gain confidence in the process before you add an encryption key for your organization. -
Perform key management after hours
We recommend that you do any key management actions, such as generating, adding, or rotating a key, outside of your normal business hours. Typically there aren't any issues, but it's a best practice to not create or update new data as you add or change an encryption key. -
Select two people to manage your key
We recommend that you assign at least two users with the Org Security Admin role to manage your encryption key. This allows you to have a backup in case one is not available. Also, it's common for the primary Org Admins to have the Org Security Admin role, so they can see if BYOK is active, but they would be unable to manage the key without access to the key material.
Key guidelines
When you create an encryption key, make sure you have a plan in place for the management and retention of it. Workiva does not keep a copy of your key and you need to make sure you keep it. As a general guideline, work with your company’s information security team for the proper way to generate and store encryption keys. You can upload any file type, as long as it contains binary key content.
Key requirements (Only applies to uploading your own key):
- 256-bit symmetric encryption key
- Exactly 32 bytes
- Meets cryptographic randomness
When you upload a key, it is checked to make sure it meets the requirements listed above. This ensures you can generate and test that you have a valid key before you confirm and make it active for your organization.
Monitor key activity
All of your key management actions are logged as organization activities, so you can track any time a key is added or modified. Key management activities show as the type of Control and you can click details to see the specific action.
Here are the activities related to key management:
Upload a key - Key activity
| Action | Summary |
| Bring-Your-Own-Key Setting | [Org Name] Bring-Your-Own-Key setting updated by [name]. |
| BYOK status accessed | [name] performed the read action on the byok key status associated with the organization. |
| BYOK key material imported | [name] performed the import action on the newly created byok key associated with the organization. |
| BYOK key material rotated | [name] performed the update action on the generated byok key associated with the organization (rotation started) |
| BYOK key material rotated | [name] performed the update action on the generated byok key associated with the organization (rotation finished) |
| BYOK key material revoked | [name] performed the read action on the byok key status associated with the organization. |
| BYOK key material restored | [name] performed the revoke action on the byok key material associated with the organization. |
Generate a key - Key activity
| Action | Summary |
| Bring-Your-Own-Key Setting | [Org Name] Bring-Your-Own-Key setting updated by [name]. |
| BYOK key generated | [name] performed the create action on the newly generated byok key associated with the organization. |
| BYOK status accessed | [name] performed the read action on the byok key status associated with the organization. |
| BYOK key material rotated | [name] performed the update action on the generated byok key associated with the organization (rotation started) |
| BYOK key material rotated | [name] performed the update action on the generated byok key associated with the organization (rotation finished) |
Wrap a key - Key activity
| Action | Summary |
| Bring-Your-Own-Key Setting | [Org Name] Bring-Your-Own-Key setting updated by [name]. |
| BYOK status accessed | [name] performed the read action on the byok key status associated with the organization. |
| BYOK wrapped key material | [name] performed the create action on the newly created wrapped byok key associated with the organization. |
| BYOK key material rotated | [name] performed the update action on the generated byok key associated with the organization (rotation started) |
| BYOK key material rotated | [name] performed the update action on the generated byok key associated with the organization (rotation finished) |
|
BYOK key material revoked |
[name] performed the read action on the byok key status associated with the organization. |
| BYOK key material restored | [name] performed the revoke action on the byok key material associated with the organization. |