OpenCA::OpenSSL::SMIME.3pm

Langue: en

Autres versions - même langue

Version: 2004-01-20 (mandriva - 01/05/08)

Section: 3 (Bibliothèques de fonctions)

Sommaire

NAME

OpenCA::OpenSSL::SMIME - Sign, verify, encrypt and decrypt S/MIME

SYNOPSIS

     $shell = OpenCA::OpenSSL->new();
     $smime = OpenCA::OpenSSL::SMIME->new(
                  DATA => \*STDIN,
                  SHELL => $shell);
     $smime->sign(CERTIFICATE => $my_x509,
                  PRIVATE_KEY => $my_key);
     $mime = $msg->get_mime();
     $mime->smtpsend();

DESCRIPTION

A Perl module for handling S/MIME entities: encrypting, decrypting, signing and verifying. Uses MIME::Entity for easy parsing of complex structures and optionally for input and output of data.

CONSTRUCTORS


new ARGS

Creates a new OpenCA::OpenSSL::SMIME object. If invoked as a instance method, inherits the values of SHELL, CA_CERTS, TMPDIR and DEBUG from creator.

Parameters:

SHELL
A blessed reference to an OpenCA::OpenSSL object. Required argument.
INFILE
A filename containing MIME data to be processed.
DATA
An array reference, a string or a filehandle (as a reference to a glob), containing actual MIME data to be processed
ENTITY
A blessed reference to an MIME::Entity object to be processed. One of DATA or ENTITY should be present.
CA_CERTS
Optional list of certificates of CAs for signing and verifying.

Accepts a list of blessed references to OpenCA::X509 objects

TMPDIR
Sets directory to store various temporary files.
DEBUG
Sets debugging on when assigned a true value.

METHODS


set_params ARGS

Sets or resets object parameters. Takes the same arguments as new().

errno

Returns the last error in numeric form. Could be called as class method, to retrieve the last error regardless of the instance.

err

Returns the last error in literal form. Could be called as class method, to retrieve the last error regardless of the instance.

sign ARGS

Signs the message, replaces original content with signed content.

Arguments:

CERTIFICATE
Blessed reference to an OpenCA::X509 object containing the signer's certificate.
PRIVATE_KEY
The private key of the signer. Should be a string containing the textual data or a open filehandle reference.
KEY_PASSWORD
Password to decrypt the private key, if necessary.
INCLUDE_CERTS
If true, the signer's certificate and the chain of trust (if present) will be included in the message.
NO_COPY_HEADERS
If true, the original message headers won't be copied to the external envelope.
NO_STRIP_HEADERS
If true, the original message headers won't be stripped off before signing.

verify ARGS

Verifies the message for integrity and non-repudiation. Can use the embedded certificate in the message (if present) or a user-supplied expected signer.

Arguments:

USES_EMBEDDED_CERT
If true, uses the certificate included in the message, if any, instead of a user-supplied certificate for verifying.
CERTIFICATE
Blessed reference to an OpenCA::X509 object containing the user-supplied certificate for verifying.
NO_COPY_HEADERS
If true, the original message headers won't be copied to the extracted verified message.

encrypt ARGS

Encrypts the message, replaces original content with crypted content.

Arguments:

CERTIFICATE
Blessed reference to an OpenCA::X509 object containing the receiver's certificate.
NO_COPY_HEADERS
If true, the original message headers won't be copied to the external envelope.
NO_STRIP_HEADERS
If true, the original message headers won't be stripped off before encrypting.
CIPHER
Which cipher algorithm to use.

Currently supports: des3, des, rc2-40, rc2-64 and rc2-128.

decrypt ARGS

Decrypts the message, replaces it with original unencrypted data.

Arguments:

CERTIFICATE
Blessed reference to an OpenCA::X509 object containing the recipient's certificate.
PRIVATE_KEY
The private key of the recipient. Should be a string containing the textual data or a open filehandle reference.
KEY_PASSWORD
Password to decrypt the private key, if necessary.
NO_COPY_HEADERS
If true, the original message headers won't be copied to the decrypted message.

get_mime

Extracts the processed message. If called in scalar context, returns a MIME::Entity object. In list context, returns a MIME::Entity object and a filename containing the textual form of the message.

get_last_signer

Returns OpenCA::X509 object of embedded certificate from last verify operation, if it was successful and contained the signer's certificate.

Returns undef it there wasn't any certificate saved.

status

Returns status text from last verify/decrypt operation, or undef if it was successful.

status_code

Returns status code from last verify/decrypt operation, or zero if it was successful.

NOTE: when status/status_code are set, err/errno are not; and viceversa.

Currently defined status values after verifying:

   1100  message not signed
   1110  invalid certificate chain
   1111  no chain of trust supplied
   1112  certificate has expired
   1113  certificate is not yet valid
   1119  unknown certificate problem

Currently defined status values after decrypting:

   1300  message not encrypted
   1301  this certificate can't decrypt this message

SEE ALSO

OpenCA::OpenSSL, OpenCA::X509, MIME::Tools, MIME::Entity

AUTHOR

Martin Ferrari <yo@martinferrari.com.ar>.

VERSION

$Revision: 1.1 $ $Date: 2004/01/20 08:00:51 $