# class OpenSSL::ASN1::Constructive

The parent class for all constructed encodings. The `value` attribute of a `Constructive` is always an `Array`. Attributes are the same as for `ASN1Data`, with the addition of `tagging`.

## SET and SEQUENCE¶ ↑

Most constructed encodings come in the form of a SET or a SEQUENCE. These encodings are represented by one of the two sub-classes of Constructive:

- OpenSSL::ASN1::Set

- OpenSSL::ASN1::Sequence

Please note that tagged sequences and sets are still parsed as instances of `ASN1Data`. `Find` further details on tagged values there.

### Example - constructing a SEQUENCE¶ ↑

    int = OpenSSL::ASN1::Integer.new(1)
    str = OpenSSL::ASN1::PrintableString.new('abc')
    sequence = OpenSSL::ASN1::Sequence.new( [ int, str ] )

### Example - constructing a SET¶ ↑

    int = OpenSSL::ASN1::Integer.new(1)
    str = OpenSSL::ASN1::PrintableString.new('abc')
    set = OpenSSL::ASN1::Set.new( [ int, str ] )

## Infinite length primitive values¶ ↑

The only case where `Constructive` is used directly is for infinite length encodings of primitive values. These encodings are always constructed, with the contents of the `value` `Array` being either UNIVERSAL non-infinite length partial encodings of the actual value or again constructive encodings with infinite length (i.e. infinite length primitive encodings may be constructed recursively with another infinite length value within an already infinite length value). Each partial encoding must be of the same UNIVERSAL type as the overall encoding. The value of the overall encoding consists of the concatenation of each partial encoding taken in sequence. The `value` array of the outer infinite length value must end with a OpenSSL::ASN1::EndOfContent instance.

Please note that it is not possible to encode `Constructive` without the `infinite_length` attribute being set to `true`, use OpenSSL::ASN1::Sequence or OpenSSL::ASN1::Set in these cases instead.

### Example - Infinite length OCTET STRING¶ ↑

    partial1 = OpenSSL::ASN1::OctetString.new("\x01")
    partial2 = OpenSSL::ASN1::OctetString.new("\x02")
    inf_octets = OpenSSL::ASN1::Constructive.new( [ partial1,
                                                    partial2,
                                                    OpenSSL::ASN1::EndOfContent.new ],
                                                  OpenSSL::ASN1::OCTET_STRING,
                                                  nil,
                                                  :UNIVERSAL )
    # The real value of inf_octets is "\x01\x02", i.e. the concatenation
    # of partial1 and partial2
    inf_octets.infinite_length = true
    der = inf_octets.to_der
    asn1 = OpenSSL::ASN1.decode(der)
    puts asn1.infinite_length # => true

### Attributes

tagging[RW]

May be used as a hint for encoding a value either implicitly or explicitly by setting it either to `:IMPLICIT` or to `:EXPLICIT`. `tagging` is not set when a ASN.1 structure is parsed using `OpenSSL::ASN1.decode`.

### Public Class Methods

OpenSSL::ASN1::Primitive.new( value [, tag, tagging, tag_class ]) → Primitive click to toggle source

`value`: is mandatory.

`tag`: optional, may be specified for tagged values. If no `tag` is specified, the UNIVERSAL tag corresponding to the `Primitive` sub-class is used by default.

`tagging`: may be used as an encoding hint to encode a value either explicitly or implicitly, see `ASN1` for possible values.

`tag_class`: if `tag` and `tagging` are `nil` then this is set to `:UNIVERSAL` by default. If either `tag` or `tagging` are set then `:CONTEXT_SPECIFIC` is used as the default. For possible values please cf. `ASN1`.

## Example¶ ↑

    int = OpenSSL::ASN1::Integer.new(42)
    zero_tagged_int = OpenSSL::ASN1::Integer.new(42, 0, :IMPLICIT)
    private_explicit_zero_tagged_int = OpenSSL::ASN1::Integer.new(42, 0, :EXPLICIT, :PRIVATE)

    static VALUE
    ossl_asn1_initialize(int argc, VALUE *argv, VALUE self)
    {
        VALUE value, tag, tagging, tag_class;

        rb_scan_args(argc, argv, "13", &value, &tag, &tagging, &tag_class);
        if(argc > 1){
            if(NIL_P(tag))
                ossl_raise(eASN1Error, "must specify tag number");
            if(!NIL_P(tagging) && !SYMBOL_P(tagging))
                ossl_raise(eASN1Error, "invalid tagging method");
            if(NIL_P(tag_class)) {
                if (NIL_P(tagging))
                    tag_class = sym_UNIVERSAL;
                else
                    tag_class = sym_CONTEXT_SPECIFIC;
            }
            if(!SYMBOL_P(tag_class))
                ossl_raise(eASN1Error, "invalid tag class");
            if (tagging == sym_IMPLICIT && NUM2INT(tag) > 31)
                ossl_raise(eASN1Error, "tag number for Universal too large");
        }
        else{
            tag = INT2NUM(ossl_asn1_default_tag(self));
            tagging = Qnil;
            tag_class = sym_UNIVERSAL;
        }
        ossl_asn1_set_tag(self, tag);
        ossl_asn1_set_value(self, value);
        ossl_asn1_set_tagging(self, tagging);
        ossl_asn1_set_tag_class(self, tag_class);
        ossl_asn1_set_infinite_length(self, Qfalse);

        return self;
    }

### Public Instance Methods

each { |asn1| block } → asn1_ary click to toggle source

Calls block once for each element in `self`, passing that element as parameter `asn1`. If no block is given, an enumerator is returned instead.

## Example¶ ↑

    asn1_ary.each do |asn1|
      puts asn1
    end

    static VALUE
    ossl_asn1cons_each(VALUE self)
    {
        rb_block_call(ossl_asn1_get_value(self), id_each, 0, 0, 0, 0);

        return self;
    }

to_der → DER-encoded String click to toggle source

See `ASN1Data#to_der` for details.

    static VALUE
    ossl_asn1cons_to_der(VALUE self)
    {
        int tag, tn, tc, explicit, constructed = 1;
        int found_prim = 0, seq_len;
        long length;
        unsigned char *p;
        VALUE value, str, inf_length;

        tn = NUM2INT(ossl_asn1_get_tag(self));
        tc = ossl_asn1_tag_class(self);
        inf_length = ossl_asn1_get_infinite_length(self);
        if (inf_length == Qtrue) {
            VALUE ary, example;
            constructed = 2;
            if (rb_obj_class(self) == cASN1Sequence ||
                rb_obj_class(self) == cASN1Set) {
                tag = ossl_asn1_default_tag(self);
            }
            else { /* must be a constructive encoding of a primitive value */
                ary = ossl_asn1_get_value(self);
                if (!rb_obj_is_kind_of(ary, rb_cArray))
                    ossl_raise(eASN1Error, "Constructive value must be an Array");
                /* Recursively descend until a primitive value is found.
                The overall value of the entire constructed encoding
                is of the type of the first primitive encoding to be
                found. */
                while (!found_prim){
                    example = rb_ary_entry(ary, 0);
                    if (rb_obj_is_kind_of(example, cASN1Primitive)){
                        found_prim = 1;
                    }
                    else {
                        /* example is another ASN1Constructive */
                        if (!rb_obj_is_kind_of(example, cASN1Constructive)){
                            ossl_raise(eASN1Error, "invalid constructed encoding");
                            return Qnil; /* dummy */
                        }
                        ary = ossl_asn1_get_value(example);
                    }
                }
                tag = ossl_asn1_default_tag(example);
            }
        }
        else {
            if (rb_obj_class(self) == cASN1Constructive)
                ossl_raise(eASN1Error, "Constructive shall only be used with infinite length");
            tag = ossl_asn1_default_tag(self);
        }
        explicit = ossl_asn1_is_explicit(self);
        value = join_der(ossl_asn1_get_value(self));

        seq_len = ASN1_object_size(constructed, RSTRING_LENINT(value), tag);
        length = ASN1_object_size(constructed, seq_len, tn);
        str = rb_str_new(0, length);
        p = (unsigned char *)RSTRING_PTR(str);
        if(tc == V_ASN1_UNIVERSAL)
            ASN1_put_object(&p, constructed, RSTRING_LENINT(value), tn, tc);
        else{
            if(explicit){
                ASN1_put_object(&p, constructed, seq_len, tn, tc);
                ASN1_put_object(&p, constructed, RSTRING_LENINT(value), tag, V_ASN1_UNIVERSAL);
            }
            else{
                ASN1_put_object(&p, constructed, RSTRING_LENINT(value), tn, tc);
            }
        }
        memcpy(p, RSTRING_PTR(value), RSTRING_LEN(value));
        p += RSTRING_LEN(value);

        /* In this case we need an additional EOC (one for the explicit part and
         * one for the Constructive itself. The EOC for the Constructive is
         * supplied by the user, but that for the "explicit wrapper" must be
         * added here.
         */
        if (explicit && inf_length == Qtrue) {
            ASN1_put_eoc(&p);
        }
        ossl_str_adjust(str, p);

        return str;
    }