| blob | ceafd4a26e0292ac784ac2af162896e34873da91 |
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 ***** */
37 #ifndef NSSPKI1_H
38 #define NSSPKI1_H
40 #ifdef DEBUG
41 static const char NSSPKI1_CVS_ID[] = "@(#) $RCSfile: nsspki1.h,v $ $Revision: 1.3 $ $Date: 2005/01/20 02:25:49 $";
44 /*
45 * nsspki1.h
46 *
47 * This file contains the prototypes of the public NSS routines
48 * dealing with the PKIX part-1 definitions.
49 */
51 #ifndef NSSBASET_H
55 #ifndef NSSPKI1T_H
59 #ifndef OIDDATA_H
63 PR_BEGIN_EXTERN_C
65 /*
66 * NSSOID
67 *
68 * The public "methods" regarding this "object" are:
69 *
70 * NSSOID_CreateFromBER -- constructor
71 * NSSOID_CreateFromUTF8 -- constructor
72 * (there is no explicit destructor)
73 *
74 * NSSOID_GetDEREncoding
75 * NSSOID_GetUTF8Encoding
76 */
80 /*
81 * NSSOID_CreateFromBER
82 *
83 * This routine creates an NSSOID by decoding a BER- or DER-encoded
84 * OID. It may return NSS_OID_UNKNOWN upon error, in which case it
85 * will have created an error stack.
86 *
87 * The error may be one of the following values:
88 * NSS_ERROR_INVALID_BER
89 * NSS_ERROR_NO_MEMORY
90 *
91 * Return value:
92 * NSS_OID_UNKNOWN upon error
93 * An NSSOID upon success
94 */
96 NSS_EXTERN NSSOID *
97 NSSOID_CreateFromBER
98 (
99 NSSBER *berOid
100 );
105 /*
106 * NSSOID_CreateFromUTF8
107 *
108 * This routine creates an NSSOID by decoding a UTF8 string
109 * representation of an OID in dotted-number format. The string may
110 * optionally begin with an octothorpe. It may return NSS_OID_UNKNOWN
111 * upon error, in which case it will have created an error stack.
112 *
113 * The error may be one of the following values:
114 * NSS_ERROR_INVALID_STRING
115 * NSS_ERROR_NO_MEMORY
116 *
117 * Return value:
118 * NSS_OID_UNKNOWN upon error
119 * An NSSOID upon success
120 */
122 NSS_EXTERN NSSOID *
123 NSSOID_CreateFromUTF8
124 (
125 NSSUTF8 *stringOid
126 );
131 /*
132 * NSSOID_GetDEREncoding
133 *
134 * This routine returns the DER encoding of the specified NSSOID.
135 * If the optional arena argument is non-null, the memory used will
136 * be obtained from that arena; otherwise, the memory will be obtained
137 * from the heap. This routine may return return null upon error, in
138 * which case it will have created an error stack.
139 *
140 * The error may be one of the following values:
141 * NSS_ERROR_INVALID_NSSOID
142 * NSS_ERROR_NO_MEMORY
143 *
144 * Return value:
145 * NULL upon error
146 * The DER encoding of this NSSOID
147 */
149 NSS_EXTERN NSSDER *
150 NSSOID_GetDEREncoding
151 (
154 NSSArena *arenaOpt
155 );
160 /*
161 * NSSOID_GetUTF8Encoding
162 *
163 * This routine returns a UTF8 string containing the dotted-number
164 * encoding of the specified NSSOID. If the optional arena argument
165 * is non-null, the memory used will be obtained from that arena;
166 * otherwise, the memory will be obtained from the heap. This routine
167 * may return null upon error, in which case it will have created an
168 * error stack.
169 *
170 * The error may be one of the following values:
171 * NSS_ERROR_INVALID_NSSOID
172 * NSS_ERROR_NO_MEMORY
173 *
174 * Return value:
175 * NULL upon error
176 * A pointer to a UTF8 string containing the dotted-digit encoding of
177 * this NSSOID
178 */
180 NSS_EXTERN NSSUTF8 *
181 NSSOID_GetUTF8Encoding
182 (
184 NSSArena *arenaOpt
185 );
190 /*
191 * NSSATAV
192 *
193 * The public "methods" regarding this "object" are:
194 *
195 * NSSATAV_CreateFromBER -- constructor
196 * NSSATAV_CreateFromUTF8 -- constructor
197 * NSSATAV_Create -- constructor
198 *
199 * NSSATAV_Destroy
200 * NSSATAV_GetDEREncoding
201 * NSSATAV_GetUTF8Encoding
202 * NSSATAV_GetType
203 * NSSATAV_GetValue
204 * NSSATAV_Compare
205 * NSSATAV_Duplicate
206 */
208 /*
209 * NSSATAV_CreateFromBER
210 *
211 * This routine creates an NSSATAV by decoding a BER- or DER-encoded
212 * ATAV. If the optional arena argument is non-null, the memory used
213 * will be obtained from that arena; otherwise, the memory will be
214 * obtained from the heap. This routine may return NULL upon error,
215 * in which case it will have created an error stack.
216 *
217 * The error may be one of the following values:
218 * NSS_ERROR_INVALID_BER
219 * NSS_ERROR_NO_MEMORY
220 *
221 * Return value:
222 * NULL upon error
223 * A pointer to an NSSATAV upon success
224 */
226 NSS_EXTERN NSSATAV *
227 NSSATAV_CreateFromBER
228 (
230 NSSBER *derATAV
231 );
236 /*
237 * NSSATAV_CreateFromUTF8
238 *
239 * This routine creates an NSSATAV by decoding a UTF8 string in the
240 * "equals" format, e.g., "c=US." If the optional arena argument is
241 * non-null, the memory used will be obtained from that arena;
242 * otherwise, the memory will be obtained from the heap. This routine
243 * may return NULL upon error, in which case it will have created an
244 * error stack.
245 *
246 * The error may be one of the following values:
247 * NSS_ERROR_UNKNOWN_ATTRIBUTE
248 * NSS_ERROR_INVALID_STRING
249 * NSS_ERROR_NO_MEMORY
250 *
251 * Return value:
252 * NULL upon error
253 * A pointer to an NSSATAV upon success
254 */
256 NSS_EXTERN NSSATAV *
257 NSSATAV_CreateFromUTF8
258 (
260 NSSUTF8 *stringATAV
261 );
267 /*
268 * NSSATAV_Create
269 *
270 * This routine creates an NSSATAV from the specified NSSOID and the
271 * specified data. If the optional arena argument is non-null, the
272 * memory used will be obtained from that arena; otherwise, the memory
273 * will be obtained from the heap.If the specified data length is zero,
274 * the data is assumed to be terminated by first zero byte; this allows
275 * UTF8 strings to be easily specified. This routine may return NULL
276 * upon error, in which case it will have created an error stack.
277 *
278 * The error may be one of the following values:
279 * NSS_ERROR_INVALID_ARENA
280 * NSS_ERROR_INVALID_NSSOID
281 * NSS_ERROR_INVALID_POINTER
282 * NSS_ERROR_NO_MEMORY
283 *
284 * Return value:
285 * NULL upon error
286 * A pointer to an NSSATAV upon success
287 */
289 NSS_EXTERN NSSATAV *
290 NSSATAV_Create
291 (
295 PRUint32 length
296 );
303 /*
304 * NSSATAV_Destroy
305 *
306 * This routine will destroy an ATAV object. It should eventually be
307 * called on all ATAVs created without an arena. While it is not
308 * necessary to call it on ATAVs created within an arena, it is not an
309 * error to do so. This routine returns a PRStatus value; if
310 * successful, it will return PR_SUCCESS. If unsuccessful, it will
311 * create an error stack and return PR_FAILURE.
312 *
313 * The error may be one of the following values:
314 * NSS_ERROR_INVALID_ATAV
315 *
316 * Return value:
317 * PR_FAILURE upon error
318 * PR_SUCCESS upon success
319 */
321 NSS_EXTERN PRStatus
322 NSSATAV_Destroy
323 (
324 NSSATAV *atav
325 );
329 /*
330 * NSSATAV_GetDEREncoding
331 *
332 * This routine will DER-encode an ATAV object. If the optional arena
333 * argument is non-null, the memory used will be obtained from that
334 * arena; otherwise, the memory will be obtained from the heap. This
335 * routine may return null upon error, in which case it will have
336 * created an error stack.
337 *
338 * The error may be one of the following values:
339 * NSS_ERROR_INVALID_ATAV
340 * NSS_ERROR_NO_MEMORY
341 *
342 * Return value:
343 * NULL upon error
344 * The DER encoding of this NSSATAV
345 */
347 NSS_EXTERN NSSDER *
348 NSSATAV_GetDEREncoding
349 (
351 NSSArena *arenaOpt
352 );
357 /*
358 * NSSATAV_GetUTF8Encoding
359 *
360 * This routine returns a UTF8 string containing a string
361 * representation of the ATAV in "equals" notation (e.g., "o=Acme").
362 * If the optional arena argument is non-null, the memory used will be
363 * obtained from that arena; otherwise, the memory will be obtained
364 * from the heap. This routine may return null upon error, in which
365 * case it will have created an error stack.
366 *
367 * The error may be one of the following values:
368 * NSS_ERROR_INVALID_ATAV
369 * NSS_ERROR_NO_MEMORY
370 *
371 * Return value:
372 * NULL upon error
373 * A pointer to a UTF8 string containing the "equals" encoding of the
374 * ATAV
375 */
377 NSS_EXTERN NSSUTF8 *
378 NSSATAV_GetUTF8Encoding
379 (
381 NSSArena *arenaOpt
382 );
387 /*
388 * NSSATAV_GetType
389 *
390 * This routine returns the NSSOID corresponding to the attribute type
391 * in the specified ATAV. This routine may return NSS_OID_UNKNOWN
392 * upon error, in which case it will have created an error stack.
393 *
394 * The error may be one of the following values:
395 * NSS_ERROR_INVALID_ATAV
396 *
397 * Return value:
398 * NSS_OID_UNKNOWN upon error
399 * An element of enum NSSOIDenum upon success
400 */
403 NSSATAV_GetType
404 (
405 NSSATAV *atav
406 );
410 /*
411 * NSSATAV_GetValue
412 *
413 * This routine returns an NSSItem containing the attribute value
414 * in the specified ATAV. If the optional arena argument is non-null,
415 * the memory used will be obtained from that arena; otherwise, the
416 * memory will be obtained from the heap. This routine may return
417 * NULL upon error, in which case it will have created an error stack.
418 *
419 * The error may be one of the following values:
420 * NSS_ERROR_INVALID_ATAV
421 * NSS_ERROR_NO_MEMORY
422 *
423 * Return value:
424 * NULL upon error
425 * A pointer to an NSSItem containing the attribute value.
426 */
428 NSS_EXTERN NSSUTF8 *
429 NSSATAV_GetValue
430 (
432 NSSArena *arenaOpt
433 );
438 /*
439 * NSSATAV_Compare
440 *
441 * This routine compares two ATAVs for equality. For two ATAVs to be
442 * equal, the attribute types must be the same, and the attribute
443 * values must have equal length and contents. The result of the
444 * comparison will be stored at the location pointed to by the "equalp"
445 * variable, which must point to a valid PRBool. This routine may
446 * return PR_FAILURE upon error, in which case it will have created an
447 * error stack.
448 *
449 * The error may be one of the following values:
450 * NSS_ERROR_INVALID_ATAV
451 * NSS_ERROR_INVALID_ARGUMENT
452 *
453 * Return value:
454 * PR_FAILURE on error
455 * PR_SUCCESS upon a successful comparison (equal or not)
456 */
458 NSS_EXTERN PRStatus
459 NSSATAV_Compare
460 (
463 PRBool *equalp
464 );
469 /*
470 * NSSATAV_Duplicate
471 *
472 * This routine duplicates the specified ATAV. If the optional arena
473 * argument is non-null, the memory required will be obtained from
474 * that arena; otherwise, the memory will be obtained from the heap.
475 * This routine may return NULL upon error, in which case it will have
476 * created an error stack.
477 *
478 * The error may be one of the following values:
479 * NSS_ERROR_INVALID_ATAV
480 * NSS_ERROR_NO_MEMORY
481 *
482 * Return value:
483 * NULL on error
484 * A pointer to a new ATAV
485 */
487 NSS_EXTERN NSSATAV *
488 NSSATAV_Duplicate
489 (
491 NSSArena *arenaOpt
492 );
497 /*
498 * NSSRDN
499 *
500 * The public "methods" regarding this "object" are:
501 *
502 * NSSRDN_CreateFromBER -- constructor
503 * NSSRDN_CreateFromUTF8 -- constructor
504 * NSSRDN_Create -- constructor
505 * NSSRDN_CreateSimple -- constructor
506 *
507 * NSSRDN_Destroy
508 * NSSRDN_GetDEREncoding
509 * NSSRDN_GetUTF8Encoding
510 * NSSRDN_AddATAV
511 * NSSRDN_GetATAVCount
512 * NSSRDN_GetATAV
513 * NSSRDN_GetSimpleATAV
514 * NSSRDN_Compare
515 * NSSRDN_Duplicate
516 */
518 /*
519 * NSSRDN_CreateFromBER
520 *
521 * This routine creates an NSSRDN by decoding a BER- or DER-encoded
522 * RDN. If the optional arena argument is non-null, the memory used
523 * will be obtained from that arena; otherwise, the memory will be
524 * obtained from the heap. This routine may return NULL upon error,
525 * in which case it will have created an error stack.
526 *
527 * The error may be one of the following values:
528 * NSS_ERROR_INVALID_BER
529 * NSS_ERROR_NO_MEMORY
530 *
531 * Return value:
532 * NULL upon error
533 * A pointer to an NSSRDN upon success
534 */
536 NSS_EXTERN NSSRDN *
537 NSSRDN_CreateFromBER
538 (
540 NSSBER *berRDN
541 );
543 /*
544 * NSSRDN_CreateFromUTF8
545 *
546 * This routine creates an NSSRDN by decoding an UTF8 string
547 * consisting of either a single ATAV in the "equals" format, e.g.,
548 * "uid=smith," or one or more such ATAVs in parentheses, e.g.,
549 * "(sn=Smith,ou=Sales)." If the optional arena argument is non-null,
550 * the memory used will be obtained from that arena; otherwise, the
551 * memory will be obtained from the heap. This routine may return
552 * NULL upon error, in which case it will have created an error stack.
553 *
554 * The error may be one of the following values:
555 * NSS_ERROR_UNKNOWN_ATTRIBUTE
556 * NSS_ERROR_INVALID_STRING
557 * NSS_ERROR_NO_MEMORY
558 *
559 * Return value:
560 * NULL upon error
561 * A pointer to an NSSRDN upon success
562 */
564 NSS_EXTERN NSSRDN *
565 NSSRDN_CreateFromUTF8
566 (
568 NSSUTF8 *stringRDN
569 );
571 /*
572 * NSSRDN_Create
573 *
574 * This routine creates an NSSRDN from one or more NSSATAVs. The
575 * final argument to this routine must be NULL. If the optional arena
576 * argument is non-null, the memory used will be obtained from that
577 * arena; otherwise, the memory will be obtained from the heap. This
578 * routine may return NULL upon error, in which case it will have
579 * created an error stack.
580 *
581 * The error may be one of the following values:
582 * NSS_ERROR_NO_MEMORY
583 * NSS_ERROR_INVALID_ATAV
584 *
585 * Return value:
586 * NULL upon error
587 * A pointer to an NSSRDN upon success
588 */
590 NSS_EXTERN NSSRDN *
591 NSSRDN_Create
592 (
595 ...
596 );
598 /*
599 * NSSRDN_CreateSimple
600 *
601 * This routine creates a simple NSSRDN from a single NSSATAV. If the
602 * optional arena argument is non-null, the memory used will be
603 * obtained from that arena; otherwise, the memory will be obtained
604 * from the heap. This routine may return NULL upon error, in which
605 * case it will have created an error stack.
606 *
607 * The error may be one of the following values:
608 * NSS_ERROR_NO_MEMORY
609 * NSS_ERROR_INVALID_ATAV
610 *
611 * Return value:
612 * NULL upon error
613 * A pointer to an NSSRDN upon success
614 */
616 NSS_EXTERN NSSRDN *
617 NSSRDN_CreateSimple
618 (
620 NSSATAV *atav
621 );
623 /*
624 * NSSRDN_Destroy
625 *
626 * This routine will destroy an RDN object. It should eventually be
627 * called on all RDNs created without an arena. While it is not
628 * necessary to call it on RDNs created within an arena, it is not an
629 * error to do so. This routine returns a PRStatus value; if
630 * successful, it will return PR_SUCCESS. If unsuccessful, it will
631 * create an error stack and return PR_FAILURE.
632 *
633 * The error may be one of the following values:
634 * NSS_ERROR_INVALID_RDN
635 *
636 * Return value:
637 * PR_FAILURE upon failure
638 * PR_SUCCESS upon success
639 */
641 NSS_EXTERN PRStatus
642 NSSRDN_Destroy
643 (
644 NSSRDN *rdn
645 );
647 /*
648 * NSSRDN_GetDEREncoding
649 *
650 * This routine will DER-encode an RDN object. If the optional arena
651 * argument is non-null, the memory used will be obtained from that
652 * arena; otherwise, the memory will be obtained from the heap. This
653 * routine may return null upon error, in which case it will have
654 * created an error stack.
655 *
656 * The error may be one of the following values:
657 * NSS_ERROR_INVALID_RDN
658 * NSS_ERROR_NO_MEMORY
659 *
660 * Return value:
661 * NULL upon error
662 * The DER encoding of this NSSRDN
663 */
665 NSS_EXTERN NSSDER *
666 NSSRDN_GetDEREncoding
667 (
669 NSSArena *arenaOpt
670 );
672 /*
673 * NSSRDN_GetUTF8Encoding
674 *
675 * This routine returns a UTF8 string containing a string
676 * representation of the RDN. A simple (one-ATAV) RDN will be simply
677 * the string representation of that ATAV; a non-simple RDN will be in
678 * parenthesised form. If the optional arena argument is non-null,
679 * the memory used will be obtained from that arena; otherwise, the
680 * memory will be obtained from the heap. This routine may return
681 * null upon error, in which case it will have created an error stack.
682 *
683 * The error may be one of the following values:
684 * NSS_ERROR_INVALID_RDN
685 * NSS_ERROR_NO_MEMORY
686 *
687 * Return value:
688 * NULL upon error
689 * A pointer to a UTF8 string
690 */
692 NSS_EXTERN NSSUTF8 *
693 NSSRDN_GetUTF8Encoding
694 (
696 NSSArena *arenaOpt
697 );
699 /*
700 * NSSRDN_AddATAV
701 *
702 * This routine adds an ATAV to the set of ATAVs in the specified RDN.
703 * Remember that RDNs consist of an unordered set of ATAVs. If the
704 * RDN was created with a non-null arena argument, that same arena
705 * will be used for any additional required memory. If the RDN was
706 * created with a NULL arena argument, any additional memory will
707 * be obtained from the heap. This routine returns a PRStatus value;
708 * it will return PR_SUCCESS upon success, and upon failure it will
709 * create an error stack and return PR_FAILURE.
710 *
711 * The error may be one of the following values:
712 * NSS_ERROR_INVALID_RDN
713 * NSS_ERROR_INVALID_ATAV
714 * NSS_ERROR_NO_MEMORY
715 *
716 * Return value:
717 * PR_SUCCESS upon success
718 * PR_FAILURE upon failure
719 */
721 NSS_EXTERN PRStatus
722 NSSRDN_AddATAV
723 (
725 NSSATAV *atav
726 );
728 /*
729 * NSSRDN_GetATAVCount
730 *
731 * This routine returns the cardinality of the set of ATAVs within
732 * the specified RDN. This routine may return 0 upon error, in which
733 * case it will have created an error stack.
734 *
735 * The error may be one of the following values:
736 * NSS_ERROR_INVALID_RDN
737 *
738 * Return value:
739 * 0 upon error
740 * A positive number upon success
741 */
743 NSS_EXTERN PRUint32
744 NSSRDN_GetATAVCount
745 (
746 NSSRDN *rdn
747 );
749 /*
750 * NSSRDN_GetATAV
751 *
752 * This routine returns a pointer to an ATAV that is a member of
753 * the set of ATAVs within the specified RDN. While the set of
754 * ATAVs within an RDN is unordered, this routine will return
755 * distinct values for distinct values of 'i' as long as the RDN
756 * is not changed in any way. The RDN may be changed by calling
757 * NSSRDN_AddATAV. The value of the variable 'i' is on the range
758 * [0,c) where c is the cardinality returned from NSSRDN_GetATAVCount.
759 * The caller owns the ATAV the pointer to which is returned. If the
760 * optional arena argument is non-null, the memory used will be
761 * obtained from that arena; otherwise, the memory will be obtained
762 * from the heap. This routine may return NULL upon error, in which
763 * case it will have created an error stack.
764 *
765 * The error may be one of the following values:
766 * NSS_ERROR_INVALID_RDN
767 * NSS_ERROR_VALUE_OUT_OF_RANGE
768 * NSS_ERROR_NO_MEMORY
769 *
770 * Return value:
771 * NULL upon error
772 * A caller-owned pointer to an NSSATAV
773 */
775 NSS_EXTERN NSSATAV *
776 NSSRDN_GetATAV
777 (
780 PRUint32 i
781 );
783 /*
784 * NSSRDN_GetSimpleATAV
785 *
786 * Most RDNs are actually very simple, with a single ATAV. This
787 * routine will return the single ATAV from such an RDN. The caller
788 * owns the ATAV the pointer to which is returned. If the optional
789 * arena argument is non-null, the memory used will be obtained from
790 * that arena; otherwise, the memory will be obtained from the heap.
791 * This routine may return NULL upon error, including the case where
792 * the set of ATAVs in the RDN is nonsingular. Upon error, this
793 * routine will have created an error stack.
794 *
795 * The error may be one of the following values:
796 * NSS_ERROR_INVALID_RDN
797 * NSS_ERROR_RDN_NOT_SIMPLE
798 * NSS_ERROR_NO_MEMORY
799 *
800 * Return value:
801 * NULL upon error
802 * A caller-owned pointer to an NSSATAV
803 */
805 NSS_EXTERN NSSATAV *
806 NSSRDN_GetSimpleATAV
807 (
809 NSSArena *arenaOpt
810 );
812 /*
813 * NSSRDN_Compare
814 *
815 * This routine compares two RDNs for equality. For two RDNs to be
816 * equal, they must have the same number of ATAVs, and every ATAV in
817 * one must be equal to an ATAV in the other. (Note that the sets
818 * of ATAVs are unordered.) The result of the comparison will be
819 * stored at the location pointed to by the "equalp" variable, which
820 * must point to a valid PRBool. This routine may return PR_FAILURE
821 * upon error, in which case it will have created an error stack.
822 *
823 * The error may be one of the following values:
824 * NSS_ERROR_INVALID_RDN
825 * NSS_ERROR_INVALID_ARGUMENT
826 *
827 * Return value:
828 * PR_FAILURE on error
829 * PR_SUCCESS upon a successful comparison (equal or not)
830 */
832 NSS_EXTERN PRStatus
833 NSSRDN_Compare
834 (
837 PRBool *equalp
838 );
840 /*
841 * NSSRDN_Duplicate
842 *
843 * This routine duplicates the specified RDN. If the optional arena
844 * argument is non-null, the memory required will be obtained from
845 * that arena; otherwise, the memory will be obtained from the heap.
846 * This routine may return NULL upon error, in which case it will have
847 * created an error stack.
848 *
849 * The error may be one of the following values:
850 * NSS_ERROR_INVALID_RDN
851 * NSS_ERROR_NO_MEMORY
852 *
853 * Return value:
854 * NULL on error
855 * A pointer to a new RDN
856 */
858 NSS_EXTERN NSSRDN *
859 NSSRDN_Duplicate
860 (
862 NSSArena *arenaOpt
863 );
865 /*
866 * NSSRDNSeq
867 *
868 * The public "methods" regarding this "object" are:
869 *
870 * NSSRDNSeq_CreateFromBER -- constructor
871 * NSSRDNSeq_CreateFromUTF8 -- constructor
872 * NSSRDNSeq_Create -- constructor
873 *
874 * NSSRDNSeq_Destroy
875 * NSSRDNSeq_GetDEREncoding
876 * NSSRDNSeq_GetUTF8Encoding
877 * NSSRDNSeq_AppendRDN
878 * NSSRDNSeq_GetRDNCount
879 * NSSRDNSeq_GetRDN
880 * NSSRDNSeq_Compare
881 * NSSRDNSeq_Duplicate
882 */
884 /*
885 * NSSRDNSeq_CreateFromBER
886 *
887 * This routine creates an NSSRDNSeq by decoding a BER- or DER-encoded
888 * sequence of RDNs. If the optional arena argument is non-null,
889 * the memory used will be obtained from that arena; otherwise, the
890 * memory will be obtained from the heap. This routine may return
891 * NULL upon error, in which case it will have created an error stack.
892 *
893 * The error may be one of the following values:
894 * NSS_ERROR_INVALID_BER
895 * NSS_ERROR_NO_MEMORY
896 *
897 * Return value:
898 * NULL upon error
899 * A pointer to an NSSRDNSeq upon success
900 */
902 NSS_EXTERN NSSRDNSeq *
903 NSSRDNSeq_CreateFromBER
904 (
906 NSSBER *berRDNSeq
907 );
909 /*
910 * NSSRDNSeq_CreateFromUTF8
911 *
912 * This routine creates an NSSRDNSeq by decoding a UTF8 string
913 * consisting of a comma-separated sequence of RDNs, such as
914 * "(sn=Smith,ou=Sales),o=Acme,c=US." If the optional arena argument
915 * is non-null, the memory used will be obtained from that arena;
916 * otherwise, the memory will be obtained from the heap. This routine
917 * may return NULL upon error, in which case it will have created an
918 * error stack.
919 *
920 * The error may be one of the following values:
921 * NSS_ERROR_UNKNOWN_ATTRIBUTE
922 * NSS_ERROR_INVALID_STRING
923 * NSS_ERROR_NO_MEMORY
924 *
925 * Return value:
926 * NULL upon error
927 * A pointer to an NSSRDNSeq upon success
928 */
930 NSS_EXTERN NSSRDNSeq *
931 NSSRDNSeq_CreateFromUTF8
932 (
934 NSSUTF8 *stringRDNSeq
935 );
937 /*
938 * NSSRDNSeq_Create
939 *
940 * This routine creates an NSSRDNSeq from one or more NSSRDNs. The
941 * final argument to this routine must be NULL. If the optional arena
942 * argument is non-null, the memory used will be obtained from that
943 * arena; otherwise, the memory will be obtained from the heap. This
944 * routine may return NULL upon error, in which case it will have
945 * created an error stack.
946 *
947 * The error may be one of the following values:
948 * NSS_ERROR_NO_MEMORY
949 * NSS_ERROR_INVALID_RDN
950 *
951 * Return value:
952 * NULL upon error
953 * A pointero to an NSSRDNSeq upon success
954 */
956 NSS_EXTERN NSSRDNSeq *
957 NSSRDNSeq_Create
958 (
961 ...
962 );
964 /*
965 * NSSRDNSeq_Destroy
966 *
967 * This routine will destroy an RDNSeq object. It should eventually
968 * be called on all RDNSeqs created without an arena. While it is not
969 * necessary to call it on RDNSeqs created within an arena, it is not
970 * an error to do so. This routine returns a PRStatus value; if
971 * successful, it will return PR_SUCCESS. If unsuccessful, it will
972 * create an error stack and return PR_FAILURE.
973 *
974 * The error may be one of the following values:
975 * NSS_ERROR_INVALID_RDNSEQ
976 *
977 * Return value:
978 * PR_FAILURE upon error
979 * PR_SUCCESS upon success
980 */
982 NSS_EXTERN PRStatus
983 NSSRDNSeq_Destroy
984 (
985 NSSRDNSeq *rdnseq
986 );
988 /*
989 * NSSRDNSeq_GetDEREncoding
990 *
991 * This routine will DER-encode an RDNSeq object. If the optional
992 * arena argument is non-null, the memory used will be obtained from
993 * that arena; otherwise, the memory will be obtained from the heap.
994 * This routine may return null upon error, in which case it will have
995 * created an error stack.
996 *
997 * The error may be one of the following values:
998 * NSS_ERROR_INVALID_RDNSEQ
999 * NSS_ERROR_NO_MEMORY
1000 *
1001 * Return value:
1002 * NULL upon error
1003 * The DER encoding of this NSSRDNSeq
1004 */
1006 NSS_EXTERN NSSDER *
1007 NSSRDNSeq_GetDEREncoding
1008 (
1010 NSSArena *arenaOpt
1011 );
1013 /*
1014 * NSSRDNSeq_GetUTF8Encoding
1015 *
1016 * This routine returns a UTF8 string containing a string
1017 * representation of the RDNSeq as a comma-separated sequence of RDNs.
1018 * If the optional arena argument is non-null, the memory used will be
1019 * obtained from that arena; otherwise, the memory will be obtained
1020 * from the heap. This routine may return null upon error, in which
1021 * case it will have created an error stack.
1022 *
1023 * The error may be one of the following values:
1024 * NSS_ERROR_INVALID_RDNSEQ
1025 * NSS_ERROR_NO_MEMORY
1026 *
1027 * Return value:
1028 * NULL upon error
1029 * A pointer to the UTF8 string
1030 */
1032 NSS_EXTERN NSSUTF8 *
1033 NSSRDNSeq_GetUTF8Encoding
1034 (
1036 NSSArena *arenaOpt
1037 );
1039 /*
1040 * NSSRDNSeq_AppendRDN
1041 *
1042 * This routine appends an RDN to the end of the existing RDN
1043 * sequence. If the RDNSeq was created with a non-null arena
1044 * argument, that same arena will be used for any additional required
1045 * memory. If the RDNSeq was created with a NULL arena argument, any
1046 * additional memory will be obtained from the heap. This routine
1047 * returns a PRStatus value; it will return PR_SUCCESS upon success,
1048 * and upon failure it will create an error stack and return PR_FAILURE.
1049 *
1050 * The error may be one of the following values:
1051 * NSS_ERROR_INVALID_RDNSEQ
1052 * NSS_ERROR_INVALID_RDN
1053 * NSS_ERROR_NO_MEMORY
1054 *
1055 * Return value:
1056 * PR_SUCCESS upon success
1057 * PR_FAILURE upon failure
1058 */
1060 NSS_EXTERN PRStatus
1061 NSSRDNSeq_AppendRDN
1062 (
1064 NSSRDN *rdn
1065 );
1067 /*
1068 * NSSRDNSeq_GetRDNCount
1069 *
1070 * This routine returns the cardinality of the sequence of RDNs within
1071 * the specified RDNSeq. This routine may return 0 upon error, in
1072 * which case it will have created an error stack.
1073 *
1074 * The error may be one of the following values:
1075 * NSS_ERROR_INVALID_RDNSEQ
1076 *
1077 * Return value:
1078 * 0 upon error
1079 * A positive number upon success
1080 */
1082 NSS_EXTERN PRUint32
1083 NSSRDNSeq_GetRDNCount
1084 (
1085 NSSRDNSeq *rdnseq
1086 );
1088 /*
1089 * NSSRDNSeq_GetRDN
1090 *
1091 * This routine returns a pointer to the i'th RDN in the sequence of
1092 * RDNs that make up the specified RDNSeq. The sequence begins with
1093 * the top-level (e.g., "c=US") RDN. The value of the variable 'i'
1094 * is on the range [0,c) where c is the cardinality returned from
1095 * NSSRDNSeq_GetRDNCount. The caller owns the RDN the pointer to which
1096 * is returned. If the optional arena argument is non-null, the memory
1097 * used will be obtained from that areana; otherwise, the memory will
1098 * be obtained from the heap. This routine may return NULL upon error,
1099 * in which case it will have created an error stack. Note that the
1100 * usual string representation of RDN Sequences is from last to first.
1101 *
1102 * The error may be one of the following values:
1103 * NSS_ERROR_INVALID_RDNSEQ
1104 * NSS_ERROR_VALUE_OUT_OF_RANGE
1105 * NSS_ERROR_NO_MEMORY
1106 *
1107 * Return value:
1108 * NULL upon error
1109 * A caller-owned pointer to an NSSRDN
1110 */
1112 NSS_EXTERN NSSRDN *
1113 NSSRDNSeq_GetRDN
1114 (
1117 PRUint32 i
1118 );
1120 /*
1121 * NSSRDNSeq_Compare
1122 *
1123 * This routine compares two RDNSeqs for equality. For two RDNSeqs to
1124 * be equal, they must have the same number of RDNs, and each RDN in
1125 * one sequence must be equal to the corresponding RDN in the other
1126 * sequence. The result of the comparison will be stored at the
1127 * location pointed to by the "equalp" variable, which must point to a
1128 * valid PRBool. This routine may return PR_FAILURE upon error, in
1129 * which case it will have created an error stack.
1130 *
1131 * The error may be one of the following values:
1132 * NSS_ERROR_INVALID_RDNSEQ
1133 * NSS_ERROR_INVALID_ARGUMENT
1134 *
1135 * Return value:
1136 * PR_FAILURE on error
1137 * PR_SUCCESS upon a successful comparison (equal or not)
1138 */
1140 NSS_EXTERN PRStatus
1141 NSSRDNSeq_Compare
1142 (
1145 PRBool *equalp
1146 );
1148 /*
1149 * NSSRDNSeq_Duplicate
1150 *
1151 * This routine duplicates the specified RDNSeq. If the optional arena
1152 * argument is non-null, the memory required will be obtained from that
1153 * arena; otherwise, the memory will be obtained from the heap. This
1154 * routine may return NULL upon error, in which case it will have
1155 * created an error stack.
1156 *
1157 * The error may be one of the following values:
1158 * NSS_ERROR_INVALID_RDNSEQ
1159 * NSS_ERROR_NO_MEMORY
1160 *
1161 * Return value:
1162 * NULL upon error
1163 * A pointer to a new RDNSeq
1164 */
1166 NSS_EXTERN NSSRDNSeq *
1167 NSSRDNSeq_Duplicate
1168 (
1170 NSSArena *arenaOpt
1171 );
1173 /*
1174 * NSSName
1175 *
1176 * The public "methods" regarding this "object" are:
1177 *
1178 * NSSName_CreateFromBER -- constructor
1179 * NSSName_CreateFromUTF8 -- constructor
1180 * NSSName_Create -- constructor
1181 *
1182 * NSSName_Destroy
1183 * NSSName_GetDEREncoding
1184 * NSSName_GetUTF8Encoding
1185 * NSSName_GetChoice
1186 * NSSName_GetRDNSequence
1187 * NSSName_GetSpecifiedChoice
1188 * NSSName_Compare
1189 * NSSName_Duplicate
1190 *
1191 * NSSName_GetUID
1192 * NSSName_GetEmail
1193 * NSSName_GetCommonName
1194 * NSSName_GetOrganization
1195 * NSSName_GetOrganizationalUnits
1196 * NSSName_GetStateOrProvince
1197 * NSSName_GetLocality
1198 * NSSName_GetCountry
1199 * NSSName_GetAttribute
1200 */
1202 /*
1203 * NSSName_CreateFromBER
1204 *
1205 * This routine creates an NSSName by decoding a BER- or DER-encoded
1206 * (directory) Name. If the optional arena argument is non-null,
1207 * the memory used will be obtained from that arena; otherwise,
1208 * the memory will be obtained from the heap. This routine may
1209 * return NULL upon error, in which case it will have created an error
1210 * stack.
1211 *
1212 * The error may be one of the following values:
1213 * NSS_ERROR_INVALID_BER
1214 * NSS_ERROR_NO_MEMORY
1215 *
1216 * Return value:
1217 * NULL upon error
1218 * A pointer to an NSSName upon success
1219 */
1221 NSS_EXTERN NSSName *
1222 NSSName_CreateFromBER
1223 (
1225 NSSBER *berName
1226 );
1228 /*
1229 * NSSName_CreateFromUTF8
1230 *
1231 * This routine creates an NSSName by decoding a UTF8 string
1232 * consisting of the string representation of one of the choices of
1233 * (directory) names. Currently the only choice is an RDNSeq. If the
1234 * optional arena argument is non-null, the memory used will be
1235 * obtained from that arena; otherwise, the memory will be obtained
1236 * from the heap. The routine may return NULL upon error, in which
1237 * case it will have created an error stack.
1238 *
1239 * The error may be one of the following values:
1240 * NSS_ERROR_INVALID_STRING
1241 * NSS_ERROR_NO_MEMORY
1242 *
1243 * Return value:
1244 * NULL upon error
1245 * A pointer to an NSSName upon success
1246 */
1248 NSS_EXTERN NSSName *
1249 NSSName_CreateFromUTF8
1250 (
1252 NSSUTF8 *stringName
1253 );
1255 /*
1256 * NSSName_Create
1257 *
1258 * This routine creates an NSSName with the specified choice of
1259 * underlying name types. The value of the choice variable must be
1260 * one of the values of the NSSNameChoice enumeration, and the type
1261 * of the arg variable must be as specified in the following table:
1262 *
1263 * Choice Type
1264 * ======================== ===========
1265 * NSSNameChoiceRdnSequence NSSRDNSeq *
1266 *
1267 * If the optional arena argument is non-null, the memory used will
1268 * be obtained from that arena; otherwise, the memory will be
1269 * obtained from the heap. This routine may return NULL upon error,
1270 * in which case it will have created an error stack.
1271 *
1272 * The error may be one of the following values:
1273 * NSS_ERROR_INVALID_CHOICE
1274 * NSS_ERROR_INVALID_ARGUMENT
1275 * NSS_ERROR_NO_MEMORY
1276 *
1277 * Return value:
1278 * NULL upon error
1279 * A pointer to an NSSName upon success
1280 */
1282 NSS_EXTERN NSSName *
1283 NSSName_Create
1284 (
1286 NSSNameChoice choice,
1288 );
1290 /*
1291 * NSSName_Destroy
1292 *
1293 * This routine will destroy a Name object. It should eventually be
1294 * called on all Names created without an arena. While it is not
1295 * necessary to call it on Names created within an arena, it is not
1296 * an error to do so. This routine returns a PRStatus value; if
1297 * successful, it will return PR_SUCCESS. If unsuccessful, it will
1298 * create an error stack and return PR_FAILURE.
1299 *
1300 * The error may be one of the following values:
1301 * NSS_ERROR_INVALID_NAME
1302 *
1303 * Return value:
1304 * PR_FAILURE upon error
1305 * PR_SUCCESS upon success
1306 */
1308 NSS_EXTERN PRStatus
1309 NSSName_Destroy
1310 (
1311 NSSName *name
1312 );
1314 /*
1315 * NSSName_GetDEREncoding
1316 *
1317 * This routine will DER-encode a name object. If the optional arena
1318 * argument is non-null, the memory used will be obtained from that
1319 * arena; otherwise, the memory will be obtained from the heap. This
1320 * routine may return null upon error, in which case it will have
1321 * created an error stack.
1322 *
1323 * The error may be one of the following values:
1324 * NSS_ERROR_INVALID_NAME
1325 * NSS_ERROR_NO_MEMORY
1326 *
1327 * Return value:
1328 * NULL upon error
1329 * The DER encoding of this NSSName
1330 */
1332 NSS_EXTERN NSSDER *
1333 NSSName_GetDEREncoding
1334 (
1336 NSSArena *arenaOpt
1337 );
1339 /*
1340 * NSSName_GetUTF8Encoding
1341 *
1342 * This routine returns a UTF8 string containing a string
1343 * representation of the Name in the format specified by the
1344 * underlying name choice. If the optional arena argument is non-null,
1345 * the memory used will be obtained from that arena; otherwise, the
1346 * memory will be obtained from the heap. This routine may return
1347 * NULL upon error, in which case it will have created an error stack.
1348 *
1349 * The error may be one of the following values:
1350 * NSS_ERROR_INVALID_NAME
1351 * NSS_ERROR_NO_MEMORY
1352 *
1353 * Return value:
1354 * NULL upon error
1355 * A pointer to the UTF8 string
1356 */
1358 NSS_EXTERN NSSUTF8 *
1359 NSSName_GetUTF8Encoding
1360 (
1362 NSSArena *arenaOpt
1363 );
1365 /*
1366 * NSSName_GetChoice
1367 *
1368 * This routine returns the type of the choice underlying the specified
1369 * name. The return value will be a member of the NSSNameChoice
1370 * enumeration. This routine may return NSSNameChoiceInvalid upon
1371 * error, in which case it will have created an error stack.
1372 *
1373 * The error may be one of the following values:
1374 * NSS_ERROR_INVALID_NAME
1375 *
1376 * Return value:
1377 * NSSNameChoiceInvalid upon error
1378 * An other member of the NSSNameChoice enumeration upon success
1379 */
1381 NSS_EXTERN NSSNameChoice
1382 NSSName_GetChoice
1383 (
1384 NSSName *name
1385 );
1387 /*
1388 * NSSName_GetRDNSequence
1389 *
1390 * If the choice underlying the specified NSSName is that of an
1391 * RDNSequence, this routine will return a pointer to that RDN
1392 * sequence. Otherwise, this routine will place an error on the
1393 * error stack, and return NULL. If the optional arena argument is
1394 * non-null, the memory required will be obtained from that arena;
1395 * otherwise, the memory will be obtained from the heap. The
1396 * caller owns the returned pointer. This routine may return NULL
1397 * upon error, in which case it will have created an error stack.
1398 *
1399 * The error may be one of the following values:
1400 * NSS_ERROR_INVALID_NAME
1401 * NSS_ERROR_WRONG_CHOICE
1402 * NSS_ERROR_NO_MEMORY
1403 *
1404 * Return value:
1405 * NULL upon error
1406 * A caller-owned pointer to an NSSRDNSeq
1407 */
1409 NSS_EXTERN NSSRDNSeq *
1410 NSSName_GetRDNSequence
1411 (
1413 NSSArena *arenaOpt
1414 );
1416 /*
1417 * NSSName_GetSpecifiedChoice
1418 *
1419 * If the choice underlying the specified NSSName matches the specified
1420 * choice, a caller-owned pointer to that underlying object will be
1421 * returned. Otherwise, an error will be placed on the error stack and
1422 * NULL will be returned. If the optional arena argument is non-null,
1423 * the memory required will be obtained from that arena; otherwise, the
1424 * memory will be obtained from the heap. The caller owns the returned
1425 * pointer. This routine may return NULL upon error, in which case it
1426 * will have created an error stack.
1427 *
1428 * The error may be one of the following values:
1429 * NSS_ERROR_INVALID_NAME
1430 * NSS_ERROR_WRONG_CHOICE
1431 * NSS_ERROR_NO_MEMORY
1432 *
1433 * Return value:
1434 * NULL upon error
1435 * A caller-owned pointer, which must be typecast
1436 */
1439 NSSName_GetSpecifiedChoice
1440 (
1442 NSSNameChoice choice,
1443 NSSArena *arenaOpt
1444 );
1446 /*
1447 * NSSName_Compare
1448 *
1449 * This routine compares two Names for equality. For two Names to be
1450 * equal, they must have the same choice of underlying types, and the
1451 * underlying values must be equal. The result of the comparison will
1452 * be stored at the location pointed to by the "equalp" variable, which
1453 * must point to a valid PRBool. This routine may return PR_FAILURE
1454 * upon error, in which case it will have created an error stack.
1455 *
1456 * The error may be one of the following values:
1457 * NSS_ERROR_INVALID_NAME
1458 * NSS_ERROR_INVALID_ARGUMENT
1459 *
1460 * Return value:
1461 * PR_FAILURE on error
1462 * PR_SUCCESS upon a successful comparison (equal or not)
1463 */
1465 NSS_EXTERN PRStatus
1466 NSSName_Compare
1467 (
1470 PRBool *equalp
1471 );
1473 /*
1474 * NSSName_Duplicate
1475 *
1476 * This routine duplicates the specified nssname. If the optional
1477 * arena argument is non-null, the memory required will be obtained
1478 * from that arena; otherwise, the memory will be obtained from the
1479 * heap. This routine may return NULL upon error, in which case it
1480 * will have created an error stack.
1481 *
1482 * The error may be one of the following values:
1483 * NSS_ERROR_INVALID_NAME
1484 * NSS_ERROR_NO_MEMORY
1485 *
1486 * Return value:
1487 * NULL upon error
1488 * A pointer to a new NSSName
1489 */
1491 NSS_EXTERN NSSName *
1492 NSSName_Duplicate
1493 (
1495 NSSArena *arenaOpt
1496 );
1498 /*
1499 * NSSName_GetUID
1500 *
1501 * This routine will attempt to derive a user identifier from the
1502 * specified name, if the choices and content of the name permit.
1503 * If the Name consists of a Sequence of Relative Distinguished
1504 * Names containing a UID attribute, the UID will be the value of
1505 * that attribute. Note that no UID attribute is defined in either
1506 * PKIX or PKCS#9; rather, this seems to derive from RFC 1274, which
1507 * defines the type as a caseIgnoreString. We'll return a Directory
1508 * String. If the optional arena argument is non-null, the memory
1509 * used will be obtained from that arena; otherwise, the memory will
1510 * be obtained from the heap. This routine may return NULL upon error,
1511 * in which case it will have created an error stack.
1512 *
1513 * The error may be one of the following values:
1514 * NSS_ERROR_INVALID_NAME
1515 * NSS_ERROR_NO_UID
1516 * NSS_ERROR_NO_MEMORY
1517 *
1518 * Return value:
1519 * NULL upon error
1520 * A pointer to a UTF8 String.
1521 */
1524 NSSName_GetUID
1525 (
1527 NSSArena *arenaOpt
1528 );
1530 /*
1531 * NSSName_GetEmail
1532 *
1533 * This routine will attempt to derive an email address from the
1534 * specified name, if the choices and content of the name permit.
1535 * If the Name consists of a Sequence of Relative Distinguished
1536 * Names containing either a PKIX email address or a PKCS#9 email
1537 * address, the result will be the value of that attribute. If the
1538 * optional arena argument is non-null, the memory used will be
1539 * obtained from that arena; otherwise, the memory will be obtained
1540 * from the heap. This routine may return NULL upon error, in which
1541 * case it will have created an error stack.
1542 *
1543 * The error may be one of the following values:
1544 * NSS_ERROR_INVALID_NAME
1545 * NSS_ERROR_NO_EMAIL
1546 * NSS_ERROR_NO_MEMORY
1547 *
1548 * Return value:
1549 * NULL upon error
1550 * A pointer to a UTF8 String
1551 */
1554 NSSName_GetEmail
1555 (
1557 NSSArena *arenaOpt
1558 );
1560 /*
1561 * NSSName_GetCommonName
1562 *
1563 * This routine will attempt to derive a common name from the
1564 * specified name, if the choices and content of the name permit.
1565 * If the Name consists of a Sequence of Relative Distinguished Names
1566 * containing a PKIX Common Name, the result will be that name. If
1567 * the optional arena argument is non-null, the memory used will be
1568 * obtained from that arena; otherwise, the memory will be obtained
1569 * from the heap. This routine may return NULL upon error, in which
1570 * case it will have created an error stack.
1571 *
1572 * The error may be one of the following values:
1573 * NSS_ERROR_INVALID_NAME
1574 * NSS_ERROR_NO_COMMON_NAME
1575 * NSS_ERROR_NO_MEMORY
1576 *
1577 * Return value:
1578 * NULL upon error
1579 * A pointer to a UTF8 String
1580 */
1583 NSSName_GetCommonName
1584 (
1586 NSSArena *arenaOpt
1587 );
1589 /*
1590 * NSSName_GetOrganization
1591 *
1592 * This routine will attempt to derive an organisation name from the
1593 * specified name, if the choices and content of the name permit.
1594 * If Name consists of a Sequence of Relative Distinguished names
1595 * containing a PKIX Organization, the result will be the value of
1596 * that attribute. If the optional arena argument is non-null, the
1597 * memory used will be obtained from that arena; otherwise, the memory
1598 * will be obtained from the heap. This routine may return NULL upon
1599 * error, in which case it will have created an error stack.
1600 *
1601 * The error may be one of the following values:
1602 * NSS_ERROR_INVALID_NAME
1603 * NSS_ERROR_NO_ORGANIZATION
1604 * NSS_ERROR_NO_MEMORY
1605 *
1606 * Return value:
1607 * NULL upon error
1608 * A pointer to a UTF8 String
1609 */
1612 NSSName_GetOrganization
1613 (
1615 NSSArena *arenaOpt
1616 );
1618 /*
1619 * NSSName_GetOrganizationalUnits
1620 *
1621 * This routine will attempt to derive a sequence of organisational
1622 * unit names from the specified name, if the choices and content of
1623 * the name permit. If the Name consists of a Sequence of Relative
1624 * Distinguished Names containing one or more organisational units,
1625 * the result will be the values of those attributes. If the optional
1626 * arena argument is non-null, the memory used will be obtained from
1627 * that arena; otherwise, the memory will be obtained from the heap.
1628 * This routine may return NULL upon error, in which case it will have
1629 * created an error stack.
1630 *
1631 * The error may be one of the following values:
1632 * NSS_ERROR_INVALID_NAME
1633 * NSS_ERROR_NO_ORGANIZATIONAL_UNITS
1634 * NSS_ERROR_NO_MEMORY
1635 *
1636 * Return value:
1637 * NULL upon error
1638 * A pointer to a null-terminated array of UTF8 Strings
1639 */
1642 NSSName_GetOrganizationalUnits
1643 (
1645 NSSArena *arenaOpt
1646 );
1648 /*
1649 * NSSName_GetStateOrProvince
1650 *
1651 * This routine will attempt to derive a state or province name from
1652 * the specified name, if the choices and content of the name permit.
1653 * If the Name consists of a Sequence of Relative Distinguished Names
1654 * containing a state or province, the result will be the value of
1655 * that attribute. If the optional arena argument is non-null, the
1656 * memory used will be obtained from that arena; otherwise, the memory
1657 * will be obtained from the heap. This routine may return NULL upon
1658 * error, in which case it will have created an error stack.
1659 *
1660 * The error may be one of the following values:
1661 * NSS_ERROR_INVALID_NAME
1662 * NSS_ERROR_NO_STATE_OR_PROVINCE
1663 * NSS_ERROR_NO_MEMORY
1664 *
1665 * Return value:
1666 * NULL upon error
1667 * A pointer to a UTF8 String
1668 */
1671 NSSName_GetStateOrProvince
1672 (
1674 NSSArena *arenaOpt
1675 );
1677 /*
1678 * NSSName_GetLocality
1679 *
1680 * This routine will attempt to derive a locality name from the
1681 * specified name, if the choices and content of the name permit. If
1682 * the Name consists of a Sequence of Relative Distinguished names
1683 * containing a Locality, the result will be the value of that
1684 * attribute. If the optional arena argument is non-null, the memory
1685 * used will be obtained from that arena; otherwise, the memory will
1686 * be obtained from the heap. This routine may return NULL upon error,
1687 * in which case it will have created an error stack.
1688 *
1689 * The error may be one of the following values:
1690 * NSS_ERROR_INVALID_NAME
1691 * NSS_ERROR_NO_LOCALITY
1692 * NSS_ERROR_NO_MEMORY
1693 *
1694 * Return value:
1695 * NULL upon error
1696 * A pointer to a UTF8 String
1697 */
1700 NSSName_GetLocality
1701 (
1703 NSSArena *arenaOpt
1704 );
1706 /*
1707 * NSSName_GetCountry
1708 *
1709 * This routine will attempt to derive a country name from the
1710 * specified name, if the choices and content of the name permit.
1711 * If the Name consists of a Sequence of Relative Distinguished
1712 * Names containing a Country, the result will be the value of
1713 * that attribute.. If the optional arena argument is non-null,
1714 * the memory used will be obtained from that arena; otherwise,
1715 * the memory will be obtained from the heap. This routine may
1716 * return NULL upon error, in which case it will have created an
1717 * error stack.
1718 *
1719 * The error may be one of the following values:
1720 * NSS_ERROR_INVALID_NAME
1721 * NSS_ERROR_NO_COUNTRY
1722 * NSS_ERROR_NO_MEMORY
1723 *
1724 * Return value:
1725 * NULL upon error
1726 * A pointer to a UTF8 String
1727 */
1730 NSSName_GetCountry
1731 (
1733 NSSArena *arenaOpt
1734 );
1736 /*
1737 * NSSName_GetAttribute
1738 *
1739 * If the specified name consists of a Sequence of Relative
1740 * Distinguished Names containing an attribute with the specified
1741 * type, and the actual value of that attribute may be expressed
1742 * with a Directory String, then the value of that attribute will
1743 * be returned as a Directory String. If the optional arena argument
1744 * is non-null, the memory used will be obtained from that arena;
1745 * otherwise, the memory will be obtained from the heap. This routine
1746 * may return NULL upon error, in which case it will have created an
1747 * error stack.
1748 *
1749 * The error may be one of the following values:
1750 * NSS_ERROR_INVALID_NAME
1751 * NSS_ERROR_NO_ATTRIBUTE
1752 * NSS_ERROR_ATTRIBUTE_VALUE_NOT_STRING
1753 *
1754 * Return value:
1755 * NULL upon error
1756 * A pointer to a UTF8 String
1757 */
1760 NSSName_GetAttribute
1761 (
1764 NSSArena *arenaOpt
1765 );
1767 /*
1768 * NSSGeneralName
1769 *
1770 * The public "methods" regarding this "object" are:
1771 *
1772 * NSSGeneralName_CreateFromBER -- constructor
1773 * NSSGeneralName_CreateFromUTF8 -- constructor
1774 * NSSGeneralName_Create -- constructor
1775 *
1776 * NSSGeneralName_Destroy
1777 * NSSGeneralName_GetDEREncoding
1778 * NSSGeneralName_GetUTF8Encoding
1779 * NSSGeneralName_GetChoice
1780 * NSSGeneralName_GetOtherName
1781 * NSSGeneralName_GetRfc822Name
1782 * NSSGeneralName_GetDNSName
1783 * NSSGeneralName_GetX400Address
1784 * NSSGeneralName_GetDirectoryName
1785 * NSSGeneralName_GetEdiPartyName
1786 * NSSGeneralName_GetUniformResourceIdentifier
1787 * NSSGeneralName_GetIPAddress
1788 * NSSGeneralName_GetRegisteredID
1789 * NSSGeneralName_GetSpecifiedChoice
1790 * NSSGeneralName_Compare
1791 * NSSGeneralName_Duplicate
1792 *
1793 * NSSGeneralName_GetUID
1794 * NSSGeneralName_GetEmail
1795 * NSSGeneralName_GetCommonName
1796 * NSSGeneralName_GetOrganization
1797 * NSSGeneralName_GetOrganizationalUnits
1798 * NSSGeneralName_GetStateOrProvince
1799 * NSSGeneralName_GetLocality
1800 * NSSGeneralName_GetCountry
1801 * NSSGeneralName_GetAttribute
1802 */
1804 /*
1805 * NSSGeneralName_CreateFromBER
1806 *
1807 * This routine creates an NSSGeneralName by decoding a BER- or DER-
1808 * encoded general name. If the optional arena argument is non-null,
1809 * the memory used will be obtained from that arena; otherwise, the
1810 * memory will be obtained from the heap. This routine may return
1811 * NULL upon error, in which case it will have created an error stack.
1812 *
1813 * The error may be one of the following values:
1814 * NSS_ERROR_INVALID_BER
1815 * NSS_ERROR_NO_MEMORY
1816 *
1817 * Return value:
1818 * NULL upon error
1819 * A pointer to an NSSGeneralName upon success
1820 */
1822 NSS_EXTERN NSSGeneralName *
1823 NSSGeneralName_CreateFromBER
1824 (
1826 NSSBER *berGeneralName
1827 );
1829 /*
1830 * NSSGeneralName_CreateFromUTF8
1831 *
1832 * This routine creates an NSSGeneralName by decoding a UTF8 string
1833 * consisting of the string representation of one of the choices of
1834 * general names. If the optional arena argument is non-null, the
1835 * memory used will be obtained from that arena; otherwise, the memory
1836 * will be obtained from the heap. The routine may return NULL upon
1837 * error, in which case it will have created an error stack.
1838 *
1839 * The error may be one of the following values:
1840 * NSS_ERROR_INVALID_STRING
1841 * NSS_ERROR_NO_MEMORY
1842 *
1843 * Return value:
1844 * NULL upon error
1845 * A pointer to an NSSGeneralName upon success
1846 */
1848 NSS_EXTERN NSSGeneralName *
1849 NSSGeneralName_CreateFromUTF8
1850 (
1852 NSSUTF8 *stringGeneralName
1853 );
1855 /*
1856 * NSSGeneralName_Create
1857 *
1858 * This routine creates an NSSGeneralName with the specified choice of
1859 * underlying name types. The value of the choice variable must be one
1860 * of the values of the NSSGeneralNameChoice enumeration, and the type
1861 * of the arg variable must be as specified in the following table:
1862 *
1863 * Choice Type
1864 * ============================================ =========
1865 * NSSGeneralNameChoiceOtherName
1866 * NSSGeneralNameChoiceRfc822Name
1867 * NSSGeneralNameChoiceDNSName
1868 * NSSGeneralNameChoiceX400Address
1869 * NSSGeneralNameChoiceDirectoryName NSSName *
1870 * NSSGeneralNameChoiceEdiPartyName
1871 * NSSGeneralNameChoiceUniformResourceIdentifier
1872 * NSSGeneralNameChoiceIPAddress
1873 * NSSGeneralNameChoiceRegisteredID
1874 *
1875 * If the optional arena argument is non-null, the memory used will
1876 * be obtained from that arena; otherwise, the memory will be
1877 * obtained from the heap. This routine may return NULL upon error,
1878 * in which case it will have created an error stack.
1879 *
1880 * The error may be one fo the following values:
1881 * NSS_ERROR_INVALID_CHOICE
1882 * NSS_ERROR_INVALID_ARGUMENT
1883 * NSS_ERROR_NO_MEMORY
1884 *
1885 * Return value:
1886 * NULL upon error
1887 * A pointer to an NSSGeneralName upon success
1888 */
1890 NSS_EXTERN NSSGeneralName *
1891 NSSGeneralName_Create
1892 (
1893 NSSGeneralNameChoice choice,
1895 );
1897 /*
1898 * NSSGeneralName_Destroy
1899 *
1900 * This routine will destroy a General Name object. It should
1901 * eventually be called on all General Names created without an arena.
1902 * While it is not necessary to call it on General Names created within
1903 * an arena, it is not an error to do so. This routine returns a
1904 * PRStatus value; if successful, it will return PR_SUCCESS. If
1905 * usuccessful, it will create an error stack and return PR_FAILURE.
1906 *
1907 * The error may be one of the following values:
1908 * NSS_ERROR_INVALID_GENERAL_NAME
1909 *
1910 * Return value:
1911 * PR_FAILURE upon failure
1912 * PR_SUCCESS upon success
1913 */
1915 NSS_EXTERN PRStatus
1916 NSSGeneralName_Destroy
1917 (
1918 NSSGeneralName *generalName
1919 );
1921 /*
1922 * NSSGeneralName_GetDEREncoding
1923 *
1924 * This routine will DER-encode a name object. If the optional arena
1925 * argument is non-null, the memory used will be obtained from that
1926 * arena; otherwise, the memory will be obtained from the heap. This
1927 * routine may return null upon error, in which case it will have
1928 * created an error stack.
1929 *
1930 * The error may be one of the following values:
1931 * NSS_ERROR_INVALID_GENERAL_NAME
1932 * NSS_ERROR_NO_MEMORY
1933 *
1934 * Return value:
1935 * NULL upon error
1936 * The DER encoding of this NSSGeneralName
1937 */
1939 NSS_EXTERN NSSDER *
1940 NSSGeneralName_GetDEREncoding
1941 (
1943 NSSArena *arenaOpt
1944 );
1946 /*
1947 * NSSGeneralName_GetUTF8Encoding
1948 *
1949 * This routine returns a UTF8 string containing a string
1950 * representation of the General Name in the format specified by the
1951 * underlying name choice. If the optional arena argument is
1952 * non-null, the memory used will be obtained from that arena;
1953 * otherwise, the memory will be obtained from the heap. This routine
1954 * may return NULL upon error, in which case it will have created an
1955 * error stack.
1956 *
1957 * The error may be one of the following values:
1958 * NSS_ERROR_INVALID_GENERAL_NAME
1959 * NSS_ERROR_NO_MEMORY
1960 *
1961 * Return value:
1962 * NULL upon error
1963 * A pointer to a UTF8 string
1964 */
1966 NSS_EXTERN NSSUTF8 *
1967 NSSGeneralName_GetUTF8Encoding
1968 (
1970 NSSArena *arenaOpt
1971 );
1973 /*
1974 * NSSGeneralName_GetChoice
1975 *
1976 * This routine returns the type of choice underlying the specified
1977 * general name. The return value will be a member of the
1978 * NSSGeneralNameChoice enumeration. This routine may return
1979 * NSSGeneralNameChoiceInvalid upon error, in which case it will have
1980 * created an error stack.
1981 *
1982 * The error may be one of the following values:
1983 * NSS_ERROR_INVALID_GENERAL_NAME
1984 *
1985 * Return value:
1986 * NSSGeneralNameChoiceInvalid upon error
1987 * An other member of the NSSGeneralNameChoice enumeration
1988 */
1990 NSS_EXTERN NSSGeneralNameChoice
1991 NSSGeneralName_GetChoice
1992 (
1993 NSSGeneralName *generalName
1994 );
1996 /*
1997 * NSSGeneralName_GetOtherName
1998 *
1999 * If the choice underlying the specified NSSGeneralName is that of an
2000 * Other Name, this routine will return a pointer to that Other name.
2001 * Otherwise, this routine will place an error on the error stack, and
2002 * return NULL. If the optional arena argument is non-null, the memory
2003 * required will be obtained from that arena; otherwise, the memory
2004 * will be obtained from the heap. The caller owns the returned
2005 * pointer. This routine may return NULL upon error, in which case it
2006 * will have created an error stack.
2007 *
2008 * The error may be one of the following values:
2009 * NSS_ERROR_INVALID_GENERAL_NAME
2010 * NSS_ERROR_WRONG_CHOICE
2011 * NSS_ERROR_NO_MEMORY
2012 *
2013 * Return value:
2014 * NULL upon error
2015 * A caller-owned pointer to an NSSOtherName
2016 */
2018 NSS_EXTERN NSSOtherName *
2019 NSSGeneralName_GetOtherName
2020 (
2022 NSSArena *arenaOpt
2023 );
2025 /*
2026 * NSSGeneralName_GetRfc822Name
2027 *
2028 * If the choice underlying the specified NSSGeneralName is that of an
2029 * RFC 822 Name, this routine will return a pointer to that name.
2030 * Otherwise, this routine will place an error on the error stack, and
2031 * return NULL. If the optional arena argument is non-null, the memory
2032 * required will be obtained from that arena; otherwise, the memory
2033 * will be obtained from the heap. The caller owns the returned
2034 * pointer. This routine may return NULL upon error, in which case it
2035 * will have created an error stack.
2036 *
2037 * The error may be one of the following values:
2038 * NSS_ERROR_INVALID_GENERAL_NAME
2039 * NSS_ERROR_WRONG_CHOICE
2040 * NSS_ERROR_NO_MEMORY
2041 *
2042 * Return value:
2043 * NULL upon error
2044 * A caller-owned pointer to an NSSRFC822Name
2045 */
2047 NSS_EXTERN NSSRFC822Name *
2048 NSSGeneralName_GetRfc822Name
2049 (
2051 NSSArena *arenaOpt
2052 );
2054 /*
2055 * NSSGeneralName_GetDNSName
2056 *
2057 * If the choice underlying the specified NSSGeneralName is that of a
2058 * DNS Name, this routine will return a pointer to that DNS name.
2059 * Otherwise, this routine will place an error on the error stack, and
2060 * return NULL. If the optional arena argument is non-null, the memory
2061 * required will be obtained from that arena; otherwise, the memory
2062 * will be obtained from the heap. The caller owns the returned
2063 * pointer. This routine may return NULL upon error, in which case it
2064 * will have created an error stack.
2065 *
2066 * The error may be one of the following values:
2067 * NSS_ERROR_INVALID_GENERAL_NAME
2068 * NSS_ERROR_WRONG_CHOICE
2069 * NSS_ERROR_NO_MEMORY
2070 *
2071 * Return value:
2072 * NULL upon error
2073 * A caller-owned pointer to an NSSDNSName
2074 */
2076 NSS_EXTERN NSSDNSName *
2077 NSSGeneralName_GetDNSName
2078 (
2080 NSSArena *arenaOpt
2081 );
2083 /*
2084 * NSSGeneralName_GetX400Address
2085 *
2086 * If the choice underlying the specified NSSGeneralName is that of an
2087 * X.400 Address, this routine will return a pointer to that Address.
2088 * Otherwise, this routine will place an error on the error stack, and
2089 * return NULL. If the optional arena argument is non-null, the memory
2090 * required will be obtained from that arena; otherwise, the memory
2091 * will be obtained from the heap. The caller owns the returned
2092 * pointer. This routine may return NULL upon error, in which case it
2093 * will have created an error stack.
2094 *
2095 * The error may be one of the following values:
2096 * NSS_ERROR_INVALID_GENERAL_NAME
2097 * NSS_ERROR_WRONG_CHOICE
2098 * NSS_ERROR_NO_MEMORY
2099 *
2100 * Return value:
2101 * NULL upon error
2102 * A caller-owned pointer to an NSSX400Address
2103 */
2105 NSS_EXTERN NSSX400Address *
2106 NSSGeneralName_GetX400Address
2107 (
2109 NSSArena *arenaOpt
2110 );
2112 /*
2113 * NSSGeneralName_GetDirectoryName
2114 *
2115 * If the choice underlying the specified NSSGeneralName is that of a
2116 * (directory) Name, this routine will return a pointer to that name.
2117 * Otherwise, this routine will place an error on the error stack, and
2118 * return NULL. If the optional arena argument is non-null, the memory
2119 * required will be obtained from that arena; otherwise, the memory
2120 * will be obtained from the heap. The caller owns the returned
2121 * pointer. This routine may return NULL upon error, in which case it
2122 * will have created an error stack.
2123 *
2124 * The error may be one of the following values:
2125 * NSS_ERROR_INVALID_GENERAL_NAME
2126 * NSS_ERROR_WRONG_CHOICE
2127 * NSS_ERROR_NO_MEMORY
2128 *
2129 * Return value:
2130 * NULL upon error
2131 * A caller-owned pointer to an NSSName
2132 */
2134 NSS_EXTERN NSSName *
2135 NSSGeneralName_GetName
2136 (
2138 NSSArena *arenaOpt
2139 );
2141 /*
2142 * NSSGeneralName_GetEdiPartyName
2143 *
2144 * If the choice underlying the specified NSSGeneralName is that of an
2145 * EDI Party Name, this routine will return a pointer to that name.
2146 * Otherwise, this routine will place an error on the error stack, and
2147 * return NULL. If the optional arena argument is non-null, the memory
2148 * required will be obtained from that arena; otherwise, the memory
2149 * will be obtained from the heap. The caller owns the returned
2150 * pointer. This routine may return NULL upon error, in which case it
2151 * will have created an error stack.
2152 *
2153 * The error may be one of the following values:
2154 * NSS_ERROR_INVALID_GENERAL_NAME
2155 * NSS_ERROR_WRONG_CHOICE
2156 * NSS_ERROR_NO_MEMORY
2157 *
2158 * Return value:
2159 * NULL upon error
2160 * A caller-owned pointer to an NSSEdiPartyName
2161 */
2163 NSS_EXTERN NSSEdiPartyName *
2164 NSSGeneralName_GetEdiPartyName
2165 (
2167 NSSArena *arenaOpt
2168 );
2170 /*
2171 * NSSGeneralName_GetUniformResourceIdentifier
2172 *
2173 * If the choice underlying the specified NSSGeneralName is that of a
2174 * URI, this routine will return a pointer to that URI.
2175 * Otherwise, this routine will place an error on the error stack, and
2176 * return NULL. If the optional arena argument is non-null, the memory
2177 * required will be obtained from that arena; otherwise, the memory
2178 * will be obtained from the heap. The caller owns the returned
2179 * pointer. This routine may return NULL upon error, in which case it
2180 * will have created an error stack.
2181 *
2182 * The error may be one of the following values:
2183 * NSS_ERROR_INVALID_GENERAL_NAME
2184 * NSS_ERROR_WRONG_CHOICE
2185 * NSS_ERROR_NO_MEMORY
2186 *
2187 * Return value:
2188 * NULL upon error
2189 * A caller-owned pointer to an NSSURI
2190 */
2192 NSS_EXTERN NSSURI *
2193 NSSGeneralName_GetUniformResourceIdentifier
2194 (
2196 NSSArena *arenaOpt
2197 );
2199 /*
2200 * NSSGeneralName_GetIPAddress
2201 *
2202 * If the choice underlying the specified NSSGeneralName is that of an
2203 * IP Address , this routine will return a pointer to that address.
2204 * Otherwise, this routine will place an error on the error stack, and
2205 * return NULL. If the optional arena argument is non-null, the memory
2206 * required will be obtained from that arena; otherwise, the memory
2207 * will be obtained from the heap. The caller owns the returned
2208 * pointer. This routine may return NULL upon error, in which case it
2209 * will have created an error stack.
2210 *
2211 * The error may be one of the following values:
2212 * NSS_ERROR_INVALID_GENERAL_NAME
2213 * NSS_ERROR_WRONG_CHOICE
2214 * NSS_ERROR_NO_MEMORY
2215 *
2216 * Return value:
2217 * NULL upon error
2218 * A caller-owned pointer to an NSSIPAddress
2219 */
2221 NSS_EXTERN NSSIPAddress *
2222 NSSGeneralName_GetIPAddress
2223 (
2225 NSSArena *arenaOpt
2226 );
2228 /*
2229 * NSSGeneralName_GetRegisteredID
2230 *
2231 * If the choice underlying the specified NSSGeneralName is that of a
2232 * Registered ID, this routine will return a pointer to that ID.
2233 * Otherwise, this routine will place an error on the error stack, and
2234 * return NULL. If the optional arena argument is non-null, the memory
2235 * required will be obtained from that arena; otherwise, the memory
2236 * will be obtained from the heap. The caller owns the returned
2237 * pointer. This routine may return NULL upon error, in which case it
2238 * will have created an error stack.
2239 *
2240 * The error may be one of the following values:
2241 * NSS_ERROR_INVALID_GENERAL_NAME
2242 * NSS_ERROR_WRONG_CHOICE
2243 * NSS_ERROR_NO_MEMORY
2244 *
2245 * Return value:
2246 * NULL upon error
2247 * A caller-owned pointer to an NSSRegisteredID
2248 */
2250 NSS_EXTERN NSSRegisteredID *
2251 NSSGeneralName_GetRegisteredID
2252 (
2254 NSSArena *arenaOpt
2255 );
2257 /*
2258 * NSSGeneralName_GetSpecifiedChoice
2259 *
2260 * If the choice underlying the specified NSSGeneralName matches the
2261 * specified choice, a caller-owned pointer to that underlying object
2262 * will be returned. Otherwise, an error will be placed on the error
2263 * stack and NULL will be returned. If the optional arena argument
2264 * is non-null, the memory required will be obtained from that arena;
2265 * otherwise, the memory will be obtained from the heap. The caller
2266 * owns the returned pointer. This routine may return NULL upon
2267 * error, in which caes it will have created an error stack.
2268 *
2269 * The error may be one of the following values:
2270 * NSS_ERROR_INVALID_GENERAL_NAME
2271 * NSS_ERROR_WRONG_CHOICE
2272 * NSS_ERROR_NO_MEMORY
2273 *
2274 * Return value:
2275 * NULL upon error
2276 * A caller-owned pointer, which must be typecast
2277 */
2280 NSSGeneralName_GetSpecifiedChoice
2281 (
2283 NSSGeneralNameChoice choice,
2284 NSSArena *arenaOpt
2285 );
2287 /*
2288 * NSSGeneralName_Compare
2289 *
2290 * This routine compares two General Names for equality. For two
2291 * General Names to be equal, they must have the same choice of
2292 * underlying types, and the underlying values must be equal. The
2293 * result of the comparison will be stored at the location pointed
2294 * to by the "equalp" variable, which must point to a valid PRBool.
2295 * This routine may return PR_FAILURE upon error, in which case it
2296 * will have created an error stack.
2297 *
2298 * The error may be one of the following value:
2299 * NSS_ERROR_INVALID_GENERAL_NAME
2300 * NSS_ERROR_INVALID_ARGUMENT
2301 *
2302 * Return value:
2303 * PR_FAILURE upon error
2304 * PR_SUCCESS upon a successful comparison (equal or not)
2305 */
2307 NSS_EXTERN PRStatus
2308 NSSGeneralName_Compare
2309 (
2312 PRBool *equalp
2313 );
2315 /*
2316 * NSSGeneralName_Duplicate
2317 *
2318 * This routine duplicates the specified General Name. If the optional
2319 * arena argument is non-null, the memory required will be obtained
2320 * from that arena; otherwise, the memory will be obtained from the
2321 * heap. This routine may return NULL upon error, in which case it
2322 * will have created an error stack.
2323 *
2324 * The error may be one of the following values:
2325 * NSS_ERROR_INVALID_GENERAL_NAME
2326 * NSS_ERROR_NO_MEMORY
2327 *
2328 * Return value:
2329 * NULL upon error
2330 * A pointer to a new NSSGeneralName
2331 */
2333 NSS_EXTERN NSSGeneralName *
2334 NSSGeneralName_Duplicate
2335 (
2337 NSSArena *arenaOpt
2338 );
2340 /*
2341 * NSSGeneralName_GetUID
2342 *
2343 * This routine will attempt to derive a user identifier from the
2344 * specified general name, if the choices and content of the name
2345 * permit. If the General Name is a (directory) Name consisting
2346 * of a Sequence of Relative Distinguished Names containing a UID
2347 * attribute, the UID will be the value of that attribute. Note
2348 * that no UID attribute is defined in either PKIX or PKCS#9;
2349 * rather, this seems to derive from RFC 1274, which defines the
2350 * type as a caseIgnoreString. We'll return a Directory String.
2351 * If the optional arena argument is non-null, the memory used
2352 * will be obtained from that arena; otherwise, the memory will be
2353 * obtained from the heap. This routine may return NULL upon error,
2354 * in which case it will have created an error stack.
2355 *
2356 * The error may be one of the following values:
2357 * NSS_ERROR_INVALID_GENERAL_NAME
2358 * NSS_ERROR_NO_UID
2359 * NSS_ERROR_NO_MEMORY
2360 *
2361 * Return value:
2362 * NULL upon error
2363 * A pointer to a UTF8 String.
2364 */
2367 NSSGeneralName_GetUID
2368 (
2370 NSSArena *arenaOpt
2371 );
2373 /*
2374 * NSSGeneralName_GetEmail
2375 *
2376 * This routine will attempt to derive an email address from the
2377 * specified general name, if the choices and content of the name
2378 * permit. If the General Name is a (directory) Name consisting
2379 * of a Sequence of Relative Distinguished names containing either
2380 * a PKIX email address or a PKCS#9 email address, the result will
2381 * be the value of that attribute. If the General Name is an RFC 822
2382 * Name, the result will be the string form of that name. If the
2383 * optional arena argument is non-null, the memory used will be
2384 * obtained from that arena; otherwise, the memory will be obtained
2385 * from the heap. This routine may return NULL upon error, in which
2386 * case it will have created an error stack.
2387 *
2388 * The error may be one of the following values:
2389 * NSS_ERROR_INVALID_GENERAL_NAME
2390 * NSS_ERROR_NO_EMAIL
2391 * NSS_ERROR_NO_MEMORY
2392 *
2393 * Return value:
2394 * NULL upon error
2395 * A pointer to a UTF8 String
2396 */
2399 NSSGeneralName_GetEmail
2400 (
2402 NSSArena *arenaOpt
2403 );
2405 /*
2406 * NSSGeneralName_GetCommonName
2407 *
2408 * This routine will attempt to derive a common name from the
2409 * specified general name, if the choices and content of the name
2410 * permit. If the General Name is a (directory) Name consisting
2411 * of a Sequence of Relative Distinguished names containing a PKIX
2412 * Common Name, the result will be that name. If the optional arena
2413 * argument is non-null, the memory used will be obtained from that
2414 * arena; otherwise, the memory will be obtained from the heap. This
2415 * routine may return NULL upon error, in which case it will have
2416 * created an error stack.
2417 *
2418 * The error may be one of the following values:
2419 * NSS_ERROR_INVALID_GENERAL_NAME
2420 * NSS_ERROR_NO_COMMON_NAME
2421 * NSS_ERROR_NO_MEMORY
2422 *
2423 * Return value:
2424 * NULL upon error
2425 * A pointer to a UTF8 String
2426 */
2429 NSSGeneralName_GetCommonName
2430 (
2432 NSSArena *arenaOpt
2433 );
2435 /*
2436 * NSSGeneralName_GetOrganization
2437 *
2438 * This routine will attempt to derive an organisation name from the
2439 * specified general name, if the choices and content of the name
2440 * permit. If the General Name is a (directory) Name consisting
2441 * of a Sequence of Relative Distinguished names containing an
2442 * Organization, the result will be the value of that attribute.
2443 * If the optional arena argument is non-null, the memory used will
2444 * be obtained from that arena; otherwise, the memory will be obtained
2445 * from the heap. This routine may return NULL upon error, in which
2446 * case it will have created an error stack.
2447 *
2448 * The error may be one of the following values:
2449 * NSS_ERROR_INVALID_GENERAL_NAME
2450 * NSS_ERROR_NO_ORGANIZATION
2451 * NSS_ERROR_NO_MEMORY
2452 *
2453 * Return value:
2454 * NULL upon error
2455 * A pointer to a UTF8 String
2456 */
2459 NSSGeneralName_GetOrganization
2460 (
2462 NSSArena *arenaOpt
2463 );
2465 /*
2466 * NSSGeneralName_GetOrganizationalUnits
2467 *
2468 * This routine will attempt to derive a sequence of organisational
2469 * unit names from the specified general name, if the choices and
2470 * content of the name permit. If the General Name is a (directory)
2471 * Name consisting of a Sequence of Relative Distinguished names
2472 * containing one or more organisational units, the result will
2473 * consist of those units. If the optional arena argument is non-
2474 * null, the memory used will be obtained from that arena; otherwise,
2475 * the memory will be obtained from the heap. This routine may return
2476 * NULL upon error, in which case it will have created an error stack.
2477 *
2478 * The error may be one of the following values:
2479 * NSS_ERROR_INVALID_GENERAL_NAME
2480 * NSS_ERROR_NO_ORGANIZATIONAL_UNITS
2481 * NSS_ERROR_NO_MEMORY
2482 *
2483 * Return value:
2484 * NULL upon error
2485 * A pointer to a null-terminated array of UTF8 Strings
2486 */
2489 NSSGeneralName_GetOrganizationalUnits
2490 (
2492 NSSArena *arenaOpt
2493 );
2495 /*
2496 * NSSGeneralName_GetStateOrProvince
2497 *
2498 * This routine will attempt to derive a state or province name from
2499 * the specified general name, if the choices and content of the name
2500 * permit. If the General Name is a (directory) Name consisting
2501 * of a Sequence of Relative Distinguished names containing a state or
2502 * province, the result will be the value of that attribute. If the
2503 * optional arena argument is non-null, the memory used will be
2504 * obtained from that arena; otherwise, the memory will be obtained
2505 * from the heap. This routine may return NULL upon error, in which
2506 * case it will have created an error stack.
2507 *
2508 * The error may be one of the following values:
2509 * NSS_ERROR_INVALID_GENERAL_NAME
2510 * NSS_ERROR_NO_STATE_OR_PROVINCE
2511 * NSS_ERROR_NO_MEMORY
2512 *
2513 * Return value:
2514 * NULL upon error
2515 * A pointer to a UTF8 String
2516 */
2519 NSSGeneralName_GetStateOrProvince
2520 (
2522 NSSArena *arenaOpt
2523 );
2525 /*
2526 * NSSGeneralName_GetLocality
2527 *
2528 * This routine will attempt to derive a locality name from
2529 * the specified general name, if the choices and content of the name
2530 * permit. If the General Name is a (directory) Name consisting
2531 * of a Sequence of Relative Distinguished names containing a Locality,
2532 * the result will be the value of that attribute. If the optional
2533 * arena argument is non-null, the memory used will be obtained from
2534 * that arena; otherwise, the memory will be obtained from the heap.
2535 * This routine may return NULL upon error, in which case it will have
2536 * created an error stack.
2537 *
2538 * The error may be one of the following values:
2539 * NSS_ERROR_INVALID_GENERAL_NAME
2540 * NSS_ERROR_NO_LOCALITY
2541 * NSS_ERROR_NO_MEMORY
2542 *
2543 * Return value:
2544 * NULL upon error
2545 * A pointer to a UTF8 String
2546 */
2549 NSSGeneralName_GetLocality
2550 (
2552 NSSArena *arenaOpt
2553 );
2555 /*
2556 * NSSGeneralName_GetCountry
2557 *
2558 * This routine will attempt to derive a country name from the
2559 * specified general name, if the choices and content of the name
2560 * permit. If the General Name is a (directory) Name consisting of a
2561 * Sequence of Relative Distinguished names containing a Country, the
2562 * result will be the value of that attribute. If the optional
2563 * arena argument is non-null, the memory used will be obtained from
2564 * that arena; otherwise, the memory will be obtained from the heap.
2565 * This routine may return NULL upon error, in which case it will have
2566 * created an error stack.
2567 *
2568 * The error may be one of the following values:
2569 * NSS_ERROR_INVALID_GENERAL_NAME
2570 * NSS_ERROR_NO_COUNTRY
2571 * NSS_ERROR_NO_MEMORY
2572 *
2573 * Return value:
2574 * NULL upon error
2575 * A pointer to a UTF8 String
2576 */
2579 NSSGeneralName_GetCountry
2580 (
2582 NSSArena *arenaOpt
2583 );
2585 /*
2586 * NSSGeneralName_GetAttribute
2587 *
2588 * If the specified general name is a (directory) name consisting
2589 * of a Sequence of Relative Distinguished Names containing an
2590 * attribute with the specified type, and the actual value of that
2591 * attribute may be expressed with a Directory String, then the
2592 * value of that attribute will be returned as a Directory String.
2593 * If the optional arena argument is non-null, the memory used will
2594 * be obtained from that arena; otherwise, the memory will be obtained
2595 * from the heap. This routine may return NULL upon error, in which
2596 * case it will have created an error stack.
2597 *
2598 * The error may be one of the following values:
2599 * NSS_ERROR_INVALID_GENERAL_NAME
2600 * NSS_ERROR_NO_ATTRIBUTE
2601 * NSS_ERROR_ATTRIBUTE_VALUE_NOT_STRING
2602 *
2603 * Return value:
2604 * NULL upon error
2605 * A pointer to a UTF8 String
2606 */
2609 NSSGeneralName_GetAttribute
2610 (
2613 NSSArena *arenaOpt
2614 );
2616 /*
2617 * NSSGeneralNameSeq
2618 *
2619 * The public "methods" regarding this "object" are:
2620 *
2621 * NSSGeneralNameSeq_CreateFromBER -- constructor
2622 * NSSGeneralNameSeq_Create -- constructor
2623 *
2624 * NSSGeneralNameSeq_Destroy
2625 * NSSGeneralNameSeq_GetDEREncoding
2626 * NSSGeneralNameSeq_AppendGeneralName
2627 * NSSGeneralNameSeq_GetGeneralNameCount
2628 * NSSGeneralNameSeq_GetGeneralName
2629 * NSSGeneralNameSeq_Compare
2630 * NSSGeneralnameSeq_Duplicate
2631 */
2633 /*
2634 * NSSGeneralNameSeq_CreateFromBER
2635 *
2636 * This routine creates a general name sequence by decoding a BER-
2637 * or DER-encoded GeneralNames. If the optional arena argument is
2638 * non-null, the memory used will be obtained from that arena;
2639 * otherwise, the memory will be obtained from the heap. This routine
2640 * may return NULL upon error, in which case it will have created an
2641 * error stack.
2642 *
2643 * The error may be one of the following values:
2644 * NSS_ERROR_INVALID_BER
2645 * NSS_ERROR_NO_MEMORY
2646 *
2647 * Return value:
2648 * NULL upon error
2649 * A pointer to an NSSGeneralNameSeq upon success
2650 */
2652 NSS_EXTERN NSSGeneralNameSeq *
2653 NSSGeneralNameSeq_CreateFromBER
2654 (
2656 NSSBER *berGeneralNameSeq
2657 );
2659 /*
2660 * NSSGeneralNameSeq_Create
2661 *
2662 * This routine creates an NSSGeneralNameSeq from one or more General
2663 * Names. The final argument to this routine must be NULL. If the
2664 * optional arena argument is non-null, the memory used will be
2665 * obtained from that arena; otherwise, the memory will be obtained
2666 * from the heap. This routine may return NULL upon error, in which
2667 * case it will have created an error stack.
2668 *
2669 * The error may be one of the following values:
2670 * NSS_ERROR_NO_MEMORY
2671 * NSS_ERROR_INVALID_GENERAL_NAME
2672 *
2673 * Return value:
2674 * NULL upon error
2675 * A pointer to an NSSGeneralNameSeq upon success
2676 */
2678 NSS_EXTERN NSSGeneralNameSeq *
2679 NSSGeneralNameSeq_Create
2680 (
2683 ...
2684 );
2686 /*
2687 * NSSGeneralNameSeq_Destroy
2688 *
2689 * This routine will destroy an NSSGeneralNameSeq object. It should
2690 * eventually be called on all NSSGeneralNameSeqs created without an
2691 * arena. While it is not necessary to call it on NSSGeneralNameSeq's
2692 * created within an arena, it is not an error to do so. This routine
2693 * returns a PRStatus value; if successful, it will return PR_SUCCESS.
2694 * If unsuccessful, it will create an error stack and return PR_FAILURE.
2695 *
2696 * The error may be one of the following values:
2697 * NSS_ERROR_INVALID_GENERAL_NAME_SEQ
2698 *
2699 * Return value:
2700 * PR_FAILURE upon error
2701 * PR_SUCCESS upon success
2702 */
2704 NSS_EXTERN PRStatus
2705 NSSGeneralNameSeq_Destroy
2706 (
2707 NSSGeneralNameSeq *generalNameSeq
2708 );
2710 /*
2711 * NSSGeneralNameSeq_GetDEREncoding
2712 *
2713 * This routine will DER-encode an NSSGeneralNameSeq object. If the
2714 * optional arena argument is non-null, the memory used will be
2715 * obtained from that arena; otherwise, the memory will be obtained
2716 * from the heap. This routine may return null upon error, in which
2717 * case it will have created an error stack.
2718 *
2719 * The error may be one of the following values:
2720 * NSS_ERROR_INVALID_GENERAL_NAME_SEQ
2721 * NSS_ERROR_NO_MEMORY
2722 *
2723 * Return value:
2724 * NULL upon error
2725 * The DER encoding of this NSSGeneralNameSeq
2726 */
2728 NSS_EXTERN NSSDER *
2729 NSSGeneralNameSeq_GetDEREncoding
2730 (
2732 NSSArena *arenaOpt
2733 );
2735 /*
2736 * NSSGeneralNameSeq_AppendGeneralName
2737 *
2738 * This routine appends a General Name to the end of the existing
2739 * General Name Sequence. If the sequence was created with a non-null
2740 * arena argument, that same arena will be used for any additional
2741 * required memory. If the sequence was created with a NULL arena
2742 * argument, any additional memory will be obtained from the heap.
2743 * This routine returns a PRStatus value; it will return PR_SUCCESS
2744 * upon success, and upon failure it will create an error stack and
2745 * return PR_FAILURE.
2746 *
2747 * The error may be one of the following values:
2748 * NSS_ERROR_INVALID_GENERAL_NAME_SEQ
2749 * NSS_ERROR_INVALID_GENERAL_NAME
2750 * NSS_ERROR_NO_MEMORY
2751 *
2752 * Return value:
2753 * PR_SUCCESS upon success
2754 * PR_FAILURE upon failure.
2755 */
2757 NSS_EXTERN PRStatus
2758 NSSGeneralNameSeq_AppendGeneralName
2759 (
2761 NSSGeneralName *generalName
2762 );
2764 /*
2765 * NSSGeneralNameSeq_GetGeneralNameCount
2766 *
2767 * This routine returns the cardinality of the specified General name
2768 * Sequence. This routine may return 0 upon error, in which case it
2769 * will have created an error stack.
2770 *
2771 * The error may be one of the following values:
2772 * NSS_ERROR_INVALID_GENERAL_NAME_SEQ
2773 *
2774 * Return value;
2775 * 0 upon error
2776 * A positive number upon success
2777 */
2779 NSS_EXTERN PRUint32
2780 NSSGeneralNameSeq_GetGeneralNameCount
2781 (
2782 NSSGeneralNameSeq *generalNameSeq
2783 );
2785 /*
2786 * NSSGeneralNameSeq_GetGeneralName
2787 *
2788 * This routine returns a pointer to the i'th General Name in the
2789 * specified General Name Sequence. The value of the variable 'i' is
2790 * on the range [0,c) where c is the cardinality returned from
2791 * NSSGeneralNameSeq_GetGeneralNameCount. The caller owns the General
2792 * Name the pointer to which is returned. If the optional arena
2793 * argument is non-null, the memory used will be obtained from that
2794 * arena; otherwise, the memory will be obtained from the heap. This
2795 * routine may return NULL upon error, in which case it will have
2796 * created an error stack.
2797 *
2798 * The error may be one of the following values:
2799 * NSS_ERROR_INVALID_GENERAL_NAME_SEQ
2800 * NSS_ERROR_VALUE_OUT_OF_RANGE
2801 * NSS_ERROR_NO_MEMORY
2802 *
2803 * Return value:
2804 * NULL upon error
2805 * A caller-owned pointer to a General Name.
2806 */
2808 NSS_EXTERN NSSGeneralName *
2809 NSSGeneralNameSeq_GetGeneralName
2810 (
2813 PRUint32 i
2814 );
2816 /*
2817 * NSSGeneralNameSeq_Compare
2818 *
2819 * This routine compares two General Name Sequences for equality. For
2820 * two General Name Sequences to be equal, they must have the same
2821 * cardinality, and each General Name in one sequence must be equal to
2822 * the corresponding General Name in the other. The result of the
2823 * comparison will be stored at the location pointed to by the "equalp"
2824 * variable, which must point to a valid PRBool. This routine may
2825 * return PR_FAILURE upon error, in which case it will have created an
2826 * error stack.
2827 *
2828 * The error may be one of the following values:
2829 * NSS_ERROR_INVALID_GENERAL_NAME_SEQ
2830 * NSS_ERROR_INVALID_ARGUMENT
2831 *
2832 * Return value:
2833 * PR_FAILURE upon error
2834 * PR_SUCCESS upon a successful comparison (equal or not)
2835 */
2837 NSS_EXTERN PRStatus
2838 NSSGeneralNameSeq_Compare
2839 (
2842 PRBool *equalp
2843 );
2845 /*
2846 * NSSGeneralNameSeq_Duplicate
2847 *
2848 * This routine duplicates the specified sequence of general names. If
2849 * the optional arena argument is non-null, the memory required will be
2850 * obtained from that arena; otherwise, the memory will be obtained
2851 * from the heap. This routine may return NULL upon error, in which
2852 * case it will have created an error stack.
2853 *
2854 * The error may be one of the following values:
2855 * NSS_ERROR_INVALID_GENERAL_NAME_SEQ
2856 * NSS_ERROR_NO_MEMORY
2857 *
2858 * Return value:
2859 * NULL upon error
2860 * A pointer to a new General Name Sequence.
2861 */
2863 NSS_EXTERN NSSGeneralNameSeq *
2864 NSSGeneralNameSeq_Duplicate
2865 (
2867 NSSArena *arenaOpt
2868 );
2870 PR_END_EXTERN_C