class OpenSSL::Timestamp::Factory - Documentation for Ruby 3.4
Description: class OpenSSL::Timestamp::Factory: Used to generate a Response from scratch. Please bear in mind that the implementation will always apply and prefer the policy object identifier given
Keywords: ruby,class,OpenSSL::Timestamp::Factory

# class OpenSSL::Timestamp::Factory

Used to generate a `Response` from scratch.

Please bear in mind that the implementation will always apply and prefer the policy object identifier given in the request over the default policy id specified in the `Factory`. As a consequence, `default_policy_id` will only be applied if no `Request#policy_id` was given. But this also means that one needs to check the policy identifier in the request manually before creating the `Response`, e.g. to check whether it complies to a specific set of acceptable policies.

There exists also the possibility to add certificates (instances of `OpenSSL::X509::Certificate`) besides the timestamping certificate that will be included in the resulting timestamp token if `Request#cert_requested?` is `true`. Ideally, one would also include any intermediate certificates (the root certificate can be left out - in order to trust it any verifying party will have to be in its possession anyway). This simplifies validation of the timestamp since these intermediate certificates are “already there” and need not be passed as external parameters to `Response#verify` anymore, thus minimizing external resources needed for verification.

### Example: Inclusion of (untrusted) intermediate certificates¶ ↑

Assume we received a timestamp request that has set `Request#policy_id` to `nil` and `Request#cert_requested?` to true. The raw request bytes are stored in a variable called `req_raw`. We’d still like to integrate the necessary intermediate certificates (in `inter1.cer` and `inter2.cer`) to simplify validation of the resulting `Response`. `ts.p12` is a PKCS#12-compatible file including the private key and the timestamping certificate.

    req = OpenSSL::Timestamp::Request.new(raw_bytes)
    p12 = OpenSSL::PKCS12.new(File.binread('ts.p12'), 'pwd')
    inter1 = OpenSSL::X509::Certificate.new(File.binread('inter1.cer'))
    inter2 = OpenSSL::X509::Certificate.new(File.binread('inter2.cer'))
    fac = OpenSSL::Timestamp::Factory.new
    fac.gen_time = Time.now
    fac.serial_number = 1
    fac.allowed_digests = ["sha256", "sha384", "sha512"]
    #needed because the Request contained no policy identifier
    fac.default_policy_id = '1.2.3.4.5'
    fac.additional_certificates = [ inter1, inter2 ]
    timestamp = fac.create_timestamp(p12.key, p12.certificate, req)

## Attributes¶ ↑

### `default_policy_id`¶ ↑

`Request#policy_id` will always be preferred over this if present in the `Request`, only if `Request#policy_id` is nil default_policy will be used. If none of both is present, a `TimestampError` will be raised when trying to create a `Response`.

call-seq:

    factory.default_policy_id = "string" -> string
    factory.default_policy_id            -> string or nil

### `serial_number`¶ ↑

Sets or retrieves the serial number to be used for timestamp creation. Must be present for timestamp creation.

call-seq:

    factory.serial_number = number -> number
    factory.serial_number          -> number or nil

### `gen_time`¶ ↑

Sets or retrieves the `Time` value to be used in the `Response`. Must be present for timestamp creation.

call-seq:

    factory.gen_time = Time -> Time
    factory.gen_time        -> Time or nil

### `additional_certs`¶ ↑

Sets or retrieves additional certificates apart from the timestamp certificate (e.g. intermediate certificates) to be added to the `Response`. Must be an `Array` of `OpenSSL::X509::Certificate`.

call-seq:

    factory.additional_certs = [cert1, cert2] -> [ cert1, cert2 ]
    factory.additional_certs                  -> array or nil

### `allowed_digests`¶ ↑

Sets or retrieves the digest algorithms that the factory is allowed create timestamps for. Known vulnerable or weak algorithms should not be allowed where possible. Must be an `Array` of `String` or `OpenSSL::Digest` subclass instances.

call-seq:

    factory.allowed_digests = ["sha1", OpenSSL::Digest.new('SHA256').new] -> [ "sha1", OpenSSL::Digest) ]
    factory.allowed_digests                                               -> array or nil

### Attributes

additional_certs [RW]
allowed_digests [RW]
default_policy_id [RW]
gen_time [RW]
serial_number [RW]

### Public Instance Methods

create_timestamp(key, certificate, request) → Response
Source

    static VALUE
    ossl_tsfac_create_ts(VALUE self, VALUE key, VALUE certificate, VALUE request)
    {
        VALUE serial_number, def_policy_id, gen_time, additional_certs, allowed_digests;
        VALUE str;
        STACK_OF(X509) *inter_certs;
        VALUE tsresp, ret = Qnil;
        EVP_PKEY *sign_key;
        X509 *tsa_cert;
        TS_REQ *req;
        TS_RESP *response = NULL;
        TS_RESP_CTX *ctx = NULL;
        BIO *req_bio;
        ASN1_INTEGER *asn1_serial = NULL;
        ASN1_OBJECT *def_policy_id_obj = NULL;
        long lgen_time;
        const char * err_msg = NULL;
        int status = 0;

        tsresp = NewTSResponse(cTimestampResponse);
        tsa_cert = GetX509CertPtr(certificate);
        sign_key = GetPrivPKeyPtr(key);
        GetTSRequest(request, req);

        gen_time = ossl_tsfac_get_gen_time(self);
        if (!rb_obj_is_instance_of(gen_time, rb_cTime)) {
            err_msg = "@gen_time must be a Time.";
            goto end;
        }
        lgen_time = NUM2LONG(rb_funcall(gen_time, rb_intern("to_i"), 0));

        serial_number = ossl_tsfac_get_serial_number(self);
        if (NIL_P(serial_number)) {
            err_msg = "@serial_number must be set.";
            goto end;
        }
        asn1_serial = num_to_asn1integer(serial_number, NULL);

        def_policy_id = ossl_tsfac_get_default_policy_id(self);
        if (NIL_P(def_policy_id) && !TS_REQ_get_policy_id(req)) {
            err_msg = "No policy id in the request and no default policy set";
            goto end;
        }
        if (!NIL_P(def_policy_id) && !TS_REQ_get_policy_id(req)) {
            def_policy_id_obj = (ASN1_OBJECT*)rb_protect(obj_to_asn1obj_i, (VALUE)def_policy_id, &status);
            if (status)
                goto end;
        }

        if (!(ctx = TS_RESP_CTX_new())) {
            err_msg = "Memory allocation failed.";
            goto end;
        }

        TS_RESP_CTX_set_serial_cb(ctx, ossl_tsfac_serial_cb, &asn1_serial);
        if (!TS_RESP_CTX_set_signer_cert(ctx, tsa_cert)) {
            err_msg = "Certificate does not contain the timestamping extension";
            goto end;
        }

        additional_certs = ossl_tsfac_get_additional_certs(self);
        if (rb_obj_is_kind_of(additional_certs, rb_cArray)) {
            inter_certs = ossl_protect_x509_ary2sk(additional_certs, &status);
            if (status)
                    goto end;

            /* this dups the sk_X509 and ups each cert's ref count */
            TS_RESP_CTX_set_certs(ctx, inter_certs);
            sk_X509_pop_free(inter_certs, X509_free);
        }

        TS_RESP_CTX_set_signer_key(ctx, sign_key);
        if (!NIL_P(def_policy_id) && !TS_REQ_get_policy_id(req))
            TS_RESP_CTX_set_def_policy(ctx, def_policy_id_obj);
        if (TS_REQ_get_policy_id(req))
            TS_RESP_CTX_set_def_policy(ctx, TS_REQ_get_policy_id(req));
        TS_RESP_CTX_set_time_cb(ctx, ossl_tsfac_time_cb, &lgen_time);

        allowed_digests = ossl_tsfac_get_allowed_digests(self);
        if (rb_obj_is_kind_of(allowed_digests, rb_cArray)) {
            int i;
            VALUE rbmd;
            const EVP_MD *md;

            for (i = 0; i < RARRAY_LEN(allowed_digests); i++) {
                rbmd = rb_ary_entry(allowed_digests, i);
                md = (const EVP_MD *)rb_protect(ossl_evp_get_digestbyname_i, rbmd, &status);
                if (status)
                    goto end;
                TS_RESP_CTX_add_md(ctx, md);
            }
        }

        str = rb_protect(ossl_to_der, request, &status);
        if (status)
            goto end;

        req_bio = (BIO*)rb_protect(ossl_obj2bio_i, (VALUE)&str, &status);
        if (status)
            goto end;

        response = TS_RESP_create_response(ctx, req_bio);
        BIO_free(req_bio);

        if (!response) {
            err_msg = "Error during response generation";
            goto end;
        }

        /* bad responses aren't exceptional, but openssl still sets error
         * information. */
        ossl_clear_error();

        SetTSResponse(tsresp, response);
        ret = tsresp;

    end:
        ASN1_INTEGER_free(asn1_serial);
        ASN1_OBJECT_free(def_policy_id_obj);
        TS_RESP_CTX_free(ctx);
        if (err_msg)
            rb_exc_raise(ossl_make_error(eTimestampError, rb_str_new_cstr(err_msg)));
        if (status)
            rb_jump_tag(status);
        return ret;
    }

Creates a `Response` with the help of an `OpenSSL::PKey`, an `OpenSSL::X509::Certificate` and a `Request`.

Mandatory parameters for timestamp creation that need to be set in the Request:

- `Request#algorithm`

- `Request#message_imprint`

Mandatory parameters that need to be set in the Factory:

- `Factory#serial_number`

- `Factory#gen_time`

- `Factory#allowed_digests`

In addition one of either `Request#policy_id` or `Factory#default_policy_id` must be set.

Raises a `TimestampError` if creation fails, though successfully created error responses may be returned.