Documentation
我要评分
获取效率
正确性
完整性
易理解
提交关闭

Enabling the Enhanced Heap Dump Feature

Introduction

JVM provides the capability of dumping process heap data. If sensitive information is stored in the Java process memory, dumping heap files may cause information leakage. The enhanced heap dump feature masks the sensitive information while maintaining the heap dump fault locating capability. This feature is of great significance to protect data security and privacy, especially for confidential projects.

Application Scenario

Heap dump files are required for fault locating or performance analysis, and sensitive information in the files needs to be protected from leakage.

Restrictions

  • The enhanced heap dump feature is available in BiSheng JDK 8 (since 8u422) and BiSheng JDK 17 (since 17.0.12).
  • The Java version must match the JDK package that supports this feature.
  • The BiSheng JDK acceleration software package has been installed based on Installing the BiSheng JDK Acceleration Library.

How to Use

You can enable the enhanced heap dump feature in either of the following ways:

  • Using the java command:
    1
    java -Xmx10M -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpRedact=full -XX:RedactMapFile=/home/heapmap.txt -XX:RedactMap="password:abc,encrypt:cde" MyClass -XX:RedactClassPath=/myClass/.../ReplaceValueAnnotation
  • Using the jmap command:
    1
    jmap -dump:HeapDumpRedact=<names/basic/full/annotation/diyrules/off>,RedactMap="<key1:value1;key2:value2;...>",RedactMapFile=<file path>,RedactClassPath=</myClass/.../ReplaceValueAnnotation> <pid>

    For details about jmap command parameters, see Heap Dump Anonymization User Guide.

For details about the parameters in the preceding commands, see Table 1.

Table 1 Command parameters

Parameter

Description

-XX:HeapDumpRedact

Specifies the anonymization mode.

  • names: masks sensitive symbols. You need to specify a mapping table in a file using the RedactMapFile parameter or directly in the command line using the RedactMap parameter.
  • basic: masks int/char/byte arrays by clearing them.
  • full: names + basic
  • annotation: masks sensitive field values. In the development phase, the developer needs to define annotation classes for anonymization. When dumping data, specify the class name (including the classpath), and the value within the annotation class will replace the field value.
  • diyrules: masks sensitive field values. You need to specify classes and field values to be masked in a file using the RedactMapFile parameter or directly in the command line using the RedactMap parameter.
  • off: disables heap dump anonymization (the enhanced heap dump feature). This is the default mode.

-XX:RedactMap

Specifies sensitive name mapping pairs to be masked. Use semicolons (;) to separate multiple pairs and a colon (:) to separate the key and value in a pair. Example: key1:value1;key2:value2...

-XX:RedactMapFile

Obtains the mapping of sensitive names to be masked from the specified file.

-XX:RedactClassPath

Specifies annotation classes for sensitive value replacement.