NAME¶
FKO - Perl module wrapper for libfko
SYNOPSIS¶
use FKO;
# Create a new empty FKO object.
#
my $fko = FKO->new();
if(!$fko) {
die "Unable to create FKO object: $FKO::error_str\n";
}
# Override the username (default is current user).
#
my $err = $fko->username('joeuser');
if($err) {
die "Error setting username: ", $fko->errstr($err), "\n";
}
# Set the SPA message (see libfko docs for details).
#
$err = $fko->spa_message('0.0.0.0,tcp/22');
# ..error checking, etc...
$err = $fko->spa_data_final();
# ..error checking, etc...
# Get the encrypted and encoded SPA data.
#
my $spa_data = $fko->spa_data();
## Incoming SPA data ##
# Create an FKO object to process incoming (or existing)
# SPA data.
#
my $fko_in = FKO->new($enc_spa_data, 'decrypt_pw')
or die "Unable to create FKO object: $FKO::error_str\n";
my $timestamp = $fko_in->timestamp();
my $fko_user = $fko_in->username();
my $spa_msg = $fko_in->spa_message();
my $digest = $fko_in->spa_digest();
# Pull the digest type.
my $digest_type = $fko_in->spa_digest_type();
if($digest_type == FKO::FKO_DIGEST_SHA256) {
# do something
} elsif($digest_type == FKO::FKO_DIGEST_MD5) {
# do something else
}
DESCRIPTION¶
This module is essentially a Perl wrapper for the
Firewall Knock Operator
(fwknop) library, "libfko". Fwknop is an open source implementation
of
Single Packet Authorization (
SPA) for access to networked
resources.
The original
fwknop is implemented in Perl. The
libfko library is
an implementation of the
fwknop back-end data processing routines
written in C as part of the project to move all of
fwknop to C.
See the "libfko" documentation for additional information on usage and
the functionality provided by "libfko". More information on
SPA and
fwknop can be found at
http://www.cipherdyne.org/fwknop.
CONSTRUCTOR¶
- new( )
- new($spa_data, $password)
- The "new" method creates the FKO object.
With no arguments, it creates creates and empty FKO object ready to
be popluated with data (i.e. create a new SPA data packet to send).
You can also pass existing encoded/encrypted SPA data and a
decryption password to "new". Passing valid data and a password
will create the new object, decode and parse the data, and store it within
the object for later retrieval using the various methods described below.
If there are any errors during the creation or decoding of the data
new will return undef and the appropriate error message will be
available in the $FKO::error_str variable.
Create an empty object:
my $fko = FKO->new();
Create an object using existing data:
my $fko = FKO->new($spa_data, 'decrypt_pw');
METHODS¶
Utility Methods¶
The utility methods are those that perform the non-data-set/get functions like
error messages, data processing, and clean-up.
- destroy( )
- The "destroy" method is used when you are done
with the FKO object and its data. This method will make the
appropriate libfko calls to clean-up and release resources used by
the object.
Though "destroy" will be called if the object goes out of scope,
it is good practice to clean up after yourself. This is especially true if
you are processing multiple SPA messages in a loop, etc.
- errstr($err_code)
- This method returns the descriptive error message string
for the given error code value.
- gpg_errstr( )
- If the previous FKO error was from a GPG-related
function, then calling this method may return more detailed information
from the GPG error handling system.
- spa_data_final( )
- This function is the final step in creating a complete
encrypted SPA data string suitable for transmission to an fwknop
server. It does require all of the requisite SPA data fields be
set. Otherwise it will fail and return the appropriate error code.
- encrypt_spa_data( )
- Encrypts the intermediate encoded SPA data stored in
the context. The internal libfko encryption function will call the
internal "encode_spa_data" if necessary.
This function is normally not called directly as it is automatically called
from the internal "fko_spa_data_final" function (which is
wrapped by this module's "spa_data_final" function.
- decrypt_spa_data( )
- When given the correct key (passsword), this
function decrypts, decodes, and parses the encrypted SPA data
contained in the current context. Once the data is decrypted, the
libfko internal function will also call the libfko decode
function to decode, parse, validate, and store the data fields in the
context for later retrieval.
Note: This function does not need to be called directly if encrypted
SPA data was passed to this module's constructor when the object
was created as the "new" function will call decrypt and decode
itself.
- encode_spa_data( )
- Instructs libfko to perform the base64 encoding of
those SPA data fields that need to be encoded, perform some data
validation, compute and store the message digest hash for the SPA
data.
This function is normally not called directly as it is called by other
libfko functions during normal processing (i.e during encypt and/or
final functions.
- decode_spa_data( )
- This function hands of the data to the libfko
decoding routines which perform the decoding, parsing, and validation of
the SPA data that was just decrypted.
This function is normally not called directly as it is called by other
libfko functions during normal processing.
Working with SPA Data Types¶
There are a few data and method types supported by
libfko, along with a
few functions for getting and setting them. Most of these
types are
represented using constants defined in the
FKO module.
- encryption_type( )
- encryption_type(FKO_ENCRYPTION_TYPE)
- Get or set the encryption type for the current context. If
no argument is given, the current value is returned. Otherwise encryption
type will be set to the given value.
The encryption type parameter is an integer value. Constants have been
defined to represent this values. Currently, the only supported encryption
types are:
- •
- FKO_ENCRYPTION_RIJNDAEL
The default libfko encryption algorithm.
- •
- FKO_ENCRYPTION_GPG
GnuPG encryption (if supported by the underlying libfko
implementation).
- digest_type( )
- digest_type(FKO_DIGEST_TYPE)
- Get or set the digest type for the current context. If no
argument is given, the current value is returned. Otherwise digest type
will be set to the given value.
The digest type parameter is an integer value. Constants have been defined
to represent this values. Currently, the supported digest types are:
- •
- FKO_DIGEST_MD5
The MD5 message digest algorithm.
- •
- FKO_DIGEST_SHA1
The SHA1 message digest algorithm.
- •
- FKO_DIGEST_SHA256
The SHA256 message digest algorithm. This is the libfko default.
- •
- FKO_DIGEST_SHA384
The SHA384 message digest algorithm. This is the libfko default.
- •
- FKO_DIGEST_SHA512
The SHA512 message digest algorithm. This is the libfko default.
- spa_message_type( )
- spa_message_type(FKO_MSG_TYPE)
- Get or set the SPA message type. If no argument is
given, the current value is returned. Otherwise message type will be set
to the given value.
The message type parameter is an integer value. Constants have been defined
to represent this values. Currently, the supported digest types are:
- •
- FKO_COMMAND_MSG
A request to have the fwknop server execute the given command. The format
for this type is: "<ip of requestor>:<command text>"
For example:
"192.168.1.2:uname -a"
- •
- FKO_ACCESS_MSG
A basic access request. This is the most common type in use. The format for
this type is: "<ip of
requestor>:<protocol>/<port>".
For example:
"192.168.1.2:tcp/22"
- •
- FKO_NAT_ACCESS_MSG
An access request that also provide information for the fwknop server to
create a Network Address Translation (NAT to an internal address. The
format for this string is: "<internal ip>,<ext nat
port>".
For example:
"10.10.1.2,9922"
- •
- FKO_CLIENT_TIMEOUT_ACCESS_MSG
This is an "FKO_ACCESS_REQUEST" with a timeout parameter for the
fwknop server. The timeout value is provided via the
"client_timeout" data field.
- •
- FKO_CLIENT_TIMEOUT_NAT_ACCESS_MSG
This is an "FKO_NAT_ACCESS_REQUEST" with a timeout parameter for
the fwknop server. The timeout value is provided via the
"client_timeout" data field.
- •
- FKO_LOCAL_NAT_ACCESS_MSG
This is similar to the "FKO_NAT_ACCESS" request exept the NAT is
to the local to the server (i.e. a service listening on 127.0.0.1).
- •
- FKO_CLIENT_TIMEOUT_LOCAL_NAT_ACCES_MSG
This is an "FKO_LOCAL_NAT_ACCESS_REQUEST" with a timeout parameter
for the fwknop server. The timeout value is provided via the
"client_timeout" data field.
Working With SPA Data¶
The
SPA data methods are used for setting or retrieving the various
SPA data field values. Some of these simply return a read-only value,
while others are used to set or get values.
Note: The following methods are presented roughly in the order their
respective data values appear in an
fwknop SPA message. Many of
these have reasonable default values at creation and are not typically used in
most circumstances.
- rand_value( )
- rand_value($new_value)
- Get or set the random value portion of the SPA data.
If setting the random value, you must pass either a 16-character decimal
number (to set it to the given number), or the value 0 to have a new
random value generated by libfko.
If a provided value is not a valid 16-character decimal string, the function
will return the "FKO_ERROR_INVALID_DATA" error code.
Upon creation of a new FKO object, this value is automatically
generated.
- username( )
- username($username)
- Set or get the username field of the SPA data. If no
argument is given, given, this function will return the current value.
Otherwise, the username value will be set to the name provided.
If a value of 0 is given, libfko will attempt to determine and set
the username by first looking for the environment variable
"SPOOF_USER" and use its value if found. Otherwise, it will try
to determine the username itself using various system methods, then
fallback to the environment variables "LOGNAME" or
"USER". If none of those work, the function will return the
"FKO_ERROR_USERNAME_UNKNOWN" error code.
Upon creation of a new FKO object, this value is automatically
generated based on the libfko method described above.
- timestamp( )
- timestamp($offset)
- Gets or sets the timestamp value of the SPA data. If no
argument is given, the current value is returned.
If an argument is provided, it will represent an offset to be applied to the
current timestamp value at the time this function was called.
Upon creation of a new FKO object, this value is automatically
generated based on the time of object creation.
- version( )
- Returns the fwknop version string. This version
represents the supported fwknop SPA message format and
features. This has nothing to do with the version of this module.
- spa_message( )
- spa_message($spa_msg)
- Get or set the SPA message string. If no argument is
given, the current value is returned. Otherwise SPA message string
will be set to the given value.
- spa_nat_access( )
- spa_nat_access($nat_access)
- Get or set the SPA nat access string. If no argument
is given, the current value is returned. Otherwise SPA nat access
string will be set to the given value.
- spa_server_auth( )
- spa_server_auth($server_auth)
- Get or set the SPA server auth string. If no
argument is given, the current value is returned. Otherwise SPA
server auth string will be set to the given value.
- spa_client_timeout( )
- spa_client_timeout($new_timeout)
- Get or set the SPA message client timeout value.
This is an integer value. If no argument is given, the current value is
returned. Otherwise SPA message client timeout value will be set to
the given value.
- spa_digest( )
- spa_digest(1)
- When called with no argument, the "spa_digest"
function returns the digest associated with the current data (if
available). If a true value (i.e. 1) is given as the argument, it will
force a recompute of the digest based on the data and the configured
digest_type.
This function is normally not called directly as it is called by other
libfko functions during normal processing.
- encoded_data( )
- Returns the encoded SPA data as it would be just
before the encryption step. This is not generally useful unless you are
debugging a data issue.
- spa_data( )
- spa_data($spa_data)
- Get or set the SPA data string. If no argument is
given, the current value is returned. This would be the final encrypted
and encoded string of data that is suitable for sending to an fwkno
server.
If an argument is given, it is expected to be an existing encrypted and
encoded SPA data string (perhaps data received by an fwknop
server). The provided data is stored in the object (the current context).
Note: When data is provided via this function, it is not automatically
decoded. You would need to call "decrypt_spa_data($pw)" to
complete the decryption, decoding, and parsing process.
- gpg_recipient( )
- gpg_recipient($gpg_id)
- Get or set the gpg_recipient. This is the ID or email of
the public GPG key of the intended recipient. In order for this function
to work, the following condition must be met:
- •
- The underlying libfko implementation nust have GPG
support.
- •
- The encryption_type must be set to
"FKO_ENCRYPTION_GPG".
- •
- The specified GPG key must exist and be valid.
If no argument is given, the current value is returned. Otherwise, gpg_recipient
will be set to the given value.
- gpg_signer( )
- gpg_signer($gpg_id)
- Get or set the gpg_signer. This is the ID or email for the
secret GPG key to be used to sign the encryped data. In order for this
function to work, the following condition must be met:
- •
- The underlying libfko implementation nust have GPG
support.
- •
- The encryption_type must be set to
"FKO_ENCRYPTION_GPG".
- •
- The specified GPG key must exist and be valid.
If no argument is given, the current value is returned. Otherwise, gpg_signer
will be set to the given value.
- gpg_home_dir( )
- gpg_home_dir($new_dir)
- Get or set the GPG home directory. This is the directory
that holds the GPG keyrings, etc. In order for this function to work, the
following condition must be met:
- •
- The underlying libfko implementation nust have GPG
support.
- •
- The encryption_type must be set to
"FKO_ENCRYPTION_GPG".
- •
- The specified GPG home directory must exist.
If no argument is given, the current value is returned. Otherwise, gpg_home_dir
will be set to the given value.
GPG Signature Verification
By default libfko will attempt to verify GPG signatures when decrypting
GPG-encrypted data. If the signature is missing, expired, revoked, or
otherwise bad, the decoding operation will fail.
The following functions are provided to process GPG key information, or manage
how libfko deals with GPG signatures. Like the other GPG-related functions,
these also have the following prerequisites:
- •
- The underlying libfko implementation nust have GPG
support.
- •
- The encryption_type must be set to
"FKO_ENCRYPTION_GPG".
- gpg_signature_verify( )
- gpg_signature_verify($bool)
- Get or set the GPG signature verification flag. If true
(1), then GPG signatures are processed by libfko. This is the default
behavior. If set to false (0), then libfko will not even look for or at
any GPG signatures and will proceed with a decoding the SPA data.
If no argument is given, the current value is returned. Otherwise, the
gpg_signature_verify flag will be set to the given value.
- gpg_ignore_verify_error( )
- gpg_ignore_verify_error($bool)
- Get or set the GPG signature ignore verification error
flag. If true (1), then GPG signatures are processed and retained by
libfko, but a bad signature will not prevent the decoding phase. The
default is to not ignore errors.
If no argument is given, the current value is returned. Otherwise, the
gpg_ignore_verify_error flag will be set to the given value.
- gpg_signature_id( )
- Get ID of the GPG signature from the last decryption
operation.
- gpg_signature_fpr( )
- Get Fingerprint of the GPG signature from the last
decryption operation.
- gpg_signature_summary( )
- Get GPGME signature summary value of the GPG signature from
the last decryption operation. This value is a bitmask that hold
additional information on the signature (see GPGME docs for more
information).
- gpg_signature_status( )
- Get error status of the GPG signature from the last
decryption operation. This value is a GPGME error code (see GPGME docs for
more information).
- gpg_signature_id_match($id)
- Compare the given ID with the id of the GPG signature of
the last decryption operation. If the ID's match, then a true value is
returned. Otherwise false is returned.
- gpg_signature_fpr_match($id)
- Compare the given fingerprint value with the fingerprint of
the GPG signature of the last decryption operation. If the ID's match,
then a true value is returned. Otherwise false is returned.
SEE ALSO¶
Perl, the "libfko" manual.
Additional information on the Firewall Knock Operater (
fwknop) can be
found at
http://www.cipherdyne.org/fwknop.
AUTHOR¶
Damien S. Stuart, <dstuart@dstuart.org>
COPYRIGHT AND LICENSE¶
Copyright (C) 2009 by Damien S. Stuart
This library is free software; you can redistribute it and/or modify it under
the same terms as Perl itself, either Perl version 5.8.8 or, at your option,
any later version of Perl 5 you may have available.