pki1.h

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

 * 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_ATTRIBUTE
 *  NSS_ERROR_ATTRIBUTE_VALUE_NOT_STRING
 *
 * Return value:
 *  NULL upon error
 *  A pointer to a UTF8 String
 */

NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
nssName_GetAttribute
(
  NSSName *name,
  NSSOID *attribute,
  NSSArena *arenaOpt
);

/*
 * nssName_EvaluateUTF8
 *
 * This routine evaluates a UTF8 string, and returns PR_TRUE if the 
 * string contains the string representation of an NSSName.  This 
 * routine is used by the GeneralName routine 
 * nssGeneralName_CreateFromUTF8 to determine which choice of
 * general 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 a Name" state, and does not
 * set an error on the error stack.
 * 
 * Return value:
 *  PR_TRUE if the string represents a Name
 *  PR_FALSE otherwise
 */

NSS_EXTERN PRBool
nssName_EvaluateUTF8
(
  NSSUTF8 *str
);

/*
 * NSSGeneralName
 *
 * The non-public "methods" regarding this "object" are:
 *
 * nssGeneralName_CreateFromBER   -- constructor
 * nssGeneralName_CreateFromUTF8  -- constructor
 * nssGeneralName_Create          -- constructor
 *
 * nssGeneralName_Destroy
 * nssGeneralName_GetDEREncoding
 * nssGeneralName_GetUTF8Encoding
 * nssGeneralName_GetChoice
 * nssGeneralName_GetOtherName
 * nssGeneralName_GetRfc822Name
 * nssGeneralName_GetDNSName
 * nssGeneralName_GetX400Address
 * nssGeneralName_GetDirectoryName
 * nssGeneralName_GetEdiPartyName
 * nssGeneralName_GetUniformResourceIdentifier
 * nssGeneralName_GetIPAddress
 * nssGeneralName_GetRegisteredID
 * nssGeneralName_GetSpecifiedChoice
 * nssGeneralName_Compare
 * nssGeneralName_Duplicate
 *
 * nssGeneralName_GetUID
 * nssGeneralName_GetEmail
 * nssGeneralName_GetCommonName
 * nssGeneralName_GetOrganization
 * nssGeneralName_GetOrganizationalUnits
 * nssGeneralName_GetStateOrProvince
 * nssGeneralName_GetLocality
 * nssGeneralName_GetCountry
 * nssGeneralName_GetAttribute
 */

/*
 * nssGeneralName_CreateFromBER
 *
 * This routine creates an NSSGeneralName by decoding a BER- or DER-
 * encoded general 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 NSSGeneralName upon success
 */

NSS_EXTERN NSSGeneralName *
nssGeneralName_CreateFromBER
(
  NSSArena *arenaOpt,
  NSSBER *berGeneralName
);

/*
 * nssGeneralName_CreateFromUTF8
 *
 * This routine creates an NSSGeneralName by decoding a UTF8 string
 * consisting of the string representation of one of the choices of
 * general names.  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 NSSGeneralName upon success
 */

NSS_EXTERN NSSGeneralName *
nssGeneralName_CreateFromUTF8
(
  NSSArena *arenaOpt,
  NSSUTF8 *stringGeneralName
);

/*
 * nssGeneralName_Create
 *
 * This routine creates an NSSGeneralName with the specified choice of
 * underlying name types.  The value of the choice variable must be one
 * of the values of the NSSGeneralNameChoice enumeration, and the type
 * of the arg variable must be as specified in the following table:
 *
 *   Choice                                         Type
 *   ============================================   =========
 *   NSSGeneralNameChoiceOtherName
 *   NSSGeneralNameChoiceRfc822Name
 *   NSSGeneralNameChoiceDNSName
 *   NSSGeneralNameChoiceX400Address
 *   NSSGeneralNameChoiceDirectoryName              NSSName *
 *   NSSGeneralNameChoiceEdiPartyName
 *   NSSGeneralNameChoiceUniformResourceIdentifier
 *   NSSGeneralNameChoiceIPAddress
 *   NSSGeneralNameChoiceRegisteredID
 *
 * 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 fo the following values:
 *  NSS_ERROR_INVALID_CHOICE
 *  NSS_ERROR_INVALID_ARGUMENT
 *  NSS_ERROR_NO_MEMORY
 *
 * Return value:
 *  NULL upon error
 *  A pointer to an NSSGeneralName upon success
 */

NSS_EXTERN NSSGeneralName *
nssGeneralName_Create
(
  NSSGeneralNameChoice choice,
  void *arg
);

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

NSS_EXTERN PRStatus
nssGeneralName_Destroy
(
  NSSGeneralName *generalName
);

/*
 * nssGeneralName_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_GENERAL_NAME
 *  NSS_ERROR_NO_MEMORY
 *
 * Return value:
 *  NULL upon error
 *  The DER encoding of this NSSGeneralName
 */

NSS_EXTERN NSSDER *
nssGeneralName_GetDEREncoding
(
  NSSGeneralName *generalName,
  NSSArena *arenaOpt
);

/*
 * nssGeneralName_GetUTF8Encoding
 *
 * This routine returns a UTF8 string containing a string 
 * representation of the General 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_GENERAL_NAME
 *  NSS_ERROR_NO_MEMORY
 *
 * Return value:
 *  NULL upon error
 *  A pointer to a UTF8 string
 */

NSS_EXTERN NSSUTF8 *
nssGeneralName_GetUTF8Encoding
(
  NSSGeneralName *generalName,
  NSSArena *arenaOpt
);

/*
 * nssGeneralName_GetChoice
 *
 * This routine returns the type of choice underlying the specified 
 * general name.  The return value will be a member of the 
 * NSSGeneralNameChoice enumeration.  This routine may return 
 * NSSGeneralNameChoiceInvalid 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_GENERAL_NAME
 *
 * Return value:
 *  NSSGeneralNameChoiceInvalid upon error
 *  An other member of the NSSGeneralNameChoice enumeration 
 */

NSS_EXTERN NSSGeneralNameChoice
nssGeneralName_GetChoice
(
  NSSGeneralName *generalName
);

/*
 * nssGeneralName_GetOtherName
 *
 * If the choice underlying the specified NSSGeneralName is that of an
 * Other Name, this routine will return a pointer to that Other name.
 * 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_GENERAL_NAME
 *  NSS_ERROR_WRONG_CHOICE
 *  NSS_ERROR_NO_MEMORY
 *
 * Return value:
 *  NULL upon error
 *  A caller-owned pointer to an NSSOtherName
 */

NSS_EXTERN NSSOtherName *
nssGeneralName_GetOtherName
(
  NSSGeneralName *generalName,
  NSSArena *arenaOpt
);

/*
 * nssGeneralName_GetRfc822Name
 *
 * If the choice underlying the specified NSSGeneralName is that of an
 * RFC 822 Name, this routine will return a pointer to that name.
 * 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_GENERAL_NAME
 *  NSS_ERROR_WRONG_CHOICE
 *  NSS_ERROR_NO_MEMORY
 *
 * Return value:
 *  NULL upon error
 *  A caller-owned pointer to an NSSRFC822Name
 */

NSS_EXTERN NSSRFC822Name *
nssGeneralName_GetRfc822Name
(
  NSSGeneralName *generalName,
  NSSArena *arenaOpt
);

/*
 * nssGeneralName_GetDNSName
 *
 * If the choice underlying the specified NSSGeneralName is that of a 
 * DNS Name, this routine will return a pointer to that DNS name.
 * 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_GENERAL_NAME
 *  NSS_ERROR_WRONG_CHOICE
 *  NSS_ERROR_NO_MEMORY
 *
 * Return value:
 *  NULL upon error
 *  A caller-owned pointer to an NSSDNSName
 */

NSS_EXTERN NSSDNSName *
nssGeneralName_GetDNSName
(
  NSSGeneralName *generalName,
  NSSArena *arenaOpt
);

/*
 * nssGeneralName_GetX400Address
 *
 * If the choice underlying the specified NSSGeneralName is that of an
 * X.400 Address, this routine will return a pointer to that Address.
 * 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_GENERAL_NAME
 *  NSS_ERROR_WRONG_CHOICE
 *  NSS_ERROR_NO_MEMORY
 *
 * Return value:
 *  NULL upon error
 *  A caller-owned pointer to an NSSX400Address
 */

NSS_EXTERN NSSX400Address *
nssGeneralName_GetX400Address
(
  NSSGeneralName *generalName,
  NSSArena *arenaOpt
);

/*
 * nssGeneralName_GetDirectoryName
 *
 * If the choice underlying the specified NSSGeneralName is that of a
 * (directory) Name, this routine will return a pointer to that name.
 * 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_GENERAL_NAME
 *  NSS_ERROR_WRONG_CHOICE
 *  NSS_ERROR_NO_MEMORY
 *
 * Return value:
 *  NULL upon error
 *  A caller-owned pointer to an NSSName
 */

NSS_EXTERN NSSName *
nssGeneralName_GetName
(
  NSSGeneralName *generalName,
  NSSArena *arenaOpt
);

/*
 * nssGeneralName_GetEdiPartyName
 *
 * If the choice underlying the specified NSSGeneralName is that of an
 * EDI Party Name, this routine will return a pointer to that name.
 * 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_GENERAL_NAME
 *  NSS_ERROR_WRONG_CHOICE
 *  NSS_ERROR_NO_MEMORY
 *
 * Return value:
 *  NULL upon error
 *  A caller-owned pointer to an NSSEdiPartyName
 */

NSS_EXTERN NSSEdiPartyName *
nssGeneralName_GetEdiPartyName
(
  NSSGeneralName *generalName,
  NSSArena *arenaOpt
);

/*
 * nssGeneralName_GetUniformResourceIdentifier
 *
 * If the choice underlying the specified NSSGeneralName is that of a
 * URI, this routine will return a pointer to that URI.
 * 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