Merge changes I816c59e3,I99e55519

[oom/platform/cert-service.git] / README.md

diff --git a/README.md b/README.md
index 0f4531f..82654bf 100644 (file)
--- a/README.md
+++ b/README.md
@@ -9,7 +9,7 @@ More information about the project and all its functionalities you can find unde
   
 Project consists of four submodules:
 1. oom-certservice-api
-2. oom-certservice-client
+2. *deprecated (no longer built)* oom-certservice-client
 3. oom-certservice-post-processor
 4. oom-certservice-k8s-external-provider
 
@@ -41,8 +41,8 @@ Then execute following command from certs(!) directory:
 ```
 
 ### Running Docker containers from docker-compose with EJBCA
-Docker-compose uses a local image of certservice-api and make run-client uses a local image of certservice-client
-Build docker images locally before running docker compose command.
+Docker-compose uses a local image of certservice-api and make run-client uses a released image of certservice-client
+Build certservice-api docker image locally before running docker compose command.
 ```
 1. Build local images
 make build
@@ -54,6 +54,95 @@ make run-client
 make stop-backend
 ```
 
+### Generating certificates via REST Api
+#### Requirements
+* OpenSSL
+* cURL
+* jq (for parseCertServiceResponse.sh script)
+#### Initialization Request
+1. Create Certificate Signing Request and Private Key
+```
+openssl req -new -newkey rsa:2048 -nodes -keyout ./compose-resources/certs-from-curl/ir.key \
+           -out ./compose-resources/certs-from-curl/ir.csr \
+           -subj "/C=US/ST=California/L=San-Francisco/O=ONAP/OU=Linux-Foundation/CN=onap.org" \
+           -addext "subjectAltName = DNS:test.onap.org"
+```
+2. Send Initialization Request
+```
+curl -s https://localhost:8443/v1/certificate/RA -H "PK: $(cat ./compose-resources/certs-from-curl/ir.key | base64 | tr -d \\n)" \
+        -H "CSR: $(cat ./compose-resources/certs-from-curl/ir.csr | base64 | tr -d \\n)" \
+        --cert ./certs/cmpv2Issuer-cert.pem \
+        --key ./certs/cmpv2Issuer-key.pem \
+        --cacert ./certs/cacert.pem
+```
+to parse the response pipe the output to `parseCertserviceResponse.sh` script, providing prefix as argument
+```
+curl -sN https://localhost:8443/v1/certificate/RA -H "PK: $(cat ./compose-resources/certs-from-curl/ir.key | base64 | tr -d \\n)" \
+        -H "CSR: $(cat ./compose-resources/certs-from-curl/ir.csr | base64 | tr -d \\n)" \
+        --cert ./certs/cmpv2Issuer-cert.pem \
+        --key ./certs/cmpv2Issuer-key.pem \
+        --cacert ./certs/cacert.pem | `pwd`/parseCertServiceResponse.sh "ir"
+```
+
+#### Update Request
+1. Create Certificate Signing Request and Private Key - same as for Initialization Request.
+When CSR data (like Subject and SANS) is unchanged, Key Update Request will be performed.
+Otherwise Certification Request will be performed. 
+Example for KUR:
+```
+openssl req -new -newkey rsa:2048 -nodes -keyout ./compose-resources/certs-from-curl/kur.key \
+-out ./compose-resources/certs-from-curl/kur.csr \
+-subj "/C=US/ST=California/L=San-Francisco/O=ONAP/OU=Linux-Foundation/CN=onap.org" \
+-addext "subjectAltName = DNS:test.onap.org"
+```
+Example for CR:
+```
+openssl req -new -newkey rsa:2048 -nodes -keyout ./compose-resources/certs-from-curl/cr.key \
+-out ./compose-resources/certs-from-curl/cr.csr \
+-subj "/C=US/ST=California/L=San-Francisco/O=ONAP/OU=Linux-Foundation/CN=new-onap.org" \
+-addext "subjectAltName = DNS:test.onap.org"
+```
+2. Send Update Request.
+Example for KUR:
+```
+curl -sN https://localhost:8443/v1/certificate-update/RA -H "PK: $(cat ./compose-resources/certs-from-curl/kur.key | base64 | tr -d \\n)" \
+           -H "CSR: $(cat ./compose-resources/certs-from-curl/kur.csr | base64 | tr -d \\n)" \
+           -H "OLDPK: $(cat ./compose-resources/certs-from-curl/ir.key | base64 | tr -d \\n)" \
+           -H "OLDCERT: $(cat ./compose-resources/certs-from-curl/ir-cert.pem | base64 | tr -d \\n)" \
+           --cert ./certs/cmpv2Issuer-cert.pem \
+           --key ./certs/cmpv2Issuer-key.pem \
+           --cacert ./certs/cacert.pem | `pwd`/parseCertServiceResponse.sh "kur"
+```
+Example CR:
+```
+curl -sN https://localhost:8443/v1/certificate-update/RA -H "PK: $$(cat ./compose-resources/certs-from-curl/cr.key | base64 | tr -d \\n)" \
+           -H "CSR: $$(cat ./compose-resources/certs-from-curl/cr.csr | base64 | tr -d \\n)" \
+           -H "OLD_PK: $$(cat ./compose-resources/certs-from-curl/ir.key | base64 | tr -d \\n)" \
+           -H "OLD_CERT: $$(cat ./compose-resources/certs-from-curl/ir-cert.pem | base64 | tr -d \\n)" \
+           --cert ./certs/cmpv2Issuer-cert.pem \
+           --key ./certs/cmpv2Issuer-key.pem \
+           --cacert ./certs/cacert.pem | `pwd`/parseCertServiceResponse.sh "cr"
+```
+
+#### Using makefile
+1. Perform Initialization Request:
+```
+make send-initialization-request
+```
+2. Perform Update Request:
+```
+make send-key-update-request
+```
+or:
+```
+make send-certification-request
+```
+
+To send request to custom CA use ```make <request> -e CA_NAME=<custom CA>``` e.g: 
+```
+make send-initialization-request -e CA_NAME=CUSTOM_CA
+```
+
 ### OOM CertService CSITs
 #### CSIT repository
 ```