Class: RASN1::Types::Base Abstract

Inherits:
Object
  • Object
show all
Defined in:
lib/rasn1/types/base.rb,
lib/rasn1/tracer.rb

Overview

This class is abstract.

This is base class for all ASN.1 types.

Subclasses SHOULD define:

  • an ID constant defining ASN.1 BER/DER identification number,

  • a private method #value_to_der converting its #value to DER,

  • a private method #der_to_value converting DER into #value.

Define an optional value

An optional value may be defined using :optional key from #initialize:

Integer.new(:int, optional: true)

An optional value implies:

  • while parsing, if decoded ID is not optional expected ID, no ASN1Error is raised, and parser tries next field,

  • while encoding, if #value is nil, this value is not encoded.

Define a default value

A default value may be defined using :default key from #initialize:

Integer.new(:int, default: 0)

A default value implies:

  • while parsing, if decoded ID is not expected one, no ASN1Error is raised and parser sets default value to this ID. Then parser tries next field,

  • while encoding, if #value is equal to default value, this value is not encoded.

Define a tagged value

ASN.1 permits to define tagged values. By example:

-- context specific tag
CType ::= [0] EXPLICIT INTEGER
-- application specific tag
AType ::= [APPLICATION 1] EXPLICIT INTEGER
-- private tag
PType ::= [PRIVATE 2] EXPLICIT INTEGER

These types may be defined as:

ctype = RASN1::Types::Integer.new(explicit: 0)                      # with explicit, default #asn1_class is :context
atype = RASN1::Types::Integer.new(explicit: 1, class: :application)
ptype = RASN1::Types::Integer.new(explicit: 2, class: :private)

Sometimes, an EXPLICIT type should be CONSTRUCTED. To do that, use :constructed option:

ptype = RASN1::Types::Integer.new(explicit: 2, class: :private, constructed: true)

Implicit tagged values may also be defined:

ctype_implicit = RASN1::Types::Integer.new(implicit: 0)

Author:

  • Sylvain Daubert

Constant Summary collapse

CLASSES =

Allowed ASN.1 classes

{
  universal: 0x00,
  application: 0x40,
  context: 0x80,
  private: 0xc0
}.freeze
CLASS_MASK =

Binary mask to get class

0xc0
MULTI_OCTETS_ID = 
0x1f
INDEFINITE_LENGTH =

Length value for indefinite length

0x80

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ Base

Returns a new instance of Base.

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :class (Symbol) —

    ASN.1 class. Default value is :universal. If :explicit or :implicit: is defined, default value is :context.

  • :optional (::Boolean) —

    define this tag as optional. Default is false

  • :default (Object) —

    default value (ASN.1 DEFAULT)

  • :value (Object) —

    value to set

  • :implicit (::Integer) —

    define an IMPLICIT tagged type

  • :explicit (::Integer) —

    define an EXPLICIT tagged type

  • :constructed (::Boolean) —

    if true, set type as constructed. May only be used when :explicit is defined, else it is discarded.

  • :name (::String) —

    name for this node



125
126
127
128
129
130
131
132
 
# File 'lib/rasn1/types/base.rb', line 125

def initialize(options={})
  @constructed = nil
  set_value(options.delete(:value))
  self.options = options
  specific_initializer
  @raw_data = ''.b
  @raw_length = ''.b
end

Instance Attribute Details

#asn1_class ⇒ Symbol (readonly)

Returns:

  • (Symbol) 


69
70
71
 
# File 'lib/rasn1/types/base.rb', line 69

def asn1_class
  @asn1_class
end

#default ⇒ Object? (readonly)

Returns default value, if defined.

Returns:

  • (Object, nil) —

    default value, if defined



71
72
73
 
# File 'lib/rasn1/types/base.rb', line 71

def default
  @default
end

#name ⇒ String? (readonly)

Returns:

  • (String, nil) 


67
68
69
 
# File 'lib/rasn1/types/base.rb', line 67

def name
  @name
end

#options ⇒ Hash[Symbol, Object]

Returns:

  • (Hash[Symbol, Object]) 


73
74
75
 
# File 'lib/rasn1/types/base.rb', line 73

def options
  @options
end

Class Method Details

.constrained? ⇒ Booleran

Say if a type is constrained. Always return false for predefined types

Returns:

  • (Booleran) 


109
110
111
 
# File 'lib/rasn1/types/base.rb', line 109

def self.constrained?
  false
end

.encoded_type ⇒ String

Get ASN.1 type used to encode this one

Returns:

  • (String) 


91
92
93
 
# File 'lib/rasn1/types/base.rb', line 91

def self.encoded_type
  type
end

.parse(der_or_ber, options = {}) ⇒ Object

Note:

More options are supported. See #initialize.

Parse a DER or BER string

Parameters:

  • der_or_ber (String) —

    string to parse

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :ber (Boolean) —

    if true, parse a BER string, else a DER one



100
101
102
103
104
 
# File 'lib/rasn1/types/base.rb', line 100

def self.parse(der_or_ber, options={})
  obj = self.new(options)
  obj.parse!(der_or_ber, ber: options[:ber])
  obj
end

.start_tracing ⇒ Object

Patch #do_parse to add tracing ability



68
69
70
71
72
73
 
# File 'lib/rasn1/tracer.rb', line 68

def start_tracing
  alias_method :do_parse_without_tracing, :do_parse
  alias_method :do_parse, :do_parse_with_tracing
  alias_method :do_parse_explicit_without_tracing, :do_parse_explicit
  alias_method :do_parse_explicit, :do_parse_explicit_with_tracing
end

.stop_tracing ⇒ Object

Unpatch #do_parse to remove tracing ability



77
78
79
80
 
# File 'lib/rasn1/tracer.rb', line 77

def stop_tracing
  alias_method :do_parse, :do_parse_without_tracing
  alias_method :do_parse_explicit, :do_parse_explicit_without_tracing
end

.type ⇒ String

Get ASN.1 type

Returns:

  • (String) 


83
84
85
86
87
 
# File 'lib/rasn1/types/base.rb', line 83

def self.type
  return @type if defined? @type

  @type = self.to_s.gsub(/.*::/, '').gsub(/([a-z0-9])([A-Z])/, '\1 \2').upcase
end

Instance Method Details

#==(other) ⇒ Boolean

Objects are equal if they have same class AND same DER

Parameters:

Returns:



259
260
261
 
# File 'lib/rasn1/types/base.rb', line 259

def ==(other)
  (other.class == self.class) && (other.to_der == self.to_der)
end

#can_build? ⇒ Boolean

Say if DER can be built (not default value, not optional without value, has a value)

Returns:

Since:

  • 0.12.0



286
287
288
 
# File 'lib/rasn1/types/base.rb', line 286

def can_build?
  value? && (@default.nil? || (@value != @default))
end

#constructed? ⇒ ::Boolean

Returns true if this is a constructed type.

Returns:

  • (::Boolean) —

    true if this is a constructed type



204
205
206
 
# File 'lib/rasn1/types/base.rb', line 204

def constructed?
  (self.class < Constructed) || !!@constructed
end

#do_parse_explicit_with_tracing(data) ⇒ Object 



92
93
94
95
96
 
# File 'lib/rasn1/tracer.rb', line 92

def do_parse_explicit_with_tracing(data)
  RASN1.tracer.tracing_level += 1
  do_parse_explicit_without_tracing(data)
  RASN1.tracer.tracing_level -= 1
end

#do_parse_with_tracing(der, ber) ⇒ Object

Parse der with tracing abillity

See Also:



86
87
88
89
90
 
# File 'lib/rasn1/tracer.rb', line 86

def do_parse_with_tracing(der, ber)
  ret = do_parse_without_tracing(der, ber)
  RASN1.tracer.trace(self.trace)
  ret
end

#explicit? ⇒ ::Boolean?

Say if a tagged type is explicit

Returns:

  • (::Boolean, nil) —

    return nil if not tagged, return true if explicit, else false



180
181
182
 
# File 'lib/rasn1/types/base.rb', line 180

def explicit?
  defined?(@tag) ? @tag == :explicit : nil
end

#id ⇒ Integer

Get identifier value

Returns:



216
217
218
 
# File 'lib/rasn1/types/base.rb', line 216

def id
  id_value
end

#implicit? ⇒ ::Boolean?

Say if a tagged type is implicit

Returns:

  • (::Boolean, nil) —

    return nil if not tagged, return true if implicit, else false



187
188
189
 
# File 'lib/rasn1/types/base.rb', line 187

def implicit?
  defined?(@tag) ? @tag == :implicit : nil
end

#initialize_copy ⇒ Object

Deep copy @value and @default.



138
139
140
141
142
143
 
# File 'lib/rasn1/types/base.rb', line 138

def initialize_copy(*)
  super
  @value = @value.dup
  @no_value = @no_value.dup
  @default = @default.dup
end

#inspect(level = 0) ⇒ String

Parameters:

Returns:

  • (String) 


248
249
250
251
252
253
254
 
# File 'lib/rasn1/types/base.rb', line 248

def inspect(level=0)
  str = common_inspect(level)
  str << ' ' << inspect_value
  str << ' OPTIONAL' if optional?
  str << " DEFAULT #{@default}" unless @default.nil?
  str
end

#optional? ⇒ ::Boolean

Say if this type is optional

Returns:

  • (::Boolean) 


167
168
169
 
# File 'lib/rasn1/types/base.rb', line 167

def optional?
  @optional
end

#parse!(der, ber: false) ⇒ Integer

This method is abstract.

This method SHOULD be partly implemented by subclasses to parse data. Subclasses SHOULD respond to #der_to_value.

Parse a DER string. This method updates object.

Parameters:

  • der (String) —

    DER string

  • ber (Boolean) (defaults to: false) —

    if true, accept BER encoding

Returns:

  • (Integer) —

    total number of parsed bytes

Raises:



227
228
229
230
231
232
233
234
235
236
237
238
 
# File 'lib/rasn1/types/base.rb', line 227

def parse!(der, ber: false)
  total_length, data = do_parse(der, ber)
  return 0 if total_length.zero?

  if explicit?
    do_parse_explicit(data)
  else
    der_to_value(data, ber: ber)
  end

  total_length
end

#primitive? ⇒ ::Boolean

Returns true if this is a primitive type.

Returns:

  • (::Boolean) —

    true if this is a primitive type



199
200
201
 
# File 'lib/rasn1/types/base.rb', line 199

def primitive?
  (self.class < Primitive) && !@constructed
end

#specific_initializer ⇒ Object

This method is abstract.

To help subclass initialize itself. Default implementation do nothing.



135
 
# File 'lib/rasn1/types/base.rb', line 135

def specific_initializer; end

#tagged? ⇒ ::Boolean

Say if this type is tagged or not

Returns:

  • (::Boolean) 


173
174
175
 
# File 'lib/rasn1/types/base.rb', line 173

def tagged?
  !@tag.nil?
end

#to_der ⇒ String

This method is abstract.

This method SHOULD be partly implemented by subclasses, which SHOULD respond to #value_to_der.

Returns DER-formated string.

Returns:

  • (String) —

    DER-formated string



194
195
196
 
# File 'lib/rasn1/types/base.rb', line 194

def to_der
  build
end

#trace ⇒ String

Returns:

  • (String) 


292
293
294
295
296
297
298
299
300
301
 
# File 'lib/rasn1/types/base.rb', line 292

def trace
  return trace_real if value?

  msg = msg_type
  if default.nil? # rubocop:disable Style/ConditionalAssignment
    msg << ' NONE'
  else
    msg << " DEFAULT VALUE #{default}"
  end
end

#type ⇒ String

Get ASN.1 type

Returns:

  • (String) 


210
211
212
 
# File 'lib/rasn1/types/base.rb', line 210

def type
  self.class.type
end

#value ⇒ Object

Get value or default value



146
147
148
149
150
151
152
 
# File 'lib/rasn1/types/base.rb', line 146

def value
  if value?
    @value
  else
    @default
  end
end

#value=(val) ⇒ Object

Set value. If val is nil, unset value

Parameters:

  • val (Object, nil) 


156
157
158
 
# File 'lib/rasn1/types/base.rb', line 156

def value=(val)
  set_value(val)
end

#value? ⇒ Boolean

Say if a value is set

Returns:

Since:

  • 0.12.0



279
280
281
 
# File 'lib/rasn1/types/base.rb', line 279

def value?
  !@no_value
end

#value_size ⇒ Integer

Give size in octets of encoded value

Returns:



242
243
244
 
# File 'lib/rasn1/types/base.rb', line 242

def value_size
  value_to_der.size
end

#void_value ⇒ Object

This method is abstract.

Define ‘void’ value (i.e. ‘value’ when no value was set)



161
162
163
 
# File 'lib/rasn1/types/base.rb', line 161

def void_value
  ''
end