nsspki1.h

来自「支持SSL v2/v3, TLS, PKCS #5, PKCS #7, PKCS」· C头文件 代码 · 共 2,342 行 · 第 1/5 页

 * argument is non-null, the memory required will be obtained from
 * that arena; otherwise, the memory will be obtained from the heap.  
 * This routine may return NULL upon error, in which case it will have 
 * created an error stack.
 *
 * The error may be one of the following values:
 *  NSS_ERROR_INVALID_ATAV
 *  NSS_ERROR_NO_MEMORY
 *
 * Return value:
 *  NULL on error
 *  A pointer to a new ATAV
 */

NSS_EXTERN NSSATAV *
NSSATAV_Duplicate
(
  NSSATAV *atav,
  NSSArena *arenaOpt
);

extern const NSSError NSS_ERROR_INVALID_ATAV;
extern const NSSError NSS_ERROR_NO_MEMORY;

/*
 * NSSRDN
 *
 * The public "methods" regarding this "object" are:
 *
 *  NSSRDN_CreateFromBER   -- constructor
 *  NSSRDN_CreateFromUTF8  -- constructor
 *  NSSRDN_Create          -- constructor
 *  NSSRDN_CreateSimple    -- constructor
 *
 *  NSSRDN_Destroy
 *  NSSRDN_GetDEREncoding
 *  NSSRDN_GetUTF8Encoding
 *  NSSRDN_AddATAV
 *  NSSRDN_GetATAVCount
 *  NSSRDN_GetATAV
 *  NSSRDN_GetSimpleATAV
 *  NSSRDN_Compare
 *  NSSRDN_Duplicate
 */

/*
 * NSSRDN_CreateFromBER
 *
 * This routine creates an NSSRDN by decoding a BER- or DER-encoded 
 * RDN.  If the optional arena argument is non-null, the memory used 
 * will be obtained from that arena; otherwise, the memory will be 
 * obtained from the heap.  This routine may return NULL upon error, 
 * in which case it will have created an error stack.
 *
 * The error may be one of the following values:
 *  NSS_ERROR_INVALID_BER
 *  NSS_ERROR_NO_MEMORY
 *
 * Return value:
 *  NULL upon error
 *  A pointer to an NSSRDN upon success
 */

NSS_EXTERN NSSRDN *
NSSRDN_CreateFromBER
(
  NSSArena *arenaOpt,
  NSSBER *berRDN
);

/*
 * NSSRDN_CreateFromUTF8
 *
 * This routine creates an NSSRDN by decoding an UTF8 string 
 * consisting of either a single ATAV in the "equals" format, e.g., 
 * "uid=smith," or one or more such ATAVs in parentheses, e.g., 
 * "(sn=Smith,ou=Sales)."  If the optional arena argument is non-null,
 * the memory used will be obtained from that arena; otherwise, the
 * memory will be obtained from the heap.  This routine may return
 * NULL upon error, in which case it will have created an error stack.
 *
 * The error may be one of the following values:
 *  NSS_ERROR_UNKNOWN_ATTRIBUTE
 *  NSS_ERROR_INVALID_STRING
 *  NSS_ERROR_NO_MEMORY
 *
 * Return value:
 *  NULL upon error
 *  A pointer to an NSSRDN upon success
 */

NSS_EXTERN NSSRDN *
NSSRDN_CreateFromUTF8
(
  NSSArena *arenaOpt,
  NSSUTF8 *stringRDN
);

/*
 * NSSRDN_Create
 *
 * This routine creates an NSSRDN from one or more NSSATAVs.  The
 * final argument to this routine must be NULL.  If the optional arena
 * argument is non-null, the memory used will be obtained from that
 * arena; otherwise, the memory will be obtained from the heap.  This
 * routine may return NULL upon error, in which case it will have 
 * created an error stack.
 *
 * The error may be one of the following values:
 *  NSS_ERROR_NO_MEMORY
 *  NSS_ERROR_INVALID_ATAV
 *
 * Return value:
 *  NULL upon error
 *  A pointer to an NSSRDN upon success
 */

NSS_EXTERN NSSRDN *
NSSRDN_Create
(
  NSSArena *arenaOpt,
  NSSATAV *atav1,
  ...
);

/*
 * NSSRDN_CreateSimple
 *
 * This routine creates a simple NSSRDN from a single NSSATAV.  If the
 * optional arena argument is non-null, the memory used will be 
 * obtained from that arena; otherwise, the memory will be obtained
 * from the heap.  This routine may return NULL upon error, in which
 * case it will have created an error stack.
 *
 * The error may be one of the following values:
 *  NSS_ERROR_NO_MEMORY
 *  NSS_ERROR_INVALID_ATAV
 *
 * Return value:
 *  NULL upon error
 *  A pointer to an NSSRDN upon success
 */

NSS_EXTERN NSSRDN *
NSSRDN_CreateSimple
(
  NSSArena *arenaOpt,
  NSSATAV *atav
);

/*
 * NSSRDN_Destroy
 *
 * This routine will destroy an RDN object.  It should eventually be
 * called on all RDNs created without an arena.  While it is not 
 * necessary to call it on RDNs created within an arena, it is not an
 * error to do so.  This routine returns a PRStatus value; if
 * successful, it will return PR_SUCCESS.  If unsuccessful, it will 
 * create an error stack and return PR_FAILURE.
 *
 * The error may be one of the following values:
 *  NSS_ERROR_INVALID_RDN
 *
 * Return value:
 *  PR_FAILURE upon failure
 *  PR_SUCCESS upon success
 */

NSS_EXTERN PRStatus
NSSRDN_Destroy
(
  NSSRDN *rdn
);

/*
 * NSSRDN_GetDEREncoding
 *
 * This routine will DER-encode an RDN object.  If the optional arena
 * argument is non-null, the memory used will be obtained from that
 * arena; otherwise, the memory will be obtained from the heap.  This
 * routine may return null upon error, in which case it will have 
 * created an error stack.
 *
 * The error may be one of the following values:
 *  NSS_ERROR_INVALID_RDN
 *  NSS_ERROR_NO_MEMORY
 *
 * Return value:
 *  NULL upon error
 *  The DER encoding of this NSSRDN
 */

NSS_EXTERN NSSDER *
NSSRDN_GetDEREncoding
(
  NSSRDN *rdn,
  NSSArena *arenaOpt
);

/*
 * NSSRDN_GetUTF8Encoding
 *
 * This routine returns a UTF8 string containing a string 
 * representation of the RDN.  A simple (one-ATAV) RDN will be simply
 * the string representation of that ATAV; a non-simple RDN will be in
 * parenthesised form.  If the optional arena argument is non-null, 
 * the memory used will be obtained from that arena; otherwise, the 
 * memory will be obtained from the heap.  This routine may return 
 * null upon error, in which case it will have created an error stack.
 *
 * The error may be one of the following values:
 *  NSS_ERROR_INVALID_RDN
 *  NSS_ERROR_NO_MEMORY
 *
 * Return value:
 *  NULL upon error
 *  A pointer to a UTF8 string
 */

NSS_EXTERN NSSUTF8 *
NSSRDN_GetUTF8Encoding
(
  NSSRDN *rdn,
  NSSArena *arenaOpt
);

/*
 * NSSRDN_AddATAV
 *
 * This routine adds an ATAV to the set of ATAVs in the specified RDN.
 * Remember that RDNs consist of an unordered set of ATAVs.  If the
 * RDN was created with a non-null arena argument, that same arena
 * will be used for any additional required memory.  If the RDN was 
 * created with a NULL arena argument, any additional memory will
 * be obtained from the heap.  This routine returns a PRStatus value;
 * it will return PR_SUCCESS upon success, and upon failure it will
 * create an error stack and return PR_FAILURE.
 *
 * The error may be one of the following values:
 *  NSS_ERROR_INVALID_RDN
 *  NSS_ERROR_INVALID_ATAV
 *  NSS_ERROR_NO_MEMORY
 *
 * Return value:
 *  PR_SUCCESS upon success
 *  PR_FAILURE upon failure
 */

NSS_EXTERN PRStatus
NSSRDN_AddATAV
(
  NSSRDN *rdn,
  NSSATAV *atav
);

/*
 * NSSRDN_GetATAVCount
 *
 * This routine returns the cardinality of the set of ATAVs within
 * the specified RDN.  This routine may return 0 upon error, in which 
 * case it will have created an error stack.
 *
 * The error may be one of the following values:
 *  NSS_ERROR_INVALID_RDN
 *
 * Return value:
 *  0 upon error
 *  A positive number upon success
 */

NSS_EXTERN PRUint32
NSSRDN_GetATAVCount
(
  NSSRDN *rdn
);

/*
 * NSSRDN_GetATAV
 *
 * This routine returns a pointer to an ATAV that is a member of
 * the set of ATAVs within the specified RDN.  While the set of
 * ATAVs within an RDN is unordered, this routine will return
 * distinct values for distinct values of 'i' as long as the RDN
 * is not changed in any way.  The RDN may be changed by calling
 * NSSRDN_AddATAV.  The value of the variable 'i' is on the range
 * [0,c) where c is the cardinality returned from NSSRDN_GetATAVCount.
 * The caller owns the ATAV the pointer to which is returned.  If the
 * optional arena argument is non-null, the memory used will be 
 * obtained from that arena; otherwise, the memory will be obtained
 * from the heap.  This routine may return NULL upon error, in which 
 * case it will have created an error stack.
 *
 * The error may be one of the following values:
 *  NSS_ERROR_INVALID_RDN
 *  NSS_ERROR_VALUE_OUT_OF_RANGE
 *  NSS_ERROR_NO_MEMORY
 *
 * Return value:
 *  NULL upon error
 *  A caller-owned pointer to an NSSATAV
 */

NSS_EXTERN NSSATAV *
NSSRDN_GetATAV
(
  NSSRDN *rdn,
  NSSArena *arenaOpt,
  PRUint32 i
);

/*
 * NSSRDN_GetSimpleATAV
 *
 * Most RDNs are actually very simple, with a single ATAV.  This 
 * routine will return the single ATAV from such an RDN.  The caller
 * owns the ATAV the pointer to which is returned.  If the optional
 * arena argument is non-null, the memory used will be obtained from
 * that arena; otherwise, the memory will be obtained from the heap.
 * This routine may return NULL upon error, including the case where
 * the set of ATAVs in the RDN is nonsingular.  Upon error, this
 * routine will have created an error stack.
 *
 * The error may be one of the following values:
 *  NSS_ERROR_INVALID_RDN
 *  NSS_ERROR_RDN_NOT_SIMPLE
 *  NSS_ERROR_NO_MEMORY
 *
 * Return value:
 *  NULL upon error
 *  A caller-owned pointer to an NSSATAV
 */

NSS_EXTERN NSSATAV *
NSSRDN_GetSimpleATAV
(
  NSSRDN *rdn,
  NSSArena *arenaOpt
);

/*
 * NSSRDN_Compare
 *
 * This routine compares two RDNs for equality.  For two RDNs to be
 * equal, they must have the same number of ATAVs, and every ATAV in
 * one must be equal to an ATAV in the other.  (Note that the sets
 * of ATAVs are unordered.)  The result of the comparison will be
 * stored at the location pointed to by the "equalp" variable, which
 * must point to a valid PRBool.  This routine may return PR_FAILURE
 * upon error, in which case it will have created an error stack.
 *
 * The error may be one of the following values:
 *  NSS_ERROR_INVALID_RDN
 *  NSS_ERROR_INVALID_ARGUMENT
 *
 * Return value:
 *  PR_FAILURE on error
 *  PR_SUCCESS upon a successful comparison (equal or not)
 */

NSS_EXTERN PRStatus
NSSRDN_Compare
(
  NSSRDN *rdn1,
  NSSRDN *rdn2,
  PRBool *equalp
);

/*
 * NSSRDN_Duplicate
 *
 * This routine duplicates the specified RDN.  If the optional arena
 * argument is non-null, the memory required will be obtained from
 * that arena; otherwise, the memory will be obtained from the heap.
 * This routine may return NULL upon error, in which case it will have
 * created an error stack.
 *
 * The error may be one of the following values:
 *  NSS_ERROR_INVALID_RDN
 *  NSS_ERROR_NO_MEMORY
 *
 * Return value:
 *  NULL on error
 *  A pointer to a new RDN
 */

NSS_EXTERN NSSRDN *
NSSRDN_Duplicate
(
  NSSRDN *rdn,
  NSSArena *arenaOpt
);

/*
 * NSSRDNSeq
 *
 * The public "methods" regarding this "object" are:
 *
 *  NSSRDNSeq_CreateFromBER   -- constructor
 *  NSSRDNSeq_CreateFromUTF8  -- constructor
 *  NSSRDNSeq_Create          -- constructor
 *
 *  NSSRDNSeq_Destroy
 *  NSSRDNSeq_GetDEREncoding
 *  NSSRDNSeq_GetUTF8Encoding
 *  NSSRDNSeq_AppendRDN
 *  NSSRDNSeq_GetRDNCount
 *  NSSRDNSeq_GetRDN
 *  NSSRDNSeq_Compare
 *  NSSRDNSeq_Duplicate
 */

/*
 * NSSRDNSeq_CreateFromBER
 *
 * This routine creates an NSSRDNSeq by decoding a BER- or DER-encoded 
 * sequence of RDNs.  If the optional arena argument is non-null,
 * the memory used will be obtained from that arena; otherwise, the
 * memory will be obtained from the heap.  This routine may return 
 * NULL upon error, in which case it will have created an error stack.
 *
 * The error may be one of the following values:
 *  NSS_ERROR_INVALID_BER
 *  NSS_ERROR_NO_MEMORY
 *
 * Return value:
 *  NULL upon error
 *  A pointer to an NSSRDNSeq upon success
 */

NSS_EXTERN NSSRDNSeq *
NSSRDNSeq_CreateFromBER
(
  NSSArena *arenaOpt,
  NSSBER *berRDNSeq
);

/*
 * NSSRDNSeq_CreateFromUTF8
 *
 * This routine creates an NSSRDNSeq by decoding a UTF8 string
 * consisting of a comma-separated sequence of RDNs, such as
 * "(sn=Smith,ou=Sales),o=Acme,c=US."  If the optional arena argument
 * is non-null, the memory used will be obtained from that arena; 
 * otherwise, the memory will be obtained from the heap.  This routine
 * may return NULL upon error, in which case it will have created an
 * error stack.
 *
 * The error may be one of the following values:
 *  NSS_ERROR_UNKNOWN_ATTRIBUTE
 *  NSS_ERROR_INVALID_STRING
 *  NSS_ERROR_NO_MEMORY
 *
 * Return value:
 *  NULL upon error
 *  A pointer to an NSSRDNSeq upon success
 */

NSS_EXTERN NSSRDNSeq *
NSSRDNSeq_CreateFromUTF8
(
  NSSArena *arenaOpt,
  NSSUTF8 *stringRDNSeq
);

/*
 * NSSRDNSeq_Create
 *
 * This routine creates an NSSRDNSeq from one or more NSSRDNs.  The
 * final argument to this routine must be NULL.  If the optional arena