Authentication

After enabling TLS, clients can verify connecting servers and keep messages encrypted, but servers can not verify clients, so authentication is designed to provide a mechanism that servers can authenticate trusted clients.

Authentication provides another feature that gives a client a role name, then hstream will be based on the role to implement authorization.

hstream only support TLS authentication, which is an extension of default TLS, to enable TLS authentication, you need to create the corresponding key and certificate for a role, then give them to trusted clients, clients use the key and certificate(binding to a role) to connect to servers.

Create a trusted role

Generate a key:

openssl genrsa -out role01.key.pem 2048

Convert it to PKCS 8 format(Java client require that):

openssl pkcs8 -topk8 -inform PEM -outform PEM \
      -in role01.key.pem -out role01.key-pk8.pem -nocrypt

Generate the certificate request(Common Name is the role name):

openssl req -config openssl.cnf \
      -key role01.key.pem -new -sha256 -out role01.csr.pem

Generate the signed certificate:

openssl ca -config openssl.cnf -extensions usr_cert \
      -days 1000 -notext -md sha256 \
      -in role01.csr.pem -out signed.role01.cert.pem

Configuration

For hstream server, you can set tls-ca-path to enable TLS authentication, e.g.:

# TLS options
#
# enable tls, which requires tls-key-path and tls-cert-path options
enable-tls: true
#
# key file path for tls, can be generated by openssl
tls-key-path: /path/to/the/server.key.pem
#
# the signed certificate by CA for the key(tls-key-path)
tls-cert-path: /path/to/the/signed.server.cert.pem
#
# optional for tls, if tls-ca-path is not empty, then enable TLS authentication,
# in the handshake phase,
# the server will request and verify the client's certificate.
tls-ca-path: /path/to/the/ca.cert.pem

For Java client:

HStreamClient.builder()
  .serviceUrl(serviceUrl)
  // enable tls
  .enableTLS()
  .tlsCaPath("/path/to/ca.pem")

  // for authentication
  .enableTlsAuthentication()
  .tlsKeyPath("path/to/role01.key-pk8.pem")
  .tlsCertPath("path/to/signed.role01.cert.pem")

  .build()