- Added documentation with an example of FIPS compliant communication with Kafka cluster.

- Fixed wrong error code parameter name in KafkaError.

We tested FIPS compliance for the client using OpenSSL 3.0. To use the client in FIPS-compliant mode, use OpenSSL 3.0. Older versions of OpenSSL have not been verified (although they may work).

If you install this client through prebuilt wheels using `pip install confluent_kafka`, OpenSSL 3.0 is already statically linked with the librdkafka shared library. To enable this client to communicate with the Kafka cluster using the OpenSSL FIPS provider and FIPS-approved algorithms, you must enable the FIPS provider. You can find steps to enable the FIPS provider in section [Enabling FIPS provider](#enabling-fips-provider).

You should follow the same above steps if you install this client from the source using `pip install confluent_kafka --no-binary :all:` with prebuilt librdkafka in which OpenSSL is statically linked

When you build the librdkafka from source, librdkafka dynamically links to the OpenSSL present in the system (if static linking is not used explicitly while building). If the installed OpenSSL is already working in FIPS mode, then you can directly jump to the section [Client configuration to enable FIPS provider](#client-configuration-to-enable-fips-provider) and enable `fips` provider. If you don't have OpenSSL working in FIPS mode, use the steps mentioned in the section [Enabling FIPS provider](#enabling-fips-provider) to make OpenSSL in your system FIPS compliant and then enable the `fips` provider. Once you have OpenSSL working in FIPS mode and the `fips` provider enabled, librdkafka and python client will use FIPS approved algorithms for the communication between client and Kafka Cluster using the producer, consumer or admin client.

To enable the FIPS provider, you must have the FIPS module available on your system, plug the module into OpenSSL, and then configure OpenSSL to use the module.

You can plug the FIPS provider into OpenSSL two ways: 1) put the module in the default module folder of OpenSSL or 2) point to the module with the environment variable, `OPENSSL_MODULES`. For example: `OPENSSL_MODULES="/path/to/fips/module/lib/folder/`

You configure OpenSSL to use the FIPS provider using the FIPS configuration in OpenSSL config. You can 1) modify the default configuration file to include FIPS related config or 2) create a new configuration file and point to it using the environment variable,`OPENSSL_CONF`. For example `OPENSSL_CONF="/path/to/fips/enabled/openssl/config/openssl.cnf` For an example of OpenSSL config, see below.

**NOTE:** You need to specify both `OPENSSL_MODULES` and `OPENSSL_CONF` environment variable when installing the client from pre-built wheels or when OpenSSL is statically linked to librdkafka.

You can find steps to generate the FIPS provider module in the [README-FIPS doc](https://github.com/openssl/openssl/blob/openssl-3.0.8/README-FIPS.md)

In short, you need to perform the following steps:

1) Clone OpenSSL from [OpenSSL Github Repo](https://github.com/openssl/openssl)

2) Checkout the correct version. (v3.0.8 is the current FIPS compliant version for OpenSSL 3.0 at the time of writing this doc.)

3) Run `./Configure enable-fips`

4) Run `make install_fips`

After last step, two files are generated.

* FIPS module (`fips.dylib` in Mac, `fips.so` in Linux and `fips.dll` in Windows)

* FIPS config (`fipsmodule.cnf`) file will be generated. Which needs to be used with OpenSSL.

As mentioned earlier, you can dynamically plug the FIPS module built above into OpenSSL by putting the FIPS module into the default OpenSSL module folder (only when installing from source). For default locations of OpenSSL on various operating systems, see the SSL section of the [Introduction to librdkafka - the Apache Kafka C/C++ client library](https://github.com/confluentinc/librdkafka/blob/master/INTRODUCTION.md#ssl). It should look something like `...lib/ossl-modules/`.

You can also point to this module with the environment variable `OPENSSL_MODULES`. For example, `OPENSSL_MODULES="/path/to/fips/module/lib/folder/`

To enable FIPS in OpenSSL, you must include `fipsmodule.cnf` in the file, `openssl.cnf`. The `fipsmodule.cnf` file includes `fips_sect` which OpenSSL requires to enable FIPS. See the example below.

Some of the algorithms might have different implementation in FIPS or other providers. If you load two different providers like default and fips, any implementation could be used. To make sure you fetch only FIPS compliant version of the algorithm, use `fips=yes` default property in config file.

OpenSSL config should look something like after applying the above changes.

OpenSSL requires some non-crypto algorithms as well. These algorithms are not included in the FIPS provider and you need to use the `base` provider in conjunction with the `fips` provider. Base provider comes with OpenSSL by default. You must enable `base` provider in the client configuration.

To make client (consumer, producer or admin client) FIPS compliant, you must enable only `fips` and `base` provider in the client using the `ssl.providers` configuration property i.e `'ssl.providers': 'fips,base'`.

This part is not tested for FIPS compliance right now.

* [Generating FIPS module and config file](https://github.com/openssl/openssl/blob/openssl-3.0.8/README-FIPS.md)

* [How to use FIPS Module](https://www.openssl.org/docs/man3.0/man7/fips_module.html)

* [librdkafka SSL Information](https://github.com/confluentinc/librdkafka/blob/master/INTRODUCTION.md#ssl)

Use `generate_certificates.sh` in secrets folder to generate the certificates.

Up the server using `docker-compose up`.

Use example producer and consumer to test the FIPS compliance. Note that you might need to point to FIPS module and FIPS enabled OpenSSL 3.0 config using environment variables like ` OPENSSL_CONF="/path/to/fips/enabled/openssl/config/openssl.cnf" OPENSSL_MODULES="/path/to/fips/module/lib/folder/" ./examples/fips/fips_producer.py localhost:9092 test-topic`

Uncomment `KAFKA_SSL_CIPHER.SUITES: TLS_CHACHA20_POLY1305_SHA256` in `docker-compose.yml` to enable non FIPS compliant algorithm. Use this to verify that only FIPS compliant algorithms are used.

version: "3.9"

services:

zookeeper:

hostname: zookeeper

container_name: zookeeper

restart: always

image: confluentinc/cp-zookeeper:7.4.0

environment:

ZOOKEEPER_CLIENT_PORT: 2181

KAFKA_OPTS: -Djava.security.auth.login.config=/etc/kafka/secrets/zookeeper_jaas.conf

-Dzookeeper.authProvider.1=org.apache.zookeeper.server.auth.SASLAuthenticationProvider

-DrequireClientAuthScheme=sasl

-Dzookeeper.allowSaslFailedClients=false

volumes:

- ./secrets:/etc/kafka/secrets

broker:

image: confluentinc/cp-kafka:7.4.0

hostname: broker

container_name: broker

restart: always

ports:

- 29092:29092

- 9092:9092

volumes:

- ./secrets:/etc/kafka/secrets

environment:

KAFKA_ZOOKEEPER_CONNECT: 'zookeeper:2181'

KAFKA_INTER_BROKER_LISTENER_NAME: SASL_SSL

KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: SASL_SSL:SASL_SSL,SASL_SSL_HOST:SASL_SSL

KAFKA_ADVERTISED_LISTENERS: SASL_SSL://localhost:9092,SASL_SSL_HOST://broker:29092

KAFKA_LISTENERS: SASL_SSL://:9092,SASL_SSL_HOST://:29092

KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1

CONFLUENT_METRICS_REPORTER_SECURITY_PROTOCOL: SASL_SSL

CONFLUENT_METRICS_REPORTER_SASL_JAAS_CONFIG: "org.apache.kafka.common.security.plain.PlainLoginModule required \

KAFKA_SASL_ENABLED_MECHANISMS: PLAIN

KAFKA_SASL_MECHANISM_INTER_BROKER_PROTOCOL: PLAIN

KAFKA_SSL_KEYSTORE_FILENAME: server.keystore.jks

KAFKA_SSL_KEYSTORE_CREDENTIALS: creds

KAFKA_SSL_KEY_CREDENTIALS: creds

KAFKA_SSL_TRUSTSTORE_FILENAME: server.truststore.jks

KAFKA_SSL_TRUSTSTORE_CREDENTIALS: creds

# KAFKA_SSL_CIPHER.SUITES: TLS_CHACHA20_POLY1305_SHA256 # FIPS non compliant algo.

# enables 2-way authentication

KAFKA_SSL_CLIENT_AUTH: "required"

KAFKA_SSL_ENDPOINT_IDENTIFICATION_ALGORITHM: ""

KAFKA_OPTS: -Djava.security.auth.login.config=/etc/kafka/secrets/broker_jaas.conf

KAFKA_SSL_PRINCIPAL_MAPPING_RULES: RULE:^CN=(.*?),OU=TEST.*$$/$$1/,DEFAULT

KafkaServer {

org.apache.kafka.common.security.plain.PlainLoginModule required

username="broker"

password="broker-secret"

user_broker="broker-secret"

user_client="client-secret"

user_schema-registry="schema-registry-secret"

user_restproxy="restproxy-secret"

user_clientrestproxy="clientrestproxy-secret"

user_badclient="badclient-secret";

};

Client {

org.apache.zookeeper.server.auth.DigestLoginModule required

username="kafka"

password="kafkasecret";

};

set -e

server_hostname=${server_hostname:-localhost}

client_hostname=${client_hostname:-localhost}

cert_password=${cert_password:-111111}

openssl=${openssl:-openssl}

keytool=${keytool:-keytool}

echo openssl version

$openssl version

echo creates server keystore

$keytool -keystore server.keystore.jks -storepass $cert_password -alias ${server_hostname} -validity 365 -genkey -keyalg RSA -dname "cn=$server_hostname"

echo creates root CA

$openssl req -nodes -new -x509 -keyout ca-root.key -out ca-root.crt -days 365 -subj "/C=US/ST=CA/L=MV/O=CFLT/CN=CFLT"

echo creates CSR

$keytool -keystore server.keystore.jks -alias ${server_hostname} -certreq -file ${server_hostname}_server.csr -storepass $cert_password

echo sign CSR

$openssl x509 -req -CA ca-root.crt -CAkey ca-root.key -in ${server_hostname}_server.csr -out ${server_hostname}_server.crt -days 365 -CAcreateserial

echo import root CA

$keytool -keystore server.keystore.jks -alias CARoot -import -noprompt -file ca-root.crt -storepass $cert_password

echo import server certificate

$keytool -keystore server.keystore.jks -alias ${server_hostname} -import -file ${server_hostname}_server.crt -storepass $cert_password

echo create client CSR

$openssl req -newkey rsa:2048 -nodes -keyout ${client_hostname}_client.key -out ${client_hostname}_client.csr -subj "/C=US/ST=CA/L=MV/O=CFLT/CN=CFLT" -passin pass:$cert_password

echo sign client CSR

$openssl x509 -req -CA ca-root.crt -CAkey ca-root.key -in ${client_hostname}_client.csr -out ${client_hostname}_client.crt -days 365 -CAcreateserial

echo create client keystore

$openssl pkcs12 -export -in ${client_hostname}_client.crt -inkey ${client_hostname}_client.key -name ${client_hostname} -out client.keystore.p12 -passin pass:$cert_password \

-passout pass:$cert_password

echo create truststore

$keytool -noprompt -keystore server.truststore.jks -alias CARoot -import -file ca-root.crt -storepass $cert_password

echo create creds file

echo "$cert_password" > ./creds

echo verify with: openssl pkcs12 -info -nodes -in client.keystore.p12

Server {

org.apache.zookeeper.server.auth.DigestLoginModule required

user_super="adminsecret"

user_kafka="kafkasecret";

};

from confluent_kafka import Consumer, KafkaException

import sys

def print_usage_and_exit(program_name):

sys.stderr.write('Usage: %s [options..] <bootstrap-brokers> <group> <topic1> <topic2> ..\n' % program_name)

sys.exit(1)

if __name__ == '__main__':

if len(sys.argv) < 4:

print_usage_and_exit(sys.argv[0])

broker = sys.argv[1]

group = sys.argv[2]

topics = sys.argv[3:]

conf = {'bootstrap.servers': broker,

'group.id': group,

'auto.offset.reset': 'earliest',

'security.protocol': 'SASL_SSL',

'sasl.mechanism': 'PLAIN',

'sasl.username': 'broker',

'sasl.password': 'broker-secret',

# pkc12 keystores are not FIPS compliant and hence you will need to use

# path to key and certificate separately in FIPS mode

# 'ssl.keystore.location': './docker/secrets/client.keystore.p12',

# 'ssl.keystore.password': '111111',

'ssl.key.location': './docker/secrets/localhost_client.key',

'ssl.key.password': '111111',

'ssl.certificate.location': './docker/secrets/localhost_client.crt',

'ssl.ca.location': './docker/secrets/ca-root.crt',

'ssl.providers': 'fips,base'

}

# Create Consumer instance

c = Consumer(conf)

def print_assignment(consumer, partitions):

print('Assignment:', partitions)

# Subscribe to topics

c.subscribe(topics, on_assign=print_assignment)

# Read messages from Kafka, print to stdout

try:

while True:

msg = c.poll(timeout=1.0)

if msg is None:

continue

if msg.error():

raise KafkaException(msg.error())

else:

# Proper message

sys.stderr.write('%% %s [%d] at offset %d with key %s:\n' %

(msg.topic(), msg.partition(), msg.offset(),

str(msg.key())))

print(msg.value())

except KeyboardInterrupt:

sys.stderr.write('%% Aborted by user\n')

finally:

# Close down consumer to commit final offsets.

c.close()

from confluent_kafka import Producer

import sys

if __name__ == '__main__':

if len(sys.argv) != 3:

sys.stderr.write('Usage: %s <bootstrap-brokers> <topic>\n' % sys.argv[0])

sys.exit(1)

broker = sys.argv[1]

topic = sys.argv[2]

# Producer configuration

# See https://github.com/confluentinc/librdkafka/blob/master/CONFIGURATION.md

conf = {'bootstrap.servers': broker,

'security.protocol': 'SASL_SSL',

'sasl.mechanism': 'PLAIN',

'sasl.username': 'broker',

'sasl.password': 'broker-secret',

# pkc12 keystores are not FIPS compliant and hence you will need to use

# path to key and certificate separately in FIPS mode

# 'ssl.keystore.location': './docker/secrets/client.keystore.p12',

# 'ssl.keystore.password': '111111',

'ssl.key.location': './docker/secrets/localhost_client.key',

'ssl.key.password': '111111',

'ssl.certificate.location': './docker/secrets/localhost_client.crt',

'ssl.ca.location': './docker/secrets/ca-root.crt',

'ssl.providers': 'fips,base'

}

# Create Producer instance

p = Producer(**conf)

# Optional per-message delivery callback (triggered by poll() or flush())

# when a message has been successfully delivered or permanently

# failed delivery (after retries).

def delivery_callback(err, msg):

if err:

sys.stderr.write('%% Message failed delivery: %s\n' % err)

else:

sys.stderr.write('%% Message delivered to %s [%d] @ %d\n' %

(msg.topic(), msg.partition(), msg.offset()))

# Read lines from stdin, produce each line to Kafka

for line in sys.stdin:

try:

# Produce line (without newline)

p.produce(topic, line.rstrip(), callback=delivery_callback)

except BufferError:

sys.stderr.write('%% Local producer queue is full (%d messages awaiting delivery): try again\n' %

len(p))

# Serve delivery callback queue.

# NOTE: Since produce() is an asynchronous API this poll() call

# will most likely not serve the delivery callback for the

# last produce()d message.

p.poll(0)

# Wait until all messages have been delivered

sys.stderr.write('%% Waiting for %d deliveries\n' % len(p))

p.flush()

" error (KafkaError): Error code indicating the type of error.\n"