RWAsymmetricKey Class Reference
[Secure Sockets]

Encapsulates the underlying cryptographic library's representation of the asymmetric key. More...

#include <rw/secsock/RWAsymmetricKey.h>

Inheritance diagram for RWAsymmetricKey:

List of all members.

Public Member Functions
	RWAsymmetricKey (const char **pubKeyData, int numLines, RWPasswordCallback cb=0)
	RWAsymmetricKey (std::istream &is, RWPasswordCallback cb=0)
	RWAsymmetricKey (const RWAsymmetricKey &second)
	~RWAsymmetricKey (void)
RWAsymmetricKey &	operator= (const RWAsymmetricKey &second)
RWAsymmetricKeyRep	getRep (void) const
Related Functions
(Note that these are not member functions.)
typedef EVP_PKEY *	RWAsymmetricKeyRep
typedef int(*	RWPasswordCallback )(char *buf, int len, int flag)

---

Detailed Description

RWAsymmetricKey encapsulates the underlying cryptographic library's representation of the asymmetric key. Public and private keys are identical in structure. Typedefs from RWAsymmetricKey to RWPublicKey and RWPrivateKey are provided.

RWAsymmetricKey uses the handle-body idiom to take over memory management from the cryptographic library.

The handle-body implementation of RWAsymmetricKey enables you to pass handles by value with the same cost as passing a class by pointer or reference. This implementation also ensures that the body and the associated memory are not destroyed until all handles referring to that body are destroyed.

RWAsymmetricKey constructors throw an RWUnableToReadPrivateKeyError exception if the data is not in PEM format. They also throw RWSecureSocketNoCallbackSpecifiedError if your application passes an encrypted key, but does not name a password callback.

Other errors, including invalid key data, are detected only when the key is used in other functions. For this reason, you should validate keys by calling RWSecureSocketContext::checkPrivateKey() after assigning a certificate and private key to a context object.

Note:

For a full discussion of the handle-body idiom, see Section 7.3.1, "Understanding the Handle-Body Idiom," in the Threads Module User's Guide.

---

Constructor & Destructor Documentation

RWAsymmetricKey::RWAsymmetricKey	(	const char **	pubKeyData,
		int	numLines,
		RWPasswordCallback	cb = 0
	)

Constructs a key from the data pointed to by pubKeyData. pubKeyData is a pointer to an array of C-style strings that contain the PEM-encoded key. Each line of a PEM-encoded key is an element in the array of strings.

numLines is the number of lines in the pubKeyData array. For example, if you are passing the pointer kData as the first parameter to this constructor, you should pass sizeof(kData)/sizeof(kData[0]) as the second parameter to this constructor.

If the key is encrypted, you must use cb to pass a callback function that provides the passphrase to the system. For more information, see the Secure Communication Module User's Guide.

This constructor throws RWSecureSocketUnderlyingAllocationError if the cryptographic library is unable to allocate memory. It throws RWSecureSocketNoCallbackSpecifiedError if your application passes an encrypted key, but does not name a password callback.

RWAsymmetricKey::RWAsymmetricKey	(	std::istream &	is,
		RWPasswordCallback	cb = 0
	)

Constructs a key from PEM-format data in the std::istream. If the key is encrypted, you must use cb to pass a callback function that provides the passphrase to the system. For more information, see the Secure Communication Module User's Guide.

This constructor reads from the std::istream until an EOF is read. Instances of std::ifstream automatically end transmissions with an EOF. For example, if you pass an RWPortalIstream that ultimately reads from a socket, the stream only enters the EOF state when the sending socket is closed.

This constructor throws RWSecureSocketUnderlyingAllocationError if the cryptographic library is unable to allocate memory. It throws RWSecureSocketNoCallbackSpecifiedError if your application passes an encrypted key, but does not name a password callback.

RWAsymmetricKey::RWAsymmetricKey

(

const RWAsymmetricKey &

second

)

[inline]

Copy constructor.

RWAsymmetricKey::~RWAsymmetricKey

(

void

)

[inline]

Destructor.

---

Member Function Documentation

RWAsymmetricKeyRep RWAsymmetricKey::getRep

(

void

)

const [inline]

Returns a pointer to the cryptographic library's representation of the key.

RWAsymmetricKey & RWAsymmetricKey::operator=

(

const RWAsymmetricKey &

second

)

[inline]

Assignment operator.

---

Friends And Related Function Documentation

typedef EVP_PKEY* RWAsymmetricKeyRep [related]

This is the internal private key representation.

typedef int(* RWPasswordCallback)(char *buf, int len, int flag) [related]

A typedef for a callback function that is invoked when an attempt is made to decrypt a key. The password callback supplies the password with which the key was encrypted.

Parameters:

	buf	The buffer into which the null terminated password string must be copied.
	len	The size of the buffer pointed to by buf. The length of the password string plus the null terminator must be less than or equal to this value.
	flag	Indicates how the supplied password is to be used. The value will be 0 when the password is to be used to decrypt a key and 1 when the password is to be used to encrypt a key. This parameter can safely be ignored because the Secure Sockets package only uses the callback for key decryption.

Returns:

The number of characters written into the buffer buf.