Generate a key

Review the steps to generate a key

The Vault service can be used to generate both asymmetric and symmetric keys. Key functionality in the vault supports the following purpose:

• Sign a JSON Web Token
• Verify the signature of a JSON Web Token

Sign a JSON Web Token

Signing a JSON Web Token (JWT) using JSON Web Signatures (JWS) is an important part of data security because it ensures that the information in the header and payload of a JWT hasn't been altered and can be trusted. You can sign JWTs using asymmetric and symmetric keys created with the Vault service. The exact way a signature is validated depends on the algorithm you specified when creating the key.

note

To learn more about JWTs, visit JSON Web Tokens (JWTs).

Generating asymmetric key pairs

The asymmetric key generation will result in the creation of a key pair. Only the public key will be accessible to the user.

The purposes and algorithms supported for asymmetric keys are:

• jwt
  • Algorithms:
    • ES256
    • ES384
    • ES512

Language

Python

JavaScript

Go

import os

import pangea.exceptions as pe
from pangea.config import PangeaConfig
from pangea.services import Vault
from pangea.services.vault.models.asymmetric import AsymmetricAlgorithm
from pangea.services.vault.models.common import KeyPurpose


def generate_asymmetric_signing_key(name):
    token = os.getenv("PANGEA_VAULT_TOKEN")
    domain = os.getenv("PANGEA_DOMAIN")
    config = PangeaConfig(domain=domain)
    vault = Vault(token, config=config)

    try:
        # use purpose of signing, encryption, or jwt
        # choose from allowed algorithms by purpose
        vault.asymmetric_generate(
            name=name,
            algorithm=AsymmetricAlgorithm.Ed25519,
            purpose=KeyPurpose.SIGNING
        )
    except pe.PangeaAPIException as e:
        print(f"Vault Request Error: {e.response.summary}")
        for err in e.errors:
            print(f"\t{err.detail} \n")

    return

Symmetric signing algorithms

Pangea supports the creation of symmetric keys using the following Hash-based Message Authentication Code (HMAC) algorithms:

• HS256
• HS384
• HS512

Generating a symmetric key

The symmetric key generation will result in the creation of a single key. This key will never be exposed to the user.

The purposes and algorithms supported for symmetric keys are:

• jwt algorithms:
  • HS256
  • HS384
  • HS512

Language

Python

JavaScript

Go

import os

import pangea.exceptions as pe
from pangea.config import PangeaConfig
from pangea.services import Vault
from pangea.services.vault.models.symmetric import SymmetricAlgorithm
from pangea.services.vault.models.common import KeyPurpose


def generate_symmetric_encryption_key(name):
    token = os.getenv("PANGEA_VAULT_TOKEN")
    domain = os.getenv("PANGEA_DOMAIN")
    config = PangeaConfig(domain=domain)
    vault = Vault(token, config=config)

    try:
        # use purpose of encryption or jwt
        # choose from allowed algorithms by purpose
        vault.symmetric_generate(
            name=name,
            algorithm=SymmetricAlgorithm.AES128_CFB,
            purpose=KeyPurpose.ENCRYPTION
        )
    except pe.PangeaAPIException as e:
        print(f"Vault Request Error: {e.response.summary}")
        for err in e.errors:
            print(f"\t{err.detail} \n")

    return

Key recommendation

tip

Pangea recommends using asymmetric keys for signing JWTs.

When using asymmetric keys, only the signing party needs access to the private key material; while, the verifying party only needs access to the public key. This reduces the risk of forged signatures using your private key.

With symmetric encryption, both parties need access to the private key material, which increases the chances that private key material is leaked, leading to forged signatures.

Creating a key for JWT signing

Using the Pangea Console or the /key/generate endpoint, you’ll need to specify a name, type, purpose, and algorithm for signing.

Specify a purpose

When creating a key for JWT signing, use "jwt" as the purpose.

Specify a key type

You’ll need to specify a key type of symmetric or asymmetric. As noted above, Pangea recommends using asymmetric encryption for JWT signing.

Specify an algorithm

Specify one of the supported algorithms for JWT signing noted in the Symmetric signing algorithm and Asymmetric signing algorithms sections.

Using the API

To sign a JWT, you'll need to:

1. Call the /key/sign/jwt endpoint
2. Include the following required parameters in your API request:

• id - Indicates the ID of the key you want to use for signing
• payload - A string with a JSON object containing the payload of the JWT

3. Receive a JSON Web Signature (JWS) in return

Example JWT

{
  "sub": "1234567890",
  "name": "John Doe",
  "admin": true
}

Verify the signature of a JSON Web Token

• signing algorithms
  • ED25519
  • RSA-PKCS1V15-2048-SHA256
  • RSA-PSS-2048-SHA256
  • RSA-PSS-3072-SHA256
  • RSA-PSS-4096-SHA256
  • RSA-PSS-4096-SHA512
  • ES256
  • ES384
  • ES512
  • ES256K
• encryption algorithms
  • RSA-OAEP-2048-SHA1
  • RSA-OAEP-2048-SHA256
  • RSA-OAEP-2048-SHA512
  • RSA-OAEP-3072-SHA1
  • RSA-OAEP-3072-SHA256
  • RSA-OAEP-3072-SHA512
  • RSA-OAEP-4096-SHA1
  • RSA-OAEP-4096-SHA256
  • RSA-OAEP-4096-SHA512
• jwt algorithms
  • ES256
  • ES384
  • ES512

import os

import pangea.exceptions as pe
from pangea.config import PangeaConfig
from pangea.services import Vault
from pangea.services.vault.models.asymmetric import AsymmetricAlgorithm
from pangea.services.vault.models.common import KeyPurpose


def generate_asymmetric_signing_key(name):
    token = os.getenv("PANGEA_VAULT_TOKEN")
    domain = os.getenv("PANGEA_DOMAIN")
    config = PangeaConfig(domain=domain)
    vault = Vault(token, config=config)

    try:
        # use purpose of signing, encryption, or jwt
        # choose from allowed algorithms by purpose
        vault.asymmetric_generate(
            name=name,
            algorithm=AsymmetricAlgorithm.Ed25519,
            purpose=KeyPurpose.SIGNING
        )
    except pe.PangeaAPIException as e:
        print(f"Vault Request Error: {e.response.summary}")
        for err in e.errors:
            print(f"\t{err.detail} \n")

    return

Was this article helpful?

Contact us