Sophie: php-kadm5-4.3.3_0.2.3-1mdk i586

php-kadm5-4.3.3_0.2.3-1mdk.i586.rpm

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.00 $ -->
<reference id="ref.kadm5">
  <title>KADM5 Functions</title>
  <titleabbrev>KADM5</titleabbrev>

  <partintro>
  <sect1 id="kadm5.intro">
    <title>Introduction to KADM5</title>
    <simpara>
    These functions allow you to access Kerberos administration servers. In
    order to have these functions available, you must compile PHP
    with KADM5 support by using the
    <option role="configure">--with-kadm5</option> option. If you
    use this option without specifying the path to KADM5, PHP will
    use the built-in KADM5 client libraries. Users who run other
    applications that use KADM5 (for example, running PHP 3 and PHP 4
    as concurrent apache modules, or auth-kadm5) should always
    specify the path to KADM5:
    <option role="configure">--with-kadm5=/path/to/kadm5</option>.
    This will force PHP to use the client libraries installed by
    KADM5, avoiding any conflicts.
   </simpara>
   <simpara>
    More information about Kerberos can be found at <ulink
    url="http://web.mit.edu/kerberos/www/"></ulink>.
   </simpara>
   <simpara>
    Documentation for Kerberos and KADM5 can be found at <ulink
    url="http://web.mit.edu/kerberos/www/krb5-1.2/krb5-1.2.8/doc/admin_toc.html"></ulink>.
   </simpara>

   <para>
    This simple example shows how to connect, query, print
    resulting principals and disconnect from a KADM5 database.
    <example>
     <title>KADM5 extension overview example</title>
     <programlisting role="php">
<![CDATA[
<?php

  $handle = kadm5_init_with_password("afs-1", "GONICUS.LOCAL", "admin/admin", "password");

  print "<h1>get_principals</h1>\n";
  $principals = kadm5_get_principals($handle);
  for( $i=0; $i<count($principals); $i++)
      print "$principals[$i]<br>\n";

  print "<h1>get_policies</h1>\n";
  $policies = kadm5_get_policies($handle);
  for( $i=0; $i<count($policies); $i++)
      print "$policies[$i]<br>\n";

  print "<h1>get_principal burbach@GONICUS.LOCAL</h1>\n";

  $options = kadm5_get_principal($handle, "burbach@GONICUS.LOCAL" );
  $keys = array_keys($options);
  for( $i=0; $i<count($keys); $i++) {
    $value = $options[$keys[$i]];
    print "$keys[$i]: $value<br>\n";
  }

  $options = array(KADM5_PRINC_EXPIRE_TIME => 0);
  kadm5_modify_principal($handle, "burbach@GONICUS.LOCAL", $options);

  kadm5_destroy($handle);
?>
]]>
     </programlisting>
    </example>
   </para>
   </sect1>

  <sect1 id="kadm5.constantsAF">
    <title>Constants for Attribute Flags</title>
    <para>
     The functions <function>kadm5_create_principal</function>,
	 <function>kadm5_modify_principal</function>, and
	 <function>kadm5_modify_principal</function> allow to specify
	 special attributes using a bitfield. The symbols are defined below:
     <table>
      <title>Attributes for use by the KDC</title>
      <tgroup cols="1">
       <thead>
        <row>
         <entry>constant</entry>
        </row>
       </thead>
       <tbody>
        <row>
         <entry>KRB5_KDB_DISALLOW_POSTDATED</entry>
        </row>
        <row>
         <entry>KRB5_KDB_DISALLOW_FORWARDABLE</entry>
        </row>
        <row>
         <entry>KRB5_KDB_DISALLOW_TGT_BASED</entry>
        </row>
        <row>
         <entry>KRB5_KDB_DISALLOW_RENEWABLE</entry>
        </row>
        <row>
         <entry>KRB5_KDB_DISALLOW_PROXIABLE</entry>
        </row>
        <row>
         <entry>KRB5_KDB_DISALLOW_DUP_SKEY</entry>
        </row>
        <row>
         <entry>KRB5_KDB_DISALLOW_ALL_TIX</entry>
        </row>
        <row>
         <entry>KRB5_KDB_REQUIRES_PRE_AUTH</entry>
        </row>
        <row>
         <entry>KRB5_KDB_REQUIRES_HW_AUTH</entry>
        </row>
        <row>
         <entry>KRB5_KDB_REQUIRES_PWCHANGE</entry>
        </row>
        <row>
         <entry>KRB5_KDB_DISALLOW_SVR</entry>
        </row>
        <row>
         <entry>KRB5_KDB_PWCHANGE_SERVER</entry>
        </row>
        <row>
         <entry>KRB5_KDB_SUPPORT_DESMD5</entry>
        </row>
        <row>
         <entry>KRB5_KDB_NEW_PRINC</entry>
        </row>
       </tbody>
      </tgroup>
     </table>
    </para>
	</sect1>

  <sect1 id="kadm5.constantsOP">
    <title>Constants for Options</title>
    <para>
     The functions <function>kadm5_create_principal</function>,
	 <function>kadm5_modify_principal</function>, and
	 <function>kadm5_get_principal</function> allow to specify
	 or return principal's options as an associative array.
	 The keys for the associative array are defined as string
	 constants below:

	 <table>
      <title>Options for creating/modifying/retrieving principals</title>
      <tgroup cols="2">
       <thead>
        <row>
         <entry>constant</entry>
		 <entry>type</entry>
         <entry>description</entry>
        </row>
       </thead>
       <tbody>
        <row>
         <entry>KADM5_PRINCIPAL</entry>
         <entry>long</entry>
         <entry>The expire time of the princial as a Kerberos timestamp.</entry>
        </row>
        <row>
         <entry>KADM5_PRINC_EXPIRE_TIME</entry>
         <entry>long</entry>
         <entry>The expire time of the princial as a Kerberos timestamp.</entry>
        </row>
        <row>
         <entry>KADM5_LAST_PW_CHANGE</entry>
         <entry>long</entry>
         <entry>The time this principal's password was last changed.</entry>
        </row>
        <row>
         <entry>KADM5_PW_EXPIRATION</entry>
         <entry>long</entry>
         <entry>The expire time of the principal's current password, as a Kerberos timestamp.</entry>
        </row>
        <row>
         <entry>KADM5_MAX_LIFE</entry>
         <entry>long</entry>
         <entry>The maximum lifetime of any Kerberos ticket issued to this principal.</entry>
        </row>
        <row>
         <entry>KADM5_MAX_RLIFE</entry>
         <entry>long</entry>
         <entry>The maximum renewable lifetime of any Kerberos ticket issued to or for this principal.</entry>
        </row>
        <row>
         <entry>KADM5_MOD_NAME</entry>
         <entry>string</entry>
         <entry>The name of the Kerberos principal that most recently modified this principal.</entry>
        </row>
        <row>
         <entry>KADM5_MOD_TIME</entry>
         <entry>long</entry>
         <entry>The time this principal was last modified, as a Kerberos timestamp.</entry>
        </row>
        <row>
         <entry>KADM5_KVNO</entry>
         <entry>long</entry>
         <entry>The version of the principal's current key.</entry>
        </row>
        <row>
         <entry>KADM5_POLICY</entry>
         <entry>string</entry>
         <entry>The name of the policy controlling this principal.</entry>
        </row>
        <row>
         <entry>KADM5_CLEARPOLICY</entry>
         <entry>long</entry>
         <entry>Standard procedure is to assign the 'default' policy to new principals.
		 KADM5_CLEARPOLICY suppresses this behaviour.</entry>
        </row>
        <row>
         <entry>KADM5_LAST_SUCCESS</entry>
         <entry>long</entry>
         <entry>The KDC time of the last successfull AS_REQ.</entry>
        </row>
        <row>
         <entry>KADM5_LAST_FAILED</entry>
         <entry>long</entry>
         <entry>The KDC time of the last failed AS_REQ.</entry>
        </row>
        <row>
         <entry>KADM5_FAIL_AUTH_COUNT</entry>
         <entry>long</entry>
         <entry>The number of consecutive failed AS_REQs.</entry>
        </row>
		<row>
         <entry>KADM5_RANDKEY</entry>
         <entry>long</entry>
         <entry>Generates a random password for the principal. The parameter
		   <parameter>password</parameter> will be ignored.
		 </entry>
        </row>
		<row>
         <entry>KADM5_ATTRIBUTES</entry>
         <entry>long</entry>
         <entry>A bitfield of attributes for use by the KDC.
		 </entry>
        </row>
       </tbody>
      </tgroup>
     </table>
    </para>
	</sect1>
  </partintro>


  <refentry id="function.kadm5-init-with-password">
   <refnamediv>
    <refname>kadm5_init_with_password</refname>
    <refpurpose>Opens a conncetion to the KADM5 library and initializes any neccessary
	state information.</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>resource</type><methodname>kadm5_init_with_password</methodname>
      <methodparam><type>string</type><parameter>
        admin_server
       </parameter></methodparam>
      <methodparam><type>string</type><parameter>
        realm
       </parameter></methodparam>
      <methodparam><type>string</type><parameter>
        principal
       </parameter></methodparam>
      <methodparam><type>string</type><parameter>
        password
       </parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns a KADM5 handle on success, or &false; on failure.
    </para>
	<para>
     <function>kadm5_init_with_password</function>
	 Opens a connection with the KADM5 library using the
	 <parameter>principal</parameter> and the given
	 <parameter>password</parameter> to obtain initial credentials
	 from the <parameter>admin_server</parameter>. The parameter
	 <parameter>realm</parameter> defines the authentication domain
	 for the connection.
    </para>
    <example>
     <title>KADM5 initialization example</title>
     <programlisting role="php">
<![CDATA[
<?php

  $handle = kadm5_init_with_password("afs-1", "GONICUS.LOCAL", "admin/admin", "password");

  $attributes = KRB5_KDB_REQUIRES_PRE_AUTH | KRB5_KDB_DISALLOW_PROXIABLE;
  $options = array(KADM5_PRINC_EXPIRE_TIME => 0,
                   KADM5_POLICY => "default",
                   KADM5_ATTRIBUTES => $attributes);

  kadm5_create_principal($handle, "burbach@GONICUS.LOCAL", "password", $options);

  kadm5_destroy($handle);
?>
]]>
     </programlisting>
    </example>

	<note>
     <para>
	  Connection should be closed after use with
      <function>kadm5_destroy</function>.
     </para>
    </note>
    <para>
     See also: <function>kadm5_destroy</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.kadm5-flush">
   <refnamediv>
    <refname>kadm5_flush</refname>
    <refpurpose>Flush all changes to the Kerberos database, leaving the connection
	to the Kerberos admin server open.</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>kadm5_flush</methodname>
      <methodparam><type>resource</type><parameter>
        handle
       </parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns &true on success, or &false; on failure.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.kadm5-destroy">
   <refnamediv>
    <refname>kadm5_destroy</refname>
    <refpurpose>Closes the connection to the admin server and releases all related resources.</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>kadm5_destroy</methodname>
      <methodparam><type>resource</type><parameter>
        handle
       </parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns &true on success, or &false; on failure.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.kadm5-create-principal">
   <refnamediv>
    <refname>kadm5_create_principal</refname>
    <refpurpose>Creates a kerberos principal with the given parameters.</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>kadm5_create_principal</methodname>
      <methodparam><type>resource</type><parameter>
        handle
       </parameter></methodparam>
      <methodparam><type>string</type><parameter>
        principal
       </parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>
        password
       </parameter></methodparam>
      <methodparam choice="opt"><type>array</type><parameter>
        options
       </parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns &true on success, or &false; on failure.
    </para>
	<para>
     <function>kadm5_create_principal</function>
	 creates a <parameter>principal</parameter> with the given
	 <parameter>password</parameter>. If <parameter>password</parameter>
	 is omitted or is &null, a random key will be generated.
    </para>
	<para>
	 It is possible to specify several optional parameters within the
	 array <parameter>options</parameter>. Allowed are the following
	 options: KADM5_PRINC_EXPIRE_TIME, KADM5_PW_EXPIRATION, KADM5_ATTRIBUTES,
	 KADM5_MAX_LIFE, KADM5_KVNO, KADM5_POLICY, KADM5_CLEARPOLICY,
	 KADM5_MAX_RLIFE.
	</para>

    <example>
     <title>Example of principal's creation</title>
     <programlisting role="php">
<![CDATA[
<?php

  $handle = kadm5_init_with_password("afs-1", "GONICUS.LOCAL", "admin/admin", "password");

  $attributes = KRB5_KDB_REQUIRES_PRE_AUTH | KRB5_KDB_DISALLOW_PROXIABLE;
  $options = array(KADM5_PRINC_EXPIRE_TIME => 0,
                   KADM5_POLICY => "default",
                   KADM5_ATTRIBUTES => $attributes);

  kadm5_create_principal($handle, "burbach@GONICUS.LOCAL", "password", $options);

  kadm5_destroy($handle);
?>
]]>
     </programlisting>
    </example>
   </refsect1>
  </refentry>

 <refentry id="function.kadm5-delete-principal">
   <refnamediv>
    <refname>kadm5_delete_principal</refname>
    <refpurpose>Deletes a kerberos principal.</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>kadm5_delete_principal</methodname>
      <methodparam><type>resource</type><parameter>
        handlesection
       </parameter></methodparam>
      <methodparam><type>string</type><parameter>
        principal
       </parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns &true on success, or &false; on failure.
    </para>
	<para>
     <function>kadm5_delete_principal</function>
	 remove the <parameter>principal</parameter> from the
	 Kerberos database.
    </para>
    <example>
     <title>KADM5 extension overview example</title>
     <programlisting role="php">
<![CDATA[
<?php

  $handle = kadm5_init_with_password("afs-1", "GONICUS.LOCAL", "admin/admin", "password");

  kadm5_delete_principal($handle, "burbach@GONICUS.LOCAL");

  kadm5_destroy($handle);
?>
]]>
     </programlisting>
    </example>

   </refsect1>
  </refentry>

  <refentry id="function.kadm5-modify-principal">
   <refnamediv>
    <refname>kadm5_modify_principal</refname>
    <refpurpose>Modifies a kerberos principal with the given parameters.</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>kadm5_modify_principal</methodname>
      <methodparam><type>resource</type><parameter>
        handle
       </parameter></methodparam>
      <methodparam><type>string</type><parameter>
        principal
       </parameter></methodparam>
      <methodparam choice="opt"><type>array</type><parameter>
        options
       </parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns &true on success, or &false; on failure.
    </para>
	<para>
     <function>kadm5_create_principal</function>
	 modifies a <parameter>principal</parameter> according to the given
	 <parameter>options</parameter>. Allowed are the following
	 options: KADM5_PRINC_EXPIRE_TIME, KADM5_PW_EXPIRATION, KADM5_ATTRIBUTES,
	 KADM5_MAX_LIFE, KADM5_KVNO, KADM5_POLICY, KADM5_CLEARPOLICY,
	 KADM5_MAX_RLIFE, KADM5_FAIL_AUTH_COUNT.
	</para>
    <example>
     <title>Example of modifying principal</title>
     <programlisting role="php">
<![CDATA[
<?php

  $handle = kadm5_init_with_password("afs-1", "GONICUS.LOCAL", "admin/admin", "password");

  $attributes = KRB5_KDB_REQUIRES_PRE_AUTH;
  $options = array(KADM5_PRINC_EXPIRE_TIME => 3451234,
                   KADM5_POLICY => "gonicus",
                   KADM5_ATTRIBUTES => $attributes);

  kadm5_modify_principal($handle, "burbach@GONICUS.LOCAL", "password", $options);

  kadm5_destroy($handle);
?>
]]>
     </programlisting>
    </example>

   </refsect1>
  </refentry>

  <refentry id="function.kadm5-chpass-principal">
   <refnamediv>
    <refname>kadm5_chpass_principal</refname>
    <refpurpose>Changes the principal's password.</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>kadm5_chpass_principal</methodname>
      <methodparam><type>resource</type><parameter>
        handle
       </parameter></methodparam>
      <methodparam><type>string</type><parameter>
        principal
       </parameter></methodparam>
      <methodparam><type>string</type><parameter>
        password
       </parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns &true on success, or &false; on failure.
    </para>
	<para>
     <function>kadm5_chpass_principal</function>
	 sets the new password <parameter>password</parameter> for
	 the <parameter>principal</parameter>.
	</para>
    <example>
     <title>Example of changing principal's password</title>
     <programlisting role="php">
<![CDATA[
<?php

  $handle = kadm5_init_with_password("afs-1", "GONICUS.LOCAL", "admin/admin", "password");

  kadm5_chpass_principal($handle, "burbach@GONICUS.LOCAL", "newpassword");

  kadm5_destroy($handle);
?>
]]>
     </programlisting>
    </example>

   </refsect1>
  </refentry>

  <refentry id="function.kadm5-get-principal">
   <refnamediv>
    <refname>kadm5_get_principal</refname>
    <refpurpose>Gets the principal's entries from the Kerberos database.</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>array</type><methodname>kadm5_get_principal</methodname>
      <methodparam><type>resource</type><parameter>
        handle
       </parameter></methodparam>
      <methodparam><type>string</type><parameter>
        principal
       </parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns array of options on success, or &false; on failure.
    </para>
	<para>
     <function>kadm5_get_principal</function>
	 returns an associative array containing the following
	 keys: KADM5_PRINCIPAL, KADM5_PRINC_EXPIRE_TIME, KADM5_PW_EXPIRATION, KADM5_ATTRIBUTES,
	 KADM5_MAX_LIFE, KADM5_MOD_NAME, KADM5_MOD_TIME, KADM5_KVNO, KADM5_POLICY,
	 KADM5_MAX_RLIFE, KADM5_LAST_SUCCESS, KADM5_LAST_FAILED, KADM5_FAIL_AUTH_COUNT.
	</para>
    <example>
     <title>KADM5 extension overview example</title>
     <programlisting role="php">
<![CDATA[
<?php

  $handle = kadm5_init_with_password("afs-1", "GONICUS.LOCAL", "admin/admin", "password");

  print "<h1>get_principal burbach@GONICUS.LOCAL</h1>\n";

  $options = kadm5_get_principal($handle, "burbach@GONICUS.LOCAL" );

  $keys = array_keys($options);
  for( $i=0; $i<count($keys); $i++) {
    $value = $options[$keys[$i]];
    print "$keys[$i]: $value<br>\n";
  }

  kadm5_destroy($handle);
?>
]]>
     </programlisting>
    </example>

   </refsect1>
  </refentry>

  <refentry id="function.kadm5-get-principals">
   <refnamediv>
    <refname>kadm5_get_principals</refname>
    <refpurpose>Gets all principals from the Kerberos database.</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>array</type><methodname>kadm5_get_principals</methodname>
      <methodparam><type>resource</type><parameter>
        handle
       </parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns array of principals on success, or &false; on failure.
    </para>
	<para>
     <function>kadm5_get_principals</function>
	 returns an array containing the principals's names.
	</para>
    <example>
     <title>KADM5 extension overview example</title>
     <programlisting role="php">
<![CDATA[
<?php

  $handle = kadm5_init_with_password("afs-1", "GONICUS.LOCAL", "admin/admin", "password");

  print "<h1>get_principals</h1>\n";
  $principals = kadm5_get_principals($handle);
  for( $i=0; $i<count($principals); $i++)
      print "$principals[$i]<br>\n";

  kadm5_destroy($handle);
?>
]]>
     </programlisting>
    </example>
   </refsect1>
  </refentry>

  <refentry id="function.kadm5-get-policies">
   <refnamediv>
    <refname>kadm5_get_policies</refname>
    <refpurpose>Gets all policies from the Kerberos database.</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>array</type><methodname>kadm5_get_policies</methodname>
      <methodparam><type>resource</type><parameter>
        handle
       </parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns array of policies on success, or &false; on failure.
    </para>
	<para>
     <function>kadm5_get_principals</function>
	 returns an array containing the policies's names.
	</para>
    <example>
     <title>KADM5 extension overview example</title>
     <programlisting role="php">
<![CDATA[
<?php

  $handle = kadm5_init_with_password("afs-1", "GONICUS.LOCAL", "admin/admin", "password");

  print "<h1>get_policies</h1>\n";
  $policies = kadm5_get_policies($handle);
  for( $i=0; $i<count($policies); $i++)
      print "$policies[$i]<br>\n";

  kadm5_destroy($handle);
?>
]]>
     </programlisting>
    </example>

   </refsect1>
  </refentry>


 </reference>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->