1 /* 2 * Copyright (c) 2013, 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; 27 28 import java.net.URI; 29 import java.util.*; 30 import static java.security.KeyStore.*; 31 32 /** 33 * Configuration data that specifies the keystores in a keystore domain. 34 * A keystore domain is a collection of keystores that are presented as a 35 * single logical keystore. The configuration data is used during 36 * {@code KeyStore} 37 * {@link KeyStore#load(KeyStore.LoadStoreParameter) load} and 38 * {@link KeyStore#store(KeyStore.LoadStoreParameter) store} operations. 39 * <p> 40 * The following syntax is supported for configuration data: 41 * <pre>{@code 42 * domain <domainName> [<property> ...] { 43 * keystore <keystoreName> [<property> ...] ; 44 * ... 45 * }; 46 * ... 47 * }</pre> 48 * where {@code domainName} and {@code keystoreName} are identifiers 49 * and {@code property} is a key/value pairing. The key and value are 50 * separated by an 'equals' symbol and the value is enclosed in double 51 * quotes. A property value may be either a printable string or a binary 52 * string of colon-separated pairs of hexadecimal digits. Multi-valued 53 * properties are represented as a comma-separated list of values, 54 * enclosed in square brackets. 55 * See {@link Arrays#toString(java.lang.Object[])}. 56 * <p> 57 * To ensure that keystore entries are uniquely identified, each 58 * entry's alias is prefixed by its {@code keystoreName} followed 59 * by the entry name separator and each {@code keystoreName} must be 60 * unique within its domain. Entry name prefixes are omitted when 61 * storing a keystore. 62 * <p> 63 * Properties are context-sensitive: properties that apply to 64 * all the keystores in a domain are located in the domain clause, 65 * and properties that apply only to a specific keystore are located 66 * in that keystore's clause. 67 * Unless otherwise specified, a property in a keystore clause overrides 68 * a property of the same name in the domain clause. All property names 69 * are case-insensitive. The following properties are supported: 70 * <dl> 71 * <dt> {@code keystoreType="<type>"} </dt> 72 * <dd> The keystore type. </dd> 73 * <dt> {@code keystoreURI="<url>"} </dt> 74 * <dd> The keystore location. </dd> 75 * <dt> {@code keystoreProviderName="<name>"} </dt> 76 * <dd> The name of the keystore's JCE provider. </dd> 77 * <dt> {@code keystorePasswordEnv="<environment-variable>"} </dt> 78 * <dd> The environment variable that stores a keystore password. 79 * Alternatively, passwords may be supplied to the constructor 80 * method in a {@code Map<String, ProtectionParameter>}. </dd> 81 * <dt> {@code entryNameSeparator="<separator>"} </dt> 82 * <dd> The separator between a keystore name prefix and an entry name. 83 * When specified, it applies to all the entries in a domain. 84 * Its default value is a space. </dd> 85 * </dl> 86 * <p> 87 * For example, configuration data for a simple keystore domain 88 * comprising three keystores is shown below: 89 * <pre> 90 * 91 * domain app1 { 92 * keystore app1-truststore 93 * keystoreURI="file:///app1/etc/truststore.jks"; 94 * 95 * keystore system-truststore 96 * keystoreURI="${java.home}/lib/security/cacerts"; 97 * 98 * keystore app1-keystore 99 * keystoreType="PKCS12" 100 * keystoreURI="file:///app1/etc/keystore.p12"; 101 * }; 102 * 103 * </pre> 104 * @since 1.8 105 */ 106 public final class DomainLoadStoreParameter implements LoadStoreParameter { 107 108 private final URI configuration; 109 private final Map<String,ProtectionParameter> protectionParams; 110 111 /** 112 * Constructs a DomainLoadStoreParameter for a keystore domain with 113 * the parameters used to protect keystore data. 114 * 115 * @param configuration identifier for the domain configuration data. 116 * The name of the target domain should be specified in the 117 * {@code java.net.URI} fragment component when it is necessary 118 * to distinguish between several domain configurations at the 119 * same location. 120 * 121 * @param protectionParams the map from keystore name to the parameter 122 * used to protect keystore data. 123 * A {@code java.util.Collections.EMPTY_MAP} should be used 124 * when protection parameters are not required or when they have 125 * been specified by properties in the domain configuration data. 126 * It is cloned to prevent subsequent modification. 127 * 128 * @exception NullPointerException if {@code configuration} or 129 * {@code protectionParams} is {@code null} 130 */ DomainLoadStoreParameter(URI configuration, Map<String,ProtectionParameter> protectionParams)131 public DomainLoadStoreParameter(URI configuration, 132 Map<String,ProtectionParameter> protectionParams) { 133 if (configuration == null || protectionParams == null) { 134 throw new NullPointerException("invalid null input"); 135 } 136 this.configuration = configuration; 137 this.protectionParams = 138 Collections.unmodifiableMap(new HashMap<>(protectionParams)); 139 } 140 141 /** 142 * Gets the identifier for the domain configuration data. 143 * 144 * @return the identifier for the configuration data 145 */ getConfiguration()146 public URI getConfiguration() { 147 return configuration; 148 } 149 150 /** 151 * Gets the keystore protection parameters for keystores in this 152 * domain. 153 * 154 * @return an unmodifiable map of keystore names to protection 155 * parameters 156 */ getProtectionParams()157 public Map<String,ProtectionParameter> getProtectionParams() { 158 return protectionParams; 159 } 160 161 /** 162 * Gets the keystore protection parameters for this domain. 163 * Keystore domains do not support a protection parameter. 164 * 165 * @return always returns {@code null} 166 */ 167 @Override getProtectionParameter()168 public KeyStore.ProtectionParameter getProtectionParameter() { 169 return null; 170 } 171 } 172