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