1 /*
   2  * Copyright (c) 2007, 2011, 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.nio.file.attribute;
  27 
  28 import java.nio.file.*;
  29 import java.util.List;
  30 import java.io.IOException;
  31 
  32 /**
  33  * A file attribute view that supports reading or updating a file's Access
  34  * Control Lists (ACL) or file owner attributes.
  35  *
  36  * <p> ACLs are used to specify access rights to file system objects. An ACL is
  37  * an ordered list of {@link AclEntry access-control-entries}, each specifying a
  38  * {@link UserPrincipal} and the level of access for that user principal. This
  39  * file attribute view defines the {@link #getAcl() getAcl}, and {@link
  40  * #setAcl(List) setAcl} methods to read and write ACLs based on the ACL
  41  * model specified in <a href="http://www.ietf.org/rfc/rfc3530.txt"><i>RFC&nbsp;3530:
  42  * Network File System (NFS) version 4 Protocol</i></a>. This file attribute view
  43  * is intended for file system implementations that support the NFSv4 ACL model
  44  * or have a <em>well-defined</em> mapping between the NFSv4 ACL model and the ACL
  45  * model used by the file system. The details of such mapping are implementation
  46  * dependent and are therefore unspecified.
  47  *
  48  * <p> This class also extends {@code FileOwnerAttributeView} so as to define
  49  * methods to get and set the file owner.
  50  *
  51  * <p> When a file system provides access to a set of {@link FileStore
  52  * file-systems} that are not homogeneous then only some of the file systems may
  53  * support ACLs. The {@link FileStore#supportsFileAttributeView
  54  * supportsFileAttributeView} method can be used to test if a file system
  55  * supports ACLs.
  56  *
  57  * <a name="interop"><h4>Interoperability</h4></a>
  58  *
  59  * RFC&nbsp;3530 allows for special user identities to be used on platforms that
  60  * support the POSIX defined access permissions. The special user identities
  61  * are "{@code OWNER@}", "{@code GROUP@}", and "{@code EVERYONE@}". When both
  62  * the {@code AclFileAttributeView} and the {@link PosixFileAttributeView}
  63  * are supported then these special user identities may be included in ACL {@link
  64  * AclEntry entries} that are read or written. The file system's {@link
  65  * UserPrincipalLookupService} may be used to obtain a {@link UserPrincipal}
  66  * to represent these special identities by invoking the {@link
  67  * UserPrincipalLookupService#lookupPrincipalByName lookupPrincipalByName}
  68  * method. </p>
  69  *
  70  * <p> <b>Usage Example:</b>
  71  * Suppose we wish to add an entry to an existing ACL to grant "joe" access:
  72  * <pre>
  73  *     // lookup "joe"
  74  *     UserPrincipal joe = file.getFileSystem().getUserPrincipalLookupService()
  75  *         .lookupPrincipalByName("joe");
  76  *
  77  *     // get view
  78  *     AclFileAttributeView view = Files.getFileAttributeView(file, AclFileAttributeView.class);
  79  *
  80  *     // create ACE to give "joe" read access
  81  *     AclEntry entry = AclEntry.newBuilder()
  82  *         .setType(AclEntryType.ALLOW)
  83  *         .setPrincipal(joe)
  84  *         .setPermissions(AclEntryPermission.READ_DATA, AclEntryPermission.READ_ATTRIBUTES)
  85  *         .build();
  86  *
  87  *     // read ACL, insert ACE, re-write ACL
  88  *     List&lt;AclEntry&gt; acl = view.getAcl();
  89  *     acl.add(0, entry);   // insert before any DENY entries
  90  *     view.setAcl(acl);
  91  * </pre>
  92  *
  93  * <h4> Dynamic Access </h4>
  94  * <p> Where dynamic access to file attributes is required, the attributes
  95  * supported by this attribute view are as follows:
  96  * <blockquote>
  97  * <table border="1" cellpadding="8">
  98  *   <tr>
  99  *     <th> Name </th>
 100  *     <th> Type </th>
 101  *   </tr>
 102  *   <tr>
 103  *     <td> "acl" </td>
 104  *     <td> {@link List}&lt;{@link AclEntry}&gt; </td>
 105  *   </tr>
 106  *   <tr>
 107  *     <td> "owner" </td>
 108  *     <td> {@link UserPrincipal} </td>
 109  *   </tr>
 110  * </table>
 111  * </blockquote>
 112  *
 113  * <p> The {@link Files#getAttribute getAttribute} method may be used to read
 114  * the ACL or owner attributes as if by invoking the {@link #getAcl getAcl} or
 115  * {@link #getOwner getOwner} methods.
 116  *
 117  * <p> The {@link Files#setAttribute setAttribute} method may be used to
 118  * update the ACL or owner attributes as if by invoking the {@link #setAcl setAcl}
 119  * or {@link #setOwner setOwner} methods.
 120  *
 121  * <h4> Setting the ACL when creating a file </h4>
 122  *
 123  * <p> Implementations supporting this attribute view may also support setting
 124  * the initial ACL when creating a file or directory. The initial ACL
 125  * may be provided to methods such as {@link Files#createFile createFile} or {@link
 126  * Files#createDirectory createDirectory} as an {@link FileAttribute} with {@link
 127  * FileAttribute#name name} {@code "acl:acl"} and a {@link FileAttribute#value
 128  * value} that is the list of {@code AclEntry} objects.
 129  *
 130  * <p> Where an implementation supports an ACL model that differs from the NFSv4
 131  * defined ACL model then setting the initial ACL when creating the file must
 132  * translate the ACL to the model supported by the file system. Methods that
 133  * create a file should reject (by throwing {@link IOException IOException})
 134  * any attempt to create a file that would be less secure as a result of the
 135  * translation.
 136  *
 137  * @since 1.7
 138  */
 139 
 140 public interface AclFileAttributeView
 141     extends FileOwnerAttributeView
 142 {
 143     /**
 144      * Returns the name of the attribute view. Attribute views of this type
 145      * have the name {@code "acl"}.
 146      */
 147     @Override
 148     String name();
 149 
 150     /**
 151      * Reads the access control list.
 152      *
 153      * <p> When the file system uses an ACL model that differs from the NFSv4
 154      * defined ACL model, then this method returns an ACL that is the translation
 155      * of the ACL to the NFSv4 ACL model.
 156      *
 157      * <p> The returned list is modifiable so as to facilitate changes to the
 158      * existing ACL. The {@link #setAcl setAcl} method is used to update
 159      * the file's ACL attribute.
 160      *
 161      * @return  an ordered list of {@link AclEntry entries} representing the
 162      *          ACL
 163      *
 164      * @throws  IOException
 165      *          if an I/O error occurs
 166      * @throws  SecurityException
 167      *          In the case of the default provider, a security manager is
 168      *          installed, and it denies {@link RuntimePermission}<tt>("accessUserInformation")</tt>
 169      *          or its {@link SecurityManager#checkRead(String) checkRead} method
 170      *          denies read access to the file.
 171      */
 172     List<AclEntry> getAcl() throws IOException;
 173 
 174     /**
 175      * Updates (replace) the access control list.
 176      *
 177      * <p> Where the file system supports Access Control Lists, and it uses an
 178      * ACL model that differs from the NFSv4 defined ACL model, then this method
 179      * must translate the ACL to the model supported by the file system. This
 180      * method should reject (by throwing {@link IOException IOException}) any
 181      * attempt to write an ACL that would appear to make the file more secure
 182      * than would be the case if the ACL were updated. Where an implementation
 183      * does not support a mapping of {@link AclEntryType#AUDIT} or {@link
 184      * AclEntryType#ALARM} entries, then this method ignores these entries when
 185      * writing the ACL.
 186      *
 187      * <p> If an ACL entry contains a {@link AclEntry#principal user-principal}
 188      * that is not associated with the same provider as this attribute view then
 189      * {@link ProviderMismatchException} is thrown. Additional validation, if
 190      * any, is implementation dependent.
 191      *
 192      * <p> If the file system supports other security related file attributes
 193      * (such as a file {@link PosixFileAttributes#permissions
 194      * access-permissions} for example), the updating the access control list
 195      * may also cause these security related attributes to be updated.
 196      *
 197      * @param   acl
 198      *          the new access control list
 199      *
 200      * @throws  IOException
 201      *          if an I/O error occurs or the ACL is invalid
 202      * @throws  SecurityException
 203      *          In the case of the default provider, a security manager is
 204      *          installed, it denies {@link RuntimePermission}<tt>("accessUserInformation")</tt>
 205      *          or its {@link SecurityManager#checkWrite(String) checkWrite}
 206      *          method denies write access to the file.
 207      */
 208     void setAcl(List<AclEntry> acl) throws IOException;
 209 }