certificate-api/README.md

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.

{
  status: false,
  message: string,
}

200 | SUCCESS

{
  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.

{
  status: false,
  message: string,
}

200 | SUCCESS

{
  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[],
  },
  aia: {
    issuingCertificateURL: string,
    ocspServer: 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,
  emailAddresses: string,
  fingerprint: string,
}