From 00f0decd1b0aca7142a1e81c0bc91be0817abac2 Mon Sep 17 00:00:00 2001
From: Pushkar Niranjan Kulkarni <pushkar.kulkarni@canonical.com>
Date: Fri, 4 Oct 2024 19:29:28 +0530
Subject: [PATCH] Update README.md

---
 README.md | 45 +++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 41 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 5cb28c2..d0c96ee 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,42 @@
-## Instructions
+### Introduction
+The OpenSSL FIPS Java project is a Java FIPS security provider module layered on top of the [OpenSSL library and its FIPS module](https://docs.openssl.org/3.0/man7/OSSL_PROVIDER-FIPS/). Complying with the [Java Cryptography Architecture](https://docs.oracle.com/javase/8/docs/technotes/guides/security/crypto/CryptoSpec.html), it implements the Java security SPI classes for security functions including [Deterministic Random Bit Generators](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/security/SecureRandomSpi.html), [Ciphers](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/javax/crypto/CipherSpi.html), [Key Agreements](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/javax/crypto/KeyAgreementSpi.html), [Key Derivations](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/javax/crypto/SecretKeyFactorySpi.html), [Key Encapsulation](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/javax/crypto/KEMSpi.html), [Message Digests](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/security/MessageDigest.html#:~:text=Message%20digests%20are%20secure%20one,called%20to%20reset%20the%20digest.), [Message Authentication Codes](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/javax/crypto/Mac.html) and [Signatures](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/security/Signature.html?source=%3Aso%3Atw%3Aor%3Aawr%3Aosec%3A%2C%3Aso%3Atw%3Aor%3Aawr%3Aosec%3A).
 
-1. Install and configure openssl in the FIPS mode as detailed [here](https://github.com/openssl/openssl/blob/master/README-FIPS.md)
-2. `git clone https://github.com/canonical/openssl-fips-jni-wrapper && cd openssl-fips-jni-wrapper`
-3. `make test`
+Under the covers, OpenSSL FIPS Java is quite tightly coupled with OpenSSL through the [Java Native Interface](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/security/Signature.html?source=%3Aso%3Atw%3Aor%3Aawr%3Aosec%3A%2C%3Aso%3Atw%3Aor%3Aawr%3Aosec%3A) and the [OpenSSL EVP API](https://docs.openssl.org/3.3/man7/evp/). Only FIPS-approved algorithms, offered by the OpenSSL FIPS module are registered with this provider. The binaries produced from this source should be generally considered FIPS-compliant if the underlying OpenSSL module is FIPS 140-2/140-3 certified.
+
+### Structure of the source code
+| Directory | Functionality |
+|-----------|---------------|
+| src/main/java/com/canonical/openssl | Java classes, including SPI implementations |
+| src/main/native/c | C code that invokes OpenSSL EVP API, JNI code |
+| src/main/native/include | JNI headers and library header files |
+| src/test | C and Java tests | 
+
+### Instructions to build and test the provider
+#### Install and configure OpenSSL FIPS
+You should skip this step if you have OpenSSL and OpenSSL FIPS module installed. Here are the commands for Ubuntu/Debian installations:
+```
+git clone https://github.com/openssl/openssl && cd openssl
+git checkout openssl-3.0.2
+sudo apt update && sudo apt install build-essential -y
+./Configure enable-fips && make && sudo make install && sudo make install_fips
+```
+Create a FIPS module configuration file which will be loaded by the provider. Please keep this file under `/usr/local/ssl` only.
+```
+sudo mkdir -p /usr/local/ssl
+sudo openssl fipsinstall -out /usr/local/ssl/fipsmodule.cnf -module /usr/local/lib64/ossl-modules/fips.so
+```
+#### Install OpenJDK v21
+This project needs OpenJDK 21 or a later release of it. On Ubuntu/Debian systems, you may install the OpenJDK from the archive.
+```
+sudo apt update
+sudo apt install openjdk-21-jdk-headless
+```
+#### Clone the project, build and test
+This set of commands may be used on Ubuntu/Debian systems.
+```
+git clone https://github.com/canonical/openssl-fips-java
+cd openssl-fips-java
+export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64/
+mvn -B package --file pom.xml
+```
+Refer to this [GitHub Action](https://github.com/canonical/openssl-fips-java/blob/main/.github/workflows/maven.yml) for more details.