import FIREFOX_52_6_0esr_RELEASE from mozilla-esr52 hg repo

security/nss/lib/pki/nsspkit.h

@@ -0,0 +1,247 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+#ifndef NSSPKIT_H
+#define NSSPKIT_H
+
+/*
+ * 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
+ * interchangeable; 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
+ */
+
+/*
+ * OBJECT IDENTIFIER
+ *
+ * This is the basic OID that crops up everywhere.
+ */
+
+struct NSSOIDStr; /* unused opaque structure */
+typedef struct NSSOIDStr NSSOID;
+
+/*
+ * 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 */