MDN may have intermittent access issues April 18 13:00 - April 19 01:00 UTC. See whistlepig.mozilla.org for all notifications.

mozilla
Your Search Results

    ssltyp.html

    • This page is part of the SSL Reference that we are migrating into the format described in the MDN Style Guide. If you are inclined to help with this migration, your help would be very much appreciated.

    Selected SSL Types and Structures

     


    Chapter 3
    Selected SSL Types and Structures

    This chapter describes some of the most important types and structures used with the functions described in the rest of this document, and how to manage the memory used for them. Additional types are described with the functions that use them or in the header files.

    Types and Structures
    Managing SECItem Memory

     

    Types and Structures

    These types and structures are described here:

    CERTCertDBHandle
    CERTCertificate
    PK11SlotInfo
    SECItem
    SECKEYPrivateKey
    SECStatus

    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 NSPR Reference.

    <a name="> 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 structures are shared objects. When an application makes a copy of a particular certificate 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 call CERT_DestroyCertificate, the function decrements the reference count and, if the reference count reaches zero as a result, frees the memory. The use of the word "destroy" in function names or in the description of a function often implies reference counting.

    Never alter the contents of a certificate 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

    A SECItem 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

    Key structures are not shared objects. When an application makes a copy of a particular key structure that already exists in memory, SSL makes a deep copy--that is, it makes a whole new copy of that object. When you call SECKEY_DestroyPrivateKey, the function both frees the memory and sets all the bits to zero.

    Never alter the contents of a key structure. Treat the structure as read only.

    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

    Reserved for internal use.

    SECFailure

    The operation failed. To find out why, call PR_GetError.

    SECSuccess

    The operation succeeded. In this case the value returned by PR_GetError is meaningless.

     

    Managing SECItem Memory

    These functions are available for managing the memory associated with SECItem structures and the structures to which they point.

    SECItem_FreeItem
    SECItem_ZfreeItem

    SECItem_FreeItem

    Frees the memory associated with a SECItem structure.

    Syntax
    #include <prtypes.h> 
    SECStatus SECItem_FreeItem (
       SECItem *item,
       PRBool freeItem)
    Parameter

    This function has the following parameter:

    item

    A pointer to a SECItem structure.

    freeItem

    When PR_FALSE, free only the structure pointed to. Otherwise, free both the structure pointed to and the SECItem structure itself.

    Returns

    The function returns one of these values:

    Description

    This function 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 frees the item structure itself.

     

    SECItem_ZfreeItem

    Zeroes and frees the memory associated with a SECItem structure.

    Syntax
    #include <prtypes.h> 
    SECStatus SECItem_ZfreeItem (
       SECItem *item,
       PRBool freeItem)
    Parameter

    This function has the following parameter:

    item

    A pointer to a SECItem structure.

    freeItem

    When PR_FALSE, free only the structure pointed to. Otherwise, free both the structure pointed to and the SECItem structure itself.

    Returns

    The function returns one of these values:

    Description

    This function is similar to SECItem_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.

    Document Tags and Contributors

    Contributors to this page: kwilson, Sheppy
    Last updated by: Sheppy,