Chapter 3
Selected SSL Types and Structures
Managing SECItem Memory
Types and Structures
These types and structures are described here:CERTCertDBHandleCERTCertificatePK11SlotInfoSECItemSECKEYPrivateKeySECStatus
Additional types used by a single function only are described with the function's entry in each chapter. Some of these functions also use types defined by NSPR and described in the
Many of the structures presented here (CERTCertDBHandle, CERTCertificate, PK11SlotInfo, and SECKEYPrivateKey) are opaque--that is, they are types defined as structures (for example, CERTCertDBHandleStr) that may change in future releases of Network Security Services. As long as you use the form shown here, your code will not need revision.
CERTCertDBHandle
An opaque handle structure for open certificate databases.Syntax
#include <certt.h>typedef struct CERTCertDBHandleStr CERTCertDBHandle;
CERTCertificate
An opaque X.509 certificate object.Syntax
#include <certt.h>typedef struct CERTCertificateStr CERTCertificate;
Description
Certificate and key structures are shared objects. When an application makes a copy of a particular certificate or key structure that already exists in memory, SSL makes a shallow copy--that is, it increments the reference count for that object rather than making a whole new copy. When you callCERT_DestroyCertificate or SECKEY_DestroyPrivateKey, the function decrements the reference count and, if the reference count reaches zero as a result, both frees the memory and sets all the bits to zero. The use of the word "destroy" in function names or in the description of a function implies reference counting.
Never alter the contents of a certificate or key structure. If you attempt to do so, the change affects all the shallow copies of that structure and can cause severe problems.
PK11SlotInfo
An opaque structure representing a physical or logical PKCS #11 slot.Syntax
#include <pk11expt.h>
typedef struct PK11SlotInfoStr PK11SlotInfo;
SECItem
A structure that points to other structures.Syntax
#include <seccomon.h>
#include <prtypes.h>
#include <secport.h>
typedef enum {
siBuffer,
siClearDataBuffer,
siCipherDataBuffer,
siDERCertBuffer,
siEncodedCertBuffer,
siDERNameBuffer,
siEncodedNameBuffer,
siAsciiNameString,
siAsciiString,
siDEROID
} SECItemType;
typedef struct SECItemStr SECItem;
struct SECItemStr {
SECItemType type;
unsigned char *data;
unsigned int len;
};
Description
ASECItem structure can be used to associate your own data with an SSL socket.
To free a structure pointed to by a SECItem, and, if desired, the SECItem structure itself, use one the functions SECItem_FreeItem or SECItem_ZfreeItem.
SECKEYPrivateKey
An opaque, generic key structure.Syntax
#include <keyt.h>typedef struct SECKEYPrivateKeyStr SECKEYPrivateKey;
Description
Certificate and key structures are shared objects. When an application makes a copy of a particular certificate or key structure that already exists in memory, SSL makes a shallow copy--that is, it increments the reference count for that object rather than making a whole new copy. When you callCERT_DestroyCertificate or SECKEY_DestroyPrivateKey, the function decrements the reference count and, if the reference count reaches zero as a result, both frees the memory and sets all the bits to zero. The use of the word "destroy" in function names or in the description of a function implies reference counting.
Never alter the contents of a certificate or key structure. If you attempt to do so, the change affects all the shallow copies of that structure and can cause severe problems.
SECStatus
The return value for many SSL functions.Syntax
#include <seccomon.h>typedef enum {
SECWouldBlock = -2,
SECFailure = -1,
SECSuccess = 0
} SECStatus;
Enumerators
The enum includes the following enumerators:SECWouldBlock | |
SECFailure | |
SECSuccess |
The operation succeeded. In this case the value returned by |
Managing SECItem Memory
These functions are available for managing the memory associated withSECItem structures and the structures to which they point.
SECItem_FreeItemSECItem_ZfreeItemSECItem_FreeItem
Frees the memory associated with aSECItem structure.
Syntax
#include <prtypes.h>
SECStatus SECItem_FreeItem (
SECItem *item,
PRBool freeItem)
Parameter
This function has the following parameter:Returns
The function returns one of these values:-
If successful,
SECSuccess. -
If unsuccessful,
SECFailure. Use PR_GetErrorto retrieve the error code.
Description
This function frees the memory associated with the structure to which the specified item points, when that structure is no longer used. WhenfreeItem is not PR_FALSE, also frees the item structure itself.
SECItem_ZfreeItem
Zeroes and frees the memory associated with aSECItem structure.
Syntax
#include <prtypes.h>
SECStatus SECItem_ZfreeItem (
SECItem *item,
PRBool freeItem)
Parameter
This function has the following parameter:Returns
The function returns one of these values:-
If successful,
SECSuccess. -
If unsuccessful,
SECFailure. Use PR_GetErrorto retrieve the error code.
Description
This function is similar toSECItem_FreeItem, except that it overwrites the structures to be freed with zeroes before it frees them. Zeros and frees the memory associated with the structure to which the specified item points, when that structure is no longer used. When freeItem is not PR_FALSE, also zeroes and frees the item structure itself.
Table of Contents | Previous | Next | Index
Last Updated: 10/18/00 09:17:43