Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/NationalSecurityAgency/MADCert
Create root and intermediate Certificate Authorities, issue user and server certificates, etc. for testing purposes.
https://github.com/NationalSecurityAgency/MADCert
Last synced: about 1 month ago
JSON representation
Create root and intermediate Certificate Authorities, issue user and server certificates, etc. for testing purposes.
- Host: GitHub
- URL: https://github.com/NationalSecurityAgency/MADCert
- Owner: NationalSecurityAgency
- License: other
- Created: 2018-08-17T22:18:15.000Z (over 6 years ago)
- Default Branch: main
- Last Pushed: 2024-06-16T20:11:46.000Z (6 months ago)
- Last Synced: 2024-11-09T04:39:52.657Z (about 1 month ago)
- Language: JavaScript
- Homepage:
- Size: 143 KB
- Stars: 103
- Watchers: 10
- Forks: 39
- Open Issues: 1
-
Metadata Files:
- Readme: README.MD
- Contributing: CONTRIBUTING_IO.md
- License: LICENSE.md
Awesome Lists containing this project
- awesome-starz - NationalSecurityAgency/MADCert - Create root and intermediate Certificate Authorities, issue user and server certificates, etc. for testing purposes. (JavaScript)
- Firmware-Guide - MADCert - platform tool that consists of a certificate generator, a file system certificate manager, and a command line interface for the purposes of testing. (Security Tools)
README
# 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 [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|