<?php

  /** SECURE STRING **/
  /** VERSION 1 BETA 11-Dec-2007 **/
  /** nickg@modp.com **/

  /** WAITING FOR CODE.GOOGLE.COM TO UP MY RESOURCE LIMITS **
  /** AND THEN IT WILL BE IN SVN **/

  /** LOOKING FOR
    *   HELP WITH PEAR-ificiation
    *   HELP WITH PHP_DOC
    *   HELP WITH PHP_UNIT-ification
    *   HELP WITH examples
    *   Translations to other languages
    **/


/**
The MIT License

Copyright (c) 2007 Nick Galbreath, nickg@modp.com

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
**/

/**
 * Web/URL safe base64 encoder
 *
 * @param string $str input string
 * @return encoded string
 */
function securestring_b64_encode($str) 
{
  return str_replace(array('+','/','='),
                     array('-','_','.'),
		     base64_encode($str));
}

/**
 * Web/URL safe base64 decoder
 *
 * @param string $str input encoded string
 * @return decoded string
 */
function securestring_b64_urldecode($str)
{
  return base64_decode(str_replace(array('-','_','.'),
				   array('+','/','='), $str));
}

/**
 * Given an input string, add an HMAC
 *
 * @param string $str         input data
 * @param string $key_array   array of key_id => key
 * @param string $kid_id      key_id to use
 * @param int    $now, default 0 for current time
 * @param string $alg, default "sha1"
 *
 * @return the new string if ok, throw Exception if bad input
 */
function securestring_create($str, $key_array, $kid, $now=0, $alg="sha1")
{
  if ($now <= 0) {
    $now = time();
  }

  if (strlen($str) == 0 || strlen($kid) == 0 || strlen($key_array[$kid]) == 0){
    // this should truly never happen
    throw new Exception("Invalid data or key data");
  }

  // TBD -- add VERSION metadata
  // TBD -- add algorithm metadata

  // note: we are also hashing _all_ of the meta data
  $payload = $str . "&_created=" . $now . "&_kid=" . $kid . "&_mac=";

  // make the HMAC
  $hmac = hash_hmac($alg, $payload, $key_array[$kid], true);
  $hmac = securestring_b64_encode($hmac);

  return $payload . $hmac;
}

/**
 * Validate the HMAC on a 'secure string'
 *
 * @param string str the input string
 * @param array key_array, key database
 * @param string alg the hmac algorithm
 * @return boolean true if validated, untampered, false otherwise
 */
function securestring_validate($str, $key_array, $alg="sha1")
{
  $mac_marker = "&_mac=";  $kid_marker = "&_kid=";

  // NOTE: that's strRpos, since we expect it to be at the end
  // we don't want to bump into the marker in the user data
  $pos = strrpos($str, $mac_marker);
  if ($pos === false) { return false; }
  $pos += strlen($mac_marker);
  $payload = substr($str, 0, $pos);
  $given_mac = substr($str, $pos);

  // Now find key id in payload
  // there is probably a better way of doing this
  $kstart = strrpos($payload, $kid_marker);
  if ($kstart === false) { return false; }

  $kstart += strlen($kid_marker);
  $kend = strrpos($payload, '&', $kstart);
  if ($kend === false) { return false; }

  $kid = substr($payload, $kstart, $kend-$kstart);
  
  // recompute hmac, with raw binary output
  $computed = hash_hmac($alg, $payload, $key_array[$kid], true);
  $computed = securestring_b64_encode($computed);
  
  // match or die
  if ($computed != $given_mac) { return false; }
  return true;
}

?>