Exception handling guidelines for OpenPGP Library for .NET

Most of the cryptography methods exposed by DidiSoft OpenPGP Library for .NET throw two general exceptions:

  • System.IO.IOException
  • DidiSoft.Pgp.PGPException

IOException is thrown in case of I/O related errors, e.g. file not found, the disk is full, etc.

DidiSoft.Pgp.PGPException is thrown in case of an OpenPGP encryption error.

In this article, we are going to explain exception handling for OpenPGP related errors.

Table of contents

1. Error handling and taking recovery actions
2. DidiSoft.Pgp.Exceptions namespace

Error handling and taking recovery actions

In order to catch an OpenPGP exception, we have to enclose the invoked methods in a try-catch block like this:

C# code

try {
...
} catch (DidiSoft.Pgp.PGPException e) {
...
}

VB.NET code

Try
...
Catch e As DidiSoft.Pgp.PGPException 
...
End Try

In most of the cases when an OpenPGP error occurs, the exception thrown is a subclass of DidiSoft.Pgp.PGPException located in the DidiSoft.Pgp.Exceptions namespace. We can check the exact exception class within the Catch block and take recovery actions accordingly.

Below is shown a simple example that illustrates the concept. You can adapt it for the particular method being invoked by referring to the Library documentation API for the declared exceptions thrown.

C# example

using System;
using DidiSoft.Pgp;
using DidiSoft.Pgp.Exceptions;
 
public class ExceptionHandlingDemo
{
 public void Demo()
 {
  // initialize the library
  PGPLib pgp = new PGPLib();
 
  try 
  {
	pgp.DecryptFile( ... );
  } catch (IOException e) {
    // I/O error 
  } catch (PGPException e) {
   // Here we can try to identify the exception
   // and take recovery actions
   if (e is NonPGPDataException)
   {
     Console.WriteLine("The passed encrypted file is not a valid OpenPGP archive");
   }
   else if (e is IntegrityCheckException)
   {
     Console.WriteLine("The passed encrypted file is corrupted");
   }
   else if (e is FileIsPBEEncryptedException)
   {
     Console.WriteLine("The passed encrypted file is encrypted with a password " +
                       "but we try to decrypt it with a private key");
   }
   else if (e is WrongPrivateKeyException)
   {
     Console.WriteLine(e.Message);
   }
   else if (e is WrongPasswordException)
   {
     Console.WriteLine("The password for the provided private key is wrong");
   }
   else
   {
     Console.WriteLine("General decryption error not among the above ones ");
   }
  }
 }
}

VB.NET example

Imports System
Imports DidiSoft.Pgp
Imports DidiSoft.Pgp.Exceptions
 
Class ExceptionHandlingDemo
 Public Sub Demo()
  ' initialize the library
  Dim pgp As New PGPLib()
 
  Try
    pgp.DecryptFile( ... )
  Catch e As IOException
    ' I/O error
  Catch e As PGPException
   ' Here we can try to identify the exception
   ' and take recovery actions
   If TypeOf e Is NonPGPDataException Then
     Console.WriteLine("The passed encrypted file is not a valid OpenPGP archive")
   ElseIf TypeOf e Is IntegrityCheckException Then
     Console.WriteLine("The passed encrypted file is corrupted")
   ElseIf TypeOf e Is FileIsPBEEncryptedException Then
     Console.WriteLine("The passed encrypted file is encrypted with a " + _
                       "password, but we try to decrypt it with a private key")
   ElseIf TypeOf e Is WrongPrivateKeyException Then
     Console.WriteLine("The encrypted input was encrypted with a " + _
                       " different private key than the provided one")
     Console.WriteLine(e.Message)
   ElseIf TypeOf e Is WrongPasswordException Then
     Console.WriteLine("The password for the provided private key is wrong")
   Else
     Console.WriteLine("General decryption error not among the above ones ")
   End If
  End Try
 End Sub
End Class

Back to TOC

DidiSoft.Pgp.Exceptions namespace

Here you can find a list with the subclasses of DidiSoft.Pgp.PGPException located in the DidiSoft.Pgp.Exceptions namespace.

Exception Description
FileIsEncryptedException Indicates that a file is encrypted with a key
FileIsPBEEncryptedException Indicates that a file is encrypted with a password
IntegrityCheckException Indicates that an integrity protected archive is corrupted
KeyIsExpiredException Shows that a public key we try to use is expired
KeyIsRevokedException Shows that a public key we try to use is revoked
NonPGPDataException Shows that a file is not an OpenPGP archive
WrongPasswordException Indicates that the provided password is wrong
WrongPrivateKeyException Shows that an OpenPGP message is archived with a different key than the provided one or the provide key source is not a private key at all
WrongPublicKeyException Indicates that the supplied public key source is invalid

Back to TOC

Summary

In this chapter, we have discussed the general exception handling strategy when using OpenPGP Library for .NET.

Concrete examples are available at the end of each chapter in this tutorial.