SYNOPSIS

  <Location "/keys">
    SetHandler perl-script
    PerlSetHandler Authen::Ticket::Signature
    PerlSetVar  TicketSignaturePublicKey http://keys.my.com/keys/${id}
    PerlSetVar  TicketSignatureId        General
  </Location>

As part of ticket server:

  package My::Ticket::Server;

  @ISA = (qw/Authen::Ticket::Server Authen::Ticket::Signature/);

As part of ticket client:

  package My::Ticket::Client;

  @ISA = (qw/Authen::Ticket::Client Authen::Ticket::Signature/);

DESCRIPTION

If IPC::Shareable is available, keys are cached in shared memory across processes. This is a virtual requirement for a multiprocess Apache ticket server since all tickets should be signed by the same key. This is only a memory issue for client websites if several keys might need to be cached simultaneously.

Different keys may be cached with each having an identifying name. This name is used to retrieve the public portion of the key from the key server. The key to be retrieved for use in signing or verification is determined by the server configuration.

METHODS

handler

This routine provides the key server functionality. Only public keys may be requested. The path-info part of the request is the name of a key. For example, if http://my.com/keys is the location of the key server, then http://my.com/keys/general will return the public key of the default key for signing tickets.

$self->get_public_key

This routine will return the public key as appropriate according to the server configuration. If the key is not available in memory, an attempt will be made to fetch the key either from a remote server or the file system.

A public key is a hash reference with the various parts of the key. This is algorithm dependent. The El Gamal routine will return the following hashref:

  { 'y' => $y, 'p' => $p, 'g' => $g }
    

This is returned by the key server as the string "y:$y;p:$p;g:$g" with the values in hexadecimal.

$self->get_private_key

This routine will return the private key as appropriate according to the server configuration. If the required key is not available in cache, it will be generated. Since the private key is only to be used on the machine it is generated on, it does not make sense to fetch the private key from any particular location.

A private key is a hash reference with the various parts of the key. This is algorithm dependent. The El Gamal routine will return the following hashref:

  { 'x' => $x, 'p' => $p, 'g' => $g }
    

$self->generate_key( $key_length )

This routine must return the private and public key parts with a nominal key length of $key_length. See the get_{private,public}_key routines for the format of the key parts. The actual value returned is an array of the format:

  ( { private_key }, { public_key } )
    

$self->sign_ticket( $ticket )

This routine should attach a signature to $ticket and return the resulting value. The format used must be understood by $self->verify_ticket. The $ticket will have already been passed through $self->construct_ticket and $self->encode_ticket.

$self->verify_ticket( $ticket )

This routine should verify the signature on the $ticket and return the encoded ticket without the signature (this would be the value that was passed to sign_ticket). The following must hold true:

  $self->verify_ticket($self->sign_ticket($ticket)) eq $ticket
    

WHY EL GAMAL?

The El Gamal algorithms are not under any patent or licensing restrictions and may thus be used freely, though with export restrictions in mind.

The default algorithm in Authen::Ticket::Signature is El Gamal. The supplied code IS NOT INTENDED to be used to encrypt messages. Other parts of the algorithm may be used for encryption, but the signature portions are not intended to encrypt and decrypt data. However, [Schneier 532] points out the ability to send subliminal messages using the signature algorithms.

SHARED MEMORY

If IPC::Shareable is not loaded during the server startup, the Authen::Ticket::Signature code will not try to use it. Therefore, you must load IPC::Shareable before loading Authen::Ticket::Signature or any class derived from it.

AUTHOR

Portions of code are based on [Orwant 552-554] and [Stein 320].

COPYRIGHT

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

 1. Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.
 2. Redistributions in binary form must reproduce the above
    copyright notice, this list of conditions and the following
    disclaimer in the documentation and/or other materials
    provided with the distribution.
 3. Neither the name of the University nor the names of its
    contributors may be used to endorse or promote products
    derived from this software without specific prior written
    permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTERS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

SEE ALSO

Orwant, Jon, et. al. Mastering Agorithms with Perl, O'Reilly & Associates, 1999.

Schneier, Bruce Applied Cryptography, 2nd ed., John Wiley & Sons, 1996.

Stein, Lincoln, & Doug MacEachern. Writing Apache Modules with Perl and C, O'Reilly & Associates, 1999.

POD ERRORS

Around line 266:

=pod directives shouldn't be over one line long! Ignoring all 2 lines of content

Around line 383:

You forgot a '=back' before '=head1'