use a builder style api instead

Author: arckoor

doc/api_ref/ffi.rst

@@ -1791,116 +1791,15 @@ X.509 Certificates
    Return a (statically allocated) string associated with the verification
    result, or NULL if the code is not known.
 
-.. cpp:type:: opaque* botan_x509_cert_opts_t
-
-   An opaque data type for X.509 certificate options. Don't mess with it.
-
-.. cpp:type:: opaque* botan_x509_time_t
-
-   An opaque data type for an X.509 time. Don't mess with it.
-
-.. cpp:type:: opaque* botan_x509_ext_as_blocks_t
-
-   An opaque data type for an X.509 AS Blocks extension (RFC 3779). Don't mess with it.
 
 .. cpp:type:: opaque* botan_x509_ext_ip_addr_blocks_t
 
    An opaque data type for an X.509 IP Address Blocks extension (RFC 3779). Don't mess with it.
 
-.. cpp:type:: opaque* botan_x509_ca_t
-
-   An opaque data type for an X.509 CA. Don't mess with it.
-
-.. cpp:type:: opaque* botan_x509_pkcs10_req_t
-
-   An opaque data type for a PKCS #10 certificate request. Don't mess with it.
-
-.. cpp:function::int botan_x509_cert_opts_destroy(botan_x509_cert_opts_t opts)
-
-   Destroy the options object.
-
-.. cpp:function::int botan_x509_time_destroy(botan_x509_time_t time)
-
-   Destroy the time object.
-
 .. cpp:function::int botan_x509_ext_ip_addr_blocks_destroy(botan_x509_ext_ip_addr_blocks_t ip_addr_blocks)
 
    Destroy the IP Address Blocks object.
 
-.. cpp:function::int botan_x509_ext_as_blocks_destroy(botan_x509_ext_as_blocks_t as_blocks)
-
-   Destroy the AS Blocks object.
-
-.. cpp:function::int botan_x509_ca_destroy(botan_x509_ca_t ca)
-
-   Destroy the CA object.
-
-.. cpp:function::int botan_x509_pkcs10_req_destroy(botan_x509_pkcs10_req_t req)
-
-   Destroy the PKCS #10 certificate request object.
-
-.. cpp:function::int int botan_x509_create_cert_opts(botan_x509_cert_opts_t* opts_obj, const char* opts, uint32_t* expire_time)
-
-   Creates a new options object. ``opts`` defines the common name (e.g. `common_name/country/organization/organizational_unit`), ``expire_time`` if given
-   is the expiration time from current clock in seconds.
-
-.. cpp:function::int botan_x509_cert_opts_common_name(botan_x509_cert_opts_t opts, const char* name)
-
-   Set the common name for the object.
-
-.. cpp:function::int botan_x509_cert_opts_country(botan_x509_cert_opts_t opts, const char* country)
-
-   Set the country for the objects.
-
-.. cpp:function::int botan_x509_cert_opts_organization(botan_x509_cert_opts_t opts, const char* organization)
-
-.. cpp:function::int botan_x509_cert_opts_org_unit(botan_x509_cert_opts_t opts, const char* org_unit)
-
-.. cpp:function::int botan_x509_cert_opts_locality(botan_x509_cert_opts_t opts, const char* locality)
-
-.. cpp:function::int botan_x509_cert_opts_state(botan_x509_cert_opts_t opts, const char* state)
-
-.. cpp:function::int botan_x509_cert_opts_serial_number(botan_x509_cert_opts_t opts, const char* serial_number)
-
-.. cpp:function::int botan_x509_cert_opts_email(botan_x509_cert_opts_t opts, const char* email)
-
-.. cpp:function::int botan_x509_cert_opts_uri(botan_x509_cert_opts_t opts, const char* uri)
-
-.. cpp:function::int botan_x509_cert_opts_ip(botan_x509_cert_opts_t opts, const char* ip)
-
-.. cpp:function::int botan_x509_cert_opts_dns(botan_x509_cert_opts_t opts, const char* dns)
-
-.. cpp:function::int botan_x509_cert_opts_xmpp(botan_x509_cert_opts_t opts, const char* xmpp)
-
-.. cpp:function::int botan_x509_cert_opts_challenge(botan_x509_cert_opts_t opts, const char* challenge)
-
-.. cpp:function::int int botan_x509_cert_opts_more_org_units(botan_x509_cert_opts_t opts, const char** more_org_units, size_t cnt)
-
-.. cpp:function::int int botan_x509_cert_opts_more_dns(botan_x509_cert_opts_t opts, const char** more_dns, size_t cnt)
-
-.. cpp:function::int botan_x509_cert_opts_ca_key(botan_x509_cert_opts_t opts, size_t limit)
-
-   Mark the certificate for CA usage.
-
-.. cpp:function::int botan_x509_cert_opts_padding_scheme(botan_x509_cert_opts_t opts, const char* scheme)
-
-.. cpp:function::int botan_x509_cert_opts_not_before(botan_x509_cert_opts_t opts, botan_x509_time_t not_before)
-
-.. cpp:function::int botan_x509_cert_opts_not_after(botan_x509_cert_opts_t opts, botan_x509_time_t not_after)
-
-.. cpp:function::int botan_x509_cert_opts_constraints(botan_x509_cert_opts_t opts, uint32_t usage)
-
-.. cpp:function::int botan_x509_cert_opts_ex_constraint(botan_x509_cert_opts_t opts, botan_asn1_oid_t oid)
-
-.. cpp:function::int botan_x509_create_time(botan_x509_time_t* time_obj, uint64_t time_since_epoch)
-
-   Create a new time object.
-
-.. cpp:function::int int botan_x509_cert_opts_ext_ip_addr_blocks(botan_x509_cert_opts_t opts, \
-                  botan_x509_ext_ip_addr_blocks_t ip_addr_blocks)
-
-.. cpp:function::int int botan_x509_cert_opts_ext_as_blocks(botan_x509_cert_opts_t opts, botan_x509_ext_as_blocks_t as_blocks)
-
 .. cpp:function::int botan_x509_ext_create_ip_addr_blocks(botan_x509_ext_ip_addr_blocks_t* ip_addr_blocks)
 
    Create a new IP Address Blocks object.
@@ -1910,8 +1809,11 @@ X.509 Certificates
 
    Get an IP Address Blocks object from a certificate. Cannot be mutated.
 
-.. cpp:function::int int botan_x509_ext_ip_addr_blocks_add_ip_addr(
-   botan_x509_ext_ip_addr_blocks_t ip_addr_blocks, const uint8_t* min, const uint8_t* max, int ipv6, uint8_t* safi)
+.. cpp:function::int int botan_x509_ext_ip_addr_blocks_add_ip_addr(botan_x509_ext_ip_addr_blocks_t ip_addr_blocks, \
+                  const uint8_t* min, \
+                  const uint8_t* max, \
+                  int ipv6, \
+                  uint8_t* safi)
 
    Add a new IP Address to the extension. Set ``ipv6`` to 0 if the address is v4, 1 if it is v6.
    ``safi`` may be NULL.
@@ -1966,6 +1868,14 @@ X.509 Certificates
    ``min_out`` and ``max_out`` will be set to the minimum and maximum of the IP range.
    You must provide 4 / 16 bytes of buffer space for each for IP v4 / v6 respectively.
 
+.. cpp:type:: opaque* botan_x509_ext_as_blocks_t
+
+   An opaque data type for an X.509 AS Blocks extension (RFC 3779). Don't mess with it.
+
+.. cpp:function::int botan_x509_ext_as_blocks_destroy(botan_x509_ext_as_blocks_t as_blocks)
+
+   Destroy the AS Blocks object.
+
 .. cpp:function::int botan_x509_ext_create_as_blocks(botan_x509_ext_as_blocks_t* as_blocks)
 
    Create a new AS Blocks object.
@@ -2005,23 +1915,82 @@ X.509 Certificates
 
 .. cpp:function::int int botan_x509_ext_as_blocks_get_rdi_at(botan_x509_ext_as_blocks_t as_blocks, size_t i, uint32_t* min, uint32_t* max)
 
+.. cpp:type:: opaque* botan_x509_cert_params_builder_t
+
+.. cpp:function::int botan_x509_cert_opts_destroy(botan_x509_cert_opts_t opts)
+
+   Destroy the options object.
+
+.. cpp:function::int botan_x509_create_cert_params_builder(botan_x509_cert_params_builder_t* builder_obj, \
+                  const char* opts, \
+                  uint32_t* expire_time);
+
+   Create a new certificate builder object. ``opts`` defines the common name (e.g. `common_name/country/organization/organizational_unit`).
+   ``expire_time`` if given is the expiration time from current clock in seconds.
+
+.. cpp:function::int botan_x509_cert_params_builder_add_common_name(botan_x509_cert_params_builder_t builder, const char* name);
+
+.. cpp:function::int botan_x509_cert_params_builder_add_country(botan_x509_cert_params_builder_t builder, const char* country);
+
+.. cpp:function::int botan_x509_cert_params_builder_add_organization(botan_x509_cert_params_builder_t builder, const char* organization);
+
+.. cpp:function::int botan_x509_cert_params_builder_add_org_unit(botan_x509_cert_params_builder_t builder, const char* org_unit);
+
+.. cpp:function::int botan_x509_cert_params_builder_add_locality(botan_x509_cert_params_builder_t builder, const char* locality);
+
+.. cpp:function::int botan_x509_cert_params_builder_add_state(botan_x509_cert_params_builder_t builder, const char* state);
+
+.. cpp:function::int botan_x509_cert_params_builder_add_serial_number(botan_x509_cert_params_builder_t builder, const char* serial_number);
+
+.. cpp:function::int botan_x509_cert_params_builder_add_email(botan_x509_cert_params_builder_t builder, const char* email);
+
+.. cpp:function::int botan_x509_cert_params_builder_add_uri(botan_x509_cert_params_builder_t builder, const char* uri);
+
+.. cpp:function::int botan_x509_cert_params_builder_add_ip(botan_x509_cert_params_builder_t builder, const char* ip);
+
+.. cpp:function::int botan_x509_cert_params_builder_add_dns(botan_x509_cert_params_builder_t builder, const char* dns);
+
+.. cpp:function::int botan_x509_cert_params_builder_add_xmpp(botan_x509_cert_params_builder_t builder, const char* xmpp);
+
+.. cpp:function::int botan_x509_cert_params_builder_add_challenge(botan_x509_cert_params_builder_t builder, const char* challenge);
+
+.. cpp:function::int botan_x509_cert_params_builder_mark_as_ca_key(botan_x509_cert_params_builder_t builder, size_t limit);
+
+   Mark the certificate for CA usage.
+
+.. cpp:function::int botan_x509_cert_params_builder_add_not_before(botan_x509_cert_params_builder_t builder, uint64_t time_since_epoch);
+
+   ``time_since_epoch`` is expected to be in seconds.
+
+.. cpp:function::int botan_x509_cert_params_builder_add_not_after(botan_x509_cert_params_builder_t builder, uint64_t time_since_epoch);
+
+.. cpp:function::int botan_x509_cert_params_builder_add_constraints(botan_x509_cert_params_builder_t builder, uint32_t usage);
+
+.. cpp:function::int botan_x509_cert_params_builder_add_ex_constraint(botan_x509_cert_params_builder_t builder, botan_asn1_oid_t oid);
+
+.. cpp:function::int botan_x509_cert_params_builder_add_ext_ip_addr_blocks(botan_x509_cert_params_builder_t builder, \
+                  botan_x509_ext_ip_addr_blocks_t ip_addr_blocks);
+
+.. cpp:function::int botan_x509_cert_params_builder_add_ext_as_blocks(botan_x509_cert_params_builder_t builder, \
+                  botan_x509_ext_as_blocks_t as_blocks);
+
 .. cpp:function::int int botan_x509_create_self_signed_cert(botan_x509_cert_t* cert_obj, \
                   botan_privkey_t key, \
                   botan_x509_cert_opts_t opts, \
                   const char* hash_fn, \
-                  const char* sig_padding, \
+                  const char* padding, \
                   botan_rng_t rng)
 
+
    Create a new self-signed X.509 certificate.
 
-.. cpp:function::int int botan_x509_create_ca(botan_x509_ca_t* ca_obj, \
-                  botan_x509_cert_t ca_cert, \
-                  botan_privkey_t key, \
-                  const char* hash_fn, \
-                  const char* sig_padding, \
-                  botan_rng_t rng)
+.. cpp:type:: opaque* botan_x509_pkcs10_req_t
 
-   Create a CA object capable of signing other certificates.
+   An opaque data type for a PKCS #10 certificate request. Don't mess with it.
+
+.. cpp:function::int botan_x509_pkcs10_req_destroy(botan_x509_pkcs10_req_t req)
+
+   Destroy the PKCS #10 certificate request object.
 
 .. cpp:function::int int botan_x509_create_pkcs10_req(botan_x509_pkcs10_req_t* req_obj, \
                   botan_x509_cert_opts_t opts, \
@@ -2031,14 +2000,17 @@ X.509 Certificates
 
    Create a PCKS #10 certificate request.
 
-.. cpp:function::int int botan_x509_sign_req(botan_x509_cert_t* cert_obj, \
-                  botan_x509_ca_t ca, \
-                  botan_x509_pkcs10_req_t req, \
+.. cpp:function::int int botan_x509_sign_req(botan_x509_cert_t* subject_cert, \
+                  botan_x509_pkcs10_req_t subject_req, \
+                  botan_x509_cert_t issuing_cert, \
+                  botan_privkey_t issuing_key, \
                   botan_rng_t rng, \
-                  botan_x509_time_t not_before, \
-                  botan_x509_time_t not_after)
+                  uint64_t not_before, \
+                  uint64_t not_after, \
+                  const char* hash_fn, \
+                  const char* padding)
 
-   Sign a PKCS #10 certificate request
+   Sign a PKCS #10 certificate request. ``not_before`` and ``not_after`` are expected to be the time since the UNIX epoch, in seconds.
 
 X.509 Certificate Revocation Lists
 ----------------------------------------

doc/api_ref/python.rst

@@ -715,80 +715,58 @@ HOTP
       in. If the code did verify and resync_range was zero, then the
       next counter will always be counter+1.
 
-X509Time
+X509CertificateBuilder
 -----------------------------------------
 .. versionadded:: 3.9.0
 
-.. py:class:: X509Time(time_since_epoch)
+.. py:class:: X509CertificateBuilder(opts, expire_time=None)
 
-PKCS10Req
------------------------------------------
-.. versionadded:: 3.9.0
-
-.. py:class:: PKCS10Req()
-
-X509Opts
------------------------------------------
-.. versionadded:: 3.9.0
-
-.. py:class:: X509Opts(opts, expire_time=None)
+   .. py:method:: add_common_name(name)
 
-   .. py:method:: set_common_name(name)
+   .. py:method:: add_country(country)
 
-      Set the common name for the certificate.
+   .. py:method:: add_organization(organization)
 
-   .. py:method:: set_country(country)
+   .. py:method:: add_org_unit(org_unit)
 
-   .. py:method:: set_organization(organization)
+   .. py:method:: add_locality(locality)
 
-   .. py:method:: set_org_unit(org_unit)
+   .. py:method:: add_state(state)
 
-   .. py:method:: set_locality(locality)
+   .. py:method:: add_serial_number(serial_number)
 
-   .. py:method:: set_state(state)
+   .. py:method:: add_email(email)
 
-   .. py:method:: set_serial_number(serial_number)
+   .. py:method:: add_uri(uri)
 
-   .. py:method:: set_email(email)
+   .. py:method:: add_ip(ip)
 
-   .. py:method:: set_uri(uri)
+   .. py:method:: add_dns(dns)
 
-   .. py:method:: set_ip(ip)
+   .. py:method:: add_xmpp(xmpp)
 
-   .. py:method:: set_dns(dns)
+   .. py:method:: add_challenge(challenge)
 
-   .. py:method:: set_xmpp(xmpp)
+   .. py:method:: mark_as_ca_key(limit)
 
-   .. py:method:: set_challenge(challenge)
+   .. py:method:: add_not_before(time_since_epoch)
 
-   .. py:method:: set_more_org_units(more_org_units)
+      ``time_since_epoch`` is expected to be in seconds.
 
-      ``more_org_units`` is expected to be a of type ``list[string]``
+   .. py:method:: add_not_after(time_since_epoch)
 
-   .. py:method:: set_more_dns(more_dns)
+   .. py:method:: add_constraints(usage_list)
 
-      ``more_dns`` is expected to be a of type ``list[string]``
-
-   .. py:method:: set_ca_key(limit)
-
-   .. py:method:: set_padding_scheme(scheme)
-
-   .. py:method:: set_not_before(not_before)
-
-   .. py:method:: set_not_after(not_after)
+   .. py:method:: add_ex_constraints(oid)
 
-   .. py:method:: set_constraints(usage_list)
+   .. py:method:: add_ext_ip_addr_blocks(ip_addr_blocks)
 
-   .. py:method:: add_ex_constraints(oid)
+   .. py:method:: add_ext_as_blocks(as_blocks)
 
    .. py:method:: create_req(key, hash_fn, rng)
 
       Create a PKCS #10 certificate request that can later be signed.
 
-   .. py:method:: add_ext_ip_addr_blocks(ip_addr_blocks)
-
-   .. py:method:: add_ext_as_blocks(as_blocks)
-
 X509ExtIPAddrBlocks
 -----------------------------------------
 
@@ -855,6 +833,16 @@ X509ExtASBlocks
 
    .. py:method:: rdi()
 
+PKCS10Req
+-----------------------------------------
+.. versionadded:: 3.9.0
+
+.. py:class:: PKCS10Req()
+
+   .. py:method:: sign(issuing_cert, issuing_key, rng, not_before, not_after, hash_fn, padding)
+
+      ``not_before`` and ``not_after`` are expected to be the time since the UNIX epoch, in seconds.
+
 X509Cert
 -----------------------------------------
 
@@ -1002,17 +990,6 @@ X509Cert
 
       Check if the certificate (``self``) is revoked on the given ``crl``.
 
-X509Ca
------------------------------------------
-
-.. versionadded:: 3.9.0
-
-.. py:class:: X509Ca(cert, key, rng, has_fn, sig_padding="")
-
-   .. py:method:: sign(req, rng, not_before, not_after)
-
-      Sign a PKCS #10 certificate request.
-
 X509CRL
 -----------------------------------------