<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->

# API Reference — Analyzing TLS Certificate Chains

## openssl s_client

### Synopsis

```bash
openssl s_client -connect <host>:<port> [options] < /dev/null
```

### Key Options

| Option | Description |
|---|---|
| `-showcerts` | Display all certificates in the chain |
| `-verify <depth>` | Set maximum chain verification depth |
| `-CAfile <path>` | Specify CA bundle for verification |
| `-servername <host>` | Set SNI hostname for virtual hosts |
| `-starttls <proto>` | Use STARTTLS for smtp, imap, ftp, etc. |
| `-brief` | Show brief connection summary |

## openssl x509

### Synopsis

```bash
openssl x509 -in <cert.pem> [options]
```

### Key Options

| Option | Description |
|---|---|
| `-text` | Full certificate details |
| `-noout` | Suppress PEM output |
| `-dates` | Show notBefore and notAfter |
| `-subject` | Show subject DN |
| `-issuer` | Show issuer DN |
| `-serial` | Show serial number |
| `-fingerprint` | Show SHA-1 fingerprint |
| `-ocsp_uri` | Extract OCSP responder URL |
| `-purpose` | Show certificate purposes |

## openssl verify

### Synopsis

```bash
openssl verify [-CAfile bundle.pem] [-untrusted intermediate.pem] cert.pem
```

### Exit Codes

| Code | Meaning |
|---|---|
| `0` | Verification succeeded |
| `2` | Unable to get issuer certificate |
| `10` | Certificate has expired |
| `18` | Self-signed certificate |
| `20` | Unable to get local issuer certificate |

## openssl ocsp

### Synopsis

```bash
openssl ocsp -issuer issuer.pem -cert cert.pem -url <ocsp_url> [-resp_text]
```

### Response Status Values

| Status | Meaning |
|---|---|
| `good` | Certificate is not revoked |
| `revoked` | Certificate has been revoked |
| `unknown` | Responder has no information |

## Agent Script

```bash
# Retrieve certificate chain
node agent.js retrieve example.com

# Inspect a local certificate
node agent.js inspect cert.pem

# Verify chain with CA and intermediate
node agent.js verify leaf.pem --ca root.pem --untrusted intermediate.pem

# Check OCSP status
node agent.js ocsp cert.pem --issuer issuer.pem --url http://ocsp.example.com

# Check certificate expiry
node agent.js expiry example.com
```
