SSL Mutual Authentication with Ballerina

Mutual SSL is a widely used certificate-based authentication used in client-server communication. The basic idea of mutual authentication is, both the client and server are assured of each other’s identity. Ballerina has ‘services’ comprising ‘resources’ bound to them. Resources are network accessible entry points. We can configure a service with annotations to bind into a related server connector with a resource.

I will take you through how we can configure a server from a ballerina service with enabled mutual ssl. For a mutual ssl connection, we need a keystore and a truststore. Keystore is basically used to store private keys in a password encrypted manner and truststore is used to store certificates of trusted parties. Truststore is there for verifying credentials and keystore is used for providing credentials to the requesting party.

As I mentioned earlier in a mutual ssl connection both client and server need to verify each other's identity. That means both parties should provide their keystore and truststore configurations in the connection process.

Let’s see how we can configure a mutual ssl enabled server from ballerina. Ballerina tools distribution which can be downloaded here comes with an existing keystore (ballerinaKeystore.p12)and a truststore (ballerinaTruststore.p12). I will be using them to in this example. You can have your own keystores and truststores as you wish.

Ballerina service for server connector

import ballerina/io;
import ballerina/http;

endpoint http:Listener echo {
    port:9095,
    secureSocket: {
        keyStore: {
            path: "${ballerina.home}/bre/security/ballerinaKeystore.p12",
            password: "ballerina"
        },
        trustStore: {
            path: "${ballerina.home}/bre/security/ballerinaTruststore.p12",
            password: "ballerina"
        }
    }
};

@http:ServiceConfig {
     endpoints:[echo],
     basePath:"/echo"
}

service<http:Service> helloWorld bind echo {

    @http:ResourceConfig {
        methods:["GET"],
        path:"/"
    }
    sayHello (endpoint conn, http:Request req) {
        http:Response res = new;
        res.setTextPayload("hello world");
        _ = conn -> respond( res);
        io:println("successful");
    }
}

As in the above example, we can give the configuration to create an https service. httpsPort should be defined in order to make this service a https one. Location of the keystore file and truststore file along with their passwords should be given. If you have a certificate password you can give that or else you can specify the same password used for keystore as given in the above example. Most importantly if you want to make this a mutual ssl connection you have to add the annotation sslVerifyClient:”require”.

For a successful ssl connection your client’s certificate should be imported to the server’s truststore and server’s certificate should be there in the client truststore.

For more information you can refer this ballerina by example. With the existing implementation a user can have different keystores and truststores for different services.