configuration on the koma - robotron

DOCI

D-21

-328

5, 2

4 M

ay 2

017

Robotron Energy Market Suite - S/MIME Encryption and Signing of 12

Version: 1.0

S/MIME S/MIME (Secure/Multipurpose Internet Mail Extensions) is a standard for the encryption and signing of e-mails. This chapter exclusively refers to the import and export of e-mail files. Bouncy Castle serves as the basis (Java third-party library) for this purpose. There are currently two methods for processing the S/MIME logic. The first method is based on the use of the “SMIME-TOMCAT”. Meanwhile, this method is DEPRECATED. If you still use it, it should be migrated to the new method as soon as possible! The migration must be executed by the Robotron support. For this, the certificates from EC_SYS.NAS_ZERTIFIKATE are transferred to EC_CERT.EMAIL_CERTIFICATES and the private key of the Tomcat application is migrated to the KomA. In the following, only the new method is described in detail.

The chapter currently refers to the ticket: eCount- 00072477. The S/MIME function can only be operated with a patched Java version (JCE).

Configuration on the KomA

The new method must currently be activated explicitly (since the old “TOMCAT method” can only be switched off when all systems have been migrated). For this, the following must be set in the Config.properties: crypto.SMIME.NEW_MODE=Y

A recommendable configuration (according to the BDEW) looks the following: crypto.SMIME.NEW_MODE=Y

crypto.SMIME.CHECK_SIGNATURE_CERTIFICATE=Y

crypto.SMIME.CHECK_SIGNATURE_CERTIFICATE_AS_WARNING=N

Signature – Hash Algorithm

The hash algorithm is defined in the Config.properties as follows: crypto.SMIME.SIGNATUR_HASHALGORITHMUS

The default value is SHA256WITHRSA. In the BDEW context (from 23 February 2017), SHA512WITHRSA can still be used. As of 1 January 2018, SHA256WITHRSAANDMGF1 or SHA512WITHRSAANDMGF1 must be set (thus applying RSASSA-PSS as the signature procedure). The setting is only relevant for the dispatch.

In the transitional period (until 1 January 2018), the default value should not be changed unless it is ensured that all market partners can process RSASSA-PSS. If this is not the case and some market partners explicitly require RSASSA-PSS, then this can be realised via the following Config.properties

https://www.bouncycastle.org/java.html

DOCI

D-21

-328

5, 2

4 M

ay 2

017

of 12 Robotron Energy Market Suite - S/MIME Encryption and Signing

Version: 1.0

setting: crypto.SMIME.RSASSA_PSS_FOR_EMAILS Here, all e-mail addresses (recipients = TO address of the export order) are entered to which RSASSA-PSS should apply. Multiple entries are separated by a semicolon.

Valid settings:

- SHA1WITHDSA - SHA1WITHRSAENCRYPTION - SHA1WITHRSA - SHA256WITHDSA - SHA256WITHRSAENCRYPTION - SHA256WITHRSA - SHA384WITHDSA - SHA384WITHRSAENCRYPTION - SHA384WITHRSA - SHA512WITHDSA - SHA512WITHRSAENCRYPTION - SHA512WITHRSA - SHA256WITHRSAANDMGF1 - SHA512WITHRSAANDMGF1

Encryption Algorithm (Content Encryption)

The encryption algorithm is defined using the Config.properties setting: crypto.SMIME.ENCRYPT_ALGORITHMUS

The default value is AES128_CBC. In the BDEW context (from 23 February 2017), AES128_CBC or AES192_CBC can still be used. The setting is only relevant for the dispatch.

Valid settings:

- AES128_CBC - AES128_CCM - AES128_GCM - AES128_WRAP - AES192_CBC - AES192_CCM - AES192_GCM - AES192_WRAP - AES256_CBC - AES256_CCM - AES256_GCM - AES256_WRAP - DES_CBC - DES_EDE3_CBC - DES_EDE3_WRAP

DOCI

D-21

-328

5, 2

4 M

ay 2

017


Version: 1.0

Encryption Algorithm (Key Encryption)

According to the BDEW, only RSAES-OAEP must be applied as of 1 January 2018. Currently, the value results from the certificate used, which in most cases is OID: "1.2.840.113549.1.1.1 – RSA". You can globally switch to RSAES-OAEP using the following Config.properties setting: crypto.SMIME.KEY_ENCRYPT_ALGORITHMUS

Possible values are:

- PKCS#1_RSAES_OAEP RSAES-OAEP with hash function SHA256

- PKCS#1_RSAES_OAEP_512 RSAES-OAEP with hash function SHA512

In the transitional period (until 1 January 2018), it could be that not all market partners can process RSAES-OAEP. Thus, the default cannot be changed. If some market partners explicitly require this algorithm, then this can be realised via the Config.properties setting crypto.SMIME.RSAES_OAEP_FOR_EMAILS. Here, all e-mail addresses (recipients = TO address of the export order) are entered to which RSAES-OAEP should apply. Multiple entries are separated by a semicolon (;).

CeMaS

The certificates must be imported using the Certificate Management Service (CeMaS) when a check against the certificate revocation list (CA) should be performed once a day according to the BDEW specifications. If the CeMaS is not used, then no check against the revocation list will take place, the certificates must be manually deleted/administered. If the CeMaS is used, then this must be communicated to the KomA. For this, the following must be stored in the Config.properties: crypto.SMIME.USE_CEMAS_VIEWS=Y

Technical background: If the setting is activated, then the queries are carried out via the CeMaS tables hiding behind the DB views EC_CERT.V_EMAIL_CERTIFICATES and EC_CERT.V_EMAIL_CERTIFICATES_ALL. The certificates are queried via the DB function: EC_CERT.PKG_EMAIL_CERTIFICATES.FNC_GET_CERT_BY_ID(?)

Signature Check

When checking the signature, the API (Bouncy Castle) checks whether the signature is correct (matching hash values) and whether the certificate was valid during the creation of the signature (concerning the validity period of the certificate). Additionally, it can be checked whether the sender (the signer) is actually known in the system. This setting must currently be activated explicitly via the Config.properties setting: crypto.SMIME.CHECK_SIGNATURE_CERTIFICATE=Y

DOCI

D-21

-328

5, 2

4 M

ay 2

017


Version: 1.0

Possible values are Y/N (default value: N).

If the check is activated, then the information of the signature (serial number of the certificate that has created the signature and the issuer of the certificate) is checked against the database as to whether or not the certificate exists. Only certificates stored in the system are classified as valid signatures. When using the CEMAS functionality (crypto.SMIME.USE_CEMAS_VIEWS=Y), it is additionally checked whether the certificate was revoked. So when the query fails, the import of the e-mail is prevented! If this behaviour is not desired – i.e. the e-mail should nevertheless be imported – then the behaviour can be changed using the Config.properties-setting: crypto.SMIME.CHECK_SIGNATURE_CERTIFICATE_AS_WARNING. Possible values are Y/N (default value: N). If Y, the import will not be prevented, merely a warning is written into the log file.

Storage of the Certificates

The exclusive maintenance of the certificates by the CeMaS is currently not considered here! If the CeMaS is used, then the maintenance of the certificates via the GUI or the KomA import filter is redundant.

The certificates (also called public keys) can be maintained as follows. As a first option, the certificates can be uploaded via import using the KomA (e.g. mass import), meaning a KomA import filter (filter_import/ecount_import_CERTLOADER.jar eCount- 00063625) for X.509 certificates. The filter must be configured in the datenimport.ini file in order to write the certificates into the table EC_CERT.EMAIL_CERTIFICATES.

X.509 certificates with the following file extensions are supported:

- .CER – DER- or Base64-encoded certificate - .CRT – DER- or Base64-encoded certificate - .PEM – Base64-encoded certificate, enclosed by -----BEGIN CERTIFICATE----- and

-----END CERTIFICATE----- - .DER – DER-encoded certificate

As a second option, the certificates can be manually uploaded in robotron*ecount in the Message Addresses mask. On the Certificates tab you can upload public certificates to EC_CERT.EMAIL_CERTIFICATES. By clicking on the green plus sign in the toolbar (for creating a new data record), the locally stored certificate must be selected.

DOCI

D-21

-328

5, 2

4 M

ay 2

017


Version: 1.0

Figure 1: Certificates Tab in the Message Addresses Mask

Storage of the Private Key

The private key is stored in the KomA. A password, which is required in most cases, is stored in encrypted form. A 100 % protection cannot be guaranteed here, which is why it is reasonable to only grant privileged users access to the KomA. The storage of the keys is controlled via the Config.properties file and the setting importcom.PrivateKeyStore.baseDir. By default, the folder is located in the KomA under config/PrivateKeys. Under Windows, both a GUI (Key Importer) and a console mode are available for the import. Under Linux, only the console mode is available. The Keytool is started by executing the following files:

- smime-private-key-importer-console.cmd - smime-private-key-importer-gui.cmd - smime-private-key-importer-console.sh

DOCI

D-21

-328

5, 2

4 M

ay 2

017


Version: 1.0

The import via the GUI (Key Importer) is self-explanatory: On the Import tab, there is the option Keystore open with which a P12 or PFX file can be uploaded. After entering the password, the keys are displayed. Using the Import checkbox, the respective key(s) can be selected and imported by means of the Import selected keys button.

Figure 2: S/MIME Key Importer (GUI)

Figure 3: S/MIME Key Importer (GUI) – Import

DOCI

D-21

-328

5, 2

4 M

ay 2

017


Version: 1.0

The console version is slightly less user-friendly. Here, the path to the P12/PFX file + password are entered and then the import takes place immediately.

Retry of Messages

In case of two error types, a subsequent correction and thus a possibly successful import of the e-mail is still possible. This includes the following errors:

1. Private key for decryption not found 2. Certificate of the signature not found in the database

In both cases, the problem can be fixed by maintaining the private key or the certificate.

If such an error occurs, then this is registered separately by the KomA in the database (S or K is stored in the STATUS column of the COM_MESSAGE table). The e-mail is saved into a special directory: <importcom.mail_dir>/IA< COM_CONNECTION.ID>/SMIME/

This is also done when importcom.save_mail=N is set! For this reason, the KomA always creates the folder behind importcom.mail_dir (by default importmail). This path of the e-mail file is registered in the database (COM_MESSAGE.ERROR_FILE). In the robotron*ecount user interface (currently in the Import Communication mask > Show all messages button > Messages dialog), the message can then be reimported (at least the retry can be started). In this process, the value R is stored in COM_MESSAGE.STATUS. The KomA retrieves these entries and attempts to reimport the file (locally identified by the KomA via the path in COM_MESSAGE.ERROR_FILE). Now, either the import works and the file is successfully imported or the import fails again. In both cases, COM_MESSAGE.STATUS is updated to a value unequal R so that the run is only executed once.

Figure 4: Retry Comimport via the Import Configuration Mask

DOCI

D-21

-328

5, 2

4 M

ay 2

017


Version: 1.0

Procedure – Signature Creation

When creating the signature, the oldest, currently valid private key is always used (smallest valid To-date). Although it is technically possible to create multiple signatures with different private keys, common e-mail clients throw error messages if the recipient only holds one matching certificate. In the example, an e-mail was signed with three different keys. However, on the receiver side (Microsoft Outlook) only two corresponding certificates are installed. The client shows an error because it cannot check one of the signatures.

Figure 5: Signature Error Message in Outlook

For this reason, only the oldest valid private key is always used for the signature. This must be taken into account if, for example, a communication with a completely new recipient is started shortly before the key expires. All currently valid certificates (not only the latest) must be transmitted to the new recipient because otherwise they cannot check the signature (which may have been generated with an older key).

Procedure – Encryption

During the encryption, all currently valid certificates belonging to an e-mail address are used. On the receiver side, it is sufficient to have a matching private key to decrypt the e-mail.

CC/BCC – Dispatch without S/MIME

By default, e-mails are also sent to CC and BCC addresses in encrypted and unsigned form if so provided for the export order. This behaviour can be globally deactivated on the KomA for CC and/or BCC. In order to send e-mails both to all CC and BCC addresses without S/MIME, the following must be configured in the Config.properties. export.MEX.SEND_CC_WITH_SMIME=N

export.MEX.SEND_BCC_WITH_SMIME=N

The default value of both parameters is Y, valid values are N or Y.

DOCI

D-21

-328

5, 2

4 M

ay 2

017


Version: 1.0

If an export is carried out to a CC address by means of export.MEX.SEND_CC_WITH_SMIME=N, then the e-mail is duplicated before the encryption/signing. After the dispatch to the TO address, the unencrypted e-mail is sent to the CC address but with the respective FROM/TO/CC/BCC addresses in the e-mail headers. The same logic is also applied to the BCC dispatch without S/MIME.

Notes:

- If a valid certificate exists for the CC/BCC address, then e-mails to this address are encrypted even if export.MEX.SEND_CC_WITH_SMIME=N, export.MEX.SEND_BCC_WITH_SMIME=N is defined because then the recipient can actually decrypt the content.

- If the parameters export.MEX.SEND_CC_WITH_SMIME=N, export.MEX.SEND_BCC_WITH_SMIME=N are not set and there is no certificate for the CC/BCC address, then the CC/BCC address receives the e-mail encrypted for the TO address. Thus, this e-mail is relatively useless for the CC/BCC address.

- This logic is also applied to addresses stored in the KomA via the Config.properties with the settings export.MEX.BCC, export.MEX.CC.

Incoming Checks According to the BDEW Specifications

By default, there is currently no strict check against the BDEW specifications in order for the market communication not to be stopped during the changeover. The following Config.properties entry results from this: crypto.SMIME.BDEW_CHECK

The following values are supported:

- NO_CHECK (default setting) - SOFT

Errors according to the BDEW specifications are shown as warnings - STRICT

Terminates the import with an error in case of a breach of the BDEW specifications

The following checks are performed during the import of an e-mail:

- Content encryption – check for the use of AES-128 CBC/AES-192 CBC - Key encryption – check for RSAES_OAEP [only from 1 January 2018!] - Signature – check for RSASSA_PSS [only from 1 January 2018!] - Signature – check for hash function SHA256 or SHA512

DOCI

D-21

-328

5, 2

4 M

ay 2

017


Version: 1.0

Problems/Solutions

In this chapter, some errors/error messages and their possible solutions are described.

key invalid in message.: Illegal key size: java.security.InvalidKeyException

Due to security reasons, the Java Cryptography Extension (JCE) Unlimited Strength Policy Files are required. These files are included in the JRE/JDK with great restrictions. If the keys are too long, then this error message occurs. The Java version must be patched in order for the policy files with Unlimited Strength not to make any restrictions to the cryptographic strength. The error “Illegal key size” indicates the missing Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files 8 in the Java version used. The current Java version can be obtained from Oracle. On 18 October 2016 the link was as follows: http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html The ZIP file must be downloaded:

Figure 6: Download of the JCE Policy Files

This ZIP file contains two JAR files (local_policy.jar, US_export_policy.jar) that must now be copied over the existing ones. The default path for the JCE Jurisdiction Policy JAR files is: <java-home>/lib/security [Unix] <java-home>\lib\security [Windows] The exchange of the two JAR files is also described in detail in the README.txt.

http://www.oracle.com/technetwork/java/javase/downloads/index.html

http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html

DOCI

D-21

-328

5, 2

4 M

ay 2

017


Version: 1.0

Figure 7: Exchange of the JCE Policy Files under Windows (1)

If Java was installed in the path c:\java\jre1.8.0_102\, then the two files under lib\security must be exchanged.

Figure 8: Exchange of the JCE Policy Files under Windows (2)

Newly Uploaded Certificates/Private Keys Are Not Recognized

A cache for certificates and private keys is used internally. Due to the architecture of the KomA, the cache is only of central importance to the Comimport (the data dispatch is periodically stopped/started and always reloads data this way). The cache only becomes effective when at least one private key or one certificate is in use under a specific e-mail address. The caching time for private keys and (existing) certificates is 12 hours. Certificates that are not present in the system are cached for 10 minutes (i.e. the information that a certificate with serial number x and issuer y does not exist is saved). This makes it possible to import missing certificates without having to restart the Comimport job. Thus, if (for whatever reason) changes of keys must take effect immediately, then the Comimport process must be restarted after the maintenance of the keys/certificates.

Therefore it is advisable to import the keys/certificates into the system immediately upon receipt!

Errors Concerning the Signature (“The message contents may have been altered.”)

If signature errors occur during the export (e.g. in Outlook), a possible cause can be the setting concerning Content-Transfer-Encoding.

Figure 9: Signature Error Message in Outlook

DOCI

D-21

-328

5, 2

4 M

ay 2

017


Version: 1.0

The setting is controlled in the Config.properties file by means of export.MEX.TextTransferEncoding. The default value was set to quoted-printable with eCount- 00072477. With regard to S/MIME, export.MEX.TextTransferEncoding = quoted-printable is the only reasonable (problem-free) setting!

Signature errors during the import can also be related to a problem concerning Content-Transfer-Encoding. Thus, for example, a market partner received e-mails, some of which encountered an error and others not.

Excerpt from the e-mail (signature OK): Content-Transfer-Encoding: quoted-printable Sehr geehrte Damen und Herren,… Mit freundlichen Grüßen Excerpt from the e-mail of the market partner (signature not OK): Content-Transfer-Encoding: quoted-printable Sehr geehrte Damen und Herren, … Mit freundlichen Gr|_en The umlauts were garbled during the transport, therefore the hash of the signature does no longer match. However, the main problem here resides in the creation of the e-mail! The e-mail protocol is pretty old and basically only provides for the US-ASCII character set. If quoted-printable is used, the characters not corresponding to US-ASCII are converted into the hexadecimal notation, which the sender did not do here. Consequently, this led to the falsification of the e-mail and thus to the signature error.

configuration on the koma - robotron

Documents