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