001/*
002 * nimbus-jose-jwt
003 *
004 * Copyright 2012-2016, Connect2id Ltd and contributors.
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.jwk.gen;
019
020
021import java.security.KeyStore;
022import java.security.Provider;
023import java.security.SecureRandom;
024import java.util.Date;
025import java.util.Set;
026
027import com.nimbusds.jose.Algorithm;
028import com.nimbusds.jose.JOSEException;
029import com.nimbusds.jose.jwk.JWK;
030import com.nimbusds.jose.jwk.JWKSet;
031import com.nimbusds.jose.jwk.KeyOperation;
032import com.nimbusds.jose.jwk.KeyUse;
033
034
035/**
036 * Abstract JWK generator.
037 *
038 * @author Vladimir Dzhuvinov
039 * @author Justin Cranford
040 * @version 2023-01-29
041 */
042public abstract class JWKGenerator<T extends JWK> {
043        
044        
045        /**
046         * The key use, optional.
047         */
048        protected KeyUse use;
049        
050        
051        /**
052         * The key operations, optional.
053         */
054        protected Set<KeyOperation> ops;
055        
056        
057        /**
058         * The intended JOSE algorithm for the key, optional.
059         */
060        protected Algorithm alg;
061        
062        
063        /**
064         * The key ID, optional.
065         */
066        protected String kid;
067        
068        
069        /**
070         * If {@code true} sets the ID of the JWK to the SHA-256 thumbprint of
071         * the JWK.
072         */
073        protected boolean x5tKid;
074        
075        
076         /**
077         * The key expiration time, optional.
078         */
079        protected Date exp;
080        
081        
082        /**
083         * The key not-before time, optional.
084         */
085        protected Date nbf;
086        
087        
088        /**
089         * The key issued-at time, optional.
090         */
091        protected Date iat;
092        
093        
094        /**
095         * Reference to the underlying key store, {@code null} if none.
096         */
097        protected KeyStore keyStore;
098        
099        
100        /**
101         * The JCA provider, {@code null} to use the default one.
102         */
103        protected Provider provider;
104
105
106        /**
107         * The secure random generator to use, {@code null} to use the default
108         * one.
109         */
110        protected SecureRandom secureRandom;
111
112
113        /**
114         * Sets the use ({@code use}) of the JWK.
115         *
116         * @param use The key use, {@code null} if not specified or if 
117         *            the key is intended for signing as well as 
118         *            encryption.
119         *
120         * @return This generator.
121         */
122        public JWKGenerator<T> keyUse(final KeyUse use) {
123                this.use = use;
124                return this;
125        }
126        
127        
128        /**
129         * Sets the operations ({@code key_ops}) of the JWK.
130         *
131         * @param ops The key operations, {@code null} if not
132         *            specified.
133         *
134         * @return This generator.
135         */
136        public JWKGenerator<T> keyOperations(final Set<KeyOperation> ops) {
137                this.ops = ops;
138                return this;
139        }
140        
141        
142        /**
143         * Sets the intended JOSE algorithm ({@code alg}) for the JWK.
144         *
145         * @param alg The intended JOSE algorithm, {@code null} if not 
146         *            specified.
147         *
148         * @return This generator.
149         */
150        public JWKGenerator<T> algorithm(final Algorithm alg) {
151                this.alg = alg;
152                return this;
153        }
154        
155        /**
156         * Sets the ID ({@code kid}) of the JWK. The key ID can be used 
157         * to match a specific key. This can be used, for instance, to 
158         * choose a key within a {@link JWKSet} during key rollover. 
159         * The key ID may also correspond to a JWS/JWE {@code kid}
160         * header parameter value.
161         *
162         * @param kid The key ID, {@code null} if not specified.
163         *
164         * @return This generator.
165         */
166        public JWKGenerator<T> keyID(final String kid) {
167                this.kid = kid;
168                return this;
169        }
170        
171        
172        /**
173         * Sets the ID ({@code kid}) of the JWK to its SHA-256 JWK
174         * thumbprint (RFC 7638). The key ID can be used to match a
175         * specific key. This can be used, for instance, to choose a
176         * key within a {@link JWKSet} during key rollover. The key ID
177         * may also correspond to a JWS/JWE {@code kid} header
178         * parameter value.
179         *
180         * @param x5tKid If {@code true} sets the ID of the JWK to the SHA-256
181         *               JWK thumbprint.
182         *
183         * @return This generator.
184         */
185        public JWKGenerator<T> keyIDFromThumbprint(final boolean x5tKid) {
186                this.x5tKid = x5tKid;
187                return this;
188        }
189        
190        
191        /**
192         * Sets the expiration time ({@code exp}) of the JWK.
193         *
194         * @param exp The expiration time, {@code null} if not
195         *            specified.
196         *
197         * @return This generator.
198         */
199        public JWKGenerator<T> expirationTime(final Date exp) {
200                this.exp = exp;
201                return this;
202        }
203        
204        
205        /**
206         * Sets the not-before time ({@code nbf}) of the JWK.
207         *
208         * @param nbf The not-before time, {@code null} if not
209         *            specified.
210         *
211         * @return This generator.
212         */
213        public JWKGenerator<T> notBeforeTime(final Date nbf) {
214                this.nbf = nbf;
215                return this;
216        }
217        
218        
219        /**
220         * Sets the issued-at time ({@code iat}) of the JWK.
221         *
222         * @param iat The issued-at time, {@code null} if not
223         *            specified.
224         *
225         * @return This generator.
226         */
227        public JWKGenerator<T> issueTime(final Date iat) {
228                this.iat = iat;
229                return this;
230        }
231        
232        
233        /**
234         * Sets the underlying key store. Overrides the {@link #provider JCA
235         * provider} is set. Note, some JWK generators may not use the JCA key
236         * store API.
237         *
238         * @param keyStore Reference to the underlying key store,
239         *                 {@code null} if none.
240         *
241         * @return This generator.
242         */
243        public JWKGenerator<T> keyStore(final KeyStore keyStore) {
244                this.keyStore = keyStore;
245                return this;
246        }
247        
248        
249        /**
250         * Sets the JCA provider for the key generation. Note, some JWK
251         * generators may not use the JCA provider API.
252         *
253         * @param provider The JCA provider, {@code null} to use the default
254         *                 one.
255         *
256         * @return This generator.
257         */
258        public JWKGenerator<T> provider(final Provider provider) {
259                this.provider = provider;
260                return this;
261        }
262        
263        
264        /**
265         * Sets the secure random generator to use. Note, some JWK generators
266         * may not use the JCA secure random API.
267         *
268         * @param secureRandom The secure random generator to use, {@code null}
269         *                     to use the default one.
270         *
271         * @return This generator.
272         */
273        public JWKGenerator<T> secureRandom(final SecureRandom secureRandom) {
274                this.secureRandom = secureRandom;
275                return this;
276        }
277        
278        
279        /**
280         * Generates the JWK according to the set parameters.
281         *
282         * @return The generated JWK.
283         *
284         * @throws JOSEException If the key generation failed.
285         */
286        public abstract T generate() throws JOSEException;
287}