\inputtexinfo@c-*-texinfo-*-@setfilenamepgg.info@setVERSION0.1@copyingThisfiledescribesthePGG.Copyright(C)2003,2004FreeSoftwareFoundation,Inc.Copyright(C)2001DaikiUeno.@quotationPermissionisgrantedtocopy,distributeand/ormodifythisdocumentunderthetermsoftheGNUFreeDocumentationLicense,Version1.1oranylaterversionpublishedbytheFreeSoftwareFoundation;withnoInvariantSections,withnoFront-CoverTexts,andwithnoBack-CoverTexts.Acopyofthelicenseisincludedinthesectionentitled``GNUFreeDocumentationLicense''.@endquotation@endcopying@dircategoryEmacs@direntry*PGG:(pgg).EmacsinterfacetovariousPGPimplementations.@enddirentry@settitlePGG@value{VERSION}@titlepage@titlePGG@authorbyDaikiUeno@page@vskip0ptplus1filll@insertcopying@endtitlepage@page@nodeTop@topPGGThismanualdescribesPGG.PGGisaninterfacelibrarybetweenEmacsandvarioustoolsforsecurecommunication.PGGalsoprovidesasimpleuserinterfacetoencrypt,decrypt,sign,andverifyMIMEmessages.@menu*Overview::WhatPGGis.*Prerequisites::Complicatedstuffyoumayhavetodo.*Howtouse::Gettingstartedquickly.*Architecture::*ParsingOpenPGPpackets::*FunctionIndex::*VariableIndex::@endmenu@nodeOverview@chapterOverviewPGGisaninterfacelibrarybetweenEmacsandvarioustoolsforsecurecommunication.EventhoughMailcrypthassimilarfeature,itdoesnotdealwithdetachedPGPmessages,normallyusedinPGP/MIMEinfrastructure.ThiswasthemainreasonwhyIwrotethenewlibrary.PGP/MIMEisanapplicationofMIMEObjectSecurityServices(RFC1848).ThestandardisdocumentedinRFC2015.@nodePrerequisites@chapterPrerequisitesPGGrequiresatleastoneimplementationofprivacyguardsystem.Thisdocumentassumesthatyouhavealreadyobtainedandinstalledthemandthatyouarefamiliarwithitsbasicfunctions.Bydefault,PGGusesGnuPG,butPrettyGoodPrivacyversion2orversion5arealsosupported.Ifyouarenewtosuchasystem,IrecommendthatyoushouldlookovertheGNUPrivacyHandbook(GPH)whichisavailableat@uref{http://www.gnupg.org/gph/}.@nodeHowtouse@chapterHowtouseThetoplevelinterfaceofthislibraryisquitesimple,andonlyintendedtousewithpublic-keycryptographicoperation.TousePGG,evaluatefollowingexpressionatthebeginningofyourapplicationprogram.@lisp(require'pgg)@endlispIfyouwanttocheckexistenceofpgg.elatruntime,insteadyoucanlistautoloadsettingfordesiredfunctionsasfollows.@lisp(autoload'pgg-encrypt-region"pgg""Encrypt the current region."t)(autoload'pgg-decrypt-region"pgg""Decrypt the current region."t)(autoload'pgg-sign-region"pgg""Sign the current region."t)(autoload'pgg-verify-region"pgg""Verify the current region."t)(autoload'pgg-insert-key"pgg""Insert the ASCII armored public key."t)(autoload'pgg-snarf-keys-region"pgg""Import public keys in the current region."t)@endlisp@menu*UserCommands::*Selectinganimplementation::*Cachingpassphrase::*Defaultuseridentity::@endmenu@nodeUserCommands@sectionUserCommandsAtthistimeyoucanusesomecryptographiccommands.Thebehaviorofthesecommandsreliesonafashionofinvocationbecausetheyarealsointendedtobeusedaslibraryfunctions.Incaseyoudon'thavethesigner'spublickey,forexample,thefunction@code{pgg-verify-region}failsimmediately,butifthefunctionhadbeencalledinteractively,itwouldaskyoutoretrievethesigner'spublickeyfromtheserver.@deffnCommandpgg-encrypt-regionstartendrecipients&optionalsignEncryptthecurrentregionbetween@var{start}and@var{end}for@var{recipients}.Whenthefunctionwerecalledinteractively,youwouldbeaskedabouttherecipients.Ifencryptionissuccessful,itreplacesthecurrentregioncontents(intheaccessibleportion)withtheresultingdata.Ifoptionalargument@var{sign}isnon-@code{nil},thefunctionisrequesttodoacombinedsignandencrypt.ThiscurrentlyonlyworkwithGnuPG.@enddeffn@deffnCommandpgg-decrypt-regionstartendDecryptthecurrentregionbetween@var{start}and@var{end}.Ifdecryptionissuccessful,itreplacesthecurrentregioncontents(intheaccessibleportion)withtheresultingdata.@enddeffn@deffnCommandpgg-sign-regionstartend&optionalcleartextMakethesignaturefromtextbetween@var{start}and@var{end}.Iftheoptionalthirdargument@var{cleartext}isnon-@code{nil},orthefunctioniscalledinteractively,itdoesnotcreateadetachedsignature.Insuchacase,itreplacesthecurrentregioncontents(intheaccessibleportion)withtheresultingdata.@enddeffn@deffnCommandpgg-verify-regionstartend&optionalsignaturefetchVerifythecurrentregionbetween@var{start}and@var{end}.Iftheoptionalthirdargument@var{signature}isnon-@code{nil},orthefunctioniscalledinteractively,itistreatedasthedetachedsignatureofthecurrentregion.Iftheoptional4thargument@var{fetch}isnon-@code{nil},orthefunctioniscalledinteractively,weattempttofetchthesigner'spublickeyfromthekeyserver.@enddeffn@deffnCommandpgg-insert-keyRetrievetheuser'spublickeyandinsertitasASCII-armoredformat.@enddeffn@deffnCommandpgg-snarf-keys-regionstartendCollectpublickeysinthecurrentregionbetween@var{start}and@var{end},andaddthemintotheuser'skeyring.@enddeffn@nodeSelectinganimplementation@sectionSelectinganimplementationSincePGPhasalonghistoryandthereareanumberofPGPimplementationsavailabletoday,thefunctionwhicheachonehasdiffersconsiderably.Forexample,ifyouareusingGnuPG,youknowyoucanselectcipheralgorithmfrom3DES,CAST5,BLOWFISH,andsoon,butontheotherhandtheversion2ofPGPonlysupportsIDEA.Bydefault,ifthevariable@code{pgg-scheme}isnotset,PGGsearchestheregisteredschemeforanimplementationoftherequestedserviceassociatedwiththenamedalgorithm.Iftherearenomatch,PGGuses@code{pgg-default-scheme}.Inotherwords,therearetwooptionstocontrolwhichcommandisusedtoprocesstheincomingPGParmors.Oneisforencryptingandsigning,theotherisfordecryptingandverifying.@defvarpgg-schemeForcespecifytheschemeofPGPimplementationfordecryptingandverifying.Thevaluecanbe@code{gpg},@code{pgp},and@code{pgp5}.@enddefvar@defvarpgg-default-schemeForcespecifytheschemeofPGPimplementationforencryptingandsigning.Thevaluecanbe@code{gpg},@code{pgp},and@code{pgp5}.@enddefvar@nodeCachingpassphrase@sectionCachingpassphrasePGGusesasimplepassphrasecachingmechanism,whichisenabledbydefault.@defvarpgg-cache-passphraseIfnon-@code{nil},storepassphrases.Thedefaultvalueofthisvariableis@code{t}.Ifyouwereworryaboutsecurityissue,however,youcouldstopcachingwithsettingit@code{nil}.@enddefvar@defvarpgg-passphrase-cache-expiryElapsedtimeforexpirationinseconds.@enddefvar@nodeDefaultuseridentity@sectionDefaultuseridentityThePGPimplementationisusuallyabletoselecttheproperkeytouseforsigninganddecryption,butifyouhavemorethanonekey,youmayneedtospecifythekeyidtouse.@defvarpgg-default-user-idUserIDofyourdefaultidentity.Itdefaultstothevaluereturnedby@samp{(user-login-name)}.Youcancustomizethisvariable.@enddefvar@defvarpgg-gpg-user-idUserIDoftheGnuPGdefaultidentity.Itdefaultsto@samp{nil}.Thisoverrides@samp{pgg-default-user-id}.Youcancustomizethisvariable.@enddefvar@defvarpgg-pgp-user-idUserIDofthePGP2.x/6.xdefaultidentity.Itdefaultsto@samp{nil}.Thisoverrides@samp{pgg-default-user-id}.Youcancustomizethisvariable.@enddefvar@defvarpgg-pgp5-user-idUserIDofthePGP5.xdefaultidentity.Itdefaultsto@samp{nil}.Thisoverrides@samp{pgg-default-user-id}.Youcancustomizethisvariable.@enddefvar@nodeArchitecture@chapterArchitecturePGGintroducesthenotionofa"scheme of PGP implementation"(usedinterchangeablywith"scheme"inthisdocument).Thistermreferstoasingletonobjectwrappedwiththelunaobjectsystem.SincePGGwasdesignedforaccessinganddevelopingPGPfunctionality,thearchitecturehadtobedesignednotjustforinteroperabilitybutalsoforextensiblity.InthischapterweexplorethearchitecturewhilefindingouthowtowritethePGGbackend.@menu*Initializing::*Backendmethods::*Gettingoutput::@endmenu@nodeInitializing@sectionInitializingAschememustbeinitializedbeforeitisused.Ithadbetterguaranteetokeeponlyoneinstanceofascheme.Thefollowingcodeissnippedoutof@file{pgg-gpg.el}.Onceaninstanceof@code{pgg-gpg}schemeisinitialized,it'sstoredtothevariable@code{pgg-scheme-gpg-instance}andwillbereusedfromnowon.@lisp(defvarpgg-scheme-gpg-instancenil)(defunpgg-make-scheme-gpg()(orpgg-scheme-gpg-instance(setqpgg-scheme-gpg-instance(luna-make-entity'pgg-scheme-gpg))))@endlispThenameofthefunctionmustfollowtheregulation---@code{pgg-make-scheme-}followsthebackendname.@nodeBackendmethods@sectionBackendmethodsIneachbackend,thesemethodsmustbepresent.Theoutputofthesemethodsisstoredinspecialbuffers(@ref{Gettingoutput}),sothatthesemethodsmusttellthestatusoftheexecution.@deffnMethodpgg-scheme-lookup-keyschemestring&optionaltypeReturnkeysassociatedwith@var{string}.Iftheoptionalthirdargument@var{type}isnon-@code{nil},itsearchesfromthesecretkeyrings.@enddeffn@deffnMethodpgg-scheme-encrypt-regionschemestartendrecipients&optionalsignEncryptthecurrentregionbetween@var{start}and@var{end}for@var{recipients}.If@var{sign}isnon-@code{nil},doacombinedsignandencrypt.Ifencryptionissuccessful,itreturns@code{t},otherwise@code{nil}.@enddeffn@deffnMethodpgg-scheme-decrypt-regionschemestartendDecryptthecurrentregionbetween@var{start}and@var{end}.Ifdecryptionissuccessful,itreturns@code{t},otherwise@code{nil}.@enddeffn@deffnMethodpgg-scheme-sign-regionschemestartend&optionalcleartextMakethesignaturefromtextbetween@var{start}and@var{end}.Iftheoptionalthirdargument@var{cleartext}isnon-@code{nil},itdoesnotcreateadetachedsignature.Ifsigningissuccessful,itreturns@code{t},otherwise@code{nil}.@enddeffn@deffnMethodpgg-scheme-verify-regionschemestartend&optionalsignatureVerifythecurrentregionbetween@var{start}and@var{end}.Iftheoptionalthirdargument@var{signature}isnon-@code{nil},itistreatedasthedetachedsignatureofthecurrentregion.Ifthesignatureissuccessfullyverified,itreturns@code{t},otherwise@code{nil}.@enddeffn@deffnMethodpgg-scheme-insert-keyschemeRetrievetheuser'spublickeyandinsertitasASCII-armoredformat.Onsuccess,itreturns@code{t},otherwise@code{nil}.@enddeffn@deffnMethodpgg-scheme-snarf-keys-regionschemestartendCollectpublickeysinthecurrentregionbetween@var{start}and@var{end},andaddthemintotheuser'skeyring.Onsuccess,itreturns@code{t},otherwise@code{nil}.@enddeffn@nodeGettingoutput@sectionGettingoutputTheoutputofthebackendmethods(@ref{Backendmethods})isstoredinspecialbuffers,sothatthesemethodsmusttellthestatusoftheexecution.@defvarpgg-errors-bufferThestandarderroroutputoftheexecutionofthePGPcommandisstoredhere.@enddefvar@defvarpgg-output-bufferThestandardoutputoftheexecutionofthePGPcommandisstoredhere.@enddefvar@defvarpgg-status-bufferTherestofstatusinformationoftheexecutionofthePGPcommandisstoredhere.@enddefvar@nodeParsingOpenPGPpackets@chapterParsingOpenPGPpacketsTheformatofOpenPGPmessagesismaintainedinordertopublishallnecessaryinformationneededtodevelopinteroperableapplications.ThestandardisdocumentedinRFC2440.PGGhasitsownparserfortheOpenPGPpackets.@defunpgg-parse-armorstringListthesequenceofpacketsin@var{string}.@enddefun@defunpgg-parse-armor-regionstartendListthesequenceofpacketsinthecurrentregionbetween@var{start}and@var{end}.@enddefun@defvarpgg-ignore-packet-checksumIfnon-@code{nil},don'tcheckthechecksumofthepackets.@enddefvar@nodeFunctionIndex@chapterFunctionIndex@printindexfn@nodeVariableIndex@chapterVariableIndex@printindexvr@summarycontents@contents@bye@cEnd:@ignorearch-tag:0c205838-34b9-41a5-b9d7-49ae57ccac85@endignore