Generate the OpenPGP key

Discuss this help topic in SecureBlackbox Forum

OpehnPGP standard supports several types of keys. In our days, a typical OpenPGP keypair actually consists of two cryptographic keys - a primary key and a subkey. The primary key is normally used for signing, while the subkey is used for encryption. While it is typical for PGP environments to use a primary key/subkey bundle, this is not a must. Sometimes you may come across standalone keys (primarily, when interacting with older implementations), as well as whole key trees with a bunch of differently-purposed subkeys bound to the same primary key.

Algorithm-wise, OpenPGP keys also differ. Generally speaking, OpenPGP supports the following public key algorithms: RSA, Elgamal (often incorrectly referred to as DH), DSA, ECDH and ECDSA. When it comes to primary key/subkey bundles, DSA/Elgamal, RSA/RSA and ECDSA/ECDH pairs are typically used (however, again, there's no restriction on algorithm bundles, i.e. a ECDSA/Elgamal key bundle is perfectly possible - yet rarely used de facto).

A typical OpenPGP key is associated with some kind of user ID. This is normally represented with a user's e-mail address, while can in theory be assigned with any textual line. The secret part of the OpenPGP keypair is protected with a password.

You can generate the key synchronously or in asynchronous mode. Asynchronous mode lets you generate the key in background (secondary thread is spawned for generation).

To generate your very own PGP key, please follow the below procedure.

Create an instance of TElPGPSecretKey class.
Decide on the algorithms and the lengths of the primary key and, optionally, the subkey in bits:
```
    int primaryKeyAlg = SBPGPConstants.Unit.SB_PGP_ALGORITHM_PK_DSA;
    int primaryKeyBits = 1024;
    int subKeyAlg = SBPGPConstants.Unit.SB_PGP_ALGORITHM_PK_ELGAMAL_ENCRYPT;
    int subKeyBits = 1024;
```
You will need to provide the following parameters:
- Password to be used for encrypting the secret key
- KeyBits, which specifies the length of the key in bits. The actual (generated) key length can be slightly larger. The key length less than 1024 bits is not recommended due to low security of such keys.
- PublicKeyAlgorithm, which specifies the asymmetric algorithm, for which the keys are generated.
- SubkeyBits and SubkeyAlgorithm. These properties correspond to KeyBits and PublicKeyAlgorithm described above. They are used for subkey. The subkey is a keypair, linked to the main key pair. If the main key pair uses DSS public key algorithm, this key pair can be used only for signing and verification of the data, but not for encryption/decryption. In such case the subkey is created and used for encryption and decryption operations.
- Username for the key to be assigned to.
- UseOldFormat flag, which defines format of key writing. Old format is needed for the key to be read by PGP 2.6.x and some rarely used PGP-compatible software.
- Expires, which specifies the date, when the key expires. This parameter is optional. If it is not specified, then no expiration date is set.
Choose a passphrase:
```
    string passphrase = "1Robot";
```

Invent a user ID:

    string userID = "Luke Skywalker <luke@sky.com>";

Choose how long the key should be valid, in days. Use the value of 0 to create a key that's valid infinitely.
```
	int expires = 365; // one year long
```

To synchronously generate the key, call Generate() method of TElPGPSecretKey class:

	key.Generate(passphrase,
		primaryKeyBits,
		primaryKeyAlg,
		subKeyBits,
		subKeyAlg,
		username,
		expires
	);

To generate the key in background, first call BeginGenerate() method of TElPGPSecretKey class. You will need to pass some of parameters, mentioned above. After calling BeginGenerate, call AsyncOperationFinished() method of TElPGPSecretKey class from time to time, to find out whether the operation has been completed. If AsyncOperationFinished() returns true, call EndGenerate() method and pass the rest of parameters, described above.

After the key is generated, you can add this key to the keyring or save to a separate file.

	keyring.AddSecretKey(key);
	keyring.Save("pubring.pkr", "secring.skr");

Note that while you are only adding the secret key to the keyring, the public key is implicitly added too as it is a part of the secret key. To access the public key of the generated keypair, use PublicKey property of TElPGPSecretKey class.

To generate a legacy standalone key (which is RSA-only), a simplified Generate() method can be used:

	key.Generate(passphrase,
		bits,
		SBPGPConstants.Unit.SB_PGP_ALGORITHM_PK_RSA,
		username,
		false,
		expires
	);

How To articles about OpenPGP key management

Discuss this help topic in SecureBlackbox Forum