gsa / fpki-guides

This is the old location for the FPKI Playbook. New location below.

This work is led by GSA teams and the Federal Public Key Infrastructure community in coordination with the ICAM Subcommittee of the Federal CIO Council.

Federal Public Key Infrastructure Guides

This repository is for the collaborative development of the Federal Identity, Credential, and Access Management Playbooks and Guides for the Federal Public Key Infrastructure.

General Practices

This content is Vendor neutral. Marketing materials for Commercial Products should not be submitted. If you would like to contribute a page or content which includes Commercial Products and a specific references for development and engineering, please review the Commercial Product trademark or copyright guides from the Product Vendor and reference those guides in your Pull Request.

Plain Language

Contributors should consider the audience when submitting content. Plain language benefits a broad audience. Review your proposed content for use of acronyms and specialized jargon before submitting.

Roadmap

The expected roadmap for these guides:

May 5th, 2017:

• Deployed to fpki.idmanagement.gov
• leveraging Federalist platform as a service for hosting

May 2017++:

• Change notices from the Federal Public Key Infrastructure service providers
• On-going contributions and collections
• Mapping of all the endpoints and additional info from AIA crawler tools
• Applications and patterns
• Developer tools and tips

How to Contribute

For information on how to contribute to the site, visit the Contribute page here. The source repository exists here.

Direct changes and line edits to the content may be submitted through a pull request by clicking 'Edit this page'. You do not need to install any software to submit content. You can use GitHub's in-browser editor to edit files and submit a pull request for your changes to be merged.

Public domain

This project is in the worldwide public domain.

This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the CC0 1.0 Universal public domain dedication.

All contributions to this project will be released under the CC0 dedication. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.

Special Thanks

This site is based on GitHub Pages and Jekyll templates. The templates are based on DOCter from CFPB.

Special thanks to the teams at 18F, 18F Pages, and US Digital Services Playbooks for their open and transparent model which benefits citizens, government, and technology.

fpki-guides's Issues

Registration Authority Guidance

This playbook provides an overview of the registration Authority (RA), and the relationship of the PKI Shared Service Providers (SSPs) with the RA function

Playbook for client certificate encryption exchange

Description of Issue:

Details of Issue:

References (Docs, Links, Files):

If a New Page or Content is Needed, Expected Outcomes:

Link to the Content Page for Contributors:

Agency Best Practices for Device Certificates

I am converting this document into a play.
https://www.idmanagement.gov/IDM/servlet/fileField?entityId=ka0t0000000TNOEAA4&field=File__Body__s

Agency-focused PIV-I FAQ

Will be a compilation of material in various places including the existing PIV-I FAQ. Will also leverage / build upon similar playbook LaChelle has already started. Target audience is agency relying parties. FAQ content would include things such as:

1. high-level explanation of what PIV-I is and use cases / benefits
2. What Is The Difference Between A PIV-I Card And A PIV Card?
3. Can My Agency Accept PIV-I Cards Issued By Our Contractors’ Company In Lieu Of Issuing PIV Cards To These Individuals?
4. Can A PIV-I Card Be Accepted For Both Physical And Logical Access?
5. As A Relying Party, When Do I Use The FASC-N Versus GUID?

Using the FPKI Overlay

@MattKing1 is developing a playbook to explain how to use the FPKI Overlay of NIST SP 800-53

Navigation Item - CRLs and Certificates Page

Description of Issue:

Need to add additional content pertaining to FPKI CRLs and Certificates

Details of Issue:

• Provide download links to FPKI artifacts such as the Common Root cert, including the thumbprints

References (Docs, Links, Files):

• FPKI Site Map - https://www.idmanagement.gov/IDM/servlet/fileField?entityId=ka0t0000000Gmh5AAC&field=File__Body__s
• http://pki.treas.gov/crl_certs.htm
• https://https.cio.gov/certificates/

If a New Page or Content is Needed, Expected Outcomes:

A content page that includes links to the common FPKI artificats agencies request for download. Also provides an overview of information about FPKI CRLs and Certificates.

Link to the Content Page for Contributors:

https://github.com/GSA/fpki-guides/blob/staging/pages/fpki_crls.md

Navigation Item - Trust Stores Page

Description of Issue:

Need an overview of Trust Stores that explains what they are, the different types of trust stores, etc.

Details of Issue:

There is already a trust store page on PIV-Guides. Reference this page and see what else we could add.

References (Docs, Links, Files):

• http://gsa.github.io/piv-guides/details/
• http://gsa.github.io/piv-guides/networkconfig/trustedroots/
• http://gsa.github.io/piv-guides/details/
• Trust Store Guide - https://www.idmanagement.gov/IDM/servlet/fileField?entityId=ka0t0000000TNRNAA4&field=File__Body__s
• FPKI CONOPS - https://www.idmanagement.gov/IDM/servlet/fileField?entityId=ka0t0000000TNQoAAO&field=File__Body__s
• #9

If a New Page or Content is Needed, Expected Outcomes:

A content page that includes an overview of Trust Stores

Link to the Content Page for Contributors:

https://github.com/GSA/fpki-guides/blob/staging/pages/fpki_truststores.md

Explain the difference between trust traversal and encryption certificate discovery

Description of Issue:

Details of Issue:

References (Docs, Links, Files):

If a New Page or Content is Needed, Expected Outcomes:

Link to the Content Page for Contributors:

How Do I Facilitate My End User Pouplations Obtaining FPKI Credentials

This derives from Issue #29

This would be new -- not based on any particular existing document. Target audience is agency relying parties....

    Educate / facilitate agency end user populations obtaining FPKI credentials

LaChelle: obtaining credentials? Low priority.

Certificate Request Form (CRF) Worksheet Guide

This playbook provides guidance to Affiliates on how to complete the Certificate Request Form when requesting a new certificate from the FPKI

Navigation Item - Useful Tools Page

Description of Issue:

Need a landing page for all tools useful for FPKI.

Details of Issue:

Include tools including links to software, checklists, other useful guides, etc.

References (Docs, Links, Files):

• https://fpki-graph.fpki-lab.gov/

If a New Page or Content is Needed, Expected Outcomes:

A content page that includes useful links to PKI tools.

Link to the Content Page for Contributors:

https://github.com/GSA/fpki-guides/blob/staging/pages/fpki_tools.md

PIV-I for Non-federal Issuers

@dasgituser will convert the PIV-I for NFI document to a playbook (started but currently on hold). The playbook provides solutions for overcoming the barriers to federal reliance on non-federal identity cards, and summarizes some of the core PIV-I requirements. Better understanding the PIV-I concept and associated core requirements, as well as knowing where to go for the full set of PIV-I requirements should help potential PIV-I Providers as well as federal relying parties.

Intro page configuration?

Description of Issue:

Currently the index.html in the root directory of FPKI Guides has an include pointing to _includes/index.md. Should we use this for the intro content instead of /pages/fpki_intro.md? Otherwise, should we copy the way the intro page is setup in PIV-Guides?

Details of Issue:

Currently, there are 2 intro pages, the /index.html is being served first, then the /pages/fpki_intro.md page is served when a user clicks on the Introduction side menu link.

Community Interoperability Test Environment (CITE) Participation Guidance

The FPKI Management Authority's Community Interoperability Test Environment (CITE) Participation Guidance will be converted into a playbook. CITE provides the FPKI Community with
a test environment to: (1) identify and resolve technical issues across Affiliates PKIs, and (2) ensure proper functionality of respective system changes prior to deploying them in a production environment. The Guidance document informs and instructs FPKI Affiliates how to access and use CITE. Encourageing use (and proper use) helps create more robust/reliable FPKI consistency and proper functioning.

Annual PIV Card Issuer (PCI) Testing Guide

This playbook provides guidance to PIV Card Issuers on how to complete annual Card Testing

FPKI and FBCA Overview

This playbook provides an overview of the historical purpose and plan for the FPKI and FBCA

Device Certificate Best Practices Guide

This playbook provides guidance for issuing device certificates.

Explaining different types of FPKI User / Person Certificates

#29 breakdown

This would be new -- not based on any particular existing document. Target audience is agency relying parties. Guide would address topics such as:

Making agencies aware of different types of FPKI credentials

• Focus on Persons
• Short succinct information on types (basic, medium, med hw, etc) - in non acronym terms
• Mapping table or diagram to the identity assurance for each
  • what is needed such as in-person, biometrics, no biometrics, remote, etc

@dasgituser thoughts?

Trust Store Management Guide

@dasgituser (Dave Silver) and @tkpk (Giuseppe Cimmino) are converting the FPKI Management Authority''s Trust Store Management Guide to a playbook. The Federal Public Key Infrastructure Management Authority designed and created the Trust Store Management Guide as an education resource for Department, Agency, corporate, and other organizational system level administrators and managers who use the Federal Public Key Infrastructure (FPKI) as part of regular business practices.

Reusing FPKI Compliance Audit Results in C&A Reviews

This playbook provides guidance on how FPKI Compliance Audit results can be leveraged to show compliance with C&A requirements

Make available a list of easily discoverable crawler output

Description of Issue:

Details of Issue:

References (Docs, Links, Files):

If a New Page or Content is Needed, Expected Outcomes:

Link to the Content Page for Contributors:

How To Configure Agency Systems To Accept Selected Credentials

This derives from Issue #29

This would be new -- not based on any particular existing document. Target audience is agency relying parties.....

    How to configure agency system to accept the selected credentials

LaChelle: is being covered elsewhere (slowly) and most certainly can't be covered in one generic guide!

Add this repository to the GSA code inventory

(I work in GSA IT, Office of the CTO. I am submitting this as part of our work to ensure GSA complies with the new Federal Source Code Policy.)

GSA needs to create an inventory of all agency source code, whether open source or closed source. The inventory we create will appear on Code.gov. The inventory will contain basic information about each source code repository, but will not include the source code itself. Please read the implementation guide and use it to submit this repository to the inventory by December 5.

Basically, please do one of the following, the details of which are described in the implementation guide:

• Add a metadata file (.codeinventory.yml or .codeinventory.json) to this repository (optionally, use this tool to generate a metadata file)
• Submit your metadata via a form (only do this if you cannot add a metadata file to this repository)

Let me know if you would like me to open a PR with an example .codeinventory.yml file.

Please let me know if you have any questions.

Thanks!

---

References:

• GSA Open Source Implementation Guide
• GSA Open Source Policy
• Federal Source Code Policy

Styles for alerts

Description of Issue:

Indicators have been added to highlight key pieces of information - I like it

Details of Issue:

Should we align the format with icons and colors from US Web Design Standards?

References (Docs, Links, Files):

https://standards.usa.gov/alerts/

Thoughts? If so, and you want to update - I can also pull the styles / merge with the ficam-arch style updates; then we can push packages to each repo en masse

@djpackham

Navigation Item - Glossary Page

Description of Issue:

A glossary that includes an alphabetical list of terms or words found throughout the FPKI Guides Playbook

Details of Issue:

References (Docs, Links, Files):

http://pki.treas.gov/glossary.htm

If a New Page or Content is Needed, Expected Outcomes:

A content page that includes a glossary for FPKI Guide Playbook

Link to the Content Page for Contributors:

https://github.com/GSA/fpki-guides/blob/staging/pages/fpki_glossary.md

Add Issue template

Add an Issue template

Purpose: to gather good information for each issue opened

NIST 800-63-3 (https://github.com/usnistgov/800-63-3/issues?q=is%3Aopen+is%3Aissue) has an example to review and modify

Include info decided for #20

FPKI Certificate and CRL Extensions Profile Guidance

This playbook provides a description of how to use the FPKI X.509 Certificate and CRL Extensions Profile

How to Digitally Sign and Encrypt - Guide for Agency employees and contractors

This would be new -- not based on any particular existing document. Target audience is agency relying parties and their staff. Guide would address topics such as:

1. how to digitally sign, encrypt, verify signatures, authenticate, etc
2. Emphasize benefits to RP applications/owners
3. special considerations such as what to do once you verify a digital signature (archive to be able to verify after certificate expiration)

Where do you find all the CAs and Crawler info

Description of Issue:

Details of Issue:

References (Docs, Links, Files):

If a New Page or Content is Needed, Expected Outcomes:

Link to the Content Page for Contributors:

PIV-I Certification Process

@dasgituser (Dave Silver) is converting document to a play - https://www.idmanagement.gov/IDM/servlet/fileField?entityId=ka0t0000000TNHNAA4&field=File__Body__s

SSP Certificate and CRL Extensions Profile Guidance

This playbook provides a description of how to use the SSP X.509 Certificate and CRL Extensions Profile. This will help Shared Service Providers operating within the FPKI to better understand and utilize the Profile, which is essential for establishing commonality and interoperability within the FPKI. This how-to playbook will be new (not from an existing document). The SSP X.509 Certificate and CRL Extensions Profile document will also be converted into markdown for publication on github.

PIV-I Certificate and CRL Extensions Profile Guidance

This playbook provides a description of how to use the PIV-I X.509 Certificate and CRL Extensions Profile. This will help PIV-I Card Issuers operating within the FPKI to better understand and utilize the Profile, which is essential for establishing commonality and interoperability within the FPKI. This how-to playbook will be new (not from an existing document). The PIV-I X.509 Certificate and CRL Extensions Profile document will also be converted into markdown for publication on github.

Navigation Item - Overview Page

Description of Issue:

Add or modify content on the Overview Page

Details of Issue:

Current content is already posted on this page. Determine what else can be added to give a general overview of FPKI and then add the new content.

References (Docs, Links, Files):

• #18
• http://pki.treas.gov/about_pki.htm

If a New Page or Content is Needed, Expected Outcomes:

A content page that provides an overview of FPKI in a clear and concise manner.

Link to the Content Page for Contributors:

https://github.com/GSA/fpki-guides/blob/staging/pages/fpki_overview.md

Navigation Item - Public Key Infrastructure Page

Description of Issue:

Public Key Infrastructure topics are needed to help program managers and engineers understand what a Public Key Infrastructure is, and what the Federal Public Key Infrastructure contains.

Details of Issue:

References (Docs, Links, Files):

• pki.treas.gov

If a New Page or Content is Needed, Expected Outcomes:

A content page that includes topics and information about what Public Key Infrastructure is, what it contains, and what it is used for.

Link to the Content Page for Contributors:

https://github.com/GSA/fpki-guides/blob/staging/pages/fpki_pki.md

Navigation Item - Introduction Page

Description of Issue:

Need a clear and concise introduction for the FPKI-Guides Playbook.

Details of Issue:

Add more details to current intro page. A visitor to the site may not know what playbooks or the FPKI is so a clear intro explaining the two is needed.

References (Docs, Links, Files):

Leverage, where possible, the wording and structure of other playbook introductions.

• https://gsa.github.io/piv-guides/

If a New Page or Content is Needed, Expected Outcomes:

A content page that explains what playbooks are as well as FPKI in a clear and concise manner. The page should be understandable by both Program Managers and System Engineers.

Link to the Content Page for Contributors:

https://github.com/GSA/fpki-guides/blob/staging/pages/fpki_intro.md

Agency C&A of SSPs Guidance

This playbook provides guidance to agencies on how to leverage the C&A conducted by GSA when the agency completes its FISMA assessment of the agency's SSP

Ping DoD for the install root source code and configure for Federal PKI

Description of Issue:

Details of Issue:

References (Docs, Links, Files):

If a New Page or Content is Needed, Expected Outcomes:

Link to the Content Page for Contributors:

FPKI Trust Infrastructure Overview

This playbook provides an overview of the FPKI Trust Infrastructure

Define structure for fpki-guides

• Identify the audience, categories of information and navigation for fpki-guides
• For each above, add Labels to track and label associated issues

Navigation Item - Certificate Authorities Page

Description of Issue:

Need to update current Certificate Authorities page to include more information about the FPKI certificate authorities.

Details of Issue:

• Links need to be updated as well as additional links should be added.
• Update the page with other relevant information aboutFPKI CAs

References (Docs, Links, Files):

• http://pki.treas.gov/
• FPKI Certificate Policies - https://www.idmanagement.gov/IDM/s/article_content_old?tag=a0Gt0000000SfwS
• https://https.cio.gov/certificates/
• FPKI Approved Providers - https://www.idmanagement.gov/IDM/s/article_content_old?tag=a0Gt0000000XRrC
• FPKI Documents - https://www.idmanagement.gov/IDM/s/article_content_old?tag=a0Gt0000000Sfx1

If a New Page or Content is Needed, Expected Outcomes:

A content page that includes basic information about the FPKI Certificate Authorities including links to policies.

Link to the Content Page for Contributors:

https://github.com/GSA/fpki-guides/blob/staging/pages/fpki_cas.md

FPKI Mapping Tables Playbook

This would be new -- not a conversion of an existing document. The FPKI has two different mapping tables. The FPKI Applicant Certification Mapping Tableis used by non-SSPs to map their Certificate Policy against the FBCA Certificate Policy. The FPKI Common Policy Framework CPS Evaluation Table is for SSPs to map their Certification Practice Statement against FCPCA Certificate Policy The mapping tables are used during the application (full mapping) process and subsequent audits (delta mappings). This playbook will explain the differences between the mapping tables, when to use, and how to use.

Target audience are FPKI Affiliates/SSPs who must complete the applicable mapping tables, as well as auditors that will facilitate use of the mapping tables and review completed mappings.

What Are The Different Types of FPKI Credentials

Derives from Issue #29

Make agencies aware of different types of FPKI credentials

LaChelle: different types? This is a perfect, small, short, no acronym section. Medium to high priority?

How To Enroll/Activate PKI-credential End Users

This derives from Issue #29

This would be new -- not based on any particular existing document. Target audience is agency relying parties.....

PKI-specific enrollment/activation (if not fully covered in another playbook that we are aware of)

LaChelle: needs more info

@dasgituser: how-to guide describing what a relying party application needs to do to map the asserted identity to some provisioned account in the system. I believe FICAM Roadmap discusses this topic in general, so we might leverage that material and frame it in terms of PKI certificates.

How Do I Determine Which Credentials to Accept

Derives from Issue #29

This would be new -- not based on any particular existing document. Target audience is agency relying parties....

Determine which to accept for their applications

LaChelle: which to accept? No priority for now. This is based on risk assessments and we want to align with 800-63-3 draft and forward thinking changes in progress.

Navigation Item - FAQ Page

Description of Issue:

Need a list of FAQs most common to the Federal PKI

Details of Issue:

References (Docs, Links, Files):

• FPKI FAQ - https://www.idmanagement.gov/IDM/servlet/fileField?entityId=ka0t0000000TNvDAAW&field=File__Body__s
• HSPD-12 FAQ (PKI) - https://www.idmanagement.gov/IDM/servlet/fileField?entityId=ka0t0000000TNMNAA4&field=File__Body__s
• https://https.cio.gov/certificates/

If a New Page or Content is Needed, Expected Outcomes:

A content page that contains FPKI related FAQs as well as links to other topics related to FPKI

Link to the Content Page for Contributors:

• https://github.com/GSA/fpki-guides/blob/staging/_faq/index.md

How to add Common Policy as a trust anchor in Firefox

Save the Common Policy (FCPCA) root certificate to your system:
http://http.fpki.gov/fcpca/fcpca.crt
The DN for the Common Policy CA is:
cn=Federal Common Policy CA, ou=FPKI, o=U.S. Government, c=US
The sha1 Thumbprint is:
90 5f 94 2f d9 f2 8f 67 9b 37 81 80 fd 4f 84 63 47 f6 45 c1

Inside FireFox click on the menu bars in the top right corner,
select options,
select advanced,
select View Certificates
Select the Authorities Tab
Click import
Browse to where you have saved the FCPCA self-signed certificate.
Select the file and click open
Highlight the certificate and click Edit Trust
Select
This certificate can identify websites and
This certificate can identity mail users
Click OK

Obtaining a Credential to Access a Federal Application

This playbook would be new -- not derived from an existing document. The playbook would explain the various contexts and steps for a citizen to obtain a credential to access a federal system. This might include a TFS scenario, PIV-I Card scenario, direct from agency scenario, etc. The target audience is primarily citizens, but others (e.g., credential issuers, relying parties) might also be interested.

Add comment / issue help

Pull from

• https://pages.nist.gov/800-63-3/comment_help.html
• https://github.com/usnistgov/800-63-3/blob/nist-pages/comment_help.md

PIV-I Testing Guide

This playbook provides guidance to PIV-I providers for testing of PIV-I credentials

Agency Guide to FPKI Credentials

This would be new -- not based on any particular existing document. Target audience is agency relying parties. Guide would address topics such as:

1. Making agencies aware of different types of FPKI credentials
2. Determining which to accept for their applications
3. Education / facilitation of agency end user populations obtaining those credentials
4. How to configure agency system to accept the selected credentials
5. PKI-specific enrollment/activation (if not fully covered in another playbook that we are aware of)