JGroupsENCRYPT

Version 9

    Encrypting entire messages (including headers)

     

    A detailed description of ENCRYPT is found in the JGroups source (JGroups/doc/ENCRYPT.html).

     

    Encryption by default only encrypts the message body, but doesn't encrypt message headers.

    To encrypt the entire message (including all headers, plus destination and source addresses), the property  has to be set to true. Also, ENCRYPT has to be below any protocols whose headers we want to encrypt, e.g.

    <config>
        <UDP mcast_recv_buf_size="64000" mcast_send_buf_size="32000" mcast_port="45566" ucast_recv_buf_size="64000"
            use_incoming_packet_handler="false" mcast_addr="228.8.8.8" use_outgoing_packet_handler="false"
            loopback="true" ucast_send_buf_size="32000" ip_ttl="32"></UDP>
        <PING timeout="2000" num_initial_members="3"></PING>
        <MERGE2 max_interval="10000" min_interval="5000"></MERGE2>
        <FD timeout="2000" max_tries="3" shun="true"></FD>
        <VERIFY_SUSPECT timeout="1500"></VERIFY_SUSPECT>
        <ENCRYPT encrypt_entire_message="true"  sym_init="128" sym_algorithm="AES/ECB/PKCS5Padding" asym_init="512" asym_algorithm="RSA"></ENCRYPT>
        <pbcast.NAKACK max_xmit_size="8192" gc_lag="50" retransmit_timeout="600,1200,2400,4800"></pbcast>
        <UNICAST timeout="1200,2400,3600"></UNICAST>
        <pbcast.STABLE stability_delay="1000" desired_avg_gossip="20000" max_bytes="0"></pbcast>
        <FRAG frag_size="8192" down_thread="false" up_thread="false"></FRAG>
    
        <pbcast.GMS print_local_addr="true" join_timeout="3000" join_retry_timeout="2000" shun="true"></pbcast>
    </config>
    

     

    Note that ENCRYPT sits below NAKACK and UNICAST, so the sequence numbers for these 2 protocols will be encrypted. Had ENCRYPT been placed below UNICAST but above NAKACK, then only UNICAST's headers (including sequence numbers) would have been encrypted, but not NAKACKs.

    Note that it doesn't make too much sense to place ENCRYPT even lower in the stack, because then almost all traffic (eve merge or discovery traffic) will be encrypted, which may be somewhat of a performance drag.

     

    When we encrypt an entire message, we have to marshal the message into a byte{FOOTNOTE DEF  } buffer first and then encrypt it. This entails marshalling and copying of the byte{FOOTNOTE DEF  } buffer, which is not so good performance wise...

    Configuration Parameters


    NameDescription
    aliasAlias used for recovering the key. Change the default
    asymAlgorithmCipher engine transformation for asymmetric algorithm. Default is RSA
    asymInitInitial public/private key length. Default is 512
    asymProviderCryptographic Service Provider. Default is Bouncy Castle Provider
    encrypt_entire_message
    idGive the protocol a different ID if needed so we can have multiple instances of it in the same stack
    keyPasswordPassword for recovering the key. Change the default
    keyStoreNameFile on classpath that contains keystore repository
    levelSets the logger level (see javadocs)
    nameGive the protocol a different name if needed so we can have multiple instances of it in the same stack
    statsDetermines whether to collect statistics (and expose them via JMX). Default is true
    storePasswordPassword used to check the integrity/unlock the keystore. Change the default
    symAlgorithmCipher engine transformation for symmetric algorithm. Default is AES
    symInitInitial key length for matching symmetric algorithm. Default is 128

     

     

    See also Protocol Configuration Common Parameters.

     

     

    Using a key store

     

    ENCRYPT uses store type JCEKS (for details between JKS and JCEKS see here), however keytool uses JKS, therefore a keystore generated with keytool won't be accessible.

    To generate a keystore compatible with JCEKS, use the following command line options to keytool:

     

    keytool -genseckey -alias myKey -keypass changeit -storepass changeit  -keyalg Blowfish -keysize 56 -keystore defaultStore.keystore -storetype  JCEKS

     

    ENCRYPT could then be configured as follows:

     

    <ENCRYPT key_store_name="defaultStore.keystore" store_password="changeit" alias="myKey"/>

     

    Note that defaultStore.keystore will have to be found in the claspath.

     

    Thanks to Marcus Moyses, Anil Saldhana and Alejandro Revilla for pointing me to the right command !