gecko/security/nss/lib/pki/nsspkit.h
2008-06-06 08:40:11 -04:00

275 lines
8.6 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 NSSPKIT_H
#define NSSPKIT_H
#ifdef DEBUG
static const char NSSPKIT_CVS_ID[] = "@(#) $RCSfile: nsspkit.h,v $ $Revision: 1.6 $ $Date: 2005/01/20 02:25:49 $";
#endif /* DEBUG */
/*
* nsspkit.h
*
* This file defines the types of the top-level PKI objects.
*/
#ifndef NSSBASET_H
#include "nssbaset.h"
#endif /* NSSBASET_H */
PR_BEGIN_EXTERN_C
/*
* NSSCertificate
*
* This is the public representation of a Certificate. The certificate
* may be one found on a smartcard or other token, one decoded from data
* received as part of a protocol, one constructed from constituent
* parts, etc. Usually it is associated with ("in") a trust domain; as
* it can be verified only within a trust domain. The underlying type
* of certificate may be of any supported standard, e.g. PKIX, PGP, etc.
*
* People speak of "verifying (with) the server's, or correspondant's,
* certificate"; for simple operations we support that simplification
* by implementing public-key crypto operations as methods on this type.
*/
struct NSSCertificateStr;
typedef struct NSSCertificateStr NSSCertificate;
/*
* NSSUserCertificate
*
* A ``User'' certificate is one for which the private key is available.
* People speak of "using my certificate to sign my email" and "using
* my certificate to authenticate to (or login to) the server"; for
* simple operations, we support that simplification by implementing
* private-key crypto operations as methods on this type.
*
* The current design only weakly distinguishes between certificates
* and user certificates: as far as the compiler goes they're
* interchangable; debug libraries only have one common pointer-tracker;
* etc. However, attempts to do private-key operations on a certificate
* for which the private key is not available will fail.
*
* Open design question: should these types be more firmly separated?
*/
typedef NSSCertificate NSSUserCertificate;
/*
* NSSPrivateKey
*
* This is the public representation of a Private Key. In general,
* the actual value of the key is not available, but operations may
* be performed with it.
*/
struct NSSPrivateKeyStr;
typedef struct NSSPrivateKeyStr NSSPrivateKey;
/*
* NSSPublicKey
*
*/
struct NSSPublicKeyStr;
typedef struct NSSPublicKeyStr NSSPublicKey;
/*
* NSSSymmetricKey
*
*/
struct NSSSymmetricKeyStr;
typedef struct NSSSymmetricKeyStr NSSSymmetricKey;
/*
* NSSTrustDomain
*
* A Trust Domain is the field in which certificates may be validated.
* A trust domain will generally have one or more cryptographic modules
* open; these modules perform the cryptographic operations, and
* provide the basic "root" trust information from which the trust in
* a specific certificate or key depends.
*
* A client program, or a simple server, would typically have one
* trust domain. A server supporting multiple "virtual servers" might
* have a separate trust domain for each virtual server. The separate
* trust domains might share some modules (e.g., a hardware crypto
* accelerator) but not others (e.g., the tokens storing the different
* servers' private keys, or the databases with each server's trusted
* root certificates).
*
* This object descends from the "permananet database" in the old code.
*/
struct NSSTrustDomainStr;
typedef struct NSSTrustDomainStr NSSTrustDomain;
/*
* NSSCryptoContext
*
* A Crypto Context is a short-term, "helper" object which is used
* for the lifetime of one ongoing "crypto operation." Such an
* operation may be the creation of a signed message, the use of an
* TLS socket connection, etc. Each crypto context is "in" a
* specific trust domain, and it may have associated with it a
* distinguished certificate, public key, private key, and/or
* symmetric key. It can also temporarily hold and use temporary
* data (e.g. intermediate certificates) which is not stored
* permanently in the trust domain.
*
* In OO terms, this interface inherits interfaces from the trust
* domain, the certificates, and the keys. It also provides
* streaming crypto operations.
*
* This object descends from the "temporary database" concept in the
* old code, but it has changed a lot as a result of what we've
* learned.
*/
typedef struct NSSCryptoContextStr NSSCryptoContext;
/*
* fgmr others
*/
/*
* NSSTime
*
* Unfortunately, we need an "exceptional" value to indicate
* an error upon return, or "no value" on input. Note that zero
* is a perfectly valid value for both time_t and PRTime.
*
* If we were to create a "range" object, with two times for
* Not Before and Not After, we would have an obvious place for
* the somewhat arbitrary logic involved in comparing them.
*
* Failing that, let's have an NSSTime_CompareRanges function.
*/
struct NSSTimeStr;
typedef struct NSSTimeStr NSSTime;
struct NSSTrustStr;
typedef struct NSSTrustStr NSSTrust;
/*
* NSSUsage
*
* This is trickier than originally planned; I'll write up a
* doc on it.
*
* We'd still like nsspki.h to have a list of common usages,
* e.g.:
*
* extern const NSSUsage *NSSUsage_ClientAuth;
* extern const NSSUsage *NSSUsage_ServerAuth;
* extern const NSSUsage *NSSUsage_SignEmail;
* extern const NSSUsage *NSSUsage_EncryptEmail;
* etc.
*/
struct NSSUsageStr;
typedef struct NSSUsageStr NSSUsage;
/*
* NSSPolicies
*
* Placeholder, for now.
*/
struct NSSPoliciesStr;
typedef struct NSSPoliciesStr NSSPolicies;
/*
* NSSAlgorithmAndParameters
*
* Algorithm is an OID
* Parameters depend on the algorithm
*/
struct NSSAlgorithmAndParametersStr;
typedef struct NSSAlgorithmAndParametersStr NSSAlgorithmAndParameters;
/*
* NSSCallback
*
* At minimum, a "challenge" method and a closure argument.
* Usually the challenge will just be prompting for a password.
* How OO do we want to make it?
*/
typedef struct NSSCallbackStr NSSCallback;
struct NSSCallbackStr {
/* Prompt for a password to initialize a slot. */
PRStatus (* getInitPW)(NSSUTF8 *slotName, void *arg,
NSSUTF8 **ssoPW, NSSUTF8 **userPW);
/* Prompt for oldPW and newPW in order to change the
* password on a slot.
*/
PRStatus (* getNewPW)(NSSUTF8 *slotName, PRUint32 *retries, void *arg,
NSSUTF8 **oldPW, NSSUTF8 **newPW);
/* Prompt for slot password. */
PRStatus (* getPW)(NSSUTF8 *slotName, PRUint32 *retries, void *arg,
NSSUTF8 **password);
void *arg;
};
/* set errors - user cancelled, ... */
typedef PRUint32 NSSOperations;
/* 1) Do we want these to be preprocessor definitions or constants? */
/* 2) What is the correct and complete list? */
#define NSSOperations_ENCRYPT 0x0001
#define NSSOperations_DECRYPT 0x0002
#define NSSOperations_WRAP 0x0004
#define NSSOperations_UNWRAP 0x0008
#define NSSOperations_SIGN 0x0010
#define NSSOperations_SIGN_RECOVER 0x0020
#define NSSOperations_VERIFY 0x0040
#define NSSOperations_VERIFY_RECOVER 0x0080
struct NSSPKIXCertificateStr;
PR_END_EXTERN_C
#endif /* NSSPKIT_H */