Skip to content

Commit 1b64140

Browse files
jason-price-mongodbjason-price-mongodb
jason-price-mongodb
and
jason-price-mongodb
authored
DOCSP-14355 at rest encryption of audit logs (#220)
Co-authored-by: jason-price-mongodb <[email protected]>
1 parent 448ad32 commit 1b64140

14 files changed

+315
-14
lines changed

‎conf.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -76,7 +76,7 @@ def has(self, *args):
7676
])
7777

7878
source_constants = {
79-
'version-dev': '5.2', # Current development branch
79+
'version-dev': '5.3', # Current development branch
8080
'package-name-org': 'mongodb-org',
8181
'package-name-enterprise': 'mongodb-enterprise',
8282
'version': version,

‎snooty.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -205,7 +205,7 @@ package-name-org = "mongodb-org"
205205
package-name-enterprise = "mongodb-enterprise"
206206
version = "5.0"
207207
release = "5.0.5"
208-
version-dev = "5.2"
208+
version-dev = "5.3"
209209
pgp-version = "{+version+}"
210210
rsa-key = "4B7C549A058F8B6B"
211211
pgp-fingerprint = "E162F504A20CDF15827F718D4B7C549A058F8B6B"

‎source/core/security-encryption-at-rest.txt‎

Lines changed: 40 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -111,21 +111,49 @@ transport encryption.
111111

112112
For details, see :ref:`rotate-encryption-keys`.
113113

114-
Logging
115-
~~~~~~~
114+
Audit Log
115+
~~~~~~~~~
116116

117-
.. versionadded:: 3.4 Available in MongoDB Enterprise only
117+
Available in MongoDB Enterprise only.
118118

119-
The log file is not encrypted as a part of MongoDB's encrypted storage engine.
120-
A :binary:`~bin.mongod` running with :ref:`logging <monitoring-standard-loggging>`
121-
may output potentially sensitive information to log files as a part of normal
122-
operations, depending on the configured :ref:`log verbosity
123-
<log-messages-configure-verbosity>`.
119+
.. _security-encryption-at-rest-audit-log:
124120

125-
MongoDB 3.4 Enterprise provides the :setting:`security.redactClientLogData`
126-
setting to prevent potentially sensitive information from entering the
127-
:binary:`~bin.mongod` process log. :setting:`~security.redactClientLogData`
128-
reduces detail in the log and may complicate log diagnostics.
121+
Use KMIP Server to Manage Keys for Encrypting the MongoDB Audit Log
122+
```````````````````````````````````````````````````````````````````
123+
124+
Starting in MongoDB 5.3 Enterprise, you can use an external Key
125+
Management Interoperability Protocol (KMIP) server to securely manage
126+
the keys for encrypting the MongoDB audit log.
127+
128+
To use a KMIP server with audit log encryption, configure these settings
129+
and parameters:
130+
131+
- :setting:`auditLog.auditEncryptionKeyIdentifier` setting
132+
- :setting:`auditLog.compressionMode` setting
133+
- :parameter:`auditEncryptionHeaderMetadataFile` parameter
134+
- :parameter:`auditEncryptKeyWithKMIPGet` parameter
135+
136+
For testing audit log encryption, you can also use the
137+
:setting:`auditLog.localAuditKeyFile` setting.
138+
139+
Unencrypted Audit Log and Process Log
140+
`````````````````````````````````````
141+
142+
This section applies if you are not using an external Key Management
143+
Interoperability Protocol (KMIP) server to manage keys for encrypting
144+
the audit log as shown in the previous section.
145+
146+
The audit log file is not encrypted as a part of MongoDB's encrypted
147+
storage engine. A :binary:`~bin.mongod` running with :ref:`logging
148+
<monitoring-standard-loggging>` may output potentially sensitive
149+
information to log files as a part of normal operations, depending on
150+
the configured :ref:`log verbosity <log-messages-configure-verbosity>`.
151+
152+
Use the :setting:`security.redactClientLogData` setting to prevent
153+
potentially sensitive information from entering the
154+
:binary:`~bin.mongod` process log.
155+
:setting:`~security.redactClientLogData` reduces detail in the log and
156+
may complicate log diagnostics.
129157

130158
See the :ref:`log redaction <monitoring-log-redaction>` manual entry for
131159
more information.

‎source/includes/audit-compression-mode-option.rst‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
.. versionadded:: 5.3
2+
3+
Specifies the compression mode for :ref:`audit log encryption
4+
<security-encryption-at-rest-audit-log>`. You must also enable audit log
5+
encryption using either |audit-encryption-key-identifier-option| or
6+
|audit-local-keyfile-option|.
7+
8+
|audit-compression-mode-option| can be set to one of these values:
9+
10+
.. list-table::
11+
:header-rows: 1
12+
:widths: 15 50
13+
14+
* - Value
15+
- Description
16+
17+
* - ``zstd``
18+
- Use the :term:`zstd` algorithm to compress the audit log.
19+
20+
* - ``none`` *(default)*
21+
- Do not compress the audit log.
22+
23+
.. include:: /includes/note-audit-in-enterprise.rst

‎source/includes/audit-encryption-key-identifier-option.rst‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
.. versionadded:: 5.3
2+
3+
Specifies the unique identifier of the Key Management
4+
Interoperability Protocol (KMIP) key for :ref:`audit log encryption
5+
<security-encryption-at-rest-audit-log>`.
6+
7+
You cannot use |audit-encryption-key-identifier-option| and
8+
|audit-local-keyfile-option| together.
9+
10+
.. include:: /includes/note-audit-in-enterprise.rst

‎source/includes/audit-local-key-file-option.rst‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
.. versionadded:: 5.3
2+
3+
Specifies the path and file name for a local audit key file for
4+
:ref:`audit log encryption <security-encryption-at-rest-audit-log>`.
5+
6+
.. note::
7+
8+
Only use |audit-local-keyfile-option| for testing because the key is
9+
not secured. To secure the key, use
10+
|audit-encryption-key-identifier-option| and an external Key
11+
Management Interoperability Protocol (KMIP) server.
12+
13+
You cannot use |audit-local-keyfile-option| and
14+
|audit-encryption-key-identifier-option| together.
15+
16+
.. include:: /includes/note-audit-in-enterprise.rst

‎source/includes/note-audit-in-enterprise.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
.. note::
2+
3+
Available only in `MongoDB Enterprise
4+
<http://www.mongodb.com/products/mongodb-enterprise-advanced?tck=docs_server>`_.
5+
MongoDB Enterprise and Atlas have different configuration
6+
requirements.

‎source/reference/configuration-file-settings-command-line-options-mapping.txt‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,13 @@ and :binary:`~bin.mongos` command-line options.
1717
* - Configuration File Setting
1818
- ``mongod`` and ``mongos`` Command-Line Options
1919

20+
* - :setting:`auditLog.auditEncryptionKeyIdentifier`
21+
- | :option:`mongod --auditEncryptionKeyUID`
22+
| :option:`mongos --auditEncryptionKeyUID`
23+
24+
* - :setting:`auditLog.compressionMode`
25+
- | :option:`mongod --auditCompressionMode`
26+
| :option:`mongos --auditCompressionMode`
2027

2128
* - :setting:`auditLog.destination`
2229
- | :option:`mongod --auditDestination`
@@ -30,6 +37,10 @@ and :binary:`~bin.mongos` command-line options.
3037
- | :option:`mongod --auditFormat`
3138
| :option:`mongos --auditFormat`
3239

40+
* - :setting:`auditLog.localAuditKeyFile`
41+
- | :option:`mongod --auditLocalKeyFile`
42+
| :option:`mongos --auditLocalKeyFile`
43+
3344
* - :setting:`auditLog.path`
3445
- | :option:`mongod --auditPath`
3546
| :option:`mongos --auditPath`

‎source/reference/configuration-options.txt‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4311,6 +4311,24 @@ LDAP Parameters
43114311
path: <string>
43124312
filter: <string>
43134313

4314+
.. |audit-compression-mode-option| replace:: :setting:`auditLog.compressionMode`
4315+
.. |audit-encryption-key-identifier-option| replace:: :setting:`auditLog.auditEncryptionKeyIdentifier`
4316+
.. |audit-local-keyfile-option| replace:: :setting:`auditLog.localAuditKeyFile`
4317+
4318+
.. setting:: auditLog.auditEncryptionKeyIdentifier
4319+
4320+
*Type*: string
4321+
4322+
.. include:: /includes/audit-encryption-key-identifier-option.rst
4323+
4324+
.. setting:: auditLog.compressionMode
4325+
4326+
*Type*: string
4327+
4328+
.. |option-1| replace:: :setting:`auditLog.compressionMode`
4329+
4330+
.. include:: /includes/audit-compression-mode-option.rst
4331+
43144332
.. setting:: auditLog.destination
43154333

43164334
*Type*: string
@@ -4408,6 +4426,12 @@ LDAP Parameters
44084426

44094427
.. include:: /includes/note-audit-in-enterprise-only.rst
44104428

4429+
.. setting:: auditLog.localAuditKeyFile
4430+
4431+
*Type*: string
4432+
4433+
.. include:: /includes/audit-local-key-file-option.rst
4434+
44114435
.. setting:: auditLog.path
44124436

44134437
*Type*: string

‎source/reference/parameters.txt‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4154,6 +4154,58 @@ Auditing Parameters
41544154
Using the default value of 300 seconds, non-config nodes may lag up
41554155
to 5 minutes behind a setAuditConfig command.
41564156

4157+
.. parameter:: auditEncryptionHeaderMetadataFile
4158+
4159+
.. versionadded:: 5.3
4160+
4161+
*Type*: string
4162+
4163+
.. include:: /includes/note-audit-in-enterprise.rst
4164+
4165+
|both|
4166+
4167+
Path and file name for logging metadata audit headers for :ref:`audit
4168+
log encryption <security-encryption-at-rest-audit-log>`. A header is
4169+
placed at the top of each audit log file and contains metadata for
4170+
decrypting the audit log. The headers are also stored in the
4171+
:doc:`audit log </core/auditing>`.
4172+
4173+
You can only set :parameter:`auditEncryptionHeaderMetadataFile`
4174+
during startup in the :setting:`configuration file <setParameter>` or
4175+
with the ``--setParameter`` option on the command line. For example,
4176+
the following sets the path and file for
4177+
:parameter:`auditEncryptionHeaderMetadataFile`:
4178+
4179+
.. code-block:: bash
4180+
4181+
mongod --setParameter auditEncryptionHeaderMetadataFile=/auditFiles/auditHeadersMetadataFile.log
4182+
4183+
.. parameter:: auditEncryptKeyWithKMIPGet
4184+
4185+
.. versionadded:: 5.3
4186+
4187+
*Type*: boolean
4188+
4189+
*Default*: false
4190+
4191+
.. include:: /includes/note-audit-in-enterprise.rst
4192+
4193+
|both|
4194+
4195+
Enables :ref:`audit log encryption
4196+
<security-encryption-at-rest-audit-log>` for Key Management
4197+
Interoperability Protocol (KMIP) servers that only support KMIP
4198+
protocol version 1.0 or 1.1.
4199+
4200+
You can only set :parameter:`auditEncryptKeyWithKMIPGet` during
4201+
startup in the :setting:`configuration file <setParameter>` or with
4202+
the ``--setParameter`` option on the command line. For example, the
4203+
following sets :parameter:`auditEncryptKeyWithKMIPGet` to ``true``:
4204+
4205+
.. code-block:: bash
4206+
4207+
mongod --setParameter auditEncryptKeyWithKMIPGet=true
4208+
41574209
Transaction Parameters
41584210
~~~~~~~~~~~~~~~~~~~~~~
41594211

0 commit comments

Comments
 (0)