org.picketlink.json.jose

Class JWEBuilder<T extends JWE,B extends JWEBuilder<?,?>>

java.lang.Object

org.picketlink.json.jose.JWEBuilder<T,B>

Type Parameters:

T - the generic type

B - the generic type

public class JWEBuilder<T extends JWE,B extends JWEBuilder<?,?>>
extends Object

JSON Web Encryption (JWE) header Builder.

Supports build of all Principal Registered Parameter Names of the JWE specification:

• alg
• typ
• cty
• enc
• zip
• keys
• jku
• x5u
• x5c
• x5t
• x5t#S256

Example header:

 {
   "alg":"RSA1_5",
   "kid":"2011-04-29",
   "enc":"A128CBC-HS256",
   "jku":"https://server.example.com/keys.jwks"
 }
 

Author:

Giriraj Sharma

Constructor Summary

Constructors

Modifier	Constructor and Description
	JWEBuilder() Instantiates a new JWE builder.
protected	JWEBuilder(Class<T> tokenType) Instantiates a new JWE builder.

Method Summary

Methods

Modifier and Type	Method and Description
JWEBuilder<T,B>	algorithm(String algorithm) Sets the algorithm used to encrypt or determine the value of the Content Encryption Key (CEK).
T	build() Builds JsonObjectBuilder.
protected T	build(javax.json.JsonObject headersObject) Builds JsonObject.
T	build(String json) Builds String JSON.
JWEBuilder<T,B>	compressionAlgorithm(String zipAlgorithm) Sets the compression algorithm.
JWEBuilder<T,B>	contentType(String contentType) Sets the content type of JSON Web Encryption
JWEBuilder<T,B>	encryptionAlgorithm(String encAlgorithm, int cekBitLength) Sets the encryption algorithm used to encrypt the Plaintext to produce the Ciphertext.
protected javax.json.JsonObjectBuilder	getHeaderBuilder() Gets the header builder.
protected Class<T>	getTokenType() Gets the token type.
JWEBuilder<T,B>	header(String name, int... value) Updates JWE Header with the specified string header and its value(s).
JWEBuilder<T,B>	header(String name, javax.json.JsonArray value) Updates JWE Header with the specified string header and its value(s).
JWEBuilder<T,B>	header(String name, List<javax.json.JsonObject> value) Updates JWE Header with the specified string header and its value(s).
JWEBuilder<T,B>	header(String name, String... value) Updates JWE Header with the specified string header and its value(s).
JWEBuilder<T,B>	JWKSet(String jwkSetURL) Updates the JWE JSON with the JWKSetURL.
JWEBuilder<T,B>	keyIdentifier(String keyId) Sets the key identifier used to determine the private key needed to decrypt the JWE.
JWEBuilder<T,B>	keys(JWK... keys) Returns the JWK Set consisting of JWK Keys.
JWEBuilder<T,B>	keys(JWKSet keySet) Sets the JSON Web Key Set.
JWEBuilder<T,B>	type(String type) Sets the type of JSON Web Encryption
JWEBuilder<T,B>	X509CertificateChain(String... certificates) Sets the x509 certificate chain.
JWEBuilder<T,B>	X509CertificateSHA1Thumbprint(String sha1Thumbprint) Sets the x509 SHA1 certificate thumbprint.
JWEBuilder<T,B>	X509CertificateSHA256Thumbprint(String sha256Thumbprint) Sets the x509 SHA256 certificate thumbprint.
JWEBuilder<T,B>	X509URL(String x509URL) Sets the x509 URL.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JWEBuilder

public JWEBuilder()

Instantiates a new JWE builder.

JWEBuilder

protected JWEBuilder(Class<T> tokenType)

Instantiates a new JWE builder.

Parameters:

tokenType - the token type

Method Detail

getTokenType

protected Class<T> getTokenType()

Gets the token type.

Returns:

the token type

getHeaderBuilder

protected javax.json.JsonObjectBuilder getHeaderBuilder()

Gets the header builder.

Returns:

the header builder

type

public JWEBuilder<T,B> type(String type)

Sets the type of JSON Web Encryption

The typ (type) Header Parameter is used by JWS or JWE to declare the MIME Media Type [IANA.MediaTypes] of this complete JWS or JWE object. This is intended for use by the application when more than one kind of object could be present in an application data structure that can contain a JWS or JWE object; the application can use this value to disambiguate among the different kinds of objects that might be present. Use of this Header Parameter is OPTIONAL.

Parameters:

type - the String type

Returns:

contentType

public JWEBuilder<T,B> contentType(String contentType)

Sets the content type of JSON Web Encryption

The cty (content type) Header Parameter is used by JWS or JWE applications to declare the MIME Media Type [IANA.MediaTypes] of the secured content (the payload) or encrypted plaintext. This is intended for use by the application when more than one kind of object could be present in the JWS payload or JWE encrypted plaintext; the application can use this value to disambiguate among the different kinds of objects that might be present. Use of this Header Parameter is OPTIONAL.

Parameters:

contentType - the String content type

Returns:

algorithm

public JWEBuilder<T,B> algorithm(String algorithm)

Sets the algorithm used to encrypt or determine the value of the Content Encryption Key (CEK).

The alg (algorithm) Header Parameter identifies the cryptographic algorithm used to secure the JWS or JWE. The signature, MAC, or plaintext value is not valid if the alg value does not represent a supported algorithm, or if there is not a key for use with that algorithm associated with the party that digitally signed or MACed the content. alg values should either be registered in the IANA JSON Web Signature and Encryption Algorithms registry defined in [JWA] or be a value that contains a Collision-Resistant Name. The alg value is a case-sensitive string containing a StringOrURI value.

• RSA1_5
• RSA-OAEP
• RSA-OAEP-256

Parameters:

algorithm - the algorithm as a string

Returns:

encryptionAlgorithm

public JWEBuilder<T,B> encryptionAlgorithm(String encAlgorithm,
                                  int cekBitLength)

Sets the encryption algorithm used to encrypt the Plaintext to produce the Ciphertext.

The enc (encryption algorithm) Header Parameter identifies the content encryption algorithm used to encrypt the Plaintext to produce the Ciphertext. This algorithm MUST be an AEAD algorithm with a specified key length. The recipient MUST reject the JWE if the enc value does not represent a supported algorithm. enc values should either be registered in the IANA JSON Web Signature and Encryption Algorithms registry defined in [JWA] or be a value that contains a Collision-Resistant Name. The enc value is a case-sensitive string containing a StringOrURI value.

• ENC_A128CBC_HS256
• ENC_A192CBC_HS384
• ENC_A256CBC_HS512
• ENC_A128GCM
• ENC_A192GCM
• ENC_A256GCM

Parameters:

encAlgorithm - the encryption algorithm

cekBitLength - the content encryption key bit length

Returns:

keyIdentifier

public JWEBuilder<T,B> keyIdentifier(String keyId)

Sets the key identifier used to determine the private key needed to decrypt the JWE.

The kid (key ID) member can be used to match a specific key. This can be used, for instance, to choose among a set of keys within a JWK Set during key rollover. The structure of the kid value is unspecified. When kid values are used within a JWK Set, different keys within the JWK Set SHOULD use distinct kid values. (One example in which different keys might use the same kid value is if they have different kty (key type) values but are considered to be equivalent alternatives by the application using them.) The kid value is a case-sensitive string. Use of this member is OPTIONAL.

Parameters:

keyId - the key id

Returns:

compressionAlgorithm

public JWEBuilder<T,B> compressionAlgorithm(String zipAlgorithm)

Sets the compression algorithm. The zip (compression algorithm) applied to the Plaintext before encryption, if any. The zip value defined by this specification is:

• DEF - Compression with the DEFLATE [RFC1951] algorithm

Other values MAY be used. Compression algorithm values can be registered in the IANA JSON Web Encryption Compression Algorithm registry defined in [JWA]. The zip value is a case-sensitive string. If no zip parameter is present, no compression is applied to the Plaintext before encryption.

Parameters:

zipAlgorithm - the zip algorithm

Returns:

keys

public JWEBuilder<T,B> keys(JWKSet keySet)

Sets the JSON Web Key Set.

The JWK (JSON Web Key) Header Parameter is the public key that corresponds to the key used to digitally sign the JWS. This key is represented as a JSON Web Key [JWK]. Use of this Header Parameter is OPTIONAL.

Parameters:

keySet - the key set

Returns:

keys

public JWEBuilder<T,B> keys(JWK... keys)

Returns the JWK Set consisting of JWK Keys.

The JWK Keys contains the public key to which the JWE was encrypted; this can be used to determine the private key needed to decrypt the JWE.

Parameters:

keys - the keys

Returns:

JWKSet

public JWEBuilder<T,B> JWKSet(String jwkSetURL)

Updates the JWE JSON with the JWKSetURL.

The jku (JWK Set URL) Header Parameter is a URI [RFC3986] that refers to a resource for a set of JSON-encoded public keys, one of which corresponds to the key used to digitally sign the JWS or encrypt plaintext using JWE. The keys MUST be encoded as a JSON Web Key Set (JWK Set) [JWK]. The protocol used to acquire the resource MUST provide integrity protection; an HTTP GET request to retrieve the JWK Set MUST use TLS [RFC2818, RFC5246]; the identity of the server MUST be validated, as per Section 6 of RFC 6125 [RFC6125]. Use of this Header Parameter is OPTIONAL.

Parameters:

jwkSetURL - the JWK Set URL

Returns:

X509URL

public JWEBuilder<T,B> X509URL(String x509URL)

Sets the x509 URL.

The x5u (X.509 URL) member is a URI [RFC3986] that refers to a resource for an X.509 public key certificate or certificate chain [RFC5280]. The identified resource MUST provide a representation of the certificate or certificate chain that conforms to RFC 5280 [RFC5280] in PEM encoded form [RFC1421]. The key in the first certificate MUST match the public key represented by other members of the JWK. The protocol used to acquire the resource MUST provide integrity protection; an HTTP GET request to retrieve the certificate MUST use TLS [RFC2818, RFC5246]; the identity of the server MUST be validated, as per Section 6 of RFC 6125 [RFC6125]. Use of this member is OPTIONAL.

Parameters:

x509URL - the x509 url

Returns:

X509CertificateChain

public JWEBuilder<T,B> X509CertificateChain(String... certificates)

Sets the x509 certificate chain.

The x5c (X.509 Certificate Chain) member contains a chain of one or more PKIX certificates [RFC5280]. The certificate chain is represented as a JSON array of certificate value strings. Each string in the array is a base64 encoded ([RFC4648] Section 4 -- not base64url encoded) DER [ITU.X690.1994] PKIX certificate value. The PKIX certificate containing the key value MUST be the first certificate. This MAY be followed by additional certificates, with each subsequent certificate being the one used to certify the previous one. The key in the first certificate MUST match the public key represented by other members of the JWK. Use of this member is OPTIONAL.

Parameters:

certificates - the certificates

Returns:

X509CertificateSHA1Thumbprint

public JWEBuilder<T,B> X509CertificateSHA1Thumbprint(String sha1Thumbprint)

Sets the x509 SHA1 certificate thumbprint.

The x5t (X.509 Certificate SHA-1 Thumbprint) member is a base64url encoded SHA-1 thumbprint (a.k.a. digest) of the DER encoding of an X.509 certificate [RFC5280]. The key in the certificate MUST match the public key represented by other members of the JWK. Use of this member is OPTIONAL.

Parameters:

sha1Thumbprint - the sha1 thumbprint

Returns:

X509CertificateSHA256Thumbprint

public JWEBuilder<T,B> X509CertificateSHA256Thumbprint(String sha256Thumbprint)

Sets the x509 SHA256 certificate thumbprint.

The x5t#S256 (X.509 Certificate SHA-256 Thumbprint) member is a base64url encoded SHA-256 thumbprint (a.k.a. digest) of the DER encoding of an X.509 certificate [RFC5280]. The key in the certificate MUST match the public key represented by other members of the JWK. Use of this member is OPTIONAL.

Parameters:

sha256Thumbprint - the sha256 thumbprint

Returns:

header

public JWEBuilder<T,B> header(String name,
                     String... value)

Updates JWE Header with the specified string header and its value(s).

Parameters:

name - the name

value - the value

Returns:

header

public JWEBuilder<T,B> header(String name,
                     int... value)

Updates JWE Header with the specified string header and its value(s).

Parameters:

name - the name

value - the value

Returns:

header

public JWEBuilder<T,B> header(String name,
                     List<javax.json.JsonObject> value)

Updates JWE Header with the specified string header and its value(s).

Parameters:

name - the name

value - the value

Returns:

header

public JWEBuilder<T,B> header(String name,
                     javax.json.JsonArray value)

Updates JWE Header with the specified string header and its value(s).

Parameters:

name - the name

value - the value

Returns:

build

public T build()

Builds JsonObjectBuilder.

Returns:

build

public T build(String json)

Builds String JSON.

Parameters:

json - the json

Returns:

build

protected T build(javax.json.JsonObject headersObject)

Builds JsonObject.

Parameters:

headersObject - the headers object

Returns: