nzt.h

ORACLE访问接口

};

/*
 * The wallet contains, one or more personas.  A persona always
 * contains its private key and its identity.  It may also contain
 * other 3rd party identites.  All identities qualified with trust
 * where the qualifier can indicate anything from untrusted to trusted
 * for specific operations.
 */

/*
 * Persona
 *
 * Structure containing information about a persona.
 */
struct nzttPersona
{
   ub1 *genericName_nzttPersona;              /* user-friendly persona name  */
   ub4  genericNamelen_nzttPersona;           /* persona-name length */
   nzttUsage usage_nzttPersona;               /* persona usage; SSL/SET/.. */
   nzttState state_nzttPersona;               /* persona state-requested/ready */
   nzttPersonaPrivate *private_nzttPersona;   /* Opaque part of persona */
   nzttIdentity *mycertreqs_nzttPersona;      /* My cert-requests */
   nzttIdentity *mycerts_nzttPersona;         /* My certificates */
   nzttIdentity *mytps_nzttPersona;           /* List of trusted identities */
   struct nzttPersona *next_nzttPersona;      /* Next persona */
#ifdef NZDEPRECATED
   ub4 ntps_nzttPersona;                   /* Num of trusted identities */
#endif
};

/*
 * Identity
 *
 * Structure containing information about an identity.
 *
 * NOTE
 *  -- the next_trustpoint field only applies to trusted identities and
 *     has no meaning (i.e. is NULL) for self identities.
 */
struct nzttIdentity
{
   text *dn_nzttIdentity;                      /* Alias */
   ub4 dnlen_nzttIdentity;                  /* Length of alias */
   text *comment_nzttIdentity;                 /* Comment  */
   ub4 commentlen_nzttIdentity;             /* Length of comment */
   nzttIdentityPrivate *private_nzttIdentity;  /* Opaque part of identity */
   nzttIdentity *next_nzttIdentity;            /* next identity in list */
};

struct nzttPKCS7ProtInfo
{
   nzttCipherType mictype_nzttPKCS7ProtInfo;    /* Hash cipher */
   nzttCipherType symmtype_nzttPKCS7ProtInfo;   /* Symmetric cipher */
   ub4 keylen_nzttPKCS7ProtInfo;             /* Length of key to use */
};
typedef struct nzttPKCS7ProtInfo nzttPKCS7ProtInfo;

/*
 * Protection Information.
 *
 * Information specific to a type of protection.
 */
union nzttProtInfo
{
   nzttPKCS7ProtInfo pkcs7_nzttProtInfo;
};
typedef union nzttProtInfo nzttProtInfo;

/*
 * A description of a persona so that the toolkit can create one.  A
 * persona can be symmetric or asymmetric and both contain an
 * identity.  The identity for an asymmetric persona will be the
 * certificate and the identity for the symmetric persona will be
 * descriptive information about the persona.  In either case, an
 * identity will have been created before the persona is created.
 *
 * A persona can be stored separately from the wallet that references
 * it.  By default, a persona is stored with the wallet (it inherits
 * with WRL used to open the wallet).  If a WRL is specified, then it
 * is used to store the actuall persona and the wallet will have a
 * reference to it.
 */
struct nzttPersonaDesc
{
   ub4 privlen_nzttPersonaDesc;        /* Length of private info (key)*/
   ub1 *priv_nzttPersonaDesc;             /* Private information */
   ub4 prllen_nzttPersonaDesc;         /* Length of PRL */
   text *prl_nzttPersonaDesc;             /* PRL for storage */
   ub4 aliaslen_nzttPersonaDesc;       /* Length of alias */
   text *alias_nzttPersonaDesc;           /* Alias */
   ub4 longlen_nzttPersonaDesc;        /* Length of longer description*/
   text *long_nzttPersonaDesc;            /* Longer persona description */
};
typedef struct nzttPersonaDesc nzttPersonaDesc;

/*
 * A description of an identity so that the toolkit can create one.
 * Since an identity can be symmetric or asymmetric, the asymmetric
 * identity information will not be used when a symmetric identity is
 * created.  This means the publen_nzttIdentityDesc and
 * pub_nzttIdentityDesc members will not be used when creating a
 * symmetric identity.
 */
struct nzttIdentityDesc
{
   ub4 publen_nzttIdentityDesc;        /* Length of identity */
   ub1 *pub_nzttIdentityDesc;             /* Type specific identity */
   ub4 dnlen_nzttIdentityDesc;         /* Length of alias */
   text *dn_nzttIdentityDesc;             /* Alias */
   ub4 longlen_nzttIdentityDesc;       /* Length of longer description */
   text *long_nzttIdentityDesc;           /* Longer description */
   ub4 quallen_nzttIdentityDesc;       /* Length of trust qualifier */
   text *trustqual_nzttIdentityDesc;      /* Trust qualifier */
};
typedef struct nzttIdentityDesc nzttIdentityDesc;

/********************************/
/* PUBLIC FUNCTION DECLARATIONS */
/********************************/

/*---------------------- nztwOpenWallet ----------------------*/

/*
 * NAME
 *    nztwOpenWallet - Open a wallet based on a wallet Resource Locator (WRL).
 * 
 * PARAMETERS
 *    osscntxt {IN}     OSS context. 
 *    wrllen   {IN}     Length of WRL.
 *    wrl      {IN}     WRL.
 *    pwdlen   {IN}     Length of password.
 *    pwd      {IN}     Password.
 *    wallet   {IN/OUT} Initialized wallet structure.   
 * 
 * NOTES
 *    The syntax for a WRL is <Wallet Type>:<Wallet Type Parameters>.
 *
 *    Wallet Type       Wallet Type Parameters.
 *    -----------       ----------------------
 *    File              Pathname (e.g. "file:/home/asriniva")
 *    Oracle            Connect string (e.g. "oracle:scott/tiger@oss")
 *
 *    There are also defaults.  If the WRL is NZT_DEFAULT_WRL, then
 *    the platform specific WRL default is used.  If only the wallet
 *    type is specified, then the WRL type specific default is used
 *    (e.g. "oracle:")
 *
 *    There is an implication with Oracle that should be stated: An
 *    Oracle based wallet can be implemented in a user's private space
 *    or in world readable space.
 *
 *    When the wallet is opened, the password is verified by hashing
 *    it and comparing against the password hash stored with the
 *    wallet.  The list of personas (and their associated identities)
 *    is built and stored into the wallet structure.
 *    
 * RETURNS
 *    NZERROR_OK           Success.
 *    NZERROR_RIO_OPEN     RIO could not open wallet (see network trace file).
 *    NZERROR_TK_PASSWORD  Password verification failed.
 *    NZERROR_TK_WRLTYPE   WRL type is not known.
 *    NZERROR_TK_WRLPARM   WRL parm does not match type.
 */
#ifdef __STDC__
nzerror nztwOpenWallet(nzctx *, ub4, text *, ub4, text *, 
                           nzttWallet *);
#else
nzerror nztwOpenWallet(/*_ nzctx *, ub4, text *, ub4, text *, 
                           nzttWallet * _*/);
#endif /* __STDC __*/

/*---------------------- nztwCloseWallet ----------------------*/

/*
 * NAME
 *    nztwCloseWallet - Close a wallet
 * 
 * PARAMETERS
 *    osscntxt {IN}     OSS context.
 *    wallet   {IN/OUT} Wallet.
 * 
 * NOTES
 *    Closing a wallet also closes all personas associated with that
 *    wallet.  It does not cause a persona to automatically be saved
 *    if it has changed.  The implication is that a persona can be
 *    modified by an application but if it is not explicitly saved it
 *    reverts back to what was in the wallet.
 *
 * RETURNS
 *    NZERROR_OK           Success.
 *    NZERROR_RIO_CLOSE    RIO could not close wallet (see network trace file).
 */
#ifdef __STDC__
nzerror nztwCloseWallet(nzctx *, nzttWallet *);
#else
nzerror nztwCloseWallet(/*_ nzctx *, nzttWallet * _*/);
#endif /* __STDC__ */

/*------------------------ nztwConstructWallet -----------------------*/
/*
 * 
 * nzerror nztwConstructWallet( nzctx *oss_context, 	
 *				  nzttPolicy openPolicy,
 *				  nzttPolicy securePolicy,
 *				  ub1 *ldapName,
 *				  ub4 ldapNamelen,
 *				  nzstrc *wrl,
 *				  nzttPersona *personas,
 *				  nzttWallet **wallet );
 */

/*---------------------- nztwRetrievePersonaCopy ----------------------*/

/*
 * NAME
 *    nztwRetrievePersonaCopy - Retrieves a persona based from wallet
 * 
 * PARAMETERS
 *    osscntxt {IN}     OSS context. 
 *    wallet   {IN}     Wallet.
 *    index    {IN}     Which wallet index to remove (first persona is zero).
 *    persona  {OUT}    Persona found.
 * 
 * NOTES
 *    Retrieves a persona from the wallet based on the index number passed
 *    in.  This persona is a COPY of the one stored in the wallet, therefore
 *    it is perfectly fine for the wallet to be closed after this call is 
 *    made.
 *
 *    The caller is responsible for disposing of the persona when completed.
 *
 * RETURNS
 *    NZERROR_OK           Success.
 */
#ifdef __STDC__
nzerror nztwRetrievePersonaCopy(nzctx *, nzttWallet *, ub4, nzttPersona **);
#else
nzerror nztwRetrievePersonaCopy(/*_ nzctx *, nzttWallet *, ub4, 
                           nzttPersona ** _*/);
#endif /* __STDC __*/


/*---------------------- nzteOpenPersona ----------------------*/

/*
 * NAME
 *    nzteOpenPersona - Open a persona.
 * 
 * PARAMETERS
 *    osscntxt {IN}     OSS context. 
 *    persona  {IN/OUT} Persona.
 * 
 * NOTES
 *    
 * RETURNS
 *    NZERROR_OK           Success.
 *    NZERROR_TK_PASSWORD  Password failed to decrypt persona.
 *    NZERROR_TK_BADPRL    Persona resource locator did not work.
 *    NZERROR_RIO_OPEN     Could not open persona (see network trace file).
 */
#ifdef __STDC__
nzerror nzteOpenPersona(nzctx *, nzttPersona *);
#else
nzerror nzteOpenPersona(/*_ nzctx *, nzttPersona * _*/);
#endif /* __STDC __*/

/*--------------------- nzteClosePersona ---------------------*/

/*
 * NAME
 *    nzteClosePersona - Close a persona.
 * 
 * PARAMETERS
 *    osscntxt {IN}     OSS context.
 *    persona  {IN/OUT} Persona.
 * 
 * NOTES
 *    Closing a persona does not store the persona, it simply releases
 *    the memory associated with the crypto engine.
 *    
 * RETURNS
 *    NZERROR_OK        Success.
 */
#ifdef __STDC__
nzerror nzteClosePersona(nzctx *, nzttPersona *);
#else
nzerror nzteClosePersona(/*_ nzctx *, nzttPersona * _*/);
#endif /* __STDC __*/

/*--------------------- nzteDestroyPersona ---------------------*/

/*
 * NAME
 *    nzteDestroyPersona - Destroy a persona.
 * 
 * PARAMETERS
 *    osscntxt {IN}        OSS context.
 *    persona  {IN/OUT}    Persona.
 * 
 * NOTES
 *    The persona is destroyd in the open state, but it will
 *    not be associated with a wallet.
 *    
 *    The persona parameter is doubly indirect so that at the
 *    conclusion of the function, the pointer can be set to NULL.
 *
 *
 * RETURNS
 *    NZERROR_OK        Success.
 *    NZERROR_TK_TYPE   Unsupported itype/ctype combination.
 *    NZERROR_TK_PARMS  Error in persona description.
 */
#ifdef __STDC__
nzerror nzteDestroyPersona(nzctx *,  nzttPersona **);
#else
nzerror nzteDestroyPersona(/*_ nzctx *, nzttPersona ** _*/);
#endif /* __STDC __*/

/*---------------------- nzteRetrieveTrustedIdentCopy ----------------------*/

/*
 * NAME
 *    nzteRetrieveTrustedIdentCopy - Retrieves a trusted identity from persona
 * 
 * PARAMETERS
 *    osscntxt {IN}     OSS context. 
 *    persona  {IN}     Persona.
 *    index    {IN}     Which wallet index to remove (first element is zero).
 *    identity {OUT}    Trusted Identity from this persona.
 * 
 * NOTES
 *    Retrieves a trusted identity from the persona based on the index 
 *    number passed in.  This identity is a COPY of the one stored in 
 *    the persona, therefore it is perfectly fine to close the persona
 *    after this call is made.
 *
 *    The caller is responsible for freeing the memory of this object 
 *    by calling nztiAbortIdentity it is no longer needed
 *
 * RETURNS
 *    NZERROR_OK           Success.
 */
#ifdef __STDC__
nzerror nzteRetrieveTrustedIdentCopy(nzctx *, nzttPersona *, ub4, 
				     nzttIdentity **);
#else
nzerror nzteRetrieveTrustedIdentCopy(/*_ nzctx *, nzttPersona *, ub4, 
                           nzttIdentity ** _*/);
#endif /* __STDC __*/

/*--------------------- nztePriKey ---------------------*/

/*
 * NAME
 *    nztePriKey - Get the decrypted Private Key for the Persona
 * 
 * PARAMETERS
 *    osscntxt {IN}     OSS context.
 *    persona  {IN}     Persona.
 *    vkey     {OUT}    Private Key [B_KEY_OBJ]
 *    vkey_len {OUT}    Private Key Length
 * 
 * NOTES
 *    This funiction will only work for X.509 based persona which contain
 *    a private key.  
 *    A copy of the private key is returned to the caller so that they do not 
 *    have to worry about the key changeing "underneath them".
 *    Memory will be allocated for the vkey and therefore, the CALLER
 *    will be responsible for freeing this memory.
 *
 * RETURNS
 *    NZERROR_OK           Success.
 *    NZERROR_NO_MEMORY    ossctx is null.
 *    NZERROR_TK_BADPRL    Persona resource locator did not work.
 */
#ifdef __STDC__
nzerror nztePriKey(nzctx *, nzttPersona *, ub1 **, ub4 *);
#else
nzerror nztePriKey(/*_ nzctx *, nzttPersona *, ub1 **, ub4 * _*/);
#endif /* __STDC __*/

/*--------------------- nzteMyCert ---------------------*/

/*
 * NAME
 *    nzteMyCert - Get the X.509 Certificate for a persona
 * 
 * PARAMETERS
 *    osscntxt {IN}     OSS context.
 *    persona  {IN}     Persona.
 *    cert     {OUT}    X.509 Certificate [BER encoded]
 *    cert_len {OUT}    Certificate length
 * 
 * NOTES
 *    This funiction will only work for X.509 based persona which contain
 *    a certificate for the self identity. 
 *    A copy of the certificate is returned to the caller so that they do not 
 *    have to worry about the certificate changeing "underneath them".
 *    Memory will be allocated for the cert and therefore, the CALLER
 *    will be responsible for freeing this memory.
 *
 * RETURNS
 *    NZERROR_OK           Success.
 *    NZERROR_NO_MEMORY    ossctx is null.
 */
#ifdef __STDC__
nzerror nzteMyCert(nzctx *, nzttPersona *, ub1 **, ub4 *);
#else
nzerror nzteMyCert(/*_ nzctx *, nzttPersona *, ub1 **, ub4 * _*/);
#endif /* __STDC __*/