Skip to content
A template for creating Common Criteria ADV and ATE documents in the German certification scheme
TeX Lua Shell XSLT Emacs Lisp Makefile
Branch: master
Clone or download

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/workflows
adv_arc
adv_fsp
adv_tds
alc
ase
ate_cov
common
config
doku
lua
mwe_arc
mwe_ate
mwe_fsp
mwe_st
mwe_tds
refliste
scripts
.gitignore
LICENSE
Makefile
Makefile.plantuml.rules
Makefile.rules
README.adoc
runmake.sh

README.adoc

CC Dokumentation für den Mauve VPN Client

Dieses Repository enthält die Herstellerdokumente des CC Verfahrens für den Mauve VPN Client. Dieses Dokument und die verlinkten Anleitungen beschreiben das Dokumentationsverfahren und die verwendeten Werkzeuge.

Übersetzen der Dokumente

  • Clonen des Repo

  • Aufruf von ./runmake.sh

  • Ergebnisdokumente landen im Verzeichnis deliverables.

Zum Übersetzen der Dokumente nach PDF wird das Docker Image n-doc verwendet. Die Quellen der Dokumente müssen im aktuellen Verzeichnis liegen und das Verzeichnis muss unter dem Pfad /data in den Container gemountet werden (runmake.sh enthält diesen Aufruf):

docker run --rm  --volume $(pwd):/data ndesign/n-doc make [-j <n> ] delivery

Statt delivery kann auch ein Dokumenttyp (st, tds etc) verwendet werden.

Der optionale Parameter -j steuert die Anzahl der Threads (jobs), die GNU Make gleichzeitig startet. Hier muss eine Zahl angegeben werden: Die Anzahl der Builder in der CI-Plattform oder die Anzahl der Cores des Arbeitsplatzrechners.

Warning
Ohne eine Zahl hinter -j verwendet GNU Make die maximalen Ressourcen des Rechners und startet alle Jobs gleichzeitig. Das führt häufig zum Stillstand des Systems, weil die simultan laufenden PlantUML Prozesse den Speicher komplett auslasten.

Arbeit an den Dokumenten / Struktur des Repositories

Jedes Herstellerdokument hat sein eigenes Unterverzeichnis. Die Unterverzeichnisse heißen so wie der Dokumenttyp und das Schutzprofil, das mit dem jeweiligen Dokument bearbeitet wird.: ase, adv_tds etc. In diesen Verzeichnissen liegen alle Dateien, die spezifisch sind für das jeweilige Herstellerdokument.

Darüber hinaus gibt es von allen Dokumenten gemeinsam verwendete Elemente, die bei allen Herstellerdokumenten gleich sein sollen. Diese Elemente (z.B. Makros, Lua-Programme und CSV-Dateien für die Datenbank) liegen im Verzeichnis common.

Die Dokumente selbst sind modularisiert, also in möglichst sinnvolle Einheiten aufgeteilt. Es gibt jeweils ein Rahmen-Dokument (Master), das die anderen Teile einbindet. Dieses Master-Dokument muss so heißen wie das Unterverzeichnis, in dem es liegt. Im Fall des umfangreichen ADV_TDS geht die Unterteilung weiter, bis auf Modulebene. Ziel der Aufteilung ist es, die Dokumente handhabbarer zu machen: Jeder Autor soll möglichst nur einen kleinen Teil des Dokuments berühren, um das Zusammenführen der Änderungen hinterher zu erleichtern.

Einen Überblick über die Arbeit am TDS gibt die Beschreibung in doku/arbeit-am-tds.adoc

Unter adv_tds/module/tds_module_template.tex liegt eine Schablone für eine Modulbeschreibung mit Kommentaren, wie ein Kapitel aufgebaut ist und welche Makros verwendet werden sollen. Eine Schritt-für-Schritt Anleitung erklärt das genaue Vorgehen.

Minimal Working Examples

Neben den Verzeichnissen für die "produktiven" Dokumente gibt es noch Verzeichnisse mwe_tds, mwe_st, mwe_fsp und mwe_arc. Diese Dokumente in diesen Verzeichnisse dienen dazu, Textfragmente zu setzen, ohne jeweils die umfangreichen und komplexen produktiven Dokumente kompilieren zu müssen. Sie stellen Testumgebungen dar, die — in Anlehnung an die Gepflogenheiten auf TeX Stackexchange — Minimal Working Examples (MWE) genannt werden. Der Dokumentrahmen ist identisch zu dem Rahmen der adv/ase Dokumente: Dieselben Makros und Packages werden eingebunden.

Die Rahmendokumente mwe_tds/mwe_tds.tex, mwe_st/mwe_st.tex und mwe_fsp/mwe_fsp.tex sollen nicht verändert werden. Stattdessen legt man eine Datei mwe_<dokumenttyp>_body.tex an, in die man den eigenen Text einträgt. Diese _body Datei wird von Git ignoriert, sodass durch Experimente keine Merge-Konflikte entstehen. Das make-Goal make mwe legt für alle MWEs die _body-Dateien an.

Build-Management

Ziel ist es, das Generieren der PDF-Dokumente und das Release-Management weitgehend zu automatisieren. Dafür wird eine Kombination von Tools genutzt: latexmk, make und verschiedene Shell-Skripte.

Auf der Ebene der einzelnen Dokumente wird latexmk verwendet, um ein Dokument zu erzeugen. Dabei startet es den Übersetzungsvorgang so häufig, wie es nötig ist, dass das Dokument vollständig erzeugt wird.

Um mehrere Dokumente zu erzeugen, wird latexmk mit make kombiniert: Das Makefile auf der obersten Ebene des Repositories steuert die Erzeugung und die Abhängigkeiten. make steigt dabei in die Unterverzeichnisse der Dokumente ab und ruft dort — über ein weiteres Makefile — latexmk auf.

Auf der obersten Ebene sind folgende Ziele im Makefile verankert:

Ziel Verwendung

all

Erzeugt alle PDF-Dokumente und die DB-Datei in ihren Dokumentverzeichnissen

delivery

Erzeugt alle Dokumente und kopiert diese in das Verzeichnis deliverables. Die Dokumente werden so umbenannt, dass sie die Versionsnummer im Namen enthalten. Schließlich werden alle Dokumente in ein tar-Archiv gepackt.

ase

Erzeugt das Security Target

fsp

Erzeugt die Funktionale Spezifikation (adv_fsp)

tds

Erzeugt die Design Spezifikation (adv_tds)

arc

Erzeugt die Sicherheitsarchitektur (adv_arc)

ate

Erzeugt die Testabdeckungstabellen (ate_cov)

ref

Erzeugt die Referenzenliste (refliste)

clean

Löscht alle Dokumente (auch in deliverables) und die von LaTeX erzeugten Hilfsdateien.

mwe

Erzeugt die "minimal working examples" (mwe_*). Dabei werden die _body Dateien aus einer Vorlage erzeugt.

cleanmwe

Löscht alle Dokumente und die von LaTeX erzeugten Hilfsdateien für die minimal working examples.

Neben dem Makefile gibt es noch Shell-Skripte, die beim Build-Management unterstützen

Skript Verwendung

scripts/release_documents.sh

Hebt die Versionsnummer der übergebenenen Dokumente an und setzt Tags in git. Entspricht in etwa dem Maven Release Plugin. Genaue Beschreibung des Verfahrens ist im Skript dokumentiert.

scripts/renamereleases.sh

Nicht vom Benutzer aufzurufen. Ergänzt die Dokumente um die Versionsnummer im Dateinamen. Wird aus dem Makefile heraus aufgerufen. .

scripts/create_release_archive.sh

Nicht vom Benutzer aufzurufen. Erzeugt ein Archiv aus den auszuliefernden Dokumenten. Wird aus dem Makefile heraus aufgerufen.

Releasemanagement

Das Erstellen von Releases der Dokumente wird in einer separaten Anleitung beschrieben.

Details zur Infrastruktur und zum Verfahren

LaTeX

Zum Schreiben an den Dokumenten ist eine TeX-Installation erforderlich. Es gibt verschiedene Implementierungen und Distributionen. Der zentrale Ort für alle Dinge rund um LaTeX ist das Comprehensive TeX Archive Network (CTAN, https://ctan.org).

Zum Übersetzen der CC-Dokumente ist zwingend die LuaLaTeX Implementierung zu verwenden. Hintergrund ist, dass für die Behandlung der SFR Lua-Code herangezogen wird. LuaLaTeX bietet gegenüber der Standard-Engine eine Schnittstelle zu einem Lua-Interpreter, der während des Übersetzungsvorgangs aufgerufen werden kann, um Lua-Funktionen auszuführen.

Verwendung von LaTeX als Dokumentationswerkzeug

Das Vorgehen beim Erstellen eines Dokuments mit LaTeX ähnelt eher dem Vorgehen bei der Softwareentwicklung als der "klassischen" Textverarbeitung, wie sie beispielsweise mit Word umgesetzt ist.

Der Autor schreibt seinen Text in Form eines Quelltexts (mit dem Dateisuffix .tex). Dieser Text enthält Befehle in Form von Makros. Diese Makros stellt entweder LaTeX selbst zur Verfügung, oder sie werden von externen Packages bereitgestellt, oder der Autor kann selbst Makros schreiben, um immer wiederkehrende Formatierungen oder Textelemente leichter handhabbar zu machen. Im vorliegenden Projekt gibt es eine Menge Makros, die explizit für unser CC Verfahren entwickelt wurden. Die einzelnen Autoren müssen nur diese handvoll Makros kennenlernen (wie eine API) und sich ansonsten um nicht viel kümmern. Besonders Dinge wie Formatierungen, Umbrüche etc. (die bei Word immer wieder Probleme machen) liegen gar nicht im Verantwortungsbereich des Autors. Dieses Vorgehen hier zu vertiefen, würde zu weit führen. Sprecht bei Bedarf bitte Alexander Krumeich für genauere Erläuterungen an.

Im ersten Moment ist es ungewohnt, dass der Text nicht in Form von WYSIWYG verfasst wird. Doch daran gewöhnt man sich schnell…​ Einer der Vorteile dieses Verfahrens ist, dass jeder Autor seinen Lieblingseditor verwenden kann.

Das Dokument selbst wird mit Hilfe des Textprozessors in eine PDF-Datei übersetzt — ganz ähnlich wie ein Compiler. Unter Umständen sind mehrere LaTeX Läufe notwendig, bis das Dokument vollständig übersetzt ist. Das liegt daran, dass Informationen über das Inhaltsverzeichnis, Abbildungsverzeichnisse oder andere Querverweise erst korrekt ausgewertet werden können, wenn das LaTeX eine Vorstellung davon hat, was alles im Dokument enthalten ist. Für das Erstellen des Literaturverzeichnisses muss ein weiteres Programm aufgeufen werden.

Wenn die PDF-Datei schließlich fertig ist, kann sie mit einem beliebigen PDF-Viewer angeschaut werden.

Lua

Für einige Funktionen wird auf den in LuaLaTeX eingebauten Lua Interpreter zurückgegriffen. Hierfür müssen einmalig einige Komponenten installiert werden. Die Erklärung dafür befindet sich in einer separaten Anleitung

Verwendbare Editoren

Grundsätzlich kann jeder Editor für die Arbeit mit LaTeX verwendet werden. Viele Editoren bieten mehr oder weniger gelungene Integrationen für LaTeX, die von einfachem Syntax-Highlighting bis hin zu eingebauten PDF-Previews reichen.

Wer mit Emacs umgehen mag, findet mit AucTeX und RefTeX hervorragende und extrem produktive Pakete für die Arbeit mit LaTeX. Allerdings ist die Lernkurve hier sehr steil.

Erfreulich gut ist auch die Einbindung von Visual Studio Code. Mit dem Paket LaTeX Workshop, das sich über den Marketplace installieren lässt, gibt es Syntax-Highlighting und automatisches Übersetzen nach dem Speichern. Einen PDF-Viewer für einfaches Preview gibt es auch.

You can’t perform that action at this time.