1 // Copyright 2015 The Chromium Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
5 #ifndef NET_DER_PARSER_H_
6 #define NET_DER_PARSER_H_
8 #include "base/compiler_specific.h"
9 #include "base/time/time.h"
10 #include "net/base/net_export.h"
11 #include "net/der/input.h"
12 #include "net/der/tag.h"
20 // Parses a DER-encoded ASN.1 structure. DER (distinguished encoding rules)
21 // encodes each data value with a tag, length, and value (TLV). The tag
22 // indicates the type of the ASN.1 value. Depending on the type of the value,
23 // it could contain arbitrary bytes, so the length of the value is encoded
24 // after the tag and before the value to indicate how many bytes of value
25 // follow. DER also defines how the values are encoded for particular types.
27 // This Parser places a few restrictions on the DER encoding it can parse. The
28 // largest restriction is that it only supports tags which have a tag number
29 // no greater than 30 - these are the tags that fit in a single octet. The
30 // second restriction is that the maximum length for a value that can be parsed
31 // is 4GB. Both of these restrictions should be fine for any reasonable input.
33 // The Parser class is mainly focused on parsing the TLV structure of DER
34 // encoding, and does not directly handle parsing primitive values (other
35 // functions in the net::der namespace are provided for this.) When a Parser
36 // is created, it is passed in a reference to the encoded data. Because the
37 // encoded data is not owned by the Parser, the data cannot change during the
38 // lifespan of the Parser. The Parser functions by keeping a pointer to the
39 // current TLV which starts at the beginning of the input and advancing through
40 // the input as each TLV is read. As such, a Parser instance is thread-unsafe.
42 // Most methods for using the Parser write the current tag and/or value to
43 // the output parameters provided and then advance the input to the next TLV.
44 // None of the methods explicitly expose the length because it is part of the
45 // value. All methods return a boolean indicating whether there was a parsing
46 // error with the current TLV.
48 // Some methods are provided in the Parser class as convenience to both read
49 // the current TLV from the input and also parse the DER encoded value,
50 // converting it to a corresponding C++ type. These methods simply combine
51 // ReadTag() with the appropriate ParseType() free function.
53 // The design of DER encoding allows for nested data structures with
54 // constructed values, where the value is a series of TLVs. The Parser class
55 // is not designed to traverse through a nested encoding from a single object,
56 // but it does facilitate parsing nested data structures through the
57 // convenience methods ReadSequence() and the more general ReadConstructed(),
58 // which provide the user with another Parser object to traverse the next
61 // For a brief example of how to use the Parser, suppose we have the following
62 // ASN.1 type definition:
65 // bar OCTET STRING OPTIONAL,
66 // quux OCTET STRING }
68 // If we have a DER-encoded Foo in an Input |encoded_value|, the
69 // following code shows an example of how to parse the quux field from the
72 // bool ReadQuux(const Input& encoded_value, Input* quux_out) {
73 // Parser parser(encoded_value);
75 // if (!parser.ReadSequence(&foo_parser))
77 // if (!foo_parser->SkipOptionalTag(kOctetString))
79 // if (!foo_parser->ReadTag(kOctetString, quux_out))
83 class NET_EXPORT Parser
{
85 // Default constructor; equivalent to calling Parser(Input()). This only
86 // exists so that a Parser can be stack allocated and passed in to
87 // ReadConstructed() and similar methods.
90 // Creates a parser to parse over the data represented by input. This class
91 // assumes that the underlying data will not change over the lifetime of
93 explicit Parser(const Input
& input
);
95 // Returns whether there is any more data left in the input to parse. This
96 // does not guarantee that the data is parseable.
99 // Reads the current TLV from the input and advances. If the tag or length
100 // encoding for the current value is invalid, this method returns false and
101 // does not advance the input. Otherwise, it returns true, putting the
102 // read tag in |tag| and the value in |out|.
103 bool ReadTagAndValue(Tag
* tag
, Input
* out
) WARN_UNUSED_RESULT
;
105 // Reads the current TLV from the input and advances. Unlike ReadTagAndValue
106 // where only the value is put in |out|, this puts the raw bytes from the
107 // tag, length, and value in |out|.
108 bool ReadRawTLV(Input
* out
) WARN_UNUSED_RESULT
;
110 // Basic methods for reading or skipping the current TLV, with an
111 // expectation of what the current tag should be. It should be possible
112 // to parse any structure with these 4 methods; convenience methods are also
113 // provided to make some cases easier.
115 // If the current tag in the input is |tag|, it puts the corresponding value
116 // in |out|, sets |was_present| to true, and advances the input to the next
117 // TLV. If the current tag is something else, then |was_present| is set to
118 // false and the input is not advanced. Like ReadTagAndValue, it returns
119 // false if the encoding is invalid and does not advance the input.
120 bool ReadOptionalTag(Tag tag
,
122 bool* was_present
) WARN_UNUSED_RESULT
;
124 // Like ReadOptionalTag, but the value is discarded.
125 bool SkipOptionalTag(Tag tag
, bool* was_present
) WARN_UNUSED_RESULT
;
127 // If the current tag matches |tag|, it puts the current value in |out|,
128 // advances the input, and returns true. Otherwise, it returns false.
129 bool ReadTag(Tag tag
, Input
* out
) WARN_UNUSED_RESULT
;
131 // Advances the input and returns true if the current tag matches |tag|;
132 // otherwise it returns false.
133 bool SkipTag(Tag tag
) WARN_UNUSED_RESULT
;
135 // Convenience methods to combine parsing the TLV with parsing the DER
136 // encoding for a specific type.
138 // Reads the current TLV from the input, checks that the tag matches |tag|
139 // and is a constructed tag, and creates a new Parser from the value.
140 bool ReadConstructed(Tag tag
, Parser
* out
) WARN_UNUSED_RESULT
;
142 // A more specific form of ReadConstructed that expects the current tag
143 // to be 0x30 (SEQUENCE).
144 bool ReadSequence(Parser
* out
) WARN_UNUSED_RESULT
;
146 // Expects the current tag to be kInteger, and calls ParseUint64 on the
147 // current value. Note that DER-encoded integers are arbitrary precision,
148 // so this method will fail for valid input that represents an integer
149 // outside the range of an int64.
151 // Note that on failure the Parser is left in an undefined state (the
152 // input may or may not have been advanced).
153 bool ReadUint64(uint64_t* out
) WARN_UNUSED_RESULT
;
155 // Reads a BIT STRING. On success fills |out| and returns true.
157 // Note that on failure the Parser is left in an undefined state (the
158 // input may or may not have been advanced).
159 bool ReadBitString(BitString
* out
) WARN_UNUSED_RESULT
;
161 // Lower level methods. The previous methods couple reading data from the
162 // input with advancing the Parser's internal pointer to the next TLV; these
163 // lower level methods decouple those two steps into methods that read from
164 // the current TLV and a method that advances the internal pointer to the
167 // Reads the current TLV from the input, putting the tag in |tag| and the raw
168 // value in |out|, but does not advance the input. Returns true if the tag
169 // and length are successfully read and the output exists.
170 bool PeekTagAndValue(Tag
* tag
, Input
* out
) WARN_UNUSED_RESULT
;
172 // Advances the input to the next TLV. This method only needs to be called
173 // after PeekTagAndValue; all other methods will advance the input if they
181 DISALLOW_COPY(Parser
);
188 #endif // NET_DER_PARSER_H_