Cryptographic Keys and JWKS

Public and Private Keys

A key pair consists of:

• A private key used to create signatures
• A public key used to verify signatures

The private key must remain confidential.

The public key can be distributed to verifiers.

Generate a Key Pair

In Keys (Admin), click:

Generate P-256 Key

BadgeMax Pro uses the Web Crypto API to create the key pair.

The public key is displayed in the Public JWK field.

The private key is exported to the Private JWK field.

Private Key Security

The Private JWK field contains sensitive signing material.

Anyone who obtains the private key may be able to issue signatures that appear to come from the same issuer.

Do not:

• Publish the private JWK
• Include it in website source code
• Upload it to a public repository
• Share it through an unsecured channel
• Include it in jwks.json

The supplied application keeps key operations within the browser, but it also displays an exportable private key.

Treat the page and browser session as a sensitive administrative environment.

Key ID (kid)

Each key has a Key ID, commonly called kid.

The default field value in the supplied interface is:

k-2025-08

For production use, choose an identifier that represents your actual signing key.

For example:

badge-signing-2026-01

The key ID is used to select a matching public key from the issuer's JWKS.

The key ID is not secret.

Public JWK

A public JSON Web Key contains information such as:

{
  "kty": "EC",
  "crv": "P-256",
  "x": "BASE64URL_X_COORDINATE",
  "y": "BASE64URL_Y_COORDINATE",
  "key_ops": ["verify"],
  "kid": "badge-signing-2026-01",
  "alg": "ES256"
}

The coordinate values above are placeholders.

Use the actual exported values.

Private JWK

A private EC JWK additionally includes a private component:

{
  "kty": "EC",
  "crv": "P-256",
  "x": "BASE64URL_X_COORDINATE",
  "y": "BASE64URL_Y_COORDINATE",
  "d": "PRIVATE_KEY_MATERIAL",
  "kid": "badge-signing-2026-01",
  "alg": "ES256"
}

Never publish this file.

Import an Existing Key

To reuse an existing signing key:

1. Paste the private JWK into Private JWK.
2. Click Import Private JWK.
3. Confirm the public key appears.
4. Generate the badge.

The application imports the key using Web Crypto.

Importing a private key allows badges to be issued with an existing cryptographic identity.

Why Reuse Keys?

A consistent issuer key allows multiple badges to be verified against the same published public key.

Generating a different key for every badge is possible, but requires careful management of public keys and key identifiers.

Download JWKS

Click:

Download jwks.json

The application exports a JSON Web Key Set.

Example structure:

{
  "keys": [
    {
      "kty": "EC",
      "crv": "P-256",
      "x": "BASE64URL_X_COORDINATE",
      "y": "BASE64URL_Y_COORDINATE",
      "key_ops": ["verify"],
      "kid": "badge-signing-2026-01",
      "alg": "ES256"
    }
  ]
}

Publish the JWKS

Upload the public JWKS to:

/.well-known/bar/jwks.json

Example:

https://example.com/.well-known/bar/jwks.json

The verifier derives this location from the assertion URL's origin unless an issuer override is supplied.

Multiple Keys

The verifier can search a JWKS containing multiple entries and select the entry matching the badge's kid.

However, the supplied export button creates a JWKS containing one key.

Managing a multi-key JWKS requires maintaining or combining those public entries outside the application's single-key export workflow.

Key Rotation

When replacing a signing key:

1. Generate or import the replacement.
2. Assign an appropriate new Key ID.
3. Publish the new public key.
4. Keep old public keys available for badges that must remain verifiable.
5. Sign new badges using the new key.

Removing an old public key may prevent verification of badges signed with that key.

Secure Contexts

The Web Crypto API generally requires a secure browser context.

Use HTTPS for deployed administrative and verification pages.

Some local development environments also qualify as secure contexts.

Critical: Downloading jwks.json is not a backup of your signing key. It contains only public key material. Back up the private JWK securely if you intend to issue additional badges with the same identity.