GitLab/ocserv
1
0
Fork 0
mirror of https://gitlab.com/openconnect/ocserv.git synced 2026-03-14 06:48:16 +08:00
Code Issues Packages Projects Releases Wiki Activity

Added a draft design document

Browse Source
This commit is contained in:
Nikos Mavrogiannopoulos
2015-11-07 11:24:34 +01:00
committed by Nikos Mavrogiannopoulos
parent e8484a2aea
commit 5138a39116
2 changed files with 142 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

141
doc/design.md Normal file
View File

@@ -0,0 +1,141 @@
Intro
=====
To enforce isolation between clients and with the authenticating process,
ocserv consists of 3 components; the main process, the security module and
the worker processes. The following sections describe the purpose and tasks
assigned to each component, and the last section describes the communication
protocol between them.
VPN overview
============
See http://www.infradead.org/ocserv/technical.html
The main process
================
The main component consists of the process which is tasked to:
* Listen for incoming TCP connections and fork a new worker process
to handle it. - See main.c
* Listen for incomping UDP "connections" and forward the packet stream
to the appropriate worker process. - See main.c
* Create and forward to workers with an authenticated user a dedicated
tun device. - See AUTH_COOKIE_REQ message handling.
* Keep track of all connected users. - See the proc_st list in main.h
* Execute any privileged operations that cannot be handled by worker
processes (e.g., change the MTU in a tun device) - See main-misc.c
* Execute any operations that require state for the worker processes,
e.g., store TLS session data for resumption - See main-misc.c
The security module process
===========================
The security module component consists of a process which keeps all
sensitive data (e.g., private keys, PAM state), that should not be leaked to
a worker process. It is separate from main to ensure that no such data are
leaked during a fork(). It handles:
* TLS authentication (i.e., private key decryption and signing). That is
it operates as a 'software security module' for the worker processes to
use the private key used for TLS without accessing it. - See
SM_CMD_SIGN/DECRYPT message handling in sec-mod.c.
* Username/password authentication. That is a worker process needs to
communicate with the security module the client username/password and
get a cookie (ticket) to be considered as logged in by the main process.
The username/password authentication includes GSSAPI authentication.
For this exchange see the SM_CMD_AUTH_* message handling.
* Partial certificate authentication. A user certificate received by the
worker process, is verified by it, and on its SM_CMD_AUTH_INIT message
it indicates the verification status. The security module approves,
and performs any other authentication method necessary.
* Gatekeeper for accounting information keeping and reporting. That is
currently closely related to radius accounting. The security module
receives periodically accounting data from the workers and forwards the
data to the radius accounting server. See the SM_CMD_CLI_STATS message
handling.
* Gatekeeper for new user sessions. When the main process receives a valid cookie
from a worker process, it will notify the security module which keeps the
authentication state. The security module will return any additional user
configuration settings (received via radius or per-user config file) -
See SM_CMD_AUTH_SESSION_OPEN and SM_CMD_AUTH_SESSION_CLOSE message
handling.
The worker processes
====================
The worker processes perform the TLS handshake, and HTTP exchange for
authentication. After that they simply act as bridge between the tun
device and the client. The tasks handled are:
* TLS authentication. Perform the TLS key exchange, and when needed verify
the client certificate.
* Bridge user authentication with the security module.
* Forward the cookie received by the security module to main to obtain a
tun device.
* Establish a DTLS channel. When a client initiates a UDP session with
main, that session is connected and forwarded to the worker. The worker
establishes a DTLS channel over that.
* Bridge the tun device with the TLS and DTLS channels.
IPC Communication
=================
* Authentication
```
main sec-mod worker
| | |
| | <--SEC_AUTH_INIT--- |
| | ---SEC_AUTH_REP---> |
| | <--SEC_AUTH_CONT--- |
| | . |
| | . |
| | . |
| | ----SEC_AUTH_REP--> |
| | |
| <----------AUTH_COOKIE_REQ----------------- |
| | |
| ---SESSION_OPEN----> | |
| <--SESSION_REPLY---- | | #contains additional config for client
| | |
| -----------------AUTH_REP-----------------> | #forwards the additional config for client
| | |
| <------------SESSION_INFO------------------ |
| | |
| | <-- CLI_STATS ------ |
| | (disconnect)
| ---SESSION_CLOSE---> |
| <-- CLI_STATS ------ |
```
* Auth in main process (cookie auth only)
```
main worker
<------ AUTH_COOKIE_REQ
AUTH_REP(OK/FAILED) ------>
+user config
```

38
src/ipc.proto
View File

@@ -1,40 +1,4 @@
/* === Authentication === /* See doc/design.md for the IPC communication sequences.
main sec-mod worker
| | |
| | <--SEC_AUTH_INIT--- |
| | ---SEC_AUTH_REP---> |
| | <--SEC_AUTH_CONT--- |
| | . |
| | . |
| | . |
| | ----SEC_AUTH_REP--> |
| | |
| <----------AUTH_COOKIE_REQ----------------- |
| | |
| ---SESSION_OPEN----> | |
| <--SESSION_REPLY---- | | #contains additional config for client
| | |
| -----------------AUTH_REP-----------------> | #forwards the additional config for client
| | |
| <------------SESSION_INFO------------------ |
| | |
| | <-- CLI_STATS ------ |
| | (disconnect)
| ---SESSION_CLOSE---> |
| <-- CLI_STATS ------ |
*/
/*
* == Auth in main process (cookie auth only) ==
*
* main worker
* <------ AUTH_COOKIE_REQ
* AUTH_REP(OK/FAILED) ------>
* +user config
*
*/ */
enum AUTH_REP { enum AUTH_REP {