gsa/fpkilint

Federal PKI, X.509 certificate linter

Certificate Profile Conformance Tool (CPCT)

CPCT is capable of analyzing a certificate’s conformance to a pre-defined certificate profile. User input consists of a certificate and a profile selection. After processing the certificate, CPCT outputs a table similar in formatting to the certificate format tables often included in Certificate Profile documents, but including additional analysis content indicating PASS or specific text describing the non-conformance.

Example output

The tool is capable of analyzing certificates for conformance with the FPKI profiles described in the documents available on the Federal Public Key Infrastructure (FPKI) web page

Running the CPCT Application

To better serve the FPKI community, the CPCT was transitioned from an online application to an application that is hosted and run from the user’s workstation. Users can now access the CPCT application directly from their local hard drive using Docker Desktop. A link to more information on how to access the CPCT application is provided below.

Step-by-step Instructions on How Run the CPCT Tool

Common Policy Framework

Certificate Policy for the Federal PKI Common Policy Framework (FCPF)

X.509 Certificate and CRL Extensions Profile for the Shared Service Provider (SSP) Program

Federal Bridge

X.509 Certificate and CRL Extensions Profile

X.509 Certificate and CRL Extensions Profile for Personal Identity Verification Interoperable (PIV-I) Credentials

fpkilint's Issues

Development test certificate profiles

A set of initial profiles are needed for development

Acceptance Criteria:
A set of profiles that exercise every configuration option in each of its states.
The profiles are not intended to reflect actual certificate profiles.

Suggested name: fpkilint?

*lint is all the rage now -- cablint, certlint, zlint. I think fpkilint might help the community quickly understand the tool's purpose.

Add content to output

As a user, I need to be able to see certificate content in a familiar, easily consumed and compared format.

Acceptance Criteria: Content column displays certificate content for all basic fields and extensions contained in the profile configuration. Content should be formatted to be largely the same or easily compared to the content displayed in the details tab of Microsoft's certificate viewer.

As the USG, I need a system architecture diagram to be able to easily understand the technology involved with building the application

Need a system architecture diagram to be able to easily describe what components are being used to build the system.

Read Certificate Profile Files

As the fpkilint software, I need to read a certificate profile configuration file from disk

Acceptance Criteria:
Profile read into an object/structure whereby the fields can be referenced and/or iterated over. config files should reside in a dedicated directory that may contain additional sub directories to organize the profiles by policy document.

Include Instructions on how to Run the CPCT

This page does not contain information on how to run the CPCT since it was removed as a public website.

The instructions are here -- https://playbooks.idmanagement.gov/fpki/tools/cpct/ -- and should be listed in this repository as well in the readme.

Integrate Unit Testing Capability

Need to test functions to ensure they are working as expected

Acceptance Criteria:
Files and directories (if needed) created to support unittest implementation
Test case for parameter to parse_cert(byte_data) is not bytes
Test cases for five different certificate inputs to parse_cert(byte_data) created

Add help page

Provide a help page that includes helpful information for using the tool. The help page should be linked from the main landing page. Using something like a question mark icon to get to the help page would work.

Help page should include the following sections:

• Background section
  • Summary of the tool (what it is, why we developed it, who can use it)
• How to use the tool section
  • Describe the meaning and purpose of each of the fields (Policy, Version, Profile)
  • Describe different ways to upload a certificate (text, file upload, drag-and-drop).
• Report section
  • Step through the different sections of the report and provide details
• Help and feature request section
  • Provide our icam at gsa.gov email address for any help or feature requests.
  • Guide folks to use the GitHub issues page for requests.
  • Provide some steps folks will need to take if they experience issues. For instance, email your certificate to icam at gsa.gov (will need to rename cert to .txt file extensions) or submit an issue and attach the file to the issue (user will need to create a github account in order to do this). I say the submit an issue and attach the file is the preferred approach.
  • Provide steps if there is a discrepancy with the results (what happens if there is a false-positive or false-negative). Probably follow similar approach as bullet above.

Test Certificates

Create test certificates & test cases / expected results
Dependency: #3

Certificate Profile Configuration Options

Need to define all certificate profile configuration options to be supported in the tool. Options should support specifying existing FPKI profiles and provide flexibility for changes.

Acceptance Criteria:
Minimum viable option set defined and stored on github

Testing and bugfix

Execute test cases, correct bugs
Dependency: #5

Multiple cert profile .json file entry updates needed.

GSA/fpkilint/profiles

The .json files for cert profiles in the following folders need to be updated.

• cpct/fpkilint/profiles/common-ssp/1.8/*.json
• cpct/fpkilint/profiles/common-ssp/1.9/*.json
• cpct/fpkilint/profiles/common-ssp/2.0/*.json

AND

• cpct/fpkilint/profiles/fbca/1.8/*.json
• cpct/fpkilint/profiles/fbca/1.9/*.json

The following JSON entry needs to be updated to an existing resource or page:

{
        "Section":  "profile",
        "Item":  "more_info_url",
        "Value":  "https://www.idmanagement.gov/wp-content/uploads/sites/1171/uploads/fpki-x509-cert-profiles.pdf",
        "OID":  ""
},

• The `PDF does not exits.
• The URL points to the old WordPress location.
• This also show up on the results page of the CPCT Tool.

Test Certificate Profiles

Need to create test profiles to exercise configuration options.
Dependency: #2

Parse Certificate

As the fpkilint software, I need to parse input certificates.

Acceptance Criteria:
Input certificates may be PEM, base64, or binary and I need to accept all three formats.

As the USG, I need a workflow diagram to be able to easily understand how the system will work and be able to share with others.

Acceptance Criteria:

• A detailed workflow that describes the flow of the system and end users.
• Generated using PPT, Visio or similar tool saved in PDF format

Create a minimum viable UI to test and demo with

As the developer, I want to develop a minimum viable UI so that I can easily demo the iterative code deployments to the USG.

FPKI Certificate Profiles

Need to create the profiles associated with FPKI policy documents
Dependency: #6

Create VM / Machine image

Build machine image, perform basic hardening
Dependency: #8

Implement analysis for all configuration options

As a user I want all the configuration options in the profile configuration to work..

Acceptance Criteria:
Aside from profile section, all options in configuration template are processed against relevant certificate content and produce expected output

Create Web UI

Integrate analysis code with web server / create UI for certificate upload and profile selection
Dependency: #4

Batch analysis support

As a PKI provider, or, as an auditor, I would like to analyze millions of certificates.

How would that be possible?

Detect certificate profile type

If a user doesn't know which certificate profile their uploaded certificate falls under, can the tool detect a best guess?

QA & Bugfix

Dependency: #7

Decide on Certificate profile storage format

As software needing to store certificate profiles, I need to have a storage format

Acceptance Criteria:
Storage format similar to JSON, YAML

Kitchen Sink Certificate

Chunde wants a test certificate that contains as much of the tested content as possible

Acceptance Criteria:
A certificate that contains 1 of every extension handled by the configuration file with all / as many of the values populated as possible. E.g. all processed eku values in the eku extension, all key usage values set, etc.

Certificate Anaylsis Code

Write code to compare certificates to profile options and generate output
Dependency: #2

Input Format Testing Certificates

As the developer, @godadada needs test certificates for the parser function

Acceptance Criteria:
Test certs in all three acceptable formats (PEM,DER,Base64) as well as 1 non-certificate file, and 1 non certificate PEM file, in order to confirm input processing is working as expected.

Update Profile Version Numbers

Update version numbers of Profiles to reflect the correct version number and update more_info_url for each type of profile.

• Update profile folder structure with correct version numbers
• Update version numbers to the correct version in Common v2.1 and v2.2 and FBCA v2.0
• Update more_info_urls to the correct profile document for each profile
• Update dropdown list for CPCT Tool to reflect updates
• Update Change log

Certificate Profile Storage Template

As someone who needs to create a certificate profile for use by the system, I need a template for creating said profiles and some reasonable efficient means for editing them.

Acceptance Criteria:
JSON template for certificate profile completed

Develop some kick start code

As the primary developer, @godadada wants some relevant sample code to see how asn1crypto would be used to parse a certificate and access its fields

Acceptance Criteria:
Create some helper functions using asn1crypto to jump start development

Create framework for processing a profile/cert comparison

Need to call relevant processing functions for each section of the profile configuration file

Acceptance Criteria:
Call specific functions based on title of each configuration section.
Skeleton functions defined for each section

Initial proof of concept framework testing the following:
Subject DN, Signature Algorithm, Cert Policies

Support for MacOS

Currently, the code will not function on MacOS because of the following:

1. the way the sys.platform string is processed in binary_utils
2. the absences of a copy of der2ascii built for darwin

Profile History/Version support

Depending on the date of issuance, a sample certificate may conform to a prior version of a certificate profile.

Will older certificates be measured against the current profile, or the profile in effect the date of issuance?

Add effective dates for Certificate Profile Versions

Recommendation from STRAC/FTI: Consider listing the effective date for a given profile version to help make it clear as to which profile was relevant at the time of certificate issuance.

How to run fpkilint on Ubuntu?

I want to run fpkilint-dev on Ubuntu, but it doesn't work properly, and your README file doesn't have detailed steps.
General virtual machines run through the following steps:
1.. / configure (I can't execute it correctly in the first step.error: don't have that file or directory)
2.make
3.make test
4.sudo make install