Back to index

lightning-sunbird  0.9+nobinonly
pki1.h
Go to the documentation of this file.
00001 /* ***** BEGIN LICENSE BLOCK *****
00002  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00003  *
00004  * The contents of this file are subject to the Mozilla Public License Version
00005  * 1.1 (the "License"); you may not use this file except in compliance with
00006  * the License. You may obtain a copy of the License at
00007  * http://www.mozilla.org/MPL/
00008  *
00009  * Software distributed under the License is distributed on an "AS IS" basis,
00010  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00011  * for the specific language governing rights and limitations under the
00012  * License.
00013  *
00014  * The Original Code is the Netscape security libraries.
00015  *
00016  * The Initial Developer of the Original Code is
00017  * Netscape Communications Corporation.
00018  * Portions created by the Initial Developer are Copyright (C) 1994-2000
00019  * the Initial Developer. All Rights Reserved.
00020  *
00021  * Contributor(s):
00022  *
00023  * Alternatively, the contents of this file may be used under the terms of
00024  * either the GNU General Public License Version 2 or later (the "GPL"), or
00025  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00026  * in which case the provisions of the GPL or the LGPL are applicable instead
00027  * of those above. If you wish to allow use of your version of this file only
00028  * under the terms of either the GPL or the LGPL, and not to allow others to
00029  * use your version of this file under the terms of the MPL, indicate your
00030  * decision by deleting the provisions above and replace them with the notice
00031  * and other provisions required by the GPL or the LGPL. If you do not delete
00032  * the provisions above, a recipient may use your version of this file under
00033  * the terms of any one of the MPL, the GPL or the LGPL.
00034  *
00035  * ***** END LICENSE BLOCK ***** */
00036 
00037 #ifndef PKI1_H
00038 #define PKI1_H
00039 
00040 #ifdef DEBUG
00041 static const char PKI1_CVS_ID[] = "@(#) $RCSfile: pki1.h,v $ $Revision: 1.5 $ $Date: 2005/03/14 18:02:00 $";
00042 #endif /* DEBUG */
00043 
00044 /*
00045  * pki1.h
00046  *
00047  * This file contains the prototypes to the non-public NSS routines
00048  * relating to the PKIX part-1 objects.
00049  */
00050 
00051 #ifndef PKI1T_H
00052 #include "pki1t.h"
00053 #endif /* PKI1T_H */
00054 
00055 #ifndef NSSPKI1_H
00056 #include "nsspki1.h"
00057 #endif /* NSSPKI1_H */
00058 
00059 PR_BEGIN_EXTERN_C
00060 
00061 extern const NSSOID nss_builtin_oids[];
00062 extern const PRUint32 nss_builtin_oid_count;
00063 
00064 extern const nssAttributeTypeAliasTable nss_attribute_type_aliases[];
00065 extern const PRUint32 nss_attribute_type_alias_count;
00066 
00067 /*
00068  * NSSOID
00069  *
00070  * The non-public "methods" regarding this "object" are:
00071  *
00072  *  nssOID_CreateFromBER   -- constructor
00073  *  nssOID_CreateFromUTF8  -- constructor
00074  *  (there is no explicit destructor)
00075  * 
00076  *  nssOID_GetDEREncoding
00077  *  nssOID_GetUTF8Encoding
00078  *
00079  * In debug builds, the following non-public calls are also available:
00080  *
00081  *  nssOID_verifyPointer
00082  *  nssOID_getExplanation
00083  *  nssOID_getTaggedUTF8
00084  */
00085 
00086 /*
00087  * nssOID_CreateFromBER
00088  *
00089  * This routine creates an NSSOID by decoding a BER- or DER-encoded
00090  * OID.  It may return NSS_OID_UNKNOWN upon error, in which case it 
00091  * will have set an error on the error stack.
00092  *
00093  * The error may be one of the following values:
00094  *  NSS_ERROR_INVALID_BER
00095  *  NSS_ERROR_NO_MEMORY
00096  *
00097  * Return value:
00098  *  NSS_OID_UNKNOWN upon error
00099  *  An NSSOID upon success
00100  */
00101 
00102 NSS_EXTERN NSSOID *
00103 nssOID_CreateFromBER
00104 (
00105   NSSBER *berOid
00106 );
00107 
00108 extern const NSSError NSS_ERROR_INVALID_BER;
00109 extern const NSSError NSS_ERROR_NO_MEMORY;
00110 
00111 /*
00112  * nssOID_CreateFromUTF8
00113  *
00114  * This routine creates an NSSOID by decoding a UTF8 string 
00115  * representation of an OID in dotted-number format.  The string may 
00116  * optionally begin with an octothorpe.  It may return NSS_OID_UNKNOWN
00117  * upon error, in which case it will have set an error on the error 
00118  * stack.
00119  *
00120  * The error may be one of the following values:
00121  *  NSS_ERROR_INVALID_UTF8
00122  *  NSS_ERROR_NO_MEMORY
00123  *
00124  * Return value:
00125  *  NSS_OID_UNKNOWN upon error
00126  *  An NSSOID upon success
00127  */
00128 
00129 NSS_EXTERN NSSOID *
00130 nssOID_CreateFromUTF8
00131 (
00132   NSSUTF8 *stringOid
00133 );
00134 
00135 extern const NSSError NSS_ERROR_INVALID_UTF8;
00136 extern const NSSError NSS_ERROR_NO_MEMORY;
00137 
00138 /*
00139  * nssOID_GetDEREncoding
00140  *
00141  * This routine returns the DER encoding of the specified NSSOID.
00142  * If the optional arena argument is non-null, the memory used will
00143  * be obtained from that arena; otherwise, the memory will be obtained
00144  * from the heap.  This routine may return return null upon error, in 
00145  * which case it will have set an error on the error stack.
00146  *
00147  * The error may be one of the following values:
00148  *  NSS_ERROR_INVALID_NSSOID
00149  *  NSS_ERROR_NO_MEMORY
00150  *
00151  * Return value:
00152  *  NULL upon error
00153  *  The DER encoding of this NSSOID
00154  */
00155 
00156 NSS_EXTERN NSSDER *
00157 nssOID_GetDEREncoding
00158 (
00159   const NSSOID *oid,
00160   NSSDER *rvOpt,
00161   NSSArena *arenaOpt
00162 );
00163 
00164 /*
00165  * nssOID_GetUTF8Encoding
00166  *
00167  * This routine returns a UTF8 string containing the dotted-number 
00168  * encoding of the specified NSSOID.  If the optional arena argument 
00169  * is non-null, the memory used will be obtained from that arena; 
00170  * otherwise, the memory will be obtained from the heap.  This routine
00171  * may return null upon error, in which case it will have set an error
00172  * on the error stack.
00173  *
00174  * The error may be one of the following values:
00175  *  NSS_ERROR_INVALID_NSSOID
00176  *  NSS_ERROR_NO_MEMORY
00177  *
00178  * Return value:
00179  *  NULL upon error
00180  *  A pointer to a UTF8 string containing the dotted-digit encoding of 
00181  *      this NSSOID
00182  */
00183 
00184 NSS_EXTERN NSSUTF8 *
00185 nssOID_GetUTF8Encoding
00186 (
00187   const NSSOID *oid,
00188   NSSArena *arenaOpt
00189 );
00190 
00191 /*
00192  * nssOID_verifyPointer
00193  *
00194  * This method is only present in debug builds.
00195  *
00196  * If the specified pointer is a valid poitner to an NSSOID object, 
00197  * this routine will return PR_SUCCESS.  Otherwise, it will put an 
00198  * error on the error stack and return PR_FAILURE.
00199  *
00200  * The error may be one of the following values:
00201  *  NSS_ERROR_INVALID_NSSOID
00202  *
00203  * Return value:
00204  *  PR_SUCCESS if the pointer is valid
00205  *  PR_FAILURE if it isn't
00206  */
00207 
00208 #ifdef DEBUG
00209 NSS_EXTERN PRStatus
00210 nssOID_verifyPointer
00211 (
00212   const NSSOID *oid
00213 );
00214 
00215 extern const NSSError NSS_ERROR_INVALID_NSSOID;
00216 #endif /* DEBUG */
00217 
00218 /*
00219  * nssOID_getExplanation
00220  *
00221  * This method is only present in debug builds.
00222  *
00223  * This routine will return a static pointer to a UTF8-encoded string
00224  * describing (in English) the specified OID.  The memory pointed to
00225  * by the return value is not owned by the caller, and should not be
00226  * freed or modified.  Note that explanations are only provided for
00227  * the OIDs built into the NSS library; there is no way to specify an
00228  * explanation for dynamically created OIDs.  This routine is intended
00229  * only for use in debugging tools such as "derdump."  This routine
00230  * may return null upon error, in which case it will have placed an
00231  * error on the error stack.
00232  *
00233  * The error may be one of the following values:
00234  *  NSS_ERROR_INVALID_NSSOID
00235  *
00236  * Return value:
00237  *  NULL upon error
00238  *  A static pointer to a readonly, non-caller-owned UTF8-encoded
00239  *    string explaining the specified OID.
00240  */
00241 
00242 #ifdef DEBUG
00243 NSS_EXTERN const NSSUTF8 *
00244 nssOID_getExplanation
00245 (
00246   NSSOID *oid
00247 );
00248 
00249 extern const NSSError NSS_ERROR_INVALID_NSSOID;
00250 #endif /* DEBUG */
00251 
00252 /*
00253  * nssOID_getTaggedUTF8
00254  *
00255  * This method is only present in debug builds.
00256  *
00257  * This routine will return a pointer to a caller-owned UTF8-encoded
00258  * string containing a tagged encoding of the specified OID.  Note
00259  * that OID (component) tags are only provided for the OIDs built 
00260  * into the NSS library; there is no way to specify tags for 
00261  * dynamically created OIDs.  This routine is intended for use in
00262  * debugging tools such as "derdump."   If the optional arena argument
00263  * is non-null, the memory used will be obtained from that arena; 
00264  * otherwise, the memory will be obtained from the heap.  This routine 
00265  * may return return null upon error, in which case it will have set 
00266  * an error on the error stack.
00267  *
00268  * The error may be one of the following values
00269  *  NSS_ERROR_INVALID_NSSOID
00270  *  NSS_ERROR_NO_MEMORY
00271  *
00272  * Return value:
00273  *  NULL upon error
00274  *  A pointer to a UTF8 string containing the tagged encoding of
00275  *      this NSSOID
00276  */
00277 
00278 #ifdef DEBUG
00279 NSS_EXTERN NSSUTF8 *
00280 nssOID_getTaggedUTF8
00281 (
00282   NSSOID *oid,
00283   NSSArena *arenaOpt
00284 );
00285 
00286 extern const NSSError NSS_ERROR_INVALID_NSSOID;
00287 extern const NSSError NSS_ERROR_NO_MEMORY;
00288 #endif /* DEBUG */
00289 
00290 /*
00291  * NSSATAV
00292  *
00293  * The non-public "methods" regarding this "object" are:
00294  *
00295  *  nssATAV_CreateFromBER   -- constructor
00296  *  nssATAV_CreateFromUTF8  -- constructor
00297  *  nssATAV_Create          -- constructor
00298  *
00299  *  nssATAV_Destroy
00300  *  nssATAV_GetDEREncoding
00301  *  nssATAV_GetUTF8Encoding
00302  *  nssATAV_GetType
00303  *  nssATAV_GetValue
00304  *  nssATAV_Compare
00305  *  nssATAV_Duplicate
00306  *
00307  * In debug builds, the following non-public call is also available:
00308  *
00309  *  nssATAV_verifyPointer
00310  */
00311 
00312 /*
00313  * nssATAV_CreateFromBER
00314  * 
00315  * This routine creates an NSSATAV by decoding a BER- or DER-encoded
00316  * ATAV.  If the optional arena argument is non-null, the memory used 
00317  * will be obtained from that arena; otherwise, the memory will be 
00318  * obtained from the heap.  This routine may return NULL upon error, 
00319  * in which case it will have set an error on the error stack.
00320  *
00321  * The error may be one of the following values:
00322  *  NSS_ERROR_INVALID_BER
00323  *  NSS_ERROR_NO_MEMORY
00324  *
00325  * Return value:
00326  *  NULL upon error
00327  *  A pointer to an NSSATAV upon success
00328  */
00329 
00330 NSS_EXTERN NSSATAV *
00331 nssATAV_CreateFromBER
00332 (
00333   NSSArena *arenaOpt,
00334   const NSSBER *berATAV
00335 );
00336 
00337 /*
00338  * nssATAV_CreateFromUTF8
00339  *
00340  * This routine creates an NSSATAV by decoding a UTF8 string in the
00341  * "equals" format, e.g., "c=US."  If the optional arena argument is 
00342  * non-null, the memory used will be obtained from that arena; 
00343  * otherwise, the memory will be obtained from the heap.  This routine
00344  * may return NULL upon error, in which case it will have set an error 
00345  * on the error stack.
00346  *
00347  * The error may be one of the following values:
00348  *  NSS_ERROR_UNKNOWN_ATTRIBUTE
00349  *  NSS_ERROR_INVALID_UTF8
00350  *  NSS_ERROR_NO_MEMORY
00351  *
00352  * Return value:
00353  *  NULL upon error
00354  *  A pointer to an NSSATAV upon success
00355  */
00356 
00357 NSS_EXTERN NSSATAV *
00358 nssATAV_CreateFromUTF8
00359 (
00360   NSSArena *arenaOpt,
00361   const NSSUTF8 *stringATAV
00362 );
00363 
00364 /*
00365  * nssATAV_Create
00366  *
00367  * This routine creates an NSSATAV from the specified NSSOID and the
00368  * specified data. If the optional arena argument is non-null, the 
00369  * memory used will be obtained from that arena; otherwise, the memory
00370  * will be obtained from the heap.If the specified data length is zero, 
00371  * the data is assumed to be terminated by first zero byte; this allows 
00372  * UTF8 strings to be easily specified.  This routine may return NULL 
00373  * upon error, in which case it will have set an error on the error 
00374  * stack.
00375  *
00376  * The error may be one of the following values:
00377  *  NSS_ERROR_INVALID_ARENA
00378  *  NSS_ERROR_INVALID_NSSOID
00379  *  NSS_ERROR_INVALID_POINTER
00380  *  NSS_ERROR_NO_MEMORY
00381  *
00382  * Return value:
00383  *  NULL upon error
00384  *  A pointer to an NSSATAV upon success
00385  */
00386 
00387 NSS_EXTERN NSSATAV *
00388 nssATAV_Create
00389 (
00390   NSSArena *arenaOpt,
00391   const NSSOID *oid,
00392   const void *data,
00393   PRUint32 length
00394 );
00395 
00396 /*
00397  * nssATAV_Destroy
00398  *
00399  * This routine will destroy an ATAV object.  It should eventually be
00400  * called on all ATAVs created without an arena.  While it is not 
00401  * necessary to call it on ATAVs created within an arena, it is not an
00402  * error to do so.  This routine returns a PRStatus value; if
00403  * successful, it will return PR_SUCCESS.  If unsuccessful, it will
00404  * set an error on the error stack and return PR_FAILURE.
00405  *
00406  * The error may be one of the following values:
00407  *  NSS_ERROR_INVALID_ATAV
00408  *  
00409  * Return value:
00410  *  PR_FAILURE upon error
00411  *  PR_SUCCESS upon success
00412  */
00413 
00414 NSS_EXTERN PRStatus
00415 nssATAV_Destroy
00416 (
00417   NSSATAV *atav
00418 );
00419 
00420 /*
00421  * nssATAV_GetDEREncoding
00422  *
00423  * This routine will DER-encode an ATAV object. If the optional arena
00424  * argument is non-null, the memory used will be obtained from that
00425  * arena; otherwise, the memory will be obtained from the heap.  This
00426  * routine may return null upon error, in which case it will have set
00427  * an error on the error stack.
00428  *
00429  * The error may be one of the following values:
00430  *  NSS_ERROR_INVALID_ATAV
00431  *  NSS_ERROR_NO_MEMORY
00432  *
00433  * Return value:
00434  *  NULL upon error
00435  *  The DER encoding of this NSSATAV
00436  */
00437 
00438 NSS_EXTERN NSSDER *
00439 nssATAV_GetDEREncoding
00440 (
00441   NSSATAV *atav,
00442   NSSArena *arenaOpt
00443 );
00444 
00445 /*
00446  * nssATAV_GetUTF8Encoding
00447  *
00448  * This routine returns a UTF8 string containing a string 
00449  * representation of the ATAV in "equals" notation (e.g., "o=Acme").  
00450  * If the optional arena argument is non-null, the memory used will be
00451  * obtained from that arena; otherwise, the memory will be obtained 
00452  * from the heap.  This routine may return null upon error, in which 
00453  * case it will have set an error on the error stack.
00454  *
00455  * The error may be one of the following values:
00456  *  NSS_ERROR_INVALID_ATAV
00457  *  NSS_ERROR_NO_MEMORY
00458  *
00459  * Return value:
00460  *  NULL upon error
00461  *  A pointer to a UTF8 string containing the "equals" encoding of the 
00462  *      ATAV
00463  */
00464 
00465 NSS_EXTERN NSSUTF8 *
00466 nssATAV_GetUTF8Encoding
00467 (
00468   NSSATAV *atav,
00469   NSSArena *arenaOpt
00470 );
00471 
00472 /*
00473  * nssATAV_GetType
00474  *
00475  * This routine returns the NSSOID corresponding to the attribute type
00476  * in the specified ATAV.  This routine may return NSS_OID_UNKNOWN 
00477  * upon error, in which case it will have set an error on the error
00478  * stack.
00479  *
00480  * The error may be one of the following values:
00481  *  NSS_ERROR_INVALID_ATAV
00482  *
00483  * Return value:
00484  *  NSS_OID_UNKNOWN upon error
00485  *  An element of enum NSSOIDenum upon success
00486  */
00487 
00488 NSS_EXTERN const NSSOID *
00489 nssATAV_GetType
00490 (
00491   NSSATAV *atav
00492 );
00493 
00494 /*
00495  * nssATAV_GetValue
00496  *
00497  * This routine returns a string containing the attribute value
00498  * in the specified ATAV.  If the optional arena argument is non-null,
00499  * the memory used will be obtained from that arena; otherwise, the
00500  * memory will be obtained from the heap.  This routine may return
00501  * NULL upon error, in which case it will have set an error upon the
00502  * error stack.
00503  *
00504  * The error may be one of the following values:
00505  *  NSS_ERROR_INVALID_ATAV
00506  *  NSS_ERROR_NO_MEMORY
00507  *
00508  * Return value:
00509  *  NULL upon error
00510  *  A pointer to an NSSItem containing the attribute value.
00511  */
00512 
00513 NSS_EXTERN NSSUTF8 *
00514 nssATAV_GetValue
00515 (
00516   NSSATAV *atav,
00517   NSSArena *arenaOpt
00518 );
00519 
00520 /*
00521  * nssATAV_Compare
00522  *
00523  * This routine compares two ATAVs for equality.  For two ATAVs to be
00524  * equal, the attribute types must be the same, and the attribute 
00525  * values must have equal length and contents.  The result of the 
00526  * comparison will be stored at the location pointed to by the "equalp"
00527  * variable, which must point to a valid PRBool.  This routine may 
00528  * return PR_FAILURE upon error, in which case it will have set an 
00529  * error on the error stack.
00530  *
00531  * The error may be one of the following values:
00532  *  NSS_ERROR_INVALID_ATAV
00533  *  NSS_ERROR_INVALID_ARGUMENT
00534  *
00535  * Return value:
00536  *  PR_FAILURE on error
00537  *  PR_SUCCESS upon a successful comparison (equal or not)
00538  */
00539 
00540 NSS_EXTERN PRStatus
00541 nssATAV_Compare
00542 (
00543   NSSATAV *atav1,
00544   NSSATAV *atav2,
00545   PRBool *equalp
00546 );
00547 
00548 /*
00549  * nssATAV_Duplicate
00550  *
00551  * This routine duplicates the specified ATAV.  If the optional arena 
00552  * argument is non-null, the memory required will be obtained from
00553  * that arena; otherwise, the memory will be obtained from the heap.  
00554  * This routine may return NULL upon error, in which case it will have 
00555  * placed an error on the error stack.
00556  *
00557  * The error may be one of the following values:
00558  *  NSS_ERROR_INVALID_ATAV
00559  *  NSS_ERROR_NO_MEMORY
00560  *
00561  * Return value:
00562  *  NULL on error
00563  *  A pointer to a new ATAV
00564  */
00565 
00566 NSS_EXTERN NSSATAV *
00567 nssATAV_Duplicate
00568 (
00569   NSSATAV *atav,
00570   NSSArena *arenaOpt
00571 );
00572 
00573 /*
00574  * nssATAV_verifyPointer
00575  *
00576  * This method is only present in debug builds.
00577  *
00578  * If the specified pointer is a valid pointer to an NSSATAV object,
00579  * this routine will return PR_SUCCESS.  Otherwise, it will put an
00580  * error on the error stack and return PR_FAILRUE.
00581  *
00582  * The error may be one of the following values:
00583  *  NSS_ERROR_INVALID_NSSATAV
00584  *  NSS_ERROR_NO_MEMORY
00585  *
00586  * Return value:
00587  *  PR_SUCCESS if the pointer is valid
00588  *  PR_FAILURE if it isn't
00589  */
00590 
00591 #ifdef DEBUG
00592 NSS_EXTERN PRStatus
00593 nssATAV_verifyPointer
00594 (
00595   NSSATAV *atav
00596 );
00597 #endif /* DEBUG */
00598 
00599 /*
00600  * NSSRDN
00601  *
00602  * The non-public "methods" regarding this "object" are:
00603  *
00604  *  nssRDN_CreateFromBER   -- constructor
00605  *  nssRDN_CreateFromUTF8  -- constructor
00606  *  nssRDN_Create          -- constructor
00607  *  nssRDN_CreateSimple    -- constructor
00608  *
00609  *  nssRDN_Destroy
00610  *  nssRDN_GetDEREncoding
00611  *  nssRDN_GetUTF8Encoding
00612  *  nssRDN_AddATAV
00613  *  nssRDN_GetATAVCount
00614  *  nssRDN_GetATAV
00615  *  nssRDN_GetSimpleATAV
00616  *  nssRDN_Compare
00617  *  nssRDN_Duplicate
00618  */
00619 
00620 /*
00621  * nssRDN_CreateFromBER
00622  *
00623  * This routine creates an NSSRDN by decoding a BER- or DER-encoded 
00624  * RDN.  If the optional arena argument is non-null, the memory used 
00625  * will be obtained from that arena; otherwise, the memory will be 
00626  * obtained from the heap.  This routine may return NULL upon error, 
00627  * in which case it will have set an error on the error stack.
00628  *
00629  * The error may be one of the following values:
00630  *  NSS_ERROR_INVALID_BER
00631  *  NSS_ERROR_NO_MEMORY
00632  *
00633  * Return value:
00634  *  NULL upon error
00635  *  A pointer to an NSSRDN upon success
00636  */
00637 
00638 NSS_EXTERN NSSRDN *
00639 nssRDN_CreateFromBER
00640 (
00641   NSSArena *arenaOpt,
00642   NSSBER *berRDN
00643 );
00644 
00645 /*
00646  * nssRDN_CreateFromUTF8
00647  *
00648  * This routine creates an NSSRDN by decoding an UTF8 string 
00649  * consisting of either a single ATAV in the "equals" format, e.g., 
00650  * "uid=smith," or one or more such ATAVs in parentheses, e.g., 
00651  * "(sn=Smith,ou=Sales)."  If the optional arena argument is non-null,
00652  * the memory used will be obtained from that arena; otherwise, the
00653  * memory will be obtained from the heap.  This routine may return
00654  * NULL upon error, in which case it will have set an error on the
00655  * error stack.
00656  *
00657  * The error may be one of the following values:
00658  *  NSS_ERROR_UNKNOWN_ATTRIBUTE
00659  *  NSS_ERROR_INVALID_UTF8
00660  *  NSS_ERROR_NO_MEMORY
00661  *
00662  * Return value:
00663  *  NULL upon error
00664  *  A pointer to an NSSRDN upon success
00665  */
00666 
00667 NSS_EXTERN NSSRDN *
00668 nssRDN_CreateFromUTF8
00669 (
00670   NSSArena *arenaOpt,
00671   NSSUTF8 *stringRDN
00672 );
00673 
00674 /*
00675  * nssRDN_Create
00676  *
00677  * This routine creates an NSSRDN from one or more NSSATAVs.  The
00678  * final argument to this routine must be NULL.  If the optional arena
00679  * argument is non-null, the memory used will be obtained from that
00680  * arena; otherwise, the memory will be obtained from the heap.  This
00681  * routine may return NULL upon error, in which case it will have set
00682  * an error on the error stack.
00683  *
00684  * The error may be one of the following values:
00685  *  NSS_ERROR_NO_MEMORY
00686  *  NSS_ERROR_INVALID_ATAV
00687  *
00688  * Return value:
00689  *  NULL upon error
00690  *  A pointer to an NSSRDN upon success
00691  */
00692 
00693 NSS_EXTERN NSSRDN *
00694 nssRDN_Create
00695 (
00696   NSSArena *arenaOpt,
00697   NSSATAV *atav1,
00698   ...
00699 );
00700 
00701 /*
00702  * nssRDN_CreateSimple
00703  *
00704  * This routine creates a simple NSSRDN from a single NSSATAV.  If the
00705  * optional arena argument is non-null, the memory used will be 
00706  * obtained from that arena; otherwise, the memory will be obtained
00707  * from the heap.  This routine may return NULL upon error, in which
00708  * case it will have set an error on the error stack.
00709  *
00710  * The error may be one of the following values:
00711  *  NSS_ERROR_NO_MEMORY
00712  *  NSS_ERROR_INVALID_ATAV
00713  *
00714  * Return value:
00715  *  NULL upon error
00716  *  A pointer to an NSSRDN upon success
00717  */
00718 
00719 NSS_EXTERN NSSRDN *
00720 nssRDN_CreateSimple
00721 (
00722   NSSArena *arenaOpt,
00723   NSSATAV *atav
00724 );
00725 
00726 /*
00727  * nssRDN_Destroy
00728  *
00729  * This routine will destroy an RDN object.  It should eventually be
00730  * called on all RDNs created without an arena.  While it is not 
00731  * necessary to call it on RDNs created within an arena, it is not an
00732  * error to do so.  This routine returns a PRStatus value; if
00733  * successful, it will return PR_SUCCESS.  If unsuccessful, it will 
00734  * set an error on the error stack and return PR_FAILURE.
00735  *
00736  * The error may be one of the following values:
00737  *  NSS_ERROR_INVALID_RDN
00738  *
00739  * Return value:
00740  *  PR_FAILURE upon failure
00741  *  PR_SUCCESS upon success
00742  */
00743 
00744 NSS_EXTERN PRStatus
00745 nssRDN_Destroy
00746 (
00747   NSSRDN *rdn
00748 );
00749 
00750 /*
00751  * nssRDN_GetDEREncoding
00752  *
00753  * This routine will DER-encode an RDN object.  If the optional arena
00754  * argument is non-null, the memory used will be obtained from that
00755  * arena; otherwise, the memory will be obtained from the heap.  This
00756  * routine may return null upon error, in which case it will have set
00757  * an error on the error stack.
00758  *
00759  * The error may be one of the following values:
00760  *  NSS_ERROR_INVALID_RDN
00761  *  NSS_ERROR_NO_MEMORY
00762  *
00763  * Return value:
00764  *  NULL upon error
00765  *  The DER encoding of this NSSRDN
00766  */
00767 
00768 NSS_EXTERN NSSDER *
00769 nssRDN_GetDEREncoding
00770 (
00771   NSSRDN *rdn,
00772   NSSArena *arenaOpt
00773 );
00774 
00775 /*
00776  * nssRDN_GetUTF8Encoding
00777  *
00778  * This routine returns a UTF8 string containing a string 
00779  * representation of the RDN.  A simple (one-ATAV) RDN will be simply
00780  * the string representation of that ATAV; a non-simple RDN will be in
00781  * parenthesised form.  If the optional arena argument is non-null, 
00782  * the memory used will be obtained from that arena; otherwise, the 
00783  * memory will be obtained from the heap.  This routine may return 
00784  * null upon error, in which case it will have set an error on the 
00785  * error stack.
00786  *
00787  * The error may be one of the following values:
00788  *  NSS_ERROR_INVALID_RDN
00789  *  NSS_ERROR_NO_MEMORY
00790  *
00791  * Return value:
00792  *  NULL upon error
00793  *  A pointer to a UTF8 string
00794  */
00795 
00796 NSS_EXTERN NSSUTF8 *
00797 nssRDN_GetUTF8Encoding
00798 (
00799   NSSRDN *rdn,
00800   NSSArena *arenaOpt
00801 );
00802 
00803 /*
00804  * nssRDN_AddATAV
00805  *
00806  * This routine adds an ATAV to the set of ATAVs in the specified RDN.
00807  * Remember that RDNs consist of an unordered set of ATAVs.  If the
00808  * RDN was created with a non-null arena argument, that same arena
00809  * will be used for any additional required memory.  If the RDN was 
00810  * created with a NULL arena argument, any additional memory will
00811  * be obtained from the heap.  This routine returns a PRStatus value;
00812  * it will return PR_SUCCESS upon success, and upon failure it will
00813  * set an error on the error stack and return PR_FAILURE.
00814  *
00815  * The error may be one of the following values:
00816  *  NSS_ERROR_INVALID_RDN
00817  *  NSS_ERROR_INVALID_ATAV
00818  *  NSS_ERROR_NO_MEMORY
00819  *
00820  * Return value:
00821  *  PR_SUCCESS upon success
00822  *  PR_FAILURE upon failure
00823  */
00824 
00825 NSS_EXTERN PRStatus
00826 nssRDN_AddATAV
00827 (
00828   NSSRDN *rdn,
00829   NSSATAV *atav
00830 );
00831 
00832 /*
00833  * nssRDN_GetATAVCount
00834  *
00835  * This routine returns the cardinality of the set of ATAVs within
00836  * the specified RDN.  This routine may return 0 upon error, in which 
00837  * case it will have set an error on the error stack.
00838  *
00839  * The error may be one of the following values:
00840  *  NSS_ERROR_INVALID_RDN
00841  *
00842  * Return value:
00843  *  0 upon error
00844  *  A positive number upon success
00845  */
00846 
00847 NSS_EXTERN PRUint32
00848 nssRDN_GetATAVCount
00849 (
00850   NSSRDN *rdn
00851 );
00852 
00853 /*
00854  * nssRDN_GetATAV
00855  *
00856  * This routine returns a pointer to an ATAV that is a member of
00857  * the set of ATAVs within the specified RDN.  While the set of
00858  * ATAVs within an RDN is unordered, this routine will return
00859  * distinct values for distinct values of 'i' as long as the RDN
00860  * is not changed in any way.  The RDN may be changed by calling
00861  * NSSRDN_AddATAV.  The value of the variable 'i' is on the range
00862  * [0,c) where c is the cardinality returned from NSSRDN_GetATAVCount.
00863  * The caller owns the ATAV the pointer to which is returned.  If the
00864  * optional arena argument is non-null, the memory used will be 
00865  * obtained from that arena; otherwise, the memory will be obtained
00866  * from the heap.  This routine may return NULL upon error, in which 
00867  * case it will have set an error upon the error stack.
00868  *
00869  * The error may be one of the following values:
00870  *  NSS_ERROR_INVALID_RDN
00871  *  NSS_ERROR_VALUE_OUT_OF_RANGE
00872  *  NSS_ERROR_NO_MEMORY
00873  *
00874  * Return value:
00875  *  NULL upon error
00876  *  A caller-owned pointer to an NSSATAV
00877  */
00878 
00879 NSS_EXTERN NSSATAV *
00880 nssRDN_GetATAV
00881 (
00882   NSSRDN *rdn,
00883   NSSArena *arenaOpt,
00884   PRUint32 i
00885 );
00886 
00887 /*
00888  * nssRDN_GetSimpleATAV
00889  *
00890  * Most RDNs are actually very simple, with a single ATAV.  This 
00891  * routine will return the single ATAV from such an RDN.  The caller
00892  * owns the ATAV the pointer to which is returned.  If the optional
00893  * arena argument is non-null, the memory used will be obtained from
00894  * that arena; otherwise, the memory will be obtained from the heap.
00895  * This routine may return NULL upon error, including the case where
00896  * the set of ATAVs in the RDN is nonsingular.  Upon error, this
00897  * routine will have set an error on the error stack.
00898  *
00899  * The error may be one of the following values:
00900  *  NSS_ERROR_INVALID_RDN
00901  *  NSS_ERROR_RDN_NOT_SIMPLE
00902  *  NSS_ERROR_NO_MEMORY
00903  *
00904  * Return value:
00905  *  NULL upon error
00906  *  A caller-owned pointer to an NSSATAV
00907  */
00908 
00909 NSS_EXTERN NSSATAV *
00910 nssRDN_GetSimpleATAV
00911 (
00912   NSSRDN *rdn,
00913   NSSArena *arenaOpt
00914 );
00915 
00916 /*
00917  * nssRDN_Compare
00918  *
00919  * This routine compares two RDNs for equality.  For two RDNs to be
00920  * equal, they must have the same number of ATAVs, and every ATAV in
00921  * one must be equal to an ATAV in the other.  (Note that the sets
00922  * of ATAVs are unordered.)  The result of the comparison will be
00923  * stored at the location pointed to by the "equalp" variable, which
00924  * must point to a valid PRBool.  This routine may return PR_FAILURE
00925  * upon error, in which case it will have set an error on the error
00926  * stack.
00927  *
00928  * The error may be one of the following values:
00929  *  NSS_ERROR_INVALID_RDN
00930  *  NSS_ERROR_INVALID_ARGUMENT
00931  *
00932  * Return value:
00933  *  PR_FAILURE on error
00934  *  PR_SUCCESS upon a successful comparison (equal or not)
00935  */
00936 
00937 NSS_EXTERN PRStatus
00938 nssRDN_Compare
00939 (
00940   NSSRDN *rdn1,
00941   NSSRDN *rdn2,
00942   PRBool *equalp
00943 );
00944 
00945 /*
00946  * nssRDN_Duplicate
00947  *
00948  * This routine duplicates the specified RDN.  If the optional arena
00949  * argument is non-null, the memory required will be obtained from
00950  * that arena; otherwise, the memory will be obtained from the heap.
00951  * This routine may return NULL upon error, in which case it will have
00952  * placed an error on the error stack.
00953  *
00954  * The error may be one of the following values:
00955  *  NSS_ERROR_INVALID_RDN
00956  *  NSS_ERROR_NO_MEMORY
00957  *
00958  * Return value:
00959  *  NULL on error
00960  *  A pointer to a new RDN
00961  */
00962 
00963 NSS_EXTERN NSSRDN *
00964 nssRDN_Duplicate
00965 (
00966   NSSRDN *rdn,
00967   NSSArena *arenaOpt
00968 );
00969 
00970 /*
00971  * NSSRDNSeq
00972  *
00973  * The non-public "methods" regarding this "object" are:
00974  *
00975  *  nssRDNSeq_CreateFromBER   -- constructor
00976  *  nssRDNSeq_CreateFromUTF8  -- constructor
00977  *  nssRDNSeq_Create          -- constructor
00978  *
00979  *  nssRDNSeq_Destroy
00980  *  nssRDNSeq_GetDEREncoding
00981  *  nssRDNSeq_GetUTF8Encoding
00982  *  nssRDNSeq_AppendRDN
00983  *  nssRDNSeq_GetRDNCount
00984  *  nssRDNSeq_GetRDN
00985  *  nssRDNSeq_Compare
00986  *  nssRDNSeq_Duplicate
00987  *
00988  *  nssRDNSeq_EvaluateUTF8 -- not an object method
00989  */
00990 
00991 /*
00992  * nssRDNSeq_CreateFromBER
00993  *
00994  * This routine creates an NSSRDNSeq by decoding a BER- or DER-encoded 
00995  * sequence of RDNs.  If the optional arena argument is non-null,
00996  * the memory used will be obtained from that arena; otherwise, the
00997  * memory will be obtained from the heap.  This routine may return 
00998  * NULL upon error, in which case it will have set an error on the
00999  * error stack.
01000  *
01001  * The error may be one of the following values:
01002  *  NSS_ERROR_INVALID_BER
01003  *  NSS_ERROR_NO_MEMORY
01004  *
01005  * Return value:
01006  *  NULL upon error
01007  *  A pointer to an NSSRDNSeq upon success
01008  */
01009 
01010 NSS_EXTERN NSSRDNSeq *
01011 nssRDNSeq_CreateFromBER
01012 (
01013   NSSArena *arenaOpt,
01014   NSSBER *berRDNSeq
01015 );
01016 
01017 /*
01018  * nssRDNSeq_CreateFromUTF8
01019  *
01020  * This routine creates an NSSRDNSeq by decoding a UTF8 string
01021  * consisting of a comma-separated sequence of RDNs, such as
01022  * "(sn=Smith,ou=Sales),o=Acme,c=US."  If the optional arena argument
01023  * is non-null, the memory used will be obtained from that arena; 
01024  * otherwise, the memory will be obtained from the heap.  This routine
01025  * may return NULL upon error, in which case it will have set an error
01026  * on the error stack.
01027  *
01028  * The error may be one of the following values:
01029  *  NSS_ERROR_UNKNOWN_ATTRIBUTE
01030  *  NSS_ERROR_INVALID_UTF8
01031  *  NSS_ERROR_NO_MEMORY
01032  *
01033  * Return value:
01034  *  NULL upon error
01035  *  A pointer to an NSSRDNSeq upon success
01036  */
01037 
01038 NSS_EXTERN NSSRDNSeq *
01039 nssRDNSeq_CreateFromUTF8
01040 (
01041   NSSArena *arenaOpt,
01042   NSSUTF8 *stringRDNSeq
01043 );
01044 
01045 /*
01046  * nssRDNSeq_Create
01047  *
01048  * This routine creates an NSSRDNSeq from one or more NSSRDNs.  The
01049  * final argument to this routine must be NULL.  If the optional arena
01050  * argument is non-null, the memory used will be obtained from that
01051  * arena; otherwise, the memory will be obtained from the heap.  This
01052  * routine may return NULL upon error, in which case it will have set
01053  * an error on the error stack.
01054  *
01055  * The error may be one of the following values:
01056  *  NSS_ERROR_NO_MEMORY
01057  *  NSS_ERROR_INVALID_RDN
01058  *
01059  * Return value:
01060  *  NULL upon error
01061  *  A pointero to an NSSRDNSeq upon success
01062  */
01063 
01064 NSS_EXTERN NSSRDNSeq *
01065 nssRDNSeq_Create
01066 (
01067   NSSArena *arenaOpt,
01068   NSSRDN *rdn1,
01069   ...
01070 );
01071 
01072 /*
01073  * nssRDNSeq_Destroy
01074  *
01075  * This routine will destroy an RDNSeq object.  It should eventually 
01076  * be called on all RDNSeqs created without an arena.  While it is not
01077  * necessary to call it on RDNSeqs created within an arena, it is not
01078  * an error to do so.  This routine returns a PRStatus value; if
01079  * successful, it will return PR_SUCCESS.  If unsuccessful, it will
01080  * set an error on the error stack and return PR_FAILURE.
01081  *
01082  * The error may be one of the following values:
01083  *  NSS_ERROR_INVALID_RDNSEQ
01084  *
01085  * Return value:
01086  *  PR_FAILURE upon error
01087  *  PR_SUCCESS upon success
01088  */
01089 
01090 NSS_EXTERN PRStatus
01091 nssRDNSeq_Destroy
01092 (
01093   NSSRDNSeq *rdnseq
01094 );
01095 
01096 /*
01097  * nssRDNSeq_GetDEREncoding
01098  *
01099  * This routine will DER-encode an RDNSeq object.  If the optional 
01100  * arena argument is non-null, the memory used will be obtained from
01101  * that arena; otherwise, the memory will be obtained from the heap.
01102  * This routine may return null upon error, in which case it will have
01103  * set an error on the error stack.
01104  *
01105  * The error may be one of the following values:
01106  *  NSS_ERROR_INVALID_RDNSEQ
01107  *  NSS_ERROR_NO_MEMORY
01108  *
01109  * Return value:
01110  *  NULL upon error
01111  *  The DER encoding of this NSSRDNSeq
01112  */
01113 
01114 NSS_EXTERN NSSDER *
01115 nssRDNSeq_GetDEREncoding
01116 (
01117   NSSRDNSeq *rdnseq,
01118   NSSArena *arenaOpt
01119 );
01120 
01121 /*
01122  * nssRDNSeq_GetUTF8Encoding
01123  *
01124  * This routine returns a UTF8 string containing a string 
01125  * representation of the RDNSeq as a comma-separated sequence of RDNs.  
01126  * If the optional arena argument is non-null, the memory used will be
01127  * obtained from that arena; otherwise, the memory will be obtained 
01128  * from the heap.  This routine may return null upon error, in which 
01129  * case it will have set an error on the error stack.
01130  *
01131  * The error may be one of the following values:
01132  *  NSS_ERROR_INVALID_RDNSEQ
01133  *  NSS_ERROR_NO_MEMORY
01134  *
01135  * Return value:
01136  *  NULL upon error
01137  *  A pointer to the UTF8 string
01138  */
01139 
01140 NSS_EXTERN NSSUTF8 *
01141 nssRDNSeq_GetUTF8Encoding
01142 (
01143   NSSRDNSeq *rdnseq,
01144   NSSArena *arenaOpt
01145 );
01146 
01147 /*
01148  * nssRDNSeq_AppendRDN
01149  *
01150  * This routine appends an RDN to the end of the existing RDN 
01151  * sequence.  If the RDNSeq was created with a non-null arena 
01152  * argument, that same arena will be used for any additional required
01153  * memory.  If the RDNSeq was created with a NULL arena argument, any
01154  * additional memory will be obtained from the heap.  This routine
01155  * returns a PRStatus value; it will return PR_SUCCESS upon success,
01156  * and upon failure it will set an error on the error stack and return
01157  * PR_FAILURE.
01158  *
01159  * The error may be one of the following values:
01160  *  NSS_ERROR_INVALID_RDNSEQ
01161  *  NSS_ERROR_INVALID_RDN
01162  *  NSS_ERROR_NO_MEMORY
01163  *
01164  * Return value:
01165  *  PR_SUCCESS upon success
01166  *  PR_FAILURE upon failure
01167  */
01168 
01169 NSS_EXTERN PRStatus
01170 nssRDNSeq_AppendRDN
01171 (
01172   NSSRDNSeq *rdnseq,
01173   NSSRDN *rdn
01174 );
01175 
01176 /*
01177  * nssRDNSeq_GetRDNCount
01178  *
01179  * This routine returns the cardinality of the sequence of RDNs within
01180  * the specified RDNSeq.  This routine may return 0 upon error, in 
01181  * which case it will have set an error on the error stack.
01182  *
01183  * The error may be one of the following values:
01184  *  NSS_ERROR_INVALID_RDNSEQ
01185  *
01186  * Return value:
01187  *  0 upon error
01188  *  A positive number upon success
01189  */
01190 
01191 NSS_EXTERN PRUint32
01192 nssRDNSeq_GetRDNCount
01193 (
01194   NSSRDNSeq *rdnseq
01195 );
01196 
01197 /*
01198  * nssRDNSeq_GetRDN
01199  *
01200  * This routine returns a pointer to the i'th RDN in the sequence of
01201  * RDNs that make up the specified RDNSeq.  The sequence begins with
01202  * the top-level (e.g., "c=US") RDN.  The value of the variable 'i'
01203  * is on the range [0,c) where c is the cardinality returned from
01204  * NSSRDNSeq_GetRDNCount.  The caller owns the RDN the pointer to which
01205  * is returned.  If the optional arena argument is non-null, the memory
01206  * used will be obtained from that areana; otherwise, the memory will 
01207  * be obtained from the heap.  This routine may return NULL upon error,
01208  * in which case it will have set an error upon the error stack.  Note
01209  * that the usual UTF8 representation of RDN Sequences is from last
01210  * to first.
01211  *
01212  * The error may be one of the following values:
01213  *  NSS_ERROR_INVALID_RDNSEQ
01214  *  NSS_ERROR_VALUE_OUT_OF_RANGE
01215  *  NSS_ERROR_NO_MEMORY
01216  *
01217  * Return value:
01218  *  NULL upon error
01219  *  A caller-owned pointer to an NSSRDN
01220  */
01221 
01222 NSS_EXTERN NSSRDN *
01223 nssRDNSeq_GetRDN
01224 (
01225   NSSRDNSeq *rdnseq,
01226   NSSArena *arenaOpt,
01227   PRUint32 i
01228 );
01229 
01230 /*
01231  * nssRDNSeq_Compare
01232  *
01233  * This routine compares two RDNSeqs for equality.  For two RDNSeqs to 
01234  * be equal, they must have the same number of RDNs, and each RDN in
01235  * one sequence must be equal to the corresponding RDN in the other
01236  * sequence.  The result of the comparison will be stored at the
01237  * location pointed to by the "equalp" variable, which must point to a
01238  * valid PRBool.  This routine may return PR_FAILURE upon error, in
01239  * which case it will have set an error on the error stack.
01240  *
01241  * The error may be one of the following values:
01242  *  NSS_ERROR_INVALID_RDNSEQ
01243  *  NSS_ERROR_INVALID_ARGUMENT
01244  *
01245  * Return value:
01246  *  PR_FAILURE on error
01247  *  PR_SUCCESS upon a successful comparison (equal or not)
01248  */
01249 
01250 NSS_EXTERN PRStatus
01251 nssRDNSeq_Compare
01252 (
01253   NSSRDNSeq *rdnseq1,
01254   NSSRDNSeq *rdnseq2,
01255   PRBool *equalp
01256 );
01257 
01258 /*
01259  * nssRDNSeq_Duplicate
01260  *
01261  * This routine duplicates the specified RDNSeq.  If the optional arena
01262  * argument is non-null, the memory required will be obtained from that
01263  * arena; otherwise, the memory will be obtained from the heap.  This 
01264  * routine may return NULL upon error, in which case it will have 
01265  * placed an error on the error stack.
01266  *
01267  * The error may be one of the following values:
01268  *  NSS_ERROR_INVALID_RDNSEQ
01269  *  NSS_ERROR_NO_MEMORY
01270  *
01271  * Return value:
01272  *  NULL upon error
01273  *  A pointer to a new RDNSeq
01274  */
01275 
01276 NSS_EXTERN NSSRDNSeq *
01277 nssRDNSeq_Duplicate
01278 (
01279   NSSRDNSeq *rdnseq,
01280   NSSArena *arenaOpt
01281 );
01282 
01283 /*
01284  * nssRDNSeq_EvaluateUTF8
01285  *
01286  * This routine evaluates a UTF8 string, and returns PR_TRUE if the 
01287  * string contains the string representation of an RDNSeq.  This 
01288  * routine is used by the (directory) Name routines 
01289  * nssName_CreateFromUTF8 and nssName_EvaluateUTF8 to determine which
01290  * choice of directory name the string may encode.  This routine may 
01291  * return PR_FALSE upon error, but it subsumes that condition under the
01292  * general "string does not evaluate as an RDNSeq" state, and does not
01293  * set an error on the error stack.
01294  *
01295  * Return value:
01296  *  PR_TRUE if the string represents an RDNSeq
01297  *  PR_FALSE if otherwise
01298  */
01299 
01300 NSS_EXTERN PRBool
01301 nssRDNSeq_EvaluateUTF8
01302 (
01303   NSSUTF8 *str
01304 );
01305 
01306 /*
01307  * NSSName
01308  *
01309  * The non-public "methods" regarding this "object" are:
01310  *
01311  * nssName_CreateFromBER   -- constructor
01312  * nssName_CreateFromUTF8  -- constructor
01313  * nssName_Create          -- constructor
01314  *
01315  * nssName_Destroy
01316  * nssName_GetDEREncoding
01317  * nssName_GetUTF8Encoding
01318  * nssName_GetChoice
01319  * nssName_GetRDNSequence
01320  * nssName_GetSpecifiedChoice
01321  * nssName_Compare
01322  * nssName_Duplicate
01323  *
01324  * nssName_GetUID
01325  * nssName_GetEmail
01326  * nssName_GetCommonName
01327  * nssName_GetOrganization
01328  * nssName_GetOrganizationalUnits
01329  * nssName_GetStateOrProvince
01330  * nssName_GetLocality
01331  * nssName_GetCountry
01332  * nssName_GetAttribute
01333  *
01334  * nssName_EvaluateUTF8 -- not an object method
01335  */
01336 
01337 /*
01338  * nssName_CreateFromBER
01339  *
01340  * This routine creates an NSSName by decoding a BER- or DER-encoded 
01341  * (directory) Name.  If the optional arena argument is non-null,
01342  * the memory used will be obtained from that arena; otherwise, 
01343  * the memory will be obtained from the heap.  This routine may
01344  * return NULL upon error, in which case it will have set an error
01345  * on the error stack.
01346  *
01347  * The error may be one of the following values:
01348  *  NSS_ERROR_INVALID_BER
01349  *  NSS_ERROR_NO_MEMORY
01350  *
01351  * Return value:
01352  *  NULL upon error
01353  *  A pointer to an NSSName upon success
01354  */
01355 
01356 NSS_EXTERN NSSName *
01357 nssName_CreateFromBER
01358 (
01359   NSSArena *arenaOpt,
01360   NSSBER *berName
01361 );
01362 
01363 /*
01364  * nssName_CreateFromUTF8
01365  *
01366  * This routine creates an NSSName by decoding a UTF8 string 
01367  * consisting of the string representation of one of the choices of 
01368  * (directory) names.  Currently the only choice is an RDNSeq.  If the
01369  * optional arena argument is non-null, the memory used will be 
01370  * obtained from that arena; otherwise, the memory will be obtained 
01371  * from the heap.  The routine may return NULL upon error, in which
01372  * case it will have set an error on the error stack.
01373  *
01374  * The error may be one of the following values:
01375  *  NSS_ERROR_INVALID_UTF8
01376  *  NSS_ERROR_NO_MEMORY
01377  *
01378  * Return value:
01379  *  NULL upon error
01380  *  A pointer to an NSSName upon success
01381  */
01382 
01383 NSS_EXTERN NSSName *
01384 nssName_CreateFromUTF8
01385 (
01386   NSSArena *arenaOpt,
01387   NSSUTF8 *stringName
01388 );
01389 
01390 /*
01391  * nssName_Create
01392  *
01393  * This routine creates an NSSName with the specified choice of
01394  * underlying name types.  The value of the choice variable must be
01395  * one of the values of the NSSNameChoice enumeration, and the type
01396  * of the arg variable must be as specified in the following table:
01397  *
01398  *   Choice                     Type
01399  *   ========================   ===========
01400  *   NSSNameChoiceRdnSequence   NSSRDNSeq *
01401  *
01402  * If the optional arena argument is non-null, the memory used will
01403  * be obtained from that arena; otherwise, the memory will be 
01404  * obtained from the heap.  This routine may return NULL upon error,
01405  * in which case it will have set an error on the error stack.
01406  *
01407  * The error may be one of the following values:
01408  *  NSS_ERROR_INVALID_CHOICE
01409  *  NSS_ERROR_INVALID_ARGUMENT
01410  *  NSS_ERROR_NO_MEMORY
01411  *
01412  * Return value:
01413  *  NULL upon error
01414  *  A pointer to an NSSName upon success
01415  */
01416 
01417 NSS_EXTERN NSSName *
01418 nssName_Create
01419 (
01420   NSSArena *arenaOpt,
01421   NSSNameChoice choice,
01422   void *arg
01423 );
01424 
01425 /*
01426  * nssName_Destroy
01427  *
01428  * This routine will destroy a Name object.  It should eventually be
01429  * called on all Names created without an arena.  While it is not
01430  * necessary to call it on Names created within an arena, it is not
01431  * an error to do so.  This routine returns a PRStatus value; if
01432  * successful, it will return PR_SUCCESS.  If unsuccessful, it will
01433  * set an error on the error stack and return PR_FAILURE.
01434  *
01435  * The error may be one of the following values:
01436  *  NSS_ERROR_INVALID_NAME
01437  *
01438  * Return value:
01439  *  PR_FAILURE upon error
01440  *  PR_SUCCESS upon success
01441  */
01442 
01443 NSS_EXTERN PRStatus
01444 nssName_Destroy
01445 (
01446   NSSName *name
01447 );
01448 
01449 /*
01450  * nssName_GetDEREncoding
01451  *
01452  * This routine will DER-encode a name object.  If the optional arena
01453  * argument is non-null, the memory used will be obtained from that
01454  * arena; otherwise, the memory will be obtained from the heap.  This
01455  * routine may return null upon error, in which case it will have set
01456  * an error on the error stack.
01457  *
01458  * The error may be one of the following values:
01459  *  NSS_ERROR_INVALID_NAME
01460  *  NSS_ERROR_NO_MEMORY
01461  *
01462  * Return value:
01463  *  NULL upon error
01464  *  The DER encoding of this NSSName
01465  */
01466 
01467 NSS_EXTERN NSSDER *
01468 nssName_GetDEREncoding
01469 (
01470   NSSName *name,
01471   NSSArena *arenaOpt
01472 );
01473 
01474 /*
01475  * nssName_GetUTF8Encoding
01476  *
01477  * This routine returns a UTF8 string containing a string 
01478  * representation of the Name in the format specified by the 
01479  * underlying name choice.  If the optional arena argument is non-null,
01480  * the memory used will be obtained from that arena; otherwise, the 
01481  * memory will be obtained from the heap.  This routine may return
01482  * NULL upon error, in which case it will have set an error on the 
01483  * error stack.
01484  *
01485  * The error may be one of the following values:
01486  *  NSS_ERROR_INVALID_NAME
01487  *  NSS_ERROR_NO_MEMORY
01488  *
01489  * Return value:
01490  *  NULL upon error
01491  *  A pointer to the UTF8 string
01492  */
01493 
01494 NSS_EXTERN NSSUTF8 *
01495 nssName_GetUTF8Encoding
01496 (
01497   NSSName *name,
01498   NSSArena *arenaOpt
01499 );
01500 
01501 /*
01502  * nssName_GetChoice
01503  *
01504  * This routine returns the type of the choice underlying the specified
01505  * name.  The return value will be a member of the NSSNameChoice 
01506  * enumeration.  This routine may return NSSNameChoiceInvalid upon 
01507  * error, in which case it will have set an error on the error stack.
01508  *
01509  * The error may be one of the following values:
01510  *  NSS_ERROR_INVALID_NAME
01511  *
01512  * Return value:
01513  *  NSSNameChoiceInvalid upon error
01514  *  An other member of the NSSNameChoice enumeration upon success
01515  */
01516 
01517 NSS_EXTERN NSSNameChoice
01518 nssName_GetChoice
01519 (
01520   NSSName *name
01521 );
01522 
01523 /*
01524  * nssName_GetRDNSequence
01525  *
01526  * If the choice underlying the specified NSSName is that of an 
01527  * RDNSequence, this routine will return a pointer to that RDN
01528  * sequence.  Otherwise, this routine will place an error on the
01529  * error stack, and return NULL.  If the optional arena argument is
01530  * non-null, the memory required will be obtained from that arena;
01531  * otherwise, the memory will be obtained from the heap.  The
01532  * caller owns the returned pointer.  This routine may return NULL
01533  * upon error, in which case it will have set an error on the error
01534  * stack.
01535  *
01536  * The error may be one of the following values:
01537  *  NSS_ERROR_INVALID_NAME
01538  *  NSS_ERROR_WRONG_CHOICE
01539  *  NSS_ERROR_NO_MEMORY
01540  *
01541  * Return value:
01542  *  NULL upon error
01543  *  A caller-owned pointer to an NSSRDNSeq
01544  */
01545 
01546 NSS_EXTERN NSSRDNSeq *
01547 nssName_GetRDNSequence
01548 (
01549   NSSName *name,
01550   NSSArena *arenaOpt
01551 );
01552 
01553 /*
01554  * nssName_GetSpecifiedChoice
01555  *
01556  * If the choice underlying the specified NSSName matches the specified
01557  * choice, a caller-owned pointer to that underlying object will be
01558  * returned.  Otherwise, an error will be placed on the error stack and
01559  * NULL will be returned.  If the optional arena argument is non-null, 
01560  * the memory required will be obtained from that arena; otherwise, the
01561  * memory will be obtained from the heap.  The caller owns the returned
01562  * pointer.  This routine may return NULL upon error, in which case it
01563  * will have set an error on the error stack.
01564  *
01565  * The error may be one of the following values:
01566  *  NSS_ERROR_INVALID_NAME
01567  *  NSS_ERROR_WRONG_CHOICE
01568  *  NSS_ERROR_NO_MEMORY
01569  *
01570  * Return value:
01571  *  NULL upon error
01572  *  A caller-owned pointer, which must be typecast
01573  */
01574 
01575 NSS_EXTERN void *
01576 nssName_GetSpecifiedChoice
01577 (
01578   NSSName *name,
01579   NSSNameChoice choice,
01580   NSSArena *arenaOpt
01581 );
01582 
01583 /*
01584  * nssName_Compare
01585  *
01586  * This routine compares two Names for equality.  For two Names to be
01587  * equal, they must have the same choice of underlying types, and the
01588  * underlying values must be equal.  The result of the comparison will
01589  * be stored at the location pointed to by the "equalp" variable, which
01590  * must point to a valid PRBool. This routine may return PR_FAILURE
01591  * upon error, in which case it will have set an error on the error
01592  * stack.
01593  *
01594  * The error may be one of the following values:
01595  *  NSS_ERROR_INVALID_NAME
01596  *  NSS_ERROR_INVALID_ARGUMENT
01597  *
01598  * Return value:
01599  *  PR_FAILURE on error
01600  *  PR_SUCCESS upon a successful comparison (equal or not)
01601  */
01602 
01603 NSS_EXTERN PRStatus
01604 nssName_Compare
01605 (
01606   NSSName *name1,
01607   NSSName *name2,
01608   PRBool *equalp
01609 );
01610 
01611 /*
01612  * nssName_Duplicate
01613  *
01614  * This routine duplicates the specified nssname.  If the optional
01615  * arena argument is non-null, the memory required will be obtained
01616  * from that arena; otherwise, the memory will be obtained from the
01617  * heap.  This routine may return NULL upon error, in which case it
01618  * will have placed an error on the error stack.
01619  *
01620  * The error may be one of the following values:
01621  *  NSS_ERROR_INVALID_NAME
01622  *  NSS_ERROR_NO_MEMORY
01623  *
01624  * Return value:
01625  *  NULL upon error
01626  *  A pointer to a new NSSName
01627  */
01628 
01629 NSS_EXTERN NSSName *
01630 nssName_Duplicate
01631 (
01632   NSSName *name,
01633   NSSArena *arenaOpt
01634 );
01635 
01636 /*
01637  * nssName_GetUID
01638  *
01639  * This routine will attempt to derive a user identifier from the
01640  * specified name, if the choices and content of the name permit.
01641  * If the Name consists of a Sequence of Relative Distinguished 
01642  * Names containing a UID attribute, the UID will be the value of 
01643  * that attribute.  Note that no UID attribute is defined in either 
01644  * PKIX or PKCS#9; rather, this seems to derive from RFC 1274, which 
01645  * defines the type as a caseIgnoreString.  We'll return a Directory 
01646  * String.  If the optional arena argument is non-null, the memory 
01647  * used will be obtained from that arena; otherwise, the memory will 
01648  * be obtained from the heap.  This routine may return NULL upon error,
01649  * in which case it will have set an error on the error stack.
01650  *
01651  * The error may be one of the following values:
01652  *  NSS_ERROR_INVALID_NAME
01653  *  NSS_ERROR_NO_UID
01654  *  NSS_ERROR_NO_MEMORY
01655  *
01656  * Return value:
01657  *  NULL upon error
01658  *  A pointer to a UTF8 String.
01659  */
01660 
01661 NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
01662 nssName_GetUID
01663 (
01664   NSSName *name,
01665   NSSArena *arenaOpt
01666 );
01667 
01668 /*
01669  * nssName_GetEmail
01670  *
01671  * This routine will attempt to derive an email address from the
01672  * specified name, if the choices and content of the name permit.  
01673  * If the Name consists of a Sequence of Relative Distinguished 
01674  * Names containing either a PKIX email address or a PKCS#9 email
01675  * address, the result will be the value of that attribute.  If the
01676  * optional arena argument is non-null, the memory used will be
01677  * obtained from that arena; otherwise, the memory will be obtained
01678  * from the heap.  This routine may return NULL upon error, in which
01679  * case it will have set an error on the error stack.
01680  *
01681  * The error may be one of the following values:
01682  *  NSS_ERROR_INVALID_NAME
01683  *  NSS_ERROR_NO_EMAIL
01684  *  NSS_ERROR_NO_MEMORY
01685  *
01686  * Return value:
01687  *  NULL upon error
01688  *  A pointer to a UTF8 String
01689  */
01690 
01691 NSS_EXTERN NSSUTF8 * /* XXX fgmr IA5 String */
01692 nssName_GetEmail
01693 (
01694   NSSName *name,
01695   NSSArena *arenaOpt
01696 );
01697 
01698 /*
01699  * nssName_GetCommonName
01700  *
01701  * This routine will attempt to derive a common name from the
01702  * specified name, if the choices and content of the name permit.  
01703  * If the Name consists of a Sequence of Relative Distinguished Names
01704  * containing a PKIX Common Name, the result will be that name.  If 
01705  * the optional arena argument is non-null, the memory used will be 
01706  * obtained from that arena; otherwise, the memory will be obtained 
01707  * from the heap.  This routine may return NULL upon error, in which 
01708  * case it will have set an error on the error stack.
01709  *
01710  * The error may be one of the following values:
01711  *  NSS_ERROR_INVALID_NAME
01712  *  NSS_ERROR_NO_COMMON_NAME
01713  *  NSS_ERROR_NO_MEMORY
01714  *
01715  * Return value:
01716  *  NULL upon error
01717  *  A pointer to a UTF8 String
01718  */
01719 
01720 NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
01721 nssName_GetCommonName
01722 (
01723   NSSName *name,
01724   NSSArena *arenaOpt
01725 );
01726 
01727 /*
01728  * nssName_GetOrganization
01729  *
01730  * This routine will attempt to derive an organisation name from the
01731  * specified name, if the choices and content of the name permit.  
01732  * If Name consists of a Sequence of Relative Distinguished names 
01733  * containing a PKIX Organization, the result will be the value of 
01734  * that attribute.  If the optional arena argument is non-null, the 
01735  * memory used will be obtained from that arena; otherwise, the memory 
01736  * will be obtained from the heap.  This routine may return NULL upon 
01737  * error, in which case it will have set an error on the error stack.
01738  *
01739  * The error may be one of the following values:
01740  *  NSS_ERROR_INVALID_NAME
01741  *  NSS_ERROR_NO_ORGANIZATION
01742  *  NSS_ERROR_NO_MEMORY
01743  *
01744  * Return value:
01745  *  NULL upon error
01746  *  A pointer to a UTF8 String
01747  */
01748 
01749 NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
01750 nssName_GetOrganization
01751 (
01752   NSSName *name,
01753   NSSArena *arenaOpt
01754 );
01755 
01756 /*
01757  * nssName_GetOrganizationalUnits
01758  *
01759  * This routine will attempt to derive a sequence of organisational 
01760  * unit names from the specified name, if the choices and content of 
01761  * the name permit.  If the Name consists of a Sequence of Relative 
01762  * Distinguished Names containing one or more organisational units,
01763  * the result will be the values of those attributes.  If the optional 
01764  * arena argument is non-null, the memory used will be obtained from 
01765  * that arena; otherwise, the memory will be obtained from the heap.  
01766  * This routine may return NULL upon error, in which case it will have 
01767  * set an error on the error stack.
01768  *
01769  * The error may be one of the following values:
01770  *  NSS_ERROR_INVALID_NAME
01771  *  NSS_ERROR_NO_ORGANIZATIONAL_UNITS
01772  *  NSS_ERROR_NO_MEMORY
01773  *
01774  * Return value:
01775  *  NULL upon error
01776  *  A pointer to a null-terminated array of UTF8 Strings
01777  */
01778 
01779 NSS_EXTERN NSSUTF8 ** /* XXX fgmr DirectoryString */
01780 nssName_GetOrganizationalUnits
01781 (
01782   NSSName *name,
01783   NSSArena *arenaOpt
01784 );
01785 
01786 /*
01787  * nssName_GetStateOrProvince
01788  *
01789  * This routine will attempt to derive a state or province name from 
01790  * the specified name, if the choices and content of the name permit.
01791  * If the Name consists of a Sequence of Relative Distinguished Names
01792  * containing a state or province, the result will be the value of 
01793  * that attribute.  If the optional arena argument is non-null, the 
01794  * memory used will be obtained from that arena; otherwise, the memory 
01795  * will be obtained from the heap.  This routine may return NULL upon 
01796  * error, in which case it will have set an error on the error stack.
01797  *
01798  * The error may be one of the following values:
01799  *  NSS_ERROR_INVALID_NAME
01800  *  NSS_ERROR_NO_STATE_OR_PROVINCE
01801  *  NSS_ERROR_NO_MEMORY
01802  *
01803  * Return value:
01804  *  NULL upon error
01805  *  A pointer to a UTF8 String
01806  */
01807 
01808 NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
01809 nssName_GetStateOrProvince
01810 (
01811   NSSName *name,
01812   NSSArena *arenaOpt
01813 );
01814 
01815 /*
01816  * nssName_GetLocality
01817  *
01818  * This routine will attempt to derive a locality name from the 
01819  * specified name, if the choices and content of the name permit.  If
01820  * the Name consists of a Sequence of Relative Distinguished names
01821  * containing a Locality, the result will be the value of that 
01822  * attribute.  If the optional arena argument is non-null, the memory 
01823  * used will be obtained from that arena; otherwise, the memory will 
01824  * be obtained from the heap.  This routine may return NULL upon error,
01825  * in which case it will have set an error on the error stack.
01826  *
01827  * The error may be one of the following values:
01828  *  NSS_ERROR_INVALID_NAME
01829  *  NSS_ERROR_NO_LOCALITY
01830  *  NSS_ERROR_NO_MEMORY
01831  *
01832  * Return value:
01833  *  NULL upon error
01834  *  A pointer to a UTF8 String
01835  */
01836 
01837 NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
01838 nssName_GetLocality
01839 (
01840   NSSName *name,
01841   NSSArena *arenaOpt
01842 );
01843 
01844 /*
01845  * nssName_GetCountry
01846  *
01847  * This routine will attempt to derive a country name from the 
01848  * specified name, if the choices and content of the name permit.
01849  * If the Name consists of a Sequence of Relative Distinguished 
01850  * Names containing a Country, the result will be the value of
01851  * that attribute..  If the optional arena argument is non-null, 
01852  * the memory used will be obtained from that arena; otherwise, 
01853  * the memory will be obtained from the heap.  This routine may 
01854  * return NULL upon error, in which case it will have set an error 
01855  * on the error stack.
01856  *
01857  * The error may be one of the following values:
01858  *  NSS_ERROR_INVALID_NAME
01859  *  NSS_ERROR_NO_COUNTRY
01860  *  NSS_ERROR_NO_MEMORY
01861  *
01862  * Return value:
01863  *  NULL upon error
01864  *  A pointer to a UTF8 String
01865  */
01866 
01867 NSS_EXTERN NSSUTF8 * /* XXX fgmr PrintableString */
01868 nssName_GetCountry
01869 (
01870   NSSName *name,
01871   NSSArena *arenaOpt
01872 );
01873 
01874 /*
01875  * nssName_GetAttribute
01876  *
01877  * If the specified name consists of a Sequence of Relative 
01878  * Distinguished Names containing an attribute with the specified 
01879  * type, and the actual value of that attribute may be expressed 
01880  * with a Directory String, then the value of that attribute will 
01881  * be returned as a Directory String.  If the optional arena argument 
01882  * is non-null, the memory used will be obtained from that arena; 
01883  * otherwise, the memory will be obtained from the heap.  This routine 
01884  * may return NULL upon error, in which case it will have set an error 
01885  * on the error stack.
01886  *
01887  * The error may be one of the following values:
01888  *  NSS_ERROR_INVALID_NAME
01889  *  NSS_ERROR_NO_ATTRIBUTE
01890  *  NSS_ERROR_ATTRIBUTE_VALUE_NOT_STRING
01891  *
01892  * Return value:
01893  *  NULL upon error
01894  *  A pointer to a UTF8 String
01895  */
01896 
01897 NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
01898 nssName_GetAttribute
01899 (
01900   NSSName *name,
01901   NSSOID *attribute,
01902   NSSArena *arenaOpt
01903 );
01904 
01905 /*
01906  * nssName_EvaluateUTF8
01907  *
01908  * This routine evaluates a UTF8 string, and returns PR_TRUE if the 
01909  * string contains the string representation of an NSSName.  This 
01910  * routine is used by the GeneralName routine 
01911  * nssGeneralName_CreateFromUTF8 to determine which choice of
01912  * general name the string may encode.  This routine may return 
01913  * PR_FALSE upon error, but it subsumes that condition under the 
01914  * general "string does not evaluate as a Name" state, and does not
01915  * set an error on the error stack.
01916  * 
01917  * Return value:
01918  *  PR_TRUE if the string represents a Name
01919  *  PR_FALSE otherwise
01920  */
01921 
01922 NSS_EXTERN PRBool
01923 nssName_EvaluateUTF8
01924 (
01925   NSSUTF8 *str
01926 );
01927 
01928 /*
01929  * NSSGeneralName
01930  *
01931  * The non-public "methods" regarding this "object" are:
01932  *
01933  * nssGeneralName_CreateFromBER   -- constructor
01934  * nssGeneralName_CreateFromUTF8  -- constructor
01935  * nssGeneralName_Create          -- constructor
01936  *
01937  * nssGeneralName_Destroy
01938  * nssGeneralName_GetDEREncoding
01939  * nssGeneralName_GetUTF8Encoding
01940  * nssGeneralName_GetChoice
01941  * nssGeneralName_GetOtherName
01942  * nssGeneralName_GetRfc822Name
01943  * nssGeneralName_GetDNSName
01944  * nssGeneralName_GetX400Address
01945  * nssGeneralName_GetDirectoryName
01946  * nssGeneralName_GetEdiPartyName
01947  * nssGeneralName_GetUniformResourceIdentifier
01948  * nssGeneralName_GetIPAddress
01949  * nssGeneralName_GetRegisteredID
01950  * nssGeneralName_GetSpecifiedChoice
01951  * nssGeneralName_Compare
01952  * nssGeneralName_Duplicate
01953  *
01954  * nssGeneralName_GetUID
01955  * nssGeneralName_GetEmail
01956  * nssGeneralName_GetCommonName
01957  * nssGeneralName_GetOrganization
01958  * nssGeneralName_GetOrganizationalUnits
01959  * nssGeneralName_GetStateOrProvince
01960  * nssGeneralName_GetLocality
01961  * nssGeneralName_GetCountry
01962  * nssGeneralName_GetAttribute
01963  */
01964 
01965 /*
01966  * nssGeneralName_CreateFromBER
01967  *
01968  * This routine creates an NSSGeneralName by decoding a BER- or DER-
01969  * encoded general name.  If the optional arena argument is non-null,
01970  * the memory used will be obtained from that arena; otherwise, the 
01971  * memory will be obtained from the heap.  This routine may return 
01972  * NULL upon error, in which case it will have set an error on the 
01973  * error stack.
01974  *
01975  * The error may be one of the following values:
01976  *  NSS_ERROR_INVALID_BER
01977  *  NSS_ERROR_NO_MEMORY
01978  *
01979  * Return value:
01980  *  NULL upon error
01981  *  A pointer to an NSSGeneralName upon success
01982  */
01983 
01984 NSS_EXTERN NSSGeneralName *
01985 nssGeneralName_CreateFromBER
01986 (
01987   NSSArena *arenaOpt,
01988   NSSBER *berGeneralName
01989 );
01990 
01991 /*
01992  * nssGeneralName_CreateFromUTF8
01993  *
01994  * This routine creates an NSSGeneralName by decoding a UTF8 string
01995  * consisting of the string representation of one of the choices of
01996  * general names.  If the optional arena argument is non-null, the 
01997  * memory used will be obtained from that arena; otherwise, the memory
01998  * will be obtained from the heap.  The routine may return NULL upon
01999  * error, in which case it will have set an error on the error stack.
02000  *
02001  * The error may be one of the following values:
02002  *  NSS_ERROR_INVALID_UTF8
02003  *  NSS_ERROR_NO_MEMORY
02004  *
02005  * Return value:
02006  *  NULL upon error
02007  *  A pointer to an NSSGeneralName upon success
02008  */
02009 
02010 NSS_EXTERN NSSGeneralName *
02011 nssGeneralName_CreateFromUTF8
02012 (
02013   NSSArena *arenaOpt,
02014   NSSUTF8 *stringGeneralName
02015 );
02016 
02017 /*
02018  * nssGeneralName_Create
02019  *
02020  * This routine creates an NSSGeneralName with the specified choice of
02021  * underlying name types.  The value of the choice variable must be one
02022  * of the values of the NSSGeneralNameChoice enumeration, and the type
02023  * of the arg variable must be as specified in the following table:
02024  *
02025  *   Choice                                         Type
02026  *   ============================================   =========
02027  *   NSSGeneralNameChoiceOtherName
02028  *   NSSGeneralNameChoiceRfc822Name
02029  *   NSSGeneralNameChoiceDNSName
02030  *   NSSGeneralNameChoiceX400Address
02031  *   NSSGeneralNameChoiceDirectoryName              NSSName *
02032  *   NSSGeneralNameChoiceEdiPartyName
02033  *   NSSGeneralNameChoiceUniformResourceIdentifier
02034  *   NSSGeneralNameChoiceIPAddress
02035  *   NSSGeneralNameChoiceRegisteredID
02036  *
02037  * If the optional arena argument is non-null, the memory used will
02038  * be obtained from that arena; otherwise, the memory will be 
02039  * obtained from the heap.  This routine may return NULL upon error,
02040  * in which case it will have set an error on the error stack.
02041  *
02042  * The error may be one fo the following values:
02043  *  NSS_ERROR_INVALID_CHOICE
02044  *  NSS_ERROR_INVALID_ARGUMENT
02045  *  NSS_ERROR_NO_MEMORY
02046  *
02047  * Return value:
02048  *  NULL upon error
02049  *  A pointer to an NSSGeneralName upon success
02050  */
02051 
02052 NSS_EXTERN NSSGeneralName *
02053 nssGeneralName_Create
02054 (
02055   NSSGeneralNameChoice choice,
02056   void *arg
02057 );
02058 
02059 /*
02060  * nssGeneralName_Destroy
02061  * 
02062  * This routine will destroy a General Name object.  It should 
02063  * eventually be called on all General Names created without an arena.
02064  * While it is not necessary to call it on General Names created within
02065  * an arena, it is not an error to do so.  This routine returns a
02066  * PRStatus value; if successful, it will return PR_SUCCESS. If 
02067  * usuccessful, it will set an error on the error stack and return 
02068  * PR_FAILURE.
02069  *
02070  * The error may be one of the following values:
02071  *  NSS_ERROR_INVALID_GENERAL_NAME
02072  *
02073  * Return value:
02074  *  PR_FAILURE upon failure
02075  *  PR_SUCCESS upon success
02076  */
02077 
02078 NSS_EXTERN PRStatus
02079 nssGeneralName_Destroy
02080 (
02081   NSSGeneralName *generalName
02082 );
02083 
02084 /*
02085  * nssGeneralName_GetDEREncoding
02086  *
02087  * This routine will DER-encode a name object.  If the optional arena
02088  * argument is non-null, the memory used will be obtained from that
02089  * arena; otherwise, the memory will be obtained from the heap.  This
02090  * routine may return null upon error, in which case it will have set
02091  * an error on the error stack.
02092  *
02093  * The error may be one of the following values:
02094  *  NSS_ERROR_INVALID_GENERAL_NAME
02095  *  NSS_ERROR_NO_MEMORY
02096  *
02097  * Return value:
02098  *  NULL upon error
02099  *  The DER encoding of this NSSGeneralName
02100  */
02101 
02102 NSS_EXTERN NSSDER *
02103 nssGeneralName_GetDEREncoding
02104 (
02105   NSSGeneralName *generalName,
02106   NSSArena *arenaOpt
02107 );
02108 
02109 /*
02110  * nssGeneralName_GetUTF8Encoding
02111  *
02112  * This routine returns a UTF8 string containing a string 
02113  * representation of the General Name in the format specified by the
02114  * underlying name choice.  If the optional arena argument is 
02115  * non-null, the memory used will be obtained from that arena; 
02116  * otherwise, the memory will be obtained from the heap.  This routine
02117  * may return NULL upon error, in which case it will have set an error
02118  * on the error stack.
02119  *
02120  * The error may be one of the following values:
02121  *  NSS_ERROR_INVALID_GENERAL_NAME
02122  *  NSS_ERROR_NO_MEMORY
02123  *
02124  * Return value:
02125  *  NULL upon error
02126  *  A pointer to a UTF8 string
02127  */
02128 
02129 NSS_EXTERN NSSUTF8 *
02130 nssGeneralName_GetUTF8Encoding
02131 (
02132   NSSGeneralName *generalName,
02133   NSSArena *arenaOpt
02134 );
02135 
02136 /*
02137  * nssGeneralName_GetChoice
02138  *
02139  * This routine returns the type of choice underlying the specified 
02140  * general name.  The return value will be a member of the 
02141  * NSSGeneralNameChoice enumeration.  This routine may return 
02142  * NSSGeneralNameChoiceInvalid upon error, in which case it will have 
02143  * set an error on the error stack.
02144  *
02145  * The error may be one of the following values:
02146  *  NSS_ERROR_INVALID_GENERAL_NAME
02147  *
02148  * Return value:
02149  *  NSSGeneralNameChoiceInvalid upon error
02150  *  An other member of the NSSGeneralNameChoice enumeration 
02151  */
02152 
02153 NSS_EXTERN NSSGeneralNameChoice
02154 nssGeneralName_GetChoice
02155 (
02156   NSSGeneralName *generalName
02157 );
02158 
02159 /*
02160  * nssGeneralName_GetOtherName
02161  *
02162  * If the choice underlying the specified NSSGeneralName is that of an
02163  * Other Name, this routine will return a pointer to that Other name.
02164  * Otherwise, this routine will place an error on the error stack, and
02165  * return NULL.  If the optional arena argument is non-null, the memory
02166  * required will be obtained from that arena; otherwise, the memory 
02167  * will be obtained from the heap.  The caller owns the returned 
02168  * pointer.  This routine may return NULL upon error, in which case it
02169  * will have set an error on the error stack.
02170  *
02171  * The error may be one of the following values:
02172  *  NSS_ERROR_INVALID_GENERAL_NAME
02173  *  NSS_ERROR_WRONG_CHOICE
02174  *  NSS_ERROR_NO_MEMORY
02175  *
02176  * Return value:
02177  *  NULL upon error
02178  *  A caller-owned pointer to an NSSOtherName
02179  */
02180 
02181 NSS_EXTERN NSSOtherName *
02182 nssGeneralName_GetOtherName
02183 (
02184   NSSGeneralName *generalName,
02185   NSSArena *arenaOpt
02186 );
02187 
02188 /*
02189  * nssGeneralName_GetRfc822Name
02190  *
02191  * If the choice underlying the specified NSSGeneralName is that of an
02192  * RFC 822 Name, this routine will return a pointer to that name.
02193  * Otherwise, this routine will place an error on the error stack, and
02194  * return NULL.  If the optional arena argument is non-null, the memory
02195  * required will be obtained from that arena; otherwise, the memory 
02196  * will be obtained from the heap.  The caller owns the returned 
02197  * pointer.  This routine may return NULL upon error, in which case it
02198  * will have set an error on the error stack.
02199  *
02200  * The error may be one of the following values:
02201  *  NSS_ERROR_INVALID_GENERAL_NAME
02202  *  NSS_ERROR_WRONG_CHOICE
02203  *  NSS_ERROR_NO_MEMORY
02204  *
02205  * Return value:
02206  *  NULL upon error
02207  *  A caller-owned pointer to an NSSRFC822Name
02208  */
02209 
02210 NSS_EXTERN NSSRFC822Name *
02211 nssGeneralName_GetRfc822Name
02212 (
02213   NSSGeneralName *generalName,
02214   NSSArena *arenaOpt
02215 );
02216 
02217 /*
02218  * nssGeneralName_GetDNSName
02219  *
02220  * If the choice underlying the specified NSSGeneralName is that of a 
02221  * DNS Name, this routine will return a pointer to that DNS name.
02222  * Otherwise, this routine will place an error on the error stack, and
02223  * return NULL.  If the optional arena argument is non-null, the memory
02224  * required will be obtained from that arena; otherwise, the memory 
02225  * will be obtained from the heap.  The caller owns the returned 
02226  * pointer.  This routine may return NULL upon error, in which case it
02227  * will have set an error on the error stack.
02228  *
02229  * The error may be one of the following values:
02230  *  NSS_ERROR_INVALID_GENERAL_NAME
02231  *  NSS_ERROR_WRONG_CHOICE
02232  *  NSS_ERROR_NO_MEMORY
02233  *
02234  * Return value:
02235  *  NULL upon error
02236  *  A caller-owned pointer to an NSSDNSName
02237  */
02238 
02239 NSS_EXTERN NSSDNSName *
02240 nssGeneralName_GetDNSName
02241 (
02242   NSSGeneralName *generalName,
02243   NSSArena *arenaOpt
02244 );
02245 
02246 /*
02247  * nssGeneralName_GetX400Address
02248  *
02249  * If the choice underlying the specified NSSGeneralName is that of an
02250  * X.400 Address, this routine will return a pointer to that Address.
02251  * Otherwise, this routine will place an error on the error stack, and
02252  * return NULL.  If the optional arena argument is non-null, the memory
02253  * required will be obtained from that arena; otherwise, the memory 
02254  * will be obtained from the heap.  The caller owns the returned 
02255  * pointer.  This routine may return NULL upon error, in which case it
02256  * will have set an error on the error stack.
02257  *
02258  * The error may be one of the following values:
02259  *  NSS_ERROR_INVALID_GENERAL_NAME
02260  *  NSS_ERROR_WRONG_CHOICE
02261  *  NSS_ERROR_NO_MEMORY
02262  *
02263  * Return value:
02264  *  NULL upon error
02265  *  A caller-owned pointer to an NSSX400Address
02266  */
02267 
02268 NSS_EXTERN NSSX400Address *
02269 nssGeneralName_GetX400Address
02270 (
02271   NSSGeneralName *generalName,
02272   NSSArena *arenaOpt
02273 );
02274 
02275 /*
02276  * nssGeneralName_GetDirectoryName
02277  *
02278  * If the choice underlying the specified NSSGeneralName is that of a
02279  * (directory) Name, this routine will return a pointer to that name.
02280  * Otherwise, this routine will place an error on the error stack, and
02281  * return NULL.  If the optional arena argument is non-null, the memory
02282  * required will be obtained from that arena; otherwise, the memory 
02283  * will be obtained from the heap.  The caller owns the returned 
02284  * pointer.  This routine may return NULL upon error, in which case it
02285  * will have set an error on the error stack.
02286  *
02287  * The error may be one of the following values:
02288  *  NSS_ERROR_INVALID_GENERAL_NAME
02289  *  NSS_ERROR_WRONG_CHOICE
02290  *  NSS_ERROR_NO_MEMORY
02291  *
02292  * Return value:
02293  *  NULL upon error
02294  *  A caller-owned pointer to an NSSName
02295  */
02296 
02297 NSS_EXTERN NSSName *
02298 nssGeneralName_GetName
02299 (
02300   NSSGeneralName *generalName,
02301   NSSArena *arenaOpt
02302 );
02303 
02304 /*
02305  * nssGeneralName_GetEdiPartyName
02306  *
02307  * If the choice underlying the specified NSSGeneralName is that of an
02308  * EDI Party Name, this routine will return a pointer to that name.
02309  * Otherwise, this routine will place an error on the error stack, and
02310  * return NULL.  If the optional arena argument is non-null, the memory
02311  * required will be obtained from that arena; otherwise, the memory 
02312  * will be obtained from the heap.  The caller owns the returned 
02313  * pointer.  This routine may return NULL upon error, in which case it
02314  * will have set an error on the error stack.
02315  *
02316  * The error may be one of the following values:
02317  *  NSS_ERROR_INVALID_GENERAL_NAME
02318  *  NSS_ERROR_WRONG_CHOICE
02319  *  NSS_ERROR_NO_MEMORY
02320  *
02321  * Return value:
02322  *  NULL upon error
02323  *  A caller-owned pointer to an NSSEdiPartyName
02324  */
02325 
02326 NSS_EXTERN NSSEdiPartyName *
02327 nssGeneralName_GetEdiPartyName
02328 (
02329   NSSGeneralName *generalName,
02330   NSSArena *arenaOpt
02331 );
02332 
02333 /*
02334  * nssGeneralName_GetUniformResourceIdentifier
02335  *
02336  * If the choice underlying the specified NSSGeneralName is that of a
02337  * URI, this routine will return a pointer to that URI.
02338  * Otherwise, this routine will place an error on the error stack, and
02339  * return NULL.  If the optional arena argument is non-null, the memory
02340  * required will be obtained from that arena; otherwise, the memory 
02341  * will be obtained from the heap.  The caller owns the returned 
02342  * pointer.  This routine may return NULL upon error, in which case it
02343  * will have set an error on the error stack.
02344  *
02345  * The error may be one of the following values:
02346  *  NSS_ERROR_INVALID_GENERAL_NAME
02347  *  NSS_ERROR_WRONG_CHOICE
02348  *  NSS_ERROR_NO_MEMORY
02349  *
02350  * Return value:
02351  *  NULL upon error
02352  *  A caller-owned pointer to an NSSURI
02353  */
02354 
02355 NSS_EXTERN NSSURI *
02356 nssGeneralName_GetUniformResourceIdentifier
02357 (
02358   NSSGeneralName *generalName,
02359   NSSArena *arenaOpt
02360 );
02361 
02362 /*
02363  * nssGeneralName_GetIPAddress
02364  *
02365  * If the choice underlying the specified NSSGeneralName is that of an
02366  * IP Address , this routine will return a pointer to that address.
02367  * Otherwise, this routine will place an error on the error stack, and
02368  * return NULL.  If the optional arena argument is non-null, the memory
02369  * required will be obtained from that arena; otherwise, the memory 
02370  * will be obtained from the heap.  The caller owns the returned 
02371  * pointer.  This routine may return NULL upon error, in which case it
02372  * will have set an error on the error stack.
02373  *
02374  * The error may be one of the following values:
02375  *  NSS_ERROR_INVALID_GENERAL_NAME
02376  *  NSS_ERROR_WRONG_CHOICE
02377  *  NSS_ERROR_NO_MEMORY
02378  *
02379  * Return value:
02380  *  NULL upon error
02381  *  A caller-owned pointer to an NSSIPAddress
02382  */
02383 
02384 NSS_EXTERN NSSIPAddress *
02385 nssGeneralName_GetIPAddress
02386 (
02387   NSSGeneralName *generalName,
02388   NSSArena *arenaOpt
02389 );
02390 
02391 /*
02392  * nssGeneralName_GetRegisteredID
02393  *
02394  * If the choice underlying the specified NSSGeneralName is that of a
02395  * Registered ID, this routine will return a pointer to that ID.
02396  * Otherwise, this routine will place an error on the error stack, and
02397  * return NULL.  If the optional arena argument is non-null, the memory
02398  * required will be obtained from that arena; otherwise, the memory 
02399  * will be obtained from the heap.  The caller owns the returned 
02400  * pointer.  This routine may return NULL upon error, in which case it
02401  * will have set an error on the error stack.
02402  *
02403  * The error may be one of the following values:
02404  *  NSS_ERROR_INVALID_GENERAL_NAME
02405  *  NSS_ERROR_WRONG_CHOICE
02406  *  NSS_ERROR_NO_MEMORY
02407  *
02408  * Return value:
02409  *  NULL upon error
02410  *  A caller-owned pointer to an NSSRegisteredID
02411  */
02412 
02413 NSS_EXTERN NSSRegisteredID *
02414 nssGeneralName_GetRegisteredID
02415 (
02416   NSSGeneralName *generalName,
02417   NSSArena *arenaOpt
02418 );
02419 
02420 /*
02421  * nssGeneralName_GetSpecifiedChoice
02422  *
02423  * If the choice underlying the specified NSSGeneralName matches the
02424  * specified choice, a caller-owned pointer to that underlying object
02425  * will be returned.  Otherwise, an error will be placed on the error
02426  * stack and NULL will be returned.  If the optional arena argument
02427  * is non-null, the memory required will be obtained from that arena;
02428  * otherwise, the memory will be obtained from the heap.  The caller
02429  * owns the returned pointer.  This routine may return NULL upon 
02430  * error, in which caes it will have set an error on the error stack.
02431  *
02432  * The error may be one of the following values:
02433  *  NSS_ERROR_INVALID_GENERAL_NAME
02434  *  NSS_ERROR_WRONG_CHOICE
02435  *  NSS_ERROR_NO_MEMORY
02436  *
02437  * Return value:
02438  *  NULL upon error
02439  *  A caller-owned pointer, which must be typecast
02440  */
02441 
02442 NSS_EXTERN void *
02443 nssGeneralName_GetSpecifiedChoice
02444 (
02445   NSSGeneralName *generalName,
02446   NSSGeneralNameChoice choice,
02447   NSSArena *arenaOpt
02448 );
02449 
02450 /*
02451  * nssGeneralName_Compare
02452  * 
02453  * This routine compares two General Names for equality.  For two 
02454  * General Names to be equal, they must have the same choice of
02455  * underlying types, and the underlying values must be equal.  The
02456  * result of the comparison will be stored at the location pointed
02457  * to by the "equalp" variable, which must point to a valid PRBool.
02458  * This routine may return PR_FAILURE upon error, in which case it
02459  * will have set an error on the error stack.
02460  *
02461  * The error may be one of the following value:
02462  *  NSS_ERROR_INVALID_GENERAL_NAME
02463  *  NSS_ERROR_INVALID_ARGUMENT
02464  *
02465  * Return value:
02466  *  PR_FAILURE upon error
02467  *  PR_SUCCESS upon a successful comparison (equal or not)
02468  */
02469 
02470 NSS_EXTERN PRStatus
02471 nssGeneralName_Compare
02472 (
02473   NSSGeneralName *generalName1,
02474   NSSGeneralName *generalName2,
02475   PRBool *equalp
02476 );
02477 
02478 /*
02479  * nssGeneralName_Duplicate
02480  *
02481  * This routine duplicates the specified General Name.  If the optional
02482  * arena argument is non-null, the memory required will be obtained
02483  * from that arena; otherwise, the memory will be obtained from the
02484  * heap.  This routine may return NULL upon error, in which case it 
02485  * will have set an error on the error stack.
02486  *
02487  * The error may be one of the following values:
02488  *  NSS_ERROR_INVALID_GENERAL_NAME
02489  *  NSS_ERROR_NO_MEMORY
02490  *
02491  * Return value:
02492  *  NULL upon error
02493  *  A pointer to a new NSSGeneralName
02494  */
02495 
02496 NSS_EXTERN NSSGeneralName *
02497 nssGeneralName_Duplicate
02498 (
02499   NSSGeneralName *generalName,
02500   NSSArena *arenaOpt
02501 );
02502 
02503 /*
02504  * nssGeneralName_GetUID
02505  *
02506  * This routine will attempt to derive a user identifier from the
02507  * specified general name, if the choices and content of the name
02508  * permit.  If the General Name is a (directory) Name consisting
02509  * of a Sequence of Relative Distinguished Names containing a UID
02510  * attribute, the UID will be the value of that attribute.  Note
02511  * that no UID attribute is defined in either PKIX or PKCS#9; 
02512  * rather, this seems to derive from RFC 1274, which defines the
02513  * type as a caseIgnoreString.  We'll return a Directory String.
02514  * If the optional arena argument is non-null, the memory used
02515  * will be obtained from that arena; otherwise, the memory will be
02516  * obtained from the heap.  This routine may return NULL upon error,
02517  * in which case it will have set an error on the error stack.
02518  *
02519  * The error may be one of the following values:
02520  *  NSS_ERROR_INVALID_GENERAL_NAME
02521  *  NSS_ERROR_NO_UID
02522  *  NSS_ERROR_NO_MEMORY
02523  *
02524  * Return value:
02525  *  NULL upon error
02526  *  A pointer to a UTF8 String.
02527  */
02528 
02529 NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
02530 nssGeneralName_GetUID
02531 (
02532   NSSGeneralName *generalName,
02533   NSSArena *arenaOpt
02534 );
02535 
02536 /*
02537  * nssGeneralName_GetEmail
02538  *
02539  * This routine will attempt to derive an email address from the
02540  * specified general name, if the choices and content of the name
02541  * permit.  If the General Name is a (directory) Name consisting
02542  * of a Sequence of Relative Distinguished names containing either
02543  * a PKIX email address or a PKCS#9 email address, the result will
02544  * be the value of that attribute.  If the General Name is an RFC 822
02545  * Name, the result will be the string form of that name.  If the
02546  * optional arena argument is non-null, the memory used will be 
02547  * obtained from that arena; otherwise, the memory will be obtained
02548  * from the heap.  This routine may return NULL upon error, in which
02549  * case it will have set an error on the error stack.
02550  *
02551  * The error may be one of the following values:
02552  *  NSS_ERROR_INVALID_GENERAL_NAME
02553  *  NSS_ERROR_NO_EMAIL
02554  *  NSS_ERROR_NO_MEMORY
02555  *
02556  * Return value:
02557  *  NULL upon error
02558  *  A pointer to a UTF8 String
02559  */
02560 
02561 NSS_EXTERN NSSUTF8 * /* XXX fgmr IA5String */
02562 nssGeneralName_GetEmail
02563 (
02564   NSSGeneralName *generalName,
02565   NSSArena *arenaOpt
02566 );
02567 
02568 /*
02569  * nssGeneralName_GetCommonName
02570  *
02571  * This routine will attempt to derive a common name from the
02572  * specified general name, if the choices and content of the name
02573  * permit.  If the General Name is a (directory) Name consisting
02574  * of a Sequence of Relative Distinguished names containing a PKIX
02575  * Common Name, the result will be that name.  If the optional arena 
02576  * argument is non-null, the memory used will be obtained from that 
02577  * arena; otherwise, the memory will be obtained from the heap.  This 
02578  * routine may return NULL upon error, in which case it will have set 
02579  * an error on the error stack.
02580  *
02581  * The error may be one of the following values:
02582  *  NSS_ERROR_INVALID_GENERAL_NAME
02583  *  NSS_ERROR_NO_COMMON_NAME
02584  *  NSS_ERROR_NO_MEMORY
02585  *
02586  * Return value:
02587  *  NULL upon error
02588  *  A pointer to a UTF8 String
02589  */
02590 
02591 NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
02592 nssGeneralName_GetCommonName
02593 (
02594   NSSGeneralName *generalName,
02595   NSSArena *arenaOpt
02596 );
02597 
02598 /*
02599  * nssGeneralName_GetOrganization
02600  *
02601  * This routine will attempt to derive an organisation name from the
02602  * specified general name, if the choices and content of the name
02603  * permit.  If the General Name is a (directory) Name consisting
02604  * of a Sequence of Relative Distinguished names containing an
02605  * Organization, the result will be the value of that attribute.  
02606  * If the optional arena argument is non-null, the memory used will 
02607  * be obtained from that arena; otherwise, the memory will be obtained
02608  * from the heap.  This routine may return NULL upon error, in which 
02609  * case it will have set an error on the error stack.
02610  *
02611  * The error may be one of the following values:
02612  *  NSS_ERROR_INVALID_GENERAL_NAME
02613  *  NSS_ERROR_NO_ORGANIZATION
02614  *  NSS_ERROR_NO_MEMORY
02615  *
02616  * Return value:
02617  *  NULL upon error
02618  *  A pointer to a UTF8 String
02619  */
02620 
02621 NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
02622 nssGeneralName_GetOrganization
02623 (
02624   NSSGeneralName *generalName,
02625   NSSArena *arenaOpt
02626 );
02627 
02628 /*
02629  * nssGeneralName_GetOrganizationalUnits
02630  *
02631  * This routine will attempt to derive a sequence of organisational 
02632  * unit names from the specified general name, if the choices and 
02633  * content of the name permit.  If the General Name is a (directory) 
02634  * Name consisting of a Sequence of Relative Distinguished names 
02635  * containing one or more organisational units, the result will 
02636  * consist of those units.  If the optional arena  argument is non-
02637  * null, the memory used will be obtained from that arena; otherwise, 
02638  * the memory will be obtained from the heap.  This routine may return 
02639  * NULL upon error, in which case it will have set an error on the 
02640  * error stack.
02641  *
02642  * The error may be one of the following values:
02643  *  NSS_ERROR_INVALID_GENERAL_NAME
02644  *  NSS_ERROR_NO_ORGANIZATIONAL_UNITS
02645  *  NSS_ERROR_NO_MEMORY
02646  *
02647  * Return value:
02648  *  NULL upon error
02649  *  A pointer to a null-terminated array of UTF8 Strings
02650  */
02651 
02652 NSS_EXTERN NSSUTF8 ** /* XXX fgmr DirectoryString */
02653 nssGeneralName_GetOrganizationalUnits
02654 (
02655   NSSGeneralName *generalName,
02656   NSSArena *arenaOpt
02657 );
02658 
02659 /*
02660  * nssGeneralName_GetStateOrProvince
02661  *
02662  * This routine will attempt to derive a state or province name from 
02663  * the specified general name, if the choices and content of the name
02664  * permit.  If the General Name is a (directory) Name consisting
02665  * of a Sequence of Relative Distinguished names containing a state or 
02666  * province, the result will be the value of that attribute.  If the 
02667  * optional arena argument is non-null, the memory used will be 
02668  * obtained from that arena; otherwise, the memory will be obtained 
02669  * from the heap.  This routine may return NULL upon error, in which 
02670  * case it will have set an error on the error stack.
02671  *
02672  * The error may be one of the following values:
02673  *  NSS_ERROR_INVALID_GENERAL_NAME
02674  *  NSS_ERROR_NO_STATE_OR_PROVINCE
02675  *  NSS_ERROR_NO_MEMORY
02676  *
02677  * Return value:
02678  *  NULL upon error
02679  *  A pointer to a UTF8 String
02680  */
02681 
02682 NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
02683 nssGeneralName_GetStateOrProvince
02684 (
02685   NSSGeneralName *generalName,
02686   NSSArena *arenaOpt
02687 );
02688 
02689 /*
02690  * nssGeneralName_GetLocality
02691  *
02692  * This routine will attempt to derive a locality name from 
02693  * the specified general name, if the choices and content of the name
02694  * permit.  If the General Name is a (directory) Name consisting
02695  * of a Sequence of Relative Distinguished names containing a Locality, 
02696  * the result will be the value of that attribute.  If the optional 
02697  * arena argument is non-null, the memory used will be obtained from 
02698  * that arena; otherwise, the memory will be obtained from the heap.  
02699  * This routine may return NULL upon error, in which case it will have 
02700  * set an error on the error stack.
02701  *
02702  * The error may be one of the following values:
02703  *  NSS_ERROR_INVALID_GENERAL_NAME
02704  *  NSS_ERROR_NO_LOCALITY
02705  *  NSS_ERROR_NO_MEMORY
02706  *
02707  * Return value:
02708  *  NULL upon error
02709  *  A pointer to a UTF8 String
02710  */
02711 
02712 NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
02713 nssGeneralName_GetLocality
02714 (
02715   NSSGeneralName *generalName,
02716   NSSArena *arenaOpt
02717 );
02718 
02719 /*
02720  * nssGeneralName_GetCountry
02721  *
02722  * This routine will attempt to derive a country name from the 
02723  * specified general name, if the choices and content of the name 
02724  * permit.  If the General Name is a (directory) Name consisting of a
02725  * Sequence of Relative Distinguished names containing a Country, the 
02726  * result will be the value of that attribute.  If the optional 
02727  * arena argument is non-null, the memory used will be obtained from 
02728  * that arena; otherwise, the memory will be obtained from the heap.  
02729  * This routine may return NULL upon error, in which case it will have 
02730  * set an error on the error stack.
02731  *
02732  * The error may be one of the following values:
02733  *  NSS_ERROR_INVALID_GENERAL_NAME
02734  *  NSS_ERROR_NO_COUNTRY
02735  *  NSS_ERROR_NO_MEMORY
02736  *
02737  * Return value:
02738  *  NULL upon error
02739  *  A pointer to a UTF8 String
02740  */
02741 
02742 NSS_EXTERN NSSUTF8 * /* XXX fgmr PrintableString */
02743 nssGeneralName_GetCountry
02744 (
02745   NSSGeneralName *generalName,
02746   NSSArena *arenaOpt
02747 );
02748 
02749 /*
02750  * nssGeneralName_GetAttribute
02751  *
02752  * If the specified general name is a (directory) name consisting
02753  * of a Sequence of Relative Distinguished Names containing an 
02754  * attribute with the specified type, and the actual value of that
02755  * attribute may be expressed with a Directory String, then the
02756  * value of that attribute will be returned as a Directory String.
02757  * If the optional arena argument is non-null, the memory used will
02758  * be obtained from that arena; otherwise, the memory will be obtained
02759  * from the heap.  This routine may return NULL upon error, in which
02760  * case it will have set an error on the error stack.
02761  *
02762  * The error may be one of the following values:
02763  *  NSS_ERROR_INVALID_GENERAL_NAME
02764  *  NSS_ERROR_NO_ATTRIBUTE
02765  *  NSS_ERROR_ATTRIBUTE_VALUE_NOT_STRING
02766  *
02767  * Return value:
02768  *  NULL upon error
02769  *  A pointer to a UTF8 String
02770  */
02771 
02772 NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
02773 nssGeneralName_GetAttribute
02774 (
02775   NSSGeneralName *generalName,
02776   NSSOID *attribute,
02777   NSSArena *arenaOpt
02778 );
02779 
02780 /*
02781  * NSSGeneralNameSeq
02782  *
02783  * The public "methods" regarding this "object" are:
02784  *
02785  *  nssGeneralNameSeq_CreateFromBER   -- constructor
02786  *  nssGeneralNameSeq_Create          -- constructor
02787  *
02788  *  nssGeneralNameSeq_Destroy
02789  *  nssGeneralNameSeq_GetDEREncoding
02790  *  nssGeneralNameSeq_AppendGeneralName
02791  *  nssGeneralNameSeq_GetGeneralNameCount
02792  *  nssGeneralNameSeq_GetGeneralName
02793  *  nssGeneralNameSeq_Compare
02794  *  nssGeneralnameSeq_Duplicate
02795  */
02796 
02797 /*
02798  * nssGeneralNameSeq_CreateFromBER
02799  *
02800  * This routine creates a general name sequence by decoding a BER-
02801  * or DER-encoded GeneralNames.  If the optional arena argument is
02802  * non-null, the memory used will be obtained from that arena; 
02803  * otherwise, the memory will be obtained from the heap.  This routine
02804  * may return NULL upon error, in which case it will have set an error
02805  * on the error stack.
02806  *
02807  * The error may be one of the following values:
02808  *  NSS_ERROR_INVALID_BER
02809  *  NSS_ERROR_NO_MEMORY
02810  *
02811  * Return value:
02812  *  NULL upon error
02813  *  A pointer to an NSSGeneralNameSeq upon success
02814  */
02815 
02816 NSS_EXTERN NSSGeneralNameSeq *
02817 nssGeneralNameSeq_CreateFromBER
02818 (
02819   NSSArena *arenaOpt,
02820   NSSBER *berGeneralNameSeq
02821 );
02822 
02823 /*
02824  * nssGeneralNameSeq_Create
02825  *
02826  * This routine creates an NSSGeneralNameSeq from one or more General
02827  * Names.  The final argument to this routine must be NULL.  If the
02828  * optional arena argument is non-null, the memory used will be 
02829  * obtained from that arena; otherwise, the memory will be obtained 
02830  * from the heap.  This routine may return NULL upon error, in which
02831  * case it will have set an error on the error stack.
02832  *
02833  * The error may be one of the following values:
02834  *  NSS_ERROR_NO_MEMORY
02835  *  NSS_ERROR_INVALID_GENERAL_NAME
02836  *
02837  * Return value:
02838  *  NULL upon error
02839  *  A pointer to an NSSGeneralNameSeq upon success
02840  */
02841 
02842 NSS_EXTERN NSSGeneralNameSeq *
02843 nssGeneralNameSeq_Create
02844 (
02845   NSSArena *arenaOpt,
02846   NSSGeneralName *generalName1,
02847   ...
02848 );
02849 
02850 /*
02851  * nssGeneralNameSeq_Destroy
02852  *
02853  * This routine will destroy an NSSGeneralNameSeq object.  It should
02854  * eventually be called on all NSSGeneralNameSeqs created without an
02855  * arena.  While it is not necessary to call it on NSSGeneralNameSeq's
02856  * created within an arena, it is not an error to do so.  This routine
02857  * returns a PRStatus value; if successful, it will return PR_SUCCESS.
02858  * If unsuccessful, it will set an error on the error stack and return
02859  * PR_FAILURE.
02860  *
02861  * The error may be one of the following values:
02862  *  NSS_ERROR_INVALID_GENERAL_NAME_SEQ
02863  *
02864  * Return value:
02865  *  PR_FAILURE upon error
02866  *  PR_SUCCESS upon success
02867  */
02868 
02869 NSS_EXTERN PRStatus
02870 nssGeneralNameSeq_Destroy
02871 (
02872   NSSGeneralNameSeq *generalNameSeq
02873 );
02874 
02875 /*
02876  * nssGeneralNameSeq_GetDEREncoding
02877  *
02878  * This routine will DER-encode an NSSGeneralNameSeq object.  If the
02879  * optional arena argument is non-null, the memory used will be 
02880  * obtained from that arena; otherwise, the memory will be obtained
02881  * from the heap.  This routine may return null upon error, in which
02882  * case it will have set an error on the error stack.
02883  *
02884  * The error may be one of the following values:
02885  *  NSS_ERROR_INVALID_GENERAL_NAME_SEQ
02886  *  NSS_ERROR_NO_MEMORY
02887  *
02888  * Return value:
02889  *  NULL upon error
02890  *  The DER encoding of this NSSGeneralNameSeq
02891  */
02892 
02893 NSS_EXTERN NSSDER *
02894 nssGeneralNameSeq_GetDEREncoding
02895 (
02896   NSSGeneralNameSeq *generalNameSeq,
02897   NSSArena *arenaOpt
02898 );
02899 
02900 /*
02901  * nssGeneralNameSeq_AppendGeneralName
02902  *
02903  * This routine appends a General Name to the end of the existing
02904  * General Name Sequence.  If the sequence was created with a non-null
02905  * arena argument, that same arena will be used for any additional
02906  * required memory.  If the sequence was created with a NULL arena
02907  * argument, any additional memory will be obtained from the heap.
02908  * This routine returns a PRStatus value; it will return PR_SUCCESS
02909  * upon success, and upon failure it will set an error on the error
02910  * stack and return PR_FAILURE.
02911  *
02912  * The error may be one of the following values:
02913  *  NSS_ERROR_INVALID_GENERAL_NAME_SEQ
02914  *  NSS_ERROR_INVALID_GENERAL_NAME
02915  *  NSS_ERROR_NO_MEMORY
02916  * 
02917  * Return value:
02918  *  PR_SUCCESS upon success
02919  *  PR_FAILURE upon failure.
02920  */
02921 
02922 NSS_EXTERN PRStatus
02923 nssGeneralNameSeq_AppendGeneralName
02924 (
02925   NSSGeneralNameSeq *generalNameSeq,
02926   NSSGeneralName *generalName
02927 );
02928 
02929 /*
02930  * nssGeneralNameSeq_GetGeneralNameCount
02931  *
02932  * This routine returns the cardinality of the specified General name
02933  * Sequence.  This routine may return 0 upon error, in which case it
02934  * will have set an error on the error stack.
02935  *
02936  * The error may be one of the following values:
02937  *  NSS_ERROR_INVALID_GENERAL_NAME_SEQ
02938  *
02939  * Return value;
02940  *  0 upon error
02941  *  A positive number upon success
02942  */
02943 
02944 NSS_EXTERN PRUint32
02945 nssGeneralNameSeq_GetGeneralNameCount
02946 (
02947   NSSGeneralNameSeq *generalNameSeq
02948 );
02949 
02950 /*
02951  * nssGeneralNameSeq_GetGeneralName
02952  *
02953  * This routine returns a pointer to the i'th General Name in the 
02954  * specified General Name Sequence.  The value of the variable 'i' is
02955  * on the range [0,c) where c is the cardinality returned from 
02956  * NSSGeneralNameSeq_GetGeneralNameCount.  The caller owns the General
02957  * Name the pointer to which is returned.  If the optional arena
02958  * argument is non-null, the memory used will be obtained from that
02959  * arena; otherwise, the memory will be obtained from the heap.  This
02960  * routine may return NULL upon error, in which case it will have set
02961  * an error upon the error stack.
02962  *
02963  * The error may be one of the following values:
02964  *  NSS_ERROR_INVALID_GENERAL_NAME_SEQ
02965  *  NSS_ERROR_VALUE_OUT_OF_RANGE
02966  *  NSS_ERROR_NO_MEMORY
02967  *
02968  * Return value:
02969  *  NULL upon error
02970  *  A caller-owned pointer to a General Name.
02971  */
02972 
02973 NSS_EXTERN NSSGeneralName *
02974 nssGeneralNameSeq_GetGeneralName
02975 (
02976   NSSGeneralNameSeq *generalNameSeq,
02977   NSSArena *arenaOpt,
02978   PRUint32 i
02979 );
02980 
02981 /*
02982  * nssGeneralNameSeq_Compare
02983  *
02984  * This routine compares two General Name Sequences for equality.  For
02985  * two General Name Sequences to be equal, they must have the same
02986  * cardinality, and each General Name in one sequence must be equal to
02987  * the corresponding General Name in the other.  The result of the
02988  * comparison will be stored at the location pointed to by the "equalp"
02989  * variable, which must point to a valid PRBool.  This routine may 
02990  * return PR_FAILURE upon error, in which case it will have set an 
02991  * error on the error stack.
02992  *
02993  * The error may be one of the following values:
02994  *  NSS_ERROR_INVALID_GENERAL_NAME_SEQ
02995  *  NSS_ERROR_INVALID_ARGUMENT
02996  *
02997  * Return value:
02998  *  PR_FAILURE upon error
02999  *  PR_SUCCESS upon a successful comparison (equal or not)
03000  */
03001 
03002 NSS_EXTERN PRStatus
03003 nssGeneralNameSeq_Compare
03004 (
03005   NSSGeneralNameSeq *generalNameSeq1,
03006   NSSGeneralNameSeq *generalNameSeq2,
03007   PRBool *equalp
03008 );
03009 
03010 /*
03011  * nssGeneralNameSeq_Duplicate
03012  *
03013  * This routine duplicates the specified sequence of general names.  If
03014  * the optional arena argument is non-null, the memory required will be
03015  * obtained from that arena; otherwise, the memory will be obtained 
03016  * from the heap.  This routine may return NULL upon error, in which 
03017  * case it will have placed an error on the error stack.
03018  *
03019  * The error may be one of the following values:
03020  *  NSS_ERROR_INVALID_GENERAL_NAME_SEQ
03021  *  NSS_ERROR_NO_MEMORY
03022  *
03023  * Return value:
03024  *  NULL upon error
03025  *  A pointer to a new General Name Sequence.
03026  */
03027 
03028 NSS_EXTERN NSSGeneralNameSeq *
03029 nssGeneralNameSeq_Duplicate
03030 (
03031   NSSGeneralNameSeq *generalNameSeq,
03032   NSSArena *arenaOpt
03033 );
03034 
03035 PR_END_EXTERN_C
03036 
03037 #endif /* PKI1_H */