Discuss this help topic in SecureBlackbox Forum

Unprotect an OpenPGP file (alternative)

By 'unprotecting' we mean processing of protected file, whatever that may mean security-wise. While protected files may come in different forms and shapes (encrypted, signed, encrypted and signed), their processing by OpenPGPBlackbox is performed in a unified manner, which lets you process them in a more comfortable way.

You use TElPGPReader to process protected files. For the majority of cases, you will call its DecryptAndVerify() method (or DecryptAndVerifyFile(), if you wish to read input data from a file rather than from a stream). DecryptAndVerify() processes the protected file, informs you about the data in there and the security mechanisms applied to it, decrypts protected files and verifies any signatures included.

Note. The only exceptional case where you use a different processing method is when you need to verify a detached signature. In this case you call VerifyDetached() instead of DecryptAndVerify(), passing data and its signature(s) separately. Read more about specifics of processing of detached signatures.

Before calling DecryptAndVerify() you need to configure your TElPGPReader to provide it with access to decryption and verifying keys. You might also want to handle some events to keep yourself notified about the processing progress.

Load your public and secret keyring into a TElPGPKeyring object. You can use the same object for both public and secret keyrings, or use two different objects, depending on the way in which you manage your keys. Assign the keyring containing your decryption (secret) keys to DecryptingKeys property, and the keyring containing public keys of the originators to VerifyingKeys property:

reader.DecryptingKeys  = secKeyring;
reader.VerifyingKeys = pubKeyring;

Tune-up your TElPGPReader object by adjusting its properties. If you know the contents and security features of the protected files beforehand, you can adjust such properties as KeyPassphrase, Passphrase, OutputFile or OutputStream before processing the file instead of providing them on the fly via the object's events.

Note. Passphrase property specifies the decryption password for conventional (password-based) encryption method. It has a totally different meaning to the passwords you use to encrypt your secret keys. Please use KeyPassphrase property to specify passwords for your secret keys.

Handle events exposed by TElPGPReader to keep yourself notified about the processing progress:

• OnEncrypted is fired if encrypted data were encountered in the protected file. It returns you the Key IDs of the keys the data is encrypted for, together with the indicator if the data is [also] protected with conventional password. You can adjust the DecryptingKeys, Passphrase and KeyPassphrase properties from inside the handler to set up decryption facilities on the fly.
• OnSigned is fired if the data in the protected file is signed. A list of signing KeyIDs are passed as parameters. You can adjust the contents of VerifyingKeys inside the handler so that all the needed public keys were available for validation.
• OnCreateOutputStream / OnRequestOutputFile are invoked to let you provide a stream or filename for the output data. OnCreateOutputStream expects you to create a stream where the unprotected (decrypted) data will be saved to. The original file name, encrypted with the data by its creator, and the time stamp of the original file, are returned too. Please note that a name of _CONSOLE indicates that a file was encrypted in a special 'for-your-eyes-only' mode and must not be written to any persistent media.
• OnKeyPassphrase is raised when a proper decryption key was located in the keyring but can't be used due to unset/incorrect passphrase. Please ask the user for a valid passphrase and return it via the Passphrase parameter. To stop the process, set Cancel parameter to true.
• OnPassword is invoked when the components need a password to decrypt conventionally encrypted data. Use the same approach as you do with OnKeyPassphrase handling.
• OnProgress is invoked periodically to notify you about the overall progress of the operation.
• OnFileExtractionStart is fired during processing of a multi-file archive to notify you about the start of decryption of the next file in the processing queue.
• OnMultipleFilesFound notifies you that the protected file contains a number of files and not a single file.
• OnTemporaryStream is invoked when the component needs a temporary media to store some intermediary data. The best way is to handle this event is to create a temporary file stream in a standard temporary directory and return the stream object back to the component. If you don't handle this event, any temporary objects will be created in memory.
• OnSignatures event is invoked to inform the user about the signatures included in the document and their validities. This event, in contrast to OnSigned, is fired at the end of file processing and returns the actual results of the validation.
• OnArmored, OnCompressed are auxiliary events that you can use to track the specifics of OpenPGP file protection.

Finally, call DecryptAndVerify(), passing your data to it. Data processing may take some time, depending on the length of the input and the specifics of its protection. Once DecryptAndVerify() returns, your output media will contain the unprotected file. If any processing issues occur, DecryptAndVerify() will throw a relevant exception. Please analyse the exception message carefully to identify the reason for the problem.

How To articles about file encryption and signing with OpenPGP

Discuss this help topic in SecureBlackbox Forum