n-doc is a platform for creating Common Criteria documentation. This repository is the official distribution of n-doc. It contains sample documents, LaTeX macros, Lua programs and everything else you need to write your own developer documentation. The sample documents here are the developer documentation for "Mauve VPN Client", a fictional TOE serving as a template for the n-doc process. Follow the links to see the resulting PDFs!
-
Security Target (ASE)
-
Functional Specification (ADV_FSP)
-
TOE Design Specification (ADV_TDS)
-
Test Coverage (ATE_COV)
-
Security Architecture (ADV_ARC)
-
Life Cycle (ALC)
-
Reference List (Reflist)
-
TOE database file (use SQLite Browser to view the file)
Those documents provide an outline that can be used when adapting the sample documents for your own purposes. Especially ASE, ADV_FSP and ADV_TDS contain enough text to show the interaction between documents and database. Clone the repository, build the documents and start changing them for your own TOE!
In 2021 the Common Criteria Users Forum has invited us to present n-doc at the 20th CCUF Workshop (see presentation slides and recording).
In 2022 we have presented n-doc at the International Common Criteria Conference, check out the recording of the presentation.
The easiest way to use n-doc is via the Docker image. Read the next section on how to use it. If you want to install the toolchain yourself, check out the Installation instructions.
Call ./runmake.sh to build the documents. Result documents are copied
to the directory deliverables.
runmake.sh starts a
ndesign/n-doc
container. This container contains all the tools necessary for building the
documents. There is no need to install any software on your computer. The
current directory that contains the repository is mounted into the container:
docker run --rm --volume $(pwd):/data ndesign/n-doc make -j4 delivery
Use a specific document type instead of delivery to build only a single
document (ase, adv_tds etc, see below) . The result document will be in the
subdirectory with the same name.
The optional parameter -j controls the number of threads (jobs) that GNU Make
starts in parallel. Use the number of cores of your CPU. The more, the faster.
|
Note
|
Without a number after -j GNU Make uses all available resources of
the host system. This might lead to a complete standstill.
|
Each document has its own subdirectory. The subdirectories have the
same name as the document type: ase, adv_tds etc. All files that are
specific to that document type reside in that directory. Elements shared between
documents are in the common directory. Lua programs are in lua. The
engine subdirectory contains the resources needed to create the Docker image
containing TeX Live and all other tools. See the separate documentation in
engine/README.adoc for details.
Most of the documents are modularized. There is a main document that includes
the other parts during compile time. This main document must have the same name
as the directory it resides in, e.g. adv_tds/adv_tds.tex.
To add a document use the script scripts/add_document.sh and provide the type
of the new document as an argument on the command line,
e.g.
scripts/add_document.sh ate_fun
This generates an empty (but compileable) document from a template.
To remove a document use the script scripts/remove_document.sh and provide
the type of the document as an argument on the command line, e.g.:
scripts/remove_document.sh ate_fun
The goal is to automate both the generation of PDF documents and the release
management as far as possible. A combination of tools is used for that:
latexmk,
make and an assortment of shell
scripts.
latexmk is used at the level of individual documents. To build several
documents at once, latexmk is combined with make.
The following goals are availavble at the root level Makefile:
| Goal | Purpose |
|---|---|
|
Creates all PDF-documents and the DB file in their respective directories |
|
Creates all PDF-documents and copies them to the directory |
|
Creates the Security Target |
|
Creates the Funktional Specification ( |
|
Creates the Design Specification ( |
|
Creates the Security Architecture ( |
|
Creates the Test Coverage ( |
|
Creates the List of References ( |
|
Removes all documents and auxiliary files |
|
Creates the "minimal working examples" ( |
|
Removes all documents and auxiliary files for the minimal working examples |
The following shell scripts support the build management:
| Script | Purpose |
|---|---|
|
Adds a new document to the repository. The new
document is created from the template in the |
|
Removes a document from the repository. The directory is deleted and the document removed from the Makefile. |
|
Creates a document release. Raises the version number and tags the repository. |
|
Not to be called by the user. Adds the version number to the file name. Is called from the |
|
Not to be called by the user. Creates an archive with the documents in |
All the work is done in feature branches. No direct pushes to the main branch
are accepted. Feature branches are spun off the main branch. Their names
should reflect the purpose, e.g. a ticket number or a short description such as
fix-st-todos. Sometimes it is helpful to prefix branch names with the editor’s
name.
When a feature description is complete and the branch is pushed to the upstream
repository, the editor creates a pull request (Depending on the git server used
in the project, this is called either a merge request or a pull
request. These terms mean the same thing.) The pull request is assigned to the
coordinating editor. They can review the changes and merge the changeset into
the main branch. To facilitate a clean repository structure, it is recommended
to rebase the feature branch before accepting the pull request. This can be
done either by using git rebase or git pull --rebase. Both are acceptable
and it is a matter of personal taste which one is used.
In some environments not all editors have access to the central git servers that host this document repository. For external editors, who cannot directly push their changes to the upstream repo, there is a patch workflow that is implemented by shell scripts.
Instead of pushing a branch and submitting a pull request, the external editor creates a patch file that incorporates all commits of their feature branch. This patch file is sent to the coordinating editor who will recreate the feature branch by applying the patch file. They then create the pull request themselves.
To create a patch file, call scripts/create-patch.sh with the feature branch
checked out. The script accepts a single optional argument -f or --file
followed by a file name. If no file name is given, the script will use the
branch name to derive a file name. In the patch file, every commit of the
feature branch since the spin off from main has its own patch.
To process a patch file, call scripts/process-patch.sh. This script requires
the name of a patch file. With no other arguments, the script checks whether the
patch file can be applied to the main branch. It will also print the names of
the files that are modified by each commit in the patch file.
If called with -a (or --apply) the patch file is not only verified, but also
applied to the repository. A feature branch is created, the script derives the
branch name from the name of the patch file. The script can optionally be called
with the -b switch followed by a branch name.
It is not advisable to commit the patch files. Files with the extension
*.patch are ignored in the .gitignore file.
Creating releases is described in a separate document.
The directories mwe_tds, mwe_st, mwe_fsp and mwe_arc contain
documents that serve as Minimal Working Examples (MWE, as is common at
TeX Stackexchange). They provide the same
macros as their "bigger" counterparts and serve as test environments for
reproducing bugs or developing smaller chapters that are quicker to compile than
the ADV documents themselves. The main documents mwe_tds/mwe_tds.tex,
mwe_st/mwe_st.tex and mwe_fsp/mwe_fsp.tex should not be
modified. Instead, create a file mwe_<documenttype>_body.tex that can be
freely edited. This _body file is ignored by git so that there are no merge
conflicts that result from experiments. The make goal make mwe creates
_body files for all MWE-types.