pki1.h

支持SSL v2/v3, TLS, PKCS #5, PKCS #7, PKCS #11, PKCS #12, S/MIME, X.509v3证书等安全协议或标准的开发库编译用到NSPR

/*
 * 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
 * placed an error on the 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 non-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_EvaluateUTF8 -- not an object method
 */

/*
 * 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 set an error on the
 * 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 set an error
 * on the error stack.
 *
 * The error may be one of the following values:
 *  NSS_ERROR_UNKNOWN_ATTRIBUTE
 *  NSS_ERROR_INVALID_UTF8
 *  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
 * 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 set
 * an error on the error stack.
 *
 * The error may be one of the following values:
 *  NSS_ERROR_NO_MEMORY
 *  NSS_ERROR_INVALID_RDN
 *
 * Return value:
 *  NULL upon error
 *  A pointero to an NSSRDNSeq upon success
 */

NSS_EXTERN NSSRDNSeq *
nssRDNSeq_Create
(
  NSSArena *arenaOpt,
  NSSRDN *rdn1,
  ...
);

/*
 * nssRDNSeq_Destroy
 *
 * This routine will destroy an RDNSeq object.  It should eventually 
 * be called on all RDNSeqs created without an arena.  While it is not
 * necessary to call it on RDNSeqs 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
 * set an error on the error stack and return PR_FAILURE.
 *
 * The error may be one of the following values:
 *  NSS_ERROR_INVALID_RDNSEQ
 *
 * Return value:
 *  PR_FAILURE upon error
 *  PR_SUCCESS upon success
 */

NSS_EXTERN PRStatus
nssRDNSeq_Destroy
(
  NSSRDNSeq *rdnseq
);

/*
 * nssRDNSeq_GetDEREncoding
 *
 * This routine will DER-encode an RDNSeq 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
 * set an error on the error stack.
 *
 * The error may be one of the following values:
 *  NSS_ERROR_INVALID_RDNSEQ
 *  NSS_ERROR_NO_MEMORY
 *
 * Return value:
 *  NULL upon error
 *  The DER encoding of this NSSRDNSeq
 */

NSS_EXTERN NSSDER *
nssRDNSeq_GetDEREncoding
(
  NSSRDNSeq *rdnseq,
  NSSArena *arenaOpt
);

/*
 * nssRDNSeq_GetUTF8Encoding
 *
 * This routine returns a UTF8 string containing a string 
 * representation of the RDNSeq as a comma-separated 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 set an error on the error stack.
 *
 * The error may be one of the following values:
 *  NSS_ERROR_INVALID_RDNSEQ
 *  NSS_ERROR_NO_MEMORY
 *
 * Return value:
 *  NULL upon error
 *  A pointer to the UTF8 string
 */

NSS_EXTERN NSSUTF8 *
nssRDNSeq_GetUTF8Encoding
(
  NSSRDNSeq *rdnseq,
  NSSArena *arenaOpt
);

/*
 * nssRDNSeq_AppendRDN
 *
 * This routine appends an RDN to the end of the existing RDN 
 * sequence.  If the RDNSeq was created with a non-null arena 
 * argument, that same arena will be used for any additional required
 * memory.  If the RDNSeq 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 set an error on the error stack and return
 * PR_FAILURE.
 *
 * The error may be one of the following values:
 *  NSS_ERROR_INVALID_RDNSEQ
 *  NSS_ERROR_INVALID_RDN
 *  NSS_ERROR_NO_MEMORY
 *
 * Return value:
 *  PR_SUCCESS upon success
 *  PR_FAILURE upon failure
 */

NSS_EXTERN PRStatus
nssRDNSeq_AppendRDN
(
  NSSRDNSeq *rdnseq,
  NSSRDN *rdn
);

/*
 * nssRDNSeq_GetRDNCount
 *
 * This routine returns the cardinality of the sequence of RDNs within
 * the specified RDNSeq.  This routine may return 0 upon error, in 
 * which case it will have set an error on the error stack.
 *
 * The error may be one of the following values:
 *  NSS_ERROR_INVALID_RDNSEQ
 *
 * Return value:
 *  0 upon error
 *  A positive number upon success
 */

NSS_EXTERN PRUint32
nssRDNSeq_GetRDNCount
(
  NSSRDNSeq *rdnseq
);

/*
 * nssRDNSeq_GetRDN
 *
 * This routine returns a pointer to the i'th RDN in the sequence of
 * RDNs that make up the specified RDNSeq.  The sequence begins with
 * the top-level (e.g., "c=US") RDN.  The value of the variable 'i'
 * is on the range [0,c) where c is the cardinality returned from
 * NSSRDNSeq_GetRDNCount.  The caller owns the RDN the pointer to which
 * is returned.  If the optional arena argument is non-null, the memory
 * used will be obtained from that areana; otherwise, the memory will 
 * be obtained from the heap.  This routine may return NULL upon error,
 * in which case it will have set an error upon the error stack.  Note
 * that the usual UTF8 representation of RDN Sequences is from last
 * to first.
 *
 * The error may be one of the following values:
 *  NSS_ERROR_INVALID_RDNSEQ
 *  NSS_ERROR_VALUE_OUT_OF_RANGE
 *  NSS_ERROR_NO_MEMORY
 *
 * Return value:
 *  NULL upon error
 *  A caller-owned pointer to an NSSRDN
 */

NSS_EXTERN NSSRDN *
nssRDNSeq_GetRDN
(
  NSSRDNSeq *rdnseq,
  NSSArena *arenaOpt,
  PRUint32 i
);

/*
 * nssRDNSeq_Compare
 *
 * This routine compares two RDNSeqs for equality.  For two RDNSeqs to 
 * be equal, they must have the same number of RDNs, and each RDN in
 * one sequence must be equal to the corresponding RDN in the other
 * sequence.  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 set an error on the error stack.
 *
 * The error may be one of the following values:
 *  NSS_ERROR_INVALID_RDNSEQ
 *  NSS_ERROR_INVALID_ARGUMENT
 *
 * Return value:
 *  PR_FAILURE on error
 *  PR_SUCCESS upon a successful comparison (equal or not)
 */

NSS_EXTERN PRStatus
nssRDNSeq_Compare
(
  NSSRDNSeq *rdnseq1,
  NSSRDNSeq *rdnseq2,
  PRBool *equalp
);

/*
 * nssRDNSeq_Duplicate
 *
 * This routine duplicates the specified RDNSeq.  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 
 * placed an error on the error stack.
 *
 * The error may be one of the following values:
 *  NSS_ERROR_INVALID_RDNSEQ
 *  NSS_ERROR_NO_MEMORY
 *
 * Return value:
 *  NULL upon error
 *  A pointer to a new RDNSeq
 */

NSS_EXTERN NSSRDNSeq *
nssRDNSeq_Duplicate
(
  NSSRDNSeq *rdnseq,
  NSSArena *arenaOpt
);

/*
 * nssRDNSeq_EvaluateUTF8
 *
 * This routine evaluates a UTF8 string, and returns PR_TRUE if the 
 * string contains the string representation of an RDNSeq.  This 
 * routine is used by the (directory) Name routines 
 * nssName_CreateFromUTF8 and nssName_EvaluateUTF8 to determine which
 * choice of directory name the string may encode.  This routine may 
 * return PR_FALSE upon error, but it subsumes that condition under the
 * general "string does not evaluate as an RDNSeq" state, and does not
 * set an error on the error stack.
 *
 * Return value:
 *  PR_TRUE if the string represents an RDNSeq
 *  PR_FALSE if otherwise
 */

NSS_EXTERN PRBool
nssRDNSeq_EvaluateUTF8
(
  NSSUTF8 *str
);

/*
 * NSSName
 *
 * The non-public "methods" regarding this "object" are:
 *
 * nssName_CreateFromBER   -- constructor
 * nssName_CreateFromUTF8  -- constructor
 * nssName_Create          -- constructor
 *
 * nssName_Destroy
 * nssName_GetDEREncoding
 * nssName_GetUTF8Encoding
 * nssName_GetChoice
 * nssName_GetRDNSequence
 * nssName_GetSpecifiedChoice
 * nssName_Compare
 * nssName_Duplicate
 *
 * nssName_GetUID
 * nssName_GetEmail
 * nssName_GetCommonName
 * nssName_GetOrganization
 * nssName_GetOrganizationalUnits
 * nssName_GetStateOrProvince
 * nssName_GetLocality
 * nssName_GetCountry
 * nssName_GetAttribute
 *
 * nssName_EvaluateUTF8 -- not an object method
 */

/*
 * nssName_CreateFromBER
 *
 * This routine creates an NSSName by decoding a BER- or DER-encoded 
 * (directory) Name.  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 set an error
 * on the 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 NSSName upon success
 */

NSS_EXTERN NSSName *
nssName_CreateFromBER
(
  NSSArena *arenaOpt,
  NSSBER *berName
);

/*
 * nssName_CreateFromUTF8
 *
 * This routine creates an NSSName by decoding a UTF8 string 
 * consisting of the string representation of one of the choices of 
 * (directory) names.  Currently the only choice is an RDNSeq.  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.  The routine may return NULL upon error, in which
 * case it will have set an error on the error stack.
 *
 * The error may be one of the following values:
 *  NSS_ERROR_INVALID_UTF8
 *  NSS_ERROR_NO_MEMORY
 *
 * Return value:
 *  NULL upon error
 *  A pointer to an NSSName upon success
 */

NSS_EXTERN NSSName *
nssName_CreateFromUTF8
(
  NSSArena *arenaOpt,
  NSSUTF8 *stringName
);

/*
 * nssName_Create
 *
 * This routine creates an NSSName with the specified choice of
 * underlying name types.  The value of the choice variable must be
 * one of the values of the NSSNameChoice enumeration, and the type
 * of the arg variable must be as specified in the following table:
 *
 *   Choice                     Type
 *   ========================   ===========
 *   NSSNameChoiceRdnSequence   NSSRDNSeq *
 *
 * 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 set an error on the error stack.
 *
 * The error may be one of the following values:
 *  NSS_ERROR_INVALID_CHOICE
 *  NSS_ERROR_INVALID_ARGUMENT
 *  NSS_ERROR_NO_MEMORY
 *
 * Return value: