SecureBlackbox 2020 Kotlin Edition

Questions / Feedback?

GeneratePair Method

Generates a new pair of PGP keys.

Syntax

public fun generatePair(username: String?, keyAlgorithm: String?, keyBits: Int, subKeyAlgorithm: String?, subKeyBits: Int, password: String?, expires: Int)

Remarks

Use this method to create a new key-subkey pair. This is the primary method for generating conformant PGP keys.

Pass the user ID of the new key via the Username property. This typically should be in the format of User Name <user@email>, for example Robert Frost <robert@frost.com>, but generally can be an arbitrary text string.

Set KeyAlgorithm and SubKeyAlgorithm to the public key algorithms that you want to use for the new key. See the full list of algorithms below. Where ECDSA or ECDH algorithm is used, you can specify a particular curve after the algorithm name, separated with the colon: ECDSA:P384 or ECDH:BRAINPOOLP256. KeyBits and SubKeyBits specify the number of bits in the key and the subkey. These parameters can be set to zero if the key length is implicitly defined by the algorithm of the key. For example, ECDSA P256 keys are always 256 bit long, so you may pass 0 as the corresponding KeyBits or SubKeyBits parameter.

Provide the key encryption password and the validity period in days via the Password and Expires parameters. Set Expires to zero to indicate that the key does not expire.

While you can use any combination of algorithms for your key and subkey, most implementations got used to specific hard-wired combinations. Sticking to those will help make sure your keys are understood by other implementations. Typical combinations are:

  • EDDSA main key with ECDH:CURVE25519 subkey;
  • ECDSA main key with ECDH subkey; both with NIST curves (P256, P384, or P512);
  • ECDSA main key with ECDH subkey; both with Brainpool curves (BRAINPOOLP256 or BRAINPOOLP512);
  • RSA main key with RSA subkey.
The code snippet below illustrates a typical key generation procedure:
    Pgpkeymanager mgr = new Pgpkeymanager();

    // generating a pair
    mgr.GeneratePair("Michel Legrand <ml@email.com>", "EDDSA", 0, "ECDH:CURVE25519", 0, "password", 0);

    // creating a keyring object and adding the new pair to the keyring
    Pgpkeyring keyring = new Pgpkeyring();

    keyring.CreateNew();

    keyring.PinnedKey = mgr.Key;
    keyring.AddPinned();

    // exporting the keyring to a file
    keyring.Save("pubkey.pkr", "seckey.skr");
Alternative calls to GeneratePair may look like this:
    mgr.GeneratePair("Michel Legrand <ml@email.com>", "ECDSA:P384", 0, "ECDH", 0, "password", 0);

    mgr.GeneratePair("Michel Legrand <ml@email.com>", "ECDSA:BRAINPOOLP256", 0, "ECDH:BRAINPOOLP256", 0, "password", 0);

    mgr.GeneratePair("Michel Legrand <ml@email.com>", "RSA", 4096, "RSA", 2048, "password", 0);
Supported public key algorithms:

SB_PGP_PUBLIC_KEY_ALGORITHM_RSARSA
SB_PGP_PUBLIC_KEY_ALGORITHM_RSA_ENCRYPTRSA-encrypt
SB_PGP_PUBLIC_KEY_ALGORITHM_RSA_SIGNRSA-sign
SB_PGP_PUBLIC_KEY_ALGORITHM_DSADSA
SB_PGP_PUBLIC_KEY_ALGORITHM_ECDSAECDSA
SB_PGP_PUBLIC_KEY_ALGORITHM_ECDHECDH
SB_PGP_PUBLIC_KEY_ALGORITHM_ELGAMAL_ENCRYPTElgamal-encrypt
SB_PGP_PUBLIC_KEY_ALGORITHM_ELGAMALElgamal
SB_PGP_PUBLIC_KEY_ALGORITHM_EDDSAEDDSA

Supported elliptic curves:

SB_PGP_CURVE_P256P256
SB_PGP_CURVE_P384P384
SB_PGP_CURVE_P521P521
SB_PGP_CURVE_ED25519ED25519
SB_PGP_CURVE_CURVE25519CURVE25519
SB_PGP_CURVE_BRAINPOOLP256R1BRAINPOOLP256
SB_PGP_CURVE_BRAINPOOLP512R1BRAINPOOLP512

Copyright (c) 2022 /n software inc. - All rights reserved.
SecureBlackbox 2020 Kotlin Edition - Version 20.0 [Build 8063]