Provided by: libfko-perl_2.6.9-2_amd64 bug

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('1.2.3.4,tcp/22');
           # ..error checking, etc...

         $err = $fko->spa_data_final('mycryptkey', 'myhmackey');
           # ..error checking, etc...

         # Get the encrypted/authenticated/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, 'mycryptkey',
               FKO::FKO_ENC_MODE_CBC, 'myhmackey', FKO::FKO_HMAC_SHA256)
           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 that are protected by a default-drop packet
       filter.

       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, $enc_type, $hmac_key, $hmac_type)
           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, a decryption password, and an
           HMAC key (along with associated encryption and HMAC modes) to "new".  This will create
           a new object, authenticate, decrypt, and decode 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', FKO::FKO_ENC_MODE_CBC,
                       'myhmackey', FKO::FKO_HMAC_SHA256);

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($enc_key, $hmac_key)
           This function is the final step in creating a complete encrypted and authenticated 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 the encryption type will be set to the given
           value.

           The encryption type parameter is an integer value.  Constants have been defined to
           represent this value.  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).

       hmac_type( )
       hmac_type(FKO_HMAC_TYPE)
           Get or set the HMAC digest algorithm for the current context.  If no argument is
           given, the current value is returned.  Otherwise the HMAC type will be set to the
           given value.

           The HMAC type parameter is an integer value.  Constants have been defined to represent
           this value.  Currently, the supported HMAC types are:

           •   FKO_HMAC_SHA256

               The default libfko HMAC digest algorithm is SHA-256

           •   FKO_HMAC_MD5

               Use the MD5 digest algorithm (not recommended) to generate the HMAC.

           •   FKO_HMAC_SHA1

               Use the SHA-1 digest algorithm to generate the HMAC.

           •   FKO_HMAC_SHA512

               Use the SHA-512 digest algorithm to generate the HMAC.

       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 value.  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 value.  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 except 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.