qubesec.github.io/docs/quickstart.md at main · QubeSec/qubesec.github.io

quickstart

title

Quick Start & Examples - QubeSec

description

Get started with QubeSec in minutes. Install the operator, generate quantum-safe keys, and secure your Kubernetes applications with post-quantum cryptography.

keywords

quickstart

installation

kubernetes operator

post-quantum examples

Before You Begin

Kubernetes cluster v1.20+
kubectl configured with cluster access
QubeSec operator installed on the cluster
5-10 minutes of your time

Installation

Install QubeSec operator with a single command:

# Install the operator (CRDs, deployment, RBAC, namespace, and services)
kubectl apply -f https://github.com/QubeSec/QubeSec/raw/main/dist/install.yaml

# Verify installation
kubectl get pods -n qubesec-system
kubectl api-resources | grep qubesec

Example 1: Generate Random Bytes

Create cryptographically secure random numbers for your applications:

cat > random-numbers.yaml << 'EOF'
apiVersion: qubessec.io/v1
kind: QuantumRandomNumber
metadata:
  name: my-random
spec:
  numBytes: 32
EOF

kubectl apply -f random-numbers.yaml
kubectl get qrn my-random -w  # Watch until Success
kubectl get qrn my-random -o jsonpath='{.status.fingerprint}'

Retrieve the random data:

kubectl get secret my-random -o jsonpath='{.data.random}' | base64 -d | xxd

Example 2: Post-Quantum Key Exchange

Implement secure key exchange using Kyber (ML-KEM-1024):

cat > key-exchange.yaml << 'EOF'
# Step 1: Alice generates a keypair
apiVersion: qubessec.io/v1
kind: QuantumKEMKeyPair
metadata:
  name: alice-keypair
spec:
  algorithm: Kyber1024

---
# Step 2: Bob encapsulates using Alice's public key
apiVersion: qubessec.io/v1
kind: QuantumEncapsulateSecret
metadata:
  name: bob-encapsulate
spec:
  algorithm: Kyber1024
  publicKeyRef:
    name: alice-keypair

---
# Step 3: Alice decapsulates to recover the same secret
apiVersion: qubessec.io/v1
kind: QuantumDecapsulateSecret
metadata:
  name: alice-decapsulate
spec:
  algorithm: Kyber1024
  privateKeyRef:
    name: alice-keypair
  ciphertextRef:
    name: bob-encapsulate

---
# Step 4: Derive AES-256 encryption keys
apiVersion: qubessec.io/v1
kind: QuantumDerivedKey
metadata:
  name: shared-aes-key
spec:
  sharedSecretRef:
    name: alice-decapsulate
  keyLength: 32
  outputSecretName: final-encryption-key
EOF

kubectl apply -f key-exchange.yaml

Verify the key exchange succeeded:

# Wait for all resources
kubectl get qkkp,qes,qds,qdk -w

# Verify fingerprints match (proof of successful key exchange)
echo "Bob's shared secret fingerprint:"
kubectl get qes bob-encapsulate -o jsonpath='{.status.fingerprint}'

echo "Alice's recovered secret fingerprint:"
kubectl get qds alice-decapsulate -o jsonpath='{.status.fingerprint}'

# Both should be identical!

# Get the final AES-256 encryption key
kubectl get secret final-encryption-key -o jsonpath='{.data.key}' | base64 -d | xxd

Example 3: Digital Signatures

Sign and verify messages using post-quantum algorithms:

cat > signatures.yaml << 'EOF'
# Create signature keypair
apiVersion: qubessec.io/v1
kind: QuantumSignatureKeyPair
metadata:
  name: signer-keys
spec:
  algorithm: Dilithium3  # ML-DSA-65

---
# Create a message to sign
apiVersion: v1
kind: Secret
metadata:
  name: my-message
type: Opaque
stringData:
  content: "Important message that needs signature"

---
# Sign the message
apiVersion: qubessec.io/v1
kind: QuantumSignMessage
metadata:
  name: sign-message
spec:
  privateKeyRef:
    name: signer-keys
  messageRef:
    name: my-message
  algorithm: Dilithium3
  outputSecretName: my-signature

---
# Verify the signature
apiVersion: qubessec.io/v1
kind: QuantumVerifySignature
metadata:
  name: verify-message
spec:
  publicKeyRef:
    name: signer-keys
  messageRef:
    name: my-message
  signatureRef:
    name: my-signature
  algorithm: Dilithium3
EOF

kubectl apply -f signatures.yaml
kubectl get qskp,qsm,qvs -w

Check verification result:

# Get verification status
kubectl get qvs verify-message -o jsonpath='{.status.status}'
# Output: Valid (or Invalid if signature doesn't match)

# Get the signature
kubectl get secret my-signature -o jsonpath='{.data.signature}' | base64 -d > signature.bin

Example 4: Post-Quantum Certificates

Create an X.509 certificate for TLS:

cat > certificate.yaml << 'EOF'
apiVersion: qubessec.io/v1
kind: QuantumCertificate
metadata:
  name: my-service-cert
spec:
  algorithm: Dilithium3
  certType: self-signed
  commonName: "my-service.default.svc.cluster.local"
  subjectAltNames:
    - "my-service"
    - "my-service.default"
    - "my-service.default.svc.cluster.local"
  organization: "My Organization"
  country: "US"
  durationDays: 365
EOF

kubectl apply -f certificate.yaml
kubectl get qc my-service-cert -w

Use the certificate in your Ingress:

cat > ingress.yaml << 'EOF'
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-ingress
spec:
  tls:
  - hosts:
    - my-service.default.svc.cluster.local
    secretName: my-service-cert-secret
  rules:
  - host: my-service.default.svc.cluster.local
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: my-service
            port:
              number: 443
EOF

kubectl apply -f ingress.yaml

Example 5: Complete Multi-Step Workflow

Combine multiple resources for a comprehensive security setup:

cat > complete-workflow.yaml << 'EOF'
---
# 1. Generate random seed material
apiVersion: qubessec.io/v1
kind: QuantumRandomNumber
metadata:
  name: workflow-seed
spec:
  numBytes: 64

---
# 2. Create signature keys
apiVersion: qubessec.io/v1
kind: QuantumSignatureKeyPair
metadata:
  name: workflow-signer
spec:
  algorithm: Dilithium3

---
# 3. Create KEM keypair
apiVersion: qubessec.io/v1
kind: QuantumKEMKeyPair
metadata:
  name: workflow-kem
spec:
  algorithm: Kyber1024

---
# 4. Encapsulate using public key
apiVersion: qubessec.io/v1
kind: QuantumEncapsulateSecret
metadata:
  name: workflow-encapsulate
spec:
  algorithm: Kyber1024
  publicKeyRef:
    name: workflow-kem

---
# 5. Derive encryption key
apiVersion: qubessec.io/v1
kind: QuantumDerivedKey
metadata:
  name: workflow-derived-key
spec:
  sharedSecretRef:
    name: workflow-encapsulate
  keyLength: 32

---
# 6. Create message to sign
apiVersion: v1
kind: Secret
metadata:
  name: workflow-message
type: Opaque
stringData:
  content: "This workflow demonstrates QubeSec's capabilities"

---
# 7. Sign the message
apiVersion: qubessec.io/v1
kind: QuantumSignMessage
metadata:
  name: workflow-sign
spec:
  privateKeyRef:
    name: workflow-signer
  messageRef:
    name: workflow-message
  algorithm: Dilithium3

---
# 8. Verify the signature
apiVersion: qubessec.io/v1
kind: QuantumVerifySignature
metadata:
  name: workflow-verify
spec:
  publicKeyRef:
    name: workflow-signer
  messageRef:
    name: workflow-message
  signatureRef:
    name: workflow-sign
  algorithm: Dilithium3

---
# 9. Create certificate
apiVersion: qubessec.io/v1
kind: QuantumCertificate
metadata:
  name: workflow-certificate
spec:
  algorithm: Dilithium3
  certType: self-signed
  commonName: "workflow.example.com"
  durationDays: 365
EOF

kubectl apply -f complete-workflow.yaml

Monitor all resources:

# Watch creation progress
kubectl get qrn,qskp,qkkp,qes,qdk,qsm,qvs,qc -w

# Once all are ready, check status
kubectl get qrn,qskp,qkkp,qes,qdk,qsm,qvs,qc -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.status}{"\n"}{end}'

Accessing Generated Resources

Retrieve Random Data

kubectl get secret my-random -o jsonpath='{.data.random}' | base64 -d | xxd

Retrieve Keypair

# Public key
kubectl get secret alice-keypair -o jsonpath='{.data.public_key}' | base64 -d > pub.pem

# Private key (be careful!)
kubectl get secret alice-keypair -o jsonpath='{.data.private_key}' | base64 -d > priv.pem

Retrieve Certificate

# Certificate
kubectl get secret my-service-cert-secret -o jsonpath='{.data.cert\.pem}' | base64 -d > cert.pem

# Private key
kubectl get secret my-service-cert-secret -o jsonpath='{.data.key\.pem}' | base64 -d > key.pem

# View certificate details
openssl x509 -in cert.pem -text -noout

Retrieve Signature

kubectl get secret my-signature -o jsonpath='{.data.signature}' | base64 -d > signature.bin

Common Operations

Check Status of All Resources

# List all QubeSec resources
kubectl get qrn,qkkp,qes,qds,qdk,qskp,qsm,qvs,qc -A

# Get detailed status
kubectl describe qkkp alice-keypair
kubectl describe qes bob-encapsulate
kubectl describe qvs verify-message

Delete Resources

# Delete a single resource (associated Secrets auto-deleted)
kubectl delete qkkp alice-keypair

# Delete all resources in a file
kubectl delete -f key-exchange.yaml

# Delete by label
kubectl delete qrn -l app=myapp

View Fingerprints

# Get fingerprint from any resource
kubectl get qkkp alice-keypair -o jsonpath='{.status.fingerprint}'
kubectl get qes bob-encapsulate -o jsonpath='{.status.fingerprint}'
kubectl get qvs verify-message -o jsonpath='{.status.messageFingerprint}'

Mount in Pod

cat > pod.yaml << 'EOF'
apiVersion: v1
kind: Pod
metadata:
  name: app-with-keys
spec:
  containers:
  - name: app
    image: myapp:latest
    volumeMounts:
    - name: encryption-key
      mountPath: /secrets/encryption
      readOnly: true
    - name: certificate
      mountPath: /etc/tls
      readOnly: true
  volumes:
  - name: encryption-key
    secret:
      secretName: final-encryption-key
  - name: certificate
    secret:
      secretName: my-service-cert-secret
EOF

kubectl apply -f pod.yaml

Troubleshooting

Resource Stuck in "Pending"

# Check controller logs
kubectl logs -n qubesec-system -f deployment/qubesec-controller-manager

# Check resource events
kubectl describe qkkp alice-keypair

# Check if Secret was created
kubectl get secret alice-keypair

Signature Verification Failed

# Check fingerprints match
echo "Message fingerprint at signing:"
kubectl get qsm sign-message -o jsonpath='{.status.messageFingerprint}'

echo "Message fingerprint at verification:"
kubectl get qvs verify-message -o jsonpath='{.status.messageFingerprint}'

# If they don't match, the message was modified

Permission Denied Errors

# Check RBAC permissions
kubectl auth can-i get secrets
kubectl auth can-i list customresourcedefinitions

# Check service account
kubectl get sa -n qubesec-system

Next Steps

Learn Architecture: Read /architecture
Key Exchange Deep Dive: See /keyexchange
Digital Signatures: Explore /signatures
Certificates: Study /certificates
API Details: Reference /api-reference

Getting Help

Check logs: kubectl logs -n qubesec-system -f deployment/qubesec-controller-manager
Describe resources: kubectl describe qkkp <name>
GitHub Issues: https://github.com/QubeSec/QubeSec/issues
Documentation: https://qubesec.github.io/

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Before You Begin

Installation

Example 1: Generate Random Bytes

Example 2: Post-Quantum Key Exchange

Example 3: Digital Signatures

Example 4: Post-Quantum Certificates

Example 5: Complete Multi-Step Workflow

Accessing Generated Resources

Retrieve Random Data

Retrieve Keypair

Retrieve Certificate

Retrieve Signature

Common Operations

Check Status of All Resources

Delete Resources

View Fingerprints

Mount in Pod

Troubleshooting

Resource Stuck in "Pending"

Signature Verification Failed

Permission Denied Errors

Next Steps

Getting Help

FilesExpand file tree

quickstart.md

Latest commit

History

quickstart.md

File metadata and controls

Before You Begin

Installation

Example 1: Generate Random Bytes

Example 2: Post-Quantum Key Exchange

Example 3: Digital Signatures

Example 4: Post-Quantum Certificates

Example 5: Complete Multi-Step Workflow

Accessing Generated Resources

Retrieve Random Data

Retrieve Keypair

Retrieve Certificate

Retrieve Signature

Common Operations

Check Status of All Resources

Delete Resources

View Fingerprints

Mount in Pod

Troubleshooting

Resource Stuck in "Pending"

Signature Verification Failed

Permission Denied Errors

Next Steps

Getting Help