# Understanding PEM vs P7B Certificates

## Quick Summary

**You CANNOT use P7B files to run your HTTPS server!**

- **PEM files** = Run your server with HTTPS ✓
- **P7B files** = Upload to Square Dashboard ✓

## The Complete Picture

```
┌─────────────────────────────────────────────────────────────┐
│                    Your HTTPS Server                        │
│                                                             │
│  Uses: cert.pem + key.pem (PEM format)                    │
│  Command: python src/test_server.py                        │
│           --ssl-cert cert.pem                              │
│           --ssl-key key.pem                                │
│           --hook-port 8443                                 │
└─────────────────────────────────────────────────────────────┘
                         │
                         │ HTTPS traffic
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                  Square's Servers                           │
│                                                             │
│  They verify your server using: cert.p7b                   │
│  (which YOU upload to Square Dashboard)                    │
└─────────────────────────────────────────────────────────────┘
```

## Why Two Formats?

### PEM Format (.pem files)
- **Contains**: Certificate AND private key (separate files)
- **Used by**: Your HTTPS server to encrypt traffic
- **Files needed**: 
  - `cert.pem` - Your public certificate
  - `key.pem` - Your private key (NEVER share this!)

### P7B Format (.p7b files)  
- **Contains**: Certificate ONLY (no private key)
- **Used by**: Square to verify webhook signatures
- **File**: `cert.p7b` - Uploaded to Square Dashboard

## Step-by-Step Workflow

### 1. Generate Certificates (PEM format)
```powershell
python generate_cert.py
```
**Creates:**
- `cert.pem` - Your certificate (public)
- `key.pem` - Your private key (secret!)

### 2. Start Your HTTPS Server (uses PEM)
```powershell
python src/test_server.py --ssl-cert cert.pem --ssl-key key.pem --hook-port 8443 --hook-ssl-only
```
**Server runs at:**
- `https://localhost:8443/hook`

### 3. Convert Certificate to P7B for Square
```powershell
python convert_to_p7b.py
```
**Creates:**
- `cert.p7b` - Certificate in P7B format (for Square)

### 4. Upload P7B to Square
1. Go to: https://developer.squareup.com/apps
2. Your App → **Webhooks** → **Manage Notification Settings**
3. Upload `cert.p7b`

### 5. Configure Square Webhook URL
- Enter: `https://yourdomain.com:8443/hook`
- Square will verify using the P7B you uploaded

## Common Mistakes

### ❌ Trying to use P7B with your server
```powershell
# THIS WON'T WORK!
python src/test_server.py --ssl-cert cert.p7b --ssl-key key.p7b
```
**Error:** P7B doesn't contain the private key needed for HTTPS!

### ✓ Correct usage
```powershell
# Server uses PEM files
python src/test_server.py --ssl-cert cert.pem --ssl-key key.pem --hook-port 8443

# P7B file is uploaded to Square Dashboard (not used by your server)
```

## If You Only Have a P7B File

If someone gave you a P7B file, you can extract the certificate:

```powershell
python convert_from_p7b.py your_cert.p7b --output cert.pem
```

**BUT:** You still need the private key (`key.pem`) to run HTTPS!

If you don't have the private key, you must:
1. Generate a new certificate pair: `python generate_cert.py`
2. Or get the private key from whoever created the P7B

## File Checklist

To run your HTTPS server with Square webhooks, you need:

- [ ] `cert.pem` - Certificate (PEM format) - For your server
- [ ] `key.pem` - Private key (PEM format) - For your server  
- [ ] `cert.p7b` - Certificate (P7B format) - Upload to Square

Generate all three with:
```powershell
python generate_cert.py      # Creates cert.pem and key.pem
python convert_to_p7b.py      # Creates cert.p7b from cert.pem
```

## Security Notes

- **Never share `key.pem`** - This is your private key!
- **`cert.pem` is public** - Safe to share
- **`cert.p7b` is public** - You upload this to Square
- Self-signed certificates are fine for testing but use Let's Encrypt for production

## Need Help?

See the detailed guides:
- `HTTPS_SETUP.md` - Complete HTTPS setup instructions
- `SQUARE_WEBHOOK_SETUP.md` - Square webhook configuration