Merge pull request #1166 from lvh/c-binding-docs
Early developer documentation for C bindings
diff --git a/cryptography/hazmat/backends/interfaces.py b/cryptography/hazmat/backends/interfaces.py
index 524e0a5..e4faf32 100644
--- a/cryptography/hazmat/backends/interfaces.py
+++ b/cryptography/hazmat/backends/interfaces.py
@@ -196,6 +196,24 @@
Return True if the parameters are supported by the backend for DSA.
"""
+ @abc.abstractmethod
+ def load_dsa_private_numbers(self, numbers):
+ """
+ Returns a DSAPrivateKey provider.
+ """
+
+ @abc.abstractmethod
+ def load_dsa_public_numbers(self, numbers):
+ """
+ Returns a DSAPublicKey provider.
+ """
+
+ @abc.abstractmethod
+ def load_dsa_parameter_numbers(self, numbers):
+ """
+ Returns a DSAParameters provider.
+ """
+
@six.add_metaclass(abc.ABCMeta)
class TraditionalOpenSSLSerializationBackend(object):
diff --git a/cryptography/hazmat/bindings/commoncrypto/common_cryptor.py b/cryptography/hazmat/bindings/commoncrypto/common_cryptor.py
index 9bd03a7..713bc56 100644
--- a/cryptography/hazmat/bindings/commoncrypto/common_cryptor.py
+++ b/cryptography/hazmat/bindings/commoncrypto/common_cryptor.py
@@ -101,7 +101,7 @@
"""
CUSTOMIZATIONS = """
-// Not defined in the public header
+/* Not defined in the public header */
enum {
kCCModeGCM = 11
};
diff --git a/cryptography/hazmat/bindings/openssl/aes.py b/cryptography/hazmat/bindings/openssl/aes.py
index 58ef0cf..e407152 100644
--- a/cryptography/hazmat/bindings/openssl/aes.py
+++ b/cryptography/hazmat/bindings/openssl/aes.py
@@ -49,7 +49,7 @@
"""
CUSTOMIZATIONS = """
-// OpenSSL 0.9.8h+
+/* OpenSSL 0.9.8h+ */
#if OPENSSL_VERSION_NUMBER >= 0x0090808fL
static const long Cryptography_HAS_AES_WRAP = 1;
#else
diff --git a/cryptography/hazmat/bindings/openssl/cms.py b/cryptography/hazmat/bindings/openssl/cms.py
index a3760f2..cbf4b28 100644
--- a/cryptography/hazmat/bindings/openssl/cms.py
+++ b/cryptography/hazmat/bindings/openssl/cms.py
@@ -15,8 +15,8 @@
INCLUDES = """
#if !defined(OPENSSL_NO_CMS) && OPENSSL_VERSION_NUMBER >= 0x0090808fL
-// The next define should really be in the OpenSSL header, but it is missing.
-// Failing to include this on Windows causes compilation failures.
+/* The next define should really be in the OpenSSL header, but it is missing.
+ Failing to include this on Windows causes compilation failures. */
#if defined(OPENSSL_SYS_WINDOWS)
#include <windows.h>
#endif
diff --git a/cryptography/hazmat/bindings/openssl/dh.py b/cryptography/hazmat/bindings/openssl/dh.py
index a0f9947..e2e8976 100644
--- a/cryptography/hazmat/bindings/openssl/dh.py
+++ b/cryptography/hazmat/bindings/openssl/dh.py
@@ -19,13 +19,13 @@
TYPES = """
typedef struct dh_st {
- // prime number (shared)
+ /* Prime number (shared) */
BIGNUM *p;
- // generator of Z_p (shared)
+ /* Generator of Z_p (shared) */
BIGNUM *g;
- // private DH value x
+ /* Private DH value x */
BIGNUM *priv_key;
- // public DH value g^x
+ /* Public DH value g^x */
BIGNUM *pub_key;
...;
} DH;
diff --git a/cryptography/hazmat/bindings/openssl/dsa.py b/cryptography/hazmat/bindings/openssl/dsa.py
index 7db0332..c9aa888 100644
--- a/cryptography/hazmat/bindings/openssl/dsa.py
+++ b/cryptography/hazmat/bindings/openssl/dsa.py
@@ -19,15 +19,15 @@
TYPES = """
typedef struct dsa_st {
- // prime number (public)
+ /* Prime number (public) */
BIGNUM *p;
- // 160-bit subprime, q | p-1 (public)
+ /* Subprime (160-bit, q | p-1, public) */
BIGNUM *q;
- // generator of subgroup (public)
+ /* Generator of subgroup (public) */
BIGNUM *g;
- // private key x
+ /* Private key x */
BIGNUM *priv_key;
- // public key y = g^x
+ /* Public key y = g^x */
BIGNUM *pub_key;
...;
} DSA;
diff --git a/cryptography/hazmat/bindings/openssl/err.py b/cryptography/hazmat/bindings/openssl/err.py
index 8ed97d0..9c9b45c 100644
--- a/cryptography/hazmat/bindings/openssl/err.py
+++ b/cryptography/hazmat/bindings/openssl/err.py
@@ -284,7 +284,7 @@
void (*ERR_remove_thread_state)(const CRYPTO_THREADID *) = NULL;
#endif
-// OpenSSL 0.9.8h+
+/* OpenSSL 0.9.8h+ */
#if OPENSSL_VERSION_NUMBER >= 0x0090808fL
static const long Cryptography_HAS_098H_ERROR_CODES = 1;
#else
@@ -298,7 +298,7 @@
static const int ASN1_R_NO_MULTIPART_BOUNDARY = 0;
#endif
-// OpenSSL 0.9.8c+
+/* OpenSSL 0.9.8c+ */
#ifdef EVP_F_CAMELLIA_INIT_KEY
static const long Cryptography_HAS_098C_CAMELLIA_CODES = 1;
#else
diff --git a/cryptography/hazmat/bindings/openssl/evp.py b/cryptography/hazmat/bindings/openssl/evp.py
index b3d958e..1183450 100644
--- a/cryptography/hazmat/bindings/openssl/evp.py
+++ b/cryptography/hazmat/bindings/openssl/evp.py
@@ -139,7 +139,8 @@
int EVP_PKEY_CTX_set_signature_md(EVP_PKEY_CTX *, const EVP_MD *);
-// not macros but must be in this section since they're not available in 0.9.8
+/* These aren't macros, but must be in this section because they're not
+ available in 0.9.8. */
EVP_PKEY_CTX *EVP_PKEY_CTX_new(EVP_PKEY *, ENGINE *);
EVP_PKEY_CTX *EVP_PKEY_CTX_new_id(int, ENGINE *);
EVP_PKEY_CTX *EVP_PKEY_CTX_dup(EVP_PKEY_CTX *);
diff --git a/cryptography/hazmat/bindings/openssl/nid.py b/cryptography/hazmat/bindings/openssl/nid.py
index ea6fd4d..7fa0866 100644
--- a/cryptography/hazmat/bindings/openssl/nid.py
+++ b/cryptography/hazmat/bindings/openssl/nid.py
@@ -193,7 +193,7 @@
"""
CUSTOMIZATIONS = """
-// OpenSSL 0.9.8g+
+/* OpenSSL 0.9.8g+ */
#if OPENSSL_VERSION_NUMBER >= 0x0090807fL
static const long Cryptography_HAS_ECDSA_SHA2_NIDS = 1;
#else
diff --git a/cryptography/hazmat/bindings/openssl/rsa.py b/cryptography/hazmat/bindings/openssl/rsa.py
index c635610..cb8e701 100644
--- a/cryptography/hazmat/bindings/openssl/rsa.py
+++ b/cryptography/hazmat/bindings/openssl/rsa.py
@@ -80,7 +80,7 @@
#if OPENSSL_VERSION_NUMBER >= 0x10000000
static const long Cryptography_HAS_PSS_PADDING = 1;
#else
-// see evp.py for the definition of Cryptography_HAS_PKEY_CTX
+/* see evp.py for the definition of Cryptography_HAS_PKEY_CTX */
static const long Cryptography_HAS_PSS_PADDING = 0;
int (*EVP_PKEY_CTX_set_rsa_padding)(EVP_PKEY_CTX *, int) = NULL;
int (*EVP_PKEY_CTX_set_rsa_pss_saltlen)(EVP_PKEY_CTX *, int) = NULL;
diff --git a/cryptography/hazmat/bindings/openssl/ssl.py b/cryptography/hazmat/bindings/openssl/ssl.py
index 018a141..7d805e7 100644
--- a/cryptography/hazmat/bindings/openssl/ssl.py
+++ b/cryptography/hazmat/bindings/openssl/ssl.py
@@ -456,7 +456,7 @@
const long SSL_OP_NO_TICKET = 0;
#endif
-// OpenSSL 0.9.8f+
+/* OpenSSL 0.9.8f+ */
#if OPENSSL_VERSION_NUMBER >= 0x00908070L
static const long Cryptography_HAS_SSL_SET_SSL_CTX = 1;
#else
@@ -483,7 +483,7 @@
static const long Cryptography_HAS_NETBSD_D1_METH = 1;
#endif
-// Workaround for #794 caused by cffi const** bug.
+/* Workaround for #794 caused by cffi const** bug. */
const SSL_METHOD* Cryptography_SSL_CTX_get_method(const SSL_CTX* ctx) {
return ctx->method;
}
@@ -519,7 +519,7 @@
static const long Cryptography_HAS_NEXTPROTONEG = 1;
#endif
-// ALPN was added in OpenSSL 1.0.2.
+/* ALPN was added in OpenSSL 1.0.2. */
#if OPENSSL_VERSION_NUMBER < 0x10002001L
int (*SSL_CTX_set_alpn_protos)(SSL_CTX *,
const unsigned char*,
diff --git a/cryptography/hazmat/bindings/openssl/x509.py b/cryptography/hazmat/bindings/openssl/x509.py
index cf38df3..b74c118 100644
--- a/cryptography/hazmat/bindings/openssl/x509.py
+++ b/cryptography/hazmat/bindings/openssl/x509.py
@@ -245,7 +245,7 @@
"""
CUSTOMIZATIONS = """
-// OpenSSL 0.9.8e does not have this definition
+/* OpenSSL 0.9.8e does not have this definition. */
#if OPENSSL_VERSION_NUMBER <= 0x0090805fL
typedef STACK_OF(X509_EXTENSION) X509_EXTENSIONS;
#endif
diff --git a/cryptography/hazmat/bindings/openssl/x509_vfy.py b/cryptography/hazmat/bindings/openssl/x509_vfy.py
index ed35b1b..a53716b 100644
--- a/cryptography/hazmat/bindings/openssl/x509_vfy.py
+++ b/cryptography/hazmat/bindings/openssl/x509_vfy.py
@@ -45,7 +45,7 @@
as longs, just in case they ever grow to large, such as what we saw
with OP_ALL. */
-// Verification error codes
+/* Verification error codes */
static const int X509_V_OK;
static const int X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT;
static const int X509_V_ERR_UNABLE_TO_GET_CRL;
@@ -110,7 +110,7 @@
static const int X509_V_ERR_IP_ADDRESS_MISMATCH;
static const int X509_V_ERR_APPLICATION_VERIFICATION;
-// Verification parameters
+/* Verification parameters */
static const long X509_V_FLAG_CB_ISSUER_CHECK;
static const long X509_V_FLAG_USE_CHECK_TIME;
static const long X509_V_FLAG_CRL_CHECK;
@@ -136,12 +136,12 @@
FUNCTIONS = """
int X509_verify_cert(X509_STORE_CTX *);
-// X509_STORE
+/* X509_STORE */
X509_STORE *X509_STORE_new(void);
void X509_STORE_free(X509_STORE *);
int X509_STORE_add_cert(X509_STORE *, X509 *);
-// X509_STORE_CTX
+/* X509_STORE_CTX */
X509_STORE_CTX *X509_STORE_CTX_new(void);
void X509_STORE_CTX_cleanup(X509_STORE_CTX *);
void X509_STORE_CTX_free(X509_STORE_CTX *);
@@ -165,7 +165,7 @@
int X509_STORE_CTX_set_ex_data(X509_STORE_CTX *, int, void *);
void *X509_STORE_CTX_get_ex_data(X509_STORE_CTX *, int);
-// X509_VERIFY_PARAM
+/* X509_VERIFY_PARAM */
X509_VERIFY_PARAM *X509_VERIFY_PARAM_new(void);
int X509_VERIFY_PARAM_set_flags(X509_VERIFY_PARAM *, unsigned long);
int X509_VERIFY_PARAM_clear_flags(X509_VERIFY_PARAM *, unsigned long);
@@ -181,11 +181,11 @@
"""
MACROS = """
-// X509_STORE_CTX
+/* X509_STORE_CTX */
void X509_STORE_CTX_set0_crls(X509_STORE_CTX *,
Cryptography_STACK_OF_X509_CRL *);
-// X509_VERIFY_PARAM
+/* X509_VERIFY_PARAM */
int X509_VERIFY_PARAM_set1_host(X509_VERIFY_PARAM *, const unsigned char *,
size_t);
void X509_VERIFY_PARAM_set_hostflags(X509_VERIFY_PARAM *, unsigned int);
@@ -197,7 +197,7 @@
"""
CUSTOMIZATIONS = """
-// OpenSSL 1.0.2+, but only some very new releases
+/* OpenSSL 1.0.2+, but only some very new releases */
#ifdef X509_VERIFY_PARAM_set_hostflags
static const long Cryptography_HAS_X509_VERIFY_PARAM_SET_HOSTFLAGS = 1;
#else
@@ -206,7 +206,7 @@
unsigned int) = NULL;
#endif
-// OpenSSL 1.0.2+ verification error codes
+/* OpenSSL 1.0.2+ verification error codes */
#if OPENSSL_VERSION_NUMBER >= 0x10002000L
static const long Cryptography_HAS_102_VERIFICATION_ERROR_CODES = 1;
#else
@@ -222,12 +222,13 @@
static const long X509_V_ERR_IP_ADDRESS_MISMATCH = 0;
#endif
-// OpenSSL 1.0.2+ verification parameters
+/* OpenSSL 1.0.2+ verification parameters */
#if OPENSSL_VERSION_NUMBER >= 0x10002000L
static const long Cryptography_HAS_102_VERIFICATION_PARAMS = 1;
#else
static const long Cryptography_HAS_102_VERIFICATION_PARAMS = 0;
-// X509_V_FLAG_TRUSTED_FIRST is also new in 1.0.2, but added separately below
+/* X509_V_FLAG_TRUSTED_FIRST is also new in 1.0.2+, but it is added separately
+ below because it shows up in some earlier 3rd party OpenSSL packages. */
static const long X509_V_FLAG_SUITEB_128_LOS_ONLY = 0;
static const long X509_V_FLAG_SUITEB_192_LOS = 0;
static const long X509_V_FLAG_SUITEB_128_LOS = 0;
@@ -242,7 +243,7 @@
int (*X509_VERIFY_PARAM_set1_ip_asc)(X509_VERIFY_PARAM *, const char *) = NULL;
#endif
-// OpenSSL 1.0.2+, *or* Fedora 20's flavor of OpenSSL 1.0.1e...
+/* OpenSSL 1.0.2+, *or* Fedora 20's flavor of OpenSSL 1.0.1e... */
#ifdef X509_V_FLAG_TRUSTED_FIRST
static const long Cryptography_HAS_X509_V_FLAG_TRUSTED_FIRST = 1;
#else
@@ -250,7 +251,7 @@
static const long X509_V_FLAG_TRUSTED_FIRST = 0;
#endif
-// OpenSSL 1.0.0+ verification error codes
+/* OpenSSL 1.0.0+ verification error codes */
#if OPENSSL_VERSION_NUMBER >= 0x10000000L
static const long Cryptography_HAS_100_VERIFICATION_ERROR_CODES = 1;
#else
@@ -266,7 +267,7 @@
static const long X509_V_ERR_CRL_PATH_VALIDATION_ERROR = 0;
#endif
-// OpenSSL 1.0.0+ verification parameters
+/* OpenSSL 1.0.0+ verification parameters */
#if OPENSSL_VERSION_NUMBER >= 0x10000000L
static const long Cryptography_HAS_100_VERIFICATION_PARAMS = 1;
#else
@@ -275,7 +276,7 @@
static const long X509_V_FLAG_USE_DELTAS = 0;
#endif
-// OpenSSL 0.9.8recent+
+/* OpenSSL 0.9.8recent+ */
#ifdef X509_V_FLAG_CHECK_SS_SIGNATURE
static const long Cryptography_HAS_X509_V_FLAG_CHECK_SS_SIGNATURE = 1;
#else
diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst
index 9e476f7..5cbd47d 100644
--- a/docs/hazmat/backends/interfaces.rst
+++ b/docs/hazmat/backends/interfaces.rst
@@ -470,6 +470,40 @@
:returns: ``True`` if the given values of ``p``, ``q``, and ``g`` are
supported by this backend, otherwise ``False``.
+ .. method:: load_dsa_parameter_numbers(numbers):
+
+ :param numbers: An instance of
+ :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAParameterNumbers`.
+
+ :returns: A provider of
+ :class:`~cryptography.hazmat.primitives.interfaces.DSAParameters`.
+
+ :raises cryptography.exceptions.UnsupportedAlgorithm: This raised when
+ any backend specific criteria are not met.
+
+ .. method:: load_dsa_private_numbers(numbers):
+
+ :param numbers: An instance of
+ :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateNumbers`.
+
+ :returns: A provider of
+ :class:`~cryptography.hazmat.primitives.interfaces.DSAPrivateKey`.
+
+ :raises cryptography.exceptions.UnsupportedAlgorithm: This raised when
+ any backend specific criteria are not met.
+
+ .. method:: load_dsa_public_numbers(numbers):
+
+ :param numbers: An instance of
+ :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicNumbers`.
+
+ :returns: A provider of
+ :class:`~cryptography.hazmat.primitives.interfaces.DSAPublicKey`.
+
+ :raises cryptography.exceptions.UnsupportedAlgorithm: This raised when
+ any backend specific criteria are not met.
+
+
.. class:: CMACBackend