KeyVault.removeKeyAlternateName.txt

.. _keyvault-removekeyalternatename-method:

=================================
KeyVault.removeKeyAlternateName()
=================================

.. default-domain:: mongodb

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

.. method:: KeyVault.removeKeyAlternateName(UUID, keyAltName)

   Removes the specified ``keyAltName`` from the data encryption key
   with the specified ``UUID``. The data encryption key must exist in
   the key vault associated to the database connection.

   :returns:
     The data encryption key *prior* to updating the ``keyAltName``.

     Returns ``null`` if no data encryption key has the specified
     ``UUID()``.


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

.. code-block:: none

   keyVault = db.getMongo().getKeyVault()
   
   keyVault.removeKeyAlternateName(
      UUID("<UUID string>"),
      "keyAltName"
   )


Behavior
--------

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

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

Example
-------

The following example is intended for rapid evaluation of
client-side field level encryption. For specific examples of using
:method:`KeyVault.removeKeyAlternateName()` with each supported
:abbr:`KMS (Key Management Service)` provider, see
:ref:`field-level-encryption-data-key-manage`.

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

Retrieve the :method:`keyVault <getKeyVault()>` object and use the
:method:`KeyVault.removeKeyAlternateName()` method to remove the
specified key alternate name from the data encryption key with matching
``UUID``:

.. code-block:: javascript

   keyVault = encryptedClient.getKeyVault()
   keyVault.removeKeyAlternateName(UUID("b4b41b33-5c97-412e-a02b-743498346079"),"Other-Data-Encryption-Key")

If successful, :method:`~KeyVault.removeKeyAlternateName()` returns the
data encryption key *prior* to updating the ``keyAltName``.

.. 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" : [
           "ssn-encryption-key"
       ]
   }