diff options
Diffstat (limited to 'security/nss/lib/pki1/nsspki1.h')
| -rw-r--r-- | security/nss/lib/pki1/nsspki1.h | 2869 |
1 files changed, 0 insertions, 2869 deletions
diff --git a/security/nss/lib/pki1/nsspki1.h b/security/nss/lib/pki1/nsspki1.h deleted file mode 100644 index 3498ab520..000000000 --- a/security/nss/lib/pki1/nsspki1.h +++ /dev/null @@ -1,2869 +0,0 @@ -/* - * The contents of this file are subject to the Mozilla Public - * License Version 1.1 (the "License"); you may not use this file - * except in compliance with the License. You may obtain a copy of - * the License at http://www.mozilla.org/MPL/ - * - * Software distributed under the License is distributed on an "AS - * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or - * implied. See the License for the specific language governing - * rights and limitations under the License. - * - * The Original Code is the Netscape security libraries. - * - * The Initial Developer of the Original Code is Netscape - * Communications Corporation. Portions created by Netscape are - * Copyright (C) 1994-2000 Netscape Communications Corporation. All - * Rights Reserved. - * - * Contributor(s): - * - * Alternatively, the contents of this file may be used under the - * terms of the GNU General Public License Version 2 or later (the - * "GPL"), in which case the provisions of the GPL are applicable - * instead of those above. If you wish to allow use of your - * version of this file only under the terms of the GPL and not to - * allow others to use your version of this file under the MPL, - * indicate your decision by deleting the provisions above and - * replace them with the notice and other provisions required by - * the GPL. If you do not delete the provisions above, a recipient - * may use your version of this file under either the MPL or the - * GPL. - */ - -#ifndef NSSPKI1_H -#define NSSPKI1_H - -#ifdef DEBUG -static const char NSSPKI1_CVS_ID[] = "@(#) $RCSfile$ $Revision$ $Date$ $Name$"; -#endif /* DEBUG */ - -/* - * nsspki1.h - * - * This file contains the prototypes of the public NSS routines - * dealing with the PKIX part-1 definitions. - */ - -#ifndef NSSBASET_H -#include "nssbaset.h" -#endif /* NSSBASET_H */ - -#ifndef NSSPKI1T_H -#include "nsspki1t.h" -#endif /* NSSPKI1T_H */ - -#ifndef OIDDATA_H -#include "oiddata.h" -#endif /* OIDDATA_H */ - -PR_BEGIN_EXTERN_C - -/* - * NSSOID - * - * The public "methods" regarding this "object" are: - * - * NSSOID_CreateFromBER -- constructor - * NSSOID_CreateFromUTF8 -- constructor - * (there is no explicit destructor) - * - * NSSOID_GetDEREncoding - * NSSOID_GetUTF8Encoding - */ - -extern const NSSOID *NSS_OID_UNKNOWN; - -/* - * NSSOID_CreateFromBER - * - * This routine creates an NSSOID by decoding a BER- or DER-encoded - * OID. It may return NSS_OID_UNKNOWN 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: - * NSS_OID_UNKNOWN upon error - * An NSSOID upon success - */ - -NSS_EXTERN NSSOID * -NSSOID_CreateFromBER -( - NSSBER *berOid -); - -extern const NSSError NSS_ERROR_INVALID_BER; -extern const NSSError NSS_ERROR_NO_MEMORY; - -/* - * NSSOID_CreateFromUTF8 - * - * This routine creates an NSSOID by decoding a UTF8 string - * representation of an OID in dotted-number format. The string may - * optionally begin with an octothorpe. It may return NSS_OID_UNKNOWN - * upon error, in which case it will have created an error stack. - * - * The error may be one of the following values: - * NSS_ERROR_INVALID_STRING - * NSS_ERROR_NO_MEMORY - * - * Return value: - * NSS_OID_UNKNOWN upon error - * An NSSOID upon success - */ - -NSS_EXTERN NSSOID * -NSSOID_CreateFromUTF8 -( - NSSUTF8 *stringOid -); - -extern const NSSError NSS_ERROR_INVALID_STRING; -extern const NSSError NSS_ERROR_NO_MEMORY; - -/* - * NSSOID_GetDEREncoding - * - * This routine returns the DER encoding of the specified NSSOID. - * 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 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_NSSOID - * NSS_ERROR_NO_MEMORY - * - * Return value: - * NULL upon error - * The DER encoding of this NSSOID - */ - -NSS_EXTERN NSSDER * -NSSOID_GetDEREncoding -( - const NSSOID *oid, - NSSDER *rvOpt, - NSSArena *arenaOpt -); - -extern const NSSError NSS_ERROR_INVALID_NSSOID; -extern const NSSError NSS_ERROR_NO_MEMORY; - -/* - * NSSOID_GetUTF8Encoding - * - * This routine returns a UTF8 string containing the dotted-number - * encoding of the specified NSSOID. 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_NSSOID - * NSS_ERROR_NO_MEMORY - * - * Return value: - * NULL upon error - * A pointer to a UTF8 string containing the dotted-digit encoding of - * this NSSOID - */ - -NSS_EXTERN NSSUTF8 * -NSSOID_GetUTF8Encoding -( - const NSSOID *oid, - NSSArena *arenaOpt -); - -extern const NSSError NSS_ERROR_INVALID_NSSOID; -extern const NSSError NSS_ERROR_NO_MEMORY; - -/* - * NSSATAV - * - * The public "methods" regarding this "object" are: - * - * NSSATAV_CreateFromBER -- constructor - * NSSATAV_CreateFromUTF8 -- constructor - * NSSATAV_Create -- constructor - * - * NSSATAV_Destroy - * NSSATAV_GetDEREncoding - * NSSATAV_GetUTF8Encoding - * NSSATAV_GetType - * NSSATAV_GetValue - * NSSATAV_Compare - * NSSATAV_Duplicate - */ - -/* - * NSSATAV_CreateFromBER - * - * This routine creates an NSSATAV by decoding a BER- or DER-encoded - * ATAV. 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 NSSATAV upon success - */ - -NSS_EXTERN NSSATAV * -NSSATAV_CreateFromBER -( - NSSArena *arenaOpt, - NSSBER *derATAV -); - -extern const NSSError NSS_ERROR_INVALID_BER; -extern const NSSError NSS_ERROR_NO_MEMORY; - -/* - * NSSATAV_CreateFromUTF8 - * - * This routine creates an NSSATAV by decoding a UTF8 string in the - * "equals" format, e.g., "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 NSSATAV upon success - */ - -NSS_EXTERN NSSATAV * -NSSATAV_CreateFromUTF8 -( - NSSArena *arenaOpt, - NSSUTF8 *stringATAV -); - -extern const NSSError NSS_ERROR_UNKNOWN_ATTRIBUTE; -extern const NSSError NSS_ERROR_INVALID_STRING; -extern const NSSError NSS_ERROR_NO_MEMORY; - -/* - * NSSATAV_Create - * - * This routine creates an NSSATAV from the specified NSSOID and the - * specified data. 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.If the specified data length is zero, - * the data is assumed to be terminated by first zero byte; this allows - * UTF8 strings to be easily specified. 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_ARENA - * NSS_ERROR_INVALID_NSSOID - * NSS_ERROR_INVALID_POINTER - * NSS_ERROR_NO_MEMORY - * - * Return value: - * NULL upon error - * A pointer to an NSSATAV upon success - */ - -NSS_EXTERN NSSATAV * -NSSATAV_Create -( - NSSArena *arenaOpt, - const NSSOID *oid, - const void *data, - PRUint32 length -); - -extern const NSSError NSS_ERROR_INVALID_ARENA; -extern const NSSError NSS_ERROR_INVALID_NSSOID; -extern const NSSError NSS_ERROR_INVALID_POINTER; -extern const NSSError NSS_ERROR_NO_MEMORY; - -/* - * NSSATAV_Destroy - * - * This routine will destroy an ATAV object. It should eventually be - * called on all ATAVs created without an arena. While it is not - * necessary to call it on ATAVs 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_ATAV - * - * Return value: - * PR_FAILURE upon error - * PR_SUCCESS upon success - */ - -NSS_EXTERN PRStatus -NSSATAV_Destroy -( - NSSATAV *atav -); - -extern const NSSError NSS_ERROR_INVALID_ATAV; - -/* - * NSSATAV_GetDEREncoding - * - * This routine will DER-encode an ATAV 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_ATAV - * NSS_ERROR_NO_MEMORY - * - * Return value: - * NULL upon error - * The DER encoding of this NSSATAV - */ - -NSS_EXTERN NSSDER * -NSSATAV_GetDEREncoding -( - NSSATAV *atav, - NSSArena *arenaOpt -); - -extern const NSSError NSS_ERROR_INVALID_ATAV; -extern const NSSError NSS_ERROR_NO_MEMORY; - -/* - * NSSATAV_GetUTF8Encoding - * - * This routine returns a UTF8 string containing a string - * representation of the ATAV in "equals" notation (e.g., "o=Acme"). - * 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_ATAV - * NSS_ERROR_NO_MEMORY - * - * Return value: - * NULL upon error - * A pointer to a UTF8 string containing the "equals" encoding of the - * ATAV - */ - -NSS_EXTERN NSSUTF8 * -NSSATAV_GetUTF8Encoding -( - NSSATAV *atav, - NSSArena *arenaOpt -); - -extern const NSSError NSS_ERROR_INVALID_ATAV; -extern const NSSError NSS_ERROR_NO_MEMORY; - -/* - * NSSATAV_GetType - * - * This routine returns the NSSOID corresponding to the attribute type - * in the specified ATAV. This routine may return NSS_OID_UNKNOWN - * 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 - * - * Return value: - * NSS_OID_UNKNOWN upon error - * An element of enum NSSOIDenum upon success - */ - -NSS_EXTERN const NSSOID * -NSSATAV_GetType -( - NSSATAV *atav -); - -extern const NSSError NSS_ERROR_INVALID_ATAV; - -/* - * NSSATAV_GetValue - * - * This routine returns an NSSItem containing the attribute value - * in the specified ATAV. 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_ATAV - * NSS_ERROR_NO_MEMORY - * - * Return value: - * NULL upon error - * A pointer to an NSSItem containing the attribute value. - */ - -NSS_EXTERN NSSUTF8 * -NSSATAV_GetValue -( - NSSATAV *atav, - NSSArena *arenaOpt -); - -extern const NSSError NSS_ERROR_INVALID_ATAV; -extern const NSSError NSS_ERROR_NO_MEMORY; - -/* - * NSSATAV_Compare - * - * This routine compares two ATAVs for equality. For two ATAVs to be - * equal, the attribute types must be the same, and the attribute - * values must have equal length and contents. 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_ATAV - * NSS_ERROR_INVALID_ARGUMENT - * - * Return value: - * PR_FAILURE on error - * PR_SUCCESS upon a successful comparison (equal or not) - */ - -NSS_EXTERN PRStatus -NSSATAV_Compare -( - NSSATAV *atav1, - NSSATAV *atav2, - PRBool *equalp -); - -extern const NSSError NSS_ERROR_INVALID_ATAV; -extern const NSSError NSS_ERROR_INVALID_ARGUMENT; - -/* - * NSSATAV_Duplicate - * - * This routine duplicates the specified ATAV. 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_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 - * 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_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 - * create an 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 - * created an 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 created an 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 create an 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 created an 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 created an error stack. Note that the - * usual string 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 created an 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 - * created an 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 -); - -/* - * NSSName - * - * The 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_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 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 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 created an error stack. - * - * The error may be one of the following values: - * NSS_ERROR_INVALID_STRING - * 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 created an 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: - * 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 - * create an 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 - * created an 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 created an 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 created an 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 created an 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 created an 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 created an 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 created an 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 created an 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 created an 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 created an 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 created an 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 - * created an 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 created an 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 created an 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 created an - * 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 - * 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_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 -); - -/* - * NSSGeneralName - * - * The 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 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 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 created an error stack. - * - * The error may be one of the following values: - * NSS_ERROR_INVALID_STRING - * 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 created an 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 create an 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 - * created an 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 created an - * 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 - * created an 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 created an 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 created an 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 created an 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 created an 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 created an 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 created an 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 created an 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 NSSURI - */ - -NSS_EXTERN NSSURI * -NSSGeneralName_GetUniformResourceIdentifier -( - NSSGeneralName *generalName, - NSSArena *arenaOpt -); - -/* - * NSSGeneralName_GetIPAddress - * - * If the choice underlying the specified NSSGeneralName is that of an - * IP 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 created an 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 NSSIPAddress - */ - -NSS_EXTERN NSSIPAddress * -NSSGeneralName_GetIPAddress -( - NSSGeneralName *generalName, - NSSArena *arenaOpt -); - -/* - * NSSGeneralName_GetRegisteredID - * - * If the choice underlying the specified NSSGeneralName is that of a - * Registered ID, this routine will return a pointer to that ID. - * 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 created an 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 NSSRegisteredID - */ - -NSS_EXTERN NSSRegisteredID * -NSSGeneralName_GetRegisteredID -( - NSSGeneralName *generalName, - NSSArena *arenaOpt -); - -/* - * NSSGeneralName_GetSpecifiedChoice - * - * If the choice underlying the specified NSSGeneralName 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 caes it will have created an 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, which must be typecast - */ - -NSS_EXTERN void * -NSSGeneralName_GetSpecifiedChoice -( - NSSGeneralName *generalName, - NSSGeneralNameChoice choice, - NSSArena *arenaOpt -); - -/* - * NSSGeneralName_Compare - * - * This routine compares two General Names for equality. For two - * General 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 created an error stack. - * - * The error may be one of the following value: - * NSS_ERROR_INVALID_GENERAL_NAME - * NSS_ERROR_INVALID_ARGUMENT - * - * Return value: - * PR_FAILURE upon error - * PR_SUCCESS upon a successful comparison (equal or not) - */ - -NSS_EXTERN PRStatus -NSSGeneralName_Compare -( - NSSGeneralName *generalName1, - NSSGeneralName *generalName2, - PRBool *equalp -); - -/* - * NSSGeneralName_Duplicate - * - * This routine duplicates the specified General Name. 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_GENERAL_NAME - * NSS_ERROR_NO_MEMORY - * - * Return value: - * NULL upon error - * A pointer to a new NSSGeneralName - */ - -NSS_EXTERN NSSGeneralName * -NSSGeneralName_Duplicate -( - NSSGeneralName *generalName, - NSSArena *arenaOpt -); - -/* - * NSSGeneralName_GetUID - * - * This routine will attempt to derive a user identifier from the - * specified general name, if the choices and content of the name - * permit. If the General Name is a (directory) Name consisting - * 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 created an error stack. - * - * The error may be one of the following values: - * NSS_ERROR_INVALID_GENERAL_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 */ -NSSGeneralName_GetUID -( - NSSGeneralName *generalName, - NSSArena *arenaOpt -); - -/* - * NSSGeneralName_GetEmail - * - * This routine will attempt to derive an email address from the - * specified general name, if the choices and content of the name - * permit. If the General Name is a (directory) Name consisting - * 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 General Name is an RFC 822 - * Name, the result will be the string form of 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 created an error stack. - * - * The error may be one of the following values: - * NSS_ERROR_INVALID_GENERAL_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 IA5String */ -NSSGeneralName_GetEmail -( - NSSGeneralName *generalName, - NSSArena *arenaOpt -); - -/* - * NSSGeneralName_GetCommonName - * - * This routine will attempt to derive a common name from the - * specified general name, if the choices and content of the name - * permit. If the General Name is a (directory) Name consisting - * 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 - * created an error stack. - * - * The error may be one of the following values: - * NSS_ERROR_INVALID_GENERAL_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 */ -NSSGeneralName_GetCommonName -( - NSSGeneralName *generalName, - NSSArena *arenaOpt -); - -/* - * NSSGeneralName_GetOrganization - * - * This routine will attempt to derive an organisation name from the - * specified general name, if the choices and content of the name - * permit. If the General Name is a (directory) Name consisting - * of a Sequence of Relative Distinguished names containing an - * 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 created an error stack. - * - * The error may be one of the following values: - * NSS_ERROR_INVALID_GENERAL_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 */ -NSSGeneralName_GetOrganization -( - NSSGeneralName *generalName, - NSSArena *arenaOpt -); - -/* - * NSSGeneralName_GetOrganizationalUnits - * - * This routine will attempt to derive a sequence of organisational - * unit names from the specified general name, if the choices and - * content of the name permit. If the General Name is a (directory) - * Name consisting of a Sequence of Relative Distinguished names - * containing one or more organisational units, the result will - * consist of those units. 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_GENERAL_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 */ -NSSGeneralName_GetOrganizationalUnits -( - NSSGeneralName *generalName, - NSSArena *arenaOpt -); - -/* - * NSSGeneralName_GetStateOrProvince - * - * This routine will attempt to derive a state or province name from - * the specified general name, if the choices and content of the name - * permit. If the General Name is a (directory) Name consisting - * 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 created an error stack. - * - * The error may be one of the following values: - * NSS_ERROR_INVALID_GENERAL_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 */ -NSSGeneralName_GetStateOrProvince -( - NSSGeneralName *generalName, - NSSArena *arenaOpt -); - -/* - * NSSGeneralName_GetLocality - * - * This routine will attempt to derive a locality name from - * the specified general name, if the choices and content of the name - * permit. If the General Name is a (directory) Name consisting - * 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 - * created an error stack. - * - * The error may be one of the following values: - * NSS_ERROR_INVALID_GENERAL_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 */ -NSSGeneralName_GetLocality -( - NSSGeneralName *generalName, - NSSArena *arenaOpt -); - -/* - * NSSGeneralName_GetCountry - * - * This routine will attempt to derive a country name from the - * specified general name, if the choices and content of the name - * permit. If the General Name is a (directory) Name consisting 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 - * created an error stack. - * - * The error may be one of the following values: - * NSS_ERROR_INVALID_GENERAL_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 */ -NSSGeneralName_GetCountry -( - NSSGeneralName *generalName, - NSSArena *arenaOpt -); - -/* - * NSSGeneralName_GetAttribute - * - * If the specified general name is a (directory) name consisting - * 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 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_GENERAL_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 */ -NSSGeneralName_GetAttribute -( - NSSGeneralName *generalName, - NSSOID *attribute, - NSSArena *arenaOpt -); - -/* - * NSSGeneralNameSeq - * - * The public "methods" regarding this "object" are: - * - * NSSGeneralNameSeq_CreateFromBER -- constructor - * NSSGeneralNameSeq_Create -- constructor - * - * NSSGeneralNameSeq_Destroy - * NSSGeneralNameSeq_GetDEREncoding - * NSSGeneralNameSeq_AppendGeneralName - * NSSGeneralNameSeq_GetGeneralNameCount - * NSSGeneralNameSeq_GetGeneralName - * NSSGeneralNameSeq_Compare - * NSSGeneralnameSeq_Duplicate - */ - -/* - * NSSGeneralNameSeq_CreateFromBER - * - * This routine creates a general name sequence by decoding a BER- - * or DER-encoded GeneralNames. 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 NSSGeneralNameSeq upon success - */ - -NSS_EXTERN NSSGeneralNameSeq * -NSSGeneralNameSeq_CreateFromBER -( - NSSArena *arenaOpt, - NSSBER *berGeneralNameSeq -); - -/* - * NSSGeneralNameSeq_Create - * - * This routine creates an NSSGeneralNameSeq from one or more General - * Names. 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_GENERAL_NAME - * - * Return value: - * NULL upon error - * A pointer to an NSSGeneralNameSeq upon success - */ - -NSS_EXTERN NSSGeneralNameSeq * -NSSGeneralNameSeq_Create -( - NSSArena *arenaOpt, - NSSGeneralName *generalName1, - ... -); - -/* - * NSSGeneralNameSeq_Destroy - * - * This routine will destroy an NSSGeneralNameSeq object. It should - * eventually be called on all NSSGeneralNameSeqs created without an - * arena. While it is not necessary to call it on NSSGeneralNameSeq's - * 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_GENERAL_NAME_SEQ - * - * Return value: - * PR_FAILURE upon error - * PR_SUCCESS upon success - */ - -NSS_EXTERN PRStatus -NSSGeneralNameSeq_Destroy -( - NSSGeneralNameSeq *generalNameSeq -); - -/* - * NSSGeneralNameSeq_GetDEREncoding - * - * This routine will DER-encode an NSSGeneralNameSeq 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_GENERAL_NAME_SEQ - * NSS_ERROR_NO_MEMORY - * - * Return value: - * NULL upon error - * The DER encoding of this NSSGeneralNameSeq - */ - -NSS_EXTERN NSSDER * -NSSGeneralNameSeq_GetDEREncoding -( - NSSGeneralNameSeq *generalNameSeq, - NSSArena *arenaOpt -); - -/* - * NSSGeneralNameSeq_AppendGeneralName - * - * This routine appends a General Name to the end of the existing - * General Name Sequence. If the sequence was created with a non-null - * arena argument, that same arena will be used for any additional - * required memory. If the sequence 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_GENERAL_NAME_SEQ - * NSS_ERROR_INVALID_GENERAL_NAME - * NSS_ERROR_NO_MEMORY - * - * Return value: - * PR_SUCCESS upon success - * PR_FAILURE upon failure. - */ - -NSS_EXTERN PRStatus -NSSGeneralNameSeq_AppendGeneralName -( - NSSGeneralNameSeq *generalNameSeq, - NSSGeneralName *generalName -); - -/* - * NSSGeneralNameSeq_GetGeneralNameCount - * - * This routine returns the cardinality of the specified General name - * Sequence. 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_GENERAL_NAME_SEQ - * - * Return value; - * 0 upon error - * A positive number upon success - */ - -NSS_EXTERN PRUint32 -NSSGeneralNameSeq_GetGeneralNameCount -( - NSSGeneralNameSeq *generalNameSeq -); - -/* - * NSSGeneralNameSeq_GetGeneralName - * - * This routine returns a pointer to the i'th General Name in the - * specified General Name Sequence. The value of the variable 'i' is - * on the range [0,c) where c is the cardinality returned from - * NSSGeneralNameSeq_GetGeneralNameCount. The caller owns the General - * Name 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_GENERAL_NAME_SEQ - * NSS_ERROR_VALUE_OUT_OF_RANGE - * NSS_ERROR_NO_MEMORY - * - * Return value: - * NULL upon error - * A caller-owned pointer to a General Name. - */ - -NSS_EXTERN NSSGeneralName * -NSSGeneralNameSeq_GetGeneralName -( - NSSGeneralNameSeq *generalNameSeq, - NSSArena *arenaOpt, - PRUint32 i -); - -/* - * NSSGeneralNameSeq_Compare - * - * This routine compares two General Name Sequences for equality. For - * two General Name Sequences to be equal, they must have the same - * cardinality, and each General Name in one sequence must be equal to - * the corresponding General Name in the other. 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_GENERAL_NAME_SEQ - * NSS_ERROR_INVALID_ARGUMENT - * - * Return value: - * PR_FAILURE upon error - * PR_SUCCESS upon a successful comparison (equal or not) - */ - -NSS_EXTERN PRStatus -NSSGeneralNameSeq_Compare -( - NSSGeneralNameSeq *generalNameSeq1, - NSSGeneralNameSeq *generalNameSeq2, - PRBool *equalp -); - -/* - * NSSGeneralNameSeq_Duplicate - * - * This routine duplicates the specified sequence of general names. 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_GENERAL_NAME_SEQ - * NSS_ERROR_NO_MEMORY - * - * Return value: - * NULL upon error - * A pointer to a new General Name Sequence. - */ - -NSS_EXTERN NSSGeneralNameSeq * -NSSGeneralNameSeq_Duplicate -( - NSSGeneralNameSeq *generalNameSeq, - NSSArena *arenaOpt -); - -PR_END_EXTERN_C - -#endif /* NSSPT1M_H */ |