1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/security/nss/lib/pki/nsspkit.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,247 @@
1.4 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.5 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.6 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.7 +
1.8 +#ifndef NSSPKIT_H
1.9 +#define NSSPKIT_H
1.10 +
1.11 +/*
1.12 + * nsspkit.h
1.13 + *
1.14 + * This file defines the types of the top-level PKI objects.
1.15 + */
1.16 +
1.17 +#ifndef NSSBASET_H
1.18 +#include "nssbaset.h"
1.19 +#endif /* NSSBASET_H */
1.20 +
1.21 +PR_BEGIN_EXTERN_C
1.22 +
1.23 +/*
1.24 + * NSSCertificate
1.25 + *
1.26 + * This is the public representation of a Certificate. The certificate
1.27 + * may be one found on a smartcard or other token, one decoded from data
1.28 + * received as part of a protocol, one constructed from constituent
1.29 + * parts, etc. Usually it is associated with ("in") a trust domain; as
1.30 + * it can be verified only within a trust domain. The underlying type
1.31 + * of certificate may be of any supported standard, e.g. PKIX, PGP, etc.
1.32 + *
1.33 + * People speak of "verifying (with) the server's, or correspondant's,
1.34 + * certificate"; for simple operations we support that simplification
1.35 + * by implementing public-key crypto operations as methods on this type.
1.36 + */
1.37 +
1.38 +struct NSSCertificateStr;
1.39 +typedef struct NSSCertificateStr NSSCertificate;
1.40 +
1.41 +/*
1.42 + * NSSUserCertificate
1.43 + *
1.44 + * A ``User'' certificate is one for which the private key is available.
1.45 + * People speak of "using my certificate to sign my email" and "using
1.46 + * my certificate to authenticate to (or login to) the server"; for
1.47 + * simple operations, we support that simplification by implementing
1.48 + * private-key crypto operations as methods on this type.
1.49 + *
1.50 + * The current design only weakly distinguishes between certificates
1.51 + * and user certificates: as far as the compiler goes they're
1.52 + * interchangeable; debug libraries only have one common pointer-tracker;
1.53 + * etc. However, attempts to do private-key operations on a certificate
1.54 + * for which the private key is not available will fail.
1.55 + *
1.56 + * Open design question: should these types be more firmly separated?
1.57 + */
1.58 +
1.59 +typedef NSSCertificate NSSUserCertificate;
1.60 +
1.61 +/*
1.62 + * NSSPrivateKey
1.63 + *
1.64 + * This is the public representation of a Private Key. In general,
1.65 + * the actual value of the key is not available, but operations may
1.66 + * be performed with it.
1.67 + */
1.68 +
1.69 +struct NSSPrivateKeyStr;
1.70 +typedef struct NSSPrivateKeyStr NSSPrivateKey;
1.71 +
1.72 +/*
1.73 + * NSSPublicKey
1.74 + *
1.75 + */
1.76 +
1.77 +struct NSSPublicKeyStr;
1.78 +typedef struct NSSPublicKeyStr NSSPublicKey;
1.79 +
1.80 +/*
1.81 + * NSSSymmetricKey
1.82 + *
1.83 + */
1.84 +
1.85 +struct NSSSymmetricKeyStr;
1.86 +typedef struct NSSSymmetricKeyStr NSSSymmetricKey;
1.87 +
1.88 +/*
1.89 + * NSSTrustDomain
1.90 + *
1.91 + * A Trust Domain is the field in which certificates may be validated.
1.92 + * A trust domain will generally have one or more cryptographic modules
1.93 + * open; these modules perform the cryptographic operations, and
1.94 + * provide the basic "root" trust information from which the trust in
1.95 + * a specific certificate or key depends.
1.96 + *
1.97 + * A client program, or a simple server, would typically have one
1.98 + * trust domain. A server supporting multiple "virtual servers" might
1.99 + * have a separate trust domain for each virtual server. The separate
1.100 + * trust domains might share some modules (e.g., a hardware crypto
1.101 + * accelerator) but not others (e.g., the tokens storing the different
1.102 + * servers' private keys, or the databases with each server's trusted
1.103 + * root certificates).
1.104 + *
1.105 + * This object descends from the "permananet database" in the old code.
1.106 + */
1.107 +
1.108 +struct NSSTrustDomainStr;
1.109 +typedef struct NSSTrustDomainStr NSSTrustDomain;
1.110 +
1.111 +/*
1.112 + * NSSCryptoContext
1.113 + *
1.114 + * A Crypto Context is a short-term, "helper" object which is used
1.115 + * for the lifetime of one ongoing "crypto operation." Such an
1.116 + * operation may be the creation of a signed message, the use of an
1.117 + * TLS socket connection, etc. Each crypto context is "in" a
1.118 + * specific trust domain, and it may have associated with it a
1.119 + * distinguished certificate, public key, private key, and/or
1.120 + * symmetric key. It can also temporarily hold and use temporary
1.121 + * data (e.g. intermediate certificates) which is not stored
1.122 + * permanently in the trust domain.
1.123 + *
1.124 + * In OO terms, this interface inherits interfaces from the trust
1.125 + * domain, the certificates, and the keys. It also provides
1.126 + * streaming crypto operations.
1.127 + *
1.128 + * This object descends from the "temporary database" concept in the
1.129 + * old code, but it has changed a lot as a result of what we've
1.130 + * learned.
1.131 + */
1.132 +
1.133 +typedef struct NSSCryptoContextStr NSSCryptoContext;
1.134 +
1.135 +/*
1.136 + * fgmr others
1.137 + */
1.138 +
1.139 +/*
1.140 + * OBJECT IDENTIFIER
1.141 + *
1.142 + * This is the basic OID that crops up everywhere.
1.143 + */
1.144 +
1.145 +struct NSSOIDStr; /* unused opaque structure */
1.146 +typedef struct NSSOIDStr NSSOID;
1.147 +
1.148 +/*
1.149 + * NSSTime
1.150 + *
1.151 + * Unfortunately, we need an "exceptional" value to indicate
1.152 + * an error upon return, or "no value" on input. Note that zero
1.153 + * is a perfectly valid value for both time_t and PRTime.
1.154 + *
1.155 + * If we were to create a "range" object, with two times for
1.156 + * Not Before and Not After, we would have an obvious place for
1.157 + * the somewhat arbitrary logic involved in comparing them.
1.158 + *
1.159 + * Failing that, let's have an NSSTime_CompareRanges function.
1.160 + */
1.161 +
1.162 +struct NSSTimeStr;
1.163 +typedef struct NSSTimeStr NSSTime;
1.164 +
1.165 +struct NSSTrustStr;
1.166 +typedef struct NSSTrustStr NSSTrust;
1.167 +
1.168 +/*
1.169 + * NSSUsage
1.170 + *
1.171 + * This is trickier than originally planned; I'll write up a
1.172 + * doc on it.
1.173 + *
1.174 + * We'd still like nsspki.h to have a list of common usages,
1.175 + * e.g.:
1.176 + *
1.177 + * extern const NSSUsage *NSSUsage_ClientAuth;
1.178 + * extern const NSSUsage *NSSUsage_ServerAuth;
1.179 + * extern const NSSUsage *NSSUsage_SignEmail;
1.180 + * extern const NSSUsage *NSSUsage_EncryptEmail;
1.181 + * etc.
1.182 + */
1.183 +
1.184 +struct NSSUsageStr;
1.185 +typedef struct NSSUsageStr NSSUsage;
1.186 +
1.187 +/*
1.188 + * NSSPolicies
1.189 + *
1.190 + * Placeholder, for now.
1.191 + */
1.192 +
1.193 +struct NSSPoliciesStr;
1.194 +typedef struct NSSPoliciesStr NSSPolicies;
1.195 +
1.196 +/*
1.197 + * NSSAlgorithmAndParameters
1.198 + *
1.199 + * Algorithm is an OID
1.200 + * Parameters depend on the algorithm
1.201 + */
1.202 +
1.203 +struct NSSAlgorithmAndParametersStr;
1.204 +typedef struct NSSAlgorithmAndParametersStr NSSAlgorithmAndParameters;
1.205 +
1.206 +/*
1.207 + * NSSCallback
1.208 + *
1.209 + * At minimum, a "challenge" method and a closure argument.
1.210 + * Usually the challenge will just be prompting for a password.
1.211 + * How OO do we want to make it?
1.212 + */
1.213 +
1.214 +typedef struct NSSCallbackStr NSSCallback;
1.215 +
1.216 +struct NSSCallbackStr {
1.217 + /* Prompt for a password to initialize a slot. */
1.218 + PRStatus (* getInitPW)(NSSUTF8 *slotName, void *arg,
1.219 + NSSUTF8 **ssoPW, NSSUTF8 **userPW);
1.220 + /* Prompt for oldPW and newPW in order to change the
1.221 + * password on a slot.
1.222 + */
1.223 + PRStatus (* getNewPW)(NSSUTF8 *slotName, PRUint32 *retries, void *arg,
1.224 + NSSUTF8 **oldPW, NSSUTF8 **newPW);
1.225 + /* Prompt for slot password. */
1.226 + PRStatus (* getPW)(NSSUTF8 *slotName, PRUint32 *retries, void *arg,
1.227 + NSSUTF8 **password);
1.228 + void *arg;
1.229 +};
1.230 +
1.231 +/* set errors - user cancelled, ... */
1.232 +
1.233 +typedef PRUint32 NSSOperations;
1.234 +/* 1) Do we want these to be preprocessor definitions or constants? */
1.235 +/* 2) What is the correct and complete list? */
1.236 +
1.237 +#define NSSOperations_ENCRYPT 0x0001
1.238 +#define NSSOperations_DECRYPT 0x0002
1.239 +#define NSSOperations_WRAP 0x0004
1.240 +#define NSSOperations_UNWRAP 0x0008
1.241 +#define NSSOperations_SIGN 0x0010
1.242 +#define NSSOperations_SIGN_RECOVER 0x0020
1.243 +#define NSSOperations_VERIFY 0x0040
1.244 +#define NSSOperations_VERIFY_RECOVER 0x0080
1.245 +
1.246 +struct NSSPKIXCertificateStr;
1.247 +
1.248 +PR_END_EXTERN_C
1.249 +
1.250 +#endif /* NSSPKIT_H */
