This package allows you to authenticate against kerberos realms, use the GSSAPI library and perform administrative tasks on a kerberos realm.
More information about Kerberos can be found at » http://web.mit.edu/kerberos/www/.
For the GSSAPI the best available reference can be found in RFC2744.
If you have comments, bugfixes, enhancements or want to help in developing this you can send me a mail at » mbechler@eenterphace.org.
This extensions requires the presence of a MIT or Heimdal kerberos library in a recent version. For KADM5 functionality the MIT distribution is required.
KADM5 support is disabled by default, enable it passing --with-krb5kadm to configure. KADM5 support uses some interal header files of the MIT krb5 distribution. These headers are bundled but you can specify another source (which needs to be a unpacked krb5 distribution with configure and make run) giving a path to the switch.
When compiling this extension as shared module:
run phpize in the extension directory
run ./configure (optionally add --with-krb5kadm if you need this functionality)
run make && make install
optional: enable your new extension in you php.ini by adding extension=krb5.so to it.
When compiling statically into your php binary:
move this extension into your php distributions ext/ folder
make sure that the directory is named "krb5"
run ./buildconf --force in the root directory of you php distribution
./configure php with your common flags and add --with-krb5 and optionally --with-krb5kadm=<path> where <path> is the path to your mit-krb5 distribution.
make && make install
This extension has no configuration directives defined in php.ini.
This extension has no resource types defined.
The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.
These constants are flags for GSSAPI contexts and used by the methods GSSAPIContext::initSecContext() GSSAPIContext::acceptSecContext(). More information is available in RFC2744.
| constant | |
|---|---|
| GSS_C_DELEG_FLAG | Request credential delegation when initiating context, only available when used credentials are forwardable. |
| GSS_C_MUTUAL_FLAG | Request mutual authentication. |
| GSS_C_REPLAY_FLAG | Request replay detection. |
| GSS_C_SEQUENCE_FLAG | |
| GSS_C_CONF_FLAG | |
| GSS_C_INTEG_FLAG | |
| GSS_C_ANON_FLAG | |
| GSS_C_PROT_READY_FLAG | |
| GSS_C_TRANS_FLAG |
These constants are flags for GSSAPI credentials and used by the method GSSAPIContext::acquireCredentials().
| constant | |
|---|---|
| GSS_C_BOTH | Request credentials to be usable for initiating and accepting contexts. |
| GSS_C_INITIATE | Request credentials to be usable for initiating contexts. |
| GSS_C_ACCEPT | Request credentials to be usable for accepting contexts. |
More examples can be found in the examples directory of the distribution.
This simple example shows how to obtain a TGT for a given credential using a password.
Example #1 Initializing a credential cache
<?php
$ccache = new KRB5CCache();
$flags = array('tkt_lifetime' => 3600);
$ccache->initPassword('principal@realm', 'password', $flags);
?>
Objects of this class represent credential caches. All credential caches are stored in unique memory caches but may be imported/exported to other ccache formats.
(No version information available, might only be in SVN)
KRB5CCache::getEntries — Gets the SPNs for which the ccache contains tickets
Gets the SPNs for which the ccache contains tickets.
This function has no parameters.
Returns an array of SPNs for which tickets exist.
Example #1 KRB5CCache::getEntries() example
<?php
$ccache = new KRB5CCache();
$ccache->initPassword("test","test");
$entries = $ccache->getEntries();
var_dump($entries);
?>
The above example will output something similar to:
array(1) {
[0]=>
string(32) "krbtgt/MYREALM@MYREALM"
}
(No version information available, might only be in SVN)
KRB5CCache::getName — Returns the credential cache identifier for the ccache
Returns the credential cache identifier for the ccache
This function has no parameters.
Returns the credential cache identifier for the ccache of the form TYPE:identifier
Example #1 KRB5CCache::getName() example
<?php
echo $ccache->getName();
?>
The above example will output something similar to:
MEMORY:5fds34asd
(No version information available, might only be in SVN)
KRB5CCache::initKeytab — Gets a TGT using a key given in a keytable file
Gets a TGT using a key given in a keytable file
Name of principal to get TGT for.
Path to keytable file which contains a suitable key for $principal
Associative array of Ticket flags.
| flag | type | description |
|---|---|---|
| forwardable | bool | Try to get a forwardable TGT |
| proxiable | bool | Try to get a proxiable TGT |
| tkt_life | integer | Lifetime of TGT in seconds |
| renew_life | integer | Renewable lifetime of TGT in seconds |
Example #1 KRB5CCache::initPassword() example
<?php
$ccache = new KRB5CCache();
$flags = array(
"forwardable" => true,
"tkt_life" => 60 * 60
);
$ccache->initKeytab("test@MYREALM", "/path/to/test-myrealm.keytab", $flags);
// if everything worked $ccache will now contain forwardable a TGT
// for test@MYREALM with lifetime of one hour
?>
(No version information available, might only be in SVN)
KRB5CCache::initPassword — Gets a TGT using a given password
Gets a TGT using a given password. Please note that using passwords is not suitable for services needing to accept GSSAPI contexts as the service key is required but then not available to GSSAPI.
Name of principal to get TGT for.
Password to authenticate.
Associative array of Ticket flags.
| flag | type | description |
|---|---|---|
| forwardable | bool | Try to get a forwardable TGT |
| proxiable | bool | Try to get a proxiable TGT |
| tkt_life | integer | Lifetime of TGT in seconds |
| renew_life | integer | Renewable lifetime of TGT in seconds |
Example #1 KRB5CCache::initPassword() example
<?php
$ccache = new KRB5CCache();
$flags = array(
"forwardable" => true,
"tkt_life" => 60 * 60
);
$ccache->initPassword("test@MYREALM", "test", $flags);
// if everything worked $ccache will now contain forwardable a TGT
// for test@MYREALM with lifetime of one hour
?>
(No version information available, might only be in SVN)
KRB5CCache::isValid — Checks whether the credentials contained are still valid
Checks whether the credentials contained are still valid or will be still valid after a given amount of time. Make sure to add a reasonable amount of time to compensate for clock skew.
Number of seconds for which the credentials should stay valid.
Returns true if the credentials are valid and false otherwise.
Example #1 KRB5CCache::isValid() example
<?php
$ccache->isValid(); // checks whether the credential cache is still valid
$ccache->isValid(3600); // checks whether the credential cache is still valid in an hour
?>
(No version information available, might only be in SVN)
KRB5CCache::open — Copies the credentials contained in some credential cache to this credential cache
Copies the credentials contained in some credential cache to this credential cache.
Identifier of the destination credential cache
(No version information available, might only be in SVN)
KRB5CCache::save — Copies the contents of the credential cache to another one
Copies the contents of the credential cache to another one. Please note that only the credentials currently available will be stored, so you will have to save the credential cache after service credentials are obtained through e.g. GSSAPI.
Identifier of the destination credential cache (e.g. FILE:/some/path/to/ccache)
Example #1 KRB5CCache::open() example
<?php
$ccache = new KRB5CCache();
$ccache->initPassword('test@MYREALM', 'test');
$ccache->save('FILE:/tmp/my.ccache');
$ccache2 = new KRB5CCache();
$ccache2->open('FILE:/tmp/my.ccache');
// $ccache2 will now contain the TGT for test@MYREALM
?>
(No version information available, might only be in SVN)
KRB5CCache::setConfig — Sets the kerberos confiuration file to use
Sets the kerberos confiuration file to use
Path to configuration file
Objects of this class represent GSSAPI security contexts. It is suitable for both initiating and accepting security contexts. It is designed to work with the kerberos mechanism.
(No version information available, might only be in SVN)
GSSAPIContext::acceptSecContext — Accepts a GSSAPI context initiated by a remote party
Accepts a GSSAPI context initiated by a remote party. GSSAPIContext::acquireCredentials should first be used to select the correct credentials, otherwise the default credential cache and keytab will be used.
Token passed by the remote party.
Token to pass to the remote party.
Principal name of the authenticated remote party
Flags of the established GSSAPI context.
Time in seconds for which the context will stay valid.
The given credential cache will be reinitalized and filled using delegated credentials, if available.
Will return true if the context was established, false otherwise.
Example #1 GSSAPIContext::acceptSecContext() example
<?php
// assume $client is a KRB5CCache containing credentials for client@MYREALM
// assume $server is a KRB5CCache containing credentials for server@MYREALM (initialized using keytab)
$cgssapi = new GSSAPIContext();
$cgssapi->acquireCredentials($client);
$sgssapi = new GSSAPIContext();
$sgssapi->acquireCredentials($server);
$token = '';
$cgssapi->initSecContext("server@MYREALM", null, null, null, $token);
$token2 = '';
$remote = '';
$sgssapi->acceptSecContext($token, $token2, $remote);
echo $remote;
?>
The above example will output something similar to:
client@MYREALM
(No version information available, might only be in SVN)
GSSAPIContext::acquireCredentials — Obtains credentials for establishing a GSSAPI context
Obtains credentials for establishing a GSSAPI context. If the credentials shall be used for accepting a GSSAPI context, the given credential cache must be initialized with a keytab, as access to the service key ist required.
Credential cache to fetch credentials from.
Principal to acquire credentials for
Type of credentials to acquire (GSS_C_BOTH, GSS_C_ACCEPT, GSS_C_INIT)
Example #1 GSSAPIContext::acquireCredentials() example
<?php
$ccache = new KRB5CCache();
$ccache->initPassword('test@MYREALM', 'test');
$gssapi = new GSSAPIContext();
$gssapi->acquireCredentials($ccache);
$token = '';
$gssapi->initSecContext('server@MYREALM', null, null, null, $token);
// the context will be initiated as test@MYREALM
?>
(No version information available, might only be in SVN)
GSSAPIContext::getMic — Calculate a MIC on a given message
Calculate a MIC on a given message. For remote verification both the message and the returned MIC have to be passed to the remote party.
Message to calculate MIC on.
Returns the MIC valid for the current GSSAPI context.
Example #1 GSSAPIContext::getMic() example
<?php
// assume $cgssapi is the initiator of some context
// and $sgssapi is the acceptor of the context
$message = 'foo';
$mic = $cgssapi->getMic($message);
$sgssapi->verifyMic($message, $mic); // will return true if valid
?>
(No version information available, might only be in SVN)
GSSAPIContext::initSecContext — Initiates a GSSAPI security context
This method initiates a GSSAPI context. GSSAPIContext::acquireCredentials should first be used to select the correct credentials, otherwise the default credential cache will be used.
SPN of principal to establish security context with.
GSSAPI Token passed by the context acceptor (for the kerberos mechanism only required if mutual authentication is performed).
GSSAPI Context flags (see the Constants section, defaults to no flags)
Time in seconds which the context should stay valid (defaults to 0, which means the context will stay valid as long as possible)
Token to pass to the context acceptor for authentication
Flags of the (possibly not yet established) security context
Time in seconds which the context will stay valid
Returns true if the context is fully established and false otherwise.
Example #1 GSSAPIContext::initSecContext() example
<?php
// assume $client is a KRB5CCache containing credentials for client@MYREALM
// assume $server is a KRB5CCache containing credentials for server@MYREALM (initialized using keytab)
$cgssapi = new GSSAPIContext();
$cgssapi->acquireCredentials($client);
$sgssapi = new GSSAPIContext();
$sgssapi->acquireCredentials($server);
$token = '';
$cgssapi->initSecContext("server@MYREALM", null, null, null, $token);
$token2 = '';
$remote = '';
$sgssapi->acceptSecContext($token, $token2, $remote);
echo $remote;
?>
The above example will output something similar to:
client@MYREALM
(No version information available, might only be in SVN)
GSSAPIContext::inquireCredentials — Gets information about the credentials used for context establishment
Gets information about the credentials associated with the GSSAPIContext.
This function has no parameters.
Will return an associative array of
| key | type | description |
|---|---|---|
| name | string | Prinicipal (local) |
| lifetime_remain | int | Remaining time in seconds for which the credentials are valid |
| cred_usage | integer | Possible credential usage (GSS_C_BOTH, GSS_C_INITIATE, GSS_C_ACCEPT) |
| mechs | array of strings | OIDs of usable mechanisms |
(No version information available, might only be in SVN)
GSSAPIContext::registerAcceptorIdentity — Register credentials for context establishment (acceptor side)
Registers a keytab with the GSSAPI context from which the service credentials will be extracted.
Path to keytab from which the service key will be extracted when accepting a context.
Returns nothing.
(No version information available, might only be in SVN)
GSSAPIContext::unwrap — Unwraps a previously wrapped message
Unwraps a previously wrapped message, which means that the embedded MIC will be verified and the message possibly be decrypted.
Input token
Message (possibly decrypted)
Returns true if successful and false otherwise.
Example #1 GSSAPIContext::unwrap() example
<?php
/* ... */
$message = 'test';
$decoded = '';
$token = '';
$sgssapi->wrap($message, $token, true); // adds a MIC and encrypts $message
$cgssapi->unwrap($token, $decoded);
// returns true when the embedded MIC is valid
// $decoded will contain test
?>
(No version information available, might only be in SVN)
GSSAPIContext::verifyMic — Verifies a MIC calculated by the remote party
Verifies a MIC calculated by the remote party
Message to verify MIC
MIC
true if the passed MIC is valid for the message and false otherwise.
Example #1 GSSAPIContext::verifyMic() example
<?php
// assume $cgssapi is the initiator of some context
// and $sgssapi is the acceptor of the context
$message = 'foo';
$mic = $cgssapi->getMic($message);
$sgssapi->verifyMic($message, $mic); // will return true if valid
?>
(No version information available, might only be in SVN)
GSSAPIContext::wrap — Wraps a message
Wraps a message, which means that the message and a MIC will be combined into a token which may be passed to a remote party. Optionally the message can be also encrypted.
Message to wrap
Wrapped token
Whether to encrypt the message
Returns true if successful and false otherwise.
Example #1 GSSAPIContext::wrap() example
<?php
/* ... */
$message = 'test';
$decoded = '';
$token = '';
$sgssapi->wrap($message, $token, true); // adds a MIC and encrypts $message
$cgssapi->unwrap($token, $decoded);
// returns true when the embedded MIC is valid
// $decoded will contain test
?>
This class provides a simple interface for doing HTTP Negotiate/SPNEGO authentication. This interface might be obsolete, as this functionality might be easily implemented using the GSSAPI interface. Please note that this is only possible for SAPIs which have access to the Authorization header (e.g. not using the CGI SAPI).
(No version information available, might only be in SVN)
KRB5NegotiateAuth::__construct — Initialize the negotiate auth handler
Initialize the negotiate auth handler
Path to the keytab containing the service key for the principal HTTP/server.f.q.d.n@MYREALM
(No version information available, might only be in SVN)
KRB5NegotiateAuth::doAuthentication — Performs HTTP Negotiate authentication
This method performs HTTP Negotiate authentication. It will fetch the provided credentials from the request headers and set the response headers appropriately to perform authentication.
This function has no parameters.
Returns true when authentication was successful, false otherwise.
Example #1 KRB5NegotiateAuth::doAuthentication() example
<?php
$auth = new KRB5NegotiateAuth('/etc/krb5.keytab');
if($auth->doAuthentication()) {
echo 'Success - authenticated as ' . $auth->getAuthenticatedUser();
try {
$cc = new KRB5CCache();
$auth->getDelegatedTicket($cc);
} catch (Exception $error) {
echo 'No delegated credentials available';
}
} else {
if(!empty($_SERVER['PHP_AUTH_USER'])) {
header('HTTP/1.1 401 Unauthorized');
header('WWW-Authenticate: Basic', false);
} else {
// verify basic authentication data
echo 'authenticated using BASIC method<br />';
}
}
?>
(No version information available, might only be in SVN)
KRB5NegotiateAuth::getAuthenticatedUser — Returns the principal name of the authenticated user
Returns the principal name of the authenticated user
This function has no parameters.
Returns the principal name of the authenticated user
(No version information available, might only be in SVN)
KRB5NegotiateAuth::getDelegatedCredentials — Gets the possibly delegated credentials of the authenticated user
Gets the possibly delegated credentials of the authenticated user
Credential cache that will be initialized using the delegated credentials.