Create your own clients

umask 077                                  # new files are readable by you only
IDEMPOTENCY_KEY=$(openssl rand -hex 16)    # keep it until you have the answer

# 1. A new key and a signing request, on the client's machine
rm -f client_key.pem                       # permissions only apply to new files
openssl req -new -newkey ec -pkeyopt ec_paramgen_curve:P-256 -nodes \
  -keyout client_key.pem -out client.csr -subj "/CN=new client"

# 2. Create the client. --retry repeats the same request after a timeout or a
#    temporary error such as 503, with the same Idempotency-Key and body.
RESPONSE=$(curl -s --retry 4 -X POST https://api.knovas.ch/onboard_client \
  -H "Authorization: Knovas-Org-Key $KNOVAS_ORG_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --rawfile csr client.csr \
        '{first_name: "Jane", last_name: "Doe", email: "jane.doe@example.ch", csr_pem: $csr}')")

echo "$RESPONSE" | jq -r '.client_id'
echo "$RESPONSE" | jq -r '.certificate_pem' > client_cert.pem
echo "$RESPONSE" | jq -r '.ca_root_cert'    > ca_root_cert.pem

# pip install cryptography requests
import os
import time
import uuid

import requests
from cryptography import x509
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import ec
from cryptography.x509.oid import NameOID

# 1. A new key and a signing request, on the client's machine. Save the key first.
key = ec.generate_private_key(ec.SECP256R1())
if os.path.lexists("client_key.pem"):   # permissions only apply to new files
    os.remove("client_key.pem")
fd = os.open("client_key.pem", os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
with os.fdopen(fd, "wb") as f:
    f.write(key.private_bytes(serialization.Encoding.PEM, serialization.PrivateFormat.PKCS8,
                              serialization.NoEncryption()))
csr = (x509.CertificateSigningRequestBuilder()
       .subject_name(x509.Name([x509.NameAttribute(NameOID.COMMON_NAME, "new client")]))
       .sign(key, hashes.SHA256()))

# 2. Create the client. A retry sends the same headers and the same body.
headers = {"Authorization": f"Knovas-Org-Key {os.environ['KNOVAS_ORG_KEY']}",
           "Idempotency-Key": str(uuid.uuid4())}    # keep it until you have the answer
body = {"first_name": "Jane", "last_name": "Doe", "email": "jane.doe@example.ch",
        "csr_pem": csr.public_bytes(serialization.Encoding.PEM).decode()}
r = None
for attempt in range(4):
    try:
        r = requests.post("https://api.knovas.ch/onboard_client", headers=headers, json=body, timeout=60)
    except (requests.ConnectionError, requests.Timeout):
        r = None                         # no answer: retry, same key and body
    if r is not None and r.status_code != 503:
        break
    time.sleep(2 ** attempt)
if r is None:
    raise SystemExit("No answer. Retry later with the same Idempotency-Key and body.")
r.raise_for_status()                     # 201 created, or 200 for a repeated request
answer = r.json()
with open("client_cert.pem", "w") as f:
    f.write(answer["certificate_pem"])
with open("ca_root_cert.pem", "w") as f:
    f.write(answer["ca_root_cert"])
print("client", answer["client_id"], "- clients left:", answer.get("clients_left"))

umask 077
CLIENT_ID=$(printf '%s' "<client id>" | tr 'A-F' 'a-f')   # client_id from /onboard_client

# 1. A new key and a signing request. Keep the new key even if the call fails.
rm -f new_client_key.pem
openssl req -new -newkey ec -pkeyopt ec_paramgen_curve:P-256 -nodes \
  -keyout new_client_key.pem -out new_client.csr -subj "/CN=renewal"

# 2. The message: five lines, each ending in \n
SERIAL=$(openssl x509 -in client_cert.pem -noout -serial | cut -d= -f2)
SERIAL=$(echo "ibase=16; $SERIAL" | BC_LINE_LENGTH=0 bc)     # hex to decimal
NEW_KEY=$(openssl req -in new_client.csr -noout -pubkey | openssl pkey -pubin -outform DER \
  | openssl dgst -sha256 -r | cut -d' ' -f1)
SIGNED_AT=$(date +%s)
printf 'knovas-renew-v1\n%s\n%s\n%s\n%s\n' "$CLIENT_ID" "$SERIAL" "$NEW_KEY" "$SIGNED_AT" > renewal.txt

# 3. Sign it with the CURRENT private key. An RSA key (all keys made by Knovas):
SIGNATURE=$(openssl dgst -sha256 -sigopt rsa_padding_mode:pss -sigopt rsa_pss_saltlen:32 \
  -sigopt rsa_mgf1_md:sha256 -sign client_key.pem renewal.txt | openssl base64 -A)
# An EC key instead:
# SIGNATURE=$(openssl dgst -sha256 -sign client_key.pem renewal.txt | openssl base64 -A)

# 4. Renew. On an error the answer has an error_code instead (see below).
RESPONSE=$(curl -s -X POST https://api.knovas.ch/sign_certificate \
  -H "Authorization: Knovas-Org-Key $KNOVAS_ORG_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg id "$CLIENT_ID" --rawfile csr new_client.csr --rawfile cert client_cert.pem \
        --argjson at "$SIGNED_AT" --arg sig "$SIGNATURE" \
        '{customer_id: $id, csr: $csr, validity_days: 365, current_certificate: $cert,
          possession_proof: {signed_at: $at, signature: $sig}}')")
echo "$RESPONSE" | jq -r '.certificate' > new_client_cert.pem

# pip install cryptography requests
import base64
import hashlib
import os
import time

import requests
from cryptography import x509
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import ec, padding, rsa
from cryptography.x509.oid import NameOID

client_id = "<client id>".lower()          # client_id from /onboard_client
with open("client_cert.pem", "rb") as f:
    current_cert = x509.load_pem_x509_certificate(f.read())
with open("client_key.pem", "rb") as f:
    current_key = serialization.load_pem_private_key(f.read(), password=None)

# 1. A new key and a signing request. Save the key first and keep it even if the call fails.
new_key = ec.generate_private_key(ec.SECP256R1())
if os.path.lexists("new_client_key.pem"):   # permissions only apply to new files
    os.remove("new_client_key.pem")
fd = os.open("new_client_key.pem", os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
with os.fdopen(fd, "wb") as f:
    f.write(new_key.private_bytes(serialization.Encoding.PEM, serialization.PrivateFormat.PKCS8,
                                  serialization.NoEncryption()))
csr = (x509.CertificateSigningRequestBuilder()
       .subject_name(x509.Name([x509.NameAttribute(NameOID.COMMON_NAME, "renewal")]))
       .sign(new_key, hashes.SHA256()))

# 2. The message: five lines, each ending in \n
spki = new_key.public_key().public_bytes(serialization.Encoding.DER,
                                         serialization.PublicFormat.SubjectPublicKeyInfo)
signed_at = int(time.time())
lines = ["knovas-renew-v1", client_id, str(current_cert.serial_number),
         hashlib.sha256(spki).hexdigest(), str(signed_at)]
message = "".join(line + "\n" for line in lines).encode("utf-8")

# 3. Sign it with the CURRENT private key
if isinstance(current_key, rsa.RSAPrivateKey):
    signature = current_key.sign(
        message, padding.PSS(mgf=padding.MGF1(hashes.SHA256()), salt_length=32), hashes.SHA256())
else:
    signature = current_key.sign(message, ec.ECDSA(hashes.SHA256()))

# 4. Renew
r = requests.post("https://api.knovas.ch/sign_certificate", timeout=60,
                  headers={"Authorization": f"Knovas-Org-Key {os.environ['KNOVAS_ORG_KEY']}"},
                  json={"customer_id": client_id,
                        "csr": csr.public_bytes(serialization.Encoding.PEM).decode(),
                        "validity_days": 365,
                        "current_certificate": current_cert.public_bytes(serialization.Encoding.PEM).decode(),
                        "possession_proof": {"signed_at": signed_at,
                                             "signature": base64.b64encode(signature).decode()}})
r.raise_for_status()
with open("new_client_cert.pem", "w") as f:
    f.write(r.json()["certificate"])