Public API¶

The real code is documented, of course. See header files in source:src.
For a history of how it was created, see ticket #34.

Regardless of the files the API is split into, in C++ it looks like this:

namespace Kca
{
namespace OpenSSL
{
  enum Digest {
    RIPEMD160,
    SHA1,
    SHA256,
    SHA384,
    SHA512,
  };

  enum RevocationReason {
    Unspecified,
    KeyCompromise,
    CACompromise,
    AffilitionChanged,
    Superseded,
    CessationOfOperation,
    CertificateHold,
    RemoveFromCRL = 8
  };

  class OpenSSLException : public std::exception
  {
    public:
      ~OpenSSLException() throw();

      const char * what() const throw();

    protected:
      OpenSSLException(const QString& message) throw();
  };

  class SigningException : public std::exception
  {
    public:
      enum Operation {
        SignCsr,
        SignCrl,
      };

      enum Failure {
        NoCACertificate,
        KeyMismatch,
        SerialConstraint,
        TimeConstraint,
        ExtensionError,
        ObjectError,
      };

      ~SigningException() throw();

      const Operation operation() const throw();
      const Failure failure() const throw();
      const char * what() const throw();

    protected:
      SigningException(Operation operation, Failure failure, const QString& description) throw();

      void setFailure(Failure failure) throw();
      void setMessage(const QString& message) throw();
  };

  class Extension {
    public:
      struct ObjectID {
        QString oid;
        QString shortName;
        QString longName;
      };

      Extension(const ObjectID& oid, const QString& value,
                bool critical=false, bool replace=false);
      ~Extension();

      const ObjectID oid() const;

      const QString value() const;
      void setValue(const QString& value);

      bool critical() const;
      void setCritical(bool critical);

      bool replace() const;
      void setReplace(bool replace);

      bool operator==(const Extension& other) const;
      Extension& operator=(const Extension& other);

    protected:
      Extension(const QString& name, const QString& value,
                bool critical = false, bool replace = false) throw(OpenSSLException);
      X509_EXTENSION* handle(X509V3_CTX* ctx = NULL) const throw(OpenSSLException);
  };
  typedef QList< Extension > ExtensionList;

  struct CRLEntry {
    quint64 serial;
    RevocationReason reason;
    QDateTime timestamp;
  };
  typedef QList< CRLEntry > CRL;

  QString version();
  QString build_information();

  quint64 random();
  const QSslKey generateKeyPair(unsigned int length = 2048, QSsl::KeyAlgorithm algorithm = QSsl::Rsa);
  const QByteArray generateRequest(const QSslKey& key,
                                   const QString& subject,
                                   const ExtensionList& extensions,
                                   Digest digest = SHA256);

  ExtensionList emailCertExtensions();

  QString requestSubject(const QByteArray& request);
  ExtensionList requestExtensions(const QByteArray& request);

  class Certificate : public QSslCertificate
  {
    public:
      struct SignatureDetails {
        quint64 serial;
        Digest digest;
        QDateTime effectiveDate;
        QDateTime expiryDate;
      };

      Certificate(const QSslKey& key, const QString& subject,
                  const SignatureDetails& details, const ExtensionList& extensions) throw(SigningException);

      bool isCA() const;
      bool keyMatch(const QSslKey& key) const;

      const QSslCertificate sign(const QByteArray& request, const QSslKey& signingKey,
                                 const SignatureDetails& details,
                                 const ExtensionList& extensions) const throw(SigningException);

      const QByteArray sign(const CRL& crl, const QSslKey& signingKey,
                            const SignatureDetails& details,
                            const ExtensionList& extensions) const throw(SigningException);
  };

};
};