OpenPGP API

Base URL: https://keys.ch-j.de. This Hagrid instance distributes public OpenPGP V4 and V6 certificates and their cryptographically signed revocations.

Connection and reverse proxy

The public HTTPS service is available over IPv4 and IPv6. Requests can pass through the NGINX reverse proxy with the same hostname, API paths and response formats. Use the hostname through DNS rather than a fixed IP address, and keep TLS certificate validation enabled.

Use HTTPS for API calls. Plain HTTP redirects to HTTPS; clients that disable redirects should call the HTTPS URL directly. To test a specific address family with curl, add -4 or -6.

The current development CH-J Server Manager desktop integration uses IPv6. It uploads only a freshly exported public certificate; private keys and private-key passphrases remain in the local vault.

Upload a public certificate

POST /vks/v1/upload with Content-Type: application/json. The keytext field contains one ASCII-armored public certificate, including its public subkeys and signatures. Do not submit a private-key block.

Create public-key.json with this structure, replacing the placeholder with your complete public certificate:

{
  "keytext": "-----BEGIN PGP PUBLIC KEY BLOCK-----\n...\n-----END PGP PUBLIC KEY BLOCK-----"
}

curl --fail-with-body \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --data-binary @public-key.json \
  https://keys.ch-j.de/vks/v1/upload

The JSON acknowledgement contains key_fpr (the uploaded primary fingerprint), status (email-publication statuses) and an opaque token for the separate email-verification workflow. Check that key_fpr matches the certificate you intended to upload. An upload acknowledgement does not prove the owner's identity or verify an email address.

Illustrative response schema; placeholders below are not usable credentials or a real fingerprint:

{
  "key_fpr": "PRIMARY_FINGERPRINT",
  "status": {"you@example.org": "unpublished"},
  "token": "OPAQUE_UPLOAD_TOKEN"
}

Email status values are unpublished, pending, published and revoked. They describe the reported address state; an upload acknowledgement alone is not a cryptographic check of a downloaded revocation.

Retrieve a public certificate

A successful lookup returns ASCII armor with Content-Type: application/pgp-keys. Verify that the returned primary certificate has the fingerprint you expect. A lookup by a subkey identifies its containing primary certificate.

curl --fail-with-body \
  -H 'Accept: application/pgp-keys' \
  "https://keys.ch-j.de/vks/v1/by-fingerprint/${FINGERPRINT}" \
  -o public-key.asc

Set FINGERPRINT to the full expected fingerprint before running the example. Missing certificates return HTTP 404. Unverified email identities can be omitted from the downloaded public certificate.

Publish a revocation

1. Create a valid OpenPGP revocation signature locally using the corresponding private key or an existing revocation certificate.
2. Export the updated public certificate containing that signature.
3. Submit it to POST /vks/v1/upload using the same JSON format.
4. Retrieve it again by full fingerprint and cryptographically verify the revocation.

There is no separate unsigned “revoke by fingerprint” endpoint. Deleting a local key does not revoke it. Re-uploading an older, unrevoked certificate does not undo a valid published revocation.

In CH-J Server Manager, Revoke and publish saves the local revocation before attempting the upload. If the server is unavailable, the key stays revoked locally and Publish revocation can be used to retry.

Limits and errors

Uploads are limited to 1 MiB per HTTP request, including JSON encoding. Rate limiting applies; requests through the reverse proxy may share a rate-limit bucket.

VKS POST errors normally contain a JSON error field. Lookup errors may be plain text, and errors produced by the reverse proxy may have a different format. Check the HTTP status before parsing a success response.

Email verification and management

Email delivery and email-ownership verification are enabled. Uploading a key alone does not publish its email identities. Each address must be confirmed using the link sent to that mailbox. This proves access to the mailbox, not the legal identity of its owner.

After uploading, request verification with POST /vks/v1/request-verify and Content-Type: application/json. Use the opaque upload token from the acknowledgement and only addresses present in that certificate:

{
  "token": "UPLOAD_TOKEN_FROM_ACKNOWLEDGEMENT",
  "addresses": ["you@example.org"],
  "locale": ["en"]
}

The response has the same key_fpr, status and token fields as upload. A pending status is not proof of delivery or ownership. Open the HTTPS verification link in the received message and submit the confirmation form. After confirmation, GET /vks/v1/by-email/EMAIL returns the public certificate; URL-encode the address and verify the returned fingerprint.

Verification and management requests are throttled separately per address (currently once per hour). Repeating a request does not guarantee another message. Messages are sent from keys@ch-j.de. Keep upload, verification and management tokens private.

Use Manage to request a private management link for a published address. Unpublishing an address removes email-based discovery; it does not revoke the OpenPGP key. Cryptographic revocation still uses the signed public-certificate upload described above.

HKP compatibility

Legacy HKP clients can use POST /pks/add with form-encoded keytext and GET /pks/lookup with op=get or op=index and an exact fingerprint or long key ID.

Scope and client guidance

For the browser and GnuPG workflow, see the usage guide. The service overview explains public identities and trust boundaries.

This service does not store SSH identities or provide SSH CA/KRL, TSA timestamps, or independent certification of a person's identity. Private-key storage and private-key operations remain local to the client.