studspider/doc/CERTIFICATE_FORMATS.md

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)

python generate_cert.py

Creates:

• cert.pem - Your certificate (public)
• key.pem - Your private key (secret!)

2. Start Your HTTPS Server (uses PEM)

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

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

# 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

# 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:

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:

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