SecurityDataParsers

A collection small parsing tools to aid in extracting the underlying values in some data formats commonly found in authentication or identity certificates.

Project	Description	NuGet
FederalAgencySmartCredentialNumber	A class for extracting all the good data from FASCN codes (Agency, Org, ID, Employment Type, etc..)
SubjectAlternativeName	A class for digging into all the possible extension data on certs (e.g. FASCN, X400 Address, Edi Party Name)

Installation

Install one of the packages with NuGet

    Install-Package SecurityDataParsers.FederalAgencySmartCredentialNumber
    Install-Package SecurityDataParsers.SubjectAlternativeName

Or via the .NET Core command line interface:

    dotnet add package SecurityDataParsers.FederalAgencySmartCredentialNumber
    dotnet add package SecurityDataParsers.SubjectAlternativeName

Either commands, from Package Manager Console or .NET Core CLI, will download and install the packages.

TODO

• Increasing test coverage

Usage

Federal Agency Smart Credential Number (FASCN)

  using SecurityDataParsers.FederalAgencySmartCredentialNumber;
  // Load the smart card certificate, or any cert you want to check for a FASCN
  X509Certificate2 cert = new X509Certificate2("path/to/certificate.pfx", "password");
  // Smart card certificates are usually cached in windows personal cert store,
  // so you can pull it as only the public portion and still pull the FASCN off it.

  // Create a new FASCN object
  FASCN fascnObj = FASCN.fromCertificate(cert);

  // Extract the identifying properties from the FASCN object
  
  // Identifies the government agency issuing the credential
  string agencyCode = fascnObj.AgencyCode.GetFriendlyName();
  
  // Identifies the system the card is enrolled in and is unique for each site
  // 4 digits stored as bytes
  (byte, byte, byte, byte) systemCode = fascnObj.SystemCode.AsTuple();
  
  // Encoded by the issuing agency. For a given system no duplicate numbers are active.
  // 6 digits stored as bytes, too many possibilities to enumerate all possible friendly names, so it's up to the user to find agency codes.
  (byte, byte, byte, byte, byte, byte) credentialNumber = fascnObj.CredentialNumber.AsTuple();
  
  // Single reserved digit. Field is available to reflect major system changes
  ValueTuple<byte> credentialSeries = fascnObj.CredentialSeries.AsTuple();
  
  // Usually a 1, but will be incremented if a card is replaced due to loss or damaged
  ValueTuple<byte> individualCredentialIssue = fascnObj.IndividualCredentialIssue.AsTuple();
  
  // Numeric Code used by the identity source to uniquely identify the token carrier
  // 10 digits stored as bytes, this is what is usually the User ID
  byte[] personIdentifier = fascnObj.PersonIdentifier.Digits;
  
  // Type of Organization the individual is affiliated with; whether it is Federal, State, Commercial, or Foreign
  string organizationalCategory = fascnObj.OrganizationalCategory.GetFriendlyName();
  
  // The Identifier that identifies the organization the individual is affiliated with.
  // 4 digits stored as bytes
  (byte, byte, byte, byte) organizationIdentifier = fascnObj.OrganizationIdentifier.AsTuple();
  
  // Indicates the affiliation type the individual has with the Organization, including their employment type.
  string personOrOrganizationAssociationCategory = fascnObj.PersonOrOrganizationAssociationCategory.GetFriendlyName();

Subject Alternative Name (SAN)

using SecurityDataParsers.SubjectAlternativeName;

// Load the certificate you want get data from
var cert = new X509Certificate2("path/to/certificate.pfx", "password");

// Get the SAN extension
var sanExtension = cert.Extensions["2.5.29.17"];
// Parse the SAN extension
var san = new SAN(sanExtension);

// Or let the SAN class extract it itself
var san = new SAN(cert);


// Destructure the SAN extension to get its properties
var (
  fASCN,
  principalName,
  rfc822Name,
  dnsName,
  x400Address,
  directoryName,
  ediPartyName,
  uniformResourceIdentifier,
  iPAddress,
  registeredID
) = san.First;

// Use the properties as needed
Console.WriteLine($"FASCN: {fASCN.personIdentifier}");
Console.WriteLine($"Principal Name: {principalName}");

// If it contains multiples, the base class contains lists you can check.
san.dnsNames.Select(v => Console.WrtitLine(v.Host))

API

See the packages' respective READMEs

• FederalAgencySmartCredentialNumber
• SubjectAlternativeName

Or the generated API docs

FederalAgencySmartCredentialNumber (FASCN)

See the API docs: FederalAgencySmartCredentialNumber/docs/README.md

SubjectAlternativeName (SAN)

See the API docs: SubjectAlternativeName/docs/README.md

Changelog

Take a look at the CHANGELOG.md.

Contribution

You're free to contribute to this project by submitting issues and/or pull requests.

Please keep in mind that every change and feature should be covered by tests.

License

This project is licensed under MIT.

Contributors