pki1.h

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

 *  NULL upon error
 *  A pointer to an NSSName upon success
 */

NSS_EXTERN NSSName *
nssName_Create
(
  NSSArena *arenaOpt,
  NSSNameChoice choice,
  void *arg
);

/*
 * nssName_Destroy
 *
 * This routine will destroy a Name object.  It should eventually be
 * called on all Names created without an arena.  While it is not
 * necessary to call it on Names 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_NAME
 *
 * Return value:
 *  PR_FAILURE upon error
 *  PR_SUCCESS upon success
 */

NSS_EXTERN PRStatus
nssName_Destroy
(
  NSSName *name
);

/*
 * nssName_GetDEREncoding
 *
 * This routine will DER-encode a name 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_NAME
 *  NSS_ERROR_NO_MEMORY
 *
 * Return value:
 *  NULL upon error
 *  The DER encoding of this NSSName
 */

NSS_EXTERN NSSDER *
nssName_GetDEREncoding
(
  NSSName *name,
  NSSArena *arenaOpt
);

/*
 * nssName_GetUTF8Encoding
 *
 * This routine returns a UTF8 string containing a string 
 * representation of the Name in the format specified by the 
 * underlying name choice.  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_NAME
 *  NSS_ERROR_NO_MEMORY
 *
 * Return value:
 *  NULL upon error
 *  A pointer to the UTF8 string
 */

NSS_EXTERN NSSUTF8 *
nssName_GetUTF8Encoding
(
  NSSName *name,
  NSSArena *arenaOpt
);

/*
 * nssName_GetChoice
 *
 * This routine returns the type of the choice underlying the specified
 * name.  The return value will be a member of the NSSNameChoice 
 * enumeration.  This routine may return NSSNameChoiceInvalid 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_NAME
 *
 * Return value:
 *  NSSNameChoiceInvalid upon error
 *  An other member of the NSSNameChoice enumeration upon success
 */

NSS_EXTERN NSSNameChoice
nssName_GetChoice
(
  NSSName *name
);

/*
 * nssName_GetRDNSequence
 *
 * If the choice underlying the specified NSSName is that of an 
 * RDNSequence, this routine will return a pointer to that RDN
 * sequence.  Otherwise, this routine will place an error on the
 * error stack, and return NULL.  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.  The
 * caller owns the returned pointer.  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_NAME
 *  NSS_ERROR_WRONG_CHOICE
 *  NSS_ERROR_NO_MEMORY
 *
 * Return value:
 *  NULL upon error
 *  A caller-owned pointer to an NSSRDNSeq
 */

NSS_EXTERN NSSRDNSeq *
nssName_GetRDNSequence
(
  NSSName *name,
  NSSArena *arenaOpt
);

/*
 * nssName_GetSpecifiedChoice
 *
 * If the choice underlying the specified NSSName matches the specified
 * choice, a caller-owned pointer to that underlying object will be
 * returned.  Otherwise, an error will be placed on the error stack and
 * NULL will be returned.  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.  The caller owns the returned
 * pointer.  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_NAME
 *  NSS_ERROR_WRONG_CHOICE
 *  NSS_ERROR_NO_MEMORY
 *
 * Return value:
 *  NULL upon error
 *  A caller-owned pointer, which must be typecast
 */

NSS_EXTERN void *
nssName_GetSpecifiedChoice
(
  NSSName *name,
  NSSNameChoice choice,
  NSSArena *arenaOpt
);

/*
 * nssName_Compare
 *
 * This routine compares two Names for equality.  For two Names to be
 * equal, they must have the same choice of underlying types, and the
 * underlying values must be equal.  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_NAME
 *  NSS_ERROR_INVALID_ARGUMENT
 *
 * Return value:
 *  PR_FAILURE on error
 *  PR_SUCCESS upon a successful comparison (equal or not)
 */

NSS_EXTERN PRStatus
nssName_Compare
(
  NSSName *name1,
  NSSName *name2,
  PRBool *equalp
);

/*
 * nssName_Duplicate
 *
 * This routine duplicates the specified nssname.  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_NAME
 *  NSS_ERROR_NO_MEMORY
 *
 * Return value:
 *  NULL upon error
 *  A pointer to a new NSSName
 */

NSS_EXTERN NSSName *
nssName_Duplicate
(
  NSSName *name,
  NSSArena *arenaOpt
);

/*
 * nssName_GetUID
 *
 * This routine will attempt to derive a user identifier from the
 * specified name, if the choices and content of the name permit.
 * If the Name consists of a Sequence of Relative Distinguished 
 * Names containing a UID attribute, the UID will be the value of 
 * that attribute.  Note that no UID attribute is defined in either 
 * PKIX or PKCS#9; rather, this seems to derive from RFC 1274, which 
 * defines the type as a caseIgnoreString.  We'll return a Directory 
 * String.  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_NAME
 *  NSS_ERROR_NO_UID
 *  NSS_ERROR_NO_MEMORY
 *
 * Return value:
 *  NULL upon error
 *  A pointer to a UTF8 String.
 */

NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
nssName_GetUID
(
  NSSName *name,
  NSSArena *arenaOpt
);

/*
 * nssName_GetEmail
 *
 * This routine will attempt to derive an email address from the
 * specified name, if the choices and content of the name permit.  
 * If the Name consists of a Sequence of Relative Distinguished 
 * Names containing either a PKIX email address or a PKCS#9 email
 * address, the result will be the value of that attribute.  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_NAME
 *  NSS_ERROR_NO_EMAIL
 *  NSS_ERROR_NO_MEMORY
 *
 * Return value:
 *  NULL upon error
 *  A pointer to a UTF8 String
 */

NSS_EXTERN NSSUTF8 * /* XXX fgmr IA5 String */
nssName_GetEmail
(
  NSSName *name,
  NSSArena *arenaOpt
);

/*
 * nssName_GetCommonName
 *
 * This routine will attempt to derive a common name from the
 * specified name, if the choices and content of the name permit.  
 * If the Name consists of a Sequence of Relative Distinguished Names
 * containing a PKIX Common Name, the result will be that 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_NAME
 *  NSS_ERROR_NO_COMMON_NAME
 *  NSS_ERROR_NO_MEMORY
 *
 * Return value:
 *  NULL upon error
 *  A pointer to a UTF8 String
 */

NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
nssName_GetCommonName
(
  NSSName *name,
  NSSArena *arenaOpt
);

/*
 * nssName_GetOrganization
 *
 * This routine will attempt to derive an organisation name from the
 * specified name, if the choices and content of the name permit.  
 * If Name consists of a Sequence of Relative Distinguished names 
 * containing a PKIX Organization, the result will be the value of 
 * that attribute.  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_NAME
 *  NSS_ERROR_NO_ORGANIZATION
 *  NSS_ERROR_NO_MEMORY
 *
 * Return value:
 *  NULL upon error
 *  A pointer to a UTF8 String
 */

NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
nssName_GetOrganization
(
  NSSName *name,
  NSSArena *arenaOpt
);

/*
 * nssName_GetOrganizationalUnits
 *
 * This routine will attempt to derive a sequence of organisational 
 * unit names from the specified name, if the choices and content of 
 * the name permit.  If the Name consists of a Sequence of Relative 
 * Distinguished Names containing one or more organisational units,
 * the result will be the values of those attributes.  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_NAME
 *  NSS_ERROR_NO_ORGANIZATIONAL_UNITS
 *  NSS_ERROR_NO_MEMORY
 *
 * Return value:
 *  NULL upon error
 *  A pointer to a null-terminated array of UTF8 Strings
 */

NSS_EXTERN NSSUTF8 ** /* XXX fgmr DirectoryString */
nssName_GetOrganizationalUnits
(
  NSSName *name,
  NSSArena *arenaOpt
);

/*
 * nssName_GetStateOrProvince
 *
 * This routine will attempt to derive a state or province name from 
 * the specified name, if the choices and content of the name permit.
 * If the Name consists of a Sequence of Relative Distinguished Names
 * containing a state or province, the result will be the value of 
 * that attribute.  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_NAME
 *  NSS_ERROR_NO_STATE_OR_PROVINCE
 *  NSS_ERROR_NO_MEMORY
 *
 * Return value:
 *  NULL upon error
 *  A pointer to a UTF8 String
 */

NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
nssName_GetStateOrProvince
(
  NSSName *name,
  NSSArena *arenaOpt
);

/*
 * nssName_GetLocality
 *
 * This routine will attempt to derive a locality name from the 
 * specified name, if the choices and content of the name permit.  If
 * the Name consists of a Sequence of Relative Distinguished names
 * containing a Locality, the result will be the value of that 
 * attribute.  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_NAME
 *  NSS_ERROR_NO_LOCALITY
 *  NSS_ERROR_NO_MEMORY
 *
 * Return value:
 *  NULL upon error
 *  A pointer to a UTF8 String
 */

NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
nssName_GetLocality
(
  NSSName *name,
  NSSArena *arenaOpt
);

/*
 * nssName_GetCountry
 *
 * This routine will attempt to derive a country name from the 
 * specified name, if the choices and content of the name permit.
 * If the Name consists of a Sequence of Relative Distinguished 
 * Names containing a Country, the result will be the value of
 * that attribute..  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_NAME
 *  NSS_ERROR_NO_COUNTRY
 *  NSS_ERROR_NO_MEMORY
 *
 * Return value:
 *  NULL upon error
 *  A pointer to a UTF8 String
 */

NSS_EXTERN NSSUTF8 * /* XXX fgmr PrintableString */
nssName_GetCountry
(
  NSSName *name,
  NSSArena *arenaOpt
);

/*
 * nssName_GetAttribute
 *
 * If the specified name consists of a Sequence of Relative 
 * Distinguished Names containing an attribute with the specified 
 * type, and the actual value of that attribute may be expressed 
 * with a Directory String, then the value of that attribute will 
 * be returned as a Directory String.  If the optional arena argument