Skip to content

Getting Started

Jump to bottom
kgal edited this page Sep 28, 2022 · 10 revisions

Protection Profile Development Getting Started

Welcome

So you want (or are forced) to make a Protection Profile document? You're in the right spot. NIAP's Protection Profile documents are housed in github repositories and defined in XML. The basic workflow is:

  1. You edit the XML
  2. You upload it to github
  3. Magic
  4. Readable Protection Profile document

I assure you that this is not difficult. The following topics should assist you in guiding you through this process.

Environment Preparation

Docker Image

A Docker image that handles all the PP requirements has been developed and uploaded to the Docker repository. To run it on a Linux system ensure that Docker is installed, navigate to a directory that contains (or will contain) the PP projects and issue the following command

docker run -it --rm -v $PWD:/pp:z -w /pp -u $(id -u):$(id -g) commoncriteria/pp-xml-dev

To run it on a different OS, consult the Docker documentation relating to your system.

== OR ==

Requirements

  • Bare Minimum - Allows you to edit and synchronize with the master, but you won't be able to build locally.
    • A git client
    • An XML editor (preferably one that can validate against Relax NG schemas)
  • Local Builds - Allows you to build locally, but not spell check
    • The make utility
    • bash or compatible shell
    • An XSL Engine, preferably xsltproc
    • Python version 3
  • Complete - Everything

UNIX-derivative distribution

Creating the right environment on a UNIX-derivative platform, such as macOS, Solaris, or Linux-based, is relatively straight-forward---you just need to install the packages that correspond to the requirements listed above. For example, on a yum-based distribution, you would simply enter the following command:

sudo yum install git make emacs hunspell xsltproc

Windows 10

There are a couple of options for installing the necessary requirements on a Windows 10 platform, but the easiest is probably using the Linux subsystem. Installation instructions are described here. Once this is successfully installed you need to follow the instructions listed above in the UNIX-derivative distribution section.

Web Interface

Github does provide a web interface through which you can theoretically edit Protection Profile documents. While it might be tempting for you to use it to circumvent the installation steps listed above, you are highly advised not to (beyond perhaps to fix a couple of typos). The XML specification that defines a PP-document is very complex but is defined with a documented RelaxNG schema. Using a RelaxNG-aware editor (e.g., emacs, intelli-j Oxygen, Visual Studio w/ Scholarly XML ) will allow you to do real-time schema validation and will probably provide tab-complete functionality. In the long run, this will almost certainly save you a lot of time and frustration.

Adding to an Existing Project

Cloning

To edit an existing product, you must first clone the project locally. Click the green clone button on the desired project's page, as illustrated in the picture below. Clone Button Picture This should open a small window with the git URL (also illustrated in the picture). Use this to clone your project. If using the command line git client, type

git clone --recursive $GIT_URL

where $GIT_URL is the value noted above, and not the literal string. For example, for the File Encryption PP, you'd run the following command:

git clone --recursive https://github.com/commoncriteria/fileencryption.git

This will create the project in your current working directory. To build it, change your current working directory to the project's root directory and run make. This should create the final, human-readable HTML documents in the output directory. These documents should be viewed with a JavaScript-enabled browser.

Project Structure

The PP projects in the commoncriteria group all have the same basic structure. They all have a single root directory. Under this root directory are several files and directories.

  • input/: The input directory holds the XML input files. This is where the project text goes for both the main PP and the ESR. The ESR XML is named 'esr.xml' while the main PP XML file is usually the same name as the project with an 'XML' extension.
  • output/: This is the directory the holds the HTML output files. It also has a subfolder images which is where any pictures or diagrams in the PP should go.
  • transforms/: This is where most of the logic goes that builds the PPs. It's actually a submodule, and is generally not edited by most PP contributors. To be safe, DO NOT CHANGE ANYTHING IN THIS DIRECTORY. And indeed you should be able to ignore most of these files; however, the CCProtectionProfile.rng in the schemas directory is the RNG Schema that defines the structure of the main PP input file. If you are using an RNG-aware editor, you should be able to point your editor at this to assist you to provide on-the-fly validation and in some cases tab-completion of elements and values. For more information about RNG, consult the RNG-resources in the reference section at the end of this document. Also for an API-reference style description of the elements can be found here.
  • .gitignore: This file describes other files in the project that should be ignored by git. These are usually outputfiles, and temporary or backup files generated by editors.
  • .gitmodules: File that associates the transforms project as a submodule to your project. This should be ignored.
  • LICENSE.md: Standard no-copyright disclaimer for US Government projects.
  • local/: Directory where non-content project-specific go. For instance, the hunspell spellchecker is expecting the list of whitelisted words to appear in Dictionary.txt in this directory. Project-specific XSL or RNG files, if necessary, would also go here.
  • Makefile: A make makefile that describes how to build this project. Generally it does not need to be edited; however, sometimes a PP might need to deviate from the standard build process. This might be because the input file has a non-standard name or uses a different XSL file for transformation. By defining specific variables in this file, you adjust the behavior. For instance to change the input file, you might insert the line 
     INPUT = FileEncryptionInput.xml
    at the beggining of this file. For a comprehensive list of hooks run make more-help and it will display the hooks as well as common make targets.
  • README.md: A markdown format file which should provide a basic project description. github.com will displays it when the project page is viewed.

Editing

Contributing to your project will require a shallow, but working knowledge of git. The basic work flow is a cycle of making a couple of small changes to your document, building the document, committing the changes, pulling code from the master, and finally pushing your code. The following git commands can be run in any directory in the project with the exception of the transform directory.

The first step is actually making some changes in the document using your preferred editor. Once you're satisfied with your changes, you can stage your files for a commit. This is done by marking the edited files as those to be committed for the next commit by running

git add list-of-files-to-be-committed

(or the corresponding action with a GUI-based git client). Files that are to be removed from the git project can be removed by running

git rm list-of-files-to-be-removed.

Careful---this command will remove the projects from commit and also delete them from the local filesystem (though if you had previously committed them, those versions should be recoverable). Running

git commit

should bring up an editor where a short description the intent of your edits should be captured. After you write this and close the editor, git will save the changes in the files noted above with your git add and git rm commands to your local directory. Running it with an -a flag will cause all files tracked by git (i.e. Not new files) that were changed to be committed. In general, you can't do too many commits.

After doing a couple of commits, the changes should be pushed back to the original; however it is important to ALWAYS ENSURE YOUR PROJECT BUILDS BEFORE PUSHING IT TO THE MASTER. Once you're confident it builds correctly, you can attempt to push your changes by running:

git push origin

Sometimes git will complain that commits have been made since your last pull. In which case you'll have to pull changes from the master repository and merge them with your content. This is done by running

git pull origin

Sometimes this will result in a merge, which is really just another commit, after which you can attempt to push again. Occasionally this merge will contain conflicts, when your edits and the edits that were committed to the master since you last pulled affect the same section. When this happens the conflict sections will generally be noted thusly:

<<<<<<<<<<<<<<
One version of the edits
...
==============
The other version of the edits
...
>>>>>>>>>>>>>>

To resolve the conflict(s), delete everything except the text that is appropriate (and sometimes there are many sections that must be resolved). Once all conflicts are resolved, commit the changes, and attempt to build the project. If these are successful attempt to push your changes, and repeat the subsequent steps. Running

make git-safe-push

in the project's root directory will attempt the pull, make, push, sequence and should prevent you from inadvertently pushing broken code.

Spellchecking

Spellchecking can be done by running

make spellcheck

which runs hunspell against the HTML outputs (if your project doesn't build, you can't run spellcheck). To cut down on false positives, put words that you recognize as being valid in your project's local dictionary, which is usually a file called Dictionary.txt in your project's root directory. Each valid word should be on it's own line. Hunspell does not know how to pluralize words, so both the singular and plural version of valid words might have to be entered in the dictionary.

Common Make Targets

  • [empty] : Builds all HTML documents
  • clean : Deletes all HTML documents
  • spellcheck : Runs hunspell spellchecker
  • git-safe-push : Pulls changes from the master copy (github). Builds document and if successful pushes your changes to master.
  • linkcheck : Attempts to find broken links in the HTML documents
  • worksheet : Attempts to build the HTML worksheet (requires python v.3)

Starting a New Project From Scratch

Cloning the Skeleton

  1. To make a new protection profile create a new repo on the git server (i.e. github.com), probably through the web interface. Note the value of its git URL which is displayed when you click the Clone or Download button on the upper left. We refer to this value as $NEW_REPO_GIT_URL.
  2. Run the following script (with the appropriate value for $NEW_REPO_GIT_URL). If creating a new module, change the pp-template to module-template everywhere in the following instructions. 
    git clone --bare https://github.com/commoncriteria/pp-template.git
# Make a bare clone of the repository
cd pp-template.git
git push --mirror $NEW_REPO_GIT_URL
# Mirror-push to the new repository

cd ..
rm -rf pp-template.git
# Remove our temporary local repository
  3. Do a full clone of your new project
  4. Rename the input file, currently named, input/pp-template.xml to the name of the project with xml added to it; for example, operatingsystem and application have operatingsystem.xml and application.xml input files respectively. If something was the project name it would be, 
    git mv input/pp-template.xml input/something.xml
  5. And start editing. The template project contains some boilerplate text. Besides adding the content, several values that are project-specific are called out with the QQQQ character sequence.

Live Builds with Github Pages

  1. Copy .github/workflows/manual.yml to your project .github/workflows/build_documents.yml
  2. In your settings, turn on Github pages and set the source to gh-pages

Examples

If you get into trouble, it might be helpful to view other examples such as:

References

Clone this wiki locally