1 /*
2 * Copyright (c) 2001, 2018, 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 import java.security.spec.MGF1ParameterSpec;
30
31 /**
32 * This class specifies a parameter spec for RSASSA-PSS signature scheme,
33 * as defined in the
34 * <a href="https://tools.ietf.org/rfc/rfc8017.txt">PKCS#1 v2.2</a> standard.
35 *
36 * <p>Its ASN.1 definition in PKCS#1 standard is described below:
37 * <pre>
38 * RSASSA-PSS-params ::= SEQUENCE {
39 * hashAlgorithm [0] HashAlgorithm DEFAULT sha1,
40 * maskGenAlgorithm [1] MaskGenAlgorithm DEFAULT mgf1SHA1,
41 * saltLength [2] INTEGER DEFAULT 20,
42 * trailerField [3] TrailerField DEFAULT trailerFieldBC(1)
43 * }
44 * </pre>
45 * where
46 * <pre>
47 * HashAlgorithm ::= AlgorithmIdentifier {
48 * {OAEP-PSSDigestAlgorithms}
49 * }
50 * MaskGenAlgorithm ::= AlgorithmIdentifier { {PKCS1MGFAlgorithms} }
51 * TrailerField ::= INTEGER { trailerFieldBC(1) }
52 *
53 * OAEP-PSSDigestAlgorithms ALGORITHM-IDENTIFIER ::= {
54 * { OID id-sha1 PARAMETERS NULL }|
55 * { OID id-sha224 PARAMETERS NULL }|
56 * { OID id-sha256 PARAMETERS NULL }|
57 * { OID id-sha384 PARAMETERS NULL }|
58 * { OID id-sha512 PARAMETERS NULL }|
59 * { OID id-sha512-224 PARAMETERS NULL }|
60 * { OID id-sha512-256 PARAMETERS NULL },
61 * ... -- Allows for future expansion --
62 * }
63 * PKCS1MGFAlgorithms ALGORITHM-IDENTIFIER ::= {
64 * { OID id-mgf1 PARAMETERS HashAlgorithm },
65 * ... -- Allows for future expansion --
66 * }
67 * </pre>
68 * <p>Note: the PSSParameterSpec.DEFAULT uses the following:
69 * message digest -- "SHA-1"
70 * mask generation function (mgf) -- "MGF1"
71 * parameters for mgf -- MGF1ParameterSpec.SHA1
72 * SaltLength -- 20
73 * TrailerField -- 1
74 *
75 * @see MGF1ParameterSpec
76 * @see AlgorithmParameterSpec
77 * @see java.security.Signature
78 *
79 * @author Valerie Peng
80 *
81 *
82 * @since 1.4
83 */
84
85 public class PSSParameterSpec implements AlgorithmParameterSpec {
86
87 private final String mdName;
88
89 private final String mgfName;
90
91 private final AlgorithmParameterSpec mgfSpec;
92
93 private final int saltLen;
94
95 private final int trailerField;
96
97 /**
98 * The {@code TrailerFieldBC} constant as defined in PKCS#1
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 * @since 1.5
106 */
107 public static final PSSParameterSpec DEFAULT = new PSSParameterSpec
108 ("SHA-1", "MGF1", MGF1ParameterSpec.SHA1, 20, TRAILER_FIELD_BC);
109
110
111 // disallowed
112 private PSSParameterSpec() {
113 throw new RuntimeException("default constructor not allowed");
114 }
115
116
117 /**
118 * Creates a new {@code PSSParameterSpec} as defined in
119 * the PKCS #1 standard using the specified message digest,
120 * mask generation function, parameters for mask generation
121 * function, salt length, and trailer field values.
122 *
123 * @param mdName the algorithm name of the hash function
124 * @param mgfName the algorithm name of the mask generation function
125 * @param mgfSpec the parameters for the mask generation function
126 * If null is specified, null will be returned by
127 * getMGFParameters()
128 * @param saltLen the length of salt
129 * @param trailerField the value of the trailer field
130 * @exception NullPointerException if {@code mdName}, or {@code mgfName}
131 * is null
132 * @exception IllegalArgumentException if {@code saltLen} or
133 * {@code trailerField} is less than 0
134 * @since 1.5
135 */
136 public PSSParameterSpec(String mdName, String mgfName,
137 AlgorithmParameterSpec mgfSpec, int saltLen, int trailerField) {
138 Objects.requireNonNull(mdName, "digest algorithm is null");
139 Objects.requireNonNull(mgfName,
140 "mask generation function algorithm is null");
141 if (saltLen < 0) {
142 throw new IllegalArgumentException("negative saltLen value: " +
143 saltLen);
144 }
145 if (trailerField < 0) {
146 throw new IllegalArgumentException("negative trailerField: " +
147 trailerField);
148 }
149 this.mdName = mdName;
150 this.mgfName = mgfName;
151 this.mgfSpec = mgfSpec;
152 this.saltLen = saltLen;
153 this.trailerField = trailerField;
154 }
155
156 /**
157 * Creates a new {@code PSSParameterSpec}
158 * using the specified salt length and other default values as
159 * defined in PKCS#1.
160 *
161 * @param saltLen the length of salt in bytes to be used in PKCS#1
162 * PSS encoding
163 * @exception IllegalArgumentException if {@code saltLen} is
164 * less than 0
165 */
166 public PSSParameterSpec(int saltLen) {
167 this("SHA-1", "MGF1", MGF1ParameterSpec.SHA1, saltLen, TRAILER_FIELD_BC);
168 }
169
170 /**
171 * Returns the message digest algorithm name.
172 *
173 * @return the message digest algorithm name
174 * @since 1.5
175 */
176 public String getDigestAlgorithm() {
177 return mdName;
178 }
179
180 /**
181 * Returns the mask generation function algorithm name.
182 *
183 * @return the mask generation function algorithm name
184 *
185 * @since 1.5
186 */
187 public String getMGFAlgorithm() {
188 return mgfName;
189 }
190
191 /**
192 * Returns the parameters for the mask generation function.
193 *
194 * @return the parameters for the mask generation function
195 * @since 1.5
196 */
197 public AlgorithmParameterSpec getMGFParameters() {
198 return mgfSpec;
199 }
200
201 /**
202 * Returns the salt length in bytes.
203 *
204 * @return the salt length
205 */
206 public int getSaltLength() {
207 return saltLen;
208 }
209
210 /**
211 * Returns the value for the trailer field.
212 *
213 * @return the value for the trailer field
214 * @since 1.5
215 */
216 public int getTrailerField() {
217 return trailerField;
218 }
219 }