Key pair

A key pair consists of a private and a public key, and constitutes an actor. Along with a store, a key pair enables storing private data, publishing public data, and sending messages to other actors. For most applications, the actor with document implementation is sufficient.

Generating a key pair

KeyPair keyPair = KeyPair.generate();

var keyPair = cds.generateKeyPair();

my $keyPair = CDS::KeyPair->generate;

Generates a new key pair and returns the corresponding KeyPair instance with an empty account list.

			GenerateKeyPair.Done done = new GenerateKeyPair.Done() {
				void onKeyPairGenerated(KeyPair keyPair) {
					...
				}
			};

			new GenerateKeyPair(done);
		

var done = cds.generateKeyPairAsync();
done.onDone = function(keyPair) { ... };

Creating a key pair instance

KeyPair keyPair = new KeyPair(publicKey, rsaPrivateKey);

var keyPair = new KeyPair(publicKey, rsaPrivateKey);

my $keyPair = CDS::KeyPair->new($publicKey, $rsaPrivateKey);

Creates an instance given a public key and the corresponding private key.

Serialization

		Record record = keyPair.toRecord();
		String hexString = keyPair.toHex();
	

		var record = keyPair.toRecord();
		var hexString = keyPair.toHex();
	

		my $record = $keyPair->toRecord;
		my $hexString = $keyPair->toHex;
	

Serializes the public key object and the private key parameters into a (hex-encoded) record with the following structure:

e
  public exponent
p
  prime 1
q
  prime 2
public key object
  public key object

e, p and q are the RSA coefficients of the private key. The public key object holds the corresponding public key. Its hash is the actor's identifier.

		KeyPair keyPair = KeyPair.from(file);
		KeyPair keyPair = KeyPair.from(record);
		KeyPair keyPair = KeyPair.fromHex(hexString);
	

		var keyPair = cds.keyPairFromRecord(record);
		var keyPair = cds.keyPairFromHex(hexString);

		// Web browsers
		var keyPair = cds.keyPairFromLocalStorage();

		// NodeJS
		var keyPair = cds.keyPairFromFileSync(file);
		var operation = cds.keyPairFromFile(file);

		operation.onDone = function(keyPair) {
			...
		};

		operation.onFailed = function() {
			...
		};
	

		my $keyPair = CDS::KeyPair->fromFile($filename);
		my $keyPair = CDS::KeyPair->fromRecord($record);
		my $keyPair = CDS::KeyPair->fromHex($hexString);
	

Creates an instance from a file, record, or hex-encoded record.

toRecord / fromRecord should be preferred over toHex / fromHex. The hex-string format should only be used if the storage medium cannot handle binary data, e.g. an INI-file, JSON-encoded data, or a sheet of paper.

Cryptographic operations

		Bytes encryptedBytes = keyPair.publicKey.encrypt(plainBytes);
		byte[] plainBytes = keyPair.decrypt(encryptedBytes);
		Bytes signatureBytes = keyPair.sign(digestBytes);
		Bytes signatureBytes = keyPair.sign(hash);
		boolean ok = keyPair.publicKey.verify(digestBytes, signatureBytes);
		boolean ok = keyPair.publicKey.verify(hash, signatureBytes);
	

		var encryptedBytes = keyPair.publicKey.encrypt(plainBytes);
		var plainBytes = keyPair.decrypt(encryptedBytes);
		var signatureBytes = keyPair.sign(digestBytes);
		var signatureBytes = keyPair.signHash(hash);
		var ok = keyPair.publicKey.verifyHash(hash, signatureBytes);
	

		my $encryptedBytes = $keyPair->publicKey->encrypt($plainBytes);
		my $plainBytes = $keyPair->decrypt($encryptedBytes);
		my $signatureBytes = $keyPair->sign($digestBytes);
		my $signatureBytes = $keyPair->signHash($hash);
		my $ok = $keyPair->publicKey->verifyHash($hash, $signatureBytes);
	

Uses the key pair to encrypt and decrypt digests, as well as sign hashes and verify signatures.

You rarely need these operations directly, as functions for creating and opening envelopes are available.

See also