1 /*
2 * Copyright (c) 2001, 2019, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.security.spec;
27
28 import java.util.Objects;
29
30 /**
31 * This class specifies a parameter spec for RSASSA-PSS signature scheme,
32 * as defined in the
33 * <a href="https://tools.ietf.org/rfc/rfc8017.txt">PKCS#1 v2.2</a> standard.
34 *
35 * <p>Its ASN.1 definition in PKCS#1 standard is described below:
36 * <pre>
37 * RSASSA-PSS-params ::= SEQUENCE {
38 * hashAlgorithm [0] HashAlgorithm DEFAULT sha1,
39 * maskGenAlgorithm [1] MaskGenAlgorithm DEFAULT mgf1SHA1,
40 * saltLength [2] INTEGER DEFAULT 20,
41 * trailerField [3] TrailerField DEFAULT trailerFieldBC(1)
42 * }
43 * </pre>
44 * where
45 * <pre>
46 * HashAlgorithm ::= AlgorithmIdentifier {
47 * {OAEP-PSSDigestAlgorithms}
48 * }
49 * MaskGenAlgorithm ::= AlgorithmIdentifier { {PKCS1MGFAlgorithms} }
50 * TrailerField ::= INTEGER { trailerFieldBC(1) }
51 *
52 * OAEP-PSSDigestAlgorithms ALGORITHM-IDENTIFIER ::= {
53 * { OID id-sha1 PARAMETERS NULL }|
54 * { OID id-sha224 PARAMETERS NULL }|
55 * { OID id-sha256 PARAMETERS NULL }|
56 * { OID id-sha384 PARAMETERS NULL }|
57 * { OID id-sha512 PARAMETERS NULL }|
58 * { OID id-sha512-224 PARAMETERS NULL }|
59 * { OID id-sha512-256 PARAMETERS NULL },
60 * ... -- Allows for future expansion --
61 * }
62 * PKCS1MGFAlgorithms ALGORITHM-IDENTIFIER ::= {
63 * { OID id-mgf1 PARAMETERS HashAlgorithm },
64 * ... -- Allows for future expansion --
65 * }
66 * </pre>
67 * <p>Note: the PSSParameterSpec.DEFAULT uses the following:
68 * message digest -- "SHA-1"
69 * mask generation function (mgf) -- "MGF1"
70 * parameters for mgf -- MGF1ParameterSpec.SHA1
71 * SaltLength -- 20
72 * TrailerField -- 1
73 *
74 * @see MGF1ParameterSpec
75 * @see AlgorithmParameterSpec
76 * @see java.security.Signature
77 *
78 * @author Valerie Peng
79 *
80 *
81 * @since 1.4
82 */
83
84 public class PSSParameterSpec implements AlgorithmParameterSpec {
85
86 private final String mdName;
87
88 private final String mgfName;
89
90 private final AlgorithmParameterSpec mgfSpec;
91
92 private final int saltLen;
93
94 private final int trailerField;
95
96 /**
97 * The {@code TrailerFieldBC} constant as defined in PKCS#1
98 *
99 * @since 11
100 */
101 public static final int TRAILER_FIELD_BC = 1;
102
103 /**
104 * The PSS parameter set with all default values
105 *
106 * @since 1.5
107 */
108 public static final PSSParameterSpec DEFAULT = new PSSParameterSpec
109 ("SHA-1", "MGF1", MGF1ParameterSpec.SHA1, 20, TRAILER_FIELD_BC);
110
111
112 // disallowed
113 private PSSParameterSpec() {
114 throw new RuntimeException("default constructor not allowed");
115 }
116
117
118 /**
119 * Creates a new {@code PSSParameterSpec} as defined in
120 * the PKCS #1 standard using the specified message digest,
121 * mask generation function, parameters for mask generation
122 * function, salt length, and trailer field values.
123 *
124 * @param mdName the algorithm name of the hash function
125 * @param mgfName the algorithm name of the mask generation function
126 * @param mgfSpec the parameters for the mask generation function.
127 * If null is specified, null will be returned by
128 * getMGFParameters().
129 * @param saltLen the length of salt
130 * @param trailerField the value of the trailer field
131 * @exception NullPointerException if {@code mdName}, or {@code mgfName}
132 * is null
133 * @exception IllegalArgumentException if {@code saltLen} or
134 * {@code trailerField} is less than 0
135 * @since 1.5
136 */
137 public PSSParameterSpec(String mdName, String mgfName,
138 AlgorithmParameterSpec mgfSpec, int saltLen, int trailerField) {
139 Objects.requireNonNull(mdName, "digest algorithm is null");
140 Objects.requireNonNull(mgfName,
141 "mask generation function algorithm is null");
142 if (saltLen < 0) {
143 throw new IllegalArgumentException("negative saltLen value: " +
144 saltLen);
145 }
146 if (trailerField < 0) {
147 throw new IllegalArgumentException("negative trailerField: " +
148 trailerField);
149 }
150 this.mdName = mdName;
151 this.mgfName = mgfName;
152 this.mgfSpec = mgfSpec;
153 this.saltLen = saltLen;
154 this.trailerField = trailerField;
155 }
156
157 /**
158 * Creates a new {@code PSSParameterSpec}
159 * using the specified salt length and other default values as
160 * defined in PKCS#1.
161 *
162 * @param saltLen the length of salt in bytes to be used in PKCS#1
163 * PSS encoding
164 * @exception IllegalArgumentException if {@code saltLen} is
165 * less than 0
166 */
167 public PSSParameterSpec(int saltLen) {
168 this("SHA-1", "MGF1", MGF1ParameterSpec.SHA1, saltLen, TRAILER_FIELD_BC);
169 }
170
171 /**
172 * Returns the message digest algorithm name.
173 *
174 * @return the message digest algorithm name
175 * @since 1.5
176 */
177 public String getDigestAlgorithm() {
178 return mdName;
179 }
180
181 /**
182 * Returns the mask generation function algorithm name.
183 *
184 * @return the mask generation function algorithm name
185 *
186 * @since 1.5
187 */
188 public String getMGFAlgorithm() {
189 return mgfName;
190 }
191
192 /**
193 * Returns the parameters for the mask generation function.
194 *
195 * @return the parameters for the mask generation function
196 * @since 1.5
197 */
198 public AlgorithmParameterSpec getMGFParameters() {
199 return mgfSpec;
200 }
201
202 /**
203 * Returns the salt length in bytes.
204 *
205 * @return the salt length
206 */
207 public int getSaltLength() {
208 return saltLen;
209 }
210
211 /**
212 * Returns the value for the trailer field.
213 *
214 * @return the value for the trailer field
215 * @since 1.5
216 */
217 public int getTrailerField() {
218 return trailerField;
219 }
220
221 @Override
222 public String toString() {
223 StringBuilder sb = new StringBuilder();
224 sb.append("MD: " + mdName + "\n")
225 .append("MGF: " + mgfSpec + "\n")
226 .append("SaltLength: " + saltLen + "\n")
227 .append("TrailerField: " + trailerField + "\n");
228 return sb.toString();
229 }
230 }