1 /* 2 * Copyright (c) 2001, 2020, 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 PSSParameterSpec()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 * @throws NullPointerException if {@code mdName}, or {@code mgfName} 132 * is null 133 * @throws IllegalArgumentException if {@code saltLen} or 134 * {@code trailerField} is less than 0 135 * @since 1.5 136 */ PSSParameterSpec(String mdName, String mgfName, AlgorithmParameterSpec mgfSpec, int saltLen, int trailerField)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 * @throws IllegalArgumentException if {@code saltLen} is 165 * less than 0 166 */ PSSParameterSpec(int saltLen)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 */ getDigestAlgorithm()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 */ getMGFAlgorithm()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 */ getMGFParameters()198 public AlgorithmParameterSpec getMGFParameters() { 199 return mgfSpec; 200 } 201 202 /** 203 * Returns the salt length in bytes. 204 * 205 * @return the salt length 206 */ getSaltLength()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 */ getTrailerField()217 public int getTrailerField() { 218 return trailerField; 219 } 220 221 @Override toString()222 public String toString() { 223 StringBuilder sb = new StringBuilder("PSSParameterSpec["); 224 sb.append("hashAlgorithm=" + mdName + ", ") 225 .append("maskGenAlgorithm=" + mgfSpec + ", ") 226 .append("saltLength=" + saltLen + ", ") 227 .append("trailerField=" + trailerField) 228 .append(']'); 229 return sb.toString(); 230 } 231 } 232