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 com.nimbusds.jose.util.ArrayUtils;
022import net.jcip.annotations.Immutable;
023
024
025/**
026 * JSON Web Signature (JWS) algorithm name, represents the {@code alg} header
027 * parameter in JWS objects. Also used to represent integrity algorithm 
028 * ({@code ia}) header parameters in JWE objects. This class is immutable.
029 *
030 * <p>Includes constants for the following standard JWS algorithm names:
031 *
032 * <ul>
033 *     <li>{@link #HS256}
034 *     <li>{@link #HS384}
035 *     <li>{@link #HS512}
036 *     <li>{@link #RS256}
037 *     <li>{@link #RS384}
038 *     <li>{@link #RS512}
039 *     <li>{@link #ES256}
040 *     <li>{@link #ES384}
041 *     <li>{@link #ES512}
042 *     <li>{@link #PS256}
043 *     <li>{@link #PS384}
044 *     <li>{@link #PS512}
045 *     <li>{@link #EdDSA}
046 * </ul>
047 *
048 * <p>Additional JWS algorithm names can be defined using the constructors.
049 *
050 * @author Vladimir Dzhuvinov
051 * @version 2017-08-22
052 */
053@Immutable
054public final class JWSAlgorithm extends Algorithm {
055
056
057        private static final long serialVersionUID = 1L;
058
059
060        /**
061         * HMAC using SHA-256 hash algorithm (required).
062         */
063        public static final JWSAlgorithm HS256 = new JWSAlgorithm("HS256", Requirement.REQUIRED);
064
065
066        /**
067         * HMAC using SHA-384 hash algorithm (optional).
068         */
069        public static final JWSAlgorithm HS384 = new JWSAlgorithm("HS384", Requirement.OPTIONAL);
070
071
072        /**
073         * HMAC using SHA-512 hash algorithm (optional).
074         */
075        public static final JWSAlgorithm HS512 = new JWSAlgorithm("HS512", Requirement.OPTIONAL);
076
077
078        /**
079         * RSASSA-PKCS-v1_5 using SHA-256 hash algorithm (recommended).
080         */
081        public static final JWSAlgorithm RS256 = new JWSAlgorithm("RS256", Requirement.RECOMMENDED);
082
083
084        /**
085         * RSASSA-PKCS-v1_5 using SHA-384 hash algorithm (optional).
086         */
087        public static final JWSAlgorithm RS384 = new JWSAlgorithm("RS384", Requirement.OPTIONAL);
088
089
090        /**
091         * RSASSA-PKCS-v1_5 using SHA-512 hash algorithm (optional).
092         */
093        public static final JWSAlgorithm RS512 = new JWSAlgorithm("RS512", Requirement.OPTIONAL);
094
095
096        /**
097         * ECDSA using P-256 curve and SHA-256 hash algorithm (recommended).
098         */
099        public static final JWSAlgorithm ES256 = new JWSAlgorithm("ES256", Requirement.RECOMMENDED);
100
101
102        /**
103         * ECDSA using P-384 curve and SHA-384 hash algorithm (optional).
104         */
105        public static final JWSAlgorithm ES384 = new JWSAlgorithm("ES384", Requirement.OPTIONAL);
106
107
108        /**
109         * ECDSA using P-521 curve and SHA-512 hash algorithm (optional).
110         */
111        public static final JWSAlgorithm ES512 = new JWSAlgorithm("ES512", Requirement.OPTIONAL);
112
113
114        /**
115         * RSASSA-PSS using SHA-256 hash algorithm and MGF1 mask generation
116         * function with SHA-256 (optional).
117         */
118        public static final JWSAlgorithm PS256 = new JWSAlgorithm("PS256", Requirement.OPTIONAL);
119
120
121        /**
122         * RSASSA-PSS using SHA-384 hash algorithm and MGF1 mask generation
123         * function with SHA-384 (optional).
124         */
125        public static final JWSAlgorithm PS384 = new JWSAlgorithm("PS384", Requirement.OPTIONAL);
126
127
128        /**
129         * RSASSA-PSS using SHA-512 hash algorithm and MGF1 mask generation
130         * function with SHA-512 (optional).
131         */
132        public static final JWSAlgorithm PS512 = new JWSAlgorithm("PS512", Requirement.OPTIONAL);
133        
134        
135        /**
136         * EdDSA signature algorithms (optional).
137         */
138        public static final JWSAlgorithm EdDSA = new JWSAlgorithm("EdDSA", Requirement.OPTIONAL);
139
140
141        /**
142         * JWS algorithm family.
143         */
144        public static final class Family extends AlgorithmFamily<JWSAlgorithm> {
145
146
147                private static final long serialVersionUID = 1L;
148
149
150                /**
151                 * HMAC using a SHA-2 hash.
152                 */
153                public static final Family HMAC_SHA = new Family(HS256, HS384, HS512);
154
155
156                /**
157                 * RSA signature (RSASSA-PKCS-v1_5 or RSASSA-PSS) using a SHA-2
158                 * hash.
159                 */
160                public static final Family RSA = new Family(RS256, RS384, RS512, PS256, PS384, PS512);
161
162
163                /**
164                 * Elliptic Curve signature (ECDSA) using a SHA-2 hash.
165                 */
166                public static final Family EC = new Family(ES256, ES384, ES512);
167                
168                
169                /**
170                 * Edwards Curve signature (EdDSA).
171                 */
172                public static final Family ED = new Family(EdDSA);
173                
174                
175                /**
176                 * Super family of all digital signature based JWS algorithms.
177                 */
178                public static final Family SIGNATURE = new Family(ArrayUtils
179                        .concat(
180                                RSA.toArray(new JWSAlgorithm[]{}),
181                                EC.toArray(new JWSAlgorithm[]{}),
182                                ED.toArray(new JWSAlgorithm[]{})
183                        )
184                );
185
186
187                /***
188                 * Creates a new JWS algorithm family.
189                 *
190                 * @param algs The JWS algorithms of the family. Must not be
191                 *             {@code null}.
192                 */
193                public Family(final JWSAlgorithm ... algs) {
194                        super(algs);
195                }
196        }
197
198
199        /**
200         * Creates a new JSON Web Signature (JWS) algorithm name.
201         *
202         * @param name The algorithm name. Must not be {@code null}.
203         * @param req  The implementation requirement, {@code null} if not 
204         *             known.
205         */
206        public JWSAlgorithm(final String name, final Requirement req) {
207
208                super(name, req);
209        }
210
211
212        /**
213         * Creates a new JSON Web Signature (JWS) algorithm name.
214         *
215         * @param name The algorithm name. Must not be {@code null}.
216         */
217        public JWSAlgorithm(final String name) {
218
219                super(name, null);
220        }
221
222
223        /**
224         * Parses a JWS algorithm from the specified string.
225         *
226         * @param s The string to parse. Must not be {@code null}.
227         *
228         * @return The JWS algorithm (matching standard algorithm constant, else
229         *         a newly created algorithm).
230         */
231        public static JWSAlgorithm parse(final String s) {
232
233                if (s.equals(HS256.getName())) {
234                        return HS256;
235                } else if (s.equals(HS384.getName())) {
236                        return HS384;
237                } else if (s.equals(HS512.getName())) {
238                        return HS512;
239                } else if (s.equals(RS256.getName())) {
240                        return RS256;
241                } else if (s.equals(RS384.getName())) {
242                        return RS384;
243                } else if (s.equals(RS512.getName())) {
244                        return RS512;
245                } else if (s.equals(ES256.getName())) {
246                        return ES256;
247                } else if (s.equals(ES384.getName())) {
248                        return ES384;
249                } else if (s.equals(ES512.getName())) {
250                        return ES512;
251                } else if (s.equals(PS256.getName())) {
252                        return PS256;
253                } else if (s.equals(PS384.getName())) {
254                        return PS384;
255                } else if (s.equals(PS512.getName())) {
256                        return PS512;
257                } else if (s.equals(EdDSA.getName())) {
258                        return EdDSA;
259                } else {
260                        return new JWSAlgorithm(s);
261                }
262        }
263}