diff --git a/_config.yml b/_config.yml index 326b3be9..fad3d7b6 100644 --- a/_config.yml +++ b/_config.yml @@ -9,7 +9,7 @@ baseurl: '/piv-guides' #url: "http://yourdomain.com" # the base hostname & protocol for your site #twitter_username: jekyllrb github_username: lachellel -highlighter: pygments +highlighter: rouge # Point the logo URL at a file in your repo or hosted elsewhere by your organization logourl: /piv-guides/img/logo.png @@ -110,7 +110,10 @@ navigation: internal: true coll: true collname: userconfig - +- text: Contribute + url: contribute + internal: true + coll: false collections: userconfig: diff --git a/_devconfig/15_network.md b/_devconfig/15_network.md index 9c5ff5bc..1c805b06 100644 --- a/_devconfig/15_network.md +++ b/_devconfig/15_network.md @@ -17,9 +17,9 @@ $(function() { This guide will take you through the steps necessary to configure your Windows based computer network to accept and potentially require PIV cards for authentication. ##### Assumptions -* Your organization users are currently issued PIV cards -* Your organization is using Microsoft Active Directory to manage your Windows network users -* Your organization is using Microsoft Windows Server 2008 R2 or 2012 +* Users have PIV cards +* You're using Microsoft Active Directory to manage your Windows network users +* Your Microsoft Windows Server versions are 2008 R2 or 2012 * Concepts will likely remain applicable to other versions of Windows Server, however, specific instructions may require modification #### Before you get started @@ -138,9 +138,9 @@ Perform the following steps to manually view and publish a domain controller cer 1. Log on as domain administrator or a member of the Cert Publishers global group for the target domain controller. Technically, the publication can be performed at any computer that is a domain member, but for convenience, the domain controller is used in this scenario. 2. Verify that there are no certificates already published on the domain controller's Active Directory object. -3. Run the following command from a command-line prompt. Replace the variable with the name of the target domain controller and and variable names with the appropriate domain suffix. +3. Run the following command from a command-line prompt. Replace the variable with the name of the target domain controller and and variable names with the appropriate domain suffix. - certutil -viewstore "ldap:///cn=,ou=domain controllers,dc=,dc=?usercertificate" + certutil -viewstore "ldap:///cn=,ou=domain controllers,dc=,dc=?usercertificate" A window should appear with no certificates displayed. This is expected since no certificates have been published yet. 6. Click Cancel to close the window. @@ -151,13 +151,13 @@ A window should appear with no certificates displayed. This is expected since no The command determines the proper Active Directory object by the subject information in the certificate. The publication will fail if no object can be found based on the subject information. 9. To verify that the certificate was published successfully, perform the following steps from a command-line prompt. - certutil -viewstore "ldap:///cn=,dc=,dc=?usercertificate" + certutil -viewstore "ldap:///cn=,dc=,dc=?usercertificate" If the domain controller's computer object has no certificates in the userCertificate attribute, the certutil output will display an empty list in the window. If "?userCertificate" was omitted from the command line parameters or an invalid object class was specified, an error message will appear such as the following: CertUtil: -viewstore command FAILED: 0x80092009 (-2146885623) CertUtil: Cannot find the requested object. - certutil –viewstore "ldap:///cn=Administrator,cn=Users,dc=,dc=" + certutil –viewstore "ldap:///cn=Administrator,cn=Users,dc=,dc=" > When does a CA need to contact a writeable Domain Controller? diff --git a/img/elements.png b/img/elements.png new file mode 100644 index 00000000..85a35740 Binary files /dev/null and b/img/elements.png differ diff --git a/pages/contribute.md b/pages/contribute.md new file mode 100644 index 00000000..e01ef50a --- /dev/null +++ b/pages/contribute.md @@ -0,0 +1,48 @@ +--- +layout: page +title: Contribute +permalink: /contribute/ +--- +This site is for the collaborative development of the Federal Identity, Credential and Access Management PIV Enablement Playbook. + +#### How to Contribute + +Thank you for considering contributing to our development of open and transparent FICAM guidance documents. If you're unsure of anything, just ask or submit edits through an issue or pull request. We appreciate any sort of contribution and are committed to transparency and collaboration. + +The source repository exists [here]({{site.github.repository_url}}/{{site.branch}}/). + +We encourage you to read our [LICENSE]({{site.baseurl}}/license) and our [README]({{site.github.repository_url}}/{{site.branch}}/README.md), which exist within this repository. + +We welcome contributions to the FICAM Playbooks in the form of requests, issues and pages: + +* _Requests:_ You have identified a useful addition to the playbook which benefits USG Agencies + * Open an Issue on this repository + * State the recommendation + * Include any links or other information + * Discuss the request with other contributors + +* _Issues:_ You have identified an issue with information on this site + * Open an Issue on this repository + * Discuss the Issue with other contributors + * Follow the progress of the updates + +* _Pages:_ You would like to contribute a page and content + * Open an Issue on this repository, identifying the content you would like to contribute + * Limit each Issue to one content topic + * Fork the repository + * Add a new Page or modify an existing Page with your suggested content, leveraging the [guidance document template]({{site.baseurl}}/template) to maintain a consistent page structure across the playbook. + * Submit a Pull Request, referencing the Issue Number + +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. + +#### 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 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. + +#### Thanks + +The idea for providing this content as open source, the contributing framework, and the licensing framework are based on work from [18F](https://18f.gsa.gov). diff --git a/pages/elements.md b/pages/elements.md index 684bf6ba..7bf11c22 100644 --- a/pages/elements.md +++ b/pages/elements.md @@ -3,25 +3,32 @@ layout: page title: Elements of a PIV Card permalink: /elements/ --- -Many of the design features and data elements on the PIV card enable enhanced security and privacy when used to verify a claimed identity. The features of the PIV card can be broken out into two main categories: physical card features, including security features and visual card topography, and the data objects stored electronically on the embedded integrated-circuit chip (ICC). +Many of the design features and data elements on the PIV card enable enhanced security and privacy when used to verify a claimed identity. The features of the PIV card can be broken out into two main categories: physical elements and logical elements. #### Physical Elements - - - - -
Element TypeDescriptionStandard Element
Security FeaturesThe PIV Card shall contain, at a minimum, one security feature that aids in reducing counterfeiting, is resistant to tampering, and provides visual evidence of tampering attempts.Optical varying structures, optical varying inks, laser etching and engraving, holograms, holographic images, watermarks -
Visual Card TopographyThe visual card topography for the PIV card specifies the information that is mandatory and optional and defines a common design for the placement of printed components.Front of Card - Photograph, Name, Employee Affiliation, Organizational Affiliation, Expiration Date -
Back of Card - Agency Card Serial Number, Issuer Identification -
+![Example of a PIV card and its physical components](../img/elements.png){:style="float:right"} -Most applications for the PIV card leverage the logical data elements on the card to perform electronic verification of a claimed identity. These data elements are defined as part of the PIV card data model, outlined in NIST SP 800-73. The PIV card data objects provide graduated levels of identity assurance and allow an agency the opportunity to select appropriate levels of security for applications being accessed with the PIV card. The following elements comprise the mandatory objects of the PIV card data model: +An example of a PIV card can be seen to the right. This image depicts the standard placing for physical card components such as photograph, name, affiliation, expiration date, organization, and the circuit chip to name a few. Physical elements that are not shown include a magnetic stripe and serial number. PIV cards also contain at least one security feature that aids in reducing counterfeiting, is resistant to tampering, and provides visual evidence of tampering attempts, such as optical varying structures or inks, laser etching, holographic images, and watermarks. -- Card Capability Container: An object that holds data sets and supports minimum capacity for retrieval of the Data Model. The Card Capability Container allows each PIV card to carry the information needed for software to communicate with the card -- Cardholder Unique Identifier (CHUID): A data element used by the card to prove the identity of the cardholder to an external entity. The CHUID includes a 16 byte Global Unique Identifier (GUID), a 25-byte Federal Agency Smart Credential Number (FASC-N), which uniquely identifies each card, expiration date, and issuer digital signature. -- Certificate for PIV Authentication: A certificate used with its associated private key to authenticate the card and the cardholder. -- Cardholder fingerprints: Primary and secondary fingerprint templates stored on the card for performing authentication. -- Security Object: Signed data object that enforces the integrity of unsigned information (and optionally all PIV data objects, excluding digital certificates). +#### Logical Elements -In addition to the mandatory data objects, there are also 28 optional data objects for interoperable use. Of particular note are the optional certificates that further support authentication and expanded uses, including encryption and digital signing. Digital certificates are a primary tool for performing electronic verification for logical access applications and for modernization of physical access applications. +Most applications that use PIV cards leverage the logical data elements on the card to perform verification of a claimed identity. These data elements are defined in NIST SP 800-73. The information on a PIV card allows an agency to select appropriate levels of security for applications being accessed. + +The following logical elements authenticate the PIV card: + +* **Cardholder Unique Identifier (CHUID)**, which is a digitally signed Federal Agency Smart Card Number (FASC-N) plus other elements that can be used to verify that the PIV card was issued by an authorized entity. +* **Card Authentication** can be used to verify that the PIV card was issued by an authorized entity, has not expired, and has not been revoked. + +The following logical elements authenticate the user: + +* **Photograph**, which is stored and signed digitally and allows a human to confirm that the printed photo on the card has not been altered. +* **Biometric Identity Information** such as fingerprints or iris, which can be used to verify the identity of the PIV card holder. +* **PIV Authentication** can be used to verify that the PIV card was issued by an authorized entity, has not expired, has not been revoked, and to verify that the holder of the card is the same individual it was issued to. + +The following logical elements are user-oriented capabilities: + +* **Digital Signature** allows the cardholder to digitally sign a document or email, providing both integrity and non-repudiation. +* **Digital Encryption** allows the cardholder to work with digitally encrypted documents or email, providing confidentiality through ensuring that only authorized parties con read the document. This includes a key history containing past encryption keys. + +Card and PIV authentication, digital signatures, and digital encryption all leverage private key, public key, and certificate technologies. diff --git a/pages/template.md b/pages/template.md index f19a94bb..d7ec82b5 100644 --- a/pages/template.md +++ b/pages/template.md @@ -34,32 +34,28 @@ This text will provide any reference information that may be needed to complete * This text names a link to a reference document [with the hyperlink text within brackets](and the actual URL within parentheses) #### Complete the following tasks: - -
- + +
### 1. Title of Procedure 1
-> This text will appear as a 'warning flag' on the website, which is a yellow banner. (The ">" symbol and the line directly underneath this body of text create the formatting for this flag.) Warning flags can be used for notifications such as notifying a user that they should skip a certain procedure. +> This text will appear as a 'warning flag' on the website, which is a yellow banner. (The ">" symbol and the line directly underneath this body of text create the formatting for this flag.) Warning flags can be used for notifications such as notifying a user that they should skip a certain procedure, ... {:class="warning"} -> This text will appear as a red banner, for an 'alert' message. Alert flags can be used for notifications such as common problems. +> This text will appear as a red banner, for an 'alert' message. Alert flags can be used for notifications such as common problems, ... {:class="alert"} -> This text will appear as a green banner, for an 'informational' message. These flags can be used for notifications such as useful links or helpful tips. +> This text will appear as a green banner, for an 'informational message. These flags can be used for notifications such as useful links, helpful tips, or... {:class="info"} -This is the main body text that explains the purpose of the procedure and any context that you might need before diving into the individual steps. The text within each step should walk the user directly through exactly what they need to do to complete the procedure. +This is the main body text that explains the purpose of the procedure and any context that you might need before diving into the individual steps. The text within each step should walk the user directly through exactly what they need to do to complete the procedure. **Text within double asterisks will appear as bolded.** *Text within single asterisks will appear as italicized.* For more information on formatting in markdown, go [here.](https://help.github.com/articles/basic-writing-and-formatting-syntax/) 1. Step 1 of the procedure... 2. Step 2 of the procedure... -**Text within double asterisks will appear as bolded.** This text is for separating a procedure into separate processes, if needed. +This text is for separating a procedure into separate processes, if needed. 1. Step 1 2. Step 2