This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: OpenCA/CRL, Next: OpenCA/CRR, Prev: Opcode, Up: Module List CRL Management module. ********************** NAME ==== OpenCA::CRL - CRL Management module. SYNOPSIS ======== use OpenCA::CRL; DESCRIPTION =========== This module contains functions to access CRLs infos. It, as the OpenCA::X509 module, requires some parameters such as a reference to an OpenCA::OpenSSL instance. This module provides a CRL->PERL Hashes parsing, no specific crypto functions are performed. FUNCTIONS ========= sub new () - Create a new instance of the Class. ------------------------------------------------ Creating a new instance of the module you can provide a valid crl. As a result the crl will be parsed and stored in local variable(s) for later usage. You can generate a new instance of the class either by giving an already issued CRL (see OpenCA::OpenSSL for documentation) or even generate a new CRL if you provide the CACERT and CAKEY. The function will return a self reference. Accepted parameters are: SHELL - An OpenCA::OpenSSL initialized instance; CRL - A valid CRL(*); INFILE - A CRL file(*); FORMAT - Format of the provided CRL. Supported are PEM|DER(*); CAKEY - CA private key file(*); CACERT - CA certificate file(*); DAYS - Days the CRL will be valid(*); EXTS - Extentions section (see openssl.cnf documentation)(*); (*) - Optional Parameters; EXAMPLE: my $self->{crl} = new OpenCA::CRL( SHELL=>$openssl, CRL=>$pemCRL ); NOTE: When you generate a new CRL, you have to provide BOTH CAKEY and CACERT parameters. sub initCRL () - Initialize internal CRL parameters. ---------------------------------------------------- Initialize the module with a provided CRL. You can not generate a new CRL with this function, if you wish to do so you'll have to get a new instance of the class (see the new() function). Accepted parameters are: CRL - Provided CRL(*); INFILE - A CRL file (one of CRL/INFILE params is required)(*); FORMAT - Provided CRL format (PEM|DER)(*); (*) - Optional Parameters; EXAMPLE: if( not $self->{crl}->initCRL(CRL=>$derCRL, FORMAT=>DER)) { print "Error!"; } sub getParsed () - Retrieve parsed CRL list ------------------------------------------- This function returns an HASH structure with the main CRL data and a list of HASH with SERIAL and DATE of revoked certificates. Returned value is: my $ret = { VERSION=>$version, ALGORITHM=>$alg, ISSUER=>$issuer, LAST_UPDATE=>$last, NEXT_UPDATE=>$next, LIST=>[ @list ] }; Each element of the LIST has the following format: my $element = { SERIAL=>$certSerial, DATE=>$revDate }; EXAMPLE: print "VERSION: " . $self->{crl}->getParsed()->{VERSION}; foreach $rev ( @{ $self->{crl}->getParsed()->{LIST} } ) { print "SERIAL: " . $rev->{SERIAL} . "\n"; print "DATE: " . $rev->{DATE} . "\n"; } sub getPEM () - Get the CRL in a PEM format. -------------------------------------------- This function accept no arguments and returns the CRL in PEM format. EXAMPLE: $pem = $crl->getPEM(); sub getDER () - Get the CRL in a DER format. -------------------------------------------- This function accept no arguments and returns the CRL in DER format. EXAMPLE: $der = $crl->getDER(); sub getTXT () - Get the CRL in a TXT format. -------------------------------------------- This function accept no arguments and returns the CRL in TXT format. EXAMPLE: print $crl->getTXT(); AUTHOR ====== Massimiliano Pala SEE ALSO ======== OpenCA::X509, OpenCA::Tools, OpenCA::OpenSSL, OpenCA::REQ, OpenCA::TRIStateCGI, OpenCA::Configuration  File: pm.info, Node: OpenCA/CRR, Next: OpenCA/Configuration, Prev: OpenCA/CRL, Up: Module List Perl extention to handle CRR objects. ************************************* NAME ==== OpenCA::CRR - Perl extention to handle CRR objects. SYNOPSIS ======== use OpenCA::CRR; DESCRIPTION =========== This class handles CRR (Certificate Revoking Request) objects. Them can be signed or not depending on the implementation. CRR objects begin and end with boundaries: -----BEGIN CRR----- -----END CRR----- Currently implemented functions are: new - Creates a new instance of the class. getParsed - Returns a parsed version of the object. getSignature - Returns the signature (if present). getBody - Get Signed Text (boundaries included). getCRR - Returns passed CRR (sig. incl.). FUNCTIONS ========= sub new () - Creates a new instance of the class. ------------------------------------------------- This function creates a new instance of the class. You have to provide a valid CRR data as argument. EXAMPLE: my $CRR = new OpenCA::CRR( $crrData ); sub getParsed () - Returns a parsed CRR. ---------------------------------------- This function returns a parsed CRR as an HASH object. The returned object has the following structure: my $ret = { SUBMIT_DATE => $date, BODY => $body, SIGNATURE => $signature, CERTIFICATE_DN => $dn, CERTIFICATE_NOT_BEFORE => $notbefore, CERTIFICATE_NOT_AFTER => $notafter, CERTIFICATE_SERIAL => $serial, CERTIFICATE_ISSUER => $issuer, }; sub getSignature() - Returns signature. --------------------------------------- Use this function to retrieve the signature. Remember the signature is intended to be PKCS7 and returned value includes boundaries. EXAMPLE: print $CRR->getSignature(); =head1 AUTHOR Massimiliano Pala SEE ALSO ======== perl(1).  File: pm.info, Node: OpenCA/Configuration, Next: OpenCA/DB, Prev: OpenCA/CRR, Up: Module List Perl extention to deal with config files. ***************************************** NAME ==== OpenCA::Configuration - Perl extention to deal with config files. SYNOPSIS ======== use OpenCA::Configuration; DESCRIPTION =========== Sorry, no documentation available yet. AUTHOR ====== Massimiliano Pala SEE ALSO ======== perl(1).  File: pm.info, Node: OpenCA/DB, Next: OpenCA/OpenSSL, Prev: OpenCA/Configuration, Up: Module List Perl Certificates DB Extention. ******************************* NAME ==== OpenCA::DB - Perl Certificates DB Extention. SYNOPSIS ======== use OpenCA::DB; DESCRIPTION =========== Sorry, no documentation available at the moment. Please take a look at the prova.pl program you find in main directory of the package. Here there is a list of the current available functions. Where there is (*) mark, the function is to be considered private and not public. new {}; build a new DB object; deleteData (*) {}; delete data on a DBM file; saveData (*) {}; save data on a DBM file; getData (*) {}; retrieve data from a DBM file; getIndex {}; retriexe the IDX from a DBM file; getHash (*) {}; get data and put it into hash format (used for header extra info retrivial); saveIndex {}; save the IDX to a DBM file; saveHash (*) {}; save an HASH to a DBM file (in a single key); hash2txt (*) {}; convert an HASH to a txt (VAR=VAL); txt2hash (*) {}; convert a TEXT to an HASH (VAR=VAL); deleteRecord (*) {}; delete an entry from the DB (and corresponding search dB); addRecord (*) {}; add a record to a DB (and corresponding search dB); updateRecord (*) {}; update a dB record; initDB {}; initialize the dB structure; createDB (*) {}; create and initialize the dBs; getReferences {}; getBaseType {}; get Base datatye given a generic one ( i.e. from PENDING_ REQUEST to REQUEST); getSearchAttributes (*) {}; get a list of attributes for the search facility; storeItem {}; store a given object (OpenCA::XXXX); getItem {}; retrieve an object given the serial number; getNextItem {}; get next object (or serial) given a serial; getPrevItem {}; deleteItem {}; elements {}; returns number of elements of a given DATATYPE; rows {}; return number of elements matching a serach; searchItem {}; returns objects/serials matching the search on generic datatypes (i.e. CERTIFICATE, REQUEST); searchItemDB (*) {}; returns objects/serials matching the search on exact datatypes (i.e. VALID_CERTIFICATE, PENDING_REQUEST); searchDB {}; to be removed; getElement {}; to be removed; matches {}; to be removed; byKey { $a->{KEY} <=> $b->{KEY} }; to be removed; getTimeString {}; not currently used; toHex (*) {}; convert a decimal to an hex; AUTHOR ====== Massimiliano Pala SEE ALSO ======== OpenCA::OpenSSL, OpenCA::X509, OpenCA::CRL, OpenCA::REQ, OpenCA::TRIStateCGI, OpenCA::Configuration, OpenCA::Tools  File: pm.info, Node: OpenCA/OpenSSL, Next: OpenCA/PKCS7, Prev: OpenCA/DB, Up: Module List Perl Crypto Extention to OpenSSL ******************************** NAME ==== OpenCA::OpenSSL - Perl Crypto Extention to OpenSSL SYNOPSIS ======== use OpenCA::OpenSSL; DESCRIPTION =========== This Perl Module implements an interface to the openssl backend program. It actually uses the openssl command and it is not fully integrated as PERL/C mixture. Passing parameters to functions should be very simple as them have no particular order and have, often, self-explaining name. Each parameter should be passed to the function like this: ... ( NAME=>VALUE, NAME=>VALUE, ... ); FUNCTIONS ========= sub new () - Creates a new Class instance. ------------------------------------------ This functions creates a new instance of the class. It accepts only one parameter: the path to the backend command (openssl). This is due because if it cannot find the openssl command it will return an uninitialized class (default value is /usr/bin/ openssl which may not fit many distributions/OSs) EXAMPLE: my $openssl->new OpenCA::OpenSSL( $path ); sub setParams () - Set internal module variables. ------------------------------------------------- This function can handle the internal module data such as the backend path or the tmp dir. Accepted parameters are: SHELL - Path to the openssl command. CONFIG - Path to the openssl config file. TMPDIR - Temporary files directory. STDERR - Where to redirect the STDERR file. (*) - Optional parameters; EXAMPLE: $openssl->setParams( SHELL=>'/usr/local/ssl/bin/openssl', CONFIG=>$ca/stuff/openssl.cnf, TMPDIR=>'/tmp', STDERR=>'/dev/null' ); sub genKey () - Generate a private Key. --------------------------------------- This functions let you generate a new private key. Accepted parameters are: BITS - key lengh in bits(*); OUTFILE - Output file name(*); ALGORITHM - Encryption Algorithm to be used(*); PASSWD - Password to be used when encrypting(*); (*) - Optional parameters; EXAMPLE: my $key = $openssl->genKey( BITS=>1024 ); sub genReq () - Generate a new Request. --------------------------------------- This function generate a new certificate request. Accepted parameters are: OUTFILE - Output file(*); KEYFILE - File containing the key; PASSWD - Password to decript key (if needed) (*); DN - Subject list (as required by openssl, see the openssl.cnf doc on policy); (*) - Optional parameters; EXAMPLE: my $req = $openssl->genReq( KEYFILE=>"00_key.pem", DN => [ "madwolf@openca.org","Max","","","" ] ); sub genCert () - Generate a certificate from a request. ------------------------------------------------------- This function let you generate a new certificate starting from the request file. It is used for self-signed certificate as it simply converts the request into a x509 structure. Accepted parameters are: OUTFILE - Output file(*); KEYFILE - File containing the private key; REQFILE - Request File; PASSWD - Password to decrypt private key(*); DAYS - Validity days(*); (*) - Optional parameters; EXAMPLE: $cert = $openssl->genCert( KEYFILE=>"priv_key.pem", REQFILE=>"req.pem", DAYS=>"720" ); sub dataConvert () - Convert data to different format. ------------------------------------------------------ This functions will convert data you pass to another format. Ir requires you to provide with the data's type and IN/OUT format. Accepted parameters are: DATA - Data to be processed; INFILE - Data file to be processed (one of DATA and INFILE are required and exclusive); DATATYPE - Data type ( CRL | CERTIFICATE | REQUEST ); OUTFORM - Output format (PEM|DER|NET|TXT)(*); INFORM - Input format (PEM|DER|NET|TXT)(*); OUTFILE - Output file(*); (*) - Optional parameters; EXAMPLE: print $openssl->dataConvert( INFILE=>"crl.pem", OUTFORM=>"TXT" ); sub issueCert () - Issue a certificate. ---------------------------------------- This function should be used when you have a CA certificate and a request (either DER|PEM|SPKAC) and want to issue the certificate. Parameters used will override the configuration values (remember to set to appropriate value the CONFIG with the setParams func). Accepted parameters are: REQDATA - Request; REQFILE - File containing the request (one of REQDATA and REQFILE are required); INFORM - Input format (PEM|DER|NET|SPKAC)(*); PRESERVE_DN - Preserve DN order (Y|N)(*); CA_NAME - CA sub section to be used (take a look at the OpenSSL docs for adding support of multiple CAs to the conf file)(*); CAKEY - CA key file; CACERT - CA certificate file; DAYS - Days the certificate will be valid(*); START_DATE - Starting validity date (YYMMDDHHMMSSZ)(*); END_DATE - Ending validity date (YYMMDDHHMMSSZ)(*); PASSWD - Password to decrypt priv. CA key(*); EXTS - Extentions to be used (configuration section of the openssl.cnf file)(*); REQTYPE - Request type (NETSCAPE|MSIE)(*); (*) - Optional parameters; EXAMPLE: $openssl->issueCert( REQFILE=>"myreq", INFORM=>SPKAC, PRESERVE_DN=>Y, CAKEY=>$ca/private/cakey.pem, CACERT=>$ca/cacert.pem, PASSWD=>$passwd, REQTYPE=>NETSCAPE ); sub revoke () - Revoke a certificate. ------------------------------------- This function is used to revoke a certificate. Accepted parameters are: CAKEY - CA private key file(*); CACERT - CA certificate file(*); PASSWD - Password to decrypt priv. CA key(*); INFILE - Input PEM formatted certificate filename(*); (*) - Optional parameters; EXAMPLE: if( not $openssl->revoke( INFILE=>$certFile ) ) { print "Error while revoking certificate!"; } sub issueCrl () - Issue a CRL. ------------------------------ This function is used to issue a CRL. Accepted parameters are: CAKEY - CA private key file; CACERT - CA certificate file; PASSWD - Password to decrypt priv. CA key(*); DAYS - Days the CRL will be valid for(*); EXTS - Extentions to be added ( see the openssl.cnf pages for more help on this )(*); OUTFILE - Output file(*); OUTFORM - Output format (PEM|DER|NET|TXT)(*); (*) - Optional parameters; EXAMPLE: print $openssl->issueCrl( CAKEY=>"$ca/private/cakey.pem", CACERT=>"$ca/cacert.pem", DAYS=>7, OUTFORM=>TXT ); sub SPKAC () - Get SPKAC infos. ------------------------------- This function returns a text containing all major info about an spkac structure. Accepted parameters are: SPKAC - spkac data ( SPKAC = .... ) (*); INFILE - An spkac request file (*); OUTFILE - Output file (*); (*) - Optional parameters; EXAMPLE: print $openssl->SPKAC( SPKAC=>$data, OUTFILE=>$target ); sub getDigest () - Get a message digest. ---------------------------------------- This function returns a message digest. Default digest algorithm used is MD5. Accepted parameters are: DATA - Data on which to perform digest; ALGORITHM - Algorithm to be used(*); (*) - Optional parameters; EXAMPLE: print $openssl->getDigest( DATA=>$data, ALGORITHM=>sha1); AUTHOR ====== Massimiliano Pala SEE ALSO ======== OpenCA::X509, OpenCA::CRL, OpenCA::REQ, OpenCA::TRIStateCGI, OpenCA::Configuration  File: pm.info, Node: OpenCA/PKCS7, Next: OpenCA/REQ, Prev: OpenCA/OpenSSL, Up: Module List Perl extension for basic handling PKCS#7 Signatures. **************************************************** NAME ==== OpenCA::PKCS7 - Perl extension for basic handling PKCS#7 Signatures. SYNOPSIS ======== use OpenCA::PKCS7; DESCRIPTION =========== This module contains all functions needed for handling PKCS#7 signatures. It requires some parameters to be passed such as a reference to a OpenCA::OpenSSL instance. This module provides an interface to PKCS#7 structures, no specific crypto functions are performed (see the OpenCA::OpenSSL module for this). FUNCTIONS ========= sub new () - Create a new instance of the Class. ------------------------------------------------ This function creates an instance of the module. If you provide a certificate it will be parsed and stored in local variable(s) for later usage. The function will return a blessed reference. Accepted parameters are: SHELL - Reference to an initialized OpenCA::OpenSSL instance; INFILE - Signature File; SIGNATURE - Signature Data; DATAFILE - Data File(*); CA_CERT - CA Certificate File to check chain Depth ( >0 )(*); CA_DIR - CA Certificates directory to check chain Depth ( >0 ); (*) - Optional parameter. EXAMPLE: $x509 = new OpenCA::PKCS#7( SHELL=>$crypto, INFILE=>"TEXT.sig", DATA=>"TEXT", CACERT=>"/OpenCA/cacert.pem"); sub getSigner () - Get basic Signer Infos. ------------------------------------------ sub verifyChain () - Get and Verify basic signer Infos (CAcert needed). ----------------------------------------------------------------------- AUTHOR ====== Massimiliano Pala SEE ALSO ======== OpenCA::OpenSSL, OpenCA::CRL, OpenCA::REQ, OpenCA::X509  File: pm.info, Node: OpenCA/REQ, Next: OpenCA/TRIStateCGI, Prev: OpenCA/PKCS7, Up: Module List Perl extension to easily manage Cert REQUESTs ********************************************* NAME ==== OpenCA::REQ - Perl extension to easily manage Cert REQUESTs SYNOPSIS ======== use OpenCA::REQ; DESCRIPTION =========== Sorry, no help available. The REQ module is capable of importing request like this: -----BEGIN HEADER----- VAR = NAME VAR = NAME ... -----END HEADER----- (real request text here) -----BEGIN PKCS7----- (pkcs#7 signature here -----END PKCS7----- The Real request text can be a request in every form ( DER|PEM ) or textual (called SPKAC|RENEW|REVOKE datatype). The syntax of the latters is VAR = NAME on each line (just like the HEADER section). AUTHOR ====== Massimiliano Pala SEE ALSO ======== OpenCA::OpenSSL, OpenCA::X509, OpenCA::CRL, OpenCA::Configuration, OpenCA::TRIStateCGI, OpenCA::Tools  File: pm.info, Node: OpenCA/TRIStateCGI, Next: OpenCA/Tools, Prev: OpenCA/REQ, Up: Module List Perl extension for implementing 3-state Input Objs. *************************************************** NAME ==== OpenCA::TRIStateCGI - Perl extension for implementing 3-state Input Objs. SYNOPSIS ======== use OpenCA::TRIStateCGI; DESCRIPTION =========== Sorry, no description available. Currently implemented methods derives mostly from the CGI.pm module, please take a look at that docs. Added methods are: status - newInput - newInputCheck - checkForm - startTable - addTableLine - endTable - printCopyMsg - printError - Deprecated methods (better use the OpenCA::Tools corresponding methods instead) are: subVar - getFile - AUTHOR ====== Massimiliano Pala (madwolf@openca.org) SEE ALSO ======== CGI.pm, OpenCA::Configuration, OpenCA::OpenSSL, OpenCA::X509, OpenCA::CRL, OpenCA::REQ, OpenCA::CRR, OpenCA::Tools  File: pm.info, Node: OpenCA/Tools, Next: OpenCA/X509, Prev: OpenCA/TRIStateCGI, Up: Module List Misc Utilities PERL Extention. ****************************** NAME ==== OpenCA::Tools - Misc Utilities PERL Extention. SYNOPSIS ======== use OpenCA::Tools; DESCRIPTION =========== This module provides some tools to easy some standard actions. Current functions description follows: new - Returns a reference to the object. getDate - Returns a Printable date string. copyFiles - Copy file(s). moveFiles - Move file(s). deleteFiles - Delete file(s). cmpDate - Compare two Printable date sting. isInsidePeriod - Check wether give date is within given period. parseDN - Parse a given DN returning an HASH value. FUNCTIONS ========= sub new () - Build new instance of the class. --------------------------------------------- This function returns a new instance of the class. No parameters needed. EXAMPLE: my $tools = new OpenCA::Tools(); sub getDate () - Get a Printable date string. --------------------------------------------- Returns a string representing current time (GMT or Local). Accepted parameters are: FORMAT - Use it to get local or GMT time. Defaults to GMT. EXAMPLE: print $tools->getDate(); sub copyFiles () - Copy file(s). -------------------------------- Use this function to copy file(s). Source path can contain wildcards (i.e. '*') that will be expanded when copying. Accepted parameters are: SRC - Source full path. DEST - Destination path. EXAMPLE: $tools->copyFiles( SRC=>"test.pl", DEST=>"/tmp" ); sub moveFiles () - Move file(s). -------------------------------- Use this function to move file(s). Source path can contain wildcards (i.e. '*') that will be expanded when copying. Accepted parameters are: SRC - Source full path. DEST - Destination path. EXAMPLE: $tools->moveFiles( SRC=>"test.pl", DEST=>"/tmp" ); sub deleteFiles () - Delete file(s). ------------------------------------ Use this function to delete file(s) once provided target directory and filter. Accepted parameters are: DIR - Directory containing file(s) to delete. FILTER - File filtering(*). (*) - Optional parameters; EXAMPLE: $tools->deleteFiles( DIR=>"/tmp", FILTER=>"prova.p*" ); sub cmpDate () - Compare two date strings. ------------------------------------------ Use this function to get informations on relationship between the two provided date strings. Returns integer values like strcmp() do in C, so if DATE_1 'is later' than DATE_2 it returns a positive value. A negative value is returned in the countrart case while 0 is returned if the two dates are equal. Accepted parameters: DATE_1 - First date string. DATE_2 - Second date string. EXAMPLE: $tools->cmpDate( DATA_1=>"$date1", DATA_2=>"$date2" ); sub isInsidePerios - Check if date is inside a given period. ------------------------------------------------------------ This functions returns a true (1) value if the provided date is within a given period. Accepted parameters are: DATE - Date string to check. START - Date string indicating period's starting(*). END - Date string indicating period's ending(*). (*) - Optional parameters; if( not $tools->isInsidePeriod( DATE=>$d1, START=>$d2, END=>$d3 ) ) { print "Non in period... \n"; } sub parseDN () - Parse a given DN. ---------------------------------- This function parses a given DN string and returns an HASH value. Returned structure is as following: KEY => VALUE, Only the OU key is instead a list: OU => [ @list ] EXAMPLE: $parsed = $tools->parseDN( $dn ); print $parsed->{CN}; foreach $tmp ( @{ $parsed->{OU} } ) { print "OU=$tmp\n"; } AUTHOR ====== Massimiliano Pala SEE ALSO ======== OpenCA::Configuration, OpenCA::TRIStateCGI, OpenCA::X509, OpenCA::CRL, OpenCA::REQ, OpenCA::OpenSSL, perl(1).  File: pm.info, Node: OpenCA/X509, Next: OpenInteract, Prev: OpenCA/Tools, Up: Module List Perl extension for basic handling x509 Certificates. **************************************************** NAME ==== OpenCA::X509 - Perl extension for basic handling x509 Certificates. SYNOPSIS ======== use OpenCA::X509; DESCRIPTION =========== This module contains all functions needed for handling of X509 certificates. It requires some parameters to be passed such as a reference to a OpenCA::OpenSSL instance. This module provides an interface to X509 structures, no specific crypto functions are performed (see the OpenCA::OpenSSL module for this). When not said different, default operational format is PEM. FUNCTIONS ========= sub new () - Create a new instance of the Class. ------------------------------------------------ This function creates an instance of the module. If you provide a certificate it will be parsed and stored in local variable(s) for later usage. The function will return a blessed reference. Accepted parameters are: SHELL - Reference to an initialized OpenCA::OpenSSL instance; CERTIFICATE - Certificate to stored in structure(*); INFILE - Certificate file(*); FORMAT - Format of the provided certificate, one of PEM|DER|NET(*); (*) - Optional parameter. EXAMPLE: $x509 = new OpenCA::X509( SHELL=>$crypto, CERTIFICATE=>$self->{cert}); sub initCert () - Use a new certificate. ---------------------------------------- You can use a new certificate without having to get a new module reference. Accepted parameters are: CERTIFICATE - Certificate data to be stored; FORMAT - Provided certificate's format, one of PEM|DER|NET(*); EXAMPLE: if( not $x509->initCert( CERTIFICATE=>$self->{cert} ) ) { print "Error in storing certificate!"; } sub getParsed () - Get an hash structure from certificate --------------------------------------------------------- By calling this function you can retrieve a reference to the parsed certificate (PERL hash). This structure will include, for example: $ret->{SERIAL} ## Serial Number $ret->{DN} ## Subject DN $ret->{EMAIL} ## Subject e-mail $ret->{CN} ## Subject CN $ret->{OU} ## Subject OU (list) $ret->{O} ## Subject Organization $ret->{C} ## Subject Country $ret->{ISSUER} ## Issuer DN $ret->{NOT_BEFORE} ## Not Before Date $ret->{NOT_AFTER} ## Not After Date (Expiration) $ret->{PK_ALGORITHM} ## Algorithm used (RSA,DSA,..) $ret->{MODULUS} ## Modulus (Size in bits) $ret->{EXPONENT} ## Exponent EXAMPLE: my $self->{parsedItem} = $x509->parseCertificate(); print $self->{parsedItem}->{SERIAL}; foreach $ou ( @{ $self->{parsedItem}->{OU} } ) { print "OU=$ou, "; } sub status () - Get certificate status -------------------------------------- Get certificate status using provided OpenCA::CRL initialized reference as argument. Returned status can be Valid, Revoked, Expired and Unknown. Accepted arguments: CRL - Crl to check certificate status; The returned structure is: $status->{STATUS}; $status->{REVOKATION_DATE}; $status->{EXPIRATION_DATE}; EXAMPLE: my $status = $x509->status( CRL=>$crl ); print $status->{STATUS}; sub getPEM () - Get certificate in PEM format. ---------------------------------------------- Get certificate in PEM format. EXAMPLE: $pem = $x509->getPEM(); sub getDER () - Get certificate in DER format. ---------------------------------------------- Get certificate in DER format. EXAMPLE: $der = $x509->getDER(); sub getTXT () - Get certificate in TXT format. ---------------------------------------------- Get certificate in TXT format. EXAMPLE: $der = $x509->getTXT(); AUTHOR ====== Massimiliano Pala SEE ALSO ======== OpenCA::OpenSSL, OpenCA::CRL, OpenCA::REQ, OpenCA::X509  File: pm.info, Node: OpenInteract, Next: OpenInteract/ApacheStartup, Prev: OpenCA/X509, Up: Module List A robust web application framework built to run under Apache and mod_perl ************************************************************************* NAME ==== OpenInteract - A robust web application framework built to run under Apache and mod_perl DESCRIPTION =========== OpenInteract is an extensible application server using Apache and mod_perl built for developers but also to be manageable almost entirely via the web browser. It includes: * A robust system of components built on templates that can access your data just about any way that you can think of. * A very flexible separation of presentation and data access: you can use one template for accessing data from different sources using one template (e.g., a listing of users from the system, from an LDAP server, from an NT/SMB authentication controller, etc.) or you can use one set of data to fill multiple templates. * A consistent security mechanism allowing you to control security for users and groups not only at the task level, but also at the individual data object level. * A simple user and group-management system that allows users to create their own accounts and an administrator to assign them to one or more groups. * A convenient packaging system that makes it simple for developers to distribute code, configuration and all other information necessary for an application. It also makes the installation and upgrading processes very straightforward and simple. * An integrated, database-independent method for distributing data necessary for a package. You should be able to install any package on any database that's been tested with OpenInteract. (Some of this work must be done by the package authors, but OpenInteract tries to make this as painless as possible.) Dependencies ------------ OpenInteract uses a number of CPAN modules, relying heavily on the following required modules: *SPOPS* (Simple Perl Object Persistence with Security). This module was developed in tandem with this framework but stands on its own as a full-featured object serialization system. It also implements security. *Template Toolkit*. This is the best templating environment available for Perl. Version 2 has major performance improvements and also includes usability enhancements. It's also required by OI. *Apache::Session*. Provide datasource-independent means of session management. Many others are also used - why reinvent the wheel when there are so many other well-built ones already around around and so many interesting problems to conquer? OpenInteract is usable *right now*, out of the box. That doesn't mean we're sitting on our laurels - we're working on a number of different features to OpenInteract which will be added soon to the 'TODO' file found in the OpenInteract source directory. INSTALLATION ============ A file 'INSTALL' is included with the OpenInteract distribution. It shows you the simple steps needed for installation. If you ask this question on a mailing list (below), someone will likely post: 1. Read and follow the directions in INSTALL. 2. Read and follow the directions in INSTALL. 3. Return to step (1). DOCUMENTATION ============= OpenInteract comes with a few forms of documentation: * *System-wide*: These files are in HTML format and are geared for people first learning about OpenInteract, whether from a content-management view, developer view or administration view. You can find them in the `doc/' directory of the source distribution - open up the `index.html' file for a table of contents. The files are also installed with every website. Once you have the website up and running, go to: http://mywebsite.com/SystemDoc/ And click on *View OpenInteract Documentation*. * Package: These files come in the `doc/' subdirectory of every package and give you some idea of what the package does and how you can do it. Some packages (like base) come with documentation that describe integral system functionality. To view the package documentation, go to: http://mywebsite.com/SystemDoc/ And click on *View Package Documentation*. This lists the packages currently installed and the available documentation for each. Note that package documentation is somewhat lacking right now, but we're in the process of fixing this. In the meantime, check out the Module documentation below. * Module: Normal Perl documentation can/should be found in the modules that actually do the work. Since OpenInteract uses its own packaging system you won't be able to find them via perldoc as usual. (You could circumvent this by putting the package directory in the base installation in PERL5LIB, but this isn't recommended.) Instead, you can use the browser interface and go to: http://mywebsite.com/SystemDoc/ And choose *View SPOPS/OpenInteract Module Documentation*. This gives you a web interface to view the modules (And yes, it looks fine through lynx.) Similarly, you can click on *View Perl Module Documentation* and see all the other Perl modules used by OpenInteract. Click on the module name and you'll be able to see the docs online. This is especially helpful for the *Template Toolkit*, which comes with a huge amount of documentation. FEEDBACK ======== We're interested in your feedback on a number of topics. In particular: * How did you find the installation process? Was OpenInteract simple to install and configure? * How easy was it for you to create a website, install its SQL structures and data and import its templates? * Which documentation do you feel is lacking? As you might tell, we're keenly aware that installation and initial understanding can be a big barrier to entry with a fairly substantial application like this. Feedback is crucial for us to plug the holes. We also hope to extend certain features (such as users and groups) to different types of data sources, like LDAP directories. Other applications of OpenInteract really depend on what you'd like it to do! Updates can be found in two places: CVS access, mailing list information and archives, bug tracking. http://sourceforge.net/projects/openinteract/ Latest news, package repository, everything else. http://www.openinteract.org/ REVISION ======== This document is for version *1.06* of OpenInteract. CONTACT ======= Thanks for trying out OpenInteract! If you have any questions, comments, thoughts, diatribes, check out the various OpenInteract mailing lists, hosted at SourceForge at the above URL. COPYRIGHT ========= OpenInteract is Copyright (c) 2001 intes.net, inc.. All rights reserved. The OpenInteract library(**) is free software; you can redistribute it and/or modify it under the terms of the Perl Artistic License or the GNU General Public License as published by the Free Software Foundation; either version 2 of the License (see the file COPYING in the source distribution), or (at your option) any later version. **"OpenInteract library" includes the core 'OpenInteract::' files: * OpenInteract::ApacheStartup * OpenInteract::Config * OpenInteract::Config::PerlFile * OpenInteract::DBI * OpenInteract::Error * OpenInteract::Package * OpenInteract::PackageRepository * OpenInteract::Request * OpenInteract::SPOPS * OpenInteract::SQLInstall * OpenInteract::Startup Along with the core packages: * base * base_box * base_component * base_error * base_group * base_security * base_system_documentation * base_template * base_theme * base_user * static_page And the following application packages: * classified * full_text * news Every other package, whether developed by intes.net, inc. or other party, is licensed under its own terms.  File: pm.info, Node: OpenInteract/ApacheStartup, Next: OpenInteract/Config, Prev: OpenInteract, Up: Module List Central module to call for initializing an OpenInteract website *************************************************************** NAME ==== OpenInteract::ApacheStartup - Central module to call for initializing an OpenInteract website SYNOPSIS ======== # In an website's startup.pl file: #!/usr/bin/perl use strict; use OpenInteract::ApacheStartup; my $BASE_CONFIG = '/home/httpd/demo.openinteract.org/conf/base.conf'; OpenInteract::ApacheStartup->initialize( $BASE_CONFIG ); 1; DESCRIPTION =========== `OpenInteract::ApacheStartup' should be run from the startup.pl file of your website. (You can probably also load it directly from your apache config as well, but we will stick with simple things for now :) Its purpose is to load as many modules as possible into the parent mod_perl process so we can share lots of memory. Sharing is good! Most of the actual work is done in the `OpenInteract::Startup' module, so you might want to check the documentation for that if you are curious how this works. METHODS ======= *initialize( $config_file )* Your `startup.pl' file should have a definition for a configuration file and pass it to this method, which is the only one the module contains. TO DO ===== BUGS ==== SEE ALSO ======== *Configuration Guide to OpenInteract*, `mod_perl' in this node COPYRIGHT ========= Copyright (c) 2001 intes.net, inc.. All rights reserved. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. AUTHORS ======= Chris Winters  File: pm.info, Node: OpenInteract/Config, Next: OpenInteract/Config/PerlFile, Prev: OpenInteract/ApacheStartup, Up: Module List centralized configuration information ************************************* NAME ==== OpenInteract::Config - centralized configuration information SYNOPSIS ======== use OpenInteract::Config; my $config = OpenInteract::Config->new(); $config->read_file( '/path/to/dbi-config.info' ); $config->set( 'debugging', 1 ); my $dbh = DBI->connect( $config->db_dsn(), $config->db_username() ), $config->db_password() ), { RaiseError => 1 } ); if ( my $debug = $config->get( 'debugging' ) ) { print $LOG "Trace level $debug: fetching user $user_id..."; if ( $self->fetch( $user_id ) ) { print $LOG "successful fetching $user_id\n"; } else { print $LOG "cannot retrieve $user_id. Error info: ", $self->error()->pop_error(); } } DESCRIPTION =========== Allows you to embed a configuration object that responds to get/set requests. Different from just using key/value pairs within your object since you do not have to worry about writing get/set methods, cluttering up your AUTOLOAD routine, or things like that. It also allows us to create configuration objects per module, or even per module instance, as well as create one for the entire program/project by putting it in the always-accessible Request object. Very simple interface and idea: information held in key/value pairs. You can either retrieve the information using the get() method or by calling the key name method on the config object. For instance, to retrieve the information related to DBI, you could do: my ( $dsn, $uid, $pass ) = ( $config->db_dsn(), $config->db_username(), $config->db_password() ); or you could do: my ( $dsn, $uid, $pass ) = $config->get( 'db_dsn', 'db_username', 'db_password' ); Setting values is similarly done: my $font_face = $config->font_face( 'Arial, Helvetica' ); or: my $font_face = $config->set( font_face => 'Arial, Helvetica' ); Note that you might want to use the get/set method calls more frequently for the sake of clarity. METHODS ------- A description of each method follows: *new( %params )* Parameters: Unknown. Depends on what is being configured. Create the Config object. Just bless an anonymous hash and stick every name/value pair passed into the method into the hash. Note: we should probably lower case all arguments passed in, but getting/setting parameters and values should only be done via the interface. So, in theory, we should not allow the user to set anything here... *flatten_action_config()* Copies information from the default action into all the other action (except the default action and those beginning with '_', which are presumably private.) Returns: an arrayref of action keys (tags) for which information was set. *AUTOLOAD( %params )* Parameters: Unknown (this is AUTOLOAD!) The first parameter, or name of the method call, is assumed to be a configration key. Call the Iset( 'base_dir', '/home/cwinters/work/cw' ); $c->set( 'html_dir', '$BASE_DIR/html' ); $c->set( 'image_dir', '$HTML_DIR/images' ); and call: $c->get_dir( 'image_dir' ); and receive: '/home/cwinters/work/cw/html/images' in return. We should probably generalize this to other types of settings, but this Config object is probably on its last legs anyway. ABSTRACT METHODS ================ These are methods meant to be overridden by subclasses, so they do not really do anything here. Useful for having a template to see what subclasses should do, however. *read_config()* Abstract method for subclasses to override with their own means of reading in config information (from DBI, file, CGI, whatever). Returns: $config_obj on success; undef on failure *save_config()* Abstract method for subclasses to override with their own means of writing config to disk/eleswhere. Returns: 1 on success; undef on failure. TODO ==== Future work should include setting configuration values permanently for future uses of the module. We could instantiate the configuration object with an argument giving it a file to read the keys/values from. A DESTROY routine could then save all changed values to the file. This would also allow us to change looks very easily... BUGS ==== *Remove Configuration Values* Need to determine a way to remove a value for a configuration item. Since we test for the existence of a value to determine if we are getting or setting, a non-existent value will simply return what is there. Not a big deal currently. See *Possible modifications* entries for both set() and *param_set()*. COPYRIGHT ========= Copyright (c) 2001 intes.net, inc.. All rights reserved. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. AUTHORS ======= Chris Winters  File: pm.info, Node: OpenInteract/Config/PerlFile, Next: OpenInteract/DBI, Prev: OpenInteract/Config, Up: Module List subclass of OpenInteract::Config for reading information from a perl file ************************************************************************* NAME ==== OpenInteract::Config::PerlFile - subclass of OpenInteract::Config for reading information from a perl file DESCRIPTION =========== Create a 'read_config' method to override the base Config method. See *OpenInteract::Config* for usage of this base object. The information in the config file is perl, so we do not have to go through any nutty contortions with types, etc. METHODS ======= *read_config( $filename )* Read configuration directives from $filename. The configuration directives are actually perl data structures saved in an evalable format using Data::Dumper. *save_config( $filename )* Saves the current configuration to $filename. Normally not needed since you are not always changing configurations left and right. TO DO ===== BUGS ==== COPYRIGHT ========= Copyright (c) 2001 intes.net, inc.. All rights reserved. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. AUTHORS ======= Chris Winters  File: pm.info, Node: OpenInteract/DBI, Next: OpenInteract/Error, Prev: OpenInteract/Config/PerlFile, Up: Module List Centralized connection location to DBI databases ************************************************ NAME ==== OpenInteract::DBIConnect - Centralized connection location to DBI databases SYNOPSIS ======== # Just get a database handle from the info in your config # (conf/server.perl) my $db = OpenInteract::DBI->connect({ $CONFIG->{db_info} }); DESCRIPTION =========== No, we do not subclass DBI with this. No, we do not override any of the DBI methods. Instead, we provide the means to connect to the database from one location along with the ability to manipulate the default connection information before we connect. For instance, you can setup OpenInteract in two separate databases. When users of a certain name login (say, 'devel'), you can change the 'db_name' key of the database connection info hashref from 'webdb' to 'webdb-devel'. Note that this should work flawlessly with Apache::DBI, and if you are using this on a different persistent Perl platform (say, PerlEx) then this module gives you a single location from which to retrieve database handles - this makes using the BEGIN/END tricks ActiveState recommends in their FAQ pretty trivial. METHODS ======= *connect( \%connnect_info, \%params )* Usage: my $db = eval { OpenInteract::DBI->connect({ $CONFIG->{db_info} }) }; if ( $@ ) { die "Cannot connect to database! Error found: $@"; } my ( $sth ); eval { $sth = $db->prepare( 'SELECT blah FROM bleh' ); $sth->execute; }; ... Returns: A DBI database handle with the following parameters set: RaiseError: 1 PrintError: 0 ChopBlanks: 1 AutoCommit: 1 (for now...) The first parameter is a hashref of connection information. This should include: * dsn: the last part of a fully-formed DBI data source name used to connect to this database. Examples: Full DBI DSN: DBI:mysql:webdb OpenInteract DSN: webdb Full DBI DSN: DBI:Sybase:server=SYBASE;database=web OpenInteract DSN: server=SYBASE;database=web So the OpenInteract DSN string only includes the database-specific items for DBI, the third entry in the colon-separated string.This third item is generally separated by semicolons and usually specifies a database name, hostname, packet size, protocol version, etc. See your DBD driver for what to do. * *db_name*: the name of your database * username: what username should we use to login to this database? * password: what password should we use in combination with the username to login to this database? * *driver_name*: what DBD driver is used to connect to your database? (Examples: 'Sybase', 'mysql', 'Oracle') * *db_owner*: (optional) who owns this database? The second parameter is also a hashref and can contain the following keys: * *pre_connect*: the coderef stored here is called before the database handle is requested, allowing you to modify any of the information in the first parameter before it is sent to DBI. Takes the hashref of database connection info as its first parameter, and it must return a hashref of database connection info with the same conventions as the one passed in. Failure to do so means the changes are discarded. * *post_connect*: the coderef stored here is called after the database handle is requested and allows you to perform whatever actions on it that you like. Takes the hashref of database connection info as its first parameter and the newly created database handle as its second parameter. There currently is no return value for this callback - primarily because I am not sure what it might be used for :-) Suggestions welcome! Any errors encountered will result in an exception thrown via die. Generally, there will be two errors: * *Connect error*: This means you cannot even connect to the database. This is generally a very serious error. You can distinguish this by doing a match on the returned error string for `/^Connect failed:/'. Everything after this string is the actual error reported by DBI. * *Use database error*: This means you connected to the database server, but were not able to 'use' your database. (If your database does not support the 'use' command, please contact the author.) You can find this error by matching the returned error string on `/^Use database failed: /'. Everything after this string is the actual error reported by DBI. Other errors may occur in your callbacks, but reporting them is entirely up to you. This class does not wrap the call in an `eval {}' block so you can capture the error and inspect it yourself. After all, they *are* your callbacks. STRATEGIES ========== Under mod_perl, you can use the simple connection-pooling module *Note Apache/DBI: Apache/DBI,. This module is quite simple - it overrides the connect call for `DBI' in this node. For each connect call made, it looks at the parameters (dsn, username, password and the DBI parameters) to determine whether it has connected to this database previously. If so, it returns the cached connection. If not, it creates the connection and caches it. This happens on a per-httpd-child basis, so if you have 10 httpd children you will have 10 concurrent connections to the database. Easy, right? What happens if you are running multiple websites using one httpd child? Say you have five websites running on mod_perl process group which has the aforementioned 10 children. Since each website likely has its own database, you will eventually have `10 x 5 = 50' connections to your database. This can be a bad thing. To get around this, and assuming that all of these websites connect to the database as the same user (which certainly is not a given), OpenInteract allows you to specify a single database for connection. Once the connection is handed out, OpenInteract will perform the SQL 'use' command to switch to the correct database. The trigger for this is the 'db_name' key of the first parameter passed into the connect method of this class. If this field is specified, the method will perform the following statement: $dbh->do( "use $db_info->{db_name}" ); So that you only have to keep one connection for this database open all the time. TO DO ===== *Test with PerlEx* Try to use the BEGIN/END tricks ActiveState recommends - do they work with just scripts, or also with modules? BUGS ==== SEE ALSO ======== *Note Apache/DBI: Apache/DBI, `DBI' in this node - http://www.symbolstone.org/technology/perl/DBI PerlEx - http://www.activestate.com/Products/PerlEx/index.html COPYRIGHT ========= Copyright (c) 2001 intes.net, inc.. All rights reserved. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. AUTHORS ======= Chris Winters Marcus Baker