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