getKeyVault.txt

=============
getKeyVault()
=============

.. default-domain:: mongodb

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

.. method:: getKeyVault()

   Returns the ``KeyVault`` object for the current database connection.
   The ``KeyVault`` object supports data encryption key management for
   :ref:`{+csfle+} <manual-csfle-feature>`. 

   :returns:

     The ``KeyVault`` object for current database connection.


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:`getKeyVault()` has the following syntax:

.. code-block:: javascript

   keyVault = db.getMongo().getKeyVault();

Use the ``KeyVault`` object to access the following data encryption key
management methods:

- :method:`~KeyVault.getKey`
- :method:`~KeyVault.getKeys`
- :method:`~KeyVault.getKeyByAltName`
- :method:`~KeyVault.createKey`
- :method:`~KeyVault.addKeyAlternateName`
- :method:`~KeyVault.removeKeyAlternateName`  
- :method:`~KeyVault.deleteKey`


Behavior
--------

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

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

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

Unique Partial Index on Key Vault
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. include:: /includes/extracts/csfle-keyvault-unique-index.rst

Example
-------

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

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

Use the :method:`getKeyVault()` method to retrieve the
key vault object:

.. code-block:: javascript

   keyVault = encryptedClient.getKeyVault()

For complete documentation on initiating MongoDB connections with
client-side field level encryption enabled, see :method:`Mongo()`.