SourcePro® API Reference Guide

 
List of all members | Public Member Functions | Related Functions
RWAsymmetricKey Class Reference

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

#include <rw/secsock/RWAsymmetricKey.h>

Inheritance diagram for RWAsymmetricKey:
RWHandleBase

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)
 
RWAsymmetricKeyRep getRep (void) const
 
RWAsymmetricKeyoperator= (const RWAsymmetricKey &second)
 
- Public Member Functions inherited from RWHandleBase
bool isValid (void) const
 
bool operator!= (const RWHandleBase &second) const
 
bool operator< (const RWHandleBase &second) const
 
bool operator== (const RWHandleBase &second) const
 

Related Functions

(Note that these are not member functions.)

typedef EVP_PKEY * RWAsymmetricKeyRep
 
typedef int(* RWPasswordCallback) (char *buf, int len, int flag)
 

Additional Inherited Members

- Protected Member Functions inherited from RWHandleBase
 RWHandleBase (void)
 
 RWHandleBase (RWStaticCtor)
 
 RWHandleBase (RWBodyBase *body)
 
 RWHandleBase (const RWHandleBase &second)
 
 ~RWHandleBase (void)
 
RWBodyBasebody (void) const
 
RWHandleBaseoperator= (const RWHandleBase &second)
 

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
bufThe buffer into which the null terminated password string must be copied.
lenThe 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.
flagIndicates 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.

Copyright © 2023 Rogue Wave Software, Inc., a Perforce company. All Rights Reserved.