143 lines
4.2 KiB
Markdown
143 lines
4.2 KiB
Markdown
# Certificate API
|
|
*Library of Code sp-us | Board of Directors*
|
|
|
|
This is an HTTP API which provides information on the x509 certificates deployed on TLS sites.
|
|
You can self-host this yourself, however you're more than welcome to use the public API at https://certapi.libraryofcode.org/
|
|
|
|
## Installation
|
|
Run `make` to build the binary. It'll be installed in `build/certificateapi`. Simply run this executable.
|
|
### Environment Variables
|
|
By default, the application listens on port `8080`. You can change this by setting the `PORT` environment variable to what you want.
|
|
When running in production, set this environment variable: `GIN_MODE=release`
|
|
|
|
## How to Query Information for Websites
|
|
Send a GET request to `https://certapi.libraryofcode.org` with the query parameter `q` set to equal the site you wish to dial.
|
|
Ex: `https://certapi.libraryofcode.org/?q=www.google.com`
|
|
|
|
### Response & Types
|
|
#### Error
|
|
If the status !== `true`, there will be a message field which displays the error.
|
|
```ts
|
|
{
|
|
status: false,
|
|
message: string,
|
|
}
|
|
```
|
|
|
|
### 200 | SUCCESS
|
|
```ts
|
|
{
|
|
status: true | false,
|
|
subject: {
|
|
commonName: string,
|
|
organization: string[],
|
|
organizationalUnit: string[],
|
|
locality: string[],
|
|
country: string[],
|
|
},
|
|
issuer: {
|
|
commonName: string,
|
|
organization: string[],
|
|
organizationalUnit: string[],
|
|
locality: string[],
|
|
country: string[],
|
|
},
|
|
validationType: 'DV' | 'OV' | 'EV',
|
|
signatureAlgorithm: string,
|
|
publicKeyAlgorithm: string,
|
|
serialNumber: number,
|
|
notAfter: Date,
|
|
/**
|
|
- 0: KeyUsageCRLSign
|
|
- 1: KeyUsageCertificateSign
|
|
- 2: KeyUsageContentCommitment
|
|
- 3: KeyUsageDataEncipherment
|
|
- 4: KeyUsageDecipherOnly
|
|
- 5: KeyUsageDigitalSignature
|
|
- 6: KeyUsageEncipherOnly
|
|
- 7: KeyUsageKeyAgreement
|
|
- 8: KeyUsageKeyEncipherment
|
|
*/
|
|
keyUsage: number[],
|
|
keyUsageAsText: ['CRL Signing', 'Certificate Signing', 'Content Commitment', 'Data Encipherment', 'Decipher Only', 'Digital Signature', 'Encipher Only', 'Key Agreement', 'Key Encipherment'],
|
|
/**
|
|
- 0: Any/All Usage
|
|
- 1: TLS Web Server Auth
|
|
- 2: TLS Web Client Auth
|
|
- 3: Code Signing
|
|
- 4: Email Protection (S/MIME)
|
|
*/
|
|
extendedKeyUsage: number[],
|
|
extendedKeyUsageAsText: ['All/Any Usages', 'TLS Web Server Authentication', 'TLS Web Client Authentication', 'Code Signing', 'E-mail Protection (S/MIME)'],
|
|
san: string,
|
|
fingerprint: string,
|
|
connection: {
|
|
cipherSuite: string,
|
|
tlsVersion: 'SSLv3' | 'TLSv1' | 'TLSv1.1' | 'TLSv1.2' | 'TLSv1.3',
|
|
},
|
|
}
|
|
```
|
|
|
|
## How to Parse PEM-Encoded X509 certificate data
|
|
Submit a POST request to https://certapi.libraryofcode.org/ with the body being the raw/text content of the PEM encoded certificate.
|
|
|
|
### Response & Types
|
|
#### Error
|
|
If the status !== `true`, there will be a message field which displays the error.
|
|
```ts
|
|
{
|
|
status: false,
|
|
message: string,
|
|
}
|
|
```
|
|
|
|
### 200 | SUCCESS
|
|
```ts
|
|
{
|
|
status: true | false,
|
|
subject: {
|
|
commonName: string,
|
|
organization: string[],
|
|
organizationalUnit: string[],
|
|
locality: string[],
|
|
country: string[],
|
|
},
|
|
issuer: {
|
|
commonName: string,
|
|
organization: string[],
|
|
organizationalUnit: string[],
|
|
locality: string[],
|
|
country: string[],
|
|
},
|
|
validationType: 'DV' | 'OV' | 'EV',
|
|
signatureAlgorithm: string,
|
|
publicKeyAlgorithm: string,
|
|
serialNumber: number,
|
|
notAfter: Date,
|
|
/**
|
|
- 0: KeyUsageCRLSign
|
|
- 1: KeyUsageCertificateSign
|
|
- 2: KeyUsageContentCommitment
|
|
- 3: KeyUsageDataEncipherment
|
|
- 4: KeyUsageDecipherOnly
|
|
- 5: KeyUsageDigitalSignature
|
|
- 6: KeyUsageEncipherOnly
|
|
- 7: KeyUsageKeyAgreement
|
|
- 8: KeyUsageKeyEncipherment
|
|
*/
|
|
keyUsage: number[],
|
|
keyUsageAsText: ['CRL Signing', 'Certificate Signing', 'Content Commitment', 'Data Encipherment', 'Decipher Only', 'Digital Signature', 'Encipher Only', 'Key Agreement', 'Key Encipherment'],
|
|
/**
|
|
- 0: Any/All Usage
|
|
- 1: TLS Web Server Auth
|
|
- 2: TLS Web Client Auth
|
|
- 3: Code Signing
|
|
- 4: Email Protection (S/MIME)
|
|
*/
|
|
extendedKeyUsage: number[],
|
|
extendedKeyUsageAsText: ['All/Any Usages', 'TLS Web Server Authentication', 'TLS Web Client Authentication', 'Code Signing', 'E-mail Protection (S/MIME)'],
|
|
san: string,
|
|
fingerprint: string,
|
|
}
|
|
```
|