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