137 lines
4.8 KiB
Markdown
137 lines
4.8 KiB
Markdown
# 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
|