Page MenuHome GnuPG
Files F26446021

No OneTemporary
Actions

View Options

diff --git a/README.md b/README.md
index 318cf0a..af5d707 100644
--- a/README.md
+++ b/README.md
@@ -1,249 +1,252 @@
# GpgOL/Web
This project provides a GnuPG integration for users of Outlook Web.
## Files and directories you see here
-- doc/architecture.odp :: Slides describing the architecture
+- doc/communication.md :: Technical description of client/server communication
+- doc/mime.md :: MIME structure of e-mails
- doc/security.md :: Security assessment
- common/ :: Helper code
- server/ :: The broker part to connect Outlook with our client
- client/ :: The client representing our mail GUI
## Overview
GpgOL/Web is a re-implementation of our Outlook plug-in GpgOL, bringing GnuPG
support to the web-based version of Outlook. The older application-based
Outlook had a very different plug-in interface, hence this new implementation
also uses a completely new architecture and user experience.
The new Outlook is a web service with support for user defined add-ins. The
GpgOL/Web add-in is split into two components: a server component that connects
to the outlook server to fetch and send (encrypted) emails, and a client
component that recieves emails for decryption from the sever component and
transfers encrypted emails to it. The GpgOL/Web client component always runs
locally on your computer, whereas its server component can either also run
locally or on a dedicated server (depending on your installation and network
structure). The latter is probably the case for larger organizations. In case
you are the only user or want to test the add-in, you will likely run the
server on the same machine.
The server component must also provide a TLS certificate to secure the
information exchange between client and server. This can either be a
self-signed certificate generated during installation, or an already
existing certificate (e.g., signed by your organization's CA). In case your
organization runs the server component on a dedicated server, you usually
don't have to worry about that, because the certificate is already installed
on the server as well. Only if you run the server component locally yourself,
you will have to also deal with providing a sufficient TLS certificate.
Last but not least, Outlook must be configured to actually use the add-in.
To achieve this, a manifest file (`manifest.xml`) must be added to your mail
account once. It defines the locations of both client and server component
-and adds the GpgOL/Web user interface to Outlook.
+and adds the GpgOL/Web user interface to Outlook. If your account belongs to
+a managed domain, your domain administrator can install the add-in globally
+for all members of the domain, so you won't have to take care of that either.
In summary: GpgOL/Web needs a running server component providing a TLS
-certificate, a running client component, and a proper manifest file to tell
-Outlook where to find those components.
+certificate, a running client component, and a proper manifest file
+registered with Outlook to tell it where to find those components.
### Different installation modi
There's basically two alternatives to install and run GpgOL/Web: install it as
a component of Gpg4Win, or build it yourself and run the local installation.
Depending on your method of choice, the steps of running the extensions'
components are a bit different.
-In case you used the Gpg4Win installer, you should be have both components
-running and a self-signed TLS certificate autogenerated as well. That is, you
-can continue with uploading the `manifest.xml` to your Outlook account and use
-the extension.
+In case you used the Gpg4Win installer, you can start the client from the
+application menu. A self-signed TLS certificate is autogenerated at first
+start. You can then continue with uploading the `manifest.xml` to your
+Outlook account and use the extension.
If, on the other hand, you have built your own extension, some further steps
are needed in order to run both components locally, as no automatism is active.
These manual steps are described in detail below.
## Build it yourself
Although GpgOL/Web is primarily used on Windows, the development is mainly done
on GNU/Linux. Currently the only supported method for building the add-in on
Windows is to build the full [Gpg4Win](https://www.gpg4win.org) installer. The
following instructions are therefore intended for GNU/Linux systems.
### Dependencies
The add-in needs
* [Qt6](https://www.qt.io)
-* [KDE Frameworks 6][https://kde.org]
+* [KDE Frameworks 6](https://kde.org)
* [libkleo](https://invent.kde.org/pim/libkleo)
* [mimetreeparser](https://invent.kde.org/pim/mimetreeparser)
* [QGpgME](https://git.gnupg.org/cgi-bin/gitweb.cgi?p=gpgmeqt.git;a=summary)
If your distribution provides a sufficient up to date version of these, the
easiest way is to install the development packages via your package manager.
Otherwise, you can build all the dependencies yourself with
[kdesrc-build](https://community.kde.org/Get_Involved/development).
### Compile
Then clone and build GpgOL/Web:
```sh
git clone https://dev.gnupg.org/source/gpgol.js.git
cd gpgol.js
cd web
nvm use 22
npm run build
cd ..
cmake -GNinja -DCMAKE_EXPORT_COMPILE_COMMANDS=1 -DCMAKE_BUILD_TYPE=Debug -S . build
cmake --build build && cmake --install build
```
## Generate and install TLS certificate
To secure the communication between the GpgOL/Web client and server component,
they use a self-signed TLS certificate. This certificate needs to be generated
and properly installed.
-When the GpgOL/Web client ist started for the first time, a welcome message
+When the GpgOL/Web client is started for the first time, a welcome message
appears. You are asked whether you want the server component to run locally,
or under a different URL. If you chose a local server component, once you
hit `Continue` a self-signed TLS certificate will be autogenerated if missing.
On Windows it will also be installed so that you can use it immediately with
Chrome, Firefox, or Edge. After this the server component is automatically
started.
This happens *automatically* on Windows installations with Gpg4Win. That is,
users of GNU/Linux systems currently still have to follow the manual
certificate installtion described below, unfortunately. We're still working
-on the automatic brwoser integration of the generated certificates in those
+on the automatic browser integration of the generated certificates in those
scenarios.
## Installing the Outlook extension
The `Setup` button also opens a dialog to assist you with registering the
add-in with Outlook. It should show the local path to the `manifest.xml` file
which you should copy to the clipboard. The `Open Outlook Extension Manager`
button below will launch the
[`Add-Ins for Outlook` manager](https://outlook.office365.com/owa/?path=/options/manageapps).
Be patient, it may taks a while to load.
Switch to `My add-ins` in the menu on the left side, and choose
`Add a custom add-in` in the `Custom Addins` section below. Select
`Add from file...` and provide the `manifest.xml` file you have copied to ypur
clipboard. Double check that the path is actually correct.
## Run it
*Note:* If you compiled the extension yourself, you will have to set the local
paths in the shell you want to start it from. You can do this by simply calling
```sh
source build/prefix.sh
```
from the sources root directory. After this, the components should run without
issues.
You just need to start the client component, as the server is either supposed
to be already running on a different machine or is started by the client
locally.
### Gpg4Win installations
You can start the GpgOL/Web client directly from the Windows start menu.
If you prefer to start it manually, e.g. to see verbose logs, run the following
using the paths of your installation:
```
C:\Program Files\Gpg4Win\bin\gpgol-client.exe
```
As described above, the client also takes care of starting the server
component if you configured it to use a local service.
### Self-compiled and GNU/Linux installations
Run the following from the root directory of the source tree:
```sh
./build/bin/gpgol-client
```
## Manual TLS certificate generation
This section only applies for users who can't use the automatic certificate
generation described above.
For these cases, we recommend using the
[`mkcert`](https://github.com/FiloSottile/mkcert/) tool for manually
generating a TLS certificate:
```sh
mkcert localhost 127.0.0.1
mkcert -install
```
The `-install` step should register the newcertificate with present web
browsers.
### Copy certificates to GpgOL/Web components
After manual certificate generation, you also need to manually copy/move the
private and public parts to the server and clients components of GpgOL/Web.
**GNU/Linux users:**
```sh
# copy to server
mkdir -p ~/.local/share/gpgol-server
cp localhost+1-key.pem ~/.local/share/gpgol-server/certificate-key.pem
cp localhost+1.pem ~/.local/share/gpgol-server/certificate.pem
# copy to client
mkdir -p ~/.local/share/gpgol-client
cp localhost+1.pem ~/.local/share/gpgol-client/certificate.pem
```
**Windows users:**
```sh
# copy to server
mkdir C:\Users\<User>\AppData\Local\gpgol-server
cp localhost+1-key.pem C:\Users\<User>\AppData\Local\gpgol-server\certificate-key.pem
cp localhost+1.pem C:\Users\<User>\AppData\Local\gpgol-server\certificate.pem
# copy to client
mkdir C:\Users\<User>\AppData\Local\gpgol-client
cp localhost+1.pem C:\Users\<User>\AppData\Local\gpgol-client\certificate.pem
```
## Debugging
By default, logs are send to stderr. You can also store the logs to a directory
by setting `GPGOL_SERVER_LOGDIR` and `GPGOL_CLIENT_LOGDIR` environment variable.
This assumes the directory exists.
For example:
```sh
mkdir -p /tmp/gpgol/log
export GPGOL_CLIENT_LOGDIR=/tmp/gpgol/log
export GPGOL_SERVER_LOGDIR=/tmp/gpgol/log
```

File Metadata

Mime Type
text/x-diff
Expires
Thu, Jul 17, 12:21 AM (6 h, 56 m)
Storage Engine
local-disk
Storage Format
Raw Data
Storage Handle
54/b6/d96536d030f6e1f88b71e4639dae

Event Timeline