BIRT provides an extension framework to support users registering their own encryption strategy with BIRT. The model implements the JCE (Java™ Cryptography Extension). The Java encryption extension framework provides multiple popular encryption algorithms, so the user can just specify the algorithm and key to have a high security level encryption. The default encryption extension plug-in supports customizing the encryption implementation by copying the BIRT default plug-in, and giving it different key and algorithm settings.
JCE provides a framework and implementations for encryption, key generation and key agreement, and Message Authentication Code (MAC) algorithms. Support for encryption includes symmetric, asymmetric, block, and stream ciphers. The software also supports secure streams and sealed objects.
A conventional encryption scheme has the following five major parts:
Plaintext, the text to which an algorithm is applied.
Encryption algorithm, the mathematical operations to conduct substitutions on and transformations to the plaintext. A block cipher is an algorithm that operates on plaintext in groups of bits, called blocks.
Secret key, the input for the algorithm that dictates the encrypted outcome.
Ciphertext, the encrypted or scrambled content produced by applying the algorithm to the plaintext using the secret key.
Decryption algorithm, the encryption algorithm in reverse, using the ciphertext and the secret key to derive the plaintext content.
About the BIRT default encryption plug-in
BIRT’s default encryption algorithm is implemented as a plug-in named:
com.actuate.birt.model._23.0.0.v20131216
Table 2‑2 shows the location of this plug-in folder in the supported BIRT environments.
Table 2‑2 Locations of the default encryption plug-in folder
Environment
Font configuration file folder location
Actuate Java Components
$ActuateJavaComponents/WEB-INF/platform/plugins
BIRT Designer
$InstallationDirectory/BRD/eclipse/plugins
BIRT Designer Professional
$InstallationDirectory/BRDPro/eclipse/plugins
Deploying encryption plug-ins to Actuate Java Components
If you use Java Components, you deploy all new encryption plug-ins to the Java Components plug-in folder. The BIRT report engine decrypts the encrypted report data during report generation. To do the decryption, it must have access to all encryption plug-ins. The report engine loads all encryption plug-ins at start up. When the engine runs a BIRT report, it reads the encryptionID property from the report design file and uses the corresponding encryption plug-in to decrypt the encrypted property. Every time you create reports using a new encryption plug-in, make sure you deploy the plug-in to Java Components installation, otherwise the report execution will fail.
How to deploy a new encryption plug-in instance to Actuate Java Components
This procedure uses com.actuate.birt.model.defaultsecurity_23.0.0_rsa as an example of a custom security emitter.
1 Extract the Java Components WAR or EAR file into temporary directory.
4 Recompress your Java Components WAR file using the Java jar utility and redeploy it to the application server or servlet engine as an application.
5 Restart the application service where the Java Components are deployed, to load the new encryption plug-in.
6 Run your report again. The engine uses the new encryption plug‑in to decrypt the password.
About the components of the BIRT default encryption plug-in
The BIRT default encryption plug-in consists of the following main modules:
acdefaultsecurity.jar
encryption.properties file
META-INF/MANIFEST.MF
plugin.xml
About acdefaultsecurity.jar
This JAR file contains the encryption classes. The default encryption plug-in also provides key generator classes that can create different encryption keys.
About encryption.properties
This file specifies the encryption settings. BIRT loads the encryption type, encryption algorithm, and encryption keys from the encryption.properties file to do the encryption. The file contains pre-generated default keys for each of the supported algorithms.
You define the following properties in the encryption.properties file:
Encryption type
Type of algorithm. Specify one of the two values, symmetric encryption or public encryption. The default type is symmetric encryption.
Encryption algorithm
The name of the algorithm. You must specify the correct encryption type for each algorithm. For the symmetric encryption type, BIRT supports DES and DESede. For public encryption type, BIRT supports RSA.
Encryption mode
In cryptography, a block cipher algorithm operates on blocks of fixed length, which are typically 64 or 128 bits. Because messages can be of any length, and because encrypting the same plaintext with the same key always produces the same output, block ciphers support several modes of operation to provide confidentiality for messages of arbitrary length. Table 2‑3 shows all supported modes.
Table 2‑3 Supported encryption modes
Mode
Description
None
No mode
CBC
Cipher Block Chaining Mode, as defined in the National Institute of Standards and Technology (NIST) Federal Information Processing Standard (FIPS) PUB 81, ”DES Modes of Operation,” U.S. Department of Commerce, Dec 1980
CFB
Cipher Feedback Mode, as defined in FIPS PUB 81
ECB
Electronic Codebook Mode, as defined in FIPS PUB 81
OFB
Output Feedback Mode, as defined in FIPS PUB 81
PCBC
Propagating Cipher Block Chaining, as defined by Kerberos V4
Encryption padding
Because a block cipher works on units of a fixed size, but messages come in a variety of lengths, some modes, for example CBC, require that the final block be padded before encryption. Several padding schemes exist. The supported paddings are shown in Table 2‑4. All padding settings are applicable to all algorithms.
Table 2‑4 Supported encryption paddings
Mode
Description
NoPadding
No padding.
OAEP
Optimal Asymmetric Encryption Padding (OAEP) is a padding scheme that is often used with RSA encryption.
PKCS5Padding
The padding scheme described in RSA Laboratories, “PKCS #5: Password-Based Encryption Standard,” version 1.5, November 1993. This encryption padding is the default.
SSL3Padding
The padding scheme defined in the SSL Protocol Version 3.0, November 18, 1996, section 5.2.3.2.
Encryption keys
Actuate provides pre-generated keys for all algorithms.
Listing 2‑1 shows the default contents of encryption.properties.
Listing 2‑1 Default encryption.properties
#message symmetric encryption , public encryption.
#For key , support default key value for algorithm
#For DESede ,DES we only need to support private key
#private key value of DESede algorithm : 20b0020…
#private key value of DES algorithm: 527c2…
#for RSA algorithm, there is a key pair. You should support private-public key pair
#private key value of RSA algorithm: 30820…
#public key value of RSA algorithm: 30819…
#By default private key is set to following
symmetric-key=527c23…
#By default public key is not set
public-key=
About META-INF/MANIFEST.MF
META-INF/MANIFEST.MF is a text file that is included inside a JAR file to specify metadata about the file. Java’s default ClassLoader reads the attributes defined in MANIFEST.MF and appends the specified dependencies to its internal classpath.
The encryption plug-in ID is the value of the Bundle-SymbolicName property in the manifest file for the encryption plug-in. You need to change this property when you deploy multiple instances of the default encryption plug-in, as described later in this chapter.
Listing 2‑2 shows the contents of the default MANIFEST.MF.
plugin.xml is the plug-in descriptor file. This file describes the plug-in to the Eclipse platform. The platform reads this file and uses the information to populate and update, as necessary, the registry of information that configures the whole platform.
The <plugin> tag defines the root element of the plug-in descriptor file. The <extension> element within the <plugin> element specifies the Eclipse extension point that this plug-in uses, org.eclipse.birt.report.model.encryptionHelper. This extension point requires a sub-element, <encryptionHelper>. This element uses the following attributes:
class
The qualified name of the class that implements the interface IEncryptionHelper. The default class name is com.actuate.birt.model.defaultsecurity.api.DefaultEncryptionHelper.
extensionName
The unique internal name of the extension. The default extension name is jce.
isDefault
Field indicating whether this encryption extension is the default for all encryptable properties. This property is valid only in a BIRT Designer environment. When an encryption plug-in sets the value of this attribute to true, the BIRT Designer uses this encryption method as the default to encrypt data. There is no default encryption mode in Java Components.
The encryption model that BIRT uses supports implementing and using several encryption algorithms. The default encryption plug-in is set as default using this isDefault attribute. If you implement several encryptionHelpers, set this attribute to true for only one of the implementations. If you implement multiple encryption algorithms and set isDefault to true to more than one instance, BIRT treats the first loaded encryption plug-in as the default algorithm.
Listing 2‑3 shows the contents of the default encryption plug-in’s plugin.xml.
In some cases, you need to use an encryption mechanism other than the Data Source Explorer default in your report application. For example, some applications need to create an encryption mechanism using the RSA algorithm that the default encryption plug-in supports. In this case, you must create an additional encryption plug-in instance. For use within a BIRT Designer, you can set this plug-in as the default encryption mechanism. If you change the default encryption mechanism, you must take care when you work with old report designs. For example, if you change an existing password field in the designer, the designer re-encrypts the password with the current default encryption algorithm regardless of the original algorithm that the field used.
How to create a new instance of the default encryption plug-in
2 Change the encryption type to public encryption:
type=public encryption
3 Change the algorithm type to RSA:
algorithm=RSA
4 Copy the pre-generated private and public keys for RSA to the symmetric‑key and public‑key properties. encryption.properties now looks similar to the one in Listing 2‑6.
Listing 2‑6 Modified encryption.properties file for the new encryption plug-in
8 Create a data set and a simple report design. Preview the report to validate that BIRT connects successfully to the database server using the encrypted password. Before trying to connect to the data source the report engine decrypts the password stored in the report design using the default RSA encryption. The engine sends the decrypted value to the database server.
Generating encryption keys
The default encryption plug-in provides classes that can be used to generate different encryption keys. The classes’ names are SymmetricKeyGenerator and PublicKeyPairGenerator. SymmetricKeyGenerator generates private keys, which are also known as symmetric keys. PublicKeyPairGenerator generates public keys. Both classes require acdefaultsecurity.jar in the classpath.
Both classes take two parameters, the encryption algorithm and the output file, where the generated encrypted key is written. The encryption algorithm is a required parameter. The output file is an optional parameter. If you do not provide the second parameter, the output file is named key.properties and is saved in the current folder. The encryption algorithm values are shown in Table 2‑5.
Plaintext, the text to which an algorithm is applied.