KeyVault.getKeyByAltName.txt

.. _keyvault-getkeybyaltname-method:

==========================
KeyVault.getKeyByAltName()
==========================

.. default-domain:: mongodb

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

.. method:: KeyVault.getKeyByAltName(keyAltName)

   Gets all data encryption keys with the specified ``keyAltName``. 

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

.. code-block:: none

   keyVault = db.getMongo().getKeyVault()
   
   keyVault.getKeyByAltName("keyAltName")


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 locally managed KMS 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.getKeyByAltName()` method to retrieve the data
encryption key whose ``keyAltNames`` array includes the specified key
alternate name:

.. code-block:: javascript

   keyVault.getKeyByAltName("data-encryption-key")

:method:`~KeyVault.getKeyByAltName()` returns the following data
encryption key:

.. code-block:: json

   {
       "_id" : UUID("b4b41b33-5c97-412e-a02b-743498346079"),
       "keyMaterial" : BinData(0,"PXRsLOAYxhzTS/mFQAI8486da7BwZgqA91UI7NKz/T/AjB0uJZxTvhvmQQsKbCJYsWVS/cp5Rqy/FUX2zZwxJOJmI3rosPhzV0OI5y1cuXhAlLWlj03CnTcOSRzE/YIrsCjMB0/NyiZ7MRWUYzLAEQnE30d947XCiiHIb8a0kt2SD0so8vZvSuP2n0Vtz4NYqnzF0CkhZSWFa2e2yA=="),
       "creationDate" : ISODate("2019-08-12T21:21:30.569Z"),
       "updateDate" : ISODate("2019-08-12T21:21:30.569Z"),
       "status" : 0,
       "version" : NumberLong(0),
       "masterKey" : {
           "provider" : "local"
       },
       "keyAltNames" : [
           "data-encryption-key"
       ]
   }