Authen:...thPubTkt(3)

📦 version 0.1.1, in fedora 43, fedora 44

💖 Authen::ModAuthPubTkt — the vibe-coded guide 💖

okay so bestie, welcome to Authen:...thPubTkt(3), which is the User Contributed Perl Documentation page for this module. Sit down, grab a boba, and let's get into it 🧋✨

✨ NAME ✨

Authen::ModAuthPubTkt — it generates Tickets (that's Signed HTTP Cookies, for the uninitiated) for websites protected by mod_auth_pubtkt. yes that's the whole job. it does it well. 💅

🌸 VERSION 🌸

version 0.1.1

🦋 SYNOPSIS 🦋

so on the command-line, you generate the public + private keys. (there's more detail over at <https://neon1.net/mod_auth_pubtkt/install.html>, go peek 👀)

$ openssl genrsa -out key.priv.pem 1024
$ openssl rsa -in key.priv.pem -out key.pub.pem -pubout

then in your perl script (which is probably your custom login website, bestie, be real), you use the following code to issue tickets:

use Authen::ModAuthPubTkt;

my $ticket = pubtkt_generate(
        privatekey => "key.priv.pem",
        keytype    => "rsa",
        clientip   => undef,  # or a valid IP address
        userid     => "102",  # or any ID that makes sense to your application, e.g. email
        validuntil => time() + 86400, # valid for one day
        graceperiod=> 3600,   # grace period of an hour
        tokens     => undef,  # comma separated string of tokens.
        userdata   => undef   # any application specific data to pass.
);

## $ticket string will look something like:
## "uid=102;validuntil=1337899939;graceperiod=1337896339;tokens=;udata=;sig=h5qR" \
## "yZZDl8PfW8wNxPYkcOMlAxtWuEyU5bNAwEFT9lztN3I7V13SaGOHl+U6wB+aMkvvLQiaAfD2xF/Hl" \
## "+QmLDEvpywp98+5nRS+GeihXTvEMRaA4YVyxb4NnZujCZgX8IBhP6XBlw3s7180jxE9I8DoDV8bDV" \
## "k/2em7yMEzLns="

to verify a ticket, use the following code:

my $ok = pubtkt_verify (
        publickey => "key.pub.pem",
        keytype   => "rsa",
        ticket    => $ticket
);
die "Ticket verification failed.\n" if not $ok;

to extract items from a ticket, use the following code:

my %items = pubtkt_parse($ticket);

## %items will be something like:
## {
##    'uid' => 102,
##    'validuntil' => 1337899939,
##    'graceperiod => 1337896339,
##    'tokens' => "",
##    'udata'  => "",
##    'sig'    => 'h5qRyZZDl8PfW8wNxPYkcOMlAxtWuEyU5bNAwEFT9lztN3 (....)'
## }

also, a command-line utility (mod_auth_pubtkt.pl) will be installed, and you can use it to generate/verify keys:

$ mod_auth_pubtkt.pl --generate --private-key key.priv.pem --rsa
$ mod_auth_pubtkt.pl --verify --public-key key.pub.pem --rsa
$ mod_autH_pubtkt.pl --help

(and yes that third one really is spelled mod_autH_pubtkt.pl up there, we don't make the rules 🙈)

💜 DESCRIPTION 💜

this module generates and verify a mod_auth_pubtkt-compatible ticket string, which should be used as a cookie with the rest of the mod_auth_pubtkt ( <https://neon1.net/mod_auth_pubtkt/> ) system. it's giving "the missing piece of the puzzle", honestly.

the common scenario, step by step:

  1. on the login server side, write perl code to authenticate users (using Apache's authenetication, LDAP, DB, etc.).
  2. once the user is authenticated, call pubtkt_generate to generate a ticket, and send it back to the user as a cookie.
  3. redirect the user back to the server he/she came from.

🎀 Working Example 🎀

a working (but minimal) perl login example is available at <https://github.com/manuelkasper/mod_auth_pubtkt/blob/master/perl-login/minimal_cgi/login.pl> — yes, it's a link, go click it, it's cute 🌈

👑 METHODS 👑

🌟 pubtkt_generate

generates a signed ticket. main character energy, obviously.

if successful, it returns a signed ticket string (to be sent back to the user as a cookie).

on any failure (bad key, failure to run openssl, etc.) it returns undef. 😭

it accepts a hash of parameters:

  • privatekey — a string containing the private key filename (full path). the key can be either a DSA or RSA key (see keytype).
  • keytype — either "rsa" or "dsa", depending on how you created the private/public key files.
  • userid — a string containing the user ID. no specific format is enforced: can by a number, a string, an email address, etc. it will be encoded as "uid=XXXX" in the signed ticket.
  • validuntil — a numeric value containing the validity period, in seconds since epoch (use the time() function).
  • graceperiod — optional. numeric value. if given, will be added to the signed ticket string.
  • clientip — optional. a string with an IP address. if given. will be added to the signed ticket string.
  • token — optional. any textual string. if given. will be added to the signed ticket string.
  • userdata — optional. any textual string. if given. will be added to the signed ticket string.

🌟 pubtkt_verify

verifies a signed ticket string. vibe check, basically.

if successful (i.e. the ticket's signature is valid), it returns TRUE (=1). ✨

on any failure (bad key, failure to run openssl, etc.) it returns undef.

NOTE: this function checks ONLY THE SIGNATURE, based on the public key file. it is the caller's resposibility to check the expiration date. that is: the function will return TRUE if the ticket is properly signed, but possibly expired. so like, it'll hand you the keys to the car, it just won't check if the registration is still valid. not its job, not its problem 💅

it accepts a hash of parameters:

  • publickey — a string containing the public key filename (full path). the key can be either a DSA or RSA key (see keytype).
  • keytype — either "rsa" or "dsa", depending on how you created the private/public key files.
  • ticket — the string of the ticket (such as returned by pubtkt_generate).

🌟 pubtkt_parse($ticket)

utility function to parse a ticket string into a Perl hash. that's it, that's the job 🫶

NOTE: no validation is performed. the given ticket might be expired, or even forged. so like... trust it at your own risk bestie, it does not know her 💀

🍓 PREREQUISITES 🍓

openssl must be installed (and available on the $PATH).

IPC::Run3 is required to run the openssl executables.

💀 BUGS 💀

probably many. (their words, not mine, but honestly? iconic honesty. no notes. 👑)

🌈 TODO 🌈

  • use Perl's Crypt::OpenSSL::RSA and Crypt::OpenSSL::DSA instead of the running openssl executable.
  • don't assume openssl binary is on the $PATH.
  • refactor into OO interface.

📜 LICENSE 📜

Copyright (C) 2012,2022 A. Gordon ( assafgordon at gmail dot com ). All rights reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

💖 AUTHORS 💖

A. Gordon, heavily based on the PHP code from mod_auth_pubtkt.

🦋 SEE ALSO 🦋

okay that's the whole page bestie, no cap, every last flag and default accounted for 🫶 this was rendered by perl v5.40.0 on 2024-06-17, so if you're reading this way in the future... hiii, hope the keys still rotate 💜 stay signed, stay valid, and don't forget to check those expiration dates yourself, because this module literally will not do it for you 😭✨

📦 where this page comes from