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 purposes:

• signing
  • Generating asymmetric key pairs
• encryption
  • Generating a symmetric key
  • Generating a format-preserving encryption (FPE) key
• jwt
  • Sign a JSON Web Token
  • Verify the signature of a JSON Web Token

Asymmetric signing algorithms

Vault has added quantum-safe signing algorithms to make sure that keys remain safe once quantum computers come online. There are three specific kinds of quantum-safe algorithms currently supported (SPHINCSPLUS, FALCON, and DILITHIUM).

SPHINCSPLUS - Stateless hash-based signature algorithm that is designed to be resistant to attacks from quantum computers by providing secure digital signatures. There are two primary variants (fast but larger and slow but smaller), two secondary variants (robust with conservative security guarantees and simple, which is a pure random oracle instantiation), and multiple security levels to meet the needs of users.

FALCON - Lattice-based signature algorithm that uses the computational hardness of certain lattice problems to create its security. It is compact, fast, and scalable for a quantum-safe signing algorithm, making it suitable for a variety of applications.

DILITHIUM - Digital lattice-based algorithms that are combined with pre-quantum algorithms that prevent adversaries from producing signatures for messages that they haven't seen, and from producing a different signature for a message that they saw signed. Both pre-quantum and post-quantum algorithms generate secrets and then both secrets are used to create the security key. This requires adversaries to break both the pre-quantum and post-quantum algorithms in order to obtain the key.

important

All quantum-safe signing algorithms with the suffix BETA are experimental and might not be ready for use in production environments.

The purposes and algorithms supported for asymmetric keys are:

• 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
  • ED25519-DILITHIUM2-BETA
  • ED448-DILITHIUM3-BETA
  • SPHINCSPLUS-128F-SHAKE256-SIMPLE-BETA
  • SPHINCSPLUS-128F-SHAKE256-ROBUST-BETA
  • SPHINCSPLUS-192F-SHAKE256-SIMPLE-BETA
  • SPHINCSPLUS-192F-SHAKE256-ROBUST-BETA
  • SPHINCSPLUS-256F-SHAKE256-SIMPLE-BETA
  • SPHINCSPLUS-256F-SHAKE256-ROBUST-BETA
  • SPHINCSPLUS-128F-SHA256-SIMPLE-BETA
  • SPHINCSPLUS-128F-SHA256-ROBUST-BETA
  • SPHINCSPLUS-192F-SHA256-SIMPLE-BETA
  • SPHINCSPLUS-192F-SHA256-ROBUST-BETA
  • SPHINCSPLUS-256F-SHA256-SIMPLE-BETA
  • SPHINCSPLUS-256F-SHA256-ROBUST-BETA
  • FALCON-1024-BETA
• 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

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.

POST/v1/key/generate

cURL

Code Snippet Language

curl -sSLX POST 'https://vault.'"$PANGEA_DOMAIN"'/v1/key/generate' \
-H 'Authorization: Bearer '"$PANGEA_AUDIT_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"type":"asymmetric_key","purpose":"signing","algorithm":"ED25519"}'

Symmetric signing algorithms

The purposes and algorithms for symmetric keys are:

• encryption algorithms
  • AES-CFB-128
  • AES-CFB-256
  • AES-GCM-256
  • AES-CBC-128
  • AES-CBC-256
• jwt algorithms
  • HS256
  • HS384
  • HS512

Generating a symmetric key

The symmetric key generation will result in the creation of a single key.

info

The generated key will never be exposed to the user.

POST/v1/key/generate

cURL

Code Snippet Language

curl -sSLX POST 'https://vault.'"$PANGEA_DOMAIN"'/v1/key/generate' \
-H 'Authorization: Bearer '"$PANGEA_AUDIT_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"type":"symmetric_key","purpose":"encryption","algorithm":"AES-CFB-128"}'

Generating a format-preserving encryption (FPE) key

An FPE token is a token that preserves the character format of the string during encryption. This is useful in cases where the data needs to be encrypted but the length or character types cannot be altered. Instances of this are in legacy databases that only support certain character types (such as letters for names), specific lengths of strings (such as phone numbers, Social Security numbers, or credit cards), etc. and the database cannot be feasibly altered to accept data strings created by industry-standard encryption algorithms.

note

The strongest encryption algorithms are not constrained by the length and character set (i.e. are not format-preserving). Conversely, format-preserving encryption algorithms are not the strongest available, but they are the strongest that can be used under the listed constraints and are NIST-approved.

The FPE algorithms currently supported are:

• AES-FF3-1-128-BETA - A 128-bit encryption using the FF3-1 algorithm
• AES-FF3-1-256-BETA - A 256-bit encryption using the FF3-1 algorithm

FF3 algorithms are considered vulnerable, but Vault is supporting FF3-1, which is NIST-approved.

note

When using a key generated for FPE, you can select an alphabet, the set of characters used for encryption.

Characters not included in the selected alphabet will remain unchanged in the encrypted output. The available choices are:

• "numeric" - Numeric (0-9)
• "alphalower" - Lowercase alphabet (a-z)
• "alphaupper" - Uppercase alphabet (A-Z)
• "alpha" - Lowercase and uppercase alphabet (a-z, A-Z)
• "alphanumericlower" - Lowercase alphabet with numbers (a-z, 0-9)
• "alphanumericupper" - Uppercase alphabet with numbers (A-Z, 0-9)
• "alphanumeric" - Alphanumeric (a-z, A-Z, 0-9)

For example, a driver's license with the original value "A1234567" could become "A4313639" if encrypted using the numeric alphabet. Note that the "A" is preserved as part of the format, but the digits are changed."

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 makes sure that the information in the header and payload of a JWT hasn't been altered and can be trusted. Use asymmetric keys created with the Vault service to sign JWTs. 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).

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

As mentioned 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

Before your application can start using and storing JSON Web Tokens (JWTs), you need to verify the signature included in said JWT. Signatures contained within JWTs are called JSON Web Signatures (JWSs) and are used to digitally sign and protect the integrity of the rest of the JWT data (payload, header)

Pangea allows you to verify the signature of a JWT using the Vault API.

Different parts of a signed JWT

A signed JWT consists of the following three parts:

Part	Description
Header	Includes information about the token type (JWT) and the algorithm that was used to sign the JWT, like es25, es384, es512 (asymmetric), or hs256, hs384, hs512 (symmetric).
Payload	The content of the original JWT. The payload is a JavaScript object containing identifiable information, like name.
JSON Web Signature (JWS)	Used to verify that a JWT token can be trusted, and that the payload and header haven’t been modified in any way.

Obtain a JWS

A JWS is the signed portion of a JWT that’s used for validation. The jws value is included in the API response when calling the /key/sign/jwt endpoint. You’ll need to include the jws value as a parameter in your verification API call.

For more details on obtaining the necessary jws value, visit Sign a JSON Web Token (JWT).

note

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

JWS response example

An example of a JWS could resemble the following:

ewogICJhbGciOiAiUlMyNTYiLAogICJraWQiOiAiMTMzNzQ3MTQxMjU1IiwKICAiaWF0IjogMCwKICAiaXNzIjogIkM9R0IsIEw9TG9uZG9uLCBPVT1OdWFwYXkgQVBJLCBPPU51YXBheSwgQ049eWJvcXlheTkycSIsCiAgImI2NCI6IGZhbHNlLAogICJjcml0IjogWwogICAgImlhdCIsCiAgICAiaXNzIiwKICAgICJiNjQiCiAgXQp9..d_cZ46lwNiaFHAu_saC-Zz4rSzNbevWirO94EmBlbOwkB1L78vGbAnNjUsmFSU7t_HhL-cyMiQUDyRWswsEnlDljJsRi8s8ft48ipy2SMuZrjPpyYYMgink8nZZK7l-eFJcTiS9ZWezAAXF_IJFXSTO5ax9z6xty3zTNPNMV9W7aH8fEAvbUIiueOhH5xNHcsuqlOGygKdFz2rbjTGffoE_6zS4Dry-uX5mts2duLorobUimGsdlUcSM6P6vZEtcXaJCdjrT9tuFMh4CkX9nqk19Bq2z3i-SX4JCPvhD2r3ghRmX0gG08UcvyFVbrnVZJnpl4MU8V4Nr3-2M5URZOg

Using the API

• Call the /key/verify/jwt endpoint.
• Include the jws parameter in your API call (The jws value is returned after you call the /key/sign/jwt endpoint).

Example API request

An API request might look like the example below:

POST/v1/key/sign/jwt

cURL

Code Snippet Language

curl -sSLX POST 'https://vault.'"$PANGEA_DOMAIN"'/v1/key/sign/jwt' \
-H 'Authorization: Bearer '"$PANGEA_VAULT_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"id":"pvi_p6g5i3gtbvqvc3u6zugab6qs6r63tqf5","payload":"{\"sub\": \"1234567890\",\"name\": \"John Doe\",\"admin\": true}"}'

Example API response

A sample API response could resemble the following:

{
  "request_id": "prq_x6fdiizbon6j3bsdvnpmwxsz2aan7fqd",
  "request_time": "2023-05-04T17:47:34.495376Z",
  "response_time": "2023-05-04T17:47:34.620884Z",
  "status": "Success",
  "summary": "Token signed",
  "result": {
    "jws": "ewogICJhbGciOiAiUlMyNTYiLAogICJraWQiOiAiMTMzNzQ3MTQxMjU1IiwKICAiaWF0IjogMCwKICAiaXNzIjogIkM9R0IsIEw9TG9uZG9uLCBPVT1OdWFwYXkgQVBJLCBPPU51YXBheSwgQ049eWJvcXlheTkycSIsCiAgImI2NCI6IGZhbHNlLAogICJjcml0IjogWwogICAgImlhdCIsCiAgICAiaXNzIiwKICAgICJiNjQiCiAgXQp9..d_cZ46lwNiaFHAu_saC-Zz4rSzNbevWirO94EmBlbOwkB1L78vGbAnNjUsmFSU7t_HhL-cyMiQUDyRWswsEnlDljJsRi8s8ft48ipy2SMuZrjPpyYYMgink8nZZK7l-eFJcTiS9ZWezAAXF_IJFXSTO5ax9z6xty3zTNPNMV9W7aH8fEAvbUIiueOhH5xNHcsuqlOGygKdFz2rbjTGffoE_6zS4Dry-uX5mts2duLorobUimGsdlUcSM6P6vZEtcXaJCdjrT9tuFMh4CkX9nqk19Bq2z3i-SX4JCPvhD2r3ghRmX0gG08UcvyFVbrnVZJnpl4MU8V4Nr3-2M5URZOg"
  }
}

Was this article helpful?

Contact us