# KodeMed — TLS Certificate Guide (production, valid for years)

Who this is for: hospital IT setting up KodeMed so that **Opale / the HIS and every
coder PC reach KodeMed over HTTPS without certificate warnings**, with a cert that
stays valid for **years** — not the self-signed cert used for quick evaluation.

> **KodeMed never issues production certificates — you provide them.** KodeMed only
> makes it easy to *use* your cert. See also `installer/DEPLOYMENT-MODES.md`.

## Recommended: a cert from your own internal CA / PKI

Most hospitals run an internal CA (e.g. **Active Directory Certificate Services**).
Request a server certificate for the KodeMed host from it:

- **Why this is the right answer:** the internal CA root is **already trusted by every
  domain-joined machine**. So Opale's host and all coder PCs trust KodeMed
  automatically — **no per-PC certificate install, no local-admin rights needed**.
- **Validity:** an internal CA can issue a cert valid for **as many years as your policy
  allows** (public CAs now cap at ~1 year; your internal CA does not).

### What to request from IT

| Field | Value |
|-------|-------|
| **Subject / CN** | the KodeMed hostname you will use (e.g. `kodemed.hospital.internal`) |
| **SAN (Subject Alternative Name)** | MUST list exactly what clients use to reach KodeMed. A DNS name is strongly preferred. If you must use an IP, the IP MUST appear as an `IP:` SAN entry. |
| **Key** | RSA 2048/4096 or ECDSA P-256; exportable private key |
| **Validity** | multi-year per your policy |
| **EKU** | Server Authentication |

You will receive (or export) a **full chain** cert (`cert.pem` = leaf + intermediates)
and its **private key** (`key.pem`).

## Handing the cert to KodeMed

Two supported ways (pick one):

**A. Bundled Caddy terminates TLS with your cert (custom-cert mode)**
- Deploy with `setup.sh --domain=<host>` and TLS mode **custom**.
- Drop your files at `certs/cert.pem` (full chain) and `certs/key.pem`, then
  `(podman|docker) compose up -d`.

**B. Your own reverse proxy terminates TLS**
- Use the external-proxy / single-domain preset; your nginx/HAProxy holds the cert and
  forwards to KodeMed. Guide: `installer/server/docker/EXTERNAL-PROXY.md`.

## Verify

- Browser to `https://<host>/` (and the API/Keycloak URLs) shows **no warning**.
- From Opale's host: the COM DLL reaches KodeMed with **no** `trustSelfSignedCertificates`
  needed — set it back to `false` in `kodemed-client-config.json`.
- Cert expiry: `openssl s_client -connect <host>:443 </dev/null 2>/dev/null | openssl x509 -noout -dates`.

## Quick / evaluation only: self-signed

The **IP + self-signed** preset (bundled Caddy internal CA) is for quick tests. Clients
either accept the browser warning per port, or the operator imports the Caddy root CA
into the Windows trust store (`CurrentUser\Root` needs **no admin**;
`Import-Certificate -FilePath caddy-root.crt -CertStoreLocation Cert:\CurrentUser\Root`).
The COM DLL can bypass validation with `trustSelfSignedCertificates: true` in
`kodemed-client-config.json`. **Do not ship self-signed to production** — use an
internal-CA cert as above so it lasts years and every client trusts it automatically.