<?xml version="1.0" encoding="UTF-8"?>
<!--
  ~ Copyright (c) 2008-2013, Hazelcast, Inc. All Rights Reserved.
  ~
  ~ Licensed under the Apache License, Version 2.0 (the "License");
  ~ you may not use this file except in compliance with the License.
  ~ You may obtain a copy of the License at
  ~
  ~ http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~ Unless required by applicable law or agreed to in writing, software
  ~ distributed under the License is distributed on an "AS IS" BASIS,
  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  ~ See the License for the specific language governing permissions and
  ~ limitations under the License.
  -->

<sect1 xml:id="ClientSecurity" version="5.0"
       xmlns="http://docbook.org/ns/docbook"
       xmlns:xi="http://www.w3.org/2001/XInclude"
       xmlns:xlink="http://www.w3.org/1999/xlink"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd
       http://www.w3.org/1999/xlink http://www.w3.org/1999/xlink.xsd">
    <title>Native Client Security</title>
    <para>Hazelcast's Client security includes both authentication and authorization.</para>

    <sect2>
        <title>Authentication</title>
        <para>Authentication mechanism just works the same as cluster member authentication. Implementation of client
            authentication requires a
            <literal>Credentials</literal>
            and one or more
            <literal>LoginModule</literal>(s). Client side does not have/need a factory object to
            create
            <literal>Credentials</literal>
            objects like<literal>ICredentialsFactory</literal>.
            <literal>Credentials</literal>
            must be created at client side and sent to connected node
            during connection process.
            <programlisting language="xml"><![CDATA[
<security enabled="true">
    <client-login-modules>
        <login-module class-name="com.hazelcast.examples.MyRequiredClientLoginModule" usage="required">
            <properties>
                <property name="property3">value3</property>
            </properties>
        </login-module>
        <login-module class-name="com.hazelcast.examples.MySufficientClientLoginModule" usage="sufficient">
            <properties>
                <property name="property4">value4</property>
            </properties>
        </login-module>
        <login-module class-name="com.hazelcast.examples.MyOptionalClientLoginModule" usage="optional">
            <properties>
                <property name="property5">value5</property>
            </properties>
        </login-module>
    </client-login-modules>
    ...
</security>
]]></programlisting>
        </para>
        <para>You can define as many as<literal>LoginModule</literal>s you wanted in
            configuration. Those are executed in given order. Usage attribute has 4 values; 'required',
            'requisite', 'sufficient' and 'optional' as defined in
            <code>javax.security.auth.login.AppConfigurationEntry.LoginModuleControlFlag</code>.
        </para>

        <para>
            <programlisting language="java"><![CDATA[
final Credentials credentials = new UsernamePasswordCredentials("dev", "dev-pass");
HazelcastInstance client = HazelcastClient.newHazelcastClient(credentials, "localhost");
]]></programlisting>
        </para>
    </sect2>

    <sect2>
        <title>Authorization</title>
        <para>Hazelcast client authorization is configured by a client permission policy. Hazelcast has a default
            permission policy
            implementation that uses permission configurations defined in Hazelcast security configuration. Default
            policy permission checks are done
            against instance types (map, queue...), instance names (map, queue etc. name), instance actions (put, get,
            remove, add...),
            client endpoint addresses and client principal defined by
            <literal>Credentials</literal>
            object.
            <emphasis role="italic">Instance and principal names and endpoint addresses
                can be defined as wildcards(*). Take a look at
                <link xlink:href="#WildcardConfiguration">Wildcard Name Configuration</link>
                and
                <link xlink:href="#ConfigSpecifyInterfaces">Newtwork Configuration</link>
                pages.
            </emphasis>
        </para>

        <para>
            <programlisting language="xml"><![CDATA[
<security enabled="true">
    <client-permissions>
        <!-- Principal 'admin' from endpoint '127.0.0.1' has all permissions. -->
        <all-permissions principal="admin">
            <endpoints>
                <endpoint>127.0.0.1</endpoint>
            </endpoints>
        </all-permissions>
        
        <!-- Principals named 'dev' from all endpoints have 'create', 'destroy', 
            'put', 'get' permissions for map named 'default'. -->
        <map-permission name="default" principal="dev">
            <actions>
                <action>create</action>
                <action>destroy</action>
                <action>put</action>
                <action>get</action>
            </actions>
        </map-permission>
        
        <!-- All principals from endpoints '127.0.0.1' or matching to '10.10.*.*' 
            have 'put', 'get', 'remove' permissions for map 
            whose name matches to 'com.foo.entity.*'. -->
        <map-permission name="com.foo.entity.*">
            <endpoints>
                <endpoint>10.10.*.*</endpoint>
                <endpoint>127.0.0.1</endpoint>
            </endpoints>
            <actions>
                <action>put</action>
                <action>get</action>
                <action>remove</action>
            </actions>
        </map-permission>
        
        <!-- Principals named 'dev' from endpoints matching to either 
            '192.168.1.1-100' or '192.168.2.*' 
            have 'create', 'offer', 'poll' permissions for all queues. -->
        <queue-permission name="*" principal="dev">
            <endpoints>
                <endpoint>192.168.1.1-100</endpoint>
                <endpoint>192.168.2.*</endpoint>
            </endpoints>
            <actions>
                <action>create</action>
                <action>offer</action>
                <action>poll</action>
            </actions>
        </queue-permission>
        
        <!-- All principals from all endpoints have transaction permission.-->
        <transaction-permission />
    </client-permissions>
</security>
]]></programlisting>
        </para>

        <para>Users also can define their own policy by implementing<literal>
            com.hazelcast.security.IPermissionPolicy</literal>.
            <programlisting language="java"><![CDATA[
package com.hazelcast.security;
/**
 * IPermissionPolicy is used to determine any Subject's 
 * permissions to perform a security sensitive Hazelcast operation.
 *
 */
public interface IPermissionPolicy {
    void configure(SecurityConfig securityConfig, Properties properties);
    
    PermissionCollection getPermissions(Subject subject, Class<? extends Permission> type);
    
    void destroy();
}]]></programlisting>
        </para>
        <para>Permission policy implementations can access
            <code>client-permissions</code>
            in
            configuration by using
            <code>SecurityConfig.getClientPermissionConfigs()</code>
            during
            <code>configure(SecurityConfig securityConfig, Properties properties)</code>
            method
            is called by Hazelcast.
            <code>IPermissionPolicy.getPermissions(Subject subject,
                Class&lt;? extends Permission&gt; type)
            </code>
            method is used to determine a client
            request has been granted permission to do a security-sensitive operation. Permission
            policy should return a
            <literal>PermissionCollection</literal>
            containing permissions of
            given type for given<literal>Subject</literal>. Hazelcast access controller will call
            <code>PermissionCollection.implies(Permission)</code>
            on returning
            <literal>PermissionCollection</literal>
            and will decide if current
            <literal>Subject</literal>
            has permitted to access to requested resources or
            not.
        </para>
    </sect2>

    <sect2>
        <title>Permissions</title>
        <para>
            <orderedlist>
                <listitem>
                    <para>
                        <emphasis role="bold">All Permission</emphasis>
                    </para>
                    <para>
                        <programlisting language="xml"><![CDATA[
<all-permissions principal="principal">
    <endpoints>
        ...
    </endpoints>
</all-permissions>
]]></programlisting>
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <emphasis role="bold">Map Permission</emphasis>
                    </para>
                    <para>
                        <programlisting language="xml"><![CDATA[
<map-permission name="name" principal="principal">
    <endpoints>
        ...
    </endpoints>
    <actions>
        ...
    </actions>
</map-permission>
]]></programlisting>
                    </para>
                    <para>
                        <emphasis role="bold">Actions:</emphasis>
                        <emphasis role="italic">all, create, destroy,
                            put, get, remove, listen, lock, stats
                        </emphasis>
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis role="bold">Queue Permission</emphasis>
                    </para>
                    <para>
                        <programlisting language="xml"><![CDATA[
<queue-permission name="name" principal="principal">
    <endpoints>
        ...
    </endpoints>
    <actions>
        ...
    </actions>
</queue-permission>
]]></programlisting>
                    </para>
                    <para>
                        <emphasis role="bold">Actions:</emphasis>
                        <emphasis role="italic">all, create, destroy,
                            offer, poll, get, remove, listen, stats
                        </emphasis>
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis role="bold">Multimap Permission</emphasis>
                    </para>
                    <para>
                        <programlisting language="xml"><![CDATA[
<multimap-permission name="name" principal="principal">
    <endpoints>
        ...
    </endpoints>
    <actions>
        ...
    </actions>
</multimap-permission>
]]></programlisting>
                    </para>
                    <para>
                        <emphasis role="bold">Actions:</emphasis>
                        <emphasis role="italic">all, create, destroy,
                            put, get, remove, listen, lock, stats
                        </emphasis>
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis role="bold">Topic Permission</emphasis>
                    </para>
                    <para>
                        <programlisting language="xml"><![CDATA[
<topic-permission name="name" principal="principal">
    <endpoints>
        ...
    </endpoints>
    <actions>
        ...
    </actions>
</topic-permission>
]]></programlisting>
                    </para>
                    <para>
                        <emphasis role="bold">Actions:</emphasis>
                        <emphasis role="italic">create, destroy,
                            publish, listen, stats
                        </emphasis>
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis role="bold">List Permission</emphasis>
                    </para>
                    <para>
                        <programlisting language="xml"><![CDATA[
<list-permission name="name" principal="principal">
    <endpoints>
        ...
    </endpoints>
    <actions>
        ...
    </actions>
</list-permission>
]]></programlisting>
                    </para>
                    <para>
                        <emphasis role="bold">Actions:</emphasis>
                        <emphasis role="italic">all, create, destroy,
                            add, set, get, remove, listen
                        </emphasis>
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis role="bold">Set Permission</emphasis>
                    </para>
                    <para>
                        <programlisting language="xml"><![CDATA[
<set-permission name="name" principal="principal">
    <endpoints>
        ...
    </endpoints>
    <actions>
        ...
    </actions>
</set-permission>
]]></programlisting>
                    </para>
                    <para>
                        <emphasis role="bold">Actions:</emphasis>
                        <emphasis role="italic">all, create, destroy,
                            add, get, remove, listen
                        </emphasis>
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis role="bold">Lock Permission</emphasis>
                    </para>
                    <para>
                        <programlisting language="xml"><![CDATA[
<lock-permission name="name" principal="principal">
    <endpoints>
        ...
    </endpoints>
    <actions>
        ...
    </actions>
</lock-permission>
]]></programlisting>
                    </para>
                    <para>
                        <emphasis role="bold">Actions:</emphasis>
                        <emphasis role="italic">all, create, destroy,
                            lock, stats
                        </emphasis>
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis role="bold">AtomicNumber Permission</emphasis>
                    </para>
                    <para>
                        <programlisting language="xml"><![CDATA[
<atomic-number-permission name="name" principal="principal">
    <endpoints>
        ...
    </endpoints>
    <actions>
        ...
    </actions>
</atomic-number-permission>
]]></programlisting>
                    </para>
                    <para>
                        <emphasis role="bold">Actions:</emphasis>
                        <emphasis role="italic">all, create, destroy,
                            increment, decrement, get, set, add, stats
                        </emphasis>
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis role="bold">CountDownLatch Permission</emphasis>
                    </para>
                    <para>
                        <programlisting language="xml"><![CDATA[
<countdown-latch-permission name="name" principal="principal">
    <endpoints>
        ...
    </endpoints>
    <actions>
        ...
    </actions>
</countdown-latch-permission>
]]></programlisting>
                    </para>
                    <para>
                        <emphasis role="bold">Actions:</emphasis>
                        <emphasis role="italic">all, create, destroy,
                            countdown, set, stats
                        </emphasis>
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis role="bold">Semaphore Permission</emphasis>
                    </para>
                    <para>
                        <programlisting language="xml"><![CDATA[
<semaphore-permission name="name" principal="principal">
    <endpoints>
        ...
    </endpoints>
    <actions>
        ...
    </actions>
</semaphore-permission>
]]></programlisting>
                    </para>
                    <para>
                        <emphasis role="bold">Actions:</emphasis>
                        <emphasis role="italic">all, create, destroy,
                            acquire, release, drain, stats
                        </emphasis>
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis role="bold">Executor Service Permission</emphasis>
                    </para>
                    <para>
                        <programlisting language="xml"><![CDATA[
<executor-service-permission name="name" principal="principal">
    <endpoints>
        ...
    </endpoints>
    <actions>
        ...
    </actions>
</executor-service-permission>
]]></programlisting>
                    </para>
                    <para>
                        <emphasis role="bold">Actions:</emphasis>
                        <emphasis role="italic">all, create, destroy,
                            execute
                        </emphasis>
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis role="bold">Listener Permission</emphasis>
                    </para>
                    <para>
                        <programlisting language="xml"><![CDATA[
<listener-permission name="name" principal="principal">
    <endpoints>
        ...
    </endpoints>
</listener-permission>
]]></programlisting>
                    </para>
                    <para>
                        <emphasis role="bold">Names:</emphasis>
                        <emphasis role="italic">all, instance,
                            member
                        </emphasis>
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis role="bold">Transaction Permission</emphasis>
                    </para>
                    <para>
                        <programlisting language="xml"><![CDATA[
<transaction-permission principal="principal">
    <endpoints>
        ...
    </endpoints>
</transaction-permission>
]]></programlisting>
                    </para>
                </listitem>
            </orderedlist>
        </para>
    </sect2>
</sect1>