Cryptography

This library helps to encrypt / decrypt and sign and verify your data. It supports both, point-to-point-encryption and end-to-end-encryption. This is not a introduction to cryptography.

• Point-to-point security
• End-to-end security
• Setup security environment

Point-to-point security

An ASAP session is initiated when ASAP peers encounter each other. ASAP protocol data units are transmitted during that session from one peer to another. We call it a point-to-point connection. PDUs are not encrypted or signed per default. Maybe it is not even necessary. It depends on the used protocol. If you find you protocol safe enough, you can avoid any additional security settings.

Switching signing and encryption on is simple:

ASAPPeer alicePeer = ... // was created somewhere 
alicePeer.getASAPCommunicationControl().setSendEncryptedMessages(true);
alicePeer.getASAPCommunicationControl().setSendSignedMessages(true);

There are four setting. You can choose to send signed and/or encrypted PDUs. You need access the ASAPCommunicationSetting set encryption and or signing on or off. Both are switched on in our example.

Any PDU issued by alicePeer would now be signed and encrypted. Signing works anytime if the security environment had been setup accordingly. The PDU would be signed with Alice’ private key. This signature is attached to the ASAP message.

Encryption can fail if alicePeer has no public key of the recipient. That is the peer with which Alice has running ASAP session. Nothing would happens in that case. Alice would not send any data.

Peers can define that they only accept signed or encrypted PDUs.

alicePeer.getASAPEnginePermissionSettings().setReceivedMessagesMustBeEncrypted(true);
alicePeer.getASAPEnginePermissionSettings().setReceivedMessagesMustBeSigned(true);

Encryption works anytime if the security environment had been setup accordingly and sender used the valid public key of Alice.

alicePeer would only process PDUs which encrypted and the signature can be verified. Verifying can fail for two reasons: alicePeer has a public key of the encountered peer but cannot verify the signature. In that case, the sender cheats about its identity or alicePeer has a wrong public key. Second reason is a missing public key on alicePeer side. Either way, the PDU is not processed.

End-to-end security

ASAP is a routing protocol. Messages can be send over an arbitrary number of peers (we call those exchanges hops) to its recipient. There are lot of good reasons to ensure end-to-end-security: Sender encrypts data for a dedicated recipient. Peer in between would transfer messages but without being able to read the content.

End-to-end-security is about your application data - the content in your ASAP message. Point-to-point-security is about signing the whole PDU. Quite often, it is also a good idea to sign a message. If you feel it useful keep reading.

BasicCryptoParameters

We defined an interface BasicCryptoParameters. Here is a part of the interface:

public interface BasicCryptoParameters {
    PrivateKey getPrivateKey() throws ASAPSecurityException; // get peers' private key
    PublicKey getPublicKey(CharSequence subjectID) throws ASAPSecurityException; // get public key of a peer
    PublicKey getPublicKey() throws ASAPSecurityException; // get peers' public key
}

You don't need to call those message yourself. You just need a refernce to an object implementing this interface, see Setup security environment.

More important, there is a class ASAPCryptoAlgorithms which offers very convient ways to do all that nice crypto stuff we need. That's what we discuss in the next sub sections.

Signing

You application is made up of peers who exchanges messages. Your message structure is opaque to ASAP. They are just an array of bytes. Signing is simple:

BasicCryptoParameters basicCryptoParameters; // see above
ASAPEngine yourEngine = ... // engine of your app
CharSequence yourUri = ... // optional uri describing your message in your app
byte yourMessage = ... // your application message
byte[] signature = ASAPCryptoAlgorithms.sign(message, basicCryptoParameters); // sign your message

// produce a message with attaced signature
ByteArrayOutputStream baos = new ByteArrayOutputStream();
ASAPSerialization.writeByteArray(message, baos); // message has three parts: content, sender, receiver
// append signature
ASAPSerialization.writeByteArray(signature, baos);
// attach signature to message
byte yourSignedMessage = baos.toByteArray();

yourEngine.add(yourURI, yourSignedMessage);

The first to lines should look familiar

Encrypting

Setup security environment