security/nss/lib/pki1/pki1.h

   1 /* ***** BEGIN LICENSE BLOCK *****
   2  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   3  *
   4  * The contents of this file are subject to the Mozilla Public License Version
   5  * 1.1 (the "License"); you may not use this file except in compliance with
   6  * the License. You may obtain a copy of the License at
   7  * http://www.mozilla.org/MPL/
   8  *
   9  * Software distributed under the License is distributed on an "AS IS" basis,
  10  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  11  * for the specific language governing rights and limitations under the
  12  * License.
  13  *
  14  * The Original Code is the Netscape security libraries.
  15  *
  16  * The Initial Developer of the Original Code is
  17  * Netscape Communications Corporation.
  18  * Portions created by the Initial Developer are Copyright (C) 1994-2000
  19  * the Initial Developer. All Rights Reserved.
  20  *
  21  * Contributor(s):
  22  *
  23  * Alternatively, the contents of this file may be used under the terms of
  24  * either the GNU General Public License Version 2 or later (the "GPL"), or
  25  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  26  * in which case the provisions of the GPL or the LGPL are applicable instead
  27  * of those above. If you wish to allow use of your version of this file only
  28  * under the terms of either the GPL or the LGPL, and not to allow others to
  29  * use your version of this file under the terms of the MPL, indicate your
  30  * decision by deleting the provisions above and replace them with the notice
  31  * and other provisions required by the GPL or the LGPL. If you do not delete
  32  * the provisions above, a recipient may use your version of this file under
  33  * the terms of any one of the MPL, the GPL or the LGPL.
  34  *
  35  * ***** END LICENSE BLOCK ***** */
  36
  37 #ifndef PKI1_H
  38 #define PKI1_H
  39
  40 #ifdef DEBUG
  41 static const char PKI1_CVS_ID[] = "@(#) $RCSfile: pki1.h,v $ $Revision: 1.5 $ $Date: 2005/03/14 18:02:00 $";
  42 #endif /* DEBUG */
  43
  44 /*
  45  * pki1.h
  46  *
  47  * This file contains the prototypes to the non-public NSS routines
  48  * relating to the PKIX part-1 objects.
  49  */
  50
  51 #ifndef PKI1T_H
  52 #include "pki1t.h"
  53 #endif /* PKI1T_H */
  54
  55 #ifndef NSSPKI1_H
  56 #include "nsspki1.h"
  57 #endif /* NSSPKI1_H */
  58
  59 PR_BEGIN_EXTERN_C
  60
  61 extern const NSSOID nss_builtin_oids[];
  62 extern const PRUint32 nss_builtin_oid_count;
  63
  64 extern const nssAttributeTypeAliasTable nss_attribute_type_aliases[];
  65 extern const PRUint32 nss_attribute_type_alias_count;
  66
  67 /*
  68  * NSSOID
  69  *
  70  * The non-public "methods" regarding this "object" are:
  71  *
  72  *  nssOID_CreateFromBER   -- constructor
  73  *  nssOID_CreateFromUTF8  -- constructor
  74  *  (there is no explicit destructor)
  75  *
  76  *  nssOID_GetDEREncoding
  77  *  nssOID_GetUTF8Encoding
  78  *
  79  * In debug builds, the following non-public calls are also available:
  80  *
  81  *  nssOID_verifyPointer
  82  *  nssOID_getExplanation
  83  *  nssOID_getTaggedUTF8
  84  */
  85
  86 /*
  87  * nssOID_CreateFromBER
  88  *
  89  * This routine creates an NSSOID by decoding a BER- or DER-encoded
  90  * OID.  It may return NSS_OID_UNKNOWN upon error, in which case it
  91  * will have set an error on the error stack.
  92  *
  93  * The error may be one of the following values:
  94  *  NSS_ERROR_INVALID_BER
  95  *  NSS_ERROR_NO_MEMORY
  96  *
  97  * Return value:
  98  *  NSS_OID_UNKNOWN upon error
  99  *  An NSSOID upon success
 100  */
 101
 102 NSS_EXTERN NSSOID *
 103 nssOID_CreateFromBER
 104 (
 105   NSSBER *berOid
 106 );
 107
 108 extern const NSSError NSS_ERROR_INVALID_BER;
 109 extern const NSSError NSS_ERROR_NO_MEMORY;
 110
 111 /*
 112  * nssOID_CreateFromUTF8
 113  *
 114  * This routine creates an NSSOID by decoding a UTF8 string
 115  * representation of an OID in dotted-number format.  The string may
 116  * optionally begin with an octothorpe.  It may return NSS_OID_UNKNOWN
 117  * upon error, in which case it will have set an error on the error
 118  * stack.
 119  *
 120  * The error may be one of the following values:
 121  *  NSS_ERROR_INVALID_UTF8
 122  *  NSS_ERROR_NO_MEMORY
 123  *
 124  * Return value:
 125  *  NSS_OID_UNKNOWN upon error
 126  *  An NSSOID upon success
 127  */
 128
 129 NSS_EXTERN NSSOID *
 130 nssOID_CreateFromUTF8
 131 (
 132   NSSUTF8 *stringOid
 133 );
 134
 135 extern const NSSError NSS_ERROR_INVALID_UTF8;
 136 extern const NSSError NSS_ERROR_NO_MEMORY;
 137
 138 /*
 139  * nssOID_GetDEREncoding
 140  *
 141  * This routine returns the DER encoding of the specified NSSOID.
 142  * If the optional arena argument is non-null, the memory used will
 143  * be obtained from that arena; otherwise, the memory will be obtained
 144  * from the heap.  This routine may return return null upon error, in
 145  * which case it will have set an error on the error stack.
 146  *
 147  * The error may be one of the following values:
 148  *  NSS_ERROR_INVALID_NSSOID
 149  *  NSS_ERROR_NO_MEMORY
 150  *
 151  * Return value:
 152  *  NULL upon error
 153  *  The DER encoding of this NSSOID
 154  */
 155
 156 NSS_EXTERN NSSDER *
 157 nssOID_GetDEREncoding
 158 (
 159   const NSSOID *oid,
 160   NSSDER *rvOpt,
 161   NSSArena *arenaOpt
 162 );
 163
 164 /*
 165  * nssOID_GetUTF8Encoding
 166  *
 167  * This routine returns a UTF8 string containing the dotted-number
 168  * encoding of the specified NSSOID.  If the optional arena argument
 169  * is non-null, the memory used will be obtained from that arena;
 170  * otherwise, the memory will be obtained from the heap.  This routine
 171  * may return null upon error, in which case it will have set an error
 172  * on the error stack.
 173  *
 174  * The error may be one of the following values:
 175  *  NSS_ERROR_INVALID_NSSOID
 176  *  NSS_ERROR_NO_MEMORY
 177  *
 178  * Return value:
 179  *  NULL upon error
 180  *  A pointer to a UTF8 string containing the dotted-digit encoding of
 181  *      this NSSOID
 182  */
 183
 184 NSS_EXTERN NSSUTF8 *
 185 nssOID_GetUTF8Encoding
 186 (
 187   const NSSOID *oid,
 188   NSSArena *arenaOpt
 189 );
 190
 191 /*
 192  * nssOID_verifyPointer
 193  *
 194  * This method is only present in debug builds.
 195  *
 196  * If the specified pointer is a valid poitner to an NSSOID object,
 197  * this routine will return PR_SUCCESS.  Otherwise, it will put an
 198  * error on the error stack and return PR_FAILURE.
 199  *
 200  * The error may be one of the following values:
 201  *  NSS_ERROR_INVALID_NSSOID
 202  *
 203  * Return value:
 204  *  PR_SUCCESS if the pointer is valid
 205  *  PR_FAILURE if it isn't
 206  */
 207
 208 #ifdef DEBUG
 209 NSS_EXTERN PRStatus
 210 nssOID_verifyPointer
 211 (
 212   const NSSOID *oid
 213 );
 214
 215 extern const NSSError NSS_ERROR_INVALID_NSSOID;
 216 #endif /* DEBUG */
 217
 218 /*
 219  * nssOID_getExplanation
 220  *
 221  * This method is only present in debug builds.
 222  *
 223  * This routine will return a static pointer to a UTF8-encoded string
 224  * describing (in English) the specified OID.  The memory pointed to
 225  * by the return value is not owned by the caller, and should not be
 226  * freed or modified.  Note that explanations are only provided for
 227  * the OIDs built into the NSS library; there is no way to specify an
 228  * explanation for dynamically created OIDs.  This routine is intended
 229  * only for use in debugging tools such as "derdump."  This routine
 230  * may return null upon error, in which case it will have placed an
 231  * error on the error stack.
 232  *
 233  * The error may be one of the following values:
 234  *  NSS_ERROR_INVALID_NSSOID
 235  *
 236  * Return value:
 237  *  NULL upon error
 238  *  A static pointer to a readonly, non-caller-owned UTF8-encoded
 239  *    string explaining the specified OID.
 240  */
 241
 242 #ifdef DEBUG
 243 NSS_EXTERN const NSSUTF8 *
 244 nssOID_getExplanation
 245 (
 246   NSSOID *oid
 247 );
 248
 249 extern const NSSError NSS_ERROR_INVALID_NSSOID;
 250 #endif /* DEBUG */
 251
 252 /*
 253  * nssOID_getTaggedUTF8
 254  *
 255  * This method is only present in debug builds.
 256  *
 257  * This routine will return a pointer to a caller-owned UTF8-encoded
 258  * string containing a tagged encoding of the specified OID.  Note
 259  * that OID (component) tags are only provided for the OIDs built
 260  * into the NSS library; there is no way to specify tags for
 261  * dynamically created OIDs.  This routine is intended for use in
 262  * debugging tools such as "derdump."   If the optional arena argument
 263  * is non-null, the memory used will be obtained from that arena;
 264  * otherwise, the memory will be obtained from the heap.  This routine
 265  * may return return null upon error, in which case it will have set
 266  * an error on the error stack.
 267  *
 268  * The error may be one of the following values
 269  *  NSS_ERROR_INVALID_NSSOID
 270  *  NSS_ERROR_NO_MEMORY
 271  *
 272  * Return value:
 273  *  NULL upon error
 274  *  A pointer to a UTF8 string containing the tagged encoding of
 275  *      this NSSOID
 276  */
 277
 278 #ifdef DEBUG
 279 NSS_EXTERN NSSUTF8 *
 280 nssOID_getTaggedUTF8
 281 (
 282   NSSOID *oid,
 283   NSSArena *arenaOpt
 284 );
 285
 286 extern const NSSError NSS_ERROR_INVALID_NSSOID;
 287 extern const NSSError NSS_ERROR_NO_MEMORY;
 288 #endif /* DEBUG */
 289
 290 /*
 291  * NSSATAV
 292  *
 293  * The non-public "methods" regarding this "object" are:
 294  *
 295  *  nssATAV_CreateFromBER   -- constructor
 296  *  nssATAV_CreateFromUTF8  -- constructor
 297  *  nssATAV_Create          -- constructor
 298  *
 299  *  nssATAV_Destroy
 300  *  nssATAV_GetDEREncoding
 301  *  nssATAV_GetUTF8Encoding
 302  *  nssATAV_GetType
 303  *  nssATAV_GetValue
 304  *  nssATAV_Compare
 305  *  nssATAV_Duplicate
 306  *
 307  * In debug builds, the following non-public call is also available:
 308  *
 309  *  nssATAV_verifyPointer
 310  */
 311
 312 /*
 313  * nssATAV_CreateFromBER
 314  *
 315  * This routine creates an NSSATAV by decoding a BER- or DER-encoded
 316  * ATAV.  If the optional arena argument is non-null, the memory used
 317  * will be obtained from that arena; otherwise, the memory will be
 318  * obtained from the heap.  This routine may return NULL upon error,
 319  * in which case it will have set an error on the error stack.
 320  *
 321  * The error may be one of the following values:
 322  *  NSS_ERROR_INVALID_BER
 323  *  NSS_ERROR_NO_MEMORY
 324  *
 325  * Return value:
 326  *  NULL upon error
 327  *  A pointer to an NSSATAV upon success
 328  */
 329
 330 NSS_EXTERN NSSATAV *
 331 nssATAV_CreateFromBER
 332 (
 333   NSSArena *arenaOpt,
 334   const NSSBER *berATAV
 335 );
 336
 337 /*
 338  * nssATAV_CreateFromUTF8
 339  *
 340  * This routine creates an NSSATAV by decoding a UTF8 string in the
 341  * "equals" format, e.g., "c=US."  If the optional arena argument is
 342  * non-null, the memory used will be obtained from that arena;
 343  * otherwise, the memory will be obtained from the heap.  This routine
 344  * may return NULL upon error, in which case it will have set an error
 345  * on the error stack.
 346  *
 347  * The error may be one of the following values:
 348  *  NSS_ERROR_UNKNOWN_ATTRIBUTE
 349  *  NSS_ERROR_INVALID_UTF8
 350  *  NSS_ERROR_NO_MEMORY
 351  *
 352  * Return value:
 353  *  NULL upon error
 354  *  A pointer to an NSSATAV upon success
 355  */
 356
 357 NSS_EXTERN NSSATAV *
 358 nssATAV_CreateFromUTF8
 359 (
 360   NSSArena *arenaOpt,
 361   const NSSUTF8 *stringATAV
 362 );
 363
 364 /*
 365  * nssATAV_Create
 366  *
 367  * This routine creates an NSSATAV from the specified NSSOID and the
 368  * specified data. If the optional arena argument is non-null, the
 369  * memory used will be obtained from that arena; otherwise, the memory
 370  * will be obtained from the heap.If the specified data length is zero,
 371  * the data is assumed to be terminated by first zero byte; this allows
 372  * UTF8 strings to be easily specified.  This routine may return NULL
 373  * upon error, in which case it will have set an error on the error
 374  * stack.
 375  *
 376  * The error may be one of the following values:
 377  *  NSS_ERROR_INVALID_ARENA
 378  *  NSS_ERROR_INVALID_NSSOID
 379  *  NSS_ERROR_INVALID_POINTER
 380  *  NSS_ERROR_NO_MEMORY
 381  *
 382  * Return value:
 383  *  NULL upon error
 384  *  A pointer to an NSSATAV upon success
 385  */
 386
 387 NSS_EXTERN NSSATAV *
 388 nssATAV_Create
 389 (
 390   NSSArena *arenaOpt,
 391   const NSSOID *oid,
 392   const void *data,
 393   PRUint32 length
 394 );
 395
 396 /*
 397  * nssATAV_Destroy
 398  *
 399  * This routine will destroy an ATAV object.  It should eventually be
 400  * called on all ATAVs created without an arena.  While it is not
 401  * necessary to call it on ATAVs created within an arena, it is not an
 402  * error to do so.  This routine returns a PRStatus value; if
 403  * successful, it will return PR_SUCCESS.  If unsuccessful, it will
 404  * set an error on the error stack and return PR_FAILURE.
 405  *
 406  * The error may be one of the following values:
 407  *  NSS_ERROR_INVALID_ATAV
 408  *
 409  * Return value:
 410  *  PR_FAILURE upon error
 411  *  PR_SUCCESS upon success
 412  */
 413
 414 NSS_EXTERN PRStatus
 415 nssATAV_Destroy
 416 (
 417   NSSATAV *atav
 418 );
 419
 420 /*
 421  * nssATAV_GetDEREncoding
 422  *
 423  * This routine will DER-encode an ATAV object. If the optional arena
 424  * argument is non-null, the memory used will be obtained from that
 425  * arena; otherwise, the memory will be obtained from the heap.  This
 426  * routine may return null upon error, in which case it will have set
 427  * an error on the error stack.
 428  *
 429  * The error may be one of the following values:
 430  *  NSS_ERROR_INVALID_ATAV
 431  *  NSS_ERROR_NO_MEMORY
 432  *
 433  * Return value:
 434  *  NULL upon error
 435  *  The DER encoding of this NSSATAV
 436  */
 437
 438 NSS_EXTERN NSSDER *
 439 nssATAV_GetDEREncoding
 440 (
 441   NSSATAV *atav,
 442   NSSArena *arenaOpt
 443 );
 444
 445 /*
 446  * nssATAV_GetUTF8Encoding
 447  *
 448  * This routine returns a UTF8 string containing a string
 449  * representation of the ATAV in "equals" notation (e.g., "o=Acme").
 450  * If the optional arena argument is non-null, the memory used will be
 451  * obtained from that arena; otherwise, the memory will be obtained
 452  * from the heap.  This routine may return null upon error, in which
 453  * case it will have set an error on the error stack.
 454  *
 455  * The error may be one of the following values:
 456  *  NSS_ERROR_INVALID_ATAV
 457  *  NSS_ERROR_NO_MEMORY
 458  *
 459  * Return value:
 460  *  NULL upon error
 461  *  A pointer to a UTF8 string containing the "equals" encoding of the
 462  *      ATAV
 463  */
 464
 465 NSS_EXTERN NSSUTF8 *
 466 nssATAV_GetUTF8Encoding
 467 (
 468   NSSATAV *atav,
 469   NSSArena *arenaOpt
 470 );
 471
 472 /*
 473  * nssATAV_GetType
 474  *
 475  * This routine returns the NSSOID corresponding to the attribute type
 476  * in the specified ATAV.  This routine may return NSS_OID_UNKNOWN
 477  * upon error, in which case it will have set an error on the error
 478  * stack.
 479  *
 480  * The error may be one of the following values:
 481  *  NSS_ERROR_INVALID_ATAV
 482  *
 483  * Return value:
 484  *  NSS_OID_UNKNOWN upon error
 485  *  An element of enum NSSOIDenum upon success
 486  */
 487
 488 NSS_EXTERN const NSSOID *
 489 nssATAV_GetType
 490 (
 491   NSSATAV *atav
 492 );
 493
 494 /*
 495  * nssATAV_GetValue
 496  *
 497  * This routine returns a string containing the attribute value
 498  * in the specified ATAV.  If the optional arena argument is non-null,
 499  * the memory used will be obtained from that arena; otherwise, the
 500  * memory will be obtained from the heap.  This routine may return
 501  * NULL upon error, in which case it will have set an error upon the
 502  * error stack.
 503  *
 504  * The error may be one of the following values:
 505  *  NSS_ERROR_INVALID_ATAV
 506  *  NSS_ERROR_NO_MEMORY
 507  *
 508  * Return value:
 509  *  NULL upon error
 510  *  A pointer to an NSSItem containing the attribute value.
 511  */
 512
 513 NSS_EXTERN NSSUTF8 *
 514 nssATAV_GetValue
 515 (
 516   NSSATAV *atav,
 517   NSSArena *arenaOpt
 518 );
 519
 520 /*
 521  * nssATAV_Compare
 522  *
 523  * This routine compares two ATAVs for equality.  For two ATAVs to be
 524  * equal, the attribute types must be the same, and the attribute
 525  * values must have equal length and contents.  The result of the
 526  * comparison will be stored at the location pointed to by the "equalp"
 527  * variable, which must point to a valid PRBool.  This routine may
 528  * return PR_FAILURE upon error, in which case it will have set an
 529  * error on the error stack.
 530  *
 531  * The error may be one of the following values:
 532  *  NSS_ERROR_INVALID_ATAV
 533  *  NSS_ERROR_INVALID_ARGUMENT
 534  *
 535  * Return value:
 536  *  PR_FAILURE on error
 537  *  PR_SUCCESS upon a successful comparison (equal or not)
 538  */
 539
 540 NSS_EXTERN PRStatus
 541 nssATAV_Compare
 542 (
 543   NSSATAV *atav1,
 544   NSSATAV *atav2,
 545   PRBool *equalp
 546 );
 547
 548 /*
 549  * nssATAV_Duplicate
 550  *
 551  * This routine duplicates the specified ATAV.  If the optional arena
 552  * argument is non-null, the memory required will be obtained from
 553  * that arena; otherwise, the memory will be obtained from the heap.
 554  * This routine may return NULL upon error, in which case it will have
 555  * placed an error on the error stack.
 556  *
 557  * The error may be one of the following values:
 558  *  NSS_ERROR_INVALID_ATAV
 559  *  NSS_ERROR_NO_MEMORY
 560  *
 561  * Return value:
 562  *  NULL on error
 563  *  A pointer to a new ATAV
 564  */
 565
 566 NSS_EXTERN NSSATAV *
 567 nssATAV_Duplicate
 568 (
 569   NSSATAV *atav,
 570   NSSArena *arenaOpt
 571 );
 572
 573 /*
 574  * nssATAV_verifyPointer
 575  *
 576  * This method is only present in debug builds.
 577  *
 578  * If the specified pointer is a valid pointer to an NSSATAV object,
 579  * this routine will return PR_SUCCESS.  Otherwise, it will put an
 580  * error on the error stack and return PR_FAILRUE.
 581  *
 582  * The error may be one of the following values:
 583  *  NSS_ERROR_INVALID_NSSATAV
 584  *  NSS_ERROR_NO_MEMORY
 585  *
 586  * Return value:
 587  *  PR_SUCCESS if the pointer is valid
 588  *  PR_FAILURE if it isn't
 589  */
 590
 591 #ifdef DEBUG
 592 NSS_EXTERN PRStatus
 593 nssATAV_verifyPointer
 594 (
 595   NSSATAV *atav
 596 );
 597 #endif /* DEBUG */
 598
 599 /*
 600  * NSSRDN
 601  *
 602  * The non-public "methods" regarding this "object" are:
 603  *
 604  *  nssRDN_CreateFromBER   -- constructor
 605  *  nssRDN_CreateFromUTF8  -- constructor
 606  *  nssRDN_Create          -- constructor
 607  *  nssRDN_CreateSimple    -- constructor
 608  *
 609  *  nssRDN_Destroy
 610  *  nssRDN_GetDEREncoding
 611  *  nssRDN_GetUTF8Encoding
 612  *  nssRDN_AddATAV
 613  *  nssRDN_GetATAVCount
 614  *  nssRDN_GetATAV
 615  *  nssRDN_GetSimpleATAV
 616  *  nssRDN_Compare
 617  *  nssRDN_Duplicate
 618  */
 619
 620 /*
 621  * nssRDN_CreateFromBER
 622  *
 623  * This routine creates an NSSRDN by decoding a BER- or DER-encoded
 624  * RDN.  If the optional arena argument is non-null, the memory used
 625  * will be obtained from that arena; otherwise, the memory will be
 626  * obtained from the heap.  This routine may return NULL upon error,
 627  * in which case it will have set an error on the error stack.
 628  *
 629  * The error may be one of the following values:
 630  *  NSS_ERROR_INVALID_BER
 631  *  NSS_ERROR_NO_MEMORY
 632  *
 633  * Return value:
 634  *  NULL upon error
 635  *  A pointer to an NSSRDN upon success
 636  */
 637
 638 NSS_EXTERN NSSRDN *
 639 nssRDN_CreateFromBER
 640 (
 641   NSSArena *arenaOpt,
 642   NSSBER *berRDN
 643 );
 644
 645 /*
 646  * nssRDN_CreateFromUTF8
 647  *
 648  * This routine creates an NSSRDN by decoding an UTF8 string
 649  * consisting of either a single ATAV in the "equals" format, e.g.,
 650  * "uid=smith," or one or more such ATAVs in parentheses, e.g.,
 651  * "(sn=Smith,ou=Sales)."  If the optional arena argument is non-null,
 652  * the memory used will be obtained from that arena; otherwise, the
 653  * memory will be obtained from the heap.  This routine may return
 654  * NULL upon error, in which case it will have set an error on the
 655  * error stack.
 656  *
 657  * The error may be one of the following values:
 658  *  NSS_ERROR_UNKNOWN_ATTRIBUTE
 659  *  NSS_ERROR_INVALID_UTF8
 660  *  NSS_ERROR_NO_MEMORY
 661  *
 662  * Return value:
 663  *  NULL upon error
 664  *  A pointer to an NSSRDN upon success
 665  */
 666
 667 NSS_EXTERN NSSRDN *
 668 nssRDN_CreateFromUTF8
 669 (
 670   NSSArena *arenaOpt,
 671   NSSUTF8 *stringRDN
 672 );
 673
 674 /*
 675  * nssRDN_Create
 676  *
 677  * This routine creates an NSSRDN from one or more NSSATAVs.  The
 678  * final argument to this routine must be NULL.  If the optional arena
 679  * argument is non-null, the memory used will be obtained from that
 680  * arena; otherwise, the memory will be obtained from the heap.  This
 681  * routine may return NULL upon error, in which case it will have set
 682  * an error on the error stack.
 683  *
 684  * The error may be one of the following values:
 685  *  NSS_ERROR_NO_MEMORY
 686  *  NSS_ERROR_INVALID_ATAV
 687  *
 688  * Return value:
 689  *  NULL upon error
 690  *  A pointer to an NSSRDN upon success
 691  */
 692
 693 NSS_EXTERN NSSRDN *
 694 nssRDN_Create
 695 (
 696   NSSArena *arenaOpt,
 697   NSSATAV *atav1,
 698   ...
 699 );
 700
 701 /*
 702  * nssRDN_CreateSimple
 703  *
 704  * This routine creates a simple NSSRDN from a single NSSATAV.  If the
 705  * optional arena argument is non-null, the memory used will be
 706  * obtained from that arena; otherwise, the memory will be obtained
 707  * from the heap.  This routine may return NULL upon error, in which
 708  * case it will have set an error on the error stack.
 709  *
 710  * The error may be one of the following values:
 711  *  NSS_ERROR_NO_MEMORY
 712  *  NSS_ERROR_INVALID_ATAV
 713  *
 714  * Return value:
 715  *  NULL upon error
 716  *  A pointer to an NSSRDN upon success
 717  */
 718
 719 NSS_EXTERN NSSRDN *
 720 nssRDN_CreateSimple
 721 (
 722   NSSArena *arenaOpt,
 723   NSSATAV *atav
 724 );
 725
 726 /*
 727  * nssRDN_Destroy
 728  *
 729  * This routine will destroy an RDN object.  It should eventually be
 730  * called on all RDNs created without an arena.  While it is not
 731  * necessary to call it on RDNs created within an arena, it is not an
 732  * error to do so.  This routine returns a PRStatus value; if
 733  * successful, it will return PR_SUCCESS.  If unsuccessful, it will
 734  * set an error on the error stack and return PR_FAILURE.
 735  *
 736  * The error may be one of the following values:
 737  *  NSS_ERROR_INVALID_RDN
 738  *
 739  * Return value:
 740  *  PR_FAILURE upon failure
 741  *  PR_SUCCESS upon success
 742  */
 743
 744 NSS_EXTERN PRStatus
 745 nssRDN_Destroy
 746 (
 747   NSSRDN *rdn
 748 );
 749
 750 /*
 751  * nssRDN_GetDEREncoding
 752  *
 753  * This routine will DER-encode an RDN object.  If the optional arena
 754  * argument is non-null, the memory used will be obtained from that
 755  * arena; otherwise, the memory will be obtained from the heap.  This
 756  * routine may return null upon error, in which case it will have set
 757  * an error on the error stack.
 758  *
 759  * The error may be one of the following values:
 760  *  NSS_ERROR_INVALID_RDN
 761  *  NSS_ERROR_NO_MEMORY
 762  *
 763  * Return value:
 764  *  NULL upon error
 765  *  The DER encoding of this NSSRDN
 766  */
 767
 768 NSS_EXTERN NSSDER *
 769 nssRDN_GetDEREncoding
 770 (
 771   NSSRDN *rdn,
 772   NSSArena *arenaOpt
 773 );
 774
 775 /*
 776  * nssRDN_GetUTF8Encoding
 777  *
 778  * This routine returns a UTF8 string containing a string
 779  * representation of the RDN.  A simple (one-ATAV) RDN will be simply
 780  * the string representation of that ATAV; a non-simple RDN will be in
 781  * parenthesised form.  If the optional arena argument is non-null,
 782  * the memory used will be obtained from that arena; otherwise, the
 783  * memory will be obtained from the heap.  This routine may return
 784  * null upon error, in which case it will have set an error on the
 785  * error stack.
 786  *
 787  * The error may be one of the following values:
 788  *  NSS_ERROR_INVALID_RDN
 789  *  NSS_ERROR_NO_MEMORY
 790  *
 791  * Return value:
 792  *  NULL upon error
 793  *  A pointer to a UTF8 string
 794  */
 795
 796 NSS_EXTERN NSSUTF8 *
 797 nssRDN_GetUTF8Encoding
 798 (
 799   NSSRDN *rdn,
 800   NSSArena *arenaOpt
 801 );
 802
 803 /*
 804  * nssRDN_AddATAV
 805  *
 806  * This routine adds an ATAV to the set of ATAVs in the specified RDN.
 807  * Remember that RDNs consist of an unordered set of ATAVs.  If the
 808  * RDN was created with a non-null arena argument, that same arena
 809  * will be used for any additional required memory.  If the RDN was
 810  * created with a NULL arena argument, any additional memory will
 811  * be obtained from the heap.  This routine returns a PRStatus value;
 812  * it will return PR_SUCCESS upon success, and upon failure it will
 813  * set an error on the error stack and return PR_FAILURE.
 814  *
 815  * The error may be one of the following values:
 816  *  NSS_ERROR_INVALID_RDN
 817  *  NSS_ERROR_INVALID_ATAV
 818  *  NSS_ERROR_NO_MEMORY
 819  *
 820  * Return value:
 821  *  PR_SUCCESS upon success
 822  *  PR_FAILURE upon failure
 823  */
 824
 825 NSS_EXTERN PRStatus
 826 nssRDN_AddATAV
 827 (
 828   NSSRDN *rdn,
 829   NSSATAV *atav
 830 );
 831
 832 /*
 833  * nssRDN_GetATAVCount
 834  *
 835  * This routine returns the cardinality of the set of ATAVs within
 836  * the specified RDN.  This routine may return 0 upon error, in which
 837  * case it will have set an error on the error stack.
 838  *
 839  * The error may be one of the following values:
 840  *  NSS_ERROR_INVALID_RDN
 841  *
 842  * Return value:
 843  *  0 upon error
 844  *  A positive number upon success
 845  */
 846
 847 NSS_EXTERN PRUint32
 848 nssRDN_GetATAVCount
 849 (
 850   NSSRDN *rdn
 851 );
 852
 853 /*
 854  * nssRDN_GetATAV
 855  *
 856  * This routine returns a pointer to an ATAV that is a member of
 857  * the set of ATAVs within the specified RDN.  While the set of
 858  * ATAVs within an RDN is unordered, this routine will return
 859  * distinct values for distinct values of 'i' as long as the RDN
 860  * is not changed in any way.  The RDN may be changed by calling
 861  * NSSRDN_AddATAV.  The value of the variable 'i' is on the range
 862  * [0,c) where c is the cardinality returned from NSSRDN_GetATAVCount.
 863  * The caller owns the ATAV the pointer to which is returned.  If the
 864  * optional arena argument is non-null, the memory used will be
 865  * obtained from that arena; otherwise, the memory will be obtained
 866  * from the heap.  This routine may return NULL upon error, in which
 867  * case it will have set an error upon the error stack.
 868  *
 869  * The error may be one of the following values:
 870  *  NSS_ERROR_INVALID_RDN
 871  *  NSS_ERROR_VALUE_OUT_OF_RANGE
 872  *  NSS_ERROR_NO_MEMORY
 873  *
 874  * Return value:
 875  *  NULL upon error
 876  *  A caller-owned pointer to an NSSATAV
 877  */
 878
 879 NSS_EXTERN NSSATAV *
 880 nssRDN_GetATAV
 881 (
 882   NSSRDN *rdn,
 883   NSSArena *arenaOpt,
 884   PRUint32 i
 885 );
 886
 887 /*
 888  * nssRDN_GetSimpleATAV
 889  *
 890  * Most RDNs are actually very simple, with a single ATAV.  This
 891  * routine will return the single ATAV from such an RDN.  The caller
 892  * owns the ATAV the pointer to which is returned.  If the optional
 893  * arena argument is non-null, the memory used will be obtained from
 894  * that arena; otherwise, the memory will be obtained from the heap.
 895  * This routine may return NULL upon error, including the case where
 896  * the set of ATAVs in the RDN is nonsingular.  Upon error, this
 897  * routine will have set an error on the error stack.
 898  *
 899  * The error may be one of the following values:
 900  *  NSS_ERROR_INVALID_RDN
 901  *  NSS_ERROR_RDN_NOT_SIMPLE
 902  *  NSS_ERROR_NO_MEMORY
 903  *
 904  * Return value:
 905  *  NULL upon error
 906  *  A caller-owned pointer to an NSSATAV
 907  */
 908
 909 NSS_EXTERN NSSATAV *
 910 nssRDN_GetSimpleATAV
 911 (
 912   NSSRDN *rdn,
 913   NSSArena *arenaOpt
 914 );
 915
 916 /*
 917  * nssRDN_Compare
 918  *
 919  * This routine compares two RDNs for equality.  For two RDNs to be
 920  * equal, they must have the same number of ATAVs, and every ATAV in
 921  * one must be equal to an ATAV in the other.  (Note that the sets
 922  * of ATAVs are unordered.)  The result of the comparison will be
 923  * stored at the location pointed to by the "equalp" variable, which
 924  * must point to a valid PRBool.  This routine may return PR_FAILURE
 925  * upon error, in which case it will have set an error on the error
 926  * stack.
 927  *
 928  * The error may be one of the following values:
 929  *  NSS_ERROR_INVALID_RDN
 930  *  NSS_ERROR_INVALID_ARGUMENT
 931  *
 932  * Return value:
 933  *  PR_FAILURE on error
 934  *  PR_SUCCESS upon a successful comparison (equal or not)
 935  */
 936
 937 NSS_EXTERN PRStatus
 938 nssRDN_Compare
 939 (
 940   NSSRDN *rdn1,
 941   NSSRDN *rdn2,
 942   PRBool *equalp
 943 );
 944
 945 /*
 946  * nssRDN_Duplicate
 947  *
 948  * This routine duplicates the specified RDN.  If the optional arena
 949  * argument is non-null, the memory required will be obtained from
 950  * that arena; otherwise, the memory will be obtained from the heap.
 951  * This routine may return NULL upon error, in which case it will have
 952  * placed an error on the error stack.
 953  *
 954  * The error may be one of the following values:
 955  *  NSS_ERROR_INVALID_RDN
 956  *  NSS_ERROR_NO_MEMORY
 957  *
 958  * Return value:
 959  *  NULL on error
 960  *  A pointer to a new RDN
 961  */
 962
 963 NSS_EXTERN NSSRDN *
 964 nssRDN_Duplicate
 965 (
 966   NSSRDN *rdn,
 967   NSSArena *arenaOpt
 968 );
 969
 970 /*
 971  * NSSRDNSeq
 972  *
 973  * The non-public "methods" regarding this "object" are:
 974  *
 975  *  nssRDNSeq_CreateFromBER   -- constructor
 976  *  nssRDNSeq_CreateFromUTF8  -- constructor
 977  *  nssRDNSeq_Create          -- constructor
 978  *
 979  *  nssRDNSeq_Destroy
 980  *  nssRDNSeq_GetDEREncoding
 981  *  nssRDNSeq_GetUTF8Encoding
 982  *  nssRDNSeq_AppendRDN
 983  *  nssRDNSeq_GetRDNCount
 984  *  nssRDNSeq_GetRDN
 985  *  nssRDNSeq_Compare
 986  *  nssRDNSeq_Duplicate
 987  *
 988  *  nssRDNSeq_EvaluateUTF8 -- not an object method
 989  */
 990
 991 /*
 992  * nssRDNSeq_CreateFromBER
 993  *
 994  * This routine creates an NSSRDNSeq by decoding a BER- or DER-encoded
 995  * sequence of RDNs.  If the optional arena argument is non-null,
 996  * the memory used will be obtained from that arena; otherwise, the
 997  * memory will be obtained from the heap.  This routine may return
 998  * NULL upon error, in which case it will have set an error on the
 999  * error stack.
1000  *
1001  * The error may be one of the following values:
1002  *  NSS_ERROR_INVALID_BER
1003  *  NSS_ERROR_NO_MEMORY
1004  *
1005  * Return value:
1006  *  NULL upon error
1007  *  A pointer to an NSSRDNSeq upon success
1008  */
1009
1010 NSS_EXTERN NSSRDNSeq *
1011 nssRDNSeq_CreateFromBER
1012 (
1013   NSSArena *arenaOpt,
1014   NSSBER *berRDNSeq
1015 );
1016
1017 /*
1018  * nssRDNSeq_CreateFromUTF8
1019  *
1020  * This routine creates an NSSRDNSeq by decoding a UTF8 string
1021  * consisting of a comma-separated sequence of RDNs, such as
1022  * "(sn=Smith,ou=Sales),o=Acme,c=US."  If the optional arena argument
1023  * is non-null, the memory used will be obtained from that arena;
1024  * otherwise, the memory will be obtained from the heap.  This routine
1025  * may return NULL upon error, in which case it will have set an error
1026  * on the error stack.
1027  *
1028  * The error may be one of the following values:
1029  *  NSS_ERROR_UNKNOWN_ATTRIBUTE
1030  *  NSS_ERROR_INVALID_UTF8
1031  *  NSS_ERROR_NO_MEMORY
1032  *
1033  * Return value:
1034  *  NULL upon error
1035  *  A pointer to an NSSRDNSeq upon success
1036  */
1037
1038 NSS_EXTERN NSSRDNSeq *
1039 nssRDNSeq_CreateFromUTF8
1040 (
1041   NSSArena *arenaOpt,
1042   NSSUTF8 *stringRDNSeq
1043 );
1044
1045 /*
1046  * nssRDNSeq_Create
1047  *
1048  * This routine creates an NSSRDNSeq from one or more NSSRDNs.  The
1049  * final argument to this routine must be NULL.  If the optional arena
1050  * argument is non-null, the memory used will be obtained from that
1051  * arena; otherwise, the memory will be obtained from the heap.  This
1052  * routine may return NULL upon error, in which case it will have set
1053  * an error on the error stack.
1054  *
1055  * The error may be one of the following values:
1056  *  NSS_ERROR_NO_MEMORY
1057  *  NSS_ERROR_INVALID_RDN
1058  *
1059  * Return value:
1060  *  NULL upon error
1061  *  A pointero to an NSSRDNSeq upon success
1062  */
1063
1064 NSS_EXTERN NSSRDNSeq *
1065 nssRDNSeq_Create
1066 (
1067   NSSArena *arenaOpt,
1068   NSSRDN *rdn1,
1069   ...
1070 );
1071
1072 /*
1073  * nssRDNSeq_Destroy
1074  *
1075  * This routine will destroy an RDNSeq object.  It should eventually
1076  * be called on all RDNSeqs created without an arena.  While it is not
1077  * necessary to call it on RDNSeqs created within an arena, it is not
1078  * an error to do so.  This routine returns a PRStatus value; if
1079  * successful, it will return PR_SUCCESS.  If unsuccessful, it will
1080  * set an error on the error stack and return PR_FAILURE.
1081  *
1082  * The error may be one of the following values:
1083  *  NSS_ERROR_INVALID_RDNSEQ
1084  *
1085  * Return value:
1086  *  PR_FAILURE upon error
1087  *  PR_SUCCESS upon success
1088  */
1089
1090 NSS_EXTERN PRStatus
1091 nssRDNSeq_Destroy
1092 (
1093   NSSRDNSeq *rdnseq
1094 );
1095
1096 /*
1097  * nssRDNSeq_GetDEREncoding
1098  *
1099  * This routine will DER-encode an RDNSeq object.  If the optional
1100  * arena argument is non-null, the memory used will be obtained from
1101  * that arena; otherwise, the memory will be obtained from the heap.
1102  * This routine may return null upon error, in which case it will have
1103  * set an error on the error stack.
1104  *
1105  * The error may be one of the following values:
1106  *  NSS_ERROR_INVALID_RDNSEQ
1107  *  NSS_ERROR_NO_MEMORY
1108  *
1109  * Return value:
1110  *  NULL upon error
1111  *  The DER encoding of this NSSRDNSeq
1112  */
1113
1114 NSS_EXTERN NSSDER *
1115 nssRDNSeq_GetDEREncoding
1116 (
1117   NSSRDNSeq *rdnseq,
1118   NSSArena *arenaOpt
1119 );
1120
1121 /*
1122  * nssRDNSeq_GetUTF8Encoding
1123  *
1124  * This routine returns a UTF8 string containing a string
1125  * representation of the RDNSeq as a comma-separated sequence of RDNs.
1126  * If the optional arena argument is non-null, the memory used will be
1127  * obtained from that arena; otherwise, the memory will be obtained
1128  * from the heap.  This routine may return null upon error, in which
1129  * case it will have set an error on the error stack.
1130  *
1131  * The error may be one of the following values:
1132  *  NSS_ERROR_INVALID_RDNSEQ
1133  *  NSS_ERROR_NO_MEMORY
1134  *
1135  * Return value:
1136  *  NULL upon error
1137  *  A pointer to the UTF8 string
1138  */
1139
1140 NSS_EXTERN NSSUTF8 *
1141 nssRDNSeq_GetUTF8Encoding
1142 (
1143   NSSRDNSeq *rdnseq,
1144   NSSArena *arenaOpt
1145 );
1146
1147 /*
1148  * nssRDNSeq_AppendRDN
1149  *
1150  * This routine appends an RDN to the end of the existing RDN
1151  * sequence.  If the RDNSeq was created with a non-null arena
1152  * argument, that same arena will be used for any additional required
1153  * memory.  If the RDNSeq was created with a NULL arena argument, any
1154  * additional memory will be obtained from the heap.  This routine
1155  * returns a PRStatus value; it will return PR_SUCCESS upon success,
1156  * and upon failure it will set an error on the error stack and return
1157  * PR_FAILURE.
1158  *
1159  * The error may be one of the following values:
1160  *  NSS_ERROR_INVALID_RDNSEQ
1161  *  NSS_ERROR_INVALID_RDN
1162  *  NSS_ERROR_NO_MEMORY
1163  *
1164  * Return value:
1165  *  PR_SUCCESS upon success
1166  *  PR_FAILURE upon failure
1167  */
1168
1169 NSS_EXTERN PRStatus
1170 nssRDNSeq_AppendRDN
1171 (
1172   NSSRDNSeq *rdnseq,
1173   NSSRDN *rdn
1174 );
1175
1176 /*
1177  * nssRDNSeq_GetRDNCount
1178  *
1179  * This routine returns the cardinality of the sequence of RDNs within
1180  * the specified RDNSeq.  This routine may return 0 upon error, in
1181  * which case it will have set an error on the error stack.
1182  *
1183  * The error may be one of the following values:
1184  *  NSS_ERROR_INVALID_RDNSEQ
1185  *
1186  * Return value:
1187  *  0 upon error
1188  *  A positive number upon success
1189  */
1190
1191 NSS_EXTERN PRUint32
1192 nssRDNSeq_GetRDNCount
1193 (
1194   NSSRDNSeq *rdnseq
1195 );
1196
1197 /*
1198  * nssRDNSeq_GetRDN
1199  *
1200  * This routine returns a pointer to the i'th RDN in the sequence of
1201  * RDNs that make up the specified RDNSeq.  The sequence begins with
1202  * the top-level (e.g., "c=US") RDN.  The value of the variable 'i'
1203  * is on the range [0,c) where c is the cardinality returned from
1204  * NSSRDNSeq_GetRDNCount.  The caller owns the RDN the pointer to which
1205  * is returned.  If the optional arena argument is non-null, the memory
1206  * used will be obtained from that areana; otherwise, the memory will
1207  * be obtained from the heap.  This routine may return NULL upon error,
1208  * in which case it will have set an error upon the error stack.  Note
1209  * that the usual UTF8 representation of RDN Sequences is from last
1210  * to first.
1211  *
1212  * The error may be one of the following values:
1213  *  NSS_ERROR_INVALID_RDNSEQ
1214  *  NSS_ERROR_VALUE_OUT_OF_RANGE
1215  *  NSS_ERROR_NO_MEMORY
1216  *
1217  * Return value:
1218  *  NULL upon error
1219  *  A caller-owned pointer to an NSSRDN
1220  */
1221
1222 NSS_EXTERN NSSRDN *
1223 nssRDNSeq_GetRDN
1224 (
1225   NSSRDNSeq *rdnseq,
1226   NSSArena *arenaOpt,
1227   PRUint32 i
1228 );
1229
1230 /*
1231  * nssRDNSeq_Compare
1232  *
1233  * This routine compares two RDNSeqs for equality.  For two RDNSeqs to
1234  * be equal, they must have the same number of RDNs, and each RDN in
1235  * one sequence must be equal to the corresponding RDN in the other
1236  * sequence.  The result of the comparison will be stored at the
1237  * location pointed to by the "equalp" variable, which must point to a
1238  * valid PRBool.  This routine may return PR_FAILURE upon error, in
1239  * which case it will have set an error on the error stack.
1240  *
1241  * The error may be one of the following values:
1242  *  NSS_ERROR_INVALID_RDNSEQ
1243  *  NSS_ERROR_INVALID_ARGUMENT
1244  *
1245  * Return value:
1246  *  PR_FAILURE on error
1247  *  PR_SUCCESS upon a successful comparison (equal or not)
1248  */
1249
1250 NSS_EXTERN PRStatus
1251 nssRDNSeq_Compare
1252 (
1253   NSSRDNSeq *rdnseq1,
1254   NSSRDNSeq *rdnseq2,
1255   PRBool *equalp
1256 );
1257
1258 /*
1259  * nssRDNSeq_Duplicate
1260  *
1261  * This routine duplicates the specified RDNSeq.  If the optional arena
1262  * argument is non-null, the memory required will be obtained from that
1263  * arena; otherwise, the memory will be obtained from the heap.  This
1264  * routine may return NULL upon error, in which case it will have
1265  * placed an error on the error stack.
1266  *
1267  * The error may be one of the following values:
1268  *  NSS_ERROR_INVALID_RDNSEQ
1269  *  NSS_ERROR_NO_MEMORY
1270  *
1271  * Return value:
1272  *  NULL upon error
1273  *  A pointer to a new RDNSeq
1274  */
1275
1276 NSS_EXTERN NSSRDNSeq *
1277 nssRDNSeq_Duplicate
1278 (
1279   NSSRDNSeq *rdnseq,
1280   NSSArena *arenaOpt
1281 );
1282
1283 /*
1284  * nssRDNSeq_EvaluateUTF8
1285  *
1286  * This routine evaluates a UTF8 string, and returns PR_TRUE if the
1287  * string contains the string representation of an RDNSeq.  This
1288  * routine is used by the (directory) Name routines
1289  * nssName_CreateFromUTF8 and nssName_EvaluateUTF8 to determine which
1290  * choice of directory name the string may encode.  This routine may
1291  * return PR_FALSE upon error, but it subsumes that condition under the
1292  * general "string does not evaluate as an RDNSeq" state, and does not
1293  * set an error on the error stack.
1294  *
1295  * Return value:
1296  *  PR_TRUE if the string represents an RDNSeq
1297  *  PR_FALSE if otherwise
1298  */
1299
1300 NSS_EXTERN PRBool
1301 nssRDNSeq_EvaluateUTF8
1302 (
1303   NSSUTF8 *str
1304 );
1305
1306 /*
1307  * NSSName
1308  *
1309  * The non-public "methods" regarding this "object" are:
1310  *
1311  * nssName_CreateFromBER   -- constructor
1312  * nssName_CreateFromUTF8  -- constructor
1313  * nssName_Create          -- constructor
1314  *
1315  * nssName_Destroy
1316  * nssName_GetDEREncoding
1317  * nssName_GetUTF8Encoding
1318  * nssName_GetChoice
1319  * nssName_GetRDNSequence
1320  * nssName_GetSpecifiedChoice
1321  * nssName_Compare
1322  * nssName_Duplicate
1323  *
1324  * nssName_GetUID
1325  * nssName_GetEmail
1326  * nssName_GetCommonName
1327  * nssName_GetOrganization
1328  * nssName_GetOrganizationalUnits
1329  * nssName_GetStateOrProvince
1330  * nssName_GetLocality
1331  * nssName_GetCountry
1332  * nssName_GetAttribute
1333  *
1334  * nssName_EvaluateUTF8 -- not an object method
1335  */
1336
1337 /*
1338  * nssName_CreateFromBER
1339  *
1340  * This routine creates an NSSName by decoding a BER- or DER-encoded
1341  * (directory) Name.  If the optional arena argument is non-null,
1342  * the memory used will be obtained from that arena; otherwise,
1343  * the memory will be obtained from the heap.  This routine may
1344  * return NULL upon error, in which case it will have set an error
1345  * on the error stack.
1346  *
1347  * The error may be one of the following values:
1348  *  NSS_ERROR_INVALID_BER
1349  *  NSS_ERROR_NO_MEMORY
1350  *
1351  * Return value:
1352  *  NULL upon error
1353  *  A pointer to an NSSName upon success
1354  */
1355
1356 NSS_EXTERN NSSName *
1357 nssName_CreateFromBER
1358 (
1359   NSSArena *arenaOpt,
1360   NSSBER *berName
1361 );
1362
1363 /*
1364  * nssName_CreateFromUTF8
1365  *
1366  * This routine creates an NSSName by decoding a UTF8 string
1367  * consisting of the string representation of one of the choices of
1368  * (directory) names.  Currently the only choice is an RDNSeq.  If the
1369  * optional arena argument is non-null, the memory used will be
1370  * obtained from that arena; otherwise, the memory will be obtained
1371  * from the heap.  The routine may return NULL upon error, in which
1372  * case it will have set an error on the error stack.
1373  *
1374  * The error may be one of the following values:
1375  *  NSS_ERROR_INVALID_UTF8
1376  *  NSS_ERROR_NO_MEMORY
1377  *
1378  * Return value:
1379  *  NULL upon error
1380  *  A pointer to an NSSName upon success
1381  */
1382
1383 NSS_EXTERN NSSName *
1384 nssName_CreateFromUTF8
1385 (
1386   NSSArena *arenaOpt,
1387   NSSUTF8 *stringName
1388 );
1389
1390 /*
1391  * nssName_Create
1392  *
1393  * This routine creates an NSSName with the specified choice of
1394  * underlying name types.  The value of the choice variable must be
1395  * one of the values of the NSSNameChoice enumeration, and the type
1396  * of the arg variable must be as specified in the following table:
1397  *
1398  *   Choice                     Type
1399  *   ========================   ===========
1400  *   NSSNameChoiceRdnSequence   NSSRDNSeq *
1401  *
1402  * If the optional arena argument is non-null, the memory used will
1403  * be obtained from that arena; otherwise, the memory will be
1404  * obtained from the heap.  This routine may return NULL upon error,
1405  * in which case it will have set an error on the error stack.
1406  *
1407  * The error may be one of the following values:
1408  *  NSS_ERROR_INVALID_CHOICE
1409  *  NSS_ERROR_INVALID_ARGUMENT
1410  *  NSS_ERROR_NO_MEMORY
1411  *
1412  * Return value:
1413  *  NULL upon error
1414  *  A pointer to an NSSName upon success
1415  */
1416
1417 NSS_EXTERN NSSName *
1418 nssName_Create
1419 (
1420   NSSArena *arenaOpt,
1421   NSSNameChoice choice,
1422   void *arg
1423 );
1424
1425 /*
1426  * nssName_Destroy
1427  *
1428  * This routine will destroy a Name object.  It should eventually be
1429  * called on all Names created without an arena.  While it is not
1430  * necessary to call it on Names created within an arena, it is not
1431  * an error to do so.  This routine returns a PRStatus value; if
1432  * successful, it will return PR_SUCCESS.  If unsuccessful, it will
1433  * set an error on the error stack and return PR_FAILURE.
1434  *
1435  * The error may be one of the following values:
1436  *  NSS_ERROR_INVALID_NAME
1437  *
1438  * Return value:
1439  *  PR_FAILURE upon error
1440  *  PR_SUCCESS upon success
1441  */
1442
1443 NSS_EXTERN PRStatus
1444 nssName_Destroy
1445 (
1446   NSSName *name
1447 );
1448
1449 /*
1450  * nssName_GetDEREncoding
1451  *
1452  * This routine will DER-encode a name object.  If the optional arena
1453  * argument is non-null, the memory used will be obtained from that
1454  * arena; otherwise, the memory will be obtained from the heap.  This
1455  * routine may return null upon error, in which case it will have set
1456  * an error on the error stack.
1457  *
1458  * The error may be one of the following values:
1459  *  NSS_ERROR_INVALID_NAME
1460  *  NSS_ERROR_NO_MEMORY
1461  *
1462  * Return value:
1463  *  NULL upon error
1464  *  The DER encoding of this NSSName
1465  */
1466
1467 NSS_EXTERN NSSDER *
1468 nssName_GetDEREncoding
1469 (
1470   NSSName *name,
1471   NSSArena *arenaOpt
1472 );
1473
1474 /*
1475  * nssName_GetUTF8Encoding
1476  *
1477  * This routine returns a UTF8 string containing a string
1478  * representation of the Name in the format specified by the
1479  * underlying name choice.  If the optional arena argument is non-null,
1480  * the memory used will be obtained from that arena; otherwise, the
1481  * memory will be obtained from the heap.  This routine may return
1482  * NULL upon error, in which case it will have set an error on the
1483  * error stack.
1484  *
1485  * The error may be one of the following values:
1486  *  NSS_ERROR_INVALID_NAME
1487  *  NSS_ERROR_NO_MEMORY
1488  *
1489  * Return value:
1490  *  NULL upon error
1491  *  A pointer to the UTF8 string
1492  */
1493
1494 NSS_EXTERN NSSUTF8 *
1495 nssName_GetUTF8Encoding
1496 (
1497   NSSName *name,
1498   NSSArena *arenaOpt
1499 );
1500
1501 /*
1502  * nssName_GetChoice
1503  *
1504  * This routine returns the type of the choice underlying the specified
1505  * name.  The return value will be a member of the NSSNameChoice
1506  * enumeration.  This routine may return NSSNameChoiceInvalid upon
1507  * error, in which case it will have set an error on the error stack.
1508  *
1509  * The error may be one of the following values:
1510  *  NSS_ERROR_INVALID_NAME
1511  *
1512  * Return value:
1513  *  NSSNameChoiceInvalid upon error
1514  *  An other member of the NSSNameChoice enumeration upon success
1515  */
1516
1517 NSS_EXTERN NSSNameChoice
1518 nssName_GetChoice
1519 (
1520   NSSName *name
1521 );
1522
1523 /*
1524  * nssName_GetRDNSequence
1525  *
1526  * If the choice underlying the specified NSSName is that of an
1527  * RDNSequence, this routine will return a pointer to that RDN
1528  * sequence.  Otherwise, this routine will place an error on the
1529  * error stack, and return NULL.  If the optional arena argument is
1530  * non-null, the memory required will be obtained from that arena;
1531  * otherwise, the memory will be obtained from the heap.  The
1532  * caller owns the returned pointer.  This routine may return NULL
1533  * upon error, in which case it will have set an error on the error
1534  * stack.
1535  *
1536  * The error may be one of the following values:
1537  *  NSS_ERROR_INVALID_NAME
1538  *  NSS_ERROR_WRONG_CHOICE
1539  *  NSS_ERROR_NO_MEMORY
1540  *
1541  * Return value:
1542  *  NULL upon error
1543  *  A caller-owned pointer to an NSSRDNSeq
1544  */
1545
1546 NSS_EXTERN NSSRDNSeq *
1547 nssName_GetRDNSequence
1548 (
1549   NSSName *name,
1550   NSSArena *arenaOpt
1551 );
1552
1553 /*
1554  * nssName_GetSpecifiedChoice
1555  *
1556  * If the choice underlying the specified NSSName matches the specified
1557  * choice, a caller-owned pointer to that underlying object will be
1558  * returned.  Otherwise, an error will be placed on the error stack and
1559  * NULL will be returned.  If the optional arena argument is non-null,
1560  * the memory required will be obtained from that arena; otherwise, the
1561  * memory will be obtained from the heap.  The caller owns the returned
1562  * pointer.  This routine may return NULL upon error, in which case it
1563  * will have set an error on the error stack.
1564  *
1565  * The error may be one of the following values:
1566  *  NSS_ERROR_INVALID_NAME
1567  *  NSS_ERROR_WRONG_CHOICE
1568  *  NSS_ERROR_NO_MEMORY
1569  *
1570  * Return value:
1571  *  NULL upon error
1572  *  A caller-owned pointer, which must be typecast
1573  */
1574
1575 NSS_EXTERN void *
1576 nssName_GetSpecifiedChoice
1577 (
1578   NSSName *name,
1579   NSSNameChoice choice,
1580   NSSArena *arenaOpt
1581 );
1582
1583 /*
1584  * nssName_Compare
1585  *
1586  * This routine compares two Names for equality.  For two Names to be
1587  * equal, they must have the same choice of underlying types, and the
1588  * underlying values must be equal.  The result of the comparison will
1589  * be stored at the location pointed to by the "equalp" variable, which
1590  * must point to a valid PRBool. This routine may return PR_FAILURE
1591  * upon error, in which case it will have set an error on the error
1592  * stack.
1593  *
1594  * The error may be one of the following values:
1595  *  NSS_ERROR_INVALID_NAME
1596  *  NSS_ERROR_INVALID_ARGUMENT
1597  *
1598  * Return value:
1599  *  PR_FAILURE on error
1600  *  PR_SUCCESS upon a successful comparison (equal or not)
1601  */
1602
1603 NSS_EXTERN PRStatus
1604 nssName_Compare
1605 (
1606   NSSName *name1,
1607   NSSName *name2,
1608   PRBool *equalp
1609 );
1610
1611 /*
1612  * nssName_Duplicate
1613  *
1614  * This routine duplicates the specified nssname.  If the optional
1615  * arena argument is non-null, the memory required will be obtained
1616  * from that arena; otherwise, the memory will be obtained from the
1617  * heap.  This routine may return NULL upon error, in which case it
1618  * will have placed an error on the error stack.
1619  *
1620  * The error may be one of the following values:
1621  *  NSS_ERROR_INVALID_NAME
1622  *  NSS_ERROR_NO_MEMORY
1623  *
1624  * Return value:
1625  *  NULL upon error
1626  *  A pointer to a new NSSName
1627  */
1628
1629 NSS_EXTERN NSSName *
1630 nssName_Duplicate
1631 (
1632   NSSName *name,
1633   NSSArena *arenaOpt
1634 );
1635
1636 /*
1637  * nssName_GetUID
1638  *
1639  * This routine will attempt to derive a user identifier from the
1640  * specified name, if the choices and content of the name permit.
1641  * If the Name consists of a Sequence of Relative Distinguished
1642  * Names containing a UID attribute, the UID will be the value of
1643  * that attribute.  Note that no UID attribute is defined in either
1644  * PKIX or PKCS#9; rather, this seems to derive from RFC 1274, which
1645  * defines the type as a caseIgnoreString.  We'll return a Directory
1646  * String.  If the optional arena argument is non-null, the memory
1647  * used will be obtained from that arena; otherwise, the memory will
1648  * be obtained from the heap.  This routine may return NULL upon error,
1649  * in which case it will have set an error on the error stack.
1650  *
1651  * The error may be one of the following values:
1652  *  NSS_ERROR_INVALID_NAME
1653  *  NSS_ERROR_NO_UID
1654  *  NSS_ERROR_NO_MEMORY
1655  *
1656  * Return value:
1657  *  NULL upon error
1658  *  A pointer to a UTF8 String.
1659  */
1660
1661 NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
1662 nssName_GetUID
1663 (
1664   NSSName *name,
1665   NSSArena *arenaOpt
1666 );
1667
1668 /*
1669  * nssName_GetEmail
1670  *
1671  * This routine will attempt to derive an email address from the
1672  * specified name, if the choices and content of the name permit.
1673  * If the Name consists of a Sequence of Relative Distinguished
1674  * Names containing either a PKIX email address or a PKCS#9 email
1675  * address, the result will be the value of that attribute.  If the
1676  * optional arena argument is non-null, the memory used will be
1677  * obtained from that arena; otherwise, the memory will be obtained
1678  * from the heap.  This routine may return NULL upon error, in which
1679  * case it will have set an error on the error stack.
1680  *
1681  * The error may be one of the following values:
1682  *  NSS_ERROR_INVALID_NAME
1683  *  NSS_ERROR_NO_EMAIL
1684  *  NSS_ERROR_NO_MEMORY
1685  *
1686  * Return value:
1687  *  NULL upon error
1688  *  A pointer to a UTF8 String
1689  */
1690
1691 NSS_EXTERN NSSUTF8 * /* XXX fgmr IA5 String */
1692 nssName_GetEmail
1693 (
1694   NSSName *name,
1695   NSSArena *arenaOpt
1696 );
1697
1698 /*
1699  * nssName_GetCommonName
1700  *
1701  * This routine will attempt to derive a common name from the
1702  * specified name, if the choices and content of the name permit.
1703  * If the Name consists of a Sequence of Relative Distinguished Names
1704  * containing a PKIX Common Name, the result will be that name.  If
1705  * the optional arena argument is non-null, the memory used will be
1706  * obtained from that arena; otherwise, the memory will be obtained
1707  * from the heap.  This routine may return NULL upon error, in which
1708  * case it will have set an error on the error stack.
1709  *
1710  * The error may be one of the following values:
1711  *  NSS_ERROR_INVALID_NAME
1712  *  NSS_ERROR_NO_COMMON_NAME
1713  *  NSS_ERROR_NO_MEMORY
1714  *
1715  * Return value:
1716  *  NULL upon error
1717  *  A pointer to a UTF8 String
1718  */
1719
1720 NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
1721 nssName_GetCommonName
1722 (
1723   NSSName *name,
1724   NSSArena *arenaOpt
1725 );
1726
1727 /*
1728  * nssName_GetOrganization
1729  *
1730  * This routine will attempt to derive an organisation name from the
1731  * specified name, if the choices and content of the name permit.
1732  * If Name consists of a Sequence of Relative Distinguished names
1733  * containing a PKIX Organization, the result will be the value of
1734  * that attribute.  If the optional arena argument is non-null, the
1735  * memory used will be obtained from that arena; otherwise, the memory
1736  * will be obtained from the heap.  This routine may return NULL upon
1737  * error, in which case it will have set an error on the error stack.
1738  *
1739  * The error may be one of the following values:
1740  *  NSS_ERROR_INVALID_NAME
1741  *  NSS_ERROR_NO_ORGANIZATION
1742  *  NSS_ERROR_NO_MEMORY
1743  *
1744  * Return value:
1745  *  NULL upon error
1746  *  A pointer to a UTF8 String
1747  */
1748
1749 NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
1750 nssName_GetOrganization
1751 (
1752   NSSName *name,
1753   NSSArena *arenaOpt
1754 );
1755
1756 /*
1757  * nssName_GetOrganizationalUnits
1758  *
1759  * This routine will attempt to derive a sequence of organisational
1760  * unit names from the specified name, if the choices and content of
1761  * the name permit.  If the Name consists of a Sequence of Relative
1762  * Distinguished Names containing one or more organisational units,
1763  * the result will be the values of those attributes.  If the optional
1764  * arena argument is non-null, the memory used will be obtained from
1765  * that arena; otherwise, the memory will be obtained from the heap.
1766  * This routine may return NULL upon error, in which case it will have
1767  * set an error on the error stack.
1768  *
1769  * The error may be one of the following values:
1770  *  NSS_ERROR_INVALID_NAME
1771  *  NSS_ERROR_NO_ORGANIZATIONAL_UNITS
1772  *  NSS_ERROR_NO_MEMORY
1773  *
1774  * Return value:
1775  *  NULL upon error
1776  *  A pointer to a null-terminated array of UTF8 Strings
1777  */
1778
1779 NSS_EXTERN NSSUTF8 ** /* XXX fgmr DirectoryString */
1780 nssName_GetOrganizationalUnits
1781 (
1782   NSSName *name,
1783   NSSArena *arenaOpt
1784 );
1785
1786 /*
1787  * nssName_GetStateOrProvince
1788  *
1789  * This routine will attempt to derive a state or province name from
1790  * the specified name, if the choices and content of the name permit.
1791  * If the Name consists of a Sequence of Relative Distinguished Names
1792  * containing a state or province, the result will be the value of
1793  * that attribute.  If the optional arena argument is non-null, the
1794  * memory used will be obtained from that arena; otherwise, the memory
1795  * will be obtained from the heap.  This routine may return NULL upon
1796  * error, in which case it will have set an error on the error stack.
1797  *
1798  * The error may be one of the following values:
1799  *  NSS_ERROR_INVALID_NAME
1800  *  NSS_ERROR_NO_STATE_OR_PROVINCE
1801  *  NSS_ERROR_NO_MEMORY
1802  *
1803  * Return value:
1804  *  NULL upon error
1805  *  A pointer to a UTF8 String
1806  */
1807
1808 NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
1809 nssName_GetStateOrProvince
1810 (
1811   NSSName *name,
1812   NSSArena *arenaOpt
1813 );
1814
1815 /*
1816  * nssName_GetLocality
1817  *
1818  * This routine will attempt to derive a locality name from the
1819  * specified name, if the choices and content of the name permit.  If
1820  * the Name consists of a Sequence of Relative Distinguished names
1821  * containing a Locality, the result will be the value of that
1822  * attribute.  If the optional arena argument is non-null, the memory
1823  * used will be obtained from that arena; otherwise, the memory will
1824  * be obtained from the heap.  This routine may return NULL upon error,
1825  * in which case it will have set an error on the error stack.
1826  *
1827  * The error may be one of the following values:
1828  *  NSS_ERROR_INVALID_NAME
1829  *  NSS_ERROR_NO_LOCALITY
1830  *  NSS_ERROR_NO_MEMORY
1831  *
1832  * Return value:
1833  *  NULL upon error
1834  *  A pointer to a UTF8 String
1835  */
1836
1837 NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
1838 nssName_GetLocality
1839 (
1840   NSSName *name,
1841   NSSArena *arenaOpt
1842 );
1843
1844 /*
1845  * nssName_GetCountry
1846  *
1847  * This routine will attempt to derive a country name from the
1848  * specified name, if the choices and content of the name permit.
1849  * If the Name consists of a Sequence of Relative Distinguished
1850  * Names containing a Country, the result will be the value of
1851  * that attribute..  If the optional arena argument is non-null,
1852  * the memory used will be obtained from that arena; otherwise,
1853  * the memory will be obtained from the heap.  This routine may
1854  * return NULL upon error, in which case it will have set an error
1855  * on the error stack.
1856  *
1857  * The error may be one of the following values:
1858  *  NSS_ERROR_INVALID_NAME
1859  *  NSS_ERROR_NO_COUNTRY
1860  *  NSS_ERROR_NO_MEMORY
1861  *
1862  * Return value:
1863  *  NULL upon error
1864  *  A pointer to a UTF8 String
1865  */
1866
1867 NSS_EXTERN NSSUTF8 * /* XXX fgmr PrintableString */
1868 nssName_GetCountry
1869 (
1870   NSSName *name,
1871   NSSArena *arenaOpt
1872 );
1873
1874 /*
1875  * nssName_GetAttribute
1876  *
1877  * If the specified name consists of a Sequence of Relative
1878  * Distinguished Names containing an attribute with the specified
1879  * type, and the actual value of that attribute may be expressed
1880  * with a Directory String, then the value of that attribute will
1881  * be returned as a Directory String.  If the optional arena argument
1882  * is non-null, the memory used will be obtained from that arena;
1883  * otherwise, the memory will be obtained from the heap.  This routine
1884  * may return NULL upon error, in which case it will have set an error
1885  * on the error stack.
1886  *
1887  * The error may be one of the following values:
1888  *  NSS_ERROR_INVALID_NAME
1889  *  NSS_ERROR_NO_ATTRIBUTE
1890  *  NSS_ERROR_ATTRIBUTE_VALUE_NOT_STRING
1891  *
1892  * Return value:
1893  *  NULL upon error
1894  *  A pointer to a UTF8 String
1895  */
1896
1897 NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
1898 nssName_GetAttribute
1899 (
1900   NSSName *name,
1901   NSSOID *attribute,
1902   NSSArena *arenaOpt
1903 );
1904
1905 /*
1906  * nssName_EvaluateUTF8
1907  *
1908  * This routine evaluates a UTF8 string, and returns PR_TRUE if the
1909  * string contains the string representation of an NSSName.  This
1910  * routine is used by the GeneralName routine
1911  * nssGeneralName_CreateFromUTF8 to determine which choice of
1912  * general name the string may encode.  This routine may return
1913  * PR_FALSE upon error, but it subsumes that condition under the
1914  * general "string does not evaluate as a Name" state, and does not
1915  * set an error on the error stack.
1916  *
1917  * Return value:
1918  *  PR_TRUE if the string represents a Name
1919  *  PR_FALSE otherwise
1920  */
1921
1922 NSS_EXTERN PRBool
1923 nssName_EvaluateUTF8
1924 (
1925   NSSUTF8 *str
1926 );
1927
1928 /*
1929  * NSSGeneralName
1930  *
1931  * The non-public "methods" regarding this "object" are:
1932  *
1933  * nssGeneralName_CreateFromBER   -- constructor
1934  * nssGeneralName_CreateFromUTF8  -- constructor
1935  * nssGeneralName_Create          -- constructor
1936  *
1937  * nssGeneralName_Destroy
1938  * nssGeneralName_GetDEREncoding
1939  * nssGeneralName_GetUTF8Encoding
1940  * nssGeneralName_GetChoice
1941  * nssGeneralName_GetOtherName
1942  * nssGeneralName_GetRfc822Name
1943  * nssGeneralName_GetDNSName
1944  * nssGeneralName_GetX400Address
1945  * nssGeneralName_GetDirectoryName
1946  * nssGeneralName_GetEdiPartyName
1947  * nssGeneralName_GetUniformResourceIdentifier
1948  * nssGeneralName_GetIPAddress
1949  * nssGeneralName_GetRegisteredID
1950  * nssGeneralName_GetSpecifiedChoice
1951  * nssGeneralName_Compare
1952  * nssGeneralName_Duplicate
1953  *
1954  * nssGeneralName_GetUID
1955  * nssGeneralName_GetEmail
1956  * nssGeneralName_GetCommonName
1957  * nssGeneralName_GetOrganization
1958  * nssGeneralName_GetOrganizationalUnits
1959  * nssGeneralName_GetStateOrProvince
1960  * nssGeneralName_GetLocality
1961  * nssGeneralName_GetCountry
1962  * nssGeneralName_GetAttribute
1963  */
1964
1965 /*
1966  * nssGeneralName_CreateFromBER
1967  *
1968  * This routine creates an NSSGeneralName by decoding a BER- or DER-
1969  * encoded general name.  If the optional arena argument is non-null,
1970  * the memory used will be obtained from that arena; otherwise, the
1971  * memory will be obtained from the heap.  This routine may return
1972  * NULL upon error, in which case it will have set an error on the
1973  * error stack.
1974  *
1975  * The error may be one of the following values:
1976  *  NSS_ERROR_INVALID_BER
1977  *  NSS_ERROR_NO_MEMORY
1978  *
1979  * Return value:
1980  *  NULL upon error
1981  *  A pointer to an NSSGeneralName upon success
1982  */
1983
1984 NSS_EXTERN NSSGeneralName *
1985 nssGeneralName_CreateFromBER
1986 (
1987   NSSArena *arenaOpt,
1988   NSSBER *berGeneralName
1989 );
1990
1991 /*
1992  * nssGeneralName_CreateFromUTF8
1993  *
1994  * This routine creates an NSSGeneralName by decoding a UTF8 string
1995  * consisting of the string representation of one of the choices of
1996  * general names.  If the optional arena argument is non-null, the
1997  * memory used will be obtained from that arena; otherwise, the memory
1998  * will be obtained from the heap.  The routine may return NULL upon
1999  * error, in which case it will have set an error on the error stack.
2000  *
2001  * The error may be one of the following values:
2002  *  NSS_ERROR_INVALID_UTF8
2003  *  NSS_ERROR_NO_MEMORY
2004  *
2005  * Return value:
2006  *  NULL upon error
2007  *  A pointer to an NSSGeneralName upon success
2008  */
2009
2010 NSS_EXTERN NSSGeneralName *
2011 nssGeneralName_CreateFromUTF8
2012 (
2013   NSSArena *arenaOpt,
2014   NSSUTF8 *stringGeneralName
2015 );
2016
2017 /*
2018  * nssGeneralName_Create
2019  *
2020  * This routine creates an NSSGeneralName with the specified choice of
2021  * underlying name types.  The value of the choice variable must be one
2022  * of the values of the NSSGeneralNameChoice enumeration, and the type
2023  * of the arg variable must be as specified in the following table:
2024  *
2025  *   Choice                                         Type
2026  *   ============================================   =========
2027  *   NSSGeneralNameChoiceOtherName
2028  *   NSSGeneralNameChoiceRfc822Name
2029  *   NSSGeneralNameChoiceDNSName
2030  *   NSSGeneralNameChoiceX400Address
2031  *   NSSGeneralNameChoiceDirectoryName              NSSName *
2032  *   NSSGeneralNameChoiceEdiPartyName
2033  *   NSSGeneralNameChoiceUniformResourceIdentifier
2034  *   NSSGeneralNameChoiceIPAddress
2035  *   NSSGeneralNameChoiceRegisteredID
2036  *
2037  * If the optional arena argument is non-null, the memory used will
2038  * be obtained from that arena; otherwise, the memory will be
2039  * obtained from the heap.  This routine may return NULL upon error,
2040  * in which case it will have set an error on the error stack.
2041  *
2042  * The error may be one fo the following values:
2043  *  NSS_ERROR_INVALID_CHOICE
2044  *  NSS_ERROR_INVALID_ARGUMENT
2045  *  NSS_ERROR_NO_MEMORY
2046  *
2047  * Return value:
2048  *  NULL upon error
2049  *  A pointer to an NSSGeneralName upon success
2050  */
2051
2052 NSS_EXTERN NSSGeneralName *
2053 nssGeneralName_Create
2054 (
2055   NSSGeneralNameChoice choice,
2056   void *arg
2057 );
2058
2059 /*
2060  * nssGeneralName_Destroy
2061  *
2062  * This routine will destroy a General Name object.  It should
2063  * eventually be called on all General Names created without an arena.
2064  * While it is not necessary to call it on General Names created within
2065  * an arena, it is not an error to do so.  This routine returns a
2066  * PRStatus value; if successful, it will return PR_SUCCESS. If
2067  * usuccessful, it will set an error on the error stack and return
2068  * PR_FAILURE.
2069  *
2070  * The error may be one of the following values:
2071  *  NSS_ERROR_INVALID_GENERAL_NAME
2072  *
2073  * Return value:
2074  *  PR_FAILURE upon failure
2075  *  PR_SUCCESS upon success
2076  */
2077
2078 NSS_EXTERN PRStatus
2079 nssGeneralName_Destroy
2080 (
2081   NSSGeneralName *generalName
2082 );
2083
2084 /*
2085  * nssGeneralName_GetDEREncoding
2086  *
2087  * This routine will DER-encode a name object.  If the optional arena
2088  * argument is non-null, the memory used will be obtained from that
2089  * arena; otherwise, the memory will be obtained from the heap.  This
2090  * routine may return null upon error, in which case it will have set
2091  * an error on the error stack.
2092  *
2093  * The error may be one of the following values:
2094  *  NSS_ERROR_INVALID_GENERAL_NAME
2095  *  NSS_ERROR_NO_MEMORY
2096  *
2097  * Return value:
2098  *  NULL upon error
2099  *  The DER encoding of this NSSGeneralName
2100  */
2101
2102 NSS_EXTERN NSSDER *
2103 nssGeneralName_GetDEREncoding
2104 (
2105   NSSGeneralName *generalName,
2106   NSSArena *arenaOpt
2107 );
2108
2109 /*
2110  * nssGeneralName_GetUTF8Encoding
2111  *
2112  * This routine returns a UTF8 string containing a string
2113  * representation of the General Name in the format specified by the
2114  * underlying name choice.  If the optional arena argument is
2115  * non-null, the memory used will be obtained from that arena;
2116  * otherwise, the memory will be obtained from the heap.  This routine
2117  * may return NULL upon error, in which case it will have set an error
2118  * on the error stack.
2119  *
2120  * The error may be one of the following values:
2121  *  NSS_ERROR_INVALID_GENERAL_NAME
2122  *  NSS_ERROR_NO_MEMORY
2123  *
2124  * Return value:
2125  *  NULL upon error
2126  *  A pointer to a UTF8 string
2127  */
2128
2129 NSS_EXTERN NSSUTF8 *
2130 nssGeneralName_GetUTF8Encoding
2131 (
2132   NSSGeneralName *generalName,
2133   NSSArena *arenaOpt
2134 );
2135
2136 /*
2137  * nssGeneralName_GetChoice
2138  *
2139  * This routine returns the type of choice underlying the specified
2140  * general name.  The return value will be a member of the
2141  * NSSGeneralNameChoice enumeration.  This routine may return
2142  * NSSGeneralNameChoiceInvalid upon error, in which case it will have
2143  * set an error on the error stack.
2144  *
2145  * The error may be one of the following values:
2146  *  NSS_ERROR_INVALID_GENERAL_NAME
2147  *
2148  * Return value:
2149  *  NSSGeneralNameChoiceInvalid upon error
2150  *  An other member of the NSSGeneralNameChoice enumeration
2151  */
2152
2153 NSS_EXTERN NSSGeneralNameChoice
2154 nssGeneralName_GetChoice
2155 (
2156   NSSGeneralName *generalName
2157 );
2158
2159 /*
2160  * nssGeneralName_GetOtherName
2161  *
2162  * If the choice underlying the specified NSSGeneralName is that of an
2163  * Other Name, this routine will return a pointer to that Other name.
2164  * Otherwise, this routine will place an error on the error stack, and
2165  * return NULL.  If the optional arena argument is non-null, the memory
2166  * required will be obtained from that arena; otherwise, the memory
2167  * will be obtained from the heap.  The caller owns the returned
2168  * pointer.  This routine may return NULL upon error, in which case it
2169  * will have set an error on the error stack.
2170  *
2171  * The error may be one of the following values:
2172  *  NSS_ERROR_INVALID_GENERAL_NAME
2173  *  NSS_ERROR_WRONG_CHOICE
2174  *  NSS_ERROR_NO_MEMORY
2175  *
2176  * Return value:
2177  *  NULL upon error
2178  *  A caller-owned pointer to an NSSOtherName
2179  */
2180
2181 NSS_EXTERN NSSOtherName *
2182 nssGeneralName_GetOtherName
2183 (
2184   NSSGeneralName *generalName,
2185   NSSArena *arenaOpt
2186 );
2187
2188 /*
2189  * nssGeneralName_GetRfc822Name
2190  *
2191  * If the choice underlying the specified NSSGeneralName is that of an
2192  * RFC 822 Name, this routine will return a pointer to that name.
2193  * Otherwise, this routine will place an error on the error stack, and
2194  * return NULL.  If the optional arena argument is non-null, the memory
2195  * required will be obtained from that arena; otherwise, the memory
2196  * will be obtained from the heap.  The caller owns the returned
2197  * pointer.  This routine may return NULL upon error, in which case it
2198  * will have set an error on the error stack.
2199  *
2200  * The error may be one of the following values:
2201  *  NSS_ERROR_INVALID_GENERAL_NAME
2202  *  NSS_ERROR_WRONG_CHOICE
2203  *  NSS_ERROR_NO_MEMORY
2204  *
2205  * Return value:
2206  *  NULL upon error
2207  *  A caller-owned pointer to an NSSRFC822Name
2208  */
2209
2210 NSS_EXTERN NSSRFC822Name *
2211 nssGeneralName_GetRfc822Name
2212 (
2213   NSSGeneralName *generalName,
2214   NSSArena *arenaOpt
2215 );
2216
2217 /*
2218  * nssGeneralName_GetDNSName
2219  *
2220  * If the choice underlying the specified NSSGeneralName is that of a
2221  * DNS Name, this routine will return a pointer to that DNS name.
2222  * Otherwise, this routine will place an error on the error stack, and
2223  * return NULL.  If the optional arena argument is non-null, the memory
2224  * required will be obtained from that arena; otherwise, the memory
2225  * will be obtained from the heap.  The caller owns the returned
2226  * pointer.  This routine may return NULL upon error, in which case it
2227  * will have set an error on the error stack.
2228  *
2229  * The error may be one of the following values:
2230  *  NSS_ERROR_INVALID_GENERAL_NAME
2231  *  NSS_ERROR_WRONG_CHOICE
2232  *  NSS_ERROR_NO_MEMORY
2233  *
2234  * Return value:
2235  *  NULL upon error
2236  *  A caller-owned pointer to an NSSDNSName
2237  */
2238
2239 NSS_EXTERN NSSDNSName *
2240 nssGeneralName_GetDNSName
2241 (
2242   NSSGeneralName *generalName,
2243   NSSArena *arenaOpt
2244 );
2245
2246 /*
2247  * nssGeneralName_GetX400Address
2248  *
2249  * If the choice underlying the specified NSSGeneralName is that of an
2250  * X.400 Address, this routine will return a pointer to that Address.
2251  * Otherwise, this routine will place an error on the error stack, and
2252  * return NULL.  If the optional arena argument is non-null, the memory
2253  * required will be obtained from that arena; otherwise, the memory
2254  * will be obtained from the heap.  The caller owns the returned
2255  * pointer.  This routine may return NULL upon error, in which case it
2256  * will have set an error on the error stack.
2257  *
2258  * The error may be one of the following values:
2259  *  NSS_ERROR_INVALID_GENERAL_NAME
2260  *  NSS_ERROR_WRONG_CHOICE
2261  *  NSS_ERROR_NO_MEMORY
2262  *
2263  * Return value:
2264  *  NULL upon error
2265  *  A caller-owned pointer to an NSSX400Address
2266  */
2267
2268 NSS_EXTERN NSSX400Address *
2269 nssGeneralName_GetX400Address
2270 (
2271   NSSGeneralName *generalName,
2272   NSSArena *arenaOpt
2273 );
2274
2275 /*
2276  * nssGeneralName_GetDirectoryName
2277  *
2278  * If the choice underlying the specified NSSGeneralName is that of a
2279  * (directory) Name, this routine will return a pointer to that name.
2280  * Otherwise, this routine will place an error on the error stack, and
2281  * return NULL.  If the optional arena argument is non-null, the memory
2282  * required will be obtained from that arena; otherwise, the memory
2283  * will be obtained from the heap.  The caller owns the returned
2284  * pointer.  This routine may return NULL upon error, in which case it
2285  * will have set an error on the error stack.
2286  *
2287  * The error may be one of the following values:
2288  *  NSS_ERROR_INVALID_GENERAL_NAME
2289  *  NSS_ERROR_WRONG_CHOICE
2290  *  NSS_ERROR_NO_MEMORY
2291  *
2292  * Return value:
2293  *  NULL upon error
2294  *  A caller-owned pointer to an NSSName
2295  */
2296
2297 NSS_EXTERN NSSName *
2298 nssGeneralName_GetName
2299 (
2300   NSSGeneralName *generalName,
2301   NSSArena *arenaOpt
2302 );
2303
2304 /*
2305  * nssGeneralName_GetEdiPartyName
2306  *
2307  * If the choice underlying the specified NSSGeneralName is that of an
2308  * EDI Party Name, this routine will return a pointer to that name.
2309  * Otherwise, this routine will place an error on the error stack, and
2310  * return NULL.  If the optional arena argument is non-null, the memory
2311  * required will be obtained from that arena; otherwise, the memory
2312  * will be obtained from the heap.  The caller owns the returned
2313  * pointer.  This routine may return NULL upon error, in which case it
2314  * will have set an error on the error stack.
2315  *
2316  * The error may be one of the following values:
2317  *  NSS_ERROR_INVALID_GENERAL_NAME
2318  *  NSS_ERROR_WRONG_CHOICE
2319  *  NSS_ERROR_NO_MEMORY
2320  *
2321  * Return value:
2322  *  NULL upon error
2323  *  A caller-owned pointer to an NSSEdiPartyName
2324  */
2325
2326 NSS_EXTERN NSSEdiPartyName *
2327 nssGeneralName_GetEdiPartyName
2328 (
2329   NSSGeneralName *generalName,
2330   NSSArena *arenaOpt
2331 );
2332
2333 /*
2334  * nssGeneralName_GetUniformResourceIdentifier
2335  *
2336  * If the choice underlying the specified NSSGeneralName is that of a
2337  * URI, this routine will return a pointer to that URI.
2338  * Otherwise, this routine will place an error on the error stack, and
2339  * return NULL.  If the optional arena argument is non-null, the memory
2340  * required will be obtained from that arena; otherwise, the memory
2341  * will be obtained from the heap.  The caller owns the returned
2342  * pointer.  This routine may return NULL upon error, in which case it
2343  * will have set an error on the error stack.
2344  *
2345  * The error may be one of the following values:
2346  *  NSS_ERROR_INVALID_GENERAL_NAME
2347  *  NSS_ERROR_WRONG_CHOICE
2348  *  NSS_ERROR_NO_MEMORY
2349  *
2350  * Return value:
2351  *  NULL upon error
2352  *  A caller-owned pointer to an NSSURI
2353  */
2354
2355 NSS_EXTERN NSSURI *
2356 nssGeneralName_GetUniformResourceIdentifier
2357 (
2358   NSSGeneralName *generalName,
2359   NSSArena *arenaOpt
2360 );
2361
2362 /*
2363  * nssGeneralName_GetIPAddress
2364  *
2365  * If the choice underlying the specified NSSGeneralName is that of an
2366  * IP Address , this routine will return a pointer to that address.
2367  * Otherwise, this routine will place an error on the error stack, and
2368  * return NULL.  If the optional arena argument is non-null, the memory
2369  * required will be obtained from that arena; otherwise, the memory
2370  * will be obtained from the heap.  The caller owns the returned
2371  * pointer.  This routine may return NULL upon error, in which case it
2372  * will have set an error on the error stack.
2373  *
2374  * The error may be one of the following values:
2375  *  NSS_ERROR_INVALID_GENERAL_NAME
2376  *  NSS_ERROR_WRONG_CHOICE
2377  *  NSS_ERROR_NO_MEMORY
2378  *
2379  * Return value:
2380  *  NULL upon error
2381  *  A caller-owned pointer to an NSSIPAddress
2382  */
2383
2384 NSS_EXTERN NSSIPAddress *
2385 nssGeneralName_GetIPAddress
2386 (
2387   NSSGeneralName *generalName,
2388   NSSArena *arenaOpt
2389 );
2390
2391 /*
2392  * nssGeneralName_GetRegisteredID
2393  *
2394  * If the choice underlying the specified NSSGeneralName is that of a
2395  * Registered ID, this routine will return a pointer to that ID.
2396  * Otherwise, this routine will place an error on the error stack, and
2397  * return NULL.  If the optional arena argument is non-null, the memory
2398  * required will be obtained from that arena; otherwise, the memory
2399  * will be obtained from the heap.  The caller owns the returned
2400  * pointer.  This routine may return NULL upon error, in which case it
2401  * will have set an error on the error stack.
2402  *
2403  * The error may be one of the following values:
2404  *  NSS_ERROR_INVALID_GENERAL_NAME
2405  *  NSS_ERROR_WRONG_CHOICE
2406  *  NSS_ERROR_NO_MEMORY
2407  *
2408  * Return value:
2409  *  NULL upon error
2410  *  A caller-owned pointer to an NSSRegisteredID
2411  */
2412
2413 NSS_EXTERN NSSRegisteredID *
2414 nssGeneralName_GetRegisteredID
2415 (
2416   NSSGeneralName *generalName,
2417   NSSArena *arenaOpt
2418 );
2419
2420 /*
2421  * nssGeneralName_GetSpecifiedChoice
2422  *
2423  * If the choice underlying the specified NSSGeneralName matches the
2424  * specified choice, a caller-owned pointer to that underlying object
2425  * will be returned.  Otherwise, an error will be placed on the error
2426  * stack and NULL will be returned.  If the optional arena argument
2427  * is non-null, the memory required will be obtained from that arena;
2428  * otherwise, the memory will be obtained from the heap.  The caller
2429  * owns the returned pointer.  This routine may return NULL upon
2430  * error, in which caes it will have set an error on the error stack.
2431  *
2432  * The error may be one of the following values:
2433  *  NSS_ERROR_INVALID_GENERAL_NAME
2434  *  NSS_ERROR_WRONG_CHOICE
2435  *  NSS_ERROR_NO_MEMORY
2436  *
2437  * Return value:
2438  *  NULL upon error
2439  *  A caller-owned pointer, which must be typecast
2440  */
2441
2442 NSS_EXTERN void *
2443 nssGeneralName_GetSpecifiedChoice
2444 (
2445   NSSGeneralName *generalName,
2446   NSSGeneralNameChoice choice,
2447   NSSArena *arenaOpt
2448 );
2449
2450 /*
2451  * nssGeneralName_Compare
2452  *
2453  * This routine compares two General Names for equality.  For two
2454  * General Names to be equal, they must have the same choice of
2455  * underlying types, and the underlying values must be equal.  The
2456  * result of the comparison will be stored at the location pointed
2457  * to by the "equalp" variable, which must point to a valid PRBool.
2458  * This routine may return PR_FAILURE upon error, in which case it
2459  * will have set an error on the error stack.
2460  *
2461  * The error may be one of the following value:
2462  *  NSS_ERROR_INVALID_GENERAL_NAME
2463  *  NSS_ERROR_INVALID_ARGUMENT
2464  *
2465  * Return value:
2466  *  PR_FAILURE upon error
2467  *  PR_SUCCESS upon a successful comparison (equal or not)
2468  */
2469
2470 NSS_EXTERN PRStatus
2471 nssGeneralName_Compare
2472 (
2473   NSSGeneralName *generalName1,
2474   NSSGeneralName *generalName2,
2475   PRBool *equalp
2476 );
2477
2478 /*
2479  * nssGeneralName_Duplicate
2480  *
2481  * This routine duplicates the specified General Name.  If the optional
2482  * arena argument is non-null, the memory required will be obtained
2483  * from that arena; otherwise, the memory will be obtained from the
2484  * heap.  This routine may return NULL upon error, in which case it
2485  * will have set an error on the error stack.
2486  *
2487  * The error may be one of the following values:
2488  *  NSS_ERROR_INVALID_GENERAL_NAME
2489  *  NSS_ERROR_NO_MEMORY
2490  *
2491  * Return value:
2492  *  NULL upon error
2493  *  A pointer to a new NSSGeneralName
2494  */
2495
2496 NSS_EXTERN NSSGeneralName *
2497 nssGeneralName_Duplicate
2498 (
2499   NSSGeneralName *generalName,
2500   NSSArena *arenaOpt
2501 );
2502
2503 /*
2504  * nssGeneralName_GetUID
2505  *
2506  * This routine will attempt to derive a user identifier from the
2507  * specified general name, if the choices and content of the name
2508  * permit.  If the General Name is a (directory) Name consisting
2509  * of a Sequence of Relative Distinguished Names containing a UID
2510  * attribute, the UID will be the value of that attribute.  Note
2511  * that no UID attribute is defined in either PKIX or PKCS#9;
2512  * rather, this seems to derive from RFC 1274, which defines the
2513  * type as a caseIgnoreString.  We'll return a Directory String.
2514  * If the optional arena argument is non-null, the memory used
2515  * will be obtained from that arena; otherwise, the memory will be
2516  * obtained from the heap.  This routine may return NULL upon error,
2517  * in which case it will have set an error on the error stack.
2518  *
2519  * The error may be one of the following values:
2520  *  NSS_ERROR_INVALID_GENERAL_NAME
2521  *  NSS_ERROR_NO_UID
2522  *  NSS_ERROR_NO_MEMORY
2523  *
2524  * Return value:
2525  *  NULL upon error
2526  *  A pointer to a UTF8 String.
2527  */
2528
2529 NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
2530 nssGeneralName_GetUID
2531 (
2532   NSSGeneralName *generalName,
2533   NSSArena *arenaOpt
2534 );
2535
2536 /*
2537  * nssGeneralName_GetEmail
2538  *
2539  * This routine will attempt to derive an email address from the
2540  * specified general name, if the choices and content of the name
2541  * permit.  If the General Name is a (directory) Name consisting
2542  * of a Sequence of Relative Distinguished names containing either
2543  * a PKIX email address or a PKCS#9 email address, the result will
2544  * be the value of that attribute.  If the General Name is an RFC 822
2545  * Name, the result will be the string form of that name.  If the
2546  * optional arena argument is non-null, the memory used will be
2547  * obtained from that arena; otherwise, the memory will be obtained
2548  * from the heap.  This routine may return NULL upon error, in which
2549  * case it will have set an error on the error stack.
2550  *
2551  * The error may be one of the following values:
2552  *  NSS_ERROR_INVALID_GENERAL_NAME
2553  *  NSS_ERROR_NO_EMAIL
2554  *  NSS_ERROR_NO_MEMORY
2555  *
2556  * Return value:
2557  *  NULL upon error
2558  *  A pointer to a UTF8 String
2559  */
2560
2561 NSS_EXTERN NSSUTF8 * /* XXX fgmr IA5String */
2562 nssGeneralName_GetEmail
2563 (
2564   NSSGeneralName *generalName,
2565   NSSArena *arenaOpt
2566 );
2567
2568 /*
2569  * nssGeneralName_GetCommonName
2570  *
2571  * This routine will attempt to derive a common name from the
2572  * specified general name, if the choices and content of the name
2573  * permit.  If the General Name is a (directory) Name consisting
2574  * of a Sequence of Relative Distinguished names containing a PKIX
2575  * Common Name, the result will be that name.  If the optional arena
2576  * argument is non-null, the memory used will be obtained from that
2577  * arena; otherwise, the memory will be obtained from the heap.  This
2578  * routine may return NULL upon error, in which case it will have set
2579  * an error on the error stack.
2580  *
2581  * The error may be one of the following values:
2582  *  NSS_ERROR_INVALID_GENERAL_NAME
2583  *  NSS_ERROR_NO_COMMON_NAME
2584  *  NSS_ERROR_NO_MEMORY
2585  *
2586  * Return value:
2587  *  NULL upon error
2588  *  A pointer to a UTF8 String
2589  */
2590
2591 NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
2592 nssGeneralName_GetCommonName
2593 (
2594   NSSGeneralName *generalName,
2595   NSSArena *arenaOpt
2596 );
2597
2598 /*
2599  * nssGeneralName_GetOrganization
2600  *
2601  * This routine will attempt to derive an organisation name from the
2602  * specified general name, if the choices and content of the name
2603  * permit.  If the General Name is a (directory) Name consisting
2604  * of a Sequence of Relative Distinguished names containing an
2605  * Organization, the result will be the value of that attribute.
2606  * If the optional arena argument is non-null, the memory used will
2607  * be obtained from that arena; otherwise, the memory will be obtained
2608  * from the heap.  This routine may return NULL upon error, in which
2609  * case it will have set an error on the error stack.
2610  *
2611  * The error may be one of the following values:
2612  *  NSS_ERROR_INVALID_GENERAL_NAME
2613  *  NSS_ERROR_NO_ORGANIZATION
2614  *  NSS_ERROR_NO_MEMORY
2615  *
2616  * Return value:
2617  *  NULL upon error
2618  *  A pointer to a UTF8 String
2619  */
2620
2621 NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
2622 nssGeneralName_GetOrganization
2623 (
2624   NSSGeneralName *generalName,
2625   NSSArena *arenaOpt
2626 );
2627
2628 /*
2629  * nssGeneralName_GetOrganizationalUnits
2630  *
2631  * This routine will attempt to derive a sequence of organisational
2632  * unit names from the specified general name, if the choices and
2633  * content of the name permit.  If the General Name is a (directory)
2634  * Name consisting of a Sequence of Relative Distinguished names
2635  * containing one or more organisational units, the result will
2636  * consist of those units.  If the optional arena  argument is non-
2637  * null, the memory used will be obtained from that arena; otherwise,
2638  * the memory will be obtained from the heap.  This routine may return
2639  * NULL upon error, in which case it will have set an error on the
2640  * error stack.
2641  *
2642  * The error may be one of the following values:
2643  *  NSS_ERROR_INVALID_GENERAL_NAME
2644  *  NSS_ERROR_NO_ORGANIZATIONAL_UNITS
2645  *  NSS_ERROR_NO_MEMORY
2646  *
2647  * Return value:
2648  *  NULL upon error
2649  *  A pointer to a null-terminated array of UTF8 Strings
2650  */
2651
2652 NSS_EXTERN NSSUTF8 ** /* XXX fgmr DirectoryString */
2653 nssGeneralName_GetOrganizationalUnits
2654 (
2655   NSSGeneralName *generalName,
2656   NSSArena *arenaOpt
2657 );
2658
2659 /*
2660  * nssGeneralName_GetStateOrProvince
2661  *
2662  * This routine will attempt to derive a state or province name from
2663  * the specified general name, if the choices and content of the name
2664  * permit.  If the General Name is a (directory) Name consisting
2665  * of a Sequence of Relative Distinguished names containing a state or
2666  * province, the result will be the value of that attribute.  If the
2667  * optional arena argument is non-null, the memory used will be
2668  * obtained from that arena; otherwise, the memory will be obtained
2669  * from the heap.  This routine may return NULL upon error, in which
2670  * case it will have set an error on the error stack.
2671  *
2672  * The error may be one of the following values:
2673  *  NSS_ERROR_INVALID_GENERAL_NAME
2674  *  NSS_ERROR_NO_STATE_OR_PROVINCE
2675  *  NSS_ERROR_NO_MEMORY
2676  *
2677  * Return value:
2678  *  NULL upon error
2679  *  A pointer to a UTF8 String
2680  */
2681
2682 NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
2683 nssGeneralName_GetStateOrProvince
2684 (
2685   NSSGeneralName *generalName,
2686   NSSArena *arenaOpt
2687 );
2688
2689 /*
2690  * nssGeneralName_GetLocality
2691  *
2692  * This routine will attempt to derive a locality name from
2693  * the specified general name, if the choices and content of the name
2694  * permit.  If the General Name is a (directory) Name consisting
2695  * of a Sequence of Relative Distinguished names containing a Locality,
2696  * the result will be the value of that attribute.  If the optional
2697  * arena argument is non-null, the memory used will be obtained from
2698  * that arena; otherwise, the memory will be obtained from the heap.
2699  * This routine may return NULL upon error, in which case it will have
2700  * set an error on the error stack.
2701  *
2702  * The error may be one of the following values:
2703  *  NSS_ERROR_INVALID_GENERAL_NAME
2704  *  NSS_ERROR_NO_LOCALITY
2705  *  NSS_ERROR_NO_MEMORY
2706  *
2707  * Return value:
2708  *  NULL upon error
2709  *  A pointer to a UTF8 String
2710  */
2711
2712 NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
2713 nssGeneralName_GetLocality
2714 (
2715   NSSGeneralName *generalName,
2716   NSSArena *arenaOpt
2717 );
2718
2719 /*
2720  * nssGeneralName_GetCountry
2721  *
2722  * This routine will attempt to derive a country name from the
2723  * specified general name, if the choices and content of the name
2724  * permit.  If the General Name is a (directory) Name consisting of a
2725  * Sequence of Relative Distinguished names containing a Country, the
2726  * result will be the value of that attribute.  If the optional
2727  * arena argument is non-null, the memory used will be obtained from
2728  * that arena; otherwise, the memory will be obtained from the heap.
2729  * This routine may return NULL upon error, in which case it will have
2730  * set an error on the error stack.
2731  *
2732  * The error may be one of the following values:
2733  *  NSS_ERROR_INVALID_GENERAL_NAME
2734  *  NSS_ERROR_NO_COUNTRY
2735  *  NSS_ERROR_NO_MEMORY
2736  *
2737  * Return value:
2738  *  NULL upon error
2739  *  A pointer to a UTF8 String
2740  */
2741
2742 NSS_EXTERN NSSUTF8 * /* XXX fgmr PrintableString */
2743 nssGeneralName_GetCountry
2744 (
2745   NSSGeneralName *generalName,
2746   NSSArena *arenaOpt
2747 );
2748
2749 /*
2750  * nssGeneralName_GetAttribute
2751  *
2752  * If the specified general name is a (directory) name consisting
2753  * of a Sequence of Relative Distinguished Names containing an
2754  * attribute with the specified type, and the actual value of that
2755  * attribute may be expressed with a Directory String, then the
2756  * value of that attribute will be returned as a Directory String.
2757  * If the optional arena argument is non-null, the memory used will
2758  * be obtained from that arena; otherwise, the memory will be obtained
2759  * from the heap.  This routine may return NULL upon error, in which
2760  * case it will have set an error on the error stack.
2761  *
2762  * The error may be one of the following values:
2763  *  NSS_ERROR_INVALID_GENERAL_NAME
2764  *  NSS_ERROR_NO_ATTRIBUTE
2765  *  NSS_ERROR_ATTRIBUTE_VALUE_NOT_STRING
2766  *
2767  * Return value:
2768  *  NULL upon error
2769  *  A pointer to a UTF8 String
2770  */
2771
2772 NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
2773 nssGeneralName_GetAttribute
2774 (
2775   NSSGeneralName *generalName,
2776   NSSOID *attribute,
2777   NSSArena *arenaOpt
2778 );
2779
2780 /*
2781  * NSSGeneralNameSeq
2782  *
2783  * The public "methods" regarding this "object" are:
2784  *
2785  *  nssGeneralNameSeq_CreateFromBER   -- constructor
2786  *  nssGeneralNameSeq_Create          -- constructor
2787  *
2788  *  nssGeneralNameSeq_Destroy
2789  *  nssGeneralNameSeq_GetDEREncoding
2790  *  nssGeneralNameSeq_AppendGeneralName
2791  *  nssGeneralNameSeq_GetGeneralNameCount
2792  *  nssGeneralNameSeq_GetGeneralName
2793  *  nssGeneralNameSeq_Compare
2794  *  nssGeneralnameSeq_Duplicate
2795  */
2796
2797 /*
2798  * nssGeneralNameSeq_CreateFromBER
2799  *
2800  * This routine creates a general name sequence by decoding a BER-
2801  * or DER-encoded GeneralNames.  If the optional arena argument is
2802  * non-null, the memory used will be obtained from that arena;
2803  * otherwise, the memory will be obtained from the heap.  This routine
2804  * may return NULL upon error, in which case it will have set an error
2805  * on the error stack.
2806  *
2807  * The error may be one of the following values:
2808  *  NSS_ERROR_INVALID_BER
2809  *  NSS_ERROR_NO_MEMORY
2810  *
2811  * Return value:
2812  *  NULL upon error
2813  *  A pointer to an NSSGeneralNameSeq upon success
2814  */
2815
2816 NSS_EXTERN NSSGeneralNameSeq *
2817 nssGeneralNameSeq_CreateFromBER
2818 (
2819   NSSArena *arenaOpt,
2820   NSSBER *berGeneralNameSeq
2821 );
2822
2823 /*
2824  * nssGeneralNameSeq_Create
2825  *
2826  * This routine creates an NSSGeneralNameSeq from one or more General
2827  * Names.  The final argument to this routine must be NULL.  If the
2828  * optional arena argument is non-null, the memory used will be
2829  * obtained from that arena; otherwise, the memory will be obtained
2830  * from the heap.  This routine may return NULL upon error, in which
2831  * case it will have set an error on the error stack.
2832  *
2833  * The error may be one of the following values:
2834  *  NSS_ERROR_NO_MEMORY
2835  *  NSS_ERROR_INVALID_GENERAL_NAME
2836  *
2837  * Return value:
2838  *  NULL upon error
2839  *  A pointer to an NSSGeneralNameSeq upon success
2840  */
2841
2842 NSS_EXTERN NSSGeneralNameSeq *
2843 nssGeneralNameSeq_Create
2844 (
2845   NSSArena *arenaOpt,
2846   NSSGeneralName *generalName1,
2847   ...
2848 );
2849
2850 /*
2851  * nssGeneralNameSeq_Destroy
2852  *
2853  * This routine will destroy an NSSGeneralNameSeq object.  It should
2854  * eventually be called on all NSSGeneralNameSeqs created without an
2855  * arena.  While it is not necessary to call it on NSSGeneralNameSeq's
2856  * created within an arena, it is not an error to do so.  This routine
2857  * returns a PRStatus value; if successful, it will return PR_SUCCESS.
2858  * If unsuccessful, it will set an error on the error stack and return
2859  * PR_FAILURE.
2860  *
2861  * The error may be one of the following values:
2862  *  NSS_ERROR_INVALID_GENERAL_NAME_SEQ
2863  *
2864  * Return value:
2865  *  PR_FAILURE upon error
2866  *  PR_SUCCESS upon success
2867  */
2868
2869 NSS_EXTERN PRStatus
2870 nssGeneralNameSeq_Destroy
2871 (
2872   NSSGeneralNameSeq *generalNameSeq
2873 );
2874
2875 /*
2876  * nssGeneralNameSeq_GetDEREncoding
2877  *
2878  * This routine will DER-encode an NSSGeneralNameSeq object.  If the
2879  * optional arena argument is non-null, the memory used will be
2880  * obtained from that arena; otherwise, the memory will be obtained
2881  * from the heap.  This routine may return null upon error, in which
2882  * case it will have set an error on the error stack.
2883  *
2884  * The error may be one of the following values:
2885  *  NSS_ERROR_INVALID_GENERAL_NAME_SEQ
2886  *  NSS_ERROR_NO_MEMORY
2887  *
2888  * Return value:
2889  *  NULL upon error
2890  *  The DER encoding of this NSSGeneralNameSeq
2891  */
2892
2893 NSS_EXTERN NSSDER *
2894 nssGeneralNameSeq_GetDEREncoding
2895 (
2896   NSSGeneralNameSeq *generalNameSeq,
2897   NSSArena *arenaOpt
2898 );
2899
2900 /*
2901  * nssGeneralNameSeq_AppendGeneralName
2902  *
2903  * This routine appends a General Name to the end of the existing
2904  * General Name Sequence.  If the sequence was created with a non-null
2905  * arena argument, that same arena will be used for any additional
2906  * required memory.  If the sequence was created with a NULL arena
2907  * argument, any additional memory will be obtained from the heap.
2908  * This routine returns a PRStatus value; it will return PR_SUCCESS
2909  * upon success, and upon failure it will set an error on the error
2910  * stack and return PR_FAILURE.
2911  *
2912  * The error may be one of the following values:
2913  *  NSS_ERROR_INVALID_GENERAL_NAME_SEQ
2914  *  NSS_ERROR_INVALID_GENERAL_NAME
2915  *  NSS_ERROR_NO_MEMORY
2916  *
2917  * Return value:
2918  *  PR_SUCCESS upon success
2919  *  PR_FAILURE upon failure.
2920  */
2921
2922 NSS_EXTERN PRStatus
2923 nssGeneralNameSeq_AppendGeneralName
2924 (
2925   NSSGeneralNameSeq *generalNameSeq,
2926   NSSGeneralName *generalName
2927 );
2928
2929 /*
2930  * nssGeneralNameSeq_GetGeneralNameCount
2931  *
2932  * This routine returns the cardinality of the specified General name
2933  * Sequence.  This routine may return 0 upon error, in which case it
2934  * will have set an error on the error stack.
2935  *
2936  * The error may be one of the following values:
2937  *  NSS_ERROR_INVALID_GENERAL_NAME_SEQ
2938  *
2939  * Return value;
2940  *  0 upon error
2941  *  A positive number upon success
2942  */
2943
2944 NSS_EXTERN PRUint32
2945 nssGeneralNameSeq_GetGeneralNameCount
2946 (
2947   NSSGeneralNameSeq *generalNameSeq
2948 );
2949
2950 /*
2951  * nssGeneralNameSeq_GetGeneralName
2952  *
2953  * This routine returns a pointer to the i'th General Name in the
2954  * specified General Name Sequence.  The value of the variable 'i' is
2955  * on the range [0,c) where c is the cardinality returned from
2956  * NSSGeneralNameSeq_GetGeneralNameCount.  The caller owns the General
2957  * Name the pointer to which is returned.  If the optional arena
2958  * argument is non-null, the memory used will be obtained from that
2959  * arena; otherwise, the memory will be obtained from the heap.  This
2960  * routine may return NULL upon error, in which case it will have set
2961  * an error upon the error stack.
2962  *
2963  * The error may be one of the following values:
2964  *  NSS_ERROR_INVALID_GENERAL_NAME_SEQ
2965  *  NSS_ERROR_VALUE_OUT_OF_RANGE
2966  *  NSS_ERROR_NO_MEMORY
2967  *
2968  * Return value:
2969  *  NULL upon error
2970  *  A caller-owned pointer to a General Name.
2971  */
2972
2973 NSS_EXTERN NSSGeneralName *
2974 nssGeneralNameSeq_GetGeneralName
2975 (
2976   NSSGeneralNameSeq *generalNameSeq,
2977   NSSArena *arenaOpt,
2978   PRUint32 i
2979 );
2980
2981 /*
2982  * nssGeneralNameSeq_Compare
2983  *
2984  * This routine compares two General Name Sequences for equality.  For
2985  * two General Name Sequences to be equal, they must have the same
2986  * cardinality, and each General Name in one sequence must be equal to
2987  * the corresponding General Name in the other.  The result of the
2988  * comparison will be stored at the location pointed to by the "equalp"
2989  * variable, which must point to a valid PRBool.  This routine may
2990  * return PR_FAILURE upon error, in which case it will have set an
2991  * error on the error stack.
2992  *
2993  * The error may be one of the following values:
2994  *  NSS_ERROR_INVALID_GENERAL_NAME_SEQ
2995  *  NSS_ERROR_INVALID_ARGUMENT
2996  *
2997  * Return value:
2998  *  PR_FAILURE upon error
2999  *  PR_SUCCESS upon a successful comparison (equal or not)
3000  */
3001
3002 NSS_EXTERN PRStatus
3003 nssGeneralNameSeq_Compare
3004 (
3005   NSSGeneralNameSeq *generalNameSeq1,
3006   NSSGeneralNameSeq *generalNameSeq2,
3007   PRBool *equalp
3008 );
3009
3010 /*
3011  * nssGeneralNameSeq_Duplicate
3012  *
3013  * This routine duplicates the specified sequence of general names.  If
3014  * the optional arena argument is non-null, the memory required will be
3015  * obtained from that arena; otherwise, the memory will be obtained
3016  * from the heap.  This routine may return NULL upon error, in which
3017  * case it will have placed an error on the error stack.
3018  *
3019  * The error may be one of the following values:
3020  *  NSS_ERROR_INVALID_GENERAL_NAME_SEQ
3021  *  NSS_ERROR_NO_MEMORY
3022  *
3023  * Return value:
3024  *  NULL upon error
3025  *  A pointer to a new General Name Sequence.
3026  */
3027
3028 NSS_EXTERN NSSGeneralNameSeq *
3029 nssGeneralNameSeq_Duplicate
3030 (
3031   NSSGeneralNameSeq *generalNameSeq,
3032   NSSArena *arenaOpt
3033 );
3034
3035 PR_END_EXTERN_C
3036
3037 #endif /* PKI1_H */