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