Skip to content

NationalSecurityAgency/MADCert

main
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
src
 
 
 
 
 
 
 
 
 
 
 
 
 
 

MADCert

Use MADCert to create root and intermediate Certificate Authorities, issue user and server certificates, etc for testing purposes.

MADCert is a cross-platform tool that consists of a certificate generator, a file system certificate manager, and a command line interface.

MADCert does not require openssl or any other programs to be installed in the Operating System.

Both Node.js and CLI examples are provided below.

Usage

Node.js Examples

To add MADCert to your project:

npm install madcert

var madcert = require("madcert")
  • Create a Certificate Authority (CA)

    madcert.createCACert("Test Root CA", {validFrom: "2019-08-08", validTo: "2024-08-09"})
    
  • Create an Intermediate CA (Root CA must exist)

    madcert.createIntermediateCACert("Test CA","rootCA", {validFrom: "2019-08-08", validTo: "2024-08-09"});
    
  • Create a Server Certificate (CA must exist)

    madcert.createServerCert("Test Server", "test-ca", false, {validFrom: "2019-08-08", validTo: "2024-08-09"});
    
  • Create a localhost Server Certificate (CA must exist)

    madcert.createServerCert("localhost", "test-ca", true, {validFrom: "2019-08-08", validTo: "2024-08-09"});
    
    Note: A subject alternative name is automatically added to the generated certificate.  See ENVIRONMENT above.
    
  • Create a User Certificate with CN=test-user (CA must exist)

    madcert.createUserCert("test-user", "test-ca", {commonName: "test-user", organizationalUnits: ["SECURITY", "A456"], organizations: ["Some Organization"], country: "US", validFrom: "2019-08-08", validTo: "2024-08-09"});
    
  • Create a User Certificate CN=Alice Example (CA must exist)

    madcert.createUserCert("Alice Example", "test-ca", {commonName: "Alice Example", organizationalUnits: ["SECURITY", "A456"], organizations: ["Some Organization"], country: "US", validFrom: "2019-08-08", validTo: "2024-08-09"});
    
  • List CA Certificates

    madcert.listCACerts();
    
  • List Server Certificates

    madcert.listServerCerts();
    
  • List User Certificates

    madcert.listUserCerts();
    
  • Remove a CA Certificate

    madcert.removeCACert("test-root-ca");
    
  • Remove a Server Certificate

    madcert.removeServerCert("test-server", "test-ca");
    
  • Remove a User Certificate

    madcert.removeUserCert("test-user", "test-ca");
    
  • Retrieve a CA Certificate as JSON

    madcert.caCertToJSON("test-root-ca");
    
  • Retrieve a Server Certificate as JSON

    madcert.serverCertToJSON("test-server", "test-ca");
    
  • Retrieve a User Certificate as JSON

    madcert.userCertToJSON("test-user", "test-ca");
    
  • Convert name to a File Path Friendly Name

     madcert.normalizeName("Test 123");
     > 'test-123'
    

Additional Node.js Options

Certificate Storage Location

By default, the certs created by MADCert will be placed under a "pki" folder in the current working directory. MADCert commands also have the basePath option to specify a top-level path where the certs will be stored. It is important that all of the certs are placed under the same top-level folder, so either run MADCert from within the same location each time or always provide the same basepath option when calling the MADCert commands.

  • Example Specifying the Certificate Storage Location (available on all certificate related commands)

      madcert.createCACert("Test Root CA", {validFrom: "2019-08-08", validTo: "2024-08-09", basePath: "/some/path"})
    

CLI Examples

  • General Syntax

    npx madcert <command> <arguments> [options]
    
  • Help

    npx madcert --help
    

    The MADCert options are grouped in the help output by the commands that they can be used with.

    • Creation Options - these options can be used with any of the commands that create PKI files for CAs, servers, and users
    • User Creation Options - these options can be used with the user-create command
    • Server Creation Options - these options can be used with the server-create command
    • Print Options - these options can be used with the ca-print, server-print, and user-print commands
    • Options - these options are not specific to any particular command
  • Create a Certificate Authority (CA)

    npx madcert ca-create test-root-ca --common-name "Test Root CA" --org "Some Organization" --country "US"
    
  • Create an Intermediate CA (Root CA must exist)

    npx madcert ca-intermediate-create test-ca test-root-ca --common-name "Test CA" --org-unit "orgA" --org-unit "A123" --org "Some Organization" --country "US"
    
  • Create a Server Certificate (CA must exist)

    npx madcert server-create test-server test-ca --common-name "test.server" --org-unit "S333" --org "Some Organization" --country "US" --subject-alt-ip "123.45.23.111"
    
  • Create a localhost Server Certificate (CA must exist)

    npx madcert server-create localhost test-ca --localhost true --common-name "localhost" --org-unit "D009" --org-unit "DoD" --org "U.S. Government" --country "US"
    
    Note: A subject alternative name is automatically added to the generated certificate.  See ENVIRONMENT above.
    
  • Create a User Certificate with CN=test-user (CA must exist)

    npx madcert user-create test-user test-ca --org-unit "SECURITY" --org-unit "A456" --org "Some Organization" --country "US"
    
  • Create a User Certificate CN=Alice Example (CA must exist)

    npx madcert user-create test-user test-ca --common-name "Alice Example" --org-unit "SECURITY" --org-unit "A456" --org "Some Organization" --country "US"
    
  • List CA Certificates

    npx madcert ca-list
    
  • List Server Certificates

    npx madcert server-list
    
  • List User Certificates

    npx madcert user-list
    
  • Remove a CA Certificate

    npx madcert ca-remove test-ca
    
  • Remove a Server Certificate

    npx madcert server-remove test-server test-ca
    
  • Remove a User Certificate

    npx madcert user-remove test-user test-ca
    
  • Print a CA Certificate

    npx madcert ca-print test-ca
    
  • Print a Server Certificate

    npx madcert server-print test-server test-ca
    
  • Print a User Certificate

    npx madcert user-print test-user test-ca
    

Additional CLI Options

Certificate Storage Location

By default, the certs created by MADCert will be placed under a "pki" folder in the current working directory. MADCert commands also have the --path or -p option to specify a top-level path where the certs will be stored. It is important that all of the certs are placed under the same top-level folder, so either run MADCert from within the same directory each time or always provide the same path option when calling the MADCert commands.

Environment

  • MADCERT_LH_SUBJECT_ALT_DNS_NAME - Only used when creating a localhost server certificate (--localhost true). When generating a localhost server certificate, MADCert will add a subject alternative DNS name to the certificate. This environment variable can be used to specify the subject alternative DNS name that will be added. If this environment variable is not set, then the host name will be used.

Arguments

Alias Type Default Value Description
name String Name is used for the name of the directory under which PKI files are created. If the --common-name option is not used then name will also be used for the Common Name in the certificate subject.
ca-name String CA name is used to identify the Certificate Authority to use when creating or removing users and servers.
root_ca-name -r String When creating an intermediate Certificate Authority, root_ca_name identifies the root CA that issues the intermediate CA's certificate.
path -p String '/pki' Base path for pki
common-name -n String Common Name in the Distinguished Name
country -c String Country
locality String Locality
state -st String State
expired -e Boolean Create an expired certificate
org -o Array Organization name. This option can be specified multiple times
org-unit -u Array Organizational unit name. This option can be specified multiple times.
password -w String 'changeme' Certificate password
subject-alt-dns -d Array Create certificate with DNS subject alternative name. This option can be specified multiple times and only applies to server certs.
subject-alt-ip -i Array Create certificate with IP subject alternative name. This option can be specified multiple times and only applies to server certs.
subject-alt-email -m Array Create certificate with rfc822/email subject alternative name. This option can be specified multiple times and only applies to server certs.
valid-from -f Date Valid from date in ISO 8601 format
valid-to -t Date Valid to date in ISO 8601 format

About

Create root and intermediate Certificate Authorities, issue user and server certificates, etc. for testing purposes.

Resources

License

Stars

Watchers

Forks

Packages

No packages published