README
¶
go-piv
This library has a small set of PIV peculiar extensions to a standard x.509 Certificate. This will parse out Subject Alternative Names common to PIV Certificates, as well as any custom Extensions.
This is to be used in conjunction with a crypto/x509.Certificate, and the
piv.Certificate embeds an crypto/x509.Certificate as an anonymous
member.
What's PIV?
PIV Cards are cards defined by FIPS 201, a Federal US Government standard defining the ID cards employees use. At its core, it's a set of x509 Certificates and corresponding private keys in a configuration that is standardized across implementations.
For more details on how PIV Tokens can be used, the FICAM (Federal Identity, Credential, and Access Management) team at GSA (General Services Administration) has published some guides on GitHub under GSA/piv-guides
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func HasNACI ¶
func HasNACI(cert *x509.Certificate) *bool
HasNACI will check to see if the PIV Certificate in question has the id-piv-NACI ObjectIdentifier, and if so, return the answer to if the NACI has been run on the cardholder.
This is sometimes wrong (usually in saying 'no' when someone actually has had a NACI -- or better than NACI check!), so please ensure this is never used as an authoritative source of truth for someone's level of vetting.
Types ¶
type AssuranceLevel ¶ added in v0.1.1
type AssuranceLevel uint
AssuranceLevel is an enum type defining the levels of assurance.
var ( // UnknownAssurance, as defined by the PIV specs. UnknownAssurance AssuranceLevel = 0 // RudimentaryAssurance, as defined by the PIV specs. RudimentaryAssurance AssuranceLevel = 1 // BasicAssurance, as defined by the PIV specs. BasicAssurance AssuranceLevel = 2 // MediumAssurance, as defined by the PIV specs. MediumAssurance AssuranceLevel = 3 // HighAssurance, as defined by the PIV specs. HighAssurance AssuranceLevel = 4 )
This is *not* an LOA number as defined by OMB M04-04
func (AssuranceLevel) Compare ¶ added in v0.1.1
func (a AssuranceLevel) Compare(other AssuranceLevel) int
Compare returns -1 if the LOA this function is bound to is _less_ strict than the given LOA, 0 if they're the same, and 1 if the bound LOA is _more_ strict than the given LOA.
MediumAssurance.Compare(RudimentaryAssurance) // -1 MediumAssurance.Compare(HighAssurance) // 1 MediumAssurance.Compare(MediumAssurance) // 0
func (AssuranceLevel) String ¶ added in v0.1.1
func (a AssuranceLevel) String() string
String will return the value as a human readable string.
type Certificate ¶
type Certificate struct {
*x509.Certificate
Subject Name
// This field is a largely unreliable and poor indicator of the cardholder's
// level of vetting -- it merely asserts as to if the cardholder has a
// completed NACI at the time of card issue. If the cardholder has other
// (sometimes supersets!) of the NACI, this may not be true.
//
// Additionally, not all agencies set this extension, and it's not widely
// used enough to be considered accurate. It's being parsed for any legacy
// uses of this extension.
CompletedNACI *bool
// UPN or the Universal Principal Name is a email-like key that can be used
// by the operating system or directory server to determine which account to
// grant this smartcard access to.
//
// These are *not* valid Emails. For the cardholder's email, access the
// standard x509.EmailAddresses SAN.
PrincipalNames []string
// FASC, or Federal Agency Smartcard Number, is a legacy field that was
// used to enable building access control systems. It's largely not used
// but still written to new Certificates.
FASCs []fasc.FASC
// Standards applied to the issuance of this Certificate, such as the
// amount of checking into a Person's identity, if this was even a Person,
// or if the key is stored on a hardware token.
Policies Policies
}
Certificate is an extension of the built-in crypto/x509.Certificate type. This contains the Certificate as an anonymous member of the piv.Certificate struct, as well as some PIV peculiar OID values, such as the Microsoft UPN (used for smartcard login), FASCs and if the cardholder has a completed NACI.
func NewCertificate ¶
func NewCertificate(cert *x509.Certificate) (*Certificate, error)
NewCertificate will create a piv.Certificate from a standard crypto/x509.Certificate, parsing the various PIV peculiar fields.
func ParseCertificate ¶
func ParseCertificate(bytes []byte) (*Certificate, error)
ParseCertificate will parse the raw DER into an x.509 Certificate struct, then parse out PIV specific fields. This is shorthand for calling x509.ParseCertificate, then passing that into piv.NewCertificate.
type Issued ¶
type Issued struct {
// This is true if the Key is used on a hardware device that does not
// allow the export of the private key material.
Hardware bool
// This is true if the Key is held by a Person, and False if it's held
// by a Non-Person Entity (NPE).
Person bool
// Level of Assurance that the identity of the subscriber is the actual
// identity in this Certificate.
AssuranceLevel AssuranceLevel
}
Issued contains information about the Key that belongs to the issued Certificate. This contains information about the type of device that holds the key, as well as the subscriber that that it was issued to.
type Name ¶
type Name struct {
pkix.Name
// Any User IDs for any systems the cardholder may be using. This is an
// optional Name that may be present in the Subject pkix.Name.
UserID []string
}
Name is an extension of the built-in crypto/x509/pkix.Name type. This contains the pkix.Name plus additional fields, such as the UserID field.
type Policies ¶
type Policies []Policy
Policies are a set of Policy descriptions.
func ParsePolicies ¶
func ParsePolicies(ids []asn1.ObjectIdentifier) Policies
ParsePolicies will read a list of ObjectIdentifier objects, and return the known Policy objects as a set of Policies.
func (Policies) HighestAssurance ¶
func (p Policies) HighestAssurance() AssuranceLevel
HighestAssurance returns the highest assurance level contained within the set of policies. This is most useful when looking at the set of policies a specific credential was issued under.
type Policy ¶
type Policy struct {
// Name of the Policy for humans to better understand.
Name string
// Identifier of the ASN.1 ObjectId of this Policy.
ID asn1.ObjectIdentifier
// Information about the key material and subscriber.
Issued Issued
}
Policy is information regarding the level of assurance and a human readable name for a specific federal PIV or CAC policy.
type Token ¶ added in v0.1.3
type Token interface {
AuthenticationCertificate() (*Certificate, error)
DigitalSignatureCertificate() (*Certificate, error)
KeyManagementCertificate() (*Certificate, error)
CardAuthenticationCertificate() (*Certificate, error)
}
Source Files
Directories