gsa / piv-guides Goto Github PK

A tokend makes the keys and certificates on your smart card appear in Keychain Access.app and available to applications like Safari or Chrome.

I recently spent some time looking into getting my PIV card to work for web authentication with Mac OS Sierra (10.12.3) and seem to have got it working. As far as I can tell, I'm the first person to get this working within my office and now I'm wondering how to best document the process and get some other perspectives on the approach. I'd also like to go through the process with a few other people and make sure it's repeatable. With at least one other person's system I was not able to successfully repeat the process.

I'm wondering if this would be the best place to be documenting my findings or maybe something like handbook.18f.gov instead or maybe even just a google doc to keep it private at first?

Update: for now I'm putting notes in private Google Doc. If you work in government and would like more information, please leave a comment below.

Also want to flag there may be an opportunity to coordinate with the work to use PIV for digital signing at GSA like https://github.com/GSA/gsa-doc-digital-signature

Description of Issue:

Discuss guidance and lessons learned for most effective behavior of workstations upon removal of PIV card from reader. Please reference attached draft guidance that resulted from a related Tiger Team within the federal Logical Access Working Group (LAWG).

Details of Issue:

If a policy of "must lock workstation behavior" upon card removal:

• Increased number of users walking around building without PIV card (it is still stuck in reader)
• Difficulty supporting PIV logical access to multiple workstations at same time
• Unattended PIV cards left in reader

Mitigation:

• Do not lock upon card removal, rely on user lock and screen timeout for unattended workstation security

References (Docs, Links, Files):

• Please reply with ideas, considerations, links to existing published/draft guidance to consider

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

Link to the Content Page for Contributors:

USGCB Smartcard Removal Recommendation_LAWG Review Draft_20130503.pdf

Description of Issue:

While running the certutil -verify -urlfetch mypiv_auth.cer command to verify the revocation status of my PIV auth certificate, certutil is throwing the error:

Cannot find object or property. 0x80092004 (-2146885628 CRYPT_E_NOT_FOUND)

• Using the same certificate and running the same certutil command on a Windows 7 workstation works fine.
• PIV login is working for Windows 10, so don't think there is any big issue using Windows 10, but may need to update Playbook to specify Windows 10 may throw this error when running certutil command.

Details of Issue:

Receiving error:

Cannot find object or property. 0x80092004 (-2146885628 CRYPT_E_NOT_FOUND)

CertUtil: -verify command FAILED: 0x80092004 (-2146885628 CRYPT_E_NOT_FOUND)
CertUtil: Cannot find object or property.

References (Docs, Links, Files):

• Following guidance on https://piv.idmanagement.gov/networkconfig/ports/ for running certutil command

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

Link to the Content Page for Contributors:

PIV Auth via browser - specific for managed enterprise devices

• Firefox browsers in use
• NSS needs to be updated using non-manual (no user intervention) methods by enterprise engineers
• Some of the intermediate CAs in the FPKI stop the CA name at OU rather than using a CN
• Do full chains for client (user) provided certificates need to be configured in the client for two-way TLS to succeed?

certutil or other methods to manage enterprise configurations for NSS

How do I PIV enable non-Windows based operating systems?

Action: Create new pages for OSX, Linux, Unix and common distributions & versions used across the government.

Description of Issue:

The content in the description sections seem fine. Is there specific information that we should be adding?

Details of Issue:

References (Docs, Links, Files):

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

Link to the Content Page for Contributors:

Description of Issue:

It is difficult to understand which certs should be used for which purpose. For example, which PIV cert should be used for client auth versus which should be used to sign stuff. How do I tell the difference and how do I make sure I am issued the correct certificates? What if I do not have the right certificate?

Details of Issue:

See above.

References (Docs, Links, Files):

No references.

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

New page with the following:

1. a table aligning all FPKI certificates with its intended purpose.
2. a guide on how to identify each certificate.
3. Little harder, what to do if the intended certificate does not have the appropriate extensions.

Link to the Content Page for Contributors:

None

Adding Related Request from FPKI-Guides' Issue #159 - "Distinguishing between certs on a PIV"

Note: PIV-Guides location more applicable. FPKI-Guides' Issue #159 now closed.

• Posted by woodyweaver on December 12, 2017

Description of Issue:

Users (and engineers) often don't understand the differences between the auth and digital signature cert. It would be helpful to expand on the explanation from a functional and programmatic perspective.

Details of Issue:

A useful application would be to force use of the auth cert rather than the digital signature cert when performing client authentication (e.g. SSL client auth.) For a PIV, this can be achieved by checking for 2.16.840.1.101.3.2.1.3.13. However, if the application needs to interoperate with the DoD environment, this OID may or may not be present (it looks like the DoD SHA2 CAC asserts the Common Auth OID, but others don't.)

Recommendations on how to achieve that distinction programmatically across the entirety of the Federal bridge would be welcome.

No additional comments were posted to FPKI-Guide Issue #159.

Description of Issue:

The content contained in the Template.md pages (and their locations in the directory structures) is not consistent across the PIV-Guides, FPKI-Guides, and FICAM-Arch repos.

Details of Issue:

1. The Template.md pages provide style and general instructions for those who need to write guides or information for the PIV-Guides, FPKI-Guides, and FICAM-Arch.
2. The content contained in the Template.md pages is not consistent across the 3 repos.
3. The Template.md pages are not located at the same directory structure level for all 3 repos.

References (Docs, Links, Files):

https://github.com/GSA/piv-guides/blob/staging/pages/template.md
https://github.com/GSA/fpki-guides/blob/staging/template.md
https://github.com/GSA/fpki-guides/blob/staging/pages/template.md
https://github.com/GSA/ficam-arch/blob/staging/template.md

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

1. Make the content consistent for all Template.md pages: sample outline for guides, the same style and general instructions, and Markdown syntax (style sheet).
2. Place all Template.md pages in a consistent location in the directory structures for all 3 repos.

Link to the Content Page for Contributors:

None.

(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

How do I configure my networked systems to handle the case where my user doesn't have their PIV?
-Privileged access
-Non-privileged access

Should also create configuration guidance should the agency policy allow for this use case.

Description of Issue:

grep for all links to idmanagement.gov
output to a link markdown for future tracking
update all links

Details of Issue:

migrated idmanagement on 5/11 and cross-links need to be updated

Do you need to use ActivClient for PIV enablement of your Windows network?

Using commercial middleware is not a requirement to PIV enable your network devices, desktop applications, and web applications. More recent versions of Microsoft Windows (7+ and Server 2008R2+) can be configured with Active Directory to support PIV authentication for standard and privileged user accounts.

Link to the /piv-guides/networkconfig/

I'm trying to collect scripts, government or open source tools for identifying all the intermediate certificate authorities and valid intermediate certificates which chain to Federal Common Policy Certificate Authority (Common).

This is needed for legacy network authentication implementations, and for applications that do not fully implement path discovery or validation protocols (RFC 5280). We have tools for visually viewing the certificate authorities; however, automated discovery and retrieval of all certificates can be a manually intensive process.

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

Scripts could include:

• Powershell with certutil
• Ksh with openssl
• Java
• Other

Description of Issue:

2008R2:

• Computer Configuration -> Policies-> Administrative Templates -> Windows Components, and then expand Smart Card.
• Select Allow user name hint

2012:

• Computer Configuration -> Administrative Templates -> Windows Components, and then expand Smart Card.
• Select Allow user name hint

Details of Issue:

Note change in where...add to the list
piv-guides/_networkconfig/4_accounts.md

References (Docs, Links, Files):

@GSAllewell notes

Purpose:

• A large portion of agencies need information from the PIV credential certificates (PIV Auth etc) to link the network accounts to the credentials
• Fully automated capabilities are not available or within easy implementation reach for all agencies
• Common question for agencies using USAccess are how to use the existing reports to harvest the information to perform the network account linking automatically (via scripts or other)

Option:

1. Leverage the Applicant Report (available by agency only)
2. UUID generation and which fields from the report
3. UPN generation and which fields from the report

Description of Issue:

Approved Products List categories for logical access, transparent card readers has been deprecated

Details of Issue:

Remove the reference - APL announcement references these guides (circular reference)

References (Docs, Links, Files):

https://www.idmanagement.gov/IDM/s/article_detail?link=fips-201-announce

Link to the Content Page for Contributors:

piv-guides/pages/start.md

Native Windows utility to list certificates available on the smart card
certutil –scinfo.

You will be prompted for a PIN for each certificate on the card, but it is not required for this operation. You can press ESC if you are prompted for a PIN.

User FAQ:
Q: What do I do if I lost my PIV card?
A: Contact your agency’s Security Officer if you have lost your credential or believe it has been tampered with. Your current credential will be terminated, and the process for issuing you a new credential will be initiated.

-We may want to add caveats regarding agency specific policies. In theory though, they would take a similar stance on termination.

Description of Issue:

very simple fpki playbook framework launching

Details of Issue:

update navigation

References (Docs, Links, Files):

https://fpki.idmanagement.gov

Is PIV authentication required for accessing cloud hosted solutions?
If your agency users are accessing systems with elevated or privileged access rights, regardless of the hosting solution, you would still need to use a 2-factor hardware authenticator.

Description of Issue:

Updated link needed in the contribute.md file.

Details of Issue:

In the section titled "How to Build a New Guide", the playbook directs new contributors to an example playbook titled 'How do I PIV enable my network logon?' and provides a link to the following url to use as a guide and template for creating a new playbook: https://github.com/GSA/piv-guides/blob/staging/pages/%7B%7B%20site.baseurl%20%7D%7D/devconfig/15_network.

The link is dead and there does not seem to be a 15_network file in the devconfig folder. If this file has been moved, the link should be updated with the new location. If the page has been removed, the how to contribute guide should be updated to reference a different document to use as a template.

References (Docs, Links, Files):

https://github.com/GSA/piv-guides/blob/staging/pages/contribute.md

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

Link to the Content Page for Contributors:

https://github.com/GSA/piv-guides/blob/staging/pages/contribute.md

Add the Authentication Mechanism Assurance to the network enablement as an advanced topic:

• http://csrc.nist.gov/groups/SNS/piv/fips_201-2_march_2015/day_two/tim_baldrige_ad_fips201-2_2015.pdf

@twbaldridge has also provided public domain scripts as samples for engineers to use.

Error Message:
The system could not log you on. The requested key container does not exist on the smart card.

Operating System:

• Windows 10
• Windows 2008R2, Windows 2012R2

Remote Desktop
Only native drivers (Microsoft drivers)
Repeatable (absolutely happens every time)

Description of Issue:

Kramdown does not show needed empty line sometimes

Details of Issue:

Some of the playbooks, empty ssh-all.md, 2b_domaincontrollers.md, 2a_domaincontrollers.md
are crammed without needed empty lines between section. CSS file modification is needed to create the new lines.

References (Docs, Links, Files):

ssh-all.md, 2b_domaincontrollers.md, 2a_domaincontrollers.md

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

Link to the Content Page for Contributors:

IMO it would help readers if the names in the left column exactly matched the major heading of the page that displays when you click the page. Great info, thanks to the contributors.

one should be using FIPS crypto on a platform used for PIV (e.g. that computer you'd run firefox on.)

perhaps it would be useful to document what you need to do to ensure the computer you're running on
is appropriately configured to support use of PIV-approved crypto. (Vendors get mixed messages about whether this is common knowledge among govvies thus maybe it would be worthwhile to document it in this venue.)

References (Docs, Links, Files):

perhaps a new user guide entry on use of PIV-approved crypto algorithms/features and e.g. how to make sure your windows .net platform is enabled for for FIPS 140 use.

Link to the Content Page for Contributors:

How do I configure my systems to allow for short-term employees or interns who are not required to have a PIV and require non-privileged access?

Include that these users should not have privileged access.

Add information and scripts that can be applied to filter the certificates presented to a user during browser-based client auth (PIV cert auth).

This is a combination of browser settings and OS settings - dependent upon the CSP (crypto service provider) in use. The filtering of certificates based on EKU values can help reduce confusion on which certificate to choose.

Need to verify and validate if settings are available in all platforms and versions:

• IE
• Edge
• Chrome
• Firefox
• Safari
• MacOSX
• Windows 7, 10

@grandamp

From the intermediates from crawling the Federal PKI - thru the federal bridge certificate authority; identified four (4) intermediates with 3072 bit key pairs and five (5) with 4096 bit key pairs.

 4                 Public-Key: (3072 bit) 
 5                 Public-Key: (4096 bit)

Few questions:

• We referenced only 2048 key sizes in passing here: piv-guides/pages/details.md
• Did not explicitly state end entity or intermediate (should fix?)
• Do we know of any libraries that may pose problems for processing the larger key sizes during path validation?
• Should cross reference into FPKI guides?

Description of Issue:

The content in the description sections seem fine. Is there specific information that we should be adding?

Details of Issue:

References (Docs, Links, Files):

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

Link to the Content Page for Contributors:

Major item that keeps reappearing in questions

Hold here for notes and lessons...

Page "Identifiers in a PIV Credential" references SHA-1

Perhaps should reference SHA-256 instead.

References (Docs, Links, Files):

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

https://piv.idmanagement.gov/identifiers/

Description of Issue:

It seems that there may need to be an HTML / CSS edit to make the content display correctly when clicking on anchor links. It seems like the beginning of the content that is being referenced from the anchor link is getting caught behind the header of the page.

Details of Issue:

I am seeing varying results when I click on anchor links. If a do a hard refresh (ctrl + f5) the page displays the expected content. However, clicking on anchor links without hard refreshes seems to be hiding the beginning of the expected content behind the header.

At least I've noticed this behavior on IE 11 and Chrome Version 58.0.3029.81

References (Docs, Links, Files):

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

Link to the Content Page for Contributors:

Description of Issue:

ordered nested lists do not work

Details of Issue:

following nested lists does not work:

1. list item 1
   1. sub list item 1
   2. sub list item 2
2. list item 2

following nested lists does not work:

1. list item 1
   • sub list item 1
   • sub list item 2
2. list item 2

References (Docs, Links, Files):

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

Link to the Content Page for Contributors:

Do we need FAQ on PIV-Interoperable? For any technical differences in USAGE for networks and applications?

This also needs to be updated IMHO:

https://www.idmanagement.gov/IDM/servlet/fileField?entityId=ka0t0000000TNPlAAO&field=File__Body__s

The table in network/account linking and identifiers should be cross-referenced -

piv-guides/_networkconfig/4_accounts.md
piv-guides/pages/identifiers.md

The choices to use is recommended (network/accounts) but the engineers should know the reasons and what changes (identifiers)

Placeholder for starting to capture the tuning for network auth.

I know this is not a direct function of the PIV Guide, but I think the PIV Guide should not include official guidance that instructs users to download root or intermediate certificates over plain HTTP.

Right now it links to this URL to download the Federal Common Policy CA root:

http://http.fpki.gov/fcpca/fcpca.crt

Any network-based attacker could include a rule that rewrites this content with an incorrect or malicious root certificate in transit. Depending on how the downloaded root certificate is then deployed, it could give the attacker a very privileged attack vantage point going forward.

Since the link is to download a root CA that the user is not expected to already have installed locally, the root certificate should probably be hosted on a subdomain which uses a certificate that does not chain to the Federal Common Policy.

For Outlook:

https://support.microsoft.com/en-us/kb/2829595

Is this still common and needed in an FAQ?

This is not intended to be a duplicate of #8, as I need to determine current policy on SIA for all FPKI issuers.

I believe SIA is mandatory under Common, but I am not certain if all affiliates under FBCA assert.

The SubjectInfoAccess (SIA) extension is in most intermediate certificates within the Federal PKI. This provides a convenient mechanism for scripts/services to discover most intermediates and issuing CA's within the Federal PKI.

This extension is not used by most validation software today (such as web browsers and web servers) as following all SIA URI is impractical within the Federal PKI, because it yields over 170 CA certificates! That is why they tend to perfom discovery (back to a trust anchor), and mitigate discovery attacks by implementing max size of the returned CMS certs-only file (as well as implementing download timeouts). HTTP is also the best choice, as an issuer can use cache-control headers, and clients do not have to worry about LDAP through firewalls.

For tools and services that are attempting to determine all known certificate paths, such as an SCVP service, processing SIA is a more secure and efficient choice. More secure, and efficient, because you are following references that start with the SIA URI in the Trust Anchor (in our case Common). The reference(s) claim: This file contains all of the CA certificates I have signed. As the references are followed, you have assurance that the reference is good, because it is directly asserted in the CA certificate. You can immediately validate the signature on the children, and if that fails, you log and report, or discard.

Description of Issue:

do we want to put time sensitive data in readme files?

Details of Issue:

Usually, readme files contain information about bugs/issues for, say, software. Since readers can see the issues list and the threads, it seems pointless to update the readme file with the state of issues or playbooks.

We could put long range issues in there but, again, the long range items may not get worked on by the team.

For now, I've made them generic until we decide what to do. Comments please?

References (Docs, Links, Files):

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

Link to the Content Page for Contributors:

Description of Issue:

What are the best practices for local admins managing workstations that an agency "won't" smart card enable?

Details of Issue:

For some reason or another, an agency "won't" smart card enable a system. In that case, how should the local admins manage those workstations?

References (Docs, Links, Files):

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

Link to the Content Page for Contributors:

On the "How to Contribute" page in the "How to build a new guide" pagagraph the link to "how to piv enable my logon" does not work (get a 404 error, points to http://gsa.github.io/piv-guides/devconfig/15_network/)

IMO the content on the page is clear. I think I get the point, I'm merely pointing out the 404 issue.

this is a specific instance of "accessing information on a PIV credential" per the site. I'm asking this from the view of an implementor developing code to process a CHUID.

Questions:
how do you retrieve the CHUID (see e.g. piv-tool of opensc for example code.)
what is the CHUID format
where is TIG-SCEPACS
do you use 2.2 or 2.3
what about the dead link in SP800-73-4
is the CHUID data object a proper DER object, is there a published ASN.1 structure for it
when appropriate what certificate/signature checking is necessary
who signed the CHUID
who gets a FASC-N (my TWIC card has a FASCN, I'm a civilian.)

THANK YOU the link inside gsa.github.io/piv-guides/identifiers/ works, it points to TIG-SCEPACS 2.3 (not 2.2) (search for "this document")

Description of Issue:

Need to know how to install internal CA for generating a domain controller certificate for enabling PIV credential authentication

Details of Issue:

Convert the attached document into playbook format

References (Docs, Links, Files):

• Generating and Installing Domain Controller Certificate.docx

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

Link to the Content Page for Contributors:

• https://github.com/GSA/piv-guides/blob/staging/_networkconfig/2_domaincontrollers.md

@konklone @twbaldridge @AllieTbo @maoconnor

I'm going to remove the master branch

staging is set to default

let me know if this will cause any problems with clones. I checked the forks too...and I want to clean up

Q: What do I do if I have misplaced my PIV card but it is recoverable? How do I access the systems required for my job?
A: Contact your agency’s Security Officer if you have temporarily misplace your credential and it is recoverable. Your current credential can be temporarily deactivated and can be reactivated upon recovery. Depending on your agency, their risk assessment process, and your level of access, you may be given temporary access with the strongest authenticator available.

Description of Issue:

When enabling username hints is there a way to set the non-privileged user accounts as default and leave the hints field blank? This seems to work if the UPN in AD and the UPN in the PIV authentication certificate match. However, for misconfigured UPNs either in AD or in the PIV auth cert, is there a way to set Windows to not match users by UPN when the system detects a PIV credential, but rather something like subject + issuer?

Details of Issue:

It seems when you insert your PIV card and the system recognizes it, a mapping is being done between the user's AD UPN value and UPN value on the PIV authentication certificate. The issue is some agencies AD UPN value and UPN value on the PIV authentication certificates mismatch. In this case, Windows doesn't know which account they're trying to login with and requires the user to enter a username in the hints field.

References (Docs, Links, Files):

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

Link to the Content Page for Contributors:

Description of Issue:

pivcertchains contains the link http://fpki-graph.fpki-lab.gov/ to a graphical representation of the federal pki. issue: it's not text, it's not searchable.

Details of Issue:

when relying parties call on technical support teams inquiring about intermediate CA status it would be helpful if one could search for a given CA name in a text file or spreadsheet or some other machine readable form.

References (Docs, Links, Files):

http://fpki-graph.fpki-lab.gov/ as referred to in page now

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

suggest add text downloadable file link in addition to current information so it's searchable.

Link to the Content Page for Contributors: