mozilla
/
pjs
зеркало из https://github.com/mozilla/pjs.git
1
0
Форкнуть 0
Код Задачи Пакеты Проекты Релизы Вики Активность
pjs/security/nss/lib/pki1/nsspki1.h

2873 строки
80 KiB
C
Исходник Ответственный История

/* ***** BEGIN LICENSE BLOCK *****
* Version: MPL 1.1/GPL 2.0/LGPL 2.1
*
* The contents of this file are subject to the Mozilla Public License Version
* 1.1 (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
* http://www.mozilla.org/MPL/
*
* Software distributed under the License is distributed on an "AS IS" basis,
* WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
* for the specific language governing rights and limitations under the
* License.
*
* The Original Code is the Netscape security libraries.
*
* The Initial Developer of the Original Code is
* Netscape Communications Corporation.
* Portions created by the Initial Developer are Copyright (C) 1994-2000
* the Initial Developer. All Rights Reserved.
*
* Contributor(s):
*
* Alternatively, the contents of this file may be used under the terms of
* either the GNU General Public License Version 2 or later (the "GPL"), or
* the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
* in which case the provisions of the GPL or the LGPL are applicable instead
* of those above. If you wish to allow use of your version of this file only
* under the terms of either the GPL or the LGPL, and not to allow others to
* use your version of this file under the terms of the MPL, indicate your
* decision by deleting the provisions above and replace them with the notice
* and other provisions required by the GPL or the LGPL. If you do not delete
* the provisions above, a recipient may use your version of this file under
* the terms of any one of the MPL, the GPL or the LGPL.
*
* ***** END LICENSE BLOCK ***** */
#ifndef NSSPKI1_H
#define NSSPKI1_H
#ifdef DEBUG
static const char NSSPKI1_CVS_ID[] = "@(#) $RCSfile: nsspki1.h,v $ $Revision: 1.3 $ $Date: 2005-01-20 02:25:49 $";
#endif /* DEBUG */
/*
* nsspki1.h
*
* This file contains the prototypes of the public NSS routines
* dealing with the PKIX part-1 definitions.
*/
#ifndef NSSBASET_H
#include "nssbaset.h"
#endif /* NSSBASET_H */
#ifndef NSSPKI1T_H
#include "nsspki1t.h"
#endif /* NSSPKI1T_H */
#ifndef OIDDATA_H
#include "oiddata.h"
#endif /* OIDDATA_H */
PR_BEGIN_EXTERN_C
/*
* NSSOID
*
* The public "methods" regarding this "object" are:
*
* NSSOID_CreateFromBER -- constructor
* NSSOID_CreateFromUTF8 -- constructor
* (there is no explicit destructor)
*
* NSSOID_GetDEREncoding
* NSSOID_GetUTF8Encoding
*/
extern const NSSOID *NSS_OID_UNKNOWN;
/*
* NSSOID_CreateFromBER
*
* This routine creates an NSSOID by decoding a BER- or DER-encoded
* OID. It may return NSS_OID_UNKNOWN upon error, in which case it
* will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_BER
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NSS_OID_UNKNOWN upon error
* An NSSOID upon success
*/
NSS_EXTERN NSSOID *
NSSOID_CreateFromBER
(
NSSBER *berOid
);
extern const NSSError NSS_ERROR_INVALID_BER;
extern const NSSError NSS_ERROR_NO_MEMORY;
/*
* NSSOID_CreateFromUTF8
*
* This routine creates an NSSOID by decoding a UTF8 string
* representation of an OID in dotted-number format. The string may
* optionally begin with an octothorpe. It may return NSS_OID_UNKNOWN
* upon error, in which case it will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_STRING
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NSS_OID_UNKNOWN upon error
* An NSSOID upon success
*/
NSS_EXTERN NSSOID *
NSSOID_CreateFromUTF8
(
NSSUTF8 *stringOid
);
extern const NSSError NSS_ERROR_INVALID_STRING;
extern const NSSError NSS_ERROR_NO_MEMORY;
/*
* NSSOID_GetDEREncoding
*
* This routine returns the DER encoding of the specified NSSOID.
* If the optional arena argument is non-null, the memory used will
* be obtained from that arena; otherwise, the memory will be obtained
* from the heap. This routine may return return null upon error, in
* which case it will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_NSSOID
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* The DER encoding of this NSSOID
*/
NSS_EXTERN NSSDER *
NSSOID_GetDEREncoding
(
const NSSOID *oid,
NSSDER *rvOpt,
NSSArena *arenaOpt
);
extern const NSSError NSS_ERROR_INVALID_NSSOID;
extern const NSSError NSS_ERROR_NO_MEMORY;
/*
* NSSOID_GetUTF8Encoding
*
* This routine returns a UTF8 string containing the dotted-number
* encoding of the specified NSSOID. If the optional arena argument
* is non-null, the memory used will be obtained from that arena;
* otherwise, the memory will be obtained from the heap. This routine
* may return null upon error, in which case it will have created an
* error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_NSSOID
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A pointer to a UTF8 string containing the dotted-digit encoding of
* this NSSOID
*/
NSS_EXTERN NSSUTF8 *
NSSOID_GetUTF8Encoding
(
const NSSOID *oid,
NSSArena *arenaOpt
);
extern const NSSError NSS_ERROR_INVALID_NSSOID;
extern const NSSError NSS_ERROR_NO_MEMORY;
/*
* NSSATAV
*
* The public "methods" regarding this "object" are:
*
* NSSATAV_CreateFromBER -- constructor
* NSSATAV_CreateFromUTF8 -- constructor
* NSSATAV_Create -- constructor
*
* NSSATAV_Destroy
* NSSATAV_GetDEREncoding
* NSSATAV_GetUTF8Encoding
* NSSATAV_GetType
* NSSATAV_GetValue
* NSSATAV_Compare
* NSSATAV_Duplicate
*/
/*
* NSSATAV_CreateFromBER
*
* This routine creates an NSSATAV by decoding a BER- or DER-encoded
* ATAV. If the optional arena argument is non-null, the memory used
* will be obtained from that arena; otherwise, the memory will be
* obtained from the heap. This routine may return NULL upon error,
* in which case it will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_BER
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A pointer to an NSSATAV upon success
*/
NSS_EXTERN NSSATAV *
NSSATAV_CreateFromBER
(
NSSArena *arenaOpt,
NSSBER *derATAV
);
extern const NSSError NSS_ERROR_INVALID_BER;
extern const NSSError NSS_ERROR_NO_MEMORY;
/*
* NSSATAV_CreateFromUTF8
*
* This routine creates an NSSATAV by decoding a UTF8 string in the
* "equals" format, e.g., "c=US." If the optional arena argument is
* non-null, the memory used will be obtained from that arena;
* otherwise, the memory will be obtained from the heap. This routine
* may return NULL upon error, in which case it will have created an
* error stack.
*
* The error may be one of the following values:
* NSS_ERROR_UNKNOWN_ATTRIBUTE
* NSS_ERROR_INVALID_STRING
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A pointer to an NSSATAV upon success
*/
NSS_EXTERN NSSATAV *
NSSATAV_CreateFromUTF8
(
NSSArena *arenaOpt,
NSSUTF8 *stringATAV
);
extern const NSSError NSS_ERROR_UNKNOWN_ATTRIBUTE;
extern const NSSError NSS_ERROR_INVALID_STRING;
extern const NSSError NSS_ERROR_NO_MEMORY;
/*
* NSSATAV_Create
*
* This routine creates an NSSATAV from the specified NSSOID and the
* specified data. If the optional arena argument is non-null, the
* memory used will be obtained from that arena; otherwise, the memory
* will be obtained from the heap.If the specified data length is zero,
* the data is assumed to be terminated by first zero byte; this allows
* UTF8 strings to be easily specified. This routine may return NULL
* upon error, in which case it will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_ARENA
* NSS_ERROR_INVALID_NSSOID
* NSS_ERROR_INVALID_POINTER
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A pointer to an NSSATAV upon success
*/
NSS_EXTERN NSSATAV *
NSSATAV_Create
(
NSSArena *arenaOpt,
const NSSOID *oid,
const void *data,
PRUint32 length
);
extern const NSSError NSS_ERROR_INVALID_ARENA;
extern const NSSError NSS_ERROR_INVALID_NSSOID;
extern const NSSError NSS_ERROR_INVALID_POINTER;
extern const NSSError NSS_ERROR_NO_MEMORY;
/*
* NSSATAV_Destroy
*
* This routine will destroy an ATAV object. It should eventually be
* called on all ATAVs created without an arena. While it is not
* necessary to call it on ATAVs created within an arena, it is not an
* error to do so. This routine returns a PRStatus value; if
* successful, it will return PR_SUCCESS. If unsuccessful, it will
* create an error stack and return PR_FAILURE.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_ATAV
*
* Return value:
* PR_FAILURE upon error
* PR_SUCCESS upon success
*/
NSS_EXTERN PRStatus
NSSATAV_Destroy
(
NSSATAV *atav
);
extern const NSSError NSS_ERROR_INVALID_ATAV;
/*
* NSSATAV_GetDEREncoding
*
* This routine will DER-encode an ATAV object. If the optional arena
* argument is non-null, the memory used will be obtained from that
* arena; otherwise, the memory will be obtained from the heap. This
* routine may return null upon error, in which case it will have
* created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_ATAV
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* The DER encoding of this NSSATAV
*/
NSS_EXTERN NSSDER *
NSSATAV_GetDEREncoding
(
NSSATAV *atav,
NSSArena *arenaOpt
);
extern const NSSError NSS_ERROR_INVALID_ATAV;
extern const NSSError NSS_ERROR_NO_MEMORY;
/*
* NSSATAV_GetUTF8Encoding
*
* This routine returns a UTF8 string containing a string
* representation of the ATAV in "equals" notation (e.g., "o=Acme").
* If the optional arena argument is non-null, the memory used will be
* obtained from that arena; otherwise, the memory will be obtained
* from the heap. This routine may return null upon error, in which
* case it will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_ATAV
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A pointer to a UTF8 string containing the "equals" encoding of the
* ATAV
*/
NSS_EXTERN NSSUTF8 *
NSSATAV_GetUTF8Encoding
(
NSSATAV *atav,
NSSArena *arenaOpt
);
extern const NSSError NSS_ERROR_INVALID_ATAV;
extern const NSSError NSS_ERROR_NO_MEMORY;
/*
* NSSATAV_GetType
*
* This routine returns the NSSOID corresponding to the attribute type
* in the specified ATAV. This routine may return NSS_OID_UNKNOWN
* upon error, in which case it will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_ATAV
*
* Return value:
* NSS_OID_UNKNOWN upon error
* An element of enum NSSOIDenum upon success
*/
NSS_EXTERN const NSSOID *
NSSATAV_GetType
(
NSSATAV *atav
);
extern const NSSError NSS_ERROR_INVALID_ATAV;
/*
* NSSATAV_GetValue
*
* This routine returns an NSSItem containing the attribute value
* in the specified ATAV. If the optional arena argument is non-null,
* the memory used will be obtained from that arena; otherwise, the
* memory will be obtained from the heap. This routine may return
* NULL upon error, in which case it will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_ATAV
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A pointer to an NSSItem containing the attribute value.
*/
NSS_EXTERN NSSUTF8 *
NSSATAV_GetValue
(
NSSATAV *atav,
NSSArena *arenaOpt
);
extern const NSSError NSS_ERROR_INVALID_ATAV;
extern const NSSError NSS_ERROR_NO_MEMORY;
/*
* NSSATAV_Compare
*
* This routine compares two ATAVs for equality. For two ATAVs to be
* equal, the attribute types must be the same, and the attribute
* values must have equal length and contents. The result of the
* comparison will be stored at the location pointed to by the "equalp"
* variable, which must point to a valid PRBool. This routine may
* return PR_FAILURE upon error, in which case it will have created an
* error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_ATAV
* NSS_ERROR_INVALID_ARGUMENT
*
* Return value:
* PR_FAILURE on error
* PR_SUCCESS upon a successful comparison (equal or not)
*/
NSS_EXTERN PRStatus
NSSATAV_Compare
(
NSSATAV *atav1,
NSSATAV *atav2,
PRBool *equalp
);
extern const NSSError NSS_ERROR_INVALID_ATAV;
extern const NSSError NSS_ERROR_INVALID_ARGUMENT;
/*
* NSSATAV_Duplicate
*
* This routine duplicates the specified ATAV. If the optional arena
* argument is non-null, the memory required will be obtained from
* that arena; otherwise, the memory will be obtained from the heap.
* This routine may return NULL upon error, in which case it will have
* created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_ATAV
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL on error
* A pointer to a new ATAV
*/
NSS_EXTERN NSSATAV *
NSSATAV_Duplicate
(
NSSATAV *atav,
NSSArena *arenaOpt
);
extern const NSSError NSS_ERROR_INVALID_ATAV;
extern const NSSError NSS_ERROR_NO_MEMORY;
/*
* NSSRDN
*
* The public "methods" regarding this "object" are:
*
* NSSRDN_CreateFromBER -- constructor
* NSSRDN_CreateFromUTF8 -- constructor
* NSSRDN_Create -- constructor
* NSSRDN_CreateSimple -- constructor
*
* NSSRDN_Destroy
* NSSRDN_GetDEREncoding
* NSSRDN_GetUTF8Encoding
* NSSRDN_AddATAV
* NSSRDN_GetATAVCount
* NSSRDN_GetATAV
* NSSRDN_GetSimpleATAV
* NSSRDN_Compare
* NSSRDN_Duplicate
*/
/*
* NSSRDN_CreateFromBER
*
* This routine creates an NSSRDN by decoding a BER- or DER-encoded
* RDN. If the optional arena argument is non-null, the memory used
* will be obtained from that arena; otherwise, the memory will be
* obtained from the heap. This routine may return NULL upon error,
* in which case it will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_BER
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A pointer to an NSSRDN upon success
*/
NSS_EXTERN NSSRDN *
NSSRDN_CreateFromBER
(
NSSArena *arenaOpt,
NSSBER *berRDN
);
/*
* NSSRDN_CreateFromUTF8
*
* This routine creates an NSSRDN by decoding an UTF8 string
* consisting of either a single ATAV in the "equals" format, e.g.,
* "uid=smith," or one or more such ATAVs in parentheses, e.g.,
* "(sn=Smith,ou=Sales)." If the optional arena argument is non-null,
* the memory used will be obtained from that arena; otherwise, the
* memory will be obtained from the heap. This routine may return
* NULL upon error, in which case it will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_UNKNOWN_ATTRIBUTE
* NSS_ERROR_INVALID_STRING
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A pointer to an NSSRDN upon success
*/
NSS_EXTERN NSSRDN *
NSSRDN_CreateFromUTF8
(
NSSArena *arenaOpt,
NSSUTF8 *stringRDN
);
/*
* NSSRDN_Create
*
* This routine creates an NSSRDN from one or more NSSATAVs. The
* final argument to this routine must be NULL. If the optional arena
* argument is non-null, the memory used will be obtained from that
* arena; otherwise, the memory will be obtained from the heap. This
* routine may return NULL upon error, in which case it will have
* created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_NO_MEMORY
* NSS_ERROR_INVALID_ATAV
*
* Return value:
* NULL upon error
* A pointer to an NSSRDN upon success
*/
NSS_EXTERN NSSRDN *
NSSRDN_Create
(
NSSArena *arenaOpt,
NSSATAV *atav1,
...
);
/*
* NSSRDN_CreateSimple
*
* This routine creates a simple NSSRDN from a single NSSATAV. If the
* optional arena argument is non-null, the memory used will be
* obtained from that arena; otherwise, the memory will be obtained
* from the heap. This routine may return NULL upon error, in which
* case it will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_NO_MEMORY
* NSS_ERROR_INVALID_ATAV
*
* Return value:
* NULL upon error
* A pointer to an NSSRDN upon success
*/
NSS_EXTERN NSSRDN *
NSSRDN_CreateSimple
(
NSSArena *arenaOpt,
NSSATAV *atav
);
/*
* NSSRDN_Destroy
*
* This routine will destroy an RDN object. It should eventually be
* called on all RDNs created without an arena. While it is not
* necessary to call it on RDNs created within an arena, it is not an
* error to do so. This routine returns a PRStatus value; if
* successful, it will return PR_SUCCESS. If unsuccessful, it will
* create an error stack and return PR_FAILURE.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_RDN
*
* Return value:
* PR_FAILURE upon failure
* PR_SUCCESS upon success
*/
NSS_EXTERN PRStatus
NSSRDN_Destroy
(
NSSRDN *rdn
);
/*
* NSSRDN_GetDEREncoding
*
* This routine will DER-encode an RDN object. If the optional arena
* argument is non-null, the memory used will be obtained from that
* arena; otherwise, the memory will be obtained from the heap. This
* routine may return null upon error, in which case it will have
* created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_RDN
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* The DER encoding of this NSSRDN
*/
NSS_EXTERN NSSDER *
NSSRDN_GetDEREncoding
(
NSSRDN *rdn,
NSSArena *arenaOpt
);
/*
* NSSRDN_GetUTF8Encoding
*
* This routine returns a UTF8 string containing a string
* representation of the RDN. A simple (one-ATAV) RDN will be simply
* the string representation of that ATAV; a non-simple RDN will be in
* parenthesised form. If the optional arena argument is non-null,
* the memory used will be obtained from that arena; otherwise, the
* memory will be obtained from the heap. This routine may return
* null upon error, in which case it will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_RDN
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A pointer to a UTF8 string
*/
NSS_EXTERN NSSUTF8 *
NSSRDN_GetUTF8Encoding
(
NSSRDN *rdn,
NSSArena *arenaOpt
);
/*
* NSSRDN_AddATAV
*
* This routine adds an ATAV to the set of ATAVs in the specified RDN.
* Remember that RDNs consist of an unordered set of ATAVs. If the
* RDN was created with a non-null arena argument, that same arena
* will be used for any additional required memory. If the RDN was
* created with a NULL arena argument, any additional memory will
* be obtained from the heap. This routine returns a PRStatus value;
* it will return PR_SUCCESS upon success, and upon failure it will
* create an error stack and return PR_FAILURE.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_RDN
* NSS_ERROR_INVALID_ATAV
* NSS_ERROR_NO_MEMORY
*
* Return value:
* PR_SUCCESS upon success
* PR_FAILURE upon failure
*/
NSS_EXTERN PRStatus
NSSRDN_AddATAV
(
NSSRDN *rdn,
NSSATAV *atav
);
/*
* NSSRDN_GetATAVCount
*
* This routine returns the cardinality of the set of ATAVs within
* the specified RDN. This routine may return 0 upon error, in which
* case it will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_RDN
*
* Return value:
* 0 upon error
* A positive number upon success
*/
NSS_EXTERN PRUint32
NSSRDN_GetATAVCount
(
NSSRDN *rdn
);
/*
* NSSRDN_GetATAV
*
* This routine returns a pointer to an ATAV that is a member of
* the set of ATAVs within the specified RDN. While the set of
* ATAVs within an RDN is unordered, this routine will return
* distinct values for distinct values of 'i' as long as the RDN
* is not changed in any way. The RDN may be changed by calling
* NSSRDN_AddATAV. The value of the variable 'i' is on the range
* [0,c) where c is the cardinality returned from NSSRDN_GetATAVCount.
* The caller owns the ATAV the pointer to which is returned. If the
* optional arena argument is non-null, the memory used will be
* obtained from that arena; otherwise, the memory will be obtained
* from the heap. This routine may return NULL upon error, in which
* case it will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_RDN
* NSS_ERROR_VALUE_OUT_OF_RANGE
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A caller-owned pointer to an NSSATAV
*/
NSS_EXTERN NSSATAV *
NSSRDN_GetATAV
(
NSSRDN *rdn,
NSSArena *arenaOpt,
PRUint32 i
);
/*
* NSSRDN_GetSimpleATAV
*
* Most RDNs are actually very simple, with a single ATAV. This
* routine will return the single ATAV from such an RDN. The caller
* owns the ATAV the pointer to which is returned. If the optional
* arena argument is non-null, the memory used will be obtained from
* that arena; otherwise, the memory will be obtained from the heap.
* This routine may return NULL upon error, including the case where
* the set of ATAVs in the RDN is nonsingular. Upon error, this
* routine will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_RDN
* NSS_ERROR_RDN_NOT_SIMPLE
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A caller-owned pointer to an NSSATAV
*/
NSS_EXTERN NSSATAV *
NSSRDN_GetSimpleATAV
(
NSSRDN *rdn,
NSSArena *arenaOpt
);
/*
* NSSRDN_Compare
*
* This routine compares two RDNs for equality. For two RDNs to be
* equal, they must have the same number of ATAVs, and every ATAV in
* one must be equal to an ATAV in the other. (Note that the sets
* of ATAVs are unordered.) The result of the comparison will be
* stored at the location pointed to by the "equalp" variable, which
* must point to a valid PRBool. This routine may return PR_FAILURE
* upon error, in which case it will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_RDN
* NSS_ERROR_INVALID_ARGUMENT
*
* Return value:
* PR_FAILURE on error
* PR_SUCCESS upon a successful comparison (equal or not)
*/
NSS_EXTERN PRStatus
NSSRDN_Compare
(
NSSRDN *rdn1,
NSSRDN *rdn2,
PRBool *equalp
);
/*
* NSSRDN_Duplicate
*
* This routine duplicates the specified RDN. If the optional arena
* argument is non-null, the memory required will be obtained from
* that arena; otherwise, the memory will be obtained from the heap.
* This routine may return NULL upon error, in which case it will have
* created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_RDN
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL on error
* A pointer to a new RDN
*/
NSS_EXTERN NSSRDN *
NSSRDN_Duplicate
(
NSSRDN *rdn,
NSSArena *arenaOpt
);
/*
* NSSRDNSeq
*
* The public "methods" regarding this "object" are:
*
* NSSRDNSeq_CreateFromBER -- constructor
* NSSRDNSeq_CreateFromUTF8 -- constructor
* NSSRDNSeq_Create -- constructor
*
* NSSRDNSeq_Destroy
* NSSRDNSeq_GetDEREncoding
* NSSRDNSeq_GetUTF8Encoding
* NSSRDNSeq_AppendRDN
* NSSRDNSeq_GetRDNCount
* NSSRDNSeq_GetRDN
* NSSRDNSeq_Compare
* NSSRDNSeq_Duplicate
*/
/*
* NSSRDNSeq_CreateFromBER
*
* This routine creates an NSSRDNSeq by decoding a BER- or DER-encoded
* sequence of RDNs. If the optional arena argument is non-null,
* the memory used will be obtained from that arena; otherwise, the
* memory will be obtained from the heap. This routine may return
* NULL upon error, in which case it will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_BER
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A pointer to an NSSRDNSeq upon success
*/
NSS_EXTERN NSSRDNSeq *
NSSRDNSeq_CreateFromBER
(
NSSArena *arenaOpt,
NSSBER *berRDNSeq
);
/*
* NSSRDNSeq_CreateFromUTF8
*
* This routine creates an NSSRDNSeq by decoding a UTF8 string
* consisting of a comma-separated sequence of RDNs, such as
* "(sn=Smith,ou=Sales),o=Acme,c=US." If the optional arena argument
* is non-null, the memory used will be obtained from that arena;
* otherwise, the memory will be obtained from the heap. This routine
* may return NULL upon error, in which case it will have created an
* error stack.
*
* The error may be one of the following values:
* NSS_ERROR_UNKNOWN_ATTRIBUTE
* NSS_ERROR_INVALID_STRING
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A pointer to an NSSRDNSeq upon success
*/
NSS_EXTERN NSSRDNSeq *
NSSRDNSeq_CreateFromUTF8
(
NSSArena *arenaOpt,
NSSUTF8 *stringRDNSeq
);
/*
* NSSRDNSeq_Create
*
* This routine creates an NSSRDNSeq from one or more NSSRDNs. The
* final argument to this routine must be NULL. If the optional arena
* argument is non-null, the memory used will be obtained from that
* arena; otherwise, the memory will be obtained from the heap. This
* routine may return NULL upon error, in which case it will have
* created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_NO_MEMORY
* NSS_ERROR_INVALID_RDN
*
* Return value:
* NULL upon error
* A pointero to an NSSRDNSeq upon success
*/
NSS_EXTERN NSSRDNSeq *
NSSRDNSeq_Create
(
NSSArena *arenaOpt,
NSSRDN *rdn1,
...
);
/*
* NSSRDNSeq_Destroy
*
* This routine will destroy an RDNSeq object. It should eventually
* be called on all RDNSeqs created without an arena. While it is not
* necessary to call it on RDNSeqs created within an arena, it is not
* an error to do so. This routine returns a PRStatus value; if
* successful, it will return PR_SUCCESS. If unsuccessful, it will
* create an error stack and return PR_FAILURE.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_RDNSEQ
*
* Return value:
* PR_FAILURE upon error
* PR_SUCCESS upon success
*/
NSS_EXTERN PRStatus
NSSRDNSeq_Destroy
(
NSSRDNSeq *rdnseq
);
/*
* NSSRDNSeq_GetDEREncoding
*
* This routine will DER-encode an RDNSeq object. If the optional
* arena argument is non-null, the memory used will be obtained from
* that arena; otherwise, the memory will be obtained from the heap.
* This routine may return null upon error, in which case it will have
* created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_RDNSEQ
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* The DER encoding of this NSSRDNSeq
*/
NSS_EXTERN NSSDER *
NSSRDNSeq_GetDEREncoding
(
NSSRDNSeq *rdnseq,
NSSArena *arenaOpt
);
/*
* NSSRDNSeq_GetUTF8Encoding
*
* This routine returns a UTF8 string containing a string
* representation of the RDNSeq as a comma-separated sequence of RDNs.
* If the optional arena argument is non-null, the memory used will be
* obtained from that arena; otherwise, the memory will be obtained
* from the heap. This routine may return null upon error, in which
* case it will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_RDNSEQ
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A pointer to the UTF8 string
*/
NSS_EXTERN NSSUTF8 *
NSSRDNSeq_GetUTF8Encoding
(
NSSRDNSeq *rdnseq,
NSSArena *arenaOpt
);
/*
* NSSRDNSeq_AppendRDN
*
* This routine appends an RDN to the end of the existing RDN
* sequence. If the RDNSeq was created with a non-null arena
* argument, that same arena will be used for any additional required
* memory. If the RDNSeq was created with a NULL arena argument, any
* additional memory will be obtained from the heap. This routine
* returns a PRStatus value; it will return PR_SUCCESS upon success,
* and upon failure it will create an error stack and return PR_FAILURE.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_RDNSEQ
* NSS_ERROR_INVALID_RDN
* NSS_ERROR_NO_MEMORY
*
* Return value:
* PR_SUCCESS upon success
* PR_FAILURE upon failure
*/
NSS_EXTERN PRStatus
NSSRDNSeq_AppendRDN
(
NSSRDNSeq *rdnseq,
NSSRDN *rdn
);
/*
* NSSRDNSeq_GetRDNCount
*
* This routine returns the cardinality of the sequence of RDNs within
* the specified RDNSeq. This routine may return 0 upon error, in
* which case it will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_RDNSEQ
*
* Return value:
* 0 upon error
* A positive number upon success
*/
NSS_EXTERN PRUint32
NSSRDNSeq_GetRDNCount
(
NSSRDNSeq *rdnseq
);
/*
* NSSRDNSeq_GetRDN
*
* This routine returns a pointer to the i'th RDN in the sequence of
* RDNs that make up the specified RDNSeq. The sequence begins with
* the top-level (e.g., "c=US") RDN. The value of the variable 'i'
* is on the range [0,c) where c is the cardinality returned from
* NSSRDNSeq_GetRDNCount. The caller owns the RDN the pointer to which
* is returned. If the optional arena argument is non-null, the memory
* used will be obtained from that areana; otherwise, the memory will
* be obtained from the heap. This routine may return NULL upon error,
* in which case it will have created an error stack. Note that the
* usual string representation of RDN Sequences is from last to first.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_RDNSEQ
* NSS_ERROR_VALUE_OUT_OF_RANGE
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A caller-owned pointer to an NSSRDN
*/
NSS_EXTERN NSSRDN *
NSSRDNSeq_GetRDN
(
NSSRDNSeq *rdnseq,
NSSArena *arenaOpt,
PRUint32 i
);
/*
* NSSRDNSeq_Compare
*
* This routine compares two RDNSeqs for equality. For two RDNSeqs to
* be equal, they must have the same number of RDNs, and each RDN in
* one sequence must be equal to the corresponding RDN in the other
* sequence. The result of the comparison will be stored at the
* location pointed to by the "equalp" variable, which must point to a
* valid PRBool. This routine may return PR_FAILURE upon error, in
* which case it will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_RDNSEQ
* NSS_ERROR_INVALID_ARGUMENT
*
* Return value:
* PR_FAILURE on error
* PR_SUCCESS upon a successful comparison (equal or not)
*/
NSS_EXTERN PRStatus
NSSRDNSeq_Compare
(
NSSRDNSeq *rdnseq1,
NSSRDNSeq *rdnseq2,
PRBool *equalp
);
/*
* NSSRDNSeq_Duplicate
*
* This routine duplicates the specified RDNSeq. If the optional arena
* argument is non-null, the memory required will be obtained from that
* arena; otherwise, the memory will be obtained from the heap. This
* routine may return NULL upon error, in which case it will have
* created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_RDNSEQ
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A pointer to a new RDNSeq
*/
NSS_EXTERN NSSRDNSeq *
NSSRDNSeq_Duplicate
(
NSSRDNSeq *rdnseq,
NSSArena *arenaOpt
);
/*
* NSSName
*
* The public "methods" regarding this "object" are:
*
* NSSName_CreateFromBER -- constructor
* NSSName_CreateFromUTF8 -- constructor
* NSSName_Create -- constructor
*
* NSSName_Destroy
* NSSName_GetDEREncoding
* NSSName_GetUTF8Encoding
* NSSName_GetChoice
* NSSName_GetRDNSequence
* NSSName_GetSpecifiedChoice
* NSSName_Compare
* NSSName_Duplicate
*
* NSSName_GetUID
* NSSName_GetEmail
* NSSName_GetCommonName
* NSSName_GetOrganization
* NSSName_GetOrganizationalUnits
* NSSName_GetStateOrProvince
* NSSName_GetLocality
* NSSName_GetCountry
* NSSName_GetAttribute
*/
/*
* NSSName_CreateFromBER
*
* This routine creates an NSSName by decoding a BER- or DER-encoded
* (directory) Name. If the optional arena argument is non-null,
* the memory used will be obtained from that arena; otherwise,
* the memory will be obtained from the heap. This routine may
* return NULL upon error, in which case it will have created an error
* stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_BER
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A pointer to an NSSName upon success
*/
NSS_EXTERN NSSName *
NSSName_CreateFromBER
(
NSSArena *arenaOpt,
NSSBER *berName
);
/*
* NSSName_CreateFromUTF8
*
* This routine creates an NSSName by decoding a UTF8 string
* consisting of the string representation of one of the choices of
* (directory) names. Currently the only choice is an RDNSeq. If the
* optional arena argument is non-null, the memory used will be
* obtained from that arena; otherwise, the memory will be obtained
* from the heap. The routine may return NULL upon error, in which
* case it will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_STRING
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A pointer to an NSSName upon success
*/
NSS_EXTERN NSSName *
NSSName_CreateFromUTF8
(
NSSArena *arenaOpt,
NSSUTF8 *stringName
);
/*
* NSSName_Create
*
* This routine creates an NSSName with the specified choice of
* underlying name types. The value of the choice variable must be
* one of the values of the NSSNameChoice enumeration, and the type
* of the arg variable must be as specified in the following table:
*
* Choice Type
* ======================== ===========
* NSSNameChoiceRdnSequence NSSRDNSeq *
*
* If the optional arena argument is non-null, the memory used will
* be obtained from that arena; otherwise, the memory will be
* obtained from the heap. This routine may return NULL upon error,
* in which case it will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_CHOICE
* NSS_ERROR_INVALID_ARGUMENT
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A pointer to an NSSName upon success
*/
NSS_EXTERN NSSName *
NSSName_Create
(
NSSArena *arenaOpt,
NSSNameChoice choice,
void *arg
);
/*
* NSSName_Destroy
*
* This routine will destroy a Name object. It should eventually be
* called on all Names created without an arena. While it is not
* necessary to call it on Names created within an arena, it is not
* an error to do so. This routine returns a PRStatus value; if
* successful, it will return PR_SUCCESS. If unsuccessful, it will
* create an error stack and return PR_FAILURE.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_NAME
*
* Return value:
* PR_FAILURE upon error
* PR_SUCCESS upon success
*/
NSS_EXTERN PRStatus
NSSName_Destroy
(
NSSName *name
);
/*
* NSSName_GetDEREncoding
*
* This routine will DER-encode a name object. If the optional arena
* argument is non-null, the memory used will be obtained from that
* arena; otherwise, the memory will be obtained from the heap. This
* routine may return null upon error, in which case it will have
* created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_NAME
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* The DER encoding of this NSSName
*/
NSS_EXTERN NSSDER *
NSSName_GetDEREncoding
(
NSSName *name,
NSSArena *arenaOpt
);
/*
* NSSName_GetUTF8Encoding
*
* This routine returns a UTF8 string containing a string
* representation of the Name in the format specified by the
* underlying name choice. If the optional arena argument is non-null,
* the memory used will be obtained from that arena; otherwise, the
* memory will be obtained from the heap. This routine may return
* NULL upon error, in which case it will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_NAME
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A pointer to the UTF8 string
*/
NSS_EXTERN NSSUTF8 *
NSSName_GetUTF8Encoding
(
NSSName *name,
NSSArena *arenaOpt
);
/*
* NSSName_GetChoice
*
* This routine returns the type of the choice underlying the specified
* name. The return value will be a member of the NSSNameChoice
* enumeration. This routine may return NSSNameChoiceInvalid upon
* error, in which case it will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_NAME
*
* Return value:
* NSSNameChoiceInvalid upon error
* An other member of the NSSNameChoice enumeration upon success
*/
NSS_EXTERN NSSNameChoice
NSSName_GetChoice
(
NSSName *name
);
/*
* NSSName_GetRDNSequence
*
* If the choice underlying the specified NSSName is that of an
* RDNSequence, this routine will return a pointer to that RDN
* sequence. Otherwise, this routine will place an error on the
* error stack, and return NULL. If the optional arena argument is
* non-null, the memory required will be obtained from that arena;
* otherwise, the memory will be obtained from the heap. The
* caller owns the returned pointer. This routine may return NULL
* upon error, in which case it will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_NAME
* NSS_ERROR_WRONG_CHOICE
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A caller-owned pointer to an NSSRDNSeq
*/
NSS_EXTERN NSSRDNSeq *
NSSName_GetRDNSequence
(
NSSName *name,
NSSArena *arenaOpt
);
/*
* NSSName_GetSpecifiedChoice
*
* If the choice underlying the specified NSSName matches the specified
* choice, a caller-owned pointer to that underlying object will be
* returned. Otherwise, an error will be placed on the error stack and
* NULL will be returned. If the optional arena argument is non-null,
* the memory required will be obtained from that arena; otherwise, the
* memory will be obtained from the heap. The caller owns the returned
* pointer. This routine may return NULL upon error, in which case it
* will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_NAME
* NSS_ERROR_WRONG_CHOICE
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A caller-owned pointer, which must be typecast
*/
NSS_EXTERN void *
NSSName_GetSpecifiedChoice
(
NSSName *name,
NSSNameChoice choice,
NSSArena *arenaOpt
);
/*
* NSSName_Compare
*
* This routine compares two Names for equality. For two Names to be
* equal, they must have the same choice of underlying types, and the
* underlying values must be equal. The result of the comparison will
* be stored at the location pointed to by the "equalp" variable, which
* must point to a valid PRBool. This routine may return PR_FAILURE
* upon error, in which case it will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_NAME
* NSS_ERROR_INVALID_ARGUMENT
*
* Return value:
* PR_FAILURE on error
* PR_SUCCESS upon a successful comparison (equal or not)
*/
NSS_EXTERN PRStatus
NSSName_Compare
(
NSSName *name1,
NSSName *name2,
PRBool *equalp
);
/*
* NSSName_Duplicate
*
* This routine duplicates the specified nssname. If the optional
* arena argument is non-null, the memory required will be obtained
* from that arena; otherwise, the memory will be obtained from the
* heap. This routine may return NULL upon error, in which case it
* will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_NAME
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A pointer to a new NSSName
*/
NSS_EXTERN NSSName *
NSSName_Duplicate
(
NSSName *name,
NSSArena *arenaOpt
);
/*
* NSSName_GetUID
*
* This routine will attempt to derive a user identifier from the
* specified name, if the choices and content of the name permit.
* If the Name consists of a Sequence of Relative Distinguished
* Names containing a UID attribute, the UID will be the value of
* that attribute. Note that no UID attribute is defined in either
* PKIX or PKCS#9; rather, this seems to derive from RFC 1274, which
* defines the type as a caseIgnoreString. We'll return a Directory
* String. If the optional arena argument is non-null, the memory
* used will be obtained from that arena; otherwise, the memory will
* be obtained from the heap. This routine may return NULL upon error,
* in which case it will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_NAME
* NSS_ERROR_NO_UID
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A pointer to a UTF8 String.
*/
NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
NSSName_GetUID
(
NSSName *name,
NSSArena *arenaOpt
);
/*
* NSSName_GetEmail
*
* This routine will attempt to derive an email address from the
* specified name, if the choices and content of the name permit.
* If the Name consists of a Sequence of Relative Distinguished
* Names containing either a PKIX email address or a PKCS#9 email
* address, the result will be the value of that attribute. If the
* optional arena argument is non-null, the memory used will be
* obtained from that arena; otherwise, the memory will be obtained
* from the heap. This routine may return NULL upon error, in which
* case it will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_NAME
* NSS_ERROR_NO_EMAIL
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A pointer to a UTF8 String
*/
NSS_EXTERN NSSUTF8 * /* XXX fgmr IA5 String */
NSSName_GetEmail
(
NSSName *name,
NSSArena *arenaOpt
);
/*
* NSSName_GetCommonName
*
* This routine will attempt to derive a common name from the
* specified name, if the choices and content of the name permit.
* If the Name consists of a Sequence of Relative Distinguished Names
* containing a PKIX Common Name, the result will be that name. If
* the optional arena argument is non-null, the memory used will be
* obtained from that arena; otherwise, the memory will be obtained
* from the heap. This routine may return NULL upon error, in which
* case it will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_NAME
* NSS_ERROR_NO_COMMON_NAME
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A pointer to a UTF8 String
*/
NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
NSSName_GetCommonName
(
NSSName *name,
NSSArena *arenaOpt
);
/*
* NSSName_GetOrganization
*
* This routine will attempt to derive an organisation name from the
* specified name, if the choices and content of the name permit.
* If Name consists of a Sequence of Relative Distinguished names
* containing a PKIX Organization, the result will be the value of
* that attribute. If the optional arena argument is non-null, the
* memory used will be obtained from that arena; otherwise, the memory
* will be obtained from the heap. This routine may return NULL upon
* error, in which case it will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_NAME
* NSS_ERROR_NO_ORGANIZATION
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A pointer to a UTF8 String
*/
NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
NSSName_GetOrganization
(
NSSName *name,
NSSArena *arenaOpt
);
/*
* NSSName_GetOrganizationalUnits
*
* This routine will attempt to derive a sequence of organisational
* unit names from the specified name, if the choices and content of
* the name permit. If the Name consists of a Sequence of Relative
* Distinguished Names containing one or more organisational units,
* the result will be the values of those attributes. If the optional
* arena argument is non-null, the memory used will be obtained from
* that arena; otherwise, the memory will be obtained from the heap.
* This routine may return NULL upon error, in which case it will have
* created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_NAME
* NSS_ERROR_NO_ORGANIZATIONAL_UNITS
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A pointer to a null-terminated array of UTF8 Strings
*/
NSS_EXTERN NSSUTF8 ** /* XXX fgmr DirectoryString */
NSSName_GetOrganizationalUnits
(
NSSName *name,
NSSArena *arenaOpt
);
/*
* NSSName_GetStateOrProvince
*
* This routine will attempt to derive a state or province name from
* the specified name, if the choices and content of the name permit.
* If the Name consists of a Sequence of Relative Distinguished Names
* containing a state or province, the result will be the value of
* that attribute. If the optional arena argument is non-null, the
* memory used will be obtained from that arena; otherwise, the memory
* will be obtained from the heap. This routine may return NULL upon
* error, in which case it will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_NAME
* NSS_ERROR_NO_STATE_OR_PROVINCE
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A pointer to a UTF8 String
*/
NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
NSSName_GetStateOrProvince
(
NSSName *name,
NSSArena *arenaOpt
);
/*
* NSSName_GetLocality
*
* This routine will attempt to derive a locality name from the
* specified name, if the choices and content of the name permit. If
* the Name consists of a Sequence of Relative Distinguished names
* containing a Locality, the result will be the value of that
* attribute. If the optional arena argument is non-null, the memory
* used will be obtained from that arena; otherwise, the memory will
* be obtained from the heap. This routine may return NULL upon error,
* in which case it will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_NAME
* NSS_ERROR_NO_LOCALITY
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A pointer to a UTF8 String
*/
NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
NSSName_GetLocality
(
NSSName *name,
NSSArena *arenaOpt
);
/*
* NSSName_GetCountry
*
* This routine will attempt to derive a country name from the
* specified name, if the choices and content of the name permit.
* If the Name consists of a Sequence of Relative Distinguished
* Names containing a Country, the result will be the value of
* that attribute.. If the optional arena argument is non-null,
* the memory used will be obtained from that arena; otherwise,
* the memory will be obtained from the heap. This routine may
* return NULL upon error, in which case it will have created an
* error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_NAME
* NSS_ERROR_NO_COUNTRY
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A pointer to a UTF8 String
*/
NSS_EXTERN NSSUTF8 * /* XXX fgmr PrintableString */
NSSName_GetCountry
(
NSSName *name,
NSSArena *arenaOpt
);
/*
* NSSName_GetAttribute
*
* If the specified name consists of a Sequence of Relative
* Distinguished Names containing an attribute with the specified
* type, and the actual value of that attribute may be expressed
* with a Directory String, then the value of that attribute will
* be returned as a Directory String. If the optional arena argument
* is non-null, the memory used will be obtained from that arena;
* otherwise, the memory will be obtained from the heap. This routine
* may return NULL upon error, in which case it will have created an
* error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_NAME
* NSS_ERROR_NO_ATTRIBUTE
* NSS_ERROR_ATTRIBUTE_VALUE_NOT_STRING
*
* Return value:
* NULL upon error
* A pointer to a UTF8 String
*/
NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
NSSName_GetAttribute
(
NSSName *name,
NSSOID *attribute,
NSSArena *arenaOpt
);
/*
* NSSGeneralName
*
* The public "methods" regarding this "object" are:
*
* NSSGeneralName_CreateFromBER -- constructor
* NSSGeneralName_CreateFromUTF8 -- constructor
* NSSGeneralName_Create -- constructor
*
* NSSGeneralName_Destroy
* NSSGeneralName_GetDEREncoding
* NSSGeneralName_GetUTF8Encoding
* NSSGeneralName_GetChoice
* NSSGeneralName_GetOtherName
* NSSGeneralName_GetRfc822Name
* NSSGeneralName_GetDNSName
* NSSGeneralName_GetX400Address
* NSSGeneralName_GetDirectoryName
* NSSGeneralName_GetEdiPartyName
* NSSGeneralName_GetUniformResourceIdentifier
* NSSGeneralName_GetIPAddress
* NSSGeneralName_GetRegisteredID
* NSSGeneralName_GetSpecifiedChoice
* NSSGeneralName_Compare
* NSSGeneralName_Duplicate
*
* NSSGeneralName_GetUID
* NSSGeneralName_GetEmail
* NSSGeneralName_GetCommonName
* NSSGeneralName_GetOrganization
* NSSGeneralName_GetOrganizationalUnits
* NSSGeneralName_GetStateOrProvince
* NSSGeneralName_GetLocality
* NSSGeneralName_GetCountry
* NSSGeneralName_GetAttribute
*/
/*
* NSSGeneralName_CreateFromBER
*
* This routine creates an NSSGeneralName by decoding a BER- or DER-
* encoded general name. If the optional arena argument is non-null,
* the memory used will be obtained from that arena; otherwise, the
* memory will be obtained from the heap. This routine may return
* NULL upon error, in which case it will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_BER
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A pointer to an NSSGeneralName upon success
*/
NSS_EXTERN NSSGeneralName *
NSSGeneralName_CreateFromBER
(
NSSArena *arenaOpt,
NSSBER *berGeneralName
);
/*
* NSSGeneralName_CreateFromUTF8
*
* This routine creates an NSSGeneralName by decoding a UTF8 string
* consisting of the string representation of one of the choices of
* general names. If the optional arena argument is non-null, the
* memory used will be obtained from that arena; otherwise, the memory
* will be obtained from the heap. The routine may return NULL upon
* error, in which case it will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_STRING
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A pointer to an NSSGeneralName upon success
*/
NSS_EXTERN NSSGeneralName *
NSSGeneralName_CreateFromUTF8
(
NSSArena *arenaOpt,
NSSUTF8 *stringGeneralName
);
/*
* NSSGeneralName_Create
*
* This routine creates an NSSGeneralName with the specified choice of
* underlying name types. The value of the choice variable must be one
* of the values of the NSSGeneralNameChoice enumeration, and the type
* of the arg variable must be as specified in the following table:
*
* Choice Type
* ============================================ =========
* NSSGeneralNameChoiceOtherName
* NSSGeneralNameChoiceRfc822Name
* NSSGeneralNameChoiceDNSName
* NSSGeneralNameChoiceX400Address
* NSSGeneralNameChoiceDirectoryName NSSName *
* NSSGeneralNameChoiceEdiPartyName
* NSSGeneralNameChoiceUniformResourceIdentifier
* NSSGeneralNameChoiceIPAddress
* NSSGeneralNameChoiceRegisteredID
*
* If the optional arena argument is non-null, the memory used will
* be obtained from that arena; otherwise, the memory will be
* obtained from the heap. This routine may return NULL upon error,
* in which case it will have created an error stack.
*
* The error may be one fo the following values:
* NSS_ERROR_INVALID_CHOICE
* NSS_ERROR_INVALID_ARGUMENT
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A pointer to an NSSGeneralName upon success
*/
NSS_EXTERN NSSGeneralName *
NSSGeneralName_Create
(
NSSGeneralNameChoice choice,
void *arg
);
/*
* NSSGeneralName_Destroy
*
* This routine will destroy a General Name object. It should
* eventually be called on all General Names created without an arena.
* While it is not necessary to call it on General Names created within
* an arena, it is not an error to do so. This routine returns a
* PRStatus value; if successful, it will return PR_SUCCESS. If
* usuccessful, it will create an error stack and return PR_FAILURE.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_GENERAL_NAME
*
* Return value:
* PR_FAILURE upon failure
* PR_SUCCESS upon success
*/
NSS_EXTERN PRStatus
NSSGeneralName_Destroy
(
NSSGeneralName *generalName
);
/*
* NSSGeneralName_GetDEREncoding
*
* This routine will DER-encode a name object. If the optional arena
* argument is non-null, the memory used will be obtained from that
* arena; otherwise, the memory will be obtained from the heap. This
* routine may return null upon error, in which case it will have
* created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_GENERAL_NAME
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* The DER encoding of this NSSGeneralName
*/
NSS_EXTERN NSSDER *
NSSGeneralName_GetDEREncoding
(
NSSGeneralName *generalName,
NSSArena *arenaOpt
);
/*
* NSSGeneralName_GetUTF8Encoding
*
* This routine returns a UTF8 string containing a string
* representation of the General Name in the format specified by the
* underlying name choice. If the optional arena argument is
* non-null, the memory used will be obtained from that arena;
* otherwise, the memory will be obtained from the heap. This routine
* may return NULL upon error, in which case it will have created an
* error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_GENERAL_NAME
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A pointer to a UTF8 string
*/
NSS_EXTERN NSSUTF8 *
NSSGeneralName_GetUTF8Encoding
(
NSSGeneralName *generalName,
NSSArena *arenaOpt
);
/*
* NSSGeneralName_GetChoice
*
* This routine returns the type of choice underlying the specified
* general name. The return value will be a member of the
* NSSGeneralNameChoice enumeration. This routine may return
* NSSGeneralNameChoiceInvalid upon error, in which case it will have
* created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_GENERAL_NAME
*
* Return value:
* NSSGeneralNameChoiceInvalid upon error
* An other member of the NSSGeneralNameChoice enumeration
*/
NSS_EXTERN NSSGeneralNameChoice
NSSGeneralName_GetChoice
(
NSSGeneralName *generalName
);
/*
* NSSGeneralName_GetOtherName
*
* If the choice underlying the specified NSSGeneralName is that of an
* Other Name, this routine will return a pointer to that Other name.
* Otherwise, this routine will place an error on the error stack, and
* return NULL. If the optional arena argument is non-null, the memory
* required will be obtained from that arena; otherwise, the memory
* will be obtained from the heap. The caller owns the returned
* pointer. This routine may return NULL upon error, in which case it
* will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_GENERAL_NAME
* NSS_ERROR_WRONG_CHOICE
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A caller-owned pointer to an NSSOtherName
*/
NSS_EXTERN NSSOtherName *
NSSGeneralName_GetOtherName
(
NSSGeneralName *generalName,
NSSArena *arenaOpt
);
/*
* NSSGeneralName_GetRfc822Name
*
* If the choice underlying the specified NSSGeneralName is that of an
* RFC 822 Name, this routine will return a pointer to that name.
* Otherwise, this routine will place an error on the error stack, and
* return NULL. If the optional arena argument is non-null, the memory
* required will be obtained from that arena; otherwise, the memory
* will be obtained from the heap. The caller owns the returned
* pointer. This routine may return NULL upon error, in which case it
* will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_GENERAL_NAME
* NSS_ERROR_WRONG_CHOICE
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A caller-owned pointer to an NSSRFC822Name
*/
NSS_EXTERN NSSRFC822Name *
NSSGeneralName_GetRfc822Name
(
NSSGeneralName *generalName,
NSSArena *arenaOpt
);
/*
* NSSGeneralName_GetDNSName
*
* If the choice underlying the specified NSSGeneralName is that of a
* DNS Name, this routine will return a pointer to that DNS name.
* Otherwise, this routine will place an error on the error stack, and
* return NULL. If the optional arena argument is non-null, the memory
* required will be obtained from that arena; otherwise, the memory
* will be obtained from the heap. The caller owns the returned
* pointer. This routine may return NULL upon error, in which case it
* will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_GENERAL_NAME
* NSS_ERROR_WRONG_CHOICE
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A caller-owned pointer to an NSSDNSName
*/
NSS_EXTERN NSSDNSName *
NSSGeneralName_GetDNSName
(
NSSGeneralName *generalName,
NSSArena *arenaOpt
);
/*
* NSSGeneralName_GetX400Address
*
* If the choice underlying the specified NSSGeneralName is that of an
* X.400 Address, this routine will return a pointer to that Address.
* Otherwise, this routine will place an error on the error stack, and
* return NULL. If the optional arena argument is non-null, the memory
* required will be obtained from that arena; otherwise, the memory
* will be obtained from the heap. The caller owns the returned
* pointer. This routine may return NULL upon error, in which case it
* will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_GENERAL_NAME
* NSS_ERROR_WRONG_CHOICE
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A caller-owned pointer to an NSSX400Address
*/
NSS_EXTERN NSSX400Address *
NSSGeneralName_GetX400Address
(
NSSGeneralName *generalName,
NSSArena *arenaOpt
);
/*
* NSSGeneralName_GetDirectoryName
*
* If the choice underlying the specified NSSGeneralName is that of a
* (directory) Name, this routine will return a pointer to that name.
* Otherwise, this routine will place an error on the error stack, and
* return NULL. If the optional arena argument is non-null, the memory
* required will be obtained from that arena; otherwise, the memory
* will be obtained from the heap. The caller owns the returned
* pointer. This routine may return NULL upon error, in which case it
* will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_GENERAL_NAME
* NSS_ERROR_WRONG_CHOICE
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A caller-owned pointer to an NSSName
*/
NSS_EXTERN NSSName *
NSSGeneralName_GetName
(
NSSGeneralName *generalName,
NSSArena *arenaOpt
);
/*
* NSSGeneralName_GetEdiPartyName
*
* If the choice underlying the specified NSSGeneralName is that of an
* EDI Party Name, this routine will return a pointer to that name.
* Otherwise, this routine will place an error on the error stack, and
* return NULL. If the optional arena argument is non-null, the memory
* required will be obtained from that arena; otherwise, the memory
* will be obtained from the heap. The caller owns the returned
* pointer. This routine may return NULL upon error, in which case it
* will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_GENERAL_NAME
* NSS_ERROR_WRONG_CHOICE
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A caller-owned pointer to an NSSEdiPartyName
*/
NSS_EXTERN NSSEdiPartyName *
NSSGeneralName_GetEdiPartyName
(
NSSGeneralName *generalName,
NSSArena *arenaOpt
);
/*
* NSSGeneralName_GetUniformResourceIdentifier
*
* If the choice underlying the specified NSSGeneralName is that of a
* URI, this routine will return a pointer to that URI.
* Otherwise, this routine will place an error on the error stack, and
* return NULL. If the optional arena argument is non-null, the memory
* required will be obtained from that arena; otherwise, the memory
* will be obtained from the heap. The caller owns the returned
* pointer. This routine may return NULL upon error, in which case it
* will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_GENERAL_NAME
* NSS_ERROR_WRONG_CHOICE
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A caller-owned pointer to an NSSURI
*/
NSS_EXTERN NSSURI *
NSSGeneralName_GetUniformResourceIdentifier
(
NSSGeneralName *generalName,
NSSArena *arenaOpt
);
/*
* NSSGeneralName_GetIPAddress
*
* If the choice underlying the specified NSSGeneralName is that of an
* IP Address , this routine will return a pointer to that address.
* Otherwise, this routine will place an error on the error stack, and
* return NULL. If the optional arena argument is non-null, the memory
* required will be obtained from that arena; otherwise, the memory
* will be obtained from the heap. The caller owns the returned
* pointer. This routine may return NULL upon error, in which case it
* will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_GENERAL_NAME
* NSS_ERROR_WRONG_CHOICE
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A caller-owned pointer to an NSSIPAddress
*/
NSS_EXTERN NSSIPAddress *
NSSGeneralName_GetIPAddress
(
NSSGeneralName *generalName,
NSSArena *arenaOpt
);
/*
* NSSGeneralName_GetRegisteredID
*
* If the choice underlying the specified NSSGeneralName is that of a
* Registered ID, this routine will return a pointer to that ID.
* Otherwise, this routine will place an error on the error stack, and
* return NULL. If the optional arena argument is non-null, the memory
* required will be obtained from that arena; otherwise, the memory
* will be obtained from the heap. The caller owns the returned
* pointer. This routine may return NULL upon error, in which case it
* will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_GENERAL_NAME
* NSS_ERROR_WRONG_CHOICE
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A caller-owned pointer to an NSSRegisteredID
*/
NSS_EXTERN NSSRegisteredID *
NSSGeneralName_GetRegisteredID
(
NSSGeneralName *generalName,
NSSArena *arenaOpt
);
/*
* NSSGeneralName_GetSpecifiedChoice
*
* If the choice underlying the specified NSSGeneralName matches the
* specified choice, a caller-owned pointer to that underlying object
* will be returned. Otherwise, an error will be placed on the error
* stack and NULL will be returned. If the optional arena argument
* is non-null, the memory required will be obtained from that arena;
* otherwise, the memory will be obtained from the heap. The caller
* owns the returned pointer. This routine may return NULL upon
* error, in which caes it will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_GENERAL_NAME
* NSS_ERROR_WRONG_CHOICE
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A caller-owned pointer, which must be typecast
*/
NSS_EXTERN void *
NSSGeneralName_GetSpecifiedChoice
(
NSSGeneralName *generalName,
NSSGeneralNameChoice choice,
NSSArena *arenaOpt
);
/*
* NSSGeneralName_Compare
*
* This routine compares two General Names for equality. For two
* General Names to be equal, they must have the same choice of
* underlying types, and the underlying values must be equal. The
* result of the comparison will be stored at the location pointed
* to by the "equalp" variable, which must point to a valid PRBool.
* This routine may return PR_FAILURE upon error, in which case it
* will have created an error stack.
*
* The error may be one of the following value:
* NSS_ERROR_INVALID_GENERAL_NAME
* NSS_ERROR_INVALID_ARGUMENT
*
* Return value:
* PR_FAILURE upon error
* PR_SUCCESS upon a successful comparison (equal or not)
*/
NSS_EXTERN PRStatus
NSSGeneralName_Compare
(
NSSGeneralName *generalName1,
NSSGeneralName *generalName2,
PRBool *equalp
);
/*
* NSSGeneralName_Duplicate
*
* This routine duplicates the specified General Name. If the optional
* arena argument is non-null, the memory required will be obtained
* from that arena; otherwise, the memory will be obtained from the
* heap. This routine may return NULL upon error, in which case it
* will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_GENERAL_NAME
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A pointer to a new NSSGeneralName
*/
NSS_EXTERN NSSGeneralName *
NSSGeneralName_Duplicate
(
NSSGeneralName *generalName,
NSSArena *arenaOpt
);
/*
* NSSGeneralName_GetUID
*
* This routine will attempt to derive a user identifier from the
* specified general name, if the choices and content of the name
* permit. If the General Name is a (directory) Name consisting
* of a Sequence of Relative Distinguished Names containing a UID
* attribute, the UID will be the value of that attribute. Note
* that no UID attribute is defined in either PKIX or PKCS#9;
* rather, this seems to derive from RFC 1274, which defines the
* type as a caseIgnoreString. We'll return a Directory String.
* If the optional arena argument is non-null, the memory used
* will be obtained from that arena; otherwise, the memory will be
* obtained from the heap. This routine may return NULL upon error,
* in which case it will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_GENERAL_NAME
* NSS_ERROR_NO_UID
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A pointer to a UTF8 String.
*/
NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
NSSGeneralName_GetUID
(
NSSGeneralName *generalName,
NSSArena *arenaOpt
);
/*
* NSSGeneralName_GetEmail
*
* This routine will attempt to derive an email address from the
* specified general name, if the choices and content of the name
* permit. If the General Name is a (directory) Name consisting
* of a Sequence of Relative Distinguished names containing either
* a PKIX email address or a PKCS#9 email address, the result will
* be the value of that attribute. If the General Name is an RFC 822
* Name, the result will be the string form of that name. If the
* optional arena argument is non-null, the memory used will be
* obtained from that arena; otherwise, the memory will be obtained
* from the heap. This routine may return NULL upon error, in which
* case it will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_GENERAL_NAME
* NSS_ERROR_NO_EMAIL
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A pointer to a UTF8 String
*/
NSS_EXTERN NSSUTF8 * /* XXX fgmr IA5String */
NSSGeneralName_GetEmail
(
NSSGeneralName *generalName,
NSSArena *arenaOpt
);
/*
* NSSGeneralName_GetCommonName
*
* This routine will attempt to derive a common name from the
* specified general name, if the choices and content of the name
* permit. If the General Name is a (directory) Name consisting
* of a Sequence of Relative Distinguished names containing a PKIX
* Common Name, the result will be that name. If the optional arena
* argument is non-null, the memory used will be obtained from that
* arena; otherwise, the memory will be obtained from the heap. This
* routine may return NULL upon error, in which case it will have
* created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_GENERAL_NAME
* NSS_ERROR_NO_COMMON_NAME
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A pointer to a UTF8 String
*/
NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
NSSGeneralName_GetCommonName
(
NSSGeneralName *generalName,
NSSArena *arenaOpt
);
/*
* NSSGeneralName_GetOrganization
*
* This routine will attempt to derive an organisation name from the
* specified general name, if the choices and content of the name
* permit. If the General Name is a (directory) Name consisting
* of a Sequence of Relative Distinguished names containing an
* Organization, the result will be the value of that attribute.
* If the optional arena argument is non-null, the memory used will
* be obtained from that arena; otherwise, the memory will be obtained
* from the heap. This routine may return NULL upon error, in which
* case it will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_GENERAL_NAME
* NSS_ERROR_NO_ORGANIZATION
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A pointer to a UTF8 String
*/
NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
NSSGeneralName_GetOrganization
(
NSSGeneralName *generalName,
NSSArena *arenaOpt
);
/*
* NSSGeneralName_GetOrganizationalUnits
*
* This routine will attempt to derive a sequence of organisational
* unit names from the specified general name, if the choices and
* content of the name permit. If the General Name is a (directory)
* Name consisting of a Sequence of Relative Distinguished names
* containing one or more organisational units, the result will
* consist of those units. If the optional arena argument is non-
* null, the memory used will be obtained from that arena; otherwise,
* the memory will be obtained from the heap. This routine may return
* NULL upon error, in which case it will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_GENERAL_NAME
* NSS_ERROR_NO_ORGANIZATIONAL_UNITS
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A pointer to a null-terminated array of UTF8 Strings
*/
NSS_EXTERN NSSUTF8 ** /* XXX fgmr DirectoryString */
NSSGeneralName_GetOrganizationalUnits
(
NSSGeneralName *generalName,
NSSArena *arenaOpt
);
/*
* NSSGeneralName_GetStateOrProvince
*
* This routine will attempt to derive a state or province name from
* the specified general name, if the choices and content of the name
* permit. If the General Name is a (directory) Name consisting
* of a Sequence of Relative Distinguished names containing a state or
* province, the result will be the value of that attribute. If the
* optional arena argument is non-null, the memory used will be
* obtained from that arena; otherwise, the memory will be obtained
* from the heap. This routine may return NULL upon error, in which
* case it will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_GENERAL_NAME
* NSS_ERROR_NO_STATE_OR_PROVINCE
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A pointer to a UTF8 String
*/
NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
NSSGeneralName_GetStateOrProvince
(
NSSGeneralName *generalName,
NSSArena *arenaOpt
);
/*
* NSSGeneralName_GetLocality
*
* This routine will attempt to derive a locality name from
* the specified general name, if the choices and content of the name
* permit. If the General Name is a (directory) Name consisting
* of a Sequence of Relative Distinguished names containing a Locality,
* the result will be the value of that attribute. If the optional
* arena argument is non-null, the memory used will be obtained from
* that arena; otherwise, the memory will be obtained from the heap.
* This routine may return NULL upon error, in which case it will have
* created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_GENERAL_NAME
* NSS_ERROR_NO_LOCALITY
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A pointer to a UTF8 String
*/
NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
NSSGeneralName_GetLocality
(
NSSGeneralName *generalName,
NSSArena *arenaOpt
);
/*
* NSSGeneralName_GetCountry
*
* This routine will attempt to derive a country name from the
* specified general name, if the choices and content of the name
* permit. If the General Name is a (directory) Name consisting of a
* Sequence of Relative Distinguished names containing a Country, the
* result will be the value of that attribute. If the optional
* arena argument is non-null, the memory used will be obtained from
* that arena; otherwise, the memory will be obtained from the heap.
* This routine may return NULL upon error, in which case it will have
* created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_GENERAL_NAME
* NSS_ERROR_NO_COUNTRY
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A pointer to a UTF8 String
*/
NSS_EXTERN NSSUTF8 * /* XXX fgmr PrintableString */
NSSGeneralName_GetCountry
(
NSSGeneralName *generalName,
NSSArena *arenaOpt
);
/*
* NSSGeneralName_GetAttribute
*
* If the specified general name is a (directory) name consisting
* of a Sequence of Relative Distinguished Names containing an
* attribute with the specified type, and the actual value of that
* attribute may be expressed with a Directory String, then the
* value of that attribute will be returned as a Directory String.
* If the optional arena argument is non-null, the memory used will
* be obtained from that arena; otherwise, the memory will be obtained
* from the heap. This routine may return NULL upon error, in which
* case it will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_GENERAL_NAME
* NSS_ERROR_NO_ATTRIBUTE
* NSS_ERROR_ATTRIBUTE_VALUE_NOT_STRING
*
* Return value:
* NULL upon error
* A pointer to a UTF8 String
*/
NSS_EXTERN NSSUTF8 * /* XXX fgmr DirectoryString */
NSSGeneralName_GetAttribute
(
NSSGeneralName *generalName,
NSSOID *attribute,
NSSArena *arenaOpt
);
/*
* NSSGeneralNameSeq
*
* The public "methods" regarding this "object" are:
*
* NSSGeneralNameSeq_CreateFromBER -- constructor
* NSSGeneralNameSeq_Create -- constructor
*
* NSSGeneralNameSeq_Destroy
* NSSGeneralNameSeq_GetDEREncoding
* NSSGeneralNameSeq_AppendGeneralName
* NSSGeneralNameSeq_GetGeneralNameCount
* NSSGeneralNameSeq_GetGeneralName
* NSSGeneralNameSeq_Compare
* NSSGeneralnameSeq_Duplicate
*/
/*
* NSSGeneralNameSeq_CreateFromBER
*
* This routine creates a general name sequence by decoding a BER-
* or DER-encoded GeneralNames. If the optional arena argument is
* non-null, the memory used will be obtained from that arena;
* otherwise, the memory will be obtained from the heap. This routine
* may return NULL upon error, in which case it will have created an
* error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_BER
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A pointer to an NSSGeneralNameSeq upon success
*/
NSS_EXTERN NSSGeneralNameSeq *
NSSGeneralNameSeq_CreateFromBER
(
NSSArena *arenaOpt,
NSSBER *berGeneralNameSeq
);
/*
* NSSGeneralNameSeq_Create
*
* This routine creates an NSSGeneralNameSeq from one or more General
* Names. The final argument to this routine must be NULL. If the
* optional arena argument is non-null, the memory used will be
* obtained from that arena; otherwise, the memory will be obtained
* from the heap. This routine may return NULL upon error, in which
* case it will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_NO_MEMORY
* NSS_ERROR_INVALID_GENERAL_NAME
*
* Return value:
* NULL upon error
* A pointer to an NSSGeneralNameSeq upon success
*/
NSS_EXTERN NSSGeneralNameSeq *
NSSGeneralNameSeq_Create
(
NSSArena *arenaOpt,
NSSGeneralName *generalName1,
...
);
/*
* NSSGeneralNameSeq_Destroy
*
* This routine will destroy an NSSGeneralNameSeq object. It should
* eventually be called on all NSSGeneralNameSeqs created without an
* arena. While it is not necessary to call it on NSSGeneralNameSeq's
* created within an arena, it is not an error to do so. This routine
* returns a PRStatus value; if successful, it will return PR_SUCCESS.
* If unsuccessful, it will create an error stack and return PR_FAILURE.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_GENERAL_NAME_SEQ
*
* Return value:
* PR_FAILURE upon error
* PR_SUCCESS upon success
*/
NSS_EXTERN PRStatus
NSSGeneralNameSeq_Destroy
(
NSSGeneralNameSeq *generalNameSeq
);
/*
* NSSGeneralNameSeq_GetDEREncoding
*
* This routine will DER-encode an NSSGeneralNameSeq object. If the
* optional arena argument is non-null, the memory used will be
* obtained from that arena; otherwise, the memory will be obtained
* from the heap. This routine may return null upon error, in which
* case it will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_GENERAL_NAME_SEQ
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* The DER encoding of this NSSGeneralNameSeq
*/
NSS_EXTERN NSSDER *
NSSGeneralNameSeq_GetDEREncoding
(
NSSGeneralNameSeq *generalNameSeq,
NSSArena *arenaOpt
);
/*
* NSSGeneralNameSeq_AppendGeneralName
*
* This routine appends a General Name to the end of the existing
* General Name Sequence. If the sequence was created with a non-null
* arena argument, that same arena will be used for any additional
* required memory. If the sequence was created with a NULL arena
* argument, any additional memory will be obtained from the heap.
* This routine returns a PRStatus value; it will return PR_SUCCESS
* upon success, and upon failure it will create an error stack and
* return PR_FAILURE.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_GENERAL_NAME_SEQ
* NSS_ERROR_INVALID_GENERAL_NAME
* NSS_ERROR_NO_MEMORY
*
* Return value:
* PR_SUCCESS upon success
* PR_FAILURE upon failure.
*/
NSS_EXTERN PRStatus
NSSGeneralNameSeq_AppendGeneralName
(
NSSGeneralNameSeq *generalNameSeq,
NSSGeneralName *generalName
);
/*
* NSSGeneralNameSeq_GetGeneralNameCount
*
* This routine returns the cardinality of the specified General name
* Sequence. This routine may return 0 upon error, in which case it
* will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_GENERAL_NAME_SEQ
*
* Return value;
* 0 upon error
* A positive number upon success
*/
NSS_EXTERN PRUint32
NSSGeneralNameSeq_GetGeneralNameCount
(
NSSGeneralNameSeq *generalNameSeq
);
/*
* NSSGeneralNameSeq_GetGeneralName
*
* This routine returns a pointer to the i'th General Name in the
* specified General Name Sequence. The value of the variable 'i' is
* on the range [0,c) where c is the cardinality returned from
* NSSGeneralNameSeq_GetGeneralNameCount. The caller owns the General
* Name the pointer to which is returned. If the optional arena
* argument is non-null, the memory used will be obtained from that
* arena; otherwise, the memory will be obtained from the heap. This
* routine may return NULL upon error, in which case it will have
* created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_GENERAL_NAME_SEQ
* NSS_ERROR_VALUE_OUT_OF_RANGE
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A caller-owned pointer to a General Name.
*/
NSS_EXTERN NSSGeneralName *
NSSGeneralNameSeq_GetGeneralName
(
NSSGeneralNameSeq *generalNameSeq,
NSSArena *arenaOpt,
PRUint32 i
);
/*
* NSSGeneralNameSeq_Compare
*
* This routine compares two General Name Sequences for equality. For
* two General Name Sequences to be equal, they must have the same
* cardinality, and each General Name in one sequence must be equal to
* the corresponding General Name in the other. The result of the
* comparison will be stored at the location pointed to by the "equalp"
* variable, which must point to a valid PRBool. This routine may
* return PR_FAILURE upon error, in which case it will have created an
* error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_GENERAL_NAME_SEQ
* NSS_ERROR_INVALID_ARGUMENT
*
* Return value:
* PR_FAILURE upon error
* PR_SUCCESS upon a successful comparison (equal or not)
*/
NSS_EXTERN PRStatus
NSSGeneralNameSeq_Compare
(
NSSGeneralNameSeq *generalNameSeq1,
NSSGeneralNameSeq *generalNameSeq2,
PRBool *equalp
);
/*
* NSSGeneralNameSeq_Duplicate
*
* This routine duplicates the specified sequence of general names. If
* the optional arena argument is non-null, the memory required will be
* obtained from that arena; otherwise, the memory will be obtained
* from the heap. This routine may return NULL upon error, in which
* case it will have created an error stack.
*
* The error may be one of the following values:
* NSS_ERROR_INVALID_GENERAL_NAME_SEQ
* NSS_ERROR_NO_MEMORY
*
* Return value:
* NULL upon error
* A pointer to a new General Name Sequence.
*/
NSS_EXTERN NSSGeneralNameSeq *
NSSGeneralNameSeq_Duplicate
(
NSSGeneralNameSeq *generalNameSeq,
NSSArena *arenaOpt
);
PR_END_EXTERN_C
#endif /* NSSPT1M_H */
Ссылка в новой задаче Показать git blame Копировать постоянную ссылку