Skip to content

Commit 02e723c

Browse files
author
jester
committed
Initial refactoring of legacy vs cloud native deployments.
1 parent 16ed34a commit 02e723c

4 files changed

Lines changed: 307 additions & 197 deletions

File tree

‎CloudNativeDeployment.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Cloud Native HISP Deployment Model
2+
3+
The cloud native model consists of smaller individual processes (i.e. micro-services) performing specific functional tasks and exposing APIs
4+
either via REST or asynchronous messaging interfaces. Generally the REST interfaces are used to retrieve and maintain the system's configuration
5+
data while the messaging interfaces are used to move Direct messages from one processing step to another using a streaming/pipelining paradigm.
6+
7+
Each micro-service is a discrete Spring Boot fat jar application and be deployed on multiple platforms ranging from bare metal systems to highly
8+
managed cloud provider runtimes such as Google Cloud Run. This document provides details on how to launch each micro-service as a stand alone Java process,
9+
however each micro-service can be deployed using any number of options such as Docker, CloudFoundry, Kubernetes, Google Cloud Run, etc. Instructions
10+
for each targeted platform are out of the scope for this document as they may incur additional platform specific steps such as containerization.
11+
12+
In addition, this deployment model uses asynchronous messaging to dispatch Direct messages from processing stage to the next. The deployment requires
13+
the deployment of a messaging system such as RabbitMQ or Kafka (the default deployment model uses RabbitMQ).
14+
15+
The following is the list of micros-service making up the core of the reference implementation deployment
16+
17+
* Configuration Service
18+
* Configuration UI
19+
* Message Monitor
20+
* SMTP/MQ Gateway
21+
* Security and Trust Agent
22+
* Apache James (for message sending/retrieving and last mile delivery only)
23+
* XD
24+
25+
## Deployment Topology Overview
26+
27+
The following rough diagram illustrates the micro-services in the cloud native deployment model and how they communication with each other.
28+
For simplicity, supporting services like the RabbitMQ and databases have been removed from the diagram, but they generally exist within
29+
the internal HISP network.
30+
31+
![directRICloudNativeOverview](assets/directRICloudNativeOverview.png)
32+
33+
34+
It's worth noting early that unlike the legacy deployment model, the cloud native model does utilize two different SMTP servers: an external facing server for
35+
receiving messages from other HISPs and an internal server for last mile delivery, message storage at rest, and sending out bound messages.
36+
37+
### Micro-Services List
38+
39+
The following list outlines each micro-service, the jar file that comprises the services (each is a single SpringBoot fat jar), and a description of the service.
40+
41+
| Service | Jar File | Description |
42+
| :--- | :--- | :--- |
43+
| Config Sevice | [config-service.jar](https://repo.maven.apache.org/maven2/org/nhind/config-service/8.1.0/config-service-8.1.0.jar) | Holds configuration service for the HISP such as domains, DNS entries, trust bundles, and certificates. |
44+

‎DepHispOnly.md‎

Lines changed: 38 additions & 197 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,17 @@
22

33
This section outlines step by step instructions on installing and deploying a Bare Metal instance of the Java reference implementation. The instructions contains steps for a select list of software platforms such as Windows, FreeBSD, Ubuntu, CentOS, and RedHat Enterprise linux.
44

5+
## Major Updates in Version 8.1+
6+
7+
Version 8.1 is a smaller technology update with minor updates and feature enhancements: Main features include:
8+
9+
* Update to SpringBoot 2.5.x
10+
* Updating to BouncyCastle jdk18on
11+
* Defaults to OAEP Key Encryption with SHA1 Digests for message generation
12+
* Supports ability to decrypt messages using OAEP Key Encryption with SHA256 Digests
13+
* New options to set the key encryption and key digest algorithms
14+
* Documentation to support CloudNative deployment model
15+
516
## Major Updates in Version 6.0+
617

718
This document covers only versions 6.0 and later. For documentation of earlier versions, please see docs [here](http://api.directproject.info/assembly/stock/5.1/users-guide/depl-hisp-only.html).
@@ -108,7 +119,9 @@ The Java 8 SE platform provides the runtime environment that all of the Bare Met
108119

109120
*Windows*
110121

111-
Download and install 8 JRE from Oracle's download web [site](https://www.oracle.com/technetwork/java/javase/downloads/jre8-downloads-2133155.html). After installing the JRE, set the JAVAHOME environment variable by following the instructions below:
122+
Download and install 8 JRE from Oracle's download web [site](https://www.oracle.com/technetwork/java/javase/downloads/jre8-downloads-2133155.html)
123+
(you may be required to sign up for an account).
124+
After installing the JRE, set the JAVAHOME environment variable by following the instructions below:
112125

113126
* Right click on "My Computer" (may be in different locations depending on the Windows version) and select Properties
114127
* If running later versions of Windows, you may be presented "ControlSystem" panel. If so, click Advanced system settings on the left side of the window.
@@ -189,202 +202,13 @@ From the directory where you downloaded and placed the jce zip file, run the fol
189202
sudo cp US_export_policy.jar $JAVA_HOME/jre/lib/security
190203
```
191204

192-
## Obtain Reference Implementation Stock Assembly
193-
194-
The stock assembly contains all of the pre-assembled and configured components of the Bare Metal deployment. Download the latest version of the stock assembly from the maven central repository [repository](http://repo.maven.apache.org/maven2/org/nhind/direct-project-stock/6.0/direct-project-stock-6.0.tar.gz).
195-
196-
**Note:** The maven central repository may black list some IP ranges such as virutal machines running in the Amazon EC2 cloud. Use the Sonatype repository if you are blocked from the maven central repository.
197-
198-
The assembly contains a root directly named direct and has the following folders under the root.
199-
200-
* apache-tomcat-9.0.17
201-
* ConfigMgmtConsole
202-
* DirectDNSServices
203-
* james-jpa-guice-3.2.0
204-
* tools
205-
206-
*Windows*
207-
208-
From a browser, download the desired version of the assembly from one the repositories above.
209-
210-
Example: Download version 6.0 - [direct-project-stock-6.0.tar.gz](http://repo.maven.apache.org/maven2/org/nhind/direct-project-stock/6.0/direct-project-stock-6.0.tar.gz). After downloading, unzip the contents to appropriate installation location.
211-
212-
*All Linux/Unix*
213-
214-
Obtain the URL for appropriate version of the assembly and download it the /opt directory by running wget command from the /opt directory. For example, to download version direct-project-stock-6.0.tar.gz from maven central, use the following commands:
215-
216-
```
217-
cd /opt
218-
sudo wget http://repo.maven.apache.org/maven2/org/nhind/direct-project-stock/6.0/direct-project-stock-6.0.tar.gz
219-
```
220-
221-
Extract the contents of the assembly and set the DIRECT HOME logical using the following command. Note the name of the tar.gz file if you downloaded a different version:
222-
223-
```
224-
sudo tar xvfz direct-project-stock-6.0.tar.gz
225-
export DIRECT_HOME=`pwd`/direct
226-
echo "export DIRECT_HOME=$DIRECT_HOME" | sudo tee -a /etc/environment
227-
```
228-
229-
## Launch Tomcat
230-
231-
Before running the James mail servier, the configuration and message monitiroing services must be running and some minimum configuration completed. All of these services run inside the Tomcat web server.
232-
233-
To start the tomcat server, run the following command from the DIRECT HOME/apache-tomcat-9.0.17/bin directory.
234-
235-
*Windows*
236-
237-
```
238-
startup
239-
```
240-
241-
*All Unix/Linux/FreeBSD*
242-
243-
```
244-
sudo ./startup.sh
245-
```
246-
247-
*Note:* It may take a few minutes for the web server to finish loading as it must initially deploy all of the services when run for the first time.
248-
249-
To validate that Tomcat and the configuration services loaded successfully, launch a browser window against the server node with the following URL:
250-
251-
```
252-
http://<server>:8080/config-ui
253-
```
254-
255-
You should be presented with the configuration ui login screen,
256-
257-
## Domain Name and Certificate Generation
258-
259-
The first step in running your mail server is configuring the domain and a loading a trust anchor and certificate(s) into the configuration ui.
260-
261-
First determine your HISPs domain name. Depending on the type of certificate resolution services you wish to host, your domain naming convention may slightly differ. Regardless of the certificate hosting model, you will need to have to have registered domain. For this document, we will assume you have a domain registered called example.com.
262-
263-
**Note:** Refer to the Direct Project [DNS Configuration Guide](http://wiki.directproject.org/DNS_Configuration_Guide) as a starting point for determining your DNS naming convention.
264-
265-
Now that we have our registered domain, we will host our HISP Direct messaging under the domain direct.example.com.
266-
267-
The next step is create a root certificate (anchor) for our domain and an X.509 certificate or pair of X.509 certificates for encrypting/decrypting and signing message. There are many different options for getting these certificates such as using openssl or obtaining a certificate from a commercial third party such as DigiCert. However the Direct Project reference implementation assembly ships with a tool called certGen for generating root CAs and certificates for the purpose of pilots and interop testing.
268-
269-
**NOTE:** The certificates generated by the certGen tool implement certificates that represent trust anchors and end entity certificates for domains and individual Direct addresses. However, these certificates do not implement a fully functional PKI (public key infrastructure) which would include multitude of additional operational aspects. PKIs are generally implemented by third party CAs such as DigiCert or VeriSign, but can by implemented by individual institutions if they resources to do so. PKI implementation is outside the scope of this document.
270-
271-
Full documentation for the certGen tool can be found [here](https://directprojectjavari.github.io/agent/CertGen). The documentation in the certGen link runs the certGen tool from the reference implementation source tree. In the Bare Metal assembly, the certGen tool is found under the /direct/tools directory that was extracted from the tar.gz file.
272-
273-
Run the certGen tool from tools directory using the following command:
274-
275-
*Windows*
276-
277-
```
278-
certGen
279-
```
280-
281-
*All Unix/Linux*
205+
## Deploy Reference Implementation Core Components
282206

283-
```
284-
./certGen.sh
285-
```
207+
There are two deployment configurations for the Java Reference Implementation. The links below give detailed instructions for each option:
286208

287-
#### Certificate Generation
209+
* [Legacy Deployment](LegacyDeployment.md): This consists of the legacy Apache Tomcat along with Apache James Deployment
210+
* [Cloud Native Deployment](CloudNativeDeployment.md): This consists of a contemporary Cloud Native deployment model with multiple
288211

289-
Now create a CA for your domain. In the certGen tool, enter a common name (CN:) for your new CA. For our domain direct.example.com, we might use something like Direct.Example.Com Root CA. Fill the other fields as needed. It is recommended you set the expiration to 1 year, the key strenth to at least 2048 bytes, and provide a password for your CA's private key.
290-
291-
After creating the CA, create a leaf cert and using your domain name as the CN: field and fill in all other fields as needed. It is recommended you set the expiration to at least 1 year, the key strength to at least 2044 bytes, and provide a password for your private key. After creating your CA and certificate, you should have the following similarly named files in your /tools directory (assuming the direct.example.com domain and no email address entered in the CA dialog. If an email address is entered, then the CA files will have the eamil address in the file name instead of the CN field).
292-
293-
* Direct.Example.com Root CA.der = Root CA file (trust anchor for you HISP)
294-
* Direct.Example.com Root CAKey.der - Root CA private key file
295-
* direct.example.com.der - Org certificate file
296-
* direct.example.comKey.der - Org certificate private key file
297-
* direct.example.com.p12 - Org certificate PKCS12 file
298-
299-
##### Single Use Certificates
300-
301-
The certGen tool does support generating single use certificates. If you wish to implement single use certificates, refer to this specific [section](SingleUseCerts).
302-
303-
## Import Anchors and Certificates
304-
305-
Before the security and trust agent can be run, you must create you domain in the configuration ui tool and import anchors and certificates. Follow the steps below to create your domain and import your trust anchor and certificate(s). A full description of the config ui and operations can be found [here](https://directprojectjavari.github.io/gateway/SMTPWebConfiguration).
306-
307-
1. Log into http://<server>:8080/config-ui with username: admin and password: direct
308-
* Click **Create New Domain**.
309-
* Enter the Domain Name and Postmaster E-Mail Address for the domain this HISP will be handling. Typical postmaster address is postmaster@<domain name>.
310-
* Choose ENABLED as the status.
311-
* Click **Add**
312-
313-
2. Click the Anchors tab.
314-
* Click **Choose File**... and browse to the location of your trust anchor, and select it.
315-
* Check Incoming and Outgoing
316-
* Choose ENABLED as the status.
317-
* Click **Add anchor**
318-
319-
3. Click *Certificates* at the top of the screen
320-
* Click **Choose File** and browse to the location of you org certificate PKCS12 file, and select it
321-
* Choose Unprotected PKCS12 as the private key type
322-
* Choose ENABLED as the status.
323-
* Click **Add Crtificate**
324-
325-
If you have multiple certificate files for scenarios such as single use certificates, repeat the previous 3 steps for each certificate file.
326-
327-
Before your HISP can communicate with other HISP, you must import anchors from other HISPs to establish trusted communication. You must also provide your trust anchor to the HISP(s) you are communicating with. There are a few options of HISPs that exist for interop testing that can be easily accessed. An easier way is to import trust bundles and add that trust bundle to you domain. A common test bundle is the DirectTrust Interop Test bundle found [here](https://bundles.directtrust.org/bundles/interopTestCommunity.p7b). This includes an anchor for the following test domain:
328-
329-
* direct.securehealthemail.com
330-
* Testing HISP running the latest version of the Java Bare Metal assembly. Contact gm2552@cerner.com to establish a trust relationship.
331-
332-
## Configure and Run James Mail Server
333-
334-
First, configure james with your domain name.
335-
336-
*Windows*
337-
338-
**NOTE:** You will need ant installed to use the batch file method.
339-
340-
To set the domain via the batch file, open a command prompt, CD to the %DIRECTHOME%/james-jpa-guice-3.2.0 directory and run the following command:
341-
342-
```
343-
setdomain <your domain name>
344-
```
345-
346-
*All Unix/Linux/*
347-
348-
Run the following commands:
349-
350-
```
351-
cd $DIRECT_HOME/james-jpa-guice-3.2.0
352-
sh ./setdomain.sh <your domain name>
353-
```
354-
355-
Now start the Apache James mail server with security and trust agent with the following commands:
356-
357-
*Windows*
358-
359-
**NOTE:** The Windows version does not current support running as a background service.
360-
361-
```
362-
james
363-
```
364-
365-
*All Unix/Linux/FreeBSD*
366-
367-
```
368-
james start
369-
```
370-
371-
Now add your first user.
372-
373-
*Windows*
374-
375-
```
376-
cd %DIRECTHOME%/james-jpa-guice-3.2.0
377-
james-cli -h localhost adduser username password
378-
```
379-
380-
*All Unix/Linux/FreeBSD*
381-
382-
```
383-
cd $DIRECT_HOME/apache-james-3.0-beta4/bin
384-
./james-cli.sh -h localhost adduser username password
385-
```
386-
387-
**NOTE:** The username should contain @domainname.
388212

389213
## DNS Records
390214

@@ -410,16 +234,32 @@ A fall back alternative is manually distributing your org certificate to the HIS
410234

411235
The following are optional, but recommended, next steps to secure your environment. These are only small configuration tweaks; other configuration options that cover specific areas are covered in the deployment options [section](ImpOptions).
412236

413-
#### Secure Configuration Service Port (8080)
237+
#### Secure Internal Service Ports
414238

415-
To secure the configuration service, it is recommended to limit access to port 8080 to localhost and/or a local subnet.
239+
To secure internal services, it is recommended to limit access the service ports to localhost and/or a local subnet.
416240

417241
#### Secure Configuration Service Password
418242

419-
To further protect the configuration service, or if port 8080 must remain public, it is recommended to change the default password. The default password is *direct* which is encrypted in the *<tomcat home>/webapps/config-ui/WEB-INF/classes/bootstrap.properties* file under the property *direct.configui.security.user.password*. You can either change the password by putting the new password in plain text (remove the {bcrypt} before the password) or you can create an encrypted representation using an online bcrypt web [site](https://www.browserling.com/tools/bcrypt). **NOTE:** If you are using an encrypted password in the properties file, be sure to leave the *{bcrypt}* text before the encrypted text.
243+
To further protect internal configuration service, or if ports must remain public, it is recommended to change the default password for the configuration service. The default password is *direct* which located in the following locations depending on your deployment model:
244+
245+
- Legacy Deployment
246+
247+
The default password is encrypted in the *<tomcat home>/webapps/config-ui/WEB-INF/classes/bootstrap.properties* file under the property *direct.configui.security.user.password*. You can either change the password by putting the new password in plain text (remove the {bcrypt} before the password) or you can create an encrypted representation using an online bcrypt web [site](https://www.browserling.com/tools/bcrypt). **NOTE:** If you are using an encrypted password in the properties file, be sure to leave the *{bcrypt}* text before the encrypted text.
420248

421249
Restart the tomcat server for the changes to take affect.
422250

251+
- Cloud Native Deployment
252+
253+
The default password is contained withing the code itself, but can be overridden by creating an `application.properties` or `application.yaml` file in the same
254+
directory as the config-service.jar file and setting the password under the property *direct.configui.security.user.password*. You can either change the password by putting
255+
the new password in plain text (remove the {bcrypt} before the password) or you can create an encrypted representation using an online bcrypt web [site](https://www.browserling.com/tools/bcrypt). **NOTE:** If you are using an encrypted password in the properties file, be sure to leave the *{bcrypt}* text before the encrypted text
256+
257+
You can use any other Spring configuration method to set the password property (you don't have to use an application.properties or application.yaml file) such as
258+
JVM parameters or even an external source like Spring Cloud Config.
259+
260+
Restart the configuration service process for the changes to take effect.
261+
262+
423263
#### Add Own Server Certificate to James
424264

425265
If you are using James 3, the default configuration enables last mile encryption (SSL and TLS) on the edge POP3, SMTP, and IMAP protocols. This is enabled via configuration in the imapserver.conf, pop3server.conf, and smtpserver.conf files. For POP3 and IMAP4, all connections use the STARTTLS command. For the SMTP protocol, the configuration enables STARTTLS for local outgoing connections that must be authenticated, but all incoming SMTP exchanges from external systems will continue to use non SSL/TLS connections.
@@ -434,3 +274,4 @@ The message monitoring service is preconfigured with common settings, but can be
434274

435275
Starting with version 3.0, an optional module is available for defining X509 certificate policies. See the policy enablement module (direct-policy) users [guide](https://directprojectjavari.github.io/direct-policy/) for full details.
436276

277+

0 commit comments

Comments
 (0)