diff options
Diffstat (limited to 'cpp/include/IceSSL/Plugin.h')
| -rw-r--r-- | cpp/include/IceSSL/Plugin.h | 539 |
1 files changed, 322 insertions, 217 deletions
diff --git a/cpp/include/IceSSL/Plugin.h b/cpp/include/IceSSL/Plugin.h index 0bfc483a09a..3215624a830 100644 --- a/cpp/include/IceSSL/Plugin.h +++ b/cpp/include/IceSSL/Plugin.h @@ -36,22 +36,31 @@ namespace IceSSL { -// -// This exception is thrown if the certificate cannot be read. -// +/** + * Thrown if the certificate cannot be read. + * \headerfile IceSSL/IceSSL.h + */ class ICESSL_API CertificateReadException : public IceUtil::ExceptionHelper<CertificateReadException> { public: CertificateReadException(const char*, int, const std::string&); + #ifndef ICE_CPP11_COMPILER virtual ~CertificateReadException() throw(); #endif + virtual std::string ice_id() const; + #ifndef ICE_CPP11_MAPPING + /** + * Creates a shallow copy of this exception. + * @return The new exception instance. + */ virtual CertificateReadException* ice_clone() const; #endif + /** The reason for the exception. */ std::string reason; private: @@ -59,22 +68,31 @@ private: static const char* _name; }; -// -// This exception is thrown if the certificate cannot be encoded. -// +/** + * Thrown if the certificate cannot be encoded. + * \headerfile IceSSL/IceSSL.h + */ class ICESSL_API CertificateEncodingException : public IceUtil::ExceptionHelper<CertificateEncodingException> { public: CertificateEncodingException(const char*, int, const std::string&); + #ifndef ICE_CPP11_COMPILER virtual ~CertificateEncodingException() throw(); #endif + virtual std::string ice_id() const; + #ifndef ICE_CPP11_MAPPING + /** + * Creates a shallow copy of this exception. + * @return The new exception instance. + */ virtual CertificateEncodingException* ice_clone() const; #endif + /** The reason for the exception. */ std::string reason; private: @@ -82,22 +100,31 @@ private: static const char* _name; }; -// -// This exception is thrown if a distinguished name cannot be parsed. -// +/** + * This exception is thrown if a distinguished name cannot be parsed. + * \headerfile IceSSL/IceSSL.h + */ class ICESSL_API ParseException : public IceUtil::ExceptionHelper<ParseException> { public: ParseException(const char*, int, const std::string&); + #ifndef ICE_CPP11_COMPILER virtual ~ParseException() throw(); #endif + virtual std::string ice_id() const; + #ifndef ICE_CPP11_MAPPING + /** + * Creates a shallow copy of this exception. + * @return The new exception instance. + */ virtual ParseException* ice_clone() const; #endif + /** The reason for the exception. */ std::string reason; private: @@ -105,61 +132,76 @@ private: static const char* _name; }; -// -// This class represents a DistinguishedName, similar to the Java -// type X500Principal and the .NET type X500DistinguishedName. -// -// For comparison purposes, the value of a relative distinguished -// name (RDN) component is always unescaped before matching, -// therefore "ZeroC, Inc." will match ZeroC\, Inc. -// -// toString() always returns exactly the same information as was -// provided in the constructor (i.e., "ZeroC, Inc." will not turn -// into ZeroC\, Inc.). -// +/** + * This class represents a DistinguishedName, similar to the Java + * type X500Principal and the .NET type X500DistinguishedName. + * + * For comparison purposes, the value of a relative distinguished + * name (RDN) component is always unescaped before matching, + * therefore "ZeroC, Inc." will match ZeroC\, Inc. + * + * toString() always returns exactly the same information as was + * provided in the constructor (i.e., "ZeroC, Inc." will not turn + * into ZeroC\, Inc.). + * \headerfile IceSSL/IceSSL.h + */ class ICESSL_API DistinguishedName { public: - // - // Create a DistinguishedName from a string encoded using - // the rules in RFC2253. - // - // Throws ParseException if parsing fails. - // - explicit DistinguishedName(const std::string&); - - // - // Create a DistinguishedName from a list of RDN pairs, - // where each pair consists of the RDN's type and value. - // For example, the RDN "O=ZeroC" is represented by the - // pair ("O", "ZeroC"). - // + /** + * Creates a DistinguishedName from a string encoded using the rules in RFC2253. + * @param name The encoded distinguished name. + * @throws ParseException if parsing fails. + */ + explicit DistinguishedName(const std::string& name); + + /** + * Creates a DistinguishedName from a list of RDN pairs, + * where each pair consists of the RDN's type and value. + * For example, the RDN "O=ZeroC" is represented by the + * pair ("O", "ZeroC"). + * @throws ParseException if parsing fails. + */ explicit DistinguishedName(const std::list<std::pair<std::string, std::string> >&); - // - // This is an exact match. The order of the RDN components is - // important. - // + /** + * Performs an exact match. The order of the RDN components is important. + */ friend ICESSL_API bool operator==(const DistinguishedName&, const DistinguishedName&); + + /** + * Performs an exact match. The order of the RDN components is important. + */ friend ICESSL_API bool operator<(const DistinguishedName&, const DistinguishedName&); - // - // Perform a partial match with another DistinguishedName. The function - // returns true if all of the RDNs in the argument are present in this - // DistinguishedName and they have the same values. - // - bool match(const DistinguishedName&) const; - bool match(const std::string&) const; - - // - // Encode the DN in RFC2253 format. - // + /** + * Performs a partial match with another DistinguishedName. + * @param dn The name to be matched. + * @return True if all of the RDNs in the argument are present in this + * DistinguishedName and they have the same values. + */ + bool match(const DistinguishedName& dn) const; + + /** + * Performs a partial match with another DistinguishedName. + * @param dn The name to be matched. + * @return True if all of the RDNs in the argument are present in this + * DistinguishedName and they have the same values. + */ + bool match(const std::string& dn) const; + + /** + * Encodes the DN in RFC2253 format. + * @return An encoded string. + */ operator std::string() const; protected: + /// \cond INTERNAL void unescape(); + /// \endcond private: @@ -167,33 +209,46 @@ private: std::list<std::pair<std::string, std::string> > _unescaped; }; +/** + * Performs an exact match. The order of the RDN components is important. + */ inline bool operator>(const DistinguishedName& lhs, const DistinguishedName& rhs) { return rhs < lhs; } +/** + * Performs an exact match. The order of the RDN components is important. + */ inline bool operator<=(const DistinguishedName& lhs, const DistinguishedName& rhs) { return !(lhs > rhs); } +/** + * Performs an exact match. The order of the RDN components is important. + */ inline bool operator>=(const DistinguishedName& lhs, const DistinguishedName& rhs) { return !(lhs < rhs); } +/** + * Performs an exact match. The order of the RDN components is important. + */ inline bool operator!=(const DistinguishedName& lhs, const DistinguishedName& rhs) { return !(lhs == rhs); } -// -// This class represents an X509 Certificate extension. -// +/** + * Represents an X509 Certificate extension. + * \headerfile IceSSL/IceSSL.h + */ class ICESSL_API X509Extension #ifndef ICE_CPP11_MAPPING : public virtual IceUtil::Shared @@ -201,267 +256,317 @@ class ICESSL_API X509Extension { public: + /** + * Determines whether the information in this extension is important. + * @return True if if information is important, false otherwise. + */ virtual bool isCritical() const = 0; + + /** + * Obtains the object ID of this extension. + * @return The object ID. + */ virtual std::string getOID() const = 0; + + /** + * Obtains the data associated with this extension. + * @return The extension data. + */ virtual std::vector<Ice::Byte> getData() const = 0; }; ICE_DEFINE_PTR(X509ExtensionPtr, X509Extension); -// -// This convenience class is a wrapper around a native certificate. -// The interface is inspired by java.security.cert.X509Certificate. -// - class Certificate; ICE_DEFINE_PTR(CertificatePtr, Certificate); +/** + * This convenience class is a wrapper around a native certificate. + * The interface is inspired by java.security.cert.X509Certificate. + * \headerfile IceSSL/IceSSL.h + */ class ICESSL_API Certificate : #ifdef ICE_CPP11_MAPPING - public std::enable_shared_from_this<Certificate> + public std::enable_shared_from_this<Certificate> #else - public virtual IceUtil::Shared + public virtual IceUtil::Shared #endif { public: - // - // Compare the certificates for equality using the - // native certificate comparison method. - // + /** + * Compares the certificates for equality using the native certificate comparison method. + */ virtual bool operator==(const Certificate&) const = 0; + + /** + * Compares the certificates for equality using the native certificate comparison method. + */ virtual bool operator!=(const Certificate&) const = 0; - // - // Authority key identifier - // + /** + * Obtains the authority key identifier. + * @return The identifier. + */ virtual std::vector<Ice::Byte> getAuthorityKeyIdentifier() const = 0; - // - // Subject key identifier - // + /** + * Obtains the subject key identifier. + * @return The identifier. + */ virtual std::vector<Ice::Byte> getSubjectKeyIdentifier() const = 0; - // - // Verify that this certificate was signed by the given certificate - // public key. Returns true if signed, false otherwise. - // - virtual bool verify(const CertificatePtr&) const = 0; - - // - // Return a string encoding of the certificate in PEM format. - // Raises CertificateEncodingException if an error occurs. - // + /** + * Verifies that this certificate was signed by the given certificate + * public key. + * @param cert A certificate containing the public key. + * @return True if signed, false otherwise. + */ + virtual bool verify(const CertificatePtr& cert) const = 0; + + /** + * Obtains a string encoding of the certificate in PEM format. + * @return The encoded certificate. + * @throws CertificateEncodingException if an error occurs. + */ virtual std::string encode() const = 0; - // - // Checks that the certificate is currently valid, that is, the current - // date falls between the validity period given in the certificate. - // + /** + * Checks that the certificate is currently valid, that is, the current + * date falls between the validity period given in the certificate. + * @return True if the certificate is valid, false otherwise. + */ virtual bool checkValidity() const = 0; - // - // Checks that the certificate is valid at the given time. - // + /** + * Checks that the certificate is valid at the given time. + * @param t The target time. + * @return True if the certificate is valid, false otherwise. + */ #ifdef ICE_CPP11_MAPPING - virtual bool checkValidity(const std::chrono::system_clock::time_point&) const = 0; + virtual bool checkValidity(const std::chrono::system_clock::time_point& t) const = 0; #else - virtual bool checkValidity(const IceUtil::Time&) const = 0; + virtual bool checkValidity(const IceUtil::Time& t) const = 0; #endif - // - // Get the not-after validity time. - // + /** + * Obtains the not-after validity time. + * @return The time after which this certificate is invalid. + */ #ifdef ICE_CPP11_MAPPING virtual std::chrono::system_clock::time_point getNotAfter() const = 0; #else virtual IceUtil::Time getNotAfter() const = 0; #endif - // - // Get the not-before validity time. - // + /** + * Obtains the not-before validity time. + * @return The time at which this certificate is valid. + */ #ifdef ICE_CPP11_MAPPING virtual std::chrono::system_clock::time_point getNotBefore() const = 0; #else virtual IceUtil::Time getNotBefore() const = 0; #endif - // - // Get the serial number. This is an arbitrarily large number. - // + /** + * Obtains the serial number. This is an arbitrarily large number. + * @return The certificate's serial number. + */ virtual std::string getSerialNumber() const = 0; - // - // Get the issuer's distinguished name (DN). - // + /** + * Obtains the issuer's distinguished name (DN). + * @return The distinguished name. + */ virtual DistinguishedName getIssuerDN() const = 0; - // - // Get the values in the issuer's alternative names extension. - // - // The returned list contains a pair of int, string. - // - // otherName [0] OtherName - // rfc822Name [1] IA5String - // dNSName [2] IA5String - // x400Address [3] ORAddress - // directoryName [4] Name - // ediPartyName [5] EDIPartyName - // uniformResourceIdentifier [6] IA5String - // iPAddress [7] OCTET STRING - // registeredID [8] OBJECT IDENTIFIER - // - // rfc822Name, dNSName, directoryName and - // uniformResourceIdentifier data is returned as a string. - // - // iPAddress is returned in dotted quad notation. IPv6 is not - // currently supported. - // - // All distinguished names are encoded in RFC2253 format. - // - // The remainder of the data will result in an empty string. Use the raw - // X509* certificate to obtain these values. - // + /** + * Obtains the values in the issuer's alternative names extension. + * + * The returned list contains a pair of int, string. + * + * otherName [0] OtherName + * rfc822Name [1] IA5String + * dNSName [2] IA5String + * x400Address [3] ORAddress + * directoryName [4] Name + * ediPartyName [5] EDIPartyName + * uniformResourceIdentifier [6] IA5String + * iPAddress [7] OCTET STRING + * registeredID [8] OBJECT IDENTIFIER + * + * rfc822Name, dNSName, directoryName and + * uniformResourceIdentifier data is returned as a string. + * + * iPAddress is returned in dotted quad notation. IPv6 is not + * currently supported. + * + * All distinguished names are encoded in RFC2253 format. + * + * The remainder of the data will result in an empty string. Use the raw + * X509* certificate to obtain these values. + * + * @return The issuer's alternative names. + */ virtual std::vector<std::pair<int, std::string> > getIssuerAlternativeNames() const = 0; - // - // Get the subject's distinguished name (DN). - // + /** + * Obtains the subject's distinguished name (DN). + * @return The distinguished name. + */ virtual DistinguishedName getSubjectDN() const = 0; - // - // See the comment for getIssuerAlternativeNames. - // + /** + * See the comment for Plugin::getIssuerAlternativeNames. + * @return The subject's alternative names. + */ virtual std::vector<std::pair<int, std::string> > getSubjectAlternativeNames() const = 0; - // - // Retrieve the certificate version number. - // + /** + * Obtains the certificate version number. + * @return The version number. + */ virtual int getVersion() const = 0; - // - // Stringify the certificate. This is a human readable version of - // the certificate, not a DER or PEM encoding. - // + /** + * Stringifies the certificate. This is a human readable version of + * the certificate, not a DER or PEM encoding. + * @return A string version of the certificate. + */ virtual std::string toString() const = 0; - // - // Return a list with the X509v3 extensions contained in the - // certificate. - // + /** + * Obtains a list of the X509v3 extensions contained in the certificate. + * @return The extensions. + */ virtual std::vector<X509ExtensionPtr> getX509Extensions() const = 0; - // - // Return the extension with the given OID or null if the certificate - // does not contain a extension with the given OID. - // - virtual X509ExtensionPtr getX509Extension(const std::string&) const = 0; - - // - // Load the certificate from a file. The certificate must use the - // PEM encoding format. Raises CertificateReadException if the - // file cannot be read. - // - static CertificatePtr load(const std::string&); - - // - // Decode a certificate from a string that uses the PEM encoding - // format. Raises CertificateEncodingException if an error - // occurs. - // - static CertificatePtr decode(const std::string&); + /** + * Obtains the extension with the given OID. + * @return The extension, or null if the certificate + * does not contain a extension with the given OID. + */ + virtual X509ExtensionPtr getX509Extension(const std::string& oid) const = 0; + + /** + * Loads the certificate from a file. The certificate must use the + * PEM encoding format. + * @param file The certificate file. + * @return The new certificate instance. + * @throws CertificateReadException if the file cannot be read. + */ + static CertificatePtr load(const std::string& file); + + /** + * Decodes a certificate from a string that uses the PEM encoding format. + * @param str A string containing the encoded certificate. + * @throws CertificateEncodingException if an error occurs. + */ + static CertificatePtr decode(const std::string& str); }; #ifndef ICE_CPP11_MAPPING // C++98 mapping -// -// An application can customize the certificate verification process -// by implementing the CertificateVerifier interface. -// +/** + * An application can customize the certificate verification process + * by implementing the CertificateVerifier interface. + * \headerfile IceSSL/IceSSL.h + */ class ICESSL_API CertificateVerifier : public IceUtil::Shared { public: virtual ~CertificateVerifier(); - // - // Return false if the connection should be rejected, or true to - // allow it. - // - virtual bool verify(const ConnectionInfoPtr&) = 0; + /** + * Determines whether to accept a certificate. + * @param info Information about the connection. + * @return False if the connection should be rejected, or true to allow it. + */ + virtual bool verify(const ConnectionInfoPtr& info) = 0; }; typedef IceUtil::Handle<CertificateVerifier> CertificateVerifierPtr; -// -// In order to read an encrypted file, such as one containing a -// private key, OpenSSL requests a password from IceSSL. The password -// can be defined using an IceSSL configuration property, but a -// plain-text password is a security risk. If a password is not -// supplied via configuration, IceSSL allows OpenSSL to prompt the -// user interactively. This may not be desirable (or even possible), -// so the application can supply an implementation of PasswordPrompt -// to take responsibility for obtaining the password. -// -// Note that the password is needed during plug-in initialization, so -// in general you will need to delay initialization (by defining -// IceSSL.DelayInit=1), configure the PasswordPrompt, then manually -// initialize the plug-in. -// +/** + * In order to read an encrypted file, such as one containing a + * private key, OpenSSL requests a password from IceSSL. The password + * can be defined using an IceSSL configuration property, but a + * plain-text password is a security risk. If a password is not + * supplied via configuration, IceSSL allows OpenSSL to prompt the + * user interactively. This may not be desirable (or even possible), + * so the application can supply an implementation of PasswordPrompt + * to take responsibility for obtaining the password. + * + * Note that the password is needed during plug-in initialization, so + * in general you will need to delay initialization (by defining + * IceSSL.DelayInit=1), configure the PasswordPrompt, then manually + * initialize the plug-in. + * \headerfile IceSSL/IceSSL.h + */ class ICESSL_API PasswordPrompt : public IceUtil::Shared { public: virtual ~PasswordPrompt(); - // - // The getPassword method may be invoked repeatedly, such as when - // several encrypted files are opened, or when multiple password - // attempts are allowed. - // + /** + * Obtains the password. This method may be invoked repeatedly, such as when + * several encrypted files are opened, or when multiple password + * attempts are allowed. + * @return The clear-text password. + */ virtual std::string getPassword() = 0; }; typedef IceUtil::Handle<PasswordPrompt> PasswordPromptPtr; #endif +/** + * Represents the IceSSL plug-in object. + * \headerfile IceSSL/IceSSL.h + */ class ICESSL_API Plugin : public Ice::Plugin { public: virtual ~Plugin(); - // - // Establish the certificate verifier object. This should be done - // before any connections are established. - // + /** + * Establish the certificate verifier object. This should be done + * before any connections are established. + * @param v The verifier. + */ #ifdef ICE_CPP11_MAPPING - virtual void setCertificateVerifier(std::function<bool(const std::shared_ptr<ConnectionInfo>&)>) = 0; + virtual void setCertificateVerifier(std::function<bool(const std::shared_ptr<ConnectionInfo>&)> v) = 0; #else - virtual void setCertificateVerifier(const CertificateVerifierPtr&) = 0; + virtual void setCertificateVerifier(const CertificateVerifierPtr& v) = 0; #endif - // - // Establish the password prompt object. This must be done before - // the plug-in is initialized. - // + /** + * Establish the password prompt object. This must be done before + * the plug-in is initialized. + * @param p The password prompt. + */ #ifdef ICE_CPP11_MAPPING - virtual void setPasswordPrompt(std::function<std::string()>) = 0; + virtual void setPasswordPrompt(std::function<std::string()> p) = 0; #else - virtual void setPasswordPrompt(const PasswordPromptPtr&) = 0; + virtual void setPasswordPrompt(const PasswordPromptPtr& p) = 0; #endif - // - // Load the certificate from a file. The certificate must use the - // PEM encoding format. Raises CertificateReadException if the - // file cannot be read. - // - virtual CertificatePtr load(const std::string&) const = 0; - - // - // Decode a certificate from a string that uses the PEM encoding - // format. Raises CertificateEncodingException if an error - // occurs. - // - virtual CertificatePtr decode(const std::string&) const = 0; + /** + * Load the certificate from a file. The certificate must use the + * PEM encoding format. + * @param file The certificate file. + * @throws CertificateReadException if the file cannot be read. + */ + virtual CertificatePtr load(const std::string& file) const = 0; + + /** + * Decode a certificate from a string that uses the PEM encoding + * format. + * @param str A string containing the encoded certificate. + * @throws CertificateEncodingException if an error occurs. + */ + virtual CertificatePtr decode(const std::string& str) const = 0; }; ICE_DEFINE_PTR(PluginPtr, Plugin); |