Troubleshoot Cryptography Module
To troubleshoot the Cryptography module, become familiar with app logs, PGP protocol, attached and detached signatures, and interpreting commonly thrown messages.
View the App Log
If you encounter problems while running your Mule runtime engine (Mule) app, you can view the app log as follows:
-
If you’re running the app from Anypoint Platform, the output is visible in the Anypoint Studio console window.
-
If you’re running the app using Mule from the command line, the app log is visible in your OS console.
Unless the log file path is customized in the app’s log file log4j2.xml
, view the app log in the default location MULE_HOME/logs/<app-name>.log
.
Enable Cryptography Module Debug Logging
To begin troubleshooting the Cryptography module, enable debug logging to see the exact error messages:
-
Access Anypoint Studio and navigate to the Package Explorer view.
-
Open your application by clicking the project name.
-
Open the
src/main/resources
path folder. -
Open the
log4j2.xml
file inside the folder. -
Add the following line:
<AsyncLogger name="com.mulesoft.modules.cryptography" level="DEBUG" />
-
Save your changes.
-
Click the project name in Package Explorer and then click Run > Run As > Mule Application.
Understand PGP Encryption and Decryption Configuration
During PGP encryption, the sender of the message must encrypt its content using the receiver’s public key. To encrypt messages in your Mule app using someone else’s public key, in the Crypto Pgp global configuration add the receiver public keyring file in the Public keyring field.
During PGP decryption, the receiver of the message must use its private key to decrypt the contents of a message that was encrypted using a public key. To decrypt the message, in the Crypto Pgp global configuration add the receiver private keyring file in the Private keyring field.
Understand PGP Signature Configuration
In addition to encrypting, you can sign a message. The signature provides an integrity check of the original message.
To create a signature, in the Crypto Pgp global configuration add the sender private keyring file in the Private keyring field.
To validate a signature, in the Crypto Pgp global configuration add the sender public keyring file in the Public keyring field.
PGP Signature Types and Operations
The Cryptography module has two PGP signature operations:
-
Pgp sign: Creates a PGP armored signature in ASCII format.
-
Pgp sign binary: Creates a PGP binary signature.
In both cases, signing includes the private key of the sender, so the secret passphrase must be provided.
There are two types of signatures:
-
Attached signature
Generates a single document file that contains both the signature and the original document. -
Detached signature
Generates a single document file that contains only the signature, which is stored and transmitted separately from the document the signature signs.
Currently, the Cryptography module supports validation of detached signatures only.
Understand Common Throws
Here is a list of common throw messages and how to interpret them:
-
CRYPTO:PARAMETERS
The operation is configured using invalid parameters.
-
CRYPTO:MISSING_KEY
A key required for the operation was not found.
-
CRYPTO:PASSPHRASE
The unlocking password is invalid.
-
CRYPTO:CHECKSUM
An error occurred during an attempt to calculate a checksum.
-
CRYPTO:TRANSFORMATION
An error occurred during an attempt to transform binary to ASCII to build the ASCII Armor file.
-
CRYPTO:VALIDATION
The signature cannot be validated against the data.