Rotate keys for new-main-page-UX

INSTALL.md

@@ -38,13 +38,14 @@ cp .env.example .env
 This command copies the `.env.example` into `.env`, creating the `.env` file in the process if it does not exist.
 
 2. Open `.env` with a text editor (i.e. Notepad, VS Code, etc.) and make the necessary changes to the following variables:
-   - `APP_ENV`: If you are setting up a development environment, change this to `dev`. Otherwise, leave it as `prod`.
-   - `DATABASE_URL`: If you are hosting UDOIT on Docker or your local machine, leave it as it is. Otherwise, change it to your database URL.
-   - `BASE_URL`: If you are hosting UDOIT on Docker or your local machine, leave it as it is. Otherwise, change it to the URL of your instance of UDOIT.
-   - `WEBPACK_PUBLIC_PATH`: Uf you are hosting UDOIT on Docker or your local machine, leave it as it is. Otherwise, change it to match the `BASE_URL`in such a way that `/build` is located at the root of the `BASE_URL` (Example:  If your `BASE_URL` is set to `http://127.0.0.1:8000`, your `WEBPACK_PUBLIC_PATH` should be `/build`).
-   	- `APP_LMS`: `canvas` for Canvas LMS. `d2l` for D2l Brightspace LMS.
-   - `JWK_BASE_URL`: If you are self-hosting Canvas, you may set it to the URL of your instance of Canvas. (Example: `JWK_BASE_URL="https://canvas.dev.myschool.edu"`)
-   	- `DEFAULT_LANG`: (optional)  `en` for English. `es` for Spanish. This is English by default.
+- `APP_ENV`: If you are setting up a development environment, change this to `dev` and follow the steps in [Installing Composer Dependencies](#installing-composer-dependencies) without the `--no-dev` flag to obtain all of the development packages. Otherwise, leave it as `prod`.
+- `DATABASE_URL`: If you are hosting UDOIT on Docker or your local machine, leave it as it is. Otherwise, change it to your database URL.
+- `BASE_URL`: If you are hosting UDOIT on Docker or your local machine, leave it as it is. Otherwise, change it to the URL of your instance of UDOIT.
+- `WEBPACK_PUBLIC_PATH`: Uf you are hosting UDOIT on Docker or your local machine, leave it as it is. Otherwise, change it to match the `BASE_URL`in such a way that `/build` is located at the root of the `BASE_URL` (Example:  If your `BASE_URL` is set to `http://127.0.0.1:8000`, your `WEBPACK_PUBLIC_PATH` should be `/build`).
+- `APP_LMS`: `canvas` for Canvas LMS. `d2l` for D2l Brightspace LMS.
+- `JWK_BASE_URL`: If you are self-hosting Canvas, you may set it to the URL of your instance of Canvas. (Example: `JWK_BASE_URL="https://canvas.dev.myschool.edu"`)
+- `DEFAULT_LANG`: (optional)  `en` for English. `es` for Spanish. This is English by default.
+- `DATABASE_ENCODE_KEY`: UDOIT encrypts your API keys within the database using this key. You will need to generate a key that will be used for encryption using the `create-key` script, explained further below.
 
 ## Installation
 
@@ -65,7 +66,20 @@ UDOIT uses Composer to install PHP dependencies. Running the following command w
 ```
 
 *Note: This may take a while to fully initiate. This is normal.*
-#### 4. Set Up Database
+
+#### 4. Create the encryption key
+Once the containers are initialized, run the following command:
+
+```
+    make create-key
+```
+This will generate an encryption key that is used during encryption and decryption of sensitive API keys in the database.
+
+You **must** generate a key, otherwise UDOIT will not start correctly.
+
+If you're an existing user of UDOIT and you need to rotate your keys (such as in cases where you believe your keys may have been compromised), please visit the [Rotating Keys](https://github.com/ucfopen/UDOIT/wiki/Rotating-Keys) page in the UDOIT wiki for more information.
+
+#### 5. Set Up Database
 
 The following command applies migrations necessary to set up the database to store all UDOIT data. Please make sure the containers have fully spun up before running this command.
 ```
@@ -82,12 +96,13 @@ Type `yes` and proceed. The warning is expected and is a non issue.
 
 UDOIT should be installed and running as Docker containers.
 
-#### To stop the UDOIT containers, run the following command:
+#### After generating an encryption key and applying migrations, run the following command to stop the UDOIT containers:
 ```
     make down
 ```
+You will need to stop UDOIT before loading it for the first time in order to allow the new encryption key to reload.
 
-Please be sure to review the `makefile` for more information on what this command and others do.
+Please be sure to review the `Makefile` for more information on what these commands do.
 
 If UDOIT is running without errors, you can move on to [installing it for your LMS](#connecting-udoit-to-an-lms)! If you're encountering errors, please check out the [wiki](https://github.com/ucfopen/UDOIT/wiki).
 
@@ -106,7 +121,29 @@ UDOIT uses Composer to install PHP dependencies. Follow the upstream documentati
 
 > Remove the `--no-dev` flag if you set `APP_ENV=dev` in your `.env.local` file.
 
-#### 3. Database Setup
+#### 3. Encryption Key Setup
+UDOIT encrypts your API keys in the database using a generated encryption key.
+
+This is done to protect against an attacker gaining access to your database and using the API keys to "act" as another user or UDOIT itself.
+
+In order to generate the key, first ensure that you have created a `.env`. Then, run the following command from the root directory of UDOIT:
+
+    php scripts/create-key.php .env
+
+The script will then ask: `Create new key? (Y/n): `
+
+Type `y` and then press enter. Then, you should see something like this (the generated key will be different):
+
+```
+Created new key: ha8HJt6CGAJdlO6S920eE6dUWVBOic+xJxN/O7Owu6s=
+Updated .env with new key.
+```
+
+The script should automatically update the `DATABASE_ENCODE_KEY` field in your environment file with your generated key. Verify that your environment file has been updated by comparing the value of `DATABASE_ENCODE_KEY` with the generated key.
+
+> Note: Ensure you include the correct filename of your environment file when running the key generation script. If you do not pass in any filename, you will receive the following error: `Please specify the environment file to modify!`
+
+#### 4. Database Setup
 While UDOIT is configured to use MySQL or MariaDB by default, Symfony can be configured to work with other databases as well. See the Symfony documentation for details.
 
 Use Symfony to create the database with this command:
@@ -125,7 +162,7 @@ If you are operating in a production environment you will need to generate the d
 
     php bin/console cache:warmup --env=prod
 
-#### 4. JavaScript
+#### 5. JavaScript
 UDOIT uses [node](https://nodejs.org) and [yarn](https://yarnpkg.com/) to compile the JavaScript. Install Node and Yarn on your system, then run:
 
     yarn install

Makefile

@@ -4,6 +4,16 @@ ifneq (,$(wildcard ./.ins.env))
     export
 endif
 
+# environment variable location, default to .env
+ENV_FILE ?= .env
+
+# ip address of database container
+DB_IP ?= $(shell docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' udoit3-db)
+
+# spin up the containers
+start:
+	docker compose -f docker-compose.nginx.yml up
+
 # ──────────────────────────────────────────────
 # Variables
 # ──────────────────────────────────────────────
@@ -87,6 +97,21 @@ admin-panel-retrieve-data: clean-cache
 		exit 1; \
 	fi
 	$(COMPOSE) run --rm php php bin/console app:admin-panel-retrieval $(foreach table,$(TABLES),--tables=$(table))
+
+# ──────────────────────────────────────────────
+# Encryption Key Generation/Rotation
+# ──────────────────────────────────────────────
+
+# run rotate keys
+rotate-keys:
+	@echo ENV_FILE: $(ENV_FILE)
+	@echo DB_IP: $(DB_IP)
+	docker exec -it udoit3-php php scripts/rotate-keys.php $(DB_IP) $(ENV_FILE)
+
+# run create key
+create-key:
+	docker exec -it udoit3-php php scripts/create-key.php $(ENV_FILE)
+
 # ──────────────────────────────────────────────
 # Institution Seeding
 # ──────────────────────────────────────────────

scripts/create-key.php

@@ -0,0 +1,52 @@
+<?php
+
+// create a base64-encoded key using sodium (should usually be 44 characters long)
+function createKey() {
+    $key = sodium_crypto_secretbox_keygen();
+    $final = base64_encode($key);
+
+    return $final;
+}
+
+// modify an env file to include the new key
+function updateEnvFile($envFile, $newKey) {
+    $envContent = file_get_contents($envFile);
+
+    // if DATABASE_ENCODE_KEY doesn't exist, then create the line and set it to the new key
+    if (!preg_match('/^DATABASE_ENCODE_KEY=".*"$/m', $envContent)) {
+        $envContent .= 'DATABASE_ENCODE_KEY="' . $newKey . '"' . PHP_EOL;
+    }
+    // otherwise, just replace DATABASE_ENCODE_KEY
+    else {
+        $envContent = preg_replace('/^DATABASE_ENCODE_KEY=".*"$/m', 'DATABASE_ENCODE_KEY="' . $newKey . '"', $envContent);
+    }
+
+    file_put_contents($envFile, $envContent);
+
+    print("Updated $envFile with new key. Verify DATABASE_ENCODE_KEY is set correctly.\n");
+}
+
+// first argument should be the env file we want to modify
+if (!empty($argv[1])) {
+    $envFile = $argv[1];
+
+    // if envFile doesn't exist, dont try to create a new file and instead exit
+    if (!file_exists($envFile)) {
+        print("Environment file $envFile does not exist!\n");
+        // exit(1);
+    }
+    else {
+        if (strtolower(readline("Create new key? (Y/n): ")) == 'y') {
+            $newKey = createKey();
+
+            print("\nCreated new key: $newKey\n\n");
+
+            updateEnvFile($envFile, $newKey);
+        }
+    }
+}
+else {
+    print("Please specify the environment file to modify!\n");
+}
+
+?>