Sign a file with a private key

Discuss this help topic in SecureBlackbox Forum

As said in the title of this topic, you must have access to the private part of the key to perform the signing. You can't use a key for signing if you only have its public part or you don't know its password.

First, you will need to load the signing private key into a dedicated TElPGPKeyring object. This will normally be a private key issued in your name or in the name of the party that produced the file(s) being signed. So, in most cases, your first step will consist of loading your local keyring, locating the signing key in it and adding it to the dedicated 'signing keyring' storage.

TElPGPKeyring keyring = new TElPGPKeyring();
keyring.Load(�pubring.pkr�, �secring.skr�, true);

int keyIndex = myKeys.FindSecretKeyByEmailAddress("myself@gmail.com");

TElPGPKeyring signingKeys = new TElPGPKeyring();
signingKeys.AddSecretKey(myKeys.get_SecretKeys(keyIndex));

Note: while in majority of scenarios your 'signing keyring' will contain exactly one signing key, in general case OpenPGPBlackbox allows you to sign files or data with multiple keys (provided that you know all the passwords). In such multi-signature cases the dedicated signing keyring will contain more than one key.

Having loaded the key(s), you are ready to proceed to the signing part:

Create an instance of TElPGPWriter class:

TElPGPWriter writer = new TElPGPWriter();

Assign the signing keyring to the SigningKeys property:
```
writer.SigningKeys = signingKeys;
```
Provide you key password to the component. There are two ways to do that; please choose the one more convenient for you:
1. Assign the password(s) to the key objects' Passphrase properties:
```
signingKeys.get_SecretKeys(0).Passphrase = �password�;
```
  or
2. Handle the TElPGPWriter.OnKeyPassphrase event to provide the passphrase asynchronously during the signing.
Provide the source filename (doesn't need to be the real file name) and the encryption date:
```
pgpWriter.Filename = "picture.jpg";
pgpWriter.Timestamp = DateTime.UtcNow;
```

Tune-up signing settings:

pgpWriter.HashAlgorithm = SBPGPConstants.Unit. SB_PGP_ALGORITHM_MD_SHA512;

Optionally tune-up supplementary options, such as armouring:

pgpWriter.Armor = true;
pgpWriter.Compress = true;
pgpWriter.SignBufferingMethod = TSBPGPSignBufferingMethod.sbmRewind;

Call SignFile() method:
```
pgpWriter.SignFile("picture.jpg", "picture.jpg.pgp", detached);
```
Note: the last, 'detached', parameter of the SignFile() method specifies whether an enveloping or detached signature should be created. Enveloping signature includes all the source data in it, so the signed file contains both the original data and the signature. Detached signatures only contain the signature itself, so you have to distribute the original data together with the signature file.

Note: in certain scenarios, especially where heavy multi-subkey structures are used, there might be a need to specify the exact subkey to be used for signing. While SecureBlackbox does its best to find the appropriate signing key or subkey automatically, sometimes this is not possible due to lack of information stored within the keys. If unsure about the purpose of a particular primary key or subkey (i.e. whether it is signing-only, encryption-only or both encryption and signing capable), SecureBlackbox always uses it for signing. As a result, the resulting file may be signed with multiple keys, which might be confusing for the receiving software. You can tell TElPGPWriter that it must not sign the file for a particular key or subkey by setting its Enabled property to false. For instance, the following setting makes TElPGPWriter not sign the file with the primary key and only use its subkeys:
```
signingKeys.get_SecretKeys(0).Enabled = false;
```
Note: In addition to the 'normal' signing procedure described above, OpenPGP offers a completely different way of signing applicable to text files, called 'cleartext' signing. This is an e-mail like way of signing where the signature is encoded in BASE64 and appended to the data itself:
```
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hello, world!
This is my simple signed text.

-----BEGIN PGP SIGNATURE-----
Version: PGPBlackbox

iQA/AwUBRNHhYOzg6fTTIXI1EQIPaACgvWKH+Nv5cSVJbLbMAnVsEOL6T7sAoJsU
/kCTwSirFnQVTkOzHwGwrI/p
=bTn4
-----END PGP SIGNATURE-----
```
Such signatures can be created by replacing SignFile() with CleartextSignFile() call. Cleartext signatures are always enveloping, so no 'detached' parameter is available in the method declaration. Key and component setup in this case are performed in exactly same way as you do with regular signing. Some properties, like Armor or Compress, are not applicable to cleartext signing for obvious reasons.

How To articles about file encryption and signing with OpenPGP

Discuss this help topic in SecureBlackbox Forum