1 // Copyright 2009 The Go Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style
3 // license that can be found in the LICENSE file.
5 // Package asn1 implements parsing of DER-encoded ASN.1 data structures,
6 // as defined in ITU-T Rec X.690.
8 // See also ``A Layman's Guide to a Subset of ASN.1, BER, and DER,''
9 // http://luca.ntop.org/Teaching/Appunti/asn1.html.
12 // ASN.1 is a syntax for specifying abstract objects and BER, DER, PER, XER etc
13 // are different encoding formats for those objects. Here, we'll be dealing
14 // with DER, the Distinguished Encoding Rules. DER is used in X.509 because
15 // it's fast to parse and, unlike BER, has a unique encoding for every object.
16 // When calculating hashes over objects, it's important that the resulting
17 // bytes be the same at both ends and DER removes this margin of error.
19 // ASN.1 is very complex and this package doesn't attempt to implement
20 // everything by any means.
29 // A StructuralError suggests that the ASN.1 data is valid, but the Go type
30 // which is receiving it doesn't match.
31 type StructuralError struct {
35 func (e StructuralError) Error() string { return "ASN.1 structure error: " + e.Msg }
37 // A SyntaxError suggests that the ASN.1 data is invalid.
38 type SyntaxError struct {
42 func (e SyntaxError) Error() string { return "ASN.1 syntax error: " + e.Msg }
44 // We start by dealing with each of the primitive types in turn.
48 func parseBool(bytes []byte) (ret bool, err error) {
50 err = SyntaxError{"invalid boolean"}
54 return bytes[0] != 0, nil
59 // parseInt64 treats the given bytes as a big-endian, signed integer and
60 // returns the result.
61 func parseInt64(bytes []byte) (ret int64, err error) {
63 // We'll overflow an int64 in this case.
64 err = StructuralError{"integer too large"}
67 for bytesRead := 0; bytesRead < len(bytes); bytesRead++ {
69 ret |= int64(bytes[bytesRead])
72 // Shift up and down in order to sign extend the result.
73 ret <<= 64 - uint8(len(bytes))*8
74 ret >>= 64 - uint8(len(bytes))*8
78 // parseInt treats the given bytes as a big-endian, signed integer and returns
80 func parseInt32(bytes []byte) (int32, error) {
81 ret64, err := parseInt64(bytes)
85 if ret64 != int64(int32(ret64)) {
86 return 0, StructuralError{"integer too large"}
88 return int32(ret64), nil
91 var bigOne = big.NewInt(1)
93 // parseBigInt treats the given bytes as a big-endian, signed integer and returns
95 func parseBigInt(bytes []byte) *big.Int {
97 if len(bytes) > 0 && bytes[0]&0x80 == 0x80 {
98 // This is a negative number.
99 notBytes := make([]byte, len(bytes))
100 for i := range notBytes {
101 notBytes[i] = ^bytes[i]
103 ret.SetBytes(notBytes)
114 // BitString is the structure to use when you want an ASN.1 BIT STRING type. A
115 // bit string is padded up to the nearest byte in memory and the number of
116 // valid bits is recorded. Padding bits will be zero.
117 type BitString struct {
118 Bytes []byte // bits packed into bytes.
119 BitLength int // length in bits.
122 // At returns the bit at the given index. If the index is out of range it
124 func (b BitString) At(i int) int {
125 if i < 0 || i >= b.BitLength {
130 return int(b.Bytes[x]>>y) & 1
133 // RightAlign returns a slice where the padding bits are at the beginning. The
134 // slice may share memory with the BitString.
135 func (b BitString) RightAlign() []byte {
136 shift := uint(8 - (b.BitLength % 8))
137 if shift == 8 || len(b.Bytes) == 0 {
141 a := make([]byte, len(b.Bytes))
142 a[0] = b.Bytes[0] >> shift
143 for i := 1; i < len(b.Bytes); i++ {
144 a[i] = b.Bytes[i-1] << (8 - shift)
145 a[i] |= b.Bytes[i] >> shift
151 // parseBitString parses an ASN.1 bit string from the given byte slice and returns it.
152 func parseBitString(bytes []byte) (ret BitString, err error) {
154 err = SyntaxError{"zero length BIT STRING"}
157 paddingBits := int(bytes[0])
158 if paddingBits > 7 ||
159 len(bytes) == 1 && paddingBits > 0 ||
160 bytes[len(bytes)-1]&((1<<bytes[0])-1) != 0 {
161 err = SyntaxError{"invalid padding bits in BIT STRING"}
164 ret.BitLength = (len(bytes)-1)*8 - paddingBits
165 ret.Bytes = bytes[1:]
171 // An ObjectIdentifier represents an ASN.1 OBJECT IDENTIFIER.
172 type ObjectIdentifier []int
174 // Equal returns true iff oi and other represent the same identifier.
175 func (oi ObjectIdentifier) Equal(other ObjectIdentifier) bool {
176 if len(oi) != len(other) {
179 for i := 0; i < len(oi); i++ {
180 if oi[i] != other[i] {
188 // parseObjectIdentifier parses an OBJECT IDENTIFIER from the given bytes and
189 // returns it. An object identifier is a sequence of variable length integers
190 // that are assigned in a hierarchy.
191 func parseObjectIdentifier(bytes []byte) (s []int, err error) {
193 err = SyntaxError{"zero length OBJECT IDENTIFIER"}
197 // In the worst case, we get two elements from the first byte (which is
198 // encoded differently) and then every varint is a single byte long.
199 s = make([]int, len(bytes)+1)
201 // The first byte is 40*value1 + value2:
202 s[0] = int(bytes[0]) / 40
203 s[1] = int(bytes[0]) % 40
205 for offset := 1; offset < len(bytes); i++ {
207 v, offset, err = parseBase128Int(bytes, offset)
219 // An Enumerated is represented as a plain int.
224 // A Flag accepts any data and is set to true if present.
227 // parseBase128Int parses a base-128 encoded int from the given offset in the
228 // given byte slice. It returns the value and the new offset.
229 func parseBase128Int(bytes []byte, initOffset int) (ret, offset int, err error) {
231 for shifted := 0; offset < len(bytes); shifted++ {
233 err = StructuralError{"base 128 integer too large"}
244 err = SyntaxError{"truncated base 128 integer"}
250 func parseUTCTime(bytes []byte) (ret time.Time, err error) {
252 ret, err = time.Parse("0601021504Z0700", s)
254 ret, err = time.Parse("060102150405Z0700", s)
256 if err == nil && ret.Year() >= 2050 {
257 // UTCTime only encodes times prior to 2050. See https://tools.ietf.org/html/rfc5280#section-4.1.2.5.1
258 ret = ret.AddDate(-100, 0, 0)
264 // parseGeneralizedTime parses the GeneralizedTime from the given byte slice
265 // and returns the resulting time.
266 func parseGeneralizedTime(bytes []byte) (ret time.Time, err error) {
267 return time.Parse("20060102150405Z0700", string(bytes))
272 // parsePrintableString parses a ASN.1 PrintableString from the given byte
273 // array and returns it.
274 func parsePrintableString(bytes []byte) (ret string, err error) {
275 for _, b := range bytes {
277 err = SyntaxError{"PrintableString contains invalid character"}
285 // isPrintable returns true iff the given b is in the ASN.1 PrintableString set.
286 func isPrintable(b byte) bool {
287 return 'a' <= b && b <= 'z' ||
288 'A' <= b && b <= 'Z' ||
289 '0' <= b && b <= '9' ||
290 '\'' <= b && b <= ')' ||
291 '+' <= b && b <= '/' ||
296 // This is technically not allowed in a PrintableString.
297 // However, x509 certificates with wildcard strings don't
298 // always use the correct string type so we permit it.
304 // parseIA5String parses a ASN.1 IA5String (ASCII string) from the given
305 // byte slice and returns it.
306 func parseIA5String(bytes []byte) (ret string, err error) {
307 for _, b := range bytes {
309 err = SyntaxError{"IA5String contains invalid character"}
319 // parseT61String parses a ASN.1 T61String (8-bit clean string) from the given
320 // byte slice and returns it.
321 func parseT61String(bytes []byte) (ret string, err error) {
322 return string(bytes), nil
327 // parseUTF8String parses a ASN.1 UTF8String (raw UTF-8) from the given byte
328 // array and returns it.
329 func parseUTF8String(bytes []byte) (ret string, err error) {
330 return string(bytes), nil
333 // A RawValue represents an undecoded ASN.1 object.
334 type RawValue struct {
338 FullBytes []byte // includes the tag and length
341 // RawContent is used to signal that the undecoded, DER data needs to be
342 // preserved for a struct. To use it, the first field of the struct must have
343 // this type. It's an error for any of the other fields to have this type.
344 type RawContent []byte
348 // parseTagAndLength parses an ASN.1 tag and length pair from the given offset
349 // into a byte slice. It returns the parsed data and the new offset. SET and
350 // SET OF (tag 17) are mapped to SEQUENCE and SEQUENCE OF (tag 16) since we
351 // don't distinguish between ordered and unordered objects in this code.
352 func parseTagAndLength(bytes []byte, initOffset int) (ret tagAndLength, offset int, err error) {
356 ret.class = int(b >> 6)
357 ret.isCompound = b&0x20 == 0x20
358 ret.tag = int(b & 0x1f)
360 // If the bottom five bits are set, then the tag number is actually base 128
361 // encoded afterwards
363 ret.tag, offset, err = parseBase128Int(bytes, offset)
368 if offset >= len(bytes) {
369 err = SyntaxError{"truncated tag or length"}
375 // The length is encoded in the bottom 7 bits.
376 ret.length = int(b & 0x7f)
378 // Bottom 7 bits give the number of length bytes to follow.
379 numBytes := int(b & 0x7f)
381 err = SyntaxError{"indefinite length found (not DER)"}
385 for i := 0; i < numBytes; i++ {
386 if offset >= len(bytes) {
387 err = SyntaxError{"truncated tag or length"}
392 if ret.length >= 1<<23 {
393 // We can't shift ret.length up without
395 err = StructuralError{"length too large"}
401 // DER requires that lengths be minimal.
402 err = StructuralError{"superfluous leading zeros in length"}
411 // parseSequenceOf is used for SEQUENCE OF and SET OF values. It tries to parse
412 // a number of ASN.1 values from the given byte slice and returns them as a
413 // slice of Go values of the given type.
414 func parseSequenceOf(bytes []byte, sliceType reflect.Type, elemType reflect.Type) (ret reflect.Value, err error) {
415 expectedTag, compoundType, ok := getUniversalType(elemType)
417 err = StructuralError{"unknown Go type for slice"}
421 // First we iterate over the input and count the number of elements,
422 // checking that the types are correct in each case.
424 for offset := 0; offset < len(bytes); {
426 t, offset, err = parseTagAndLength(bytes, offset)
430 // We pretend that GENERAL STRINGs are PRINTABLE STRINGs so
431 // that a sequence of them can be parsed into a []string.
432 if t.tag == tagGeneralString {
433 t.tag = tagPrintableString
435 if t.class != classUniversal || t.isCompound != compoundType || t.tag != expectedTag {
436 err = StructuralError{"sequence tag mismatch"}
439 if invalidLength(offset, t.length, len(bytes)) {
440 err = SyntaxError{"truncated sequence"}
446 ret = reflect.MakeSlice(sliceType, numElements, numElements)
447 params := fieldParameters{}
449 for i := 0; i < numElements; i++ {
450 offset, err = parseField(ret.Index(i), bytes, offset, params)
459 bitStringType = reflect.TypeOf(BitString{})
460 objectIdentifierType = reflect.TypeOf(ObjectIdentifier{})
461 enumeratedType = reflect.TypeOf(Enumerated(0))
462 flagType = reflect.TypeOf(Flag(false))
463 timeType = reflect.TypeOf(time.Time{})
464 rawValueType = reflect.TypeOf(RawValue{})
465 rawContentsType = reflect.TypeOf(RawContent(nil))
466 bigIntType = reflect.TypeOf(new(big.Int))
469 // invalidLength returns true iff offset + length > sliceLength, or if the
470 // addition would overflow.
471 func invalidLength(offset, length, sliceLength int) bool {
472 return offset+length < offset || offset+length > sliceLength
475 // parseField is the main parsing function. Given a byte slice and an offset
476 // into the array, it will try to parse a suitable ASN.1 value out and store it
477 // in the given Value.
478 func parseField(v reflect.Value, bytes []byte, initOffset int, params fieldParameters) (offset int, err error) {
480 fieldType := v.Type()
482 // If we have run out of data, it may be that there are optional elements at the end.
483 if offset == len(bytes) {
484 if !setDefaultValue(v, params) {
485 err = SyntaxError{"sequence truncated"}
490 // Deal with raw values.
491 if fieldType == rawValueType {
493 t, offset, err = parseTagAndLength(bytes, offset)
497 if invalidLength(offset, t.length, len(bytes)) {
498 err = SyntaxError{"data truncated"}
501 result := RawValue{t.class, t.tag, t.isCompound, bytes[offset : offset+t.length], bytes[initOffset : offset+t.length]}
503 v.Set(reflect.ValueOf(result))
507 // Deal with the ANY type.
508 if ifaceType := fieldType; ifaceType.Kind() == reflect.Interface && ifaceType.NumMethod() == 0 {
510 t, offset, err = parseTagAndLength(bytes, offset)
514 if invalidLength(offset, t.length, len(bytes)) {
515 err = SyntaxError{"data truncated"}
518 var result interface{}
519 if !t.isCompound && t.class == classUniversal {
520 innerBytes := bytes[offset : offset+t.length]
522 case tagPrintableString:
523 result, err = parsePrintableString(innerBytes)
525 result, err = parseIA5String(innerBytes)
527 result, err = parseT61String(innerBytes)
529 result, err = parseUTF8String(innerBytes)
531 result, err = parseInt64(innerBytes)
533 result, err = parseBitString(innerBytes)
535 result, err = parseObjectIdentifier(innerBytes)
537 result, err = parseUTCTime(innerBytes)
541 // If we don't know how to handle the type, we just leave Value as nil.
549 v.Set(reflect.ValueOf(result))
553 universalTag, compoundType, ok1 := getUniversalType(fieldType)
555 err = StructuralError{fmt.Sprintf("unknown Go type: %v", fieldType)}
559 t, offset, err := parseTagAndLength(bytes, offset)
564 expectedClass := classContextSpecific
565 if params.application {
566 expectedClass = classApplication
568 if t.class == expectedClass && t.tag == *params.tag && (t.length == 0 || t.isCompound) {
570 t, offset, err = parseTagAndLength(bytes, offset)
575 if fieldType != flagType {
576 err = StructuralError{"Zero length explicit tag was not an asn1.Flag"}
583 // The tags didn't match, it might be an optional element.
584 ok := setDefaultValue(v, params)
588 err = StructuralError{"explicitly tagged member didn't match"}
594 // Special case for strings: all the ASN.1 string types map to the Go
595 // type string. getUniversalType returns the tag for PrintableString
596 // when it sees a string, so if we see a different string type on the
597 // wire, we change the universal type to match.
598 if universalTag == tagPrintableString {
600 case tagIA5String, tagGeneralString, tagT61String, tagUTF8String:
605 // Special case for time: UTCTime and GeneralizedTime both map to the
606 // Go type time.Time.
607 if universalTag == tagUTCTime && t.tag == tagGeneralizedTime {
608 universalTag = tagGeneralizedTime
611 expectedClass := classUniversal
612 expectedTag := universalTag
614 if !params.explicit && params.tag != nil {
615 expectedClass = classContextSpecific
616 expectedTag = *params.tag
619 if !params.explicit && params.application && params.tag != nil {
620 expectedClass = classApplication
621 expectedTag = *params.tag
624 // We have unwrapped any explicit tagging at this point.
625 if t.class != expectedClass || t.tag != expectedTag || t.isCompound != compoundType {
626 // Tags don't match. Again, it could be an optional element.
627 ok := setDefaultValue(v, params)
631 err = StructuralError{fmt.Sprintf("tags don't match (%d vs %+v) %+v %s @%d", expectedTag, t, params, fieldType.Name(), offset)}
635 if invalidLength(offset, t.length, len(bytes)) {
636 err = SyntaxError{"data truncated"}
639 innerBytes := bytes[offset : offset+t.length]
642 // We deal with the structures defined in this package first.
644 case objectIdentifierType:
645 newSlice, err1 := parseObjectIdentifier(innerBytes)
646 v.Set(reflect.MakeSlice(v.Type(), len(newSlice), len(newSlice)))
648 reflect.Copy(v, reflect.ValueOf(newSlice))
653 bs, err1 := parseBitString(innerBytes)
655 v.Set(reflect.ValueOf(bs))
662 if universalTag == tagUTCTime {
663 time, err1 = parseUTCTime(innerBytes)
665 time, err1 = parseGeneralizedTime(innerBytes)
668 v.Set(reflect.ValueOf(time))
673 parsedInt, err1 := parseInt32(innerBytes)
675 v.SetInt(int64(parsedInt))
683 parsedInt := parseBigInt(innerBytes)
684 v.Set(reflect.ValueOf(parsedInt))
687 switch val := v; val.Kind() {
689 parsedBool, err1 := parseBool(innerBytes)
691 val.SetBool(parsedBool)
695 case reflect.Int, reflect.Int32, reflect.Int64:
696 if val.Type().Size() == 4 {
697 parsedInt, err1 := parseInt32(innerBytes)
699 val.SetInt(int64(parsedInt))
703 parsedInt, err1 := parseInt64(innerBytes)
705 val.SetInt(parsedInt)
710 // TODO(dfc) Add support for the remaining integer types
712 structType := fieldType
714 if structType.NumField() > 0 &&
715 structType.Field(0).Type == rawContentsType {
716 bytes := bytes[initOffset:offset]
717 val.Field(0).Set(reflect.ValueOf(RawContent(bytes)))
721 for i := 0; i < structType.NumField(); i++ {
722 field := structType.Field(i)
723 if i == 0 && field.Type == rawContentsType {
726 innerOffset, err = parseField(val.Field(i), innerBytes, innerOffset, parseFieldParameters(field.Tag.Get("asn1")))
731 // We allow extra bytes at the end of the SEQUENCE because
732 // adding elements to the end has been used in X.509 as the
733 // version numbers have increased.
736 sliceType := fieldType
737 if sliceType.Elem().Kind() == reflect.Uint8 {
738 val.Set(reflect.MakeSlice(sliceType, len(innerBytes), len(innerBytes)))
739 reflect.Copy(val, reflect.ValueOf(innerBytes))
742 newSlice, err1 := parseSequenceOf(innerBytes, sliceType, sliceType.Elem())
750 switch universalTag {
751 case tagPrintableString:
752 v, err = parsePrintableString(innerBytes)
754 v, err = parseIA5String(innerBytes)
756 v, err = parseT61String(innerBytes)
758 v, err = parseUTF8String(innerBytes)
759 case tagGeneralString:
760 // GeneralString is specified in ISO-2022/ECMA-35,
761 // A brief review suggests that it includes structures
762 // that allow the encoding to change midstring and
763 // such. We give up and pass it as an 8-bit string.
764 v, err = parseT61String(innerBytes)
766 err = SyntaxError{fmt.Sprintf("internal error: unknown string type %d", universalTag)}
773 err = StructuralError{"unsupported: " + v.Type().String()}
777 // setDefaultValue is used to install a default value, from a tag string, into
778 // a Value. It is successful is the field was optional, even if a default value
779 // wasn't provided or it failed to install it into the Value.
780 func setDefaultValue(v reflect.Value, params fieldParameters) (ok bool) {
781 if !params.optional {
785 if params.defaultValue == nil {
788 switch val := v; val.Kind() {
789 case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
790 val.SetInt(*params.defaultValue)
795 // Unmarshal parses the DER-encoded ASN.1 data structure b
796 // and uses the reflect package to fill in an arbitrary value pointed at by val.
797 // Because Unmarshal uses the reflect package, the structs
798 // being written to must use upper case field names.
800 // An ASN.1 INTEGER can be written to an int, int32, int64,
801 // or *big.Int (from the math/big package).
802 // If the encoded value does not fit in the Go type,
803 // Unmarshal returns a parse error.
805 // An ASN.1 BIT STRING can be written to a BitString.
807 // An ASN.1 OCTET STRING can be written to a []byte.
809 // An ASN.1 OBJECT IDENTIFIER can be written to an
812 // An ASN.1 ENUMERATED can be written to an Enumerated.
814 // An ASN.1 UTCTIME or GENERALIZEDTIME can be written to a time.Time.
816 // An ASN.1 PrintableString or IA5String can be written to a string.
818 // Any of the above ASN.1 values can be written to an interface{}.
819 // The value stored in the interface has the corresponding Go type.
820 // For integers, that type is int64.
822 // An ASN.1 SEQUENCE OF x or SET OF x can be written
823 // to a slice if an x can be written to the slice's element type.
825 // An ASN.1 SEQUENCE or SET can be written to a struct
826 // if each of the elements in the sequence can be
827 // written to the corresponding element in the struct.
829 // The following tags on struct fields have special meaning to Unmarshal:
831 // optional marks the field as ASN.1 OPTIONAL
832 // [explicit] tag:x specifies the ASN.1 tag number; implies ASN.1 CONTEXT SPECIFIC
833 // default:x sets the default value for optional integer fields
835 // If the type of the first field of a structure is RawContent then the raw
836 // ASN1 contents of the struct will be stored in it.
838 // Other ASN.1 types are not supported; if it encounters them,
839 // Unmarshal returns a parse error.
840 func Unmarshal(b []byte, val interface{}) (rest []byte, err error) {
841 return UnmarshalWithParams(b, val, "")
844 // UnmarshalWithParams allows field parameters to be specified for the
845 // top-level element. The form of the params is the same as the field tags.
846 func UnmarshalWithParams(b []byte, val interface{}, params string) (rest []byte, err error) {
847 v := reflect.ValueOf(val).Elem()
848 offset, err := parseField(v, b, 0, parseFieldParameters(params))
852 return b[offset:], nil