Skip Navigation
  1. BlackBerry Docs
  2. BlackBerry Workspaces
  3. BlackBerry Workspaces Server 12
  4. BlackBerry Workspaces Server Administration Guide
  5. Setting security policies
  6. Bring Your Own Key (BYOK)

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.
    Revoking a key is a destructive action. You must carefully consider the action before performing it.
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
       button.
    5. Type the
      Name
       of the Key and click the
      Next
       button.
    6. If desired, add a
      Tag
       for the Key and click the
      Next
       button.
    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
      Policies
      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
      kms:generateDataKey
      .
    4. Access the
      Users
      section from the left-hand sidebar.
    5. Select the relevant Key Administrator.
    6. Add the relevant Policy that includes the ability to
      kms:generateDataKey
      .
  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
       header.
    3. Click the
      Add External Account
       button.
    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:
    2. Add the AWS EXE to your Operating System's PATH environmental variables. For example, add
      C:\Program Files\Amazon\AWSCLI
      to the PATH variable.
    3. Run the EXE.
    4. 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.
    5. 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
      . 
      Note
      : This value can be located within the
      Policy JSON
      listed in Step #2 above as the contents of the
      Resource
      field.
    6. The Response JSON will include the following information: 
      {
 "Plaintext" : "aStringOfCharactersWillBeReturned"
 "KeyId": "TheSameKeyIdWilBeReturnedThatWasInput"
 "CiphertextBlob" : "aStringOfCharactersToBeEnteredInTheBlackBerryWorkspacesAdminConsoleWithoutTheQuotesAtTheBeginningAndEnd"
}
    7. 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
      CiphertextBlob
       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.