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,
  }; /* End enum Digest */

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

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

      const char * what() const throw();
      const char * where() const throw();

    protected:
      OpenSSLException(const QString&, const char* = NULL, int = 0) throw();
      OpenSSLException(const OpenSSLException&) throw();
  }; /* End class OpenSSLException */

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

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

      ~SigningException() throw();

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

    protected:
      SigningException(Operation, Failure, const QString&, const char* = NULL, int = 0) throw();
      SigningException(const SigningException&) throw();

      void setFailure(Failure) throw();
      void setMessage(const QString&) throw();
  }; /* End class SigningException */

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

      Extension(const ObjectID&, const QString&,
                bool = false, bool = false);
      ~Extension();

      const ObjectID oid() const;

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

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

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

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

    protected:
      Extension(const QString&, const QString&,
                bool = false, bool = false);
      Extension(int, const QString&,
                bool = false, bool = false);
      Extension(const X509_EXTENSION*);
      X509_EXTENSION* handle(X509V3_CTX* = NULL) const;
  }; /* End class Extension */
  typedef QList< Extension > ExtensionList;

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

  QString version();
  QString build_information();

  quint64 random();

  ExtensionList emailCertExtensions();

  class Key : public QSslKey
  {
    public:
      Key(const QSslKey& = QSslKey());
      Key(const Key&);
      ~Key();

      operator=(const Key&);

      static const Key generateKeyPair(int = 2048, QSsl::KeyAlgorithm = QSsl::Rsa);

    protected:
      EVP_PKEY* handle() const;
  }; /* End class Key */

  class Request
  {
    public:
      Request(const QByteArray& = QByteArray(), QSsl::EncodingFormat = QSsl::Pem);
      Request(const Request&)
      ~Request();

      bool isNull() const;

      QByteArray subject() const;

      ExtensionList extensions() const;

      QByteArray toDer() const;
      QByteArray toPem() const;

      QByteArray version() const;

      bool operator!=(const Request&) const;
      bool operator==(const Request&) const;

      Request& operator=(const Request&);

      static Request generate(const Key&, const QByteArray&,
                              const ExtensionList& = ExtensionList(),
                              Digest = SHA256);

    protected:
      X509_REQ* handle() const;
  }; /* End class Request */

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

      Certificate(const QSslCertificate& = QSslCertificate());
      Certificate(const Certificate&);

      Certificate(const Key&, const QString&,
                  const SignatureDetails&, const ExtensionList&);

      ~Certificate();

      bool isCA() const;
      bool keyMatch(const Key&) const;

      ExtensionList extensions() const;

      Certificate sign(const Request&, const Key&,
                       const SignatureDetails&,
                       const ExtensionList&) const;

      QByteArray sign(const CRL&, const Key&,
                      const SignatureDetails&,
                      const ExtensionList&, QSsl::EncodingFormat = QSsl::Der) const;
  }; /* End class Certificate */

}; /* End namespace OpenSSL */
}; /* End namespace Kca */