Skip Navigation

Bring Your Own Key (BYOK)

This feature is available only for hosted cloud environments.
A cryptographic key is used to encrypt and decrypt a BlackBerry Workspaces organization's files. As of version 7.0, the Bring Your Own Key (BYOK) security policy for public cloud instances of BlackBerry Workspaces allows third party key management solutions to be used instead of BlackBerry provided keys. This allows organizations to:
  • Encrypt and decrypt documents from storage using their own key
  • Revoke the key if needed 
A cloud organization who wishes to use this feature provides its own Amazon Web Services (AWS) Key Management Service (KMS) Key to encrypt organizational files. Decryption requires Workspaces to be integrated as an External Account with access to the AWS KMS Key.  Access to both the AWS KMS interface and the Workspaces Admin Console is necessary.
BYOK requires an additional license to be purchased; contact your account manager for more details.  
BYOK requires the BYOK tier in the Workspaces configuration. Contact your account manager for more information.
Take the following steps to Bring-Your-Own-Key (BYOK) in a BlackBerry Workspaces cloud environment:
  1. Create or retrieve the Master Key from Amazon Web Services (AWS):
    1. Sign into your AWS IAM Account with your Account ID.
    2. At the IAM Home Screen, select the appropriate Region.
    3. Select the 
      Encryption Keys 
      link from the left-hand sidebar. 
    4. Click the 
      Create Keys
    5. Type the 
       of the Key and click the 
    6. If desired, add a 
       for the Key and click the 
    7. Define a 
      Key Administrator
  2. Confirm the Key Administrator has the ability to Generate Data Keys:
    1. Sign into the AWS IAM Account and access the 
      section from the left-hand sidebar. 
    2. Review the JSON of the Policy you intend to use with the Key Administrator. 
    3. Confirm that the Policy's JSON includes the line 
    4. Access the 
      section from the left-hand sidebar. 
    5. Select the relevant Key Administrator. 
    6. Add the relevant Policy that includes the ability to 
  3. Grant access to the Master Key for the Workspaces organization:
    1. Sign into the AWS IAM Account and access the 
      Encryption Keys
       section from the left-hand sidebar.
    2. Find the 
      External Accounts
    3. Click the 
      Add External Account
    4. Add the Workspaces Amazon Account ID as an External Account. 
  4. Create an AWS KMS Encryption Key to be used for encrypting and decrypting Workspaces organizational files:
    1. Add the AWS EXE to your Operating System's PATH environmental variables. For example, add 
      C:\Program Files\Amazon\AWSCLI 
      to the PATH variable. 
    2. Run the EXE. 
    3. Input 
      aws configure
      1. When prompted, input the AWS Access Key ID.  This should be the Master Key Administrator's User Access Key.
      2. When prompted, input the AWS Secret Access Key. 
      3. When prompted, input the default region name.  For example, us-east-1. 
      4. When prompted, input the default output format.  For example, json. 
    4. Input 
      aws kms generate-data-key --key-id <key-ARN> --key-spec AES_256
      . For example, 
      aws kms generate-data-key --key-id arn:aws:kms:us-east-1:############:key/########-####-####-####-############ --key-spec AES_256
      : This value can be located within the 
      Policy JSON 
      listed in Step #2 above as the contents of the 
    5. The Response JSON will include the following information:
      { "Plaintext" : "aStringOfCharactersWillBeReturned" "KeyId": "TheSameKeyIdWilBeReturnedThatWasInput" "CiphertextBlob" : "aStringOfCharactersToBeEnteredInTheBlackBerryWorkspacesAdminConsoleWithoutTheQuotesAtTheBeginningAndEnd" }
    6. Save these encrypted values as they will be used in the BlackBerry Workspaces Admin Console. 
  5. Add the AWS KMS Encryption Key to the BlackBerry Workspaces Admin Console:
    1. In the BlackBerry Workspaces admin console, click 
      Security Policies
      Bring Your Own Key
    2. Select an appropriate Amazon Web Services (AWS) region from the dropdown.
    3. In the 
      Customer Master Encryption Key
       field, input the 
       that was returned in the 
      generate-data-key Response JSON
    4. Click 
      Activate Key
To revoke the key, click 
Revoke Key
. Access to all documents uploaded before and after the key was generated will be revoked.
Additional considerations include:
  • Files which has been synced with full access permissions will still be available after the revoke
  • DocuSign integration fails for files which were uploaded before revoking the BYOK
  • Annotation symbols still appear after revoking access for a document with annotations
  • Revoking a key in organizations which were created before BlackBerry Workspaces version 5.3 will still allow access to documents uploaded before BYOK configuration 
  • Text and office 97-2003 and non converted documents will show non-readable characters when opened after revoking the key. PDF documents will not open. 
Revoking a key is a destructive action that you must consider carefully before performing.