Skip to content

Commit 65e6ad3

Browse files
icingicing
committed
update documentation
1 parent 9ddefb5 commit 65e6ad3

File tree

5 files changed

+39
-164
lines changed

5 files changed

+39
-164
lines changed

‎Makefile.am

+7-6
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
1-
# Copyright 2021, ISRG (https://www.abetterinternet.org)
1+
# Licensed to the Apache Software Foundation (ASF) under one or more
2+
# contributor license agreements. See the NOTICE file distributed with
3+
# this work for additional information regarding copyright ownership.
4+
# The ASF licenses this file to You under the Apache License, Version 2.0
5+
# (the "License"); you may not use this file except in compliance with
6+
# the License. You may obtain a copy of the License at
27
#
3-
# Licensed under the Apache License, Version 2.0 (the "License");
4-
# you may not use this file except in compliance with the License.
5-
# You may obtain a copy of the License at
6-
#
7-
# http://www.apache.org/licenses/LICENSE-2.0
8+
# http://www.apache.org/licenses/LICENSE-2.0
89
#
910
# Unless required by applicable law or agreed to in writing, software
1011
# distributed under the License is distributed on an "AS IS" BASIS,

‎README.md

+11-128
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,18 @@
1-
# `mod_tls` - memory safety for TLS in Apache
1+
# `mod_tls` - rust based TLS for Apache httpd
22

33
This repository contains `mod_tls`, a module for Apache httpd that uses
44
[rustls](https://github.com/ctz/rustls) to provide a memory safe TLS
55
implementation in Rust.
66

7-
This project is sponsored by the [ISRG](https://www.abetterinternet.org).
8-
[Read what they said about it.](https://www.abetterinternet.org/post/memory-safe-tls-apache/).
9-
10-
117
## Status
128

13-
In development/beta test. See [beta testing](#beta-testing) for instructions how to use the recent release.
14-
15-
You need Apache httpd version 2.4.48 or newer to run this module. Also you need [rustls-ffi](https://github.com/rustls/rustls-ffi), either the `main` branch or a version at least 0.8.2.
9+
The current state is compatible with **rustls-ffi v0.13.0** and needs at least Apache 2.4.48 for the
10+
necessary infrastructure. A new release with support for rustls-ffi v0.14.0 is in the making.
1611

1712
`mod_tls` gives you:
1813

1914
* a memory safe TLS via [rustls](https://docs.rs/rustls/0.19.1/rustls/).
20-
* TLS v1.2 and TLS v1.3, features as supported in [rustls](https://docs.rs/rustls/0.19.1/rustls/).
15+
* TLS v1.2 and TLS v1.3
2116
* Configuration similar to Apache's own `mod_ssl`.
2217
* Similar performance as `mod_ssl`, better in some areas.
2318
* Frontend TLS for your clients
@@ -32,8 +27,8 @@ There is a [comparison table with mod_ssl functionality](#comparison-with-mod_ss
3227

3328
## Platforms
3429

30+
* rustls-ffi v0.13.0
3531
* Apache 2.4.48 or later
36-
* OS: wherever apache and (c)rustls are available
3732
* build system: autoconf/automake
3833

3934
### Installation from source
@@ -50,107 +45,6 @@ Run the usual autoconf/automake magic incantations.
5045
> make
5146
```
5247

53-
### Docker Test Image
54-
55-
There is support for building a Docker image based on `debian sid` to run the test suite in.
56-
57-
```
58-
> docker-compose build debian-test
59-
> docker-compose run debian-test
60-
```
61-
62-
This clones the git repository `rustls-ffi` and builds a copy of the local `mod_tls` sources. If you want to setup your own build on this platform, you'll find the instructions in `docker/debian-test/bin/update.sh`.
63-
64-
## Beta Testing
65-
66-
The releases v0.7.x are beta release that lets you run `mod_tls` inside the Apache web server. What your need:
67-
68-
* [Apache httpd](https://httpd.apache.org) 2.4.48 (earlier versions will **not** work).
69-
* [rustls-ffi](https://github.com/rustls/rustls-ffi) 0.7.0
70-
71-
#### What to Expect
72-
73-
* Frontend TLS (v1.2 + v1.3) for the clients connecting to Apache
74-
* ACME certificates (via Apache's `mod_md`)
75-
* OCSP stapling (via Apache's `mod_md`)
76-
* TLS session handling
77-
* multiple certificates per virtual host, SNI, ALPN
78-
79-
#### Detailed Instructions
80-
81-
At the time of this writing Apache 2.4.48 was not generally available as package, but expect that to change soon. When you have it, it usually is accompanied by a `apache2-dev` package that includes all header files and binaries to build `mod_tls`.
82-
83-
When you have that, you need to checkout and build `rustls-ffi`. It has [its own build instructions](https://github.com/rustls/rustls-ffi#build). Basically, you need the `Rust` tool set installed and the run `make` which will pull in the components needed.
84-
85-
After you have the `apache2-dev` package, the tool `apxs` is installed (also when you build apache2 from source yourself). `apxs` is useful to give information about the environment and parameters apache2 was built with. For example:
86-
87-
```
88-
> apxs -q exec_prefix
89-
/usr
90-
```
91-
will tell you the directory underneath everything else is placed. When you have built `rustls-ffi` you need to install it in this location with
92-
93-
```
94-
rustls-ffi> make install DESTDIR=/usr
95-
```
96-
97-
which copies the header file and library. Then get the `mod_tls` release, unpack it somewhere and run:
98-
99-
```
100-
mod_tls-0.7.x> ./configure
101-
```
102-
103-
It should find the `apxs` tool in the path. If not, you can give it:
104-
105-
```
106-
mod_tls-0.7.x> ./configure --with-apxs=/usr/bin/apxs
107-
...
108-
Version: 0.7.x shared 11:0:6
109-
Host type: x86_64-pc-linux-gnu
110-
Install prefix: /usr
111-
APXS: /usr/bin/apxs
112-
HTTPD-VERSION: 2.4.48
113-
C compiler: gcc => gcc
114-
CFLAGS: -g -O2
115-
LDFLAGS: -L/usr/lib -Wl,--gc-sections -lpthread -ldl
116-
CPPFLAGS: -I/usr/include/apache2 -I/usr/include/apr-1.0
117-
```
118-
Something similar will be printed at the end of the configuration. Then you just:
119-
120-
```
121-
mod_tls-0.7.x> make install
122-
```
123-
124-
This places the built module in Apache's `modules` directory. You can check:
125-
126-
```
127-
> apxs -q exp_libexecdir
128-
/usr/lib/apache2/modules
129-
> ls -l /usr/lib/apache2/modules/mod_tls*
130-
lrwxrwxrwx 1 sei users 16 Jun 7 14:01 /usr/lib/apache2/modules/mod_tls.so -> mod_tls.so.0.0.0
131-
-rwxr-xr-x 1 sei users 23785144 Jun 7 14:01 /usr/lib/apache2/modules/mod_tls.so.0.0.0
132-
```
133-
134-
To load it into the server, you then add a line to a `httpd` configuration file. Some installations have a `modules.conf` file where you add:
135-
136-
```
137-
LoadModule tls_module "/usr/lib/apache2/modules/mod_tls.so"
138-
```
139-
Some installations do it differently. `Debian` has a directory `/etc/apache2/mods-available` where you create 2 files `mod_tls.conf` and `mod_tls.load`. The first one can be empty, the second one just has the `LoadModule` instruction as shown above. To enable the module, you then type:
140-
141-
```
142-
> /usr/sbin/a2enmod tls
143-
```
144-
which creates some symlinks in `/etc/apache2/mods-enabled`.
145-
146-
Then you start/reload your server. If your server logs on level `info` you will see an entry like:
147-
148-
```
149-
[2021-06-07 ...] [tls:info] [pid ...] AH: mod_tls/0.7.x (crustls/0.6.1/rustls/0.19.0), initializing...
150-
```
151-
152-
And otherwise it will just do nothing! You need to configure where in your server `mod_tls` should be active and there are several [descriptions below](#configuration) on how to do that.
153-
15448
#### OCSP Stapling with mod_tls
15549

15650
`mod_tls` adds OCSP responses to TLS handshakes (this is what "Stapling" is), **when** someone provides these responses. It has no own implementation to retrieve these responses, like `mod_ssl` does.
@@ -168,34 +62,23 @@ handler by [`mod_status`](https://httpd.apache.org/docs/2.4/mod/mod_status.html)
16862

16963
## Tests
17064

171-
### Functional Tests
172-
17365
If you want to run the test suite, you need:
17466

17567
* `curl` and `openssl` in your path
176-
* Some Python packages: `pytest`, `pyopenssl`
68+
* Some Python packages: `pytest`, `cryptography`
17769

17870
```
17971
> make test
18072
```
18173

182-
### Load Tests
183-
184-
There are load tests for putting the module under a bit of pressure and getting some numbers.
185-
All benchmarks are limited in how they can be applied to reality. It is terribly easy in
186-
these limited tests to hit a sweet spot on your system where CPU+Disc caches align and
187-
you see wonderful numbers. But they will not apply to a production server.
74+
## History
18875

189-
To run these, you nee:
76+
This project has been sponsored in 2020 by the [ISRG](https://www.abetterinternet.org)
77+
([Read what they said about it.](https://www.abetterinternet.org/post/memory-safe-tls-apache/)). It had been added as an *experimental* module into the Apache httpd project. However, the `rustls-ffi`API proved to be unstable, mostly due to `rustls` own ongoing development. This requires rework of `mod_tls` on new releases and the schedule of that does not fit into the release schedule of the httpd project.
19078

191-
* `h2load` from the exceptional [nghttp2](https://nghttp2.org).
192-
* Python package: `tqdm`
193-
194-
```
195-
> make loadtest
196-
```
79+
In September 2024, I chose to give the module a standalone github location with its own releases and removed it from the Apache httpd project again. This will make maintenance and participation easier.
19780

198-
This runs one test. There are several defined in `test/load_test.py` which you can invoke via arguments.
81+
Should rustls one day become stable, we can consider merging it to the httpd project again.
19982

20083
## Comparison with `mod_ssl`
20184

‎configure.ac

+7-6
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
1-
# Copyright 2021, ISRG (https://www.abetterinternet.org)
1+
# Licensed to the Apache Software Foundation (ASF) under one or more
2+
# contributor license agreements. See the NOTICE file distributed with
3+
# this work for additional information regarding copyright ownership.
4+
# The ASF licenses this file to You under the Apache License, Version 2.0
5+
# (the "License"); you may not use this file except in compliance with
6+
# the License. You may obtain a copy of the License at
27
#
3-
# Licensed under the Apache License, Version 2.0 (the "License");
4-
# you may not use this file except in compliance with the License.
5-
# You may obtain a copy of the License at
6-
#
7-
# http://www.apache.org/licenses/LICENSE-2.0
8+
# http://www.apache.org/licenses/LICENSE-2.0
89
#
910
# Unless required by applicable law or agreed to in writing, software
1011
# distributed under the License is distributed on an "AS IS" BASIS,

‎src/Makefile.am

+7-6
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
1-
# Copyright 2021, ISRG (https://www.abetterinternet.org)
1+
# Licensed to the Apache Software Foundation (ASF) under one or more
2+
# contributor license agreements. See the NOTICE file distributed with
3+
# this work for additional information regarding copyright ownership.
4+
# The ASF licenses this file to You under the Apache License, Version 2.0
5+
# (the "License"); you may not use this file except in compliance with
6+
# the License. You may obtain a copy of the License at
27
#
3-
# Licensed under the Apache License, Version 2.0 (the "License");
4-
# you may not use this file except in compliance with the License.
5-
# You may obtain a copy of the License at
6-
#
7-
# http://www.apache.org/licenses/LICENSE-2.0
8+
# http://www.apache.org/licenses/LICENSE-2.0
89
#
910
# Unless required by applicable law or agreed to in writing, software
1011
# distributed under the License is distributed on an "AS IS" BASIS,

‎test/Makefile.am

+7-18
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,11 @@
1-
# Copyright 2021, ISRG (https://www.abetterinternet.org)
1+
# Licensed to the Apache Software Foundation (ASF) under one or more
2+
# contributor license agreements. See the NOTICE file distributed with
3+
# this work for additional information regarding copyright ownership.
4+
# The ASF licenses this file to You under the Apache License, Version 2.0
5+
# (the "License"); you may not use this file except in compliance with
6+
# the License. You may obtain a copy of the License at
27
#
3-
# Licensed under the Apache License, Version 2.0 (the "License");
4-
# you may not use this file except in compliance with the License.
5-
# You may obtain a copy of the License at
6-
#
7-
# http://www.apache.org/licenses/LICENSE-2.0
8-
#
9-
# Unless required by applicable law or agreed to in writing, software
10-
# distributed under the License is distributed on an "AS IS" BASIS,
11-
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12-
# See the License for the specific language governing permissions and
13-
# limitations under the License.
14-
#
15-
# Licensed under the Apache License, Version 2.0 (the "License");
16-
# you may not use this file except in compliance with the License.
17-
# You may obtain a copy of the License at
18-
#
19-
# http://www.apache.org/licenses/LICENSE-2.0
8+
# http://www.apache.org/licenses/LICENSE-2.0
209
#
2110
# Unless required by applicable law or agreed to in writing, software
2211
# distributed under the License is distributed on an "AS IS" BASIS,

0 commit comments

Comments
 (0)