NAME
    MacPGP.pm

SYNOPSIS
            use Mac::Apps::MacPGP;
            $object = new MacPGP;

DESCRIPTION
    MacPerl interface to MacPGP 2.6.3. Older versions WILL NOT WORK. The MIT version, MacPGP
    2.6.2, does not support nearly the number of AppleEvents as does 2.6.3. For those outside
    the U.S., you will not be able to download the program; but there are International
    versions. Perhaps in the future I will add support for those. Many of the functions should
    work fine for those, actually, but I imagine some will not.

    MacPerl 5.1.1 (released January 1997) or higher is also required because of bugs in the
    AppleEvents library in previous versions.

    Also required is the Mac::Apps::Launch module.

NOTES
    For optional parameters, MacPGP will either use the default or prompt the user. Parameters
    are required unless noted as optional. Exception: For the `$OUTP' parameter, the MacPGP
    default is binary but I set it to ASCII in the module, because I rarely use binary PGP
    files.

    Boolean parameters take a value of 1 (true) or 0 (false). Filenames should be given the full
    pathname. To leave an optional parameter empty, give it a value of `undef'. Optional
    parameters will either be given the default by MacPGP or MacPGP will prompt the user for a
    value if necessary.

    For further explanation of methods and parameters, see your MacPGP 2.6.3 user guide.

    If something seems seems to not work properly, try doing it directly from MacPGP before
    assuming it is the fault of MacPGP.pm. :-)

USAGE
  encrypt

    Encrypt. Returns encrypted text for `$TYPE="ncrd"'.

    $object->encrypt(TYPE, DOBJ, [RECV|CPAS], PASS, USID, SIGN, READ, OUTP, LATI, WRAP, ALNS,
    TABX, MDAL, WSRC, COPT);

    TYPE
    One of "encr" (encrypt files), "ncrd" (encrypt data), or "cncr" (conventional encryption).

    DOBJ
    For `$TYPE="encr"' or `"cncr"', `$DOBJ' is either a filename or a reference to an array of
    filenames. For `$TYPE="ncrd"', `$DOBJ' is the data to be encrypted. If `$DOBJ' is empty,
    MacPGP will attempt to encrypt the clipboard instead.

    RECV
    Either the name of a recipient or a reference to an array of recipients. (encr and ncrd
    only)

    CPAS
    Password used for conventional encryption. Optional. (cncr only)

    PASS
    The password. Optional.

    USID
    Name of secret key. Optional.

    SIGN
    Sign? One of "sepa" (signature in separate file), "incl", (signature included), "omit"
    (omitted, don't sign). Optional.

    READ
    Input format. One of "macb" (MacBinarize first), "text", (convert text to CRLF), "norm" (do
    nothing). Optional.

    OUTP
    Output format. One of "bina" (8-bit binary), "asci", (ASCII-armored). Optional.

    LATI
    Convert text to ISO-Latin1? Boolean. Optional.

    WRAP
    Wrap text to this many lines, between 30 and 100. 0=no wrap. Optional.

    ALNS
    For armored files, split output into files of this line length. 0=no split. Optional.

    TABX
    For wrapped files, expand tabs to this many spaces, from 0 to 9. Optional.

    MDAL
    Use "MD5 " or "SHA1" to compute message digest for file. Optional.

    WSRC
    Wipe out source file? Boolean. Optional. (encr and cncr only)

    COPT
    Self-decrypting? One of "sdf" (self-decrypting) or "sdfb", (self-decrypting and binhexed).
    Default is neither. Optional. (cncr only)

  decrypt

    Decrypt. Returns decrypted text for `$TYPE="dcrd"' and `$DOBJ ne undef'. Returns signatures
    for `$TYPE="decr"'.

    $object->decrypt(TYPE, DOBJ, PASS, SCRE, NSIG, APL2, RECV);

    TYPE
    One of "decr" (decrypt files), "dcrd" (decrypt data).

    DOBJ
    For `$TYPE="decr"', `$DOBJ' is either a filename or a reference to an array of filenames.
    For `$TYPE="dcrd"', `$DOBJ' is the data to be decrypted. If `$DOBJ' is empty, MacPGP will
    attempt to decrypt the clipboard instead. To get signatures from "dcrd" event, see the
    section on "checksignresult".

    PASS
    The password. Optional.

    SCRE
    Decrypt to screen instead of file? Boolean. Optional.

    NSIG
    Do not put up bad signature alerts? Boolean. Optional.

    APL2
    If direct object is a separate sig file, the file the sig applies to. Optional.

    RECV
    File to decrypt to. Optional. (decr only)

  sign

    Sign. Returns encrypted signed text for `$TYPE="sigd"', returns signature results for
    `$TYPE="sign"'.

    $object->sign(TYPE, DOBJ, PASS, USID, SIGN, READ, OUTP, LATI, WRAP, ALNS, TABX, MDAL, STFX);

    TYPE
    One of "sign" (sign files), "sigd" (sign data).

    DOBJ
    For `$TYPE="sign"', `$DOBJ' is either a filename or a reference to an array of filenames.
    For `$TYPE="sigd"', `$DOBJ' is the data to be signed. If `$DOBJ' is empty, MacPGP will
    attempt to sign the clipboard instead.

    PASS
    The password. Optional.

    USID
    Name of secret key. Optional.

    SIGN
    Sign? One of "sepa" (signature in separate file), "incl", (signature included), "omit"
    (omitted, don't sign). Optional.

    READ
    See READ in the section on "encrypt". Optional.

    OUTP
    See OUTP in the section on "encrypt". Optional.

    LATI
    See LATI in the section on "encrypt". Optional.

    WRAP
    See WRAP in the section on "encrypt". Optional.

    ALNS
    See ALNS in the section on "encrypt". Optional.

    TABX
    See TABX in the section on "encrypt". Optional.

    MDAL
    See MDAL in the section on "encrypt". Optional.

    STFX
    Set text flag? (Esoteric option for some PGP/MIME implementations.) Boolean. Optional.

  asciify

    Asciify a file.

    $object->asciify(DOBJ, READ, LATI, WRAP, ALNS, TABX);

    DOBJ
    Filename or reference to an array of filenames to be asciified.

    READ
    See READ in the section on "encrypt". Optional.

    LATI
    See LATI in the section on "encrypt". Optional.

    WRAP
    See WRAP in the section on "encrypt". Optional.

    ALNS
    See ALNS in the section on "encrypt". Optional.

    TABX
    See TABX in the section on "encrypt". Optional.

  execute

    Execute MacPGP command-line command.

    $object->execute(DOBJ, PASS, LATI, WRAP, ALNS, TABX, MDAL);

    DOBJ
    Command to be executed (i.e., `pgp -kv pudge').

    PASS
    The password. Optional.

    LATI
    See LATI in the section on "encrypt". Optional.

    WRAP
    See WRAP in the section on "encrypt". Optional.

    ALNS
    See ALNS in the section on "encrypt". Optional.

    TABX
    See TABX in the section on "encrypt". Optional.

    MDAL
    See MDAL in the section on "encrypt". Optional.

  generate

    Generate new public/secret key pair.

    $object->generate(DOBJ, LENG, EBIT);

    DOBJ
    User id of new key.

    LENG
    Bit length of key. Higher is stronger and slower. Lower is faster and less secure. Can be
    either a number from 384 to 2048, or one of the following: "casu" (casual, 512), "comm"
    (commercial, 768), "mili" (military, 1024). Default is casual. Optional.

    EBIT
    Number of bits in encryption exponent. Default is 17. Optional.

  extract

    Extract (export) a key.

    $object->extract(DOBJ, RECV, KEYR, OUTP);

    DOBJ
    Key id to extract.

    RECV
    File to extract key to. File must already exist (for now). See the section on "create".

    KEYR
    Filename of keyring to perform operation on. Optional.

    OUTP
    Output format. One of "bina" (8-bit binary), "asci", (ASCII-armored). Optional.

  keyring

    Miscellaneous keyring functions.

    $object->keyring(TYPE, DOBJ, KEYR, USID);

    TYPE
    addk
        Add key in file `$DOBJ'.

    ckey
        Count keys matching `$DOBJ'.

    crfy
        Certify key matching `$DOBJ'.

    fing
        Return fingerprint of key matching `$DOBJ'.

    remv
        Remove key matching `$DOBJ'.

    selk
        Show dialog box, with text `$DOBJ', of keys available in keyring. Returns user id of
        selected key.

    DOBJ
    Varies; see above.

    KEYR
    Filename of keyring to perform operation on. Optional.

    USID
    Name of secret key to certify with. Optional. (crfy only)

  create

    Create temporary scratch file. File with same name, if existing, is erased.

    $object->create(DOBJ);

    DOBJ
    New filename.

  clip2file

    Copy Clipboard to file.

    $object->clip2file(DOBJ);

    DOBJ
    Filename of destination file.

  file2clip

    Copy file to Clipboard. NOTE: This only works if MacPGP is the front application (see the
    section on "switchapp").

    $object->file2clip(DOBJ);

    DOBJ
    Filename of source file.

  checksignresult

    Check signature result from previous decrypt data event. See the section on "decrypt".

    $object->checksignresult;

  getlasterror

    Returns error message from previous MacPGP Apple Event.

    $object->getlasterror;

  getversion

    Returns MacPGP version.

    $object->getversion;

  window

    Show/hide window.

    $object->window(DOBJ);

    DOBJ
    Either "show" or "hide".

  logfile

    Echo PGP messages to a logfile. If logging was active when true sent or no filename is
    given, returns error. If logging was active. Returns full pathname if successful.

    $object->logfile(DOBJ, RECV);

    DOBJ
    Logging? Boolean.

    RECV
    Full pathname of logfile. Existing file of same name erased. Optional.

  switchapp

    Set up window handling. Whenever another method is called, MacPGP.pm will use these two
    variables to determine what app should be in front. Note: when muliple methods are called,
    this doesn't seem to work great. Oh well. Maybe someone else will fix this for me or have
    some ideas. Until then, I suggest that if you DO want MacPGP to come to the front and you
    have sveral methods being called one after the other, that you just set `$object-
    'switchapp(1)> and don't have it switch back.

    $object->switchapp(SWITCH, APP);

    SWITCH
    Switch to MacPGP when method is called? Boolean.

    APP
    Switch to `$APP' after `$object' is destroyed (i.e., when last reference to `$object' is
    made). If left blank and `$SWITCH=1', MacPGP will go to front and stay there.

  getresults

    Returns result of parameter `$DOBJ' from last method call.

    $object->getresults(DOBJ);

    DOBJ
    Name of parameter keyword, one of "----", "result" (synonym for "----", the direct object
    parameter), "errs" (error string), "errn" (error number), "outp". Optional, defaults to
    "result".

  getresultsall

    Returns hash of all result parameters from last method call.

    %results = $object->getresultsall;

  quitpgp

    Quit MacPGP app.

    $object->quitpgp;

VERSION NOTES
    v.1.1, October 13, 1997
    Get app launching from Mac::Apps::Launch, fixed descriptor disposing.

    v.1.0, February 9, 1997
    First full release.

    *   Added a whole slew of scripts and extensions for BBEdit, YA-NewsWatcher, Clipboard, Drag-n-
        Drop. See MacPGP-scripts.readme for details.

    *   Changed the behavior of `switchapp' method. Switching to MacPGP only occurs when `switchapp'
        method is invoked, and switching back only occurs when object is destroyed. Previously,
        switching took place before and after each method call.

    *   Fixed bug which required `decrypt', `encrypt' and `sign' to have a DOBJ value. When one of
        those methods is performing a function on data (dcrd, ncrd, sigd), MacPGP will use
        Clipboard if no data is given.

    *   Fixed bug in `_MpgpBBool' routine which would not catch unacceptable input.

    v.1.0b3, January 15, 1997
    Simply switching to .tar.gz for CPAN instead of .sit.hqx.

    v.1.0b2 January 8, 1997
    Fixes problems in earlier release, optimizes, module-izes.

    *   Change name from MacPGP to Mac::Apps::MacPGP.

    *   Rewrote AppleEvent calls using individual `AEPutParamDesc' and `AEBuild' calls. Should be
        more efficient. Fixes other bugs (like problems with lists and certain characters in
        TEXT values).

    *   Improved error handling and descriptions. Uses `carp' for MacPGP errors.

    *   Made file and recipients variables capable of handling either a scalar or a reference to an
        array.

    *   Added `switchapp', `getresults', `getresultsall', `quitpgp' methods. See docs above.

    v.1.0b1, January 3, 1997
    First public beta. Nearly fully-functional.

BUGS / TO DO
    app switching
    I want to benchmark different ways to switch between applications and use the best one. Stay
    tuned. If you have ideas, let me know.

    other versions
    I am investigating the idea of making this useful with other versions of MacPGP
    (international versions, and limited capabilities of MacPGP 2.6.2) and the future version of
    PGP 5.0.

    stealthify
    I have one more method group to add, and that is for stealtifying/destealthifying files.
    This will come along eventually, but it is not a high priority. First I have to figure out
    how to use it and what it does ... :-) If you have a need/want for it, let me know.

SEE ALSO
    MacPGP 2.6.3 Home Page
    http://www.math.ohio-state.edu/~fiedorow/PGP/

    MacPGP 2.6.3 Documentation
    Included with the above package, take special note of the PGP User's Guide,
    MacPGP263_Manual, and MacPGP263_AppleEvents.

AUTHOR / COPYRIGHT
    Chris Nandor, 13-Oct-1997

            mailto:pudge@pobox.com
            http://pudge.net/

    Copyright (c) 1997 Chris Nandor. All rights reserved. This program is free software; you can
    redistribute it and/or modify it under the same terms as Perl itself. Please see the Perl
    Artistic License.

