openhim-cert-updater v1.1.9
openhim-cert-updater
openhim-cert-updater
is an NPM package that handles informing both local and remote OpenHIM installations about ssl certificate updates/renewals.
Usage
With Package Installation
The package utilizes NVM to ensure that the script will be run in the appropriate nodejs environment. NVM is installed under the user openhim_cert_updater
and so commands running the script must be run as that user. E.g.:
- run updater check:
sudo su openhim_cert_updater bash -c 'sudo openhim-cert-updater'
- config file help:
sudo su openhim_cert_updater bash -c 'sudo openhim-cert-updater -c'
With Manual Installation
- after installing the application manually with the instructions below, run
sudo nodejs update_certificates.js
Overview
scripts
update_certificates.js
- This file runs the required updates for all specified ohim-core machines.
- This file utilizes javascript's
promise
feature for async handling as well as several custom layers of abstraction for communication with ohie-core applications
setup_config.js
- This file enables CLI setup of the
config/config.js
file through command line prompts.
- This file enables CLI setup of the
config/config.js
- This file stores the configurable settings (remote machine addresses, login information, path to cert and key) required for the certificate update process
abstrations/*
- These files contain abstraction interfaces relating to:
- creating http/https requests with nodejs (
request_handler.js
) - creating authenticated requests to openhim (
ohim_request_api
) - manipulating openhim configurations through the openhim-core api (
ohim_highlevel_interface
)
- creating http/https requests with nodejs (
- These files contain abstraction interfaces relating to:
packaged features
openhim-cert-updater
- this shell script is installed under
usr/bin/openhim-cert-updater
and thus is callable from the commandline anywhere. - arguments
- no arguments: run
update_certificates.js
-l
runupdate_certificates.js
and log that it ran-h <CMD>
runupdate_certificates.js
and execute the shell command<CMD>
if the local certificate was updated-l -h <CMD>
: do both of the above-c
callssetup_config.js
and enables generation of theconfig/config.js
file-c -m
callssudo nano $PATH_TO_CONFIG/config.js
and enables user to manually modify the config file
- no arguments: run
- for example:
sudo openhim-cert-updater -h 'touch ~/done.example'
will create the filedone.example
in your home directory IF the local certificate was updated
- this shell script is installed under
Installation From PPA Package
- Install from PPA
sudo add-apt-repository ppa:uladkasach/dev && sudo apt-get update && sudo apt-get -y install openhim-cert-updater
- Setup
config.json
- see below
- Test installation
openhim-cert-updater
Installation From Source Package
- Download
.deb
filewget https://github.com/uladkasach/openhim-cert-updater/releases/download/v1.2.8/openhim-cert-updater_1.2.8~trusty_amd64.deb
- Install
.deb
filesudo dpkg -i openhim-cert-updater_1.2.8~trusty_amd64.deb
- Install dependencies
sudo apt-get install -f
- Setup
config.json
- see below
- Test installation
openhim-cert-updater
Installation From Source Code
- Prerequisites
- Install
- from NPM repository
npm install -U openhim-cert-updater
- from sourcecode
- navigate to root directory
npm install
- from NPM repository
- Setup
config.json
- See below
- Test it out
sudo nodejs update_certificates.js
Setup Config.json
- create a
config/config.json
file by copying theconfig/config.example.json
fileopenhim-cert-updater -c -r
- edit the
config/config.json
to reflect your configuration- the file can be opened in nano with
openhim-cert-updater -c -r
- define the
host:port
of each OpenHIM installation (local and remote) that need to be updated- local is required
- remote is optional
- define the
email
andpassword
for each machine (required), identified byhost:port
, in theconfig.users
object.- e.g.,
"localhost:8080" : { "email" : "root@openhim.org", "password" : "openhim-password" }
- e.g.,
- define which clients need to be updated to use the new certificate on each machine
- e.g.,
"remote_host:8080" : ["client_id"]
- e.g.,
- define the
paths.cert
andpaths.key
paths to the most up to datecert
andkey
for this machine's OpenHIM installation- on a machine w/ certs created by
letsencrypt
/certbot
- cert :
/etc/letsencrypt/live/<your_domain>/fullchain.pem
- key :
/etc/letsencrypt/live/<your_domain>/privkey.pem
- cert :
- on a machine w/ certs created by
sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/ssl/private/ohim-selfsigned.key -out /etc/ssl/certs/ohim-selfsigned.crt
- cert :
/etc/ssl/certs/ohim-selfsigned.crt
- key :
/etc/ssl/private/ohim-selfsigned.key
- cert :
- on a machine w/ certs created by
- the file can be opened in nano with
Implementation
The script update_certificates.js
does several things:
0. Checks whether the cert
and key
found at config.paths
is different than the one recorded in the local OpenHIM installation
- if they are the same, then the script terminates because there is no update that is requried.
1. Updates the local OpenHIM installation with the most up to date cert
and key
available.
- Replaces the cert
and key
of the local OpenHIM installation with the cert
and key
found at the specified config.paths
.
2. "Informs" the remote OpenHIM installations about the most up to date cert
for this local machine
- Adds the new cert
to the trusted ca certs
of all config.machines.remote
machines.
3. Cleans up the trusted ca certs
list of each config.machines.remote
machine.
- Removes the old_cert
from the trusted ca certs
list of each config.machines.remote
machine.
The package includes an openhim-request-api
which handles creating properly authenticated requests and an openhim-toplevel-interface
that creates an easy to use layer of abstraction, implementing the various API calls availible per the openhim RESTful api.