001/*
002 * nimbus-jose-jwt
003 *
004 * Copyright 2012-2016, Connect2id Ltd.
005 *
006 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use
007 * this file except in compliance with the License. You may obtain a copy of the
008 * License at
009 *
010 *    http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software distributed
013 * under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
014 * CONDITIONS OF ANY KIND, either express or implied. See the License for the
015 * specific language governing permissions and limitations under the License.
016 */
017
018package com.nimbusds.jose;
019
020
021import java.net.URI;
022import java.text.ParseException;
023import java.util.*;
024
025import net.jcip.annotations.Immutable;
026
027import net.minidev.json.JSONObject;
028
029import com.nimbusds.jose.jwk.ECKey;
030import com.nimbusds.jose.jwk.JWK;
031import com.nimbusds.jose.util.Base64;
032import com.nimbusds.jose.util.Base64URL;
033import com.nimbusds.jose.util.JSONObjectUtils;
034import com.nimbusds.jose.util.X509CertChainUtils;
035
036
037/**
038 * JSON Web Encryption (JWE) header. This class is immutable.
039 *
040 * <p>Supports all {@link #getRegisteredParameterNames registered header
041 * parameters} of the JWE specification:
042 *
043 * <ul>
044 *     <li>alg
045 *     <li>enc
046 *     <li>epk
047 *     <li>zip
048 *     <li>jku
049 *     <li>jwk
050 *     <li>x5u
051 *     <li>x5t
052 *     <li>x5t#S256
053 *     <li>x5c
054 *     <li>kid
055 *     <li>typ
056 *     <li>cty
057 *     <li>crit
058 *     <li>apu
059 *     <li>apv
060 *     <li>p2s
061 *     <li>p2c
062 *     <li>iv
063 *     <li>authTag
064 * </ul>
065 *
066 * <p>The header may also include {@link #getCustomParams custom
067 * parameters}; these will be serialised and parsed along the registered ones.
068 *
069 * <p>Example header:
070 *
071 * <pre>
072 * { 
073 *   "alg" : "RSA1_5",
074 *   "enc" : "A128CBC-HS256"
075 * }
076 * </pre>
077 *
078 * @author Vladimir Dzhuvinov
079 * @version 2015-04-15
080 */
081@Immutable
082public final class JWEHeader extends CommonSEHeader {
083
084
085        private static final long serialVersionUID = 1L;
086
087
088        /**
089         * The registered parameter names.
090         */
091        private static final Set<String> REGISTERED_PARAMETER_NAMES;
092
093
094        /**
095         * Initialises the registered parameter name set.
096         */
097        static {
098                Set<String> p = new HashSet<>();
099
100                p.add("alg");
101                p.add("enc");
102                p.add("epk");
103                p.add("zip");
104                p.add("jku");
105                p.add("jwk");
106                p.add("x5u");
107                p.add("x5t");
108                p.add("x5t#S256");
109                p.add("x5c");
110                p.add("kid");
111                p.add("typ");
112                p.add("cty");
113                p.add("crit");
114                p.add("apu");
115                p.add("apv");
116                p.add("p2s");
117                p.add("p2c");
118                p.add("iv");
119                p.add("authTag");
120
121                REGISTERED_PARAMETER_NAMES = Collections.unmodifiableSet(p);
122        }
123
124
125        /**
126         * Builder for constructing JSON Web Encryption (JWE) headers.
127         *
128         * <p>Example usage:
129         *
130         * <pre>
131         * JWEHeader header = new JWEHeader.Builder(JWEAlgorithm.RSA1_5, EncryptionMethod.A128GCM).
132         *                    contentType("text/plain").
133         *                    customParam("exp", new Date().getTime()).
134         *                    build();
135         * </pre>
136         */
137        public static class Builder {
138
139
140                /**
141                 * The JWE algorithm.
142                 */
143                private final JWEAlgorithm alg;
144
145
146                /**
147                 * The encryption method.
148                 */
149                private final EncryptionMethod enc;
150
151
152                /**
153                 * The JOSE object type.
154                 */
155                private JOSEObjectType typ;
156
157
158                /**
159                 * The content type.
160                 */
161                private String cty;
162
163
164                /**
165                 * The critical headers.
166                 */
167                private Set<String> crit;
168
169
170                /**
171                 * JWK Set URL.
172                 */
173                private URI jku;
174
175
176                /**
177                 * JWK.
178                 */
179                private JWK jwk;
180
181
182                /**
183                 * X.509 certificate URL.
184                 */
185                private URI x5u;
186
187
188                /**
189                 * X.509 certificate SHA-1 thumbprint.
190                 */
191                private Base64URL x5t;
192
193
194                /**
195                 * X.509 certificate SHA-256 thumbprint.
196                 */
197                private Base64URL x5t256;
198
199
200                /**
201                 * The X.509 certificate chain corresponding to the key used to
202                 * sign the JWS object.
203                 */
204                private List<Base64> x5c;
205
206
207                /**
208                 * Key ID.
209                 */
210                private String kid;
211
212
213                /**
214                 * The ephemeral public key.
215                 */
216                private ECKey epk;
217
218
219                /**
220                 * The compression algorithm.
221                 */
222                private CompressionAlgorithm zip;
223
224
225                /**
226                 * The agreement PartyUInfo.
227                 */
228                private Base64URL apu;
229
230
231                /**
232                 * The agreement PartyVInfo.
233                 */
234                private Base64URL apv;
235
236
237                /**
238                 * The PBES2 salt.
239                 */
240                private Base64URL p2s;
241
242
243                /**
244                 * The PBES2 count.
245                 */
246                private int p2c;
247
248
249                /**
250                 * The initialisation vector.
251                 */
252                private Base64URL iv;
253
254
255                /**
256                 * The authentication authTag.
257                 */
258                private Base64URL tag;
259
260
261                /**
262                 * Custom header parameters.
263                 */
264                private Map<String,Object> customParams;
265
266
267                /**
268                 * The parsed Base64URL.
269                 */
270                private Base64URL parsedBase64URL;
271
272
273                /**
274                 * Creates a new JWE header builder.
275                 *
276                 * @param alg The JWE algorithm ({@code alg}) parameter. Must
277                 *            not be "none" or {@code null}.
278                 * @param enc The encryption method. Must not be {@code null}.
279                 */
280                public Builder(final JWEAlgorithm alg, final EncryptionMethod enc) {
281
282                        if (alg.getName().equals(Algorithm.NONE.getName())) {
283                                throw new IllegalArgumentException("The JWE algorithm \"alg\" cannot be \"none\"");
284                        }
285
286                        this.alg = alg;
287
288                        if (enc == null) {
289                                throw new IllegalArgumentException("The encryption method \"enc\" parameter must not be null");
290                        }
291
292                        this.enc = enc;
293                }
294
295
296                /**
297                 * Creates a new JWE header builder with the parameters from
298                 * the specified header.
299                 *
300                 * @param jweHeader The JWE header to use. Must not not be 
301                 *                  {@code null}.              
302                 */
303                public Builder(final JWEHeader jweHeader) {
304
305                        this(jweHeader.getAlgorithm(), jweHeader.getEncryptionMethod());
306
307                        typ = jweHeader.getType();
308                        cty = jweHeader.getContentType();
309                        crit = jweHeader.getCriticalParams();
310                        customParams = jweHeader.getCustomParams();
311
312                        jku = jweHeader.getJWKURL();
313                        jwk = jweHeader.getJWK();
314                        x5u = jweHeader.getX509CertURL();
315                        x5t = jweHeader.getX509CertThumbprint();
316                        x5t256 = jweHeader.getX509CertSHA256Thumbprint();
317                        x5c = jweHeader.getX509CertChain();
318                        kid = jweHeader.getKeyID();
319
320                        epk = jweHeader.getEphemeralPublicKey();
321                        zip = jweHeader.getCompressionAlgorithm();
322                        apu = jweHeader.getAgreementPartyUInfo();
323                        apv = jweHeader.getAgreementPartyVInfo();
324                        p2s = jweHeader.getPBES2Salt();
325                        p2c = jweHeader.getPBES2Count();
326                        iv = jweHeader.getIV();
327                        tag = jweHeader.getAuthTag();
328
329                        customParams = jweHeader.getCustomParams();
330                }
331
332
333                /**
334                 * Sets the type ({@code typ}) parameter.
335                 *
336                 * @param typ The type parameter, {@code null} if not
337                 *            specified.
338                 *
339                 * @return This builder.
340                 */
341                public Builder type(final JOSEObjectType typ) {
342
343                        this.typ = typ;
344                        return this;
345                }
346
347
348                /**
349                 * Sets the content type ({@code cty}) parameter.
350                 *
351                 * @param cty The content type parameter, {@code null} if not
352                 *            specified.
353                 *
354                 * @return This builder.
355                 */
356                public Builder contentType(final String cty) {
357
358                        this.cty = cty;
359                        return this;
360                }
361
362
363                /**
364                 * Sets the critical header parameters ({@code crit})
365                 * parameter.
366                 *
367                 * @param crit The names of the critical header parameters,
368                 *             empty set or {@code null} if none.
369                 *
370                 * @return This builder.
371                 */
372                public Builder criticalParams(final Set<String> crit) {
373
374                        this.crit = crit;
375                        return this;
376                }
377
378
379                /**
380                 * Sets the JSON Web Key (JWK) Set URL ({@code jku}) parameter.
381                 *
382                 * @param jku The JSON Web Key (JWK) Set URL parameter,
383                 *            {@code null} if not specified.
384                 *
385                 * @return This builder.
386                 */
387                public Builder jwkURL(final URI jku) {
388
389                        this.jku = jku;
390                        return this;
391                }
392
393
394                /**
395                 * Sets the JSON Web Key (JWK) ({@code jwk}) parameter.
396                 *
397                 * @param jwk The JSON Web Key (JWK) ({@code jwk}) parameter,
398                 *            {@code null} if not specified.
399                 *
400                 * @return This builder.
401                 */
402                public Builder jwk(final JWK jwk) {
403
404                        this.jwk = jwk;
405                        return this;
406                }
407
408
409                /**
410                 * Sets the X.509 certificate URL ({@code x5u}) parameter.
411                 *
412                 * @param x5u The X.509 certificate URL parameter, {@code null}
413                 *            if not specified.
414                 *
415                 * @return This builder.
416                 */
417                public Builder x509CertURL(final URI x5u) {
418
419                        this.x5u = x5u;
420                        return this;
421                }
422
423
424                /**
425                 * Sets the X.509 certificate SHA-1 thumbprint ({@code x5t})
426                 * parameter.
427                 *
428                 * @param x5t The X.509 certificate SHA-1 thumbprint parameter,
429                 *            {@code null} if not specified.
430                 *
431                 * @return This builder.
432                 */
433                public Builder x509CertThumbprint(final Base64URL x5t) {
434
435                        this.x5t = x5t;
436                        return this;
437                }
438
439
440                /**
441                 * Sets the X.509 certificate SHA-256 thumbprint
442                 * ({@code x5t#s256}) parameter.
443                 *
444                 * @param x5t256 The X.509 certificate SHA-256 thumbprint
445                 *               parameter, {@code null} if not specified.
446                 *
447                 * @return This builder.
448                 */
449                public Builder x509CertSHA256Thumbprint(final Base64URL x5t256) {
450
451                        this.x5t256 = x5t256;
452                        return this;
453                }
454
455
456                /**
457                 * Sets the X.509 certificate chain parameter ({@code x5c})
458                 * corresponding to the key used to sign the JWS object.
459                 *
460                 * @param x5c The X.509 certificate chain parameter,
461                 *            {@code null} if not specified.
462                 *
463                 * @return This builder.
464                 */
465                public Builder x509CertChain(final List<Base64> x5c) {
466
467                        this.x5c = x5c;
468                        return this;
469                }
470
471
472                /**
473                 * Sets the key ID ({@code kid}) parameter.
474                 *
475                 * @param kid The key ID parameter, {@code null} if not
476                 *            specified.
477                 *
478                 * @return This builder.
479                 */
480                public Builder keyID(final String kid) {
481
482                        this.kid = kid;
483                        return this;
484                }
485
486
487                /**
488                 * Sets the Ephemeral Public Key ({@code epk}) parameter.
489                 *
490                 * @param epk The Ephemeral Public Key parameter, {@code null}
491                 *            if not specified.
492                 *
493                 * @return This builder.
494                 */
495                public Builder ephemeralPublicKey(final ECKey epk) {
496
497                        this.epk = epk;
498                        return this;
499                }
500
501
502                /**
503                 * Sets the compression algorithm ({@code zip}) parameter.
504                 *
505                 * @param zip The compression algorithm parameter, {@code null}
506                 *            if not specified.
507                 *
508                 * @return This builder.
509                 */
510                public Builder compressionAlgorithm(final CompressionAlgorithm zip) {
511
512                        this.zip = zip;
513                        return this;
514                }
515
516
517                /**
518                 * Sets the agreement PartyUInfo ({@code apu}) parameter.
519                 *
520                 * @param apu The agreement PartyUInfo parameter, {@code null}
521                 *            if not specified.
522                 *
523                 * @return This builder.
524                 */
525                public Builder agreementPartyUInfo(final Base64URL apu) {
526
527                        this.apu = apu;
528                        return this;
529                }
530
531
532                /**
533                 * Sets the agreement PartyVInfo ({@code apv}) parameter.
534                 *
535                 * @param apv The agreement PartyVInfo parameter, {@code null}
536                 *            if not specified.
537                 *
538                 * @return This builder.
539                 */
540                public Builder agreementPartyVInfo(final Base64URL apv) {
541
542                        this.apv = apv;
543                        return this;
544                }
545
546
547                /**
548                 * Sets the PBES2 salt ({@code p2s}) parameter.
549                 *
550                 * @param p2s The PBES2 salt parameter, {@code null} if not
551                 *            specified.
552                 *
553                 * @return This builder.
554                 */
555                public Builder pbes2Salt(final Base64URL p2s) {
556
557                        this.p2s = p2s;
558                        return this;
559                }
560
561
562                /**
563                 * Sets the PBES2 count ({@code p2c}) parameter.
564                 *
565                 * @param p2c The PBES2 count parameter, zero if not specified.
566                 *            Must not be negative.
567                 *
568                 * @return This builder.
569                 */
570                public Builder pbes2Count(final int p2c) {
571
572                        if (p2c < 0)
573                                throw new IllegalArgumentException("The PBES2 count parameter must not be negative");
574
575                        this.p2c = p2c;
576                        return this;
577                }
578
579
580                /**
581                 * Sets the initialisation vector ({@code iv}) parameter.
582                 *
583                 * @param iv The initialisation vector, {@code null} if not
584                 *           specified.
585                 *
586                 * @return This builder.
587                 */
588                public Builder iv(final Base64URL iv) {
589
590                        this.iv = iv;
591                        return this;
592                }
593
594
595                /**
596                 * Sets the authentication tag ({@code tag}) parameter.
597                 *
598                 * @param tag The authentication tag, {@code null} if not
599                 *            specified.
600                 *
601                 * @return This builder.
602                 */
603                public Builder authTag(final Base64URL tag) {
604
605                        this.tag = tag;
606                        return this;
607                }
608
609
610                /**
611                 * Sets a custom (non-registered) parameter.
612                 *
613                 * @param name  The name of the custom parameter. Must not
614                 *              match a registered parameter name and must not
615                 *              be {@code null}.
616                 * @param value The value of the custom parameter, should map
617                 *              to a valid JSON entity, {@code null} if not
618                 *              specified.
619                 *
620                 * @return This builder.
621                 *
622                 * @throws IllegalArgumentException If the specified parameter
623                 *                                  name matches a registered
624                 *                                  parameter name.
625                 */
626                public Builder customParam(final String name, final Object value) {
627
628                        if (getRegisteredParameterNames().contains(name)) {
629                                throw new IllegalArgumentException("The parameter name \"" + name + "\" matches a registered name");
630                        }
631
632                        if (customParams == null) {
633                                customParams = new HashMap<>();
634                        }
635
636                        customParams.put(name, value);
637
638                        return this;
639                }
640
641
642                /**
643                 * Sets the custom (non-registered) parameters. The values must
644                 * be serialisable to a JSON entity, otherwise will be ignored.
645                 *
646                 * @param customParameters The custom parameters, empty map or
647                 *                         {@code null} if none.
648                 *
649                 * @return This builder.
650                 */
651                public Builder customParams(final Map<String, Object> customParameters) {
652
653                        this.customParams = customParameters;
654                        return this;
655                }
656
657
658                /**
659                 * Sets the parsed Base64URL.
660                 *
661                 * @param base64URL The parsed Base64URL, {@code null} if the
662                 *                  header is created from scratch.
663                 *
664                 * @return This builder.
665                 */
666                public Builder parsedBase64URL(final Base64URL base64URL) {
667
668                        this.parsedBase64URL = base64URL;
669                        return this;
670                }
671
672
673                /**
674                 * Builds a new JWE header.
675                 *
676                 * @return The JWE header.
677                 */
678                public JWEHeader build() {
679
680                        return new JWEHeader(
681                                alg, enc, typ, cty, crit,
682                                jku, jwk, x5u, x5t, x5t256, x5c, kid,
683                                epk, zip, apu, apv, p2s, p2c,
684                                iv, tag,
685                                customParams, parsedBase64URL);
686                }
687        }
688
689
690        /**
691         * The encryption method ({@code enc}) parameter.
692         */
693        private final EncryptionMethod enc;
694
695
696        /**
697         * The ephemeral public key ({@code epk}) parameter.
698         */
699        private final ECKey epk;
700
701
702        /**
703         * The compression algorithm ({@code zip}) parameter.
704         */
705        private final CompressionAlgorithm zip;
706
707
708        /**
709         * The agreement PartyUInfo ({@code apu}) parameter.
710         */
711        private final Base64URL apu;
712        
713        
714        /**
715         * The agreement PartyVInfo ({@code apv}) parameter.
716         */
717        private final Base64URL apv;
718
719
720        /**
721         * The PBES2 salt ({@code p2s}) parameter.
722         */
723        private final Base64URL p2s;
724
725
726        /**
727         * The PBES2 count ({@code p2c}) parameter.
728         */
729        private final int p2c;
730
731
732        /**
733         * The initialisation vector ({@code iv}) parameter.
734         */
735        private final Base64URL iv;
736
737
738        /**
739         * The authentication tag ({@code tag}) parameter.
740         */
741        private final Base64URL tag;
742
743
744        /**
745         * Creates a new minimal JSON Web Encryption (JWE) header.
746         *
747         * <p>Note: Use {@link PlainHeader} to create a header with algorithm
748         * {@link Algorithm#NONE none}.
749         *
750         * @param alg The JWE algorithm parameter. Must not be "none" or
751         *            {@code null}.
752         * @param enc The encryption method parameter. Must not be 
753         *            {@code null}.
754         */
755        public JWEHeader(final JWEAlgorithm alg, final EncryptionMethod enc) {
756
757                this(
758                        alg, enc,
759                        null, null, null, null, null, null, null, null, null, null,
760                        null, null, null, null, null, 0,
761                        null, null,
762                        null, null);
763        }
764
765
766        /**
767         * Creates a new JSON Web Encryption (JWE) header.
768         *
769         * <p>Note: Use {@link PlainHeader} to create a header with algorithm
770         * {@link Algorithm#NONE none}.
771         *
772         * @param alg             The JWE algorithm ({@code alg}) parameter.
773         *                        Must not be "none" or {@code null}.
774         * @param enc             The encryption method parameter. Must not be
775         *                        {@code null}.
776         * @param typ             The type ({@code typ}) parameter,
777         *                        {@code null} if not specified.
778         * @param cty             The content type ({@code cty}) parameter,
779         *                        {@code null} if not specified.
780         * @param crit            The names of the critical header
781         *                        ({@code crit}) parameters, empty set or
782         *                        {@code null} if none.
783         * @param jku             The JSON Web Key (JWK) Set URL ({@code jku})
784         *                        parameter, {@code null} if not specified.
785         * @param jwk             The X.509 certificate URL ({@code jwk})
786         *                        parameter, {@code null} if not specified.
787         * @param x5u             The X.509 certificate URL parameter
788         *                        ({@code x5u}), {@code null} if not specified.
789         * @param x5t             The X.509 certificate SHA-1 thumbprint
790         *                        ({@code x5t}) parameter, {@code null} if not
791         *                        specified.
792         * @param x5t256          The X.509 certificate SHA-256 thumbprint
793         *                        ({@code x5t#S256}) parameter, {@code null} if
794         *                        not specified.
795         * @param x5c             The X.509 certificate chain ({@code x5c})
796         *                        parameter, {@code null} if not specified.
797         * @param kid             The key ID ({@code kid}) parameter,
798         *                        {@code null} if not specified.
799         * @param epk             The Ephemeral Public Key ({@code epk})
800         *                        parameter, {@code null} if not specified.
801         * @param zip             The compression algorithm ({@code zip})
802         *                        parameter, {@code null} if not specified.
803         * @param apu             The agreement PartyUInfo ({@code apu})
804         *                        parameter, {@code null} if not specified.
805         * @param apv             The agreement PartyVInfo ({@code apv})
806         *                        parameter, {@code null} if not specified.
807         * @param p2s             The PBES2 salt ({@code p2s}) parameter,
808         *                        {@code null} if not specified.
809         * @param p2c             The PBES2 count ({@code p2c}) parameter, zero
810         *                        if not specified. Must not be negative.
811         * @param iv              The initialisation vector ({@code iv})
812         *                        parameter, {@code null} if not specified.
813         * @param tag             The authentication tag ({@code tag})
814         *                        parameter, {@code null} if not specified.
815         * @param customParams    The custom parameters, empty map or
816         *                        {@code null} if none.
817         * @param parsedBase64URL The parsed Base64URL, {@code null} if the
818         *                        header is created from scratch.
819         */
820        public JWEHeader(final Algorithm alg,
821                         final EncryptionMethod enc,
822                         final JOSEObjectType typ,
823                         final String cty,
824                         final Set<String> crit,
825                         final URI jku,
826                         final JWK jwk,
827                         final URI x5u,
828                         final Base64URL x5t,
829                         final Base64URL x5t256,
830                         final List<Base64> x5c,
831                         final String kid,
832                         final ECKey epk,
833                         final CompressionAlgorithm zip,
834                         final Base64URL apu,
835                         final Base64URL apv,
836                         final Base64URL p2s,
837                         final int p2c,
838                         final Base64URL iv,
839                         final Base64URL tag,
840                         final Map<String,Object> customParams,
841                         final Base64URL parsedBase64URL) {
842
843                super(alg, typ, cty, crit, jku, jwk, x5u, x5t, x5t256, x5c, kid, customParams, parsedBase64URL);
844
845                if (alg.getName().equals(Algorithm.NONE.getName())) {
846                        throw new IllegalArgumentException("The JWE algorithm cannot be \"none\"");
847                }
848
849                if (enc == null) {
850                        throw new IllegalArgumentException("The encryption method \"enc\" parameter must not be null");
851                }
852
853                this.enc = enc;
854
855                this.epk = epk;
856                this.zip = zip;
857                this.apu = apu;
858                this.apv = apv;
859                this.p2s = p2s;
860                this.p2c = p2c;
861                this.iv = iv;
862                this.tag = tag;
863        }
864
865
866        /**
867         * Deep copy constructor.
868         *
869         * @param jweHeader The JWE header to copy. Must not be {@code null}.
870         */
871        public JWEHeader(final JWEHeader jweHeader) {
872
873                this(
874                        jweHeader.getAlgorithm(),
875                        jweHeader.getEncryptionMethod(),
876                        jweHeader.getType(),
877                        jweHeader.getContentType(),
878                        jweHeader.getCriticalParams(),
879                        jweHeader.getJWKURL(),
880                        jweHeader.getJWK(),
881                        jweHeader.getX509CertURL(),
882                        jweHeader.getX509CertThumbprint(),
883                        jweHeader.getX509CertSHA256Thumbprint(),
884                        jweHeader.getX509CertChain(),
885                        jweHeader.getKeyID(),
886                        jweHeader.getEphemeralPublicKey(),
887                        jweHeader.getCompressionAlgorithm(),
888                        jweHeader.getAgreementPartyUInfo(),
889                        jweHeader.getAgreementPartyVInfo(),
890                        jweHeader.getPBES2Salt(),
891                        jweHeader.getPBES2Count(),
892                        jweHeader.getIV(),
893                        jweHeader.getAuthTag(),
894                        jweHeader.getCustomParams(),
895                        jweHeader.getParsedBase64URL()
896                );
897        }
898
899
900        /**
901         * Gets the registered parameter names for JWE headers.
902         *
903         * @return The registered parameter names, as an unmodifiable set.
904         */
905        public static Set<String> getRegisteredParameterNames() {
906
907                return REGISTERED_PARAMETER_NAMES;
908        }
909
910
911        /**
912         * Gets the algorithm ({@code alg}) parameter.
913         *
914         * @return The algorithm parameter.
915         */
916        public JWEAlgorithm getAlgorithm() {
917
918                return (JWEAlgorithm)super.getAlgorithm();
919        }
920
921
922        /**
923         * Gets the encryption method ({@code enc}) parameter.
924         *
925         * @return The encryption method parameter.
926         */
927        public EncryptionMethod getEncryptionMethod() {
928
929                return enc;
930        }
931
932
933        /**
934         * Gets the Ephemeral Public Key ({@code epk}) parameter.
935         *
936         * @return The Ephemeral Public Key parameter, {@code null} if not
937         *         specified.
938         */
939        public ECKey getEphemeralPublicKey() {
940
941                return epk;
942        }
943
944
945        /**
946         * Gets the compression algorithm ({@code zip}) parameter.
947         *
948         * @return The compression algorithm parameter, {@code null} if not
949         *         specified.
950         */
951        public CompressionAlgorithm getCompressionAlgorithm() {
952
953                return zip;
954        }
955
956
957        /**
958         * Gets the agreement PartyUInfo ({@code apu}) parameter.
959         *
960         * @return The agreement PartyUInfo parameter, {@code null} if not
961         *         specified.
962         */
963        public Base64URL getAgreementPartyUInfo() {
964
965                return apu;
966        }
967
968
969        /**
970         * Gets the agreement PartyVInfo ({@code apv}) parameter.
971         *
972         * @return The agreement PartyVInfo parameter, {@code null} if not
973         *         specified.
974         */
975        public Base64URL getAgreementPartyVInfo() {
976
977                return apv;
978        }
979
980
981        /**
982         * Gets the PBES2 salt ({@code p2s}) parameter.
983         *
984         * @return The PBES2 salt parameter, {@code null} if not specified.
985         */
986        public Base64URL getPBES2Salt() {
987
988                return p2s;
989        }
990
991
992        /**
993         * Gets the PBES2 count ({@code p2c}) parameter.
994         *
995         * @return The PBES2 count parameter, zero if not specified.
996         */
997        public int getPBES2Count() {
998
999                return p2c;
1000        }
1001
1002
1003        /**
1004         * Gets the initialisation vector ({@code iv}) parameter.
1005         *
1006         * @return The initialisation vector, {@code null} if not specified.
1007         */
1008        public Base64URL getIV() {
1009
1010                return iv;
1011        }
1012
1013
1014        /**
1015         * Gets the authentication tag ({@code tag}) parameter.
1016         *
1017         * @return The authentication tag, {@code null} if not specified.
1018         */
1019        public Base64URL getAuthTag() {
1020
1021                return tag;
1022        }
1023
1024
1025        @Override
1026        public Set<String> getIncludedParams() {
1027
1028                Set<String> includedParameters = super.getIncludedParams();
1029
1030                if (enc != null) {
1031                        includedParameters.add("enc");
1032                }
1033
1034                if (epk != null) {
1035                        includedParameters.add("epk");
1036                }
1037
1038                if (zip != null) {
1039                        includedParameters.add("zip");
1040                }
1041
1042                if (apu != null) {
1043                        includedParameters.add("apu");
1044                }
1045                
1046                if (apv != null) {
1047                        includedParameters.add("apv");
1048                }
1049
1050                if (p2s != null) {
1051                        includedParameters.add("p2s");
1052                }
1053
1054                if (p2c > 0) {
1055                        includedParameters.add("p2c");
1056                }
1057
1058                if (iv != null) {
1059                        includedParameters.add("iv");
1060                }
1061
1062                if (tag != null) {
1063                        includedParameters.add("tag");
1064                }
1065
1066                return includedParameters;
1067        }
1068
1069
1070        @Override
1071        public JSONObject toJSONObject() {
1072
1073                JSONObject o = super.toJSONObject();
1074
1075                if (enc != null) {
1076                        o.put("enc", enc.toString());
1077                }
1078
1079                if (epk != null) {
1080                        o.put("epk", epk.toJSONObject());
1081                }
1082
1083                if (zip != null) {
1084                        o.put("zip", zip.toString());
1085                }
1086
1087                if (apu != null) {
1088                        o.put("apu", apu.toString());
1089                }
1090                
1091                if (apv != null) {
1092                        o.put("apv", apv.toString());
1093                }
1094
1095                if (p2s != null) {
1096                        o.put("p2s", p2s.toString());
1097                }
1098
1099                if (p2c > 0) {
1100                        o.put("p2c", p2c);
1101                }
1102
1103                if (iv != null) {
1104                        o.put("iv", iv.toString());
1105                }
1106
1107                if (tag != null) {
1108                        o.put("tag", tag.toString());
1109                }
1110
1111                return o;
1112        }
1113
1114
1115        /**
1116         * Parses an encryption method ({@code enc}) parameter from the 
1117         * specified JWE header JSON object.
1118         *
1119         * @param json The JSON object to parse. Must not be {@code null}.
1120         *
1121         * @return The encryption method.
1122         *
1123         * @throws ParseException If the {@code enc} parameter couldn't be 
1124         *                        parsed.
1125         */
1126        private static EncryptionMethod parseEncryptionMethod(final JSONObject json)
1127                throws ParseException {
1128
1129                return EncryptionMethod.parse(JSONObjectUtils.getString(json, "enc"));
1130        }
1131
1132
1133        /**
1134         * Parses a JWE header from the specified JSON object.
1135         *
1136         * @param jsonObject The JSON object to parse. Must not be
1137         *                   {@code null}.
1138         *
1139         * @return The JWE header.
1140         *
1141         * @throws ParseException If the specified JSON object doesn't
1142         *                        represent a valid JWE header.
1143         */
1144        public static JWEHeader parse(final JSONObject jsonObject)
1145                throws ParseException {
1146
1147                return parse(jsonObject, null);
1148        }
1149
1150
1151        /**
1152         * Parses a JWE header from the specified JSON object.
1153         *
1154         * @param jsonObject      The JSON object to parse. Must not be
1155         *                        {@code null}.
1156         * @param parsedBase64URL The original parsed Base64URL, {@code null}
1157         *                        if not applicable.
1158         *
1159         * @return The JWE header.
1160         *
1161         * @throws ParseException If the specified JSON object doesn't 
1162         *                        represent a valid JWE header.
1163         */
1164        public static JWEHeader parse(final JSONObject jsonObject,
1165                                      final Base64URL parsedBase64URL)
1166                throws ParseException {
1167
1168                // Get the "alg" parameter
1169                Algorithm alg = Header.parseAlgorithm(jsonObject);
1170
1171                if (! (alg instanceof JWEAlgorithm)) {
1172                        throw new ParseException("The algorithm \"alg\" header parameter must be for encryption", 0);
1173                }
1174
1175                // Get the "enc" parameter
1176                EncryptionMethod enc = parseEncryptionMethod(jsonObject);
1177
1178                JWEHeader.Builder header = new Builder((JWEAlgorithm)alg, enc).parsedBase64URL(parsedBase64URL);
1179
1180                // Parse optional + custom parameters
1181                for(final String name: jsonObject.keySet()) {
1182
1183                        if("alg".equals(name)) {
1184                                // skip
1185                        } else if("enc".equals(name)) {
1186                                // skip
1187                        } else if("typ".equals(name)) {
1188                                header = header.type(new JOSEObjectType(JSONObjectUtils.getString(jsonObject, name)));
1189                        } else if("cty".equals(name)) {
1190                                header = header.contentType(JSONObjectUtils.getString(jsonObject, name));
1191                        } else if("crit".equals(name)) {
1192                                header = header.criticalParams(new HashSet<>(JSONObjectUtils.getStringList(jsonObject, name)));
1193                        } else if("jku".equals(name)) {
1194                                header = header.jwkURL(JSONObjectUtils.getURI(jsonObject, name));
1195                        } else if("jwk".equals(name)) {
1196                                header = header.jwk(JWK.parse(JSONObjectUtils.getJSONObject(jsonObject, name)));
1197                        } else if("x5u".equals(name)) {
1198                                header = header.x509CertURL(JSONObjectUtils.getURI(jsonObject, name));
1199                        } else if("x5t".equals(name)) {
1200                                header = header.x509CertThumbprint(new Base64URL(JSONObjectUtils.getString(jsonObject, name)));
1201                        } else if("x5t#S256".equals(name)) {
1202                                header = header.x509CertSHA256Thumbprint(new Base64URL(JSONObjectUtils.getString(jsonObject, name)));
1203                        } else if("x5c".equals(name)) {
1204                                header = header.x509CertChain(X509CertChainUtils.parseX509CertChain(JSONObjectUtils.getJSONArray(jsonObject, name)));
1205                        } else if("kid".equals(name)) {
1206                                header = header.keyID(JSONObjectUtils.getString(jsonObject, name));
1207                        } else if("epk".equals(name)) {
1208                                header = header.ephemeralPublicKey(ECKey.parse(JSONObjectUtils.getJSONObject(jsonObject, name)));
1209                        } else if("zip".equals(name)) {
1210                                header = header.compressionAlgorithm(new CompressionAlgorithm(JSONObjectUtils.getString(jsonObject, name)));
1211                        } else if("apu".equals(name)) {
1212                                header = header.agreementPartyUInfo(new Base64URL(JSONObjectUtils.getString(jsonObject, name)));
1213                        } else if("apv".equals(name)) {
1214                                header = header.agreementPartyVInfo(new Base64URL(JSONObjectUtils.getString(jsonObject, name)));
1215                        } else if("p2s".equals(name)) {
1216                                header = header.pbes2Salt(new Base64URL(JSONObjectUtils.getString(jsonObject, name)));
1217                        } else if("p2c".equals(name)) {
1218                                header = header.pbes2Count(JSONObjectUtils.getInt(jsonObject, name));
1219                        } else if("iv".equals(name)) {
1220                                header = header.iv(new Base64URL(JSONObjectUtils.getString(jsonObject, name)));
1221                        } else if("tag".equals(name)) {
1222                                header = header.authTag(new Base64URL(JSONObjectUtils.getString(jsonObject, name)));
1223                        } else {
1224                                header = header.customParam(name, jsonObject.get(name));
1225                        }
1226                }
1227
1228                return header.build();
1229        }
1230
1231
1232        /**
1233         * Parses a JWE header from the specified JSON object string.
1234         *
1235         * @param jsonString The JSON object string to parse. Must not be {@code null}.
1236         *
1237         * @return The JWE header.
1238         *
1239         * @throws ParseException If the specified JSON object string doesn't 
1240         *                        represent a valid JWE header.
1241         */
1242        public static JWEHeader parse(final String jsonString)
1243                throws ParseException {
1244
1245                return parse(JSONObjectUtils.parse(jsonString), null);
1246        }
1247
1248
1249        /**
1250         * Parses a JWE header from the specified JSON object string.
1251         *
1252         * @param jsonString      The JSON string to parse. Must not be
1253         *                        {@code null}.
1254         * @param parsedBase64URL The original parsed Base64URL, {@code null}
1255         *                        if not applicable.
1256         *
1257         * @return The JWE header.
1258         *
1259         * @throws ParseException If the specified JSON object string doesn't
1260         *                        represent a valid JWE header.
1261         */
1262        public static JWEHeader parse(final String jsonString,
1263                                      final Base64URL parsedBase64URL)
1264                throws ParseException {
1265
1266                return parse(JSONObjectUtils.parse(jsonString), parsedBase64URL);
1267        }
1268
1269
1270        /**
1271         * Parses a JWE header from the specified Base64URL.
1272         *
1273         * @param base64URL The Base64URL to parse. Must not be {@code null}.
1274         *
1275         * @return The JWE header.
1276         *
1277         * @throws ParseException If the specified Base64URL doesn't represent
1278         *                        a valid JWE header.
1279         */
1280        public static JWEHeader parse(final Base64URL base64URL)
1281                throws ParseException {
1282
1283                return parse(base64URL.decodeToString(), base64URL);
1284        }
1285}