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
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
- Algorithms:
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
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:
- Call the /key/sign/jwt endpoint
- Include the following required parameters in your API request:
id
- Indicates the ID of the key you want to use for signingpayload
- A string with a JSON object containing the payload of the JWT
- 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
algorithmsED25519
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
algorithmsRSA-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
algorithmsES256
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?