KeyVault.getKey.txt

.. _keyvault-getkey-method:

=================
KeyVault.getKey()
=================

.. default-domain:: mongodb

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 1
   :class: singlecol

.. method:: KeyVault.getKey(UUID)

   Gets a data encryption key with the specified ``UUID``. The data
   encryption key must exist in the key vault associated to the database
   connection.

   :returns:
  
     Document representing a matching data encryption key.


Compatibility
-------------

This command is available in deployments hosted in the following
environments: 

.. include:: /includes/fact-environments-atlas-only.rst

.. include:: /includes/fact-environments-onprem-only.rst


Syntax
------

:method:`~KeyVault.getKey()` has the following syntax:

.. code-block:: none

   keyVault = db.getMongo().getKeyVault()
   
   keyVault.getKey(UUID("<UUID String>"))

The :abbr:`UUID (Universally unique identifier)` is a BSON 
:bsontype:`binary data <Binary>` object with subtype ``4``.


Behavior
--------

Requires Configuring Client-Side Field Level Encryption on Database Connection
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. include:: /includes/extracts/csfle-requires-enabling-encryption.rst

Example
-------

The following example uses a :ref:`locally managed KMS
<qe-fundamentals-kms-providers-local>` for the client-side field level
encryption configuration. 

.. include:: /includes/csfle-connection-boilerplate-example.rst

Retrieve the :method:`keyVault <getKeyVault()>` object and
use the :method:`KeyVault.getKey()` to retrieve
a data encryption key using its ``UUID``:

.. code-block:: javascript

   keyVault = encryptedClient.getKeyVault()
   keyVault.getKey(UUID("b4b41b33-5c97-412e-a02b-743498346079"))

:method:`~KeyVault.getKey()` returns the data encryption key, with
output similar to the following:

.. code-block:: json

   {
     "_id" : UUID("b4b41b33-5c97-412e-a02b-743498346079"),
     "keyMaterial" : BinData(0,"E+0jZKzA4YuE1lGmSVIy2mivqH4JxFo0yFATdxYX/s0YtMFsgVXyu7Bbn4IQ2gn7F/9JAPJFOxdQc5lN3AR+oX33ewVZsd63f3DN1zzcukqdR2Y+EeO7ekRxyRjdzMaNNrBNIv9Gn5LEJgWPSYkG8VczF7cNZnc1YmnR0tuDPNYfm0J7dCZuZUNWW3FCGRcdFx6AlXiCtXKNR97hJ216pQ=="),
     "creationDate" : ISODate("2021-03-16T18:22:43.733Z"),
     "updateDate" : ISODate("2021-03-16T18:22:43.733Z"),
     "status" : 0, "version" : NumberLong(0),
     "masterKey" : {
       "provider" : "local"
     },
     "keyAltNames" : [
        "alpha"
     ]
   }