\inputtexinfo@c-*-texinfo-*-@setfilename../info/pgg@setVERSION0.1@copyingThisfiledescribesPGG,anEmacsinterfacetovariousPGPimplementations.Copyright@copyright{}2001,2003,2004,2005,2006,2007FreeSoftwareFoundation,Inc.@quotationPermissionisgrantedtocopy,distributeand/ormodifythisdocumentunderthetermsoftheGNUFreeDocumentationLicense,Version1.2oranylaterversionpublishedbytheFreeSoftwareFoundation;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::*GNUFreeDocumentationLicense::Thelicenseforthisdocumentation.*FunctionIndex::*VariableIndex::@endmenu@nodeOverview@chapterOverviewPGGisaninterfacelibrarybetweenEmacsandvarioustoolsforsecurecommunication.EventhoughMailcrypthassimilarfeature,itdoesnotdealwithdetachedPGPmessages,normallyusedinPGP/MIMEinfrastructure.ThiswasthemainreasonwhyIwrotethenewlibrary.PGP/MIMEisanapplicationofMIMEObjectSecurityServices(RFC1848).ThestandardisdocumentedinRFC2015.@nodePrerequisites@chapterPrerequisitesPGGrequiresatleastoneimplementationofprivacyguardsystem.Thisdocumentassumesthatyouhavealreadyobtainedandinstalledthemandthatyouarefamiliarwithitsbasicfunctions.Bydefault,PGGusesGnuPG.Ifyouarenewtosuchasystem,IrecommendthatyoushouldlookovertheGNUPrivacyHandbook(GPH)whichisavailableat@uref{http://www.gnupg.org/documentation/}.WhenusingGnuPG,werecommendtheuseofthe@code{gpg-agent}program,whichisdistributedwithversions2.0andlaterofGnuPG.Thisisadaemontomanageprivatekeysindependentlyfromanyprotocol,andprovidesthemostsecurewaytoinputandcacheyourpassphrases(@pxref{Cachingpassphrase}).Bydefault,PGGwillattempttouse@code{gpg-agent}ifitisrunning.@xref{InvokingGPG-AGENT,,,gnupg,UsingtheGNUPrivacyGuard}.PGGalsosupportsPrettyGoodPrivacyversion2orversion5.@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-encrypt-symmetric-region"pgg""Encrypt the current region with symmetric algorithm."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&optionalsignpassphraseEncryptthecurrentregionbetween@var{start}and@var{end}for@var{recipients}.Whenthefunctionwerecalledinteractively,youwouldbeaskedabouttherecipients.Ifencryptionissuccessful,itreplacesthecurrentregioncontents(intheaccessibleportion)withtheresultingdata.Ifoptionalargument@var{sign}isnon-@code{nil},thefunctionisrequesttodoacombinedsignandencrypt.ThiscurrentlyisconfirmedtoworkwithGnuPG,butmightnotworkwithPGPorPGP5.Ifoptional@var{passphrase}is@code{nil},thepassphrasewillbeobtainedfromthepassphrasecacheoruser.@enddeffn@deffnCommandpgg-encrypt-symmetric-region&optionalstartendpassphraseEncryptthecurrentregionbetween@var{start}and@var{end}usingasymmetriccipher.Afterinvocationyouareaskedforapassphrase.Ifoptional@var{passphrase}is@code{nil},thepassphrasewillbeobtainedfromthepassphrasecacheoruser.symmetric-cipherencryptioniscurrentlyonlyimplementedforGnuPG.@enddeffn@deffnCommandpgg-decrypt-regionstartend&optionalpassphraseDecryptthecurrentregionbetween@var{start}and@var{end}.Ifdecryptionissuccessful,itreplacesthecurrentregioncontents(intheaccessibleportion)withtheresultingdata.Ifoptional@var{passphrase}is@code{nil},thepassphrasewillbeobtainedfromthepassphrasecacheoruser.@enddeffn@deffnCommandpgg-sign-regionstartend&optionalcleartextpassphraseMakethesignaturefromtextbetween@var{start}and@var{end}.Iftheoptionalthirdargument@var{cleartext}isnon-@code{nil},orthefunctioniscalledinteractively,itdoesnotcreateadetachedsignature.Insuchacase,itreplacesthecurrentregioncontents(intheaccessibleportion)withtheresultingdata.Ifoptional@var{passphrase}is@code{nil},thepassphrasewillbeobtainedfromthepassphrasecacheoruser.@enddeffn@deffnCommandpgg-verify-regionstartend&optionalsignaturefetchVerifythecurrentregionbetween@var{start}and@var{end}.Iftheoptionalthirdargument@var{signature}isnon-@code{nil},itistreatedasthedetachedsignaturefileofthecurrentregion.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.Whichimplementationisusediscontrolledbythe@code{pgg-scheme}variable.Ifitis@code{nil}(thedefault),thevalueofthe@code{pgg-default-scheme}variablewillbeusedinstead.@defvarpgg-schemeForcespecifytheschemeofPGPimplementation.Thevaluecanbesetto@code{gpg},@code{pgp},and@code{pgp5}.Thedefaultis@code{nil}.@enddefvar@defvarpgg-default-schemeThedefaultschemeofPGPimplementation.Thevalueshouldbeoneof@code{gpg},@code{pgp},and@code{pgp5}.Thedefaultis@code{gpg}.@enddefvar@nodeCachingpassphrase@sectionCachingpassphraseWhenusingGnuPG(gpg)asthePGPscheme,werecommendusingaprogramcalled@code{gpg-agent}forenteringandcachingpassphrases@footnote{Actually,@code{gpg-agent}doesnotcachepassphrasesbutprivatekeys.Ontheotherhand,fromauser'spointofview,thistechnicaldifferenceisn'tvisible.}.@defvarpgg-gpg-use-agentIfnon-@code{nil},attempttouse@code{gpg-agent}wheneverpossible.Thedefaultis@code{t}.If@code{gpg-agent}isnotrunning,orGnuPGisnotthecurrentPGPscheme,PGG'sownpassphrase-cachingmechanismisused(seebelow).@enddefvarTouse@code{gpg-agent}withPGG,youmustfirstensurethat@code{gpg-agent}isrunning.Forexample,ifyouarerunningintheXWindowSystem,youcandothisbyputtingthefollowinglineinyour@file{.xsession}file:@smallexampleeval"$(gpg-agent --daemon)"@endsmallexampleFormoredetailsoninvoking@code{gpg-agent},@xref{InvokingGPG-AGENT,,,gnupg,UsingtheGNUPrivacyGuard}.WheneveryouperformaPGGoperationthatrequiresaGnuPGpassphrase,GnuPGwillcontact@code{gpg-agent},whichpromptsyouforthepassphrase.Furthermore,@code{gpg-agent}``caches''theresult,sothatsubsequentuseswillnotrequireyoutoenterthepassphraseagain.(Thiscacheusuallyexpiresafteracertaintimehaspassed;youcanchangethisusingthe@code{--default-cache-ttl}optionwheninvoking@code{gpg-agent}.)IfyouarerunninginaXWindowSystemenvironment,@code{gpg-agent}promptsforapassphrasebyopeningagraphicalwindow.However,ifyouarerunningEmacsonatextterminal,@code{gpg-agent}hastroublereceivinginputfromtheterminal,sinceitisbeingsenttoEmacs.Oneworkaroundforthisproblemistorun@code{gpg-agent}onadifferentterminalfromEmacs,withthe@code{--keep-tty}option;thistells@code{gpg-agent}useitsownterminaltopromptforpassphrases.When@code{gpg-agent}isnotbeingused,PGGpromptsforapassphrasethroughEmacs.Italsohasitsownpassphrasecachingmechanism,whichiscontrolledbythevariable@code{pgg-cache-passphrase}(seebelow).ThereisasecurityriskinhandlingpassphrasesthroughPGGratherthan@code{gpg-agent}.WhenyouenteryourpassphraseintoanEmacsprompt,itistemporarilystoredasacleartextstringinthememoryoftheEmacsexecutable.Iftheexecutablememoryisswappedtodisk,therootusercan,intheory,extractthepassphrasefromtheswapfile.Furthermore,theswapfilecontainingthecleartextpassphrasemightremainonthediskafterthesystemisdiscardedorstolen.@code{gpg-agent}avoidsthisproblembyusingcertaintricks,suchasmemorylocking,whichhavenotbeenimplementedinEmacs.@defvarpgg-cache-passphraseIfnon-@code{nil},storepassphrases.Thedefaultvalueofthisvariableis@code{t}.Ifyouareworriedaboutsecurityissues,however,youcouldstopthecachingofpassphrasesbysettingthisvariableto@code{nil}.@enddefvar@defvarpgg-passphrase-cache-expiryElapsedtimeforexpirationinseconds.@enddefvarIfyourpassphrasecontainsnon-ASCIIcharacters,youmightneedtospecifythecodingsystemtobeusedtoencodeyourpassphrases,sinceGnuPGtreatsthemasabytesequence,notasacharactersequence.@defvarpgg-passphrase-coding-systemCodingsystemusedtoencodepassphrase.@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&optionalsignpassphraseEncryptthecurrentregionbetween@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-encrypt-symmetric-regionschemestartend&optionalpassphraseEncryptthecurrentregionbetween@var{start}and@var{end}usingasymmetriccipherandapassphrases.Ifencryptionissuccessful,itreturns@code{t},otherwise@code{nil}.ThisfunctioniscurrentlyonlyimplementedforGnuPG.@enddeffn@deffnMethodpgg-scheme-decrypt-regionschemestartend&optionalpassphraseDecryptthecurrentregionbetween@var{start}and@var{end}.Ifdecryptionissuccessful,itreturns@code{t},otherwise@code{nil}.@enddeffn@deffnMethodpgg-scheme-sign-regionschemestartend&optionalcleartextpassphraseMakethesignaturefromtextbetween@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@nodeGNUFreeDocumentationLicense@appendixGNUFreeDocumentationLicense@includedoclicense.texi@nodeFunctionIndex@unnumberedFunctionIndex@printindexfn@nodeVariableIndex@unnumberedVariableIndex@printindexvr@summarycontents@contents@bye@cEnd:@ignorearch-tag:0c205838-34b9-41a5-b9d7-49ae57ccac85@endignore