IPWorks Auth 2020 JavaScript Edition

Questions / Feedback?

Encrypt Method

Encrypts the claims with the specified algorithms.

Syntax

async jwt.encrypt(): Promise<void>

Remarks

This method encrypts the claims using the specified algorithms.

To create an encrypted JWT JSON Web Encryption (JWE) is performed by first generating a random key used to encrypt the content. The content encryption key is used to encrypt the content using the algorithm specified by ContentEncryptionAlgorithm. The content encryption key is then encrypted itself using the algorithm specified by EncryptionAlgorithm. The content encryption key is not directly exposed in the API as it is randomly generated.

After calling this method the compact serialized JWT is written to EncodedJWT. For instance:

eyJhbGciOiJBMjU2S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0.4tcAnZJ00u4GY2kLOanPOL4CtvcfraZ8SIi6bOZ27qYBI2rHITPc1Q.c_9rCTdPn-saLCti2ZEyWQ.eLwqqo5BGNa70RlsvT-vTh7Gk0hjpJYY_9Zc39Vim_qEtjyMcxZygBpkfx9brzQr9rUbuiAhoCMXKip2-lKT6w.NkuLDPmWxWL4BaTWHWicIQ

The class will use the values present in the Claim* properties to build the encoded JWT. After calling this method the EncodedJWT property will hold the compact serialized JWT. The following properties are applicable when calling this method:

Notes for AES Algorithms (A128KW, A192KW, A256KW, A128GCMKW, A192GCMKW, A256GCMKW)

When EncryptionAlgorithm is set to a AES algorithm Key must be set to a key of appropriate length for the algorithm. For instance a 256 bit key would be used for A256KW.

To use an existing AES key provide the bytes to the Key property. For instance:


byte[] key = new byte[] { 164, 60, 194, 0, 161, 189, 41, 38, 130, 89, 141, 164, 45, 170, 159, 209, 69, 137, 243, 216, 191, 131, 47, 250, 32, 107, 231, 117, 37, 158, 225, 234 };

//Encrypt the payload using A256KW
Jwt jwt = new Jwt();
jwt.KeyB = key;
jwt.ClaimAudience = "audience";
jwt.ClaimIssuer = "issuer";
jwt.ClaimExp = "1498508071";
jwt.EncryptionAlgorithm = JwtEncryptionAlgorithms.eaA256KW;
jwt.Encrypt();

string encryptedData = jwt.EncodedJWT;

Notes for RSA Algorithms (RSA1_5, RSA-OEAP, RSA-OAEP-256)

The RSA based algorithms use asymmetric encryption. Encrypting is done with a public key and decryption is done with a private key. The public certificate should be in PEM (base64) format. For instance:


Jwt jwt = new Jwt();
jwt.Certificate = new Certificate("..\\recipient.cer");
jwt.ClaimAudience = "audience";
jwt.ClaimIssuer = "issuer";
jwt.ClaimExp = "1498508071";
jwt.EncryptionAlgorithm = JwtEncryptionAlgorithms.eaRSA_OAEP;
jwt.Encrypt();

string encryptedData = jwt.EncodedJWT;

Notes for ECDH Algorithms (ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A192KW, ECDH-ES+A256KW)

ECDH algorithms require a valid ECC public key to encrypt the message. If the key was originally created with the ECC class the PEM encoded PublicKey may be used directly with the Certificate property. An example PEM encoded public certificate created by the ECC component:

-----BEGIN PUBLIC KEY-----
MIIBMjCB7AYHKoZIzj0CATCB4AIBATAsBgcqhkjOPQEBAiEA/////wAAAAEAAAAAAAAAAAAA
AAD///////////////8wRAQg/////wAAAAEAAAAAAAAAAAAAAAD///////////////wEIFrG
NdiqOpPns+u9VXaYhrxlHQawzFOw9jvOPD4n0mBLBEEEaxfR8uEsQkf4vOblY6RA8ncDfYEt
6zOg9KE5RdiYwpZP40Li/hp/m47n60p8D54WK84zV2sxXs7LtkBoN79R9QIhAP////8AAAAA
//////////+85vqtpxeehPO5ysL8YyVRAgEBA0EEIC5rbLp11Mnz6cBXLLriaDIov3rm8RAY
x/OR0bOKiff0cQy+sLVaxjseqFk/+Xvl4ORSv5Z6HdHv5GyEpA0UoA==
-----END PUBLIC KEY-----


Jwt jwt = new Jwt();
jwt.Certificate = new Certificate(CertStoreTypes.cstPublicKeyFile, pubKeyFile, "", "*");
jwt.ClaimAudience = "audience";
jwt.ClaimIssuer = "issuer";
jwt.ClaimExp = "1498508071";
jwt.EncryptionAlgorithm = JwtEncryptionAlgorithms.eaECDH_ES_A256KW;
jwt.Encrypt();

string encryptedData = jwt.EncodedJWT;

To use an ECC public key created by other means the ECC class may be used to import the key parameters. Populate the Rx and Ry properties of the ECC component first to obtain the PEM formatted public key. For instance:


byte[] x_bytes = new byte[] { 171, 170, 196, 151, 94, 196, 231, 12, 128, 232, 17, 61, 45, 105, 41, 209, 192, 187, 112, 242, 110, 178, 95, 240, 36, 55, 83, 171, 190, 176, 78, 13 };
byte[] y_bytes = new byte[] { 197, 75, 134, 245, 245, 28, 199, 9, 7, 117, 1, 54, 49, 178, 135, 252, 62, 89, 35, 180, 117, 80, 231, 23, 110, 250, 28, 124, 219, 253, 224, 156 };

nsoftware.IPWorksEncrypt.Ecc ecc = new nsoftware.IPWorksEncrypt.Ecc();
ecc.Key.RxB = x_bytes;
ecc.Key.RyB = y_bytes;

string pubKey = ecc.Key.PublicKey;

Jwt jwt = new Jwt();
jwt.Certificate = new Certificate(CertStoreTypes.cstPublicKeyFile, pubKey, "", "*");
jwt.ClaimAudience = "audience";
jwt.ClaimIssuer = "issuer";
jwt.ClaimExp = "1498508071";
jwt.EncryptionAlgorithm = JwtEncryptionAlgorithms.eaECDH_ES_A256KW;
jwt.Encrypt();

string encryptedData = jwt.EncodedJWT;

Notes for PBES Algorithms (PBES2-HS256+A128KW, PBES2-HS384+A192KW, PBES2-HS512+A256KW

PBES algorithms derive a content encryption key from the KeyPassword property. Set KeyPassword to a shared secret.


Jwt jwt = new Jwt();
jwt.KeyPassword = "secret";
jwt.ClaimAudience = "audience";
jwt.ClaimIssuer = "issuer";
jwt.ClaimExp = "1498508071";
jwt.EncryptionAlgorithm = JwtEncryptionAlgorithms.eaPBES2_HS512_A256KW;
jwt.Encrypt();

string encryptedData = jwt.EncodedJWT;

Notes for Direct Shared Keys

When EncryptionAlgorithm is set to Direct the Key property must be set to a valid symmetric key that will be used directly by the ContentEncryptionAlgorithm. In this case a content encryption key is not generated randomly, the Key is used instead. The length of the specified Key must be valid for the selected ContentEncryptionAlgorithm. For instance:


byte[] key = new byte[] { 164, 62, 191, 60, 161, 189, 41, 38, 130, 89, 141, 164, 45, 170, 159, 209, 69, 137, 243, 216, 191, 131, 47, 250, 32, 107, 231, 117, 37, 158, 225, 234 };

Jwt jwt = new Jwt();
jwt.EncryptionAlgorithm = JwtEncryptionAlgorithms.eaDir;
jwt.ContentEncryptionAlgorithm = JwtContentEncryptionAlgorithms.ceaA256GCM;
jwt.KeyB = key;
jwt.ClaimAudience = "audience";
jwt.ClaimIssuer = "issuer";
jwt.ClaimExp = "1498508071";
jwt.Encrypt();

string encryptedData = jwt.EncodedJWT;
Copyright (c) 2022 /n software inc. - All rights reserved.
IPWorks Auth 2020 JavaScript Edition - Version 20.0 [Build 8262]