Apache Zeta Components Manual :: File Source for token_filter.php

Source for file token_filter.php

Documentation is available at token_filter.php

  1. <?php
  2. /**
  3.  * File containing the ezcAuthenticationTokenFilter class.
  4.  *
  5.  * Licensed to the Apache Software Foundation (ASF) under one
  6.  * or more contributor license agreements.  See the NOTICE file
  7.  * distributed with this work for additional information
  8.  * regarding copyright ownership.  The ASF licenses this file
  9.  * to you under the Apache License, Version 2.0 (the
  10.  * "License"); you may not use this file except in compliance
  11.  * with the License.  You may obtain a copy of the License at
  12.  * 
  13.  *   http://www.apache.org/licenses/LICENSE-2.0
  14.  * 
  15.  * Unless required by applicable law or agreed to in writing,
  16.  * software distributed under the License is distributed on an
  17.  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  18.  * KIND, either express or implied.  See the License for the
  19.  * specific language governing permissions and limitations
  20.  * under the License.
  21.  *
  22.  * @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0
  23.  * @filesource
  24.  * @package Authentication
  25.  * @version //autogen//
  26.  */
  27.  
  28. /**
  29.  * Filter to authenticate against a server generated token.
  30.  *
  31.  * Some uses for this filter:
  32.  *  - CAPTCHA tests
  33.  *  - security token devices (as used by banks)
  34.  *
  35.  * The following example shows how to create a CAPTCHA test. The example is
  36.  * divided into 2 parts: the initial request (where the user sees the CAPTCHA
  37.  * image and enters the characters he sees in a form) and the follow-up
  38.  * request (after the user submits the form).
  39.  * - on the initial request:
  40.  * <code>
  41.  * // generate a token and save it in the session or in a file/database
  42.  * $pattern = "1234567890abcdefghijklmnopqrstuvwxyz";
  43.  * $token  = "";
  44.  * for( $i = 1; $i <= 6 ; $i++ )
  45.  * {
  46.  *     $token .= $pattern{rand( 0, 36 )};
  47.  * }
  48.  * $encryptedToken = sha1( $token );
  49.  *
  50.  * // save the $encryptedToken in the session
  51.  * session_start();
  52.  * $_SESSION['encryptedToken'] = $encryptedToken;
  53.  *
  54.  * // also generate a distorted image which contains the symbols from $token and use it
  55.  * </code>
  56.  *
  57.  * - on the follow-up request:
  58.  * <code>
  59.  * // load the $encryptedToken as it was generated on a previous request
  60.  * session_start();
  61.  * $encryptedToken = isset( $_SESSION['encryptedToken'] ) ? $_SESSION['encryptedToken'] : null;
  62.  *
  63.  * // also load the value entered by the user in response to the CAPTCHA image
  64.  * $captcha = isset( $_POST['captcha'] ) ? $_POST['captcha'] : null;
  65.  *
  66.  * $credentials = new ezcAuthenticationIdCredentials( $captcha );
  67.  * $authentication = new ezcAuthentication( $credentials );
  68.  * $authentication->addFilter( new ezcAuthenticationTokenFilter( $encryptedToken, 'sha1' ) );
  69.  * if ( !$authentication->run() )
  70.  * {
  71.  *     // CAPTCHA was incorrect, so inform the user to try again, eventually
  72.  *     // by generating another token and CAPTCHA image
  73.  * }
  74.  * else
  75.  * {
  76.  *     // CAPTCHA was correct, so let the user send his spam or whatever
  77.  * }
  78.  * </code>
  79.  *
  80.  * @property string $token 
  81.  *            The token to check against.
  82.  * @property callback $function 
  83.  *            The encryption function to use on the user credentials in order to
  84.  *            compare it with the stored token.
  85.  *
  86.  * @package Authentication
  87.  * @version //autogen//
  88.  * @mainclass
  89.  */
  90. {
  91.     /**
  92.      * Token is not the same as the provided one.
  93.      */
  94.     const STATUS_TOKEN_INCORRECT = 1;
  95.  
  96.     /**
  97.      * Holds the properties of this class.
  98.      *
  99.      * @var array(string=>mixed) 
  100.      */
  101.     private $properties array();
  102.  
  103.     /**
  104.      * Creates a new object of this class.
  105.      *
  106.      * @param string $token A string value generated by the server
  107.      * @param callback $function The encryption function to use when comparing tokens
  108.      * @param ezcAuthenticationTokenOptions $options Options for this class
  109.      */
  110.     public function __construct$token$functionezcAuthenticationTokenOptions $options null )
  111.     {
  112.         $this->token $token;
  113.         $this->function $function;
  114.         $this->options = $options === null new ezcAuthenticationTokenOptions($options;
  115.     }
  116.  
  117.     /**
  118.      * Sets the property $name to $value.
  119.      *
  120.      * @throws ezcBasePropertyNotFoundException
  121.      *          if the property $name does not exist
  122.      * @throws ezcBaseValueException
  123.      *          if $value is not correct for the property $name
  124.      * @param string $name The name of the property to set
  125.      * @param mixed $value The new value of the property
  126.      * @ignore
  127.      */
  128.     public function __set$name$value )
  129.     {
  130.         switch $name )
  131.         {
  132.             case 'token':
  133.                 if is_string$value || is_numeric$value ) )
  134.                 {
  135.                     $this->properties[$name$value;
  136.                 }
  137.                 else
  138.                 {
  139.                     throw new ezcBaseValueException$name$value'string || int' );
  140.                 }
  141.                 break;
  142.  
  143.             case 'function':
  144.                 if is_callable$value ) )
  145.                 {
  146.                     $this->properties[$name$value;
  147.                 }
  148.                 else
  149.                 {
  150.                     throw new ezcBaseValueException$name$value'callback' );
  151.                 }
  152.                 break;
  153.  
  154.             default:
  155.                 throw new ezcBasePropertyNotFoundException$name );
  156.         }
  157.     }
  158.  
  159.     /**
  160.      * Returns the value of the property $name.
  161.      *
  162.      * @throws ezcBasePropertyNotFoundException
  163.      *          if the property $name does not exist
  164.      * @param string $name The name of the property for which to return the value
  165.      * @return mixed 
  166.      * @ignore
  167.      */
  168.     public function __get$name )
  169.     {
  170.         switch $name )
  171.         {
  172.             case 'token':
  173.             case 'function':
  174.                 return $this->properties[$name];
  175.  
  176.             default:
  177.                 throw new ezcBasePropertyNotFoundException$name );
  178.         }
  179.     }
  180.  
  181.     /**
  182.      * Returns true if the property $name is set, otherwise false.
  183.      *
  184.      * @param string $name The name of the property to test if it is set
  185.      * @return bool 
  186.      * @ignore
  187.      */
  188.     public function __isset$name )
  189.     {
  190.         switch $name )
  191.         {
  192.             case 'token':
  193.             case 'function':
  194.                 return isset$this->properties[$name);
  195.  
  196.             default:
  197.                 return false;
  198.         }
  199.     }
  200.  
  201.     /**
  202.      * Runs the filter and returns a status code when finished.
  203.      *
  204.      * @param ezcAuthenticationCredentials $credentials Authentication credentials
  205.      * @return int 
  206.      */
  207.     public function run$credentials )
  208.     {
  209.         $password call_user_func$this->function$credentials->id );
  210.         if $this->token === $password )
  211.         {
  212.             return self::STATUS_OK;
  213.         }
  214.         return self::STATUS_TOKEN_INCORRECT;
  215.     }
  216. }
  217. ?>
Documentation generated by phpDocumentor 1.4.3