nss/mozilla/security/nss/lib/pki1/pki1.h - Issue 3135002: Update to NSS 3.12.7 and NSPR 4.8.6....

Side by Side Diff: nss/mozilla/security/nss/lib/pki1/pki1.h

Issue 3135002: Update to NSS 3.12.7 and NSPR 4.8.6.... (Closed) Base URL: svn://chrome-svn/chrome/trunk/deps/third_party/

Patch Set: Created 10 years, 4 months ago

Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.

Jump to:

View unified diff | Download patch | Annotate | Revision Log

OLD	NEW
	(Empty)
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 $ $D ate: 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 */

OLD	NEW

« nss/mozilla/security/nss/lib/cryptohi/seckey.c ('K') | « nss/mozilla/security/nss/lib/pki1/oiddata.h ('k') | nss/mozilla/security/nss/lib/pki1/pki1t.h » ('j') | no next file with comments »