← Back to branch summary

~ubuntu-branches/ubuntu/trusty/xulrunner/trusty

« back to all changes in this revision

Viewing changes to security/nss-fips/lib/pki1/pki1.h

  • Committer: Bazaar Package Importer
  • Author(s): Devid Antonio Filoni
  • Date: 2008-08-25 13:04:18 UTC
  • mfrom: (1.1.12 upstream)
  • Revision ID: james.westby@ubuntu.com-20080825130418-ck1i2ms384tzb9m0
Tags: 1.8.1.16+nobinonly-0ubuntu1
https://launchpad.net/bugs/254618
* New upstream release (taken from upstream CVS), LP: #254618.
* Fix MFSA 2008-35, MFSA 2008-34, MFSA 2008-33, MFSA 2008-32, MFSA 2008-31,
  MFSA 2008-30, MFSA 2008-29, MFSA 2008-28, MFSA 2008-27, MFSA 2008-25,
  MFSA 2008-24, MFSA 2008-23, MFSA 2008-22, MFSA 2008-21, MFSA 2008-26 also
  known as CVE-2008-2933, CVE-2008-2785, CVE-2008-2811, CVE-2008-2810,
  CVE-2008-2809, CVE-2008-2808, CVE-2008-2807, CVE-2008-2806, CVE-2008-2805,
  CVE-2008-2803, CVE-2008-2802, CVE-2008-2801, CVE-2008-2800, CVE-2008-2798.
* Drop 89_bz419350_attachment_306066 patch, merged upstream.
* Bump Standards-Version to 3.8.0.

Show diffs side-by-side

added added

removed removed

Lines of Context:
security/nss-fips/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 */