Crypto++ 8.2 Free C++ class library of cryptographic schemes

Classes | Enumerations | Functions
asn.h File Reference

Classes and functions for working with ANS.1 objects. More...

Go to the source code of this file.

## Classes
class | UnknownOID
| Exception thrown when an unknown object identifier is encountered. More...
class | OID
| Object Identifier. More...
class | EncodedObjectFilter
| ASN.1 encoded object filter. More...
class | BERGeneralDecoder
| BER General Decoder. More...
class | DERGeneralEncoder
| DER General Encoder. More...
class | BERSequenceDecoder
| BER Sequence Decoder. More...
class | DERSequenceEncoder
| DER Sequence Encoder. More...
class | BERSetDecoder
| BER Set Decoder. More...
class | DERSetEncoder
| DER Set Encoder. More...
class | ASNOptional< T >
| Optional data encoder and decoder. More...
class | ASN1CryptoMaterial< BASE >
| Encode and decode ASN.1 objects with additional information. More...
class | X509PublicKey
| Encodes and decodes subjectPublicKeyInfo. More...
class | PKCS8PrivateKey
| Encodes and Decodes privateKeyInfo. More...

## Enumerations
enum | ASNTag { BOOLEAN = 0x01, INTEGER = 0x02, BIT_STRING = 0x03, OCTET_STRING = 0x04, TAG_NULL = 0x05, OBJECT_IDENTIFIER = 0x06, OBJECT_DESCRIPTOR = 0x07, EXTERNAL = 0x08, REAL = 0x09, ENUMERATED = 0x0a, UTF8_STRING = 0x0c, SEQUENCE = 0x10, SET = 0x11, NUMERIC_STRING = 0x12, PRINTABLE_STRING = 0x13, T61_STRING = 0x14, VIDEOTEXT_STRING = 0x15, IA5_STRING = 0x16, UTC_TIME = 0x17, GENERALIZED_TIME = 0x18, GRAPHIC_STRING = 0x19, VISIBLE_STRING = 0x1a, GENERAL_STRING = 0x1b, UNIVERSAL_STRING = 0x1c, BMP_STRING = 0x1e }
| ASN.1 types. More...
enum | ASNIdFlag { UNIVERSAL = 0x00, PRIMITIVE = 0x00, CONSTRUCTED = 0x20, APPLICATION = 0x40, CONTEXT_SPECIFIC = 0x80, PRIVATE = 0xc0 }
| ASN.1 flags. More...

## Functions
void | BERDecodeError ()
| Raises a BERDecodeErr.
CRYPTOPP_DLL size_t CRYPTOPP_API | DERLengthEncode (BufferedTransformation &bt, lword length)
| DER encode a length. More...
CRYPTOPP_DLL bool CRYPTOPP_API | BERLengthDecode (BufferedTransformation &bt, size_t &length)
| BER decode a length. More...
CRYPTOPP_DLL void CRYPTOPP_API | DEREncodeNull (BufferedTransformation &bt)
| DER encode NULL. More...
CRYPTOPP_DLL void CRYPTOPP_API | BERDecodeNull (BufferedTransformation &bt)
| BER decode NULL. More...
CRYPTOPP_DLL size_t CRYPTOPP_API | DEREncodeOctetString (BufferedTransformation &bt, const byte *str, size_t strLen)
| DER encode octet string. More...
CRYPTOPP_DLL size_t CRYPTOPP_API | DEREncodeOctetString (BufferedTransformation &bt, const SecByteBlock &str)
| DER encode octet string. More...
CRYPTOPP_DLL size_t CRYPTOPP_API | BERDecodeOctetString (BufferedTransformation &bt, SecByteBlock &str)
| BER decode octet string. More...
CRYPTOPP_DLL size_t CRYPTOPP_API | BERDecodeOctetString (BufferedTransformation &bt, BufferedTransformation &str)
| BER decode octet string. More...
CRYPTOPP_DLL size_t CRYPTOPP_API | DEREncodeTextString (BufferedTransformation &bt, const byte *str, size_t strLen, byte asnTag)
| DER encode text string. More...
CRYPTOPP_DLL size_t CRYPTOPP_API | DEREncodeTextString (BufferedTransformation &bt, const SecByteBlock &str, byte asnTag)
| DER encode text string. More...
CRYPTOPP_DLL size_t CRYPTOPP_API | DEREncodeTextString (BufferedTransformation &bt, const std::string &str, byte asnTag)
| DER encode text string. More...
CRYPTOPP_DLL size_t CRYPTOPP_API | BERDecodeTextString (BufferedTransformation &bt, SecByteBlock &str, byte asnTag)
| BER decode text string. More...
CRYPTOPP_DLL size_t CRYPTOPP_API | BERDecodeTextString (BufferedTransformation &bt, std::string &str, byte asnTag)
| BER decode text string. More...
CRYPTOPP_DLL size_t CRYPTOPP_API | DEREncodeDate (BufferedTransformation &bt, const SecByteBlock &str, byte asnTag)
| DER encode date. More...
CRYPTOPP_DLL size_t CRYPTOPP_API | BERDecodeDate (BufferedTransformation &bt, SecByteBlock &str, byte asnTag)
| BER decode date. More...
CRYPTOPP_DLL size_t CRYPTOPP_API | DEREncodeBitString (BufferedTransformation &bt, const byte *str, size_t strLen, unsigned int unusedBits=0)
| DER encode bit string. More...
CRYPTOPP_DLL size_t CRYPTOPP_API | BERDecodeBitString (BufferedTransformation &bt, SecByteBlock &str, unsigned int &unusedBits)
| DER decode bit string. More...
CRYPTOPP_DLL void CRYPTOPP_API | DERReencode (BufferedTransformation &bt, BufferedTransformation &dest)
| BER decode and DER re-encode. More...
CRYPTOPP_DLL size_t CRYPTOPP_API | BERDecodePeekLength (const BufferedTransformation &bt)
| BER decode size. More...
template<class T >
size_t | DEREncodeUnsigned (BufferedTransformation &out, T w, byte asnTag=INTEGER)
| DER Encode unsigned value. More...
template<class T >
void | BERDecodeUnsigned (BufferedTransformation &in, T &w, byte asnTag=INTEGER, T minValue=0, T maxValue=T(0xffffffff))
| BER Decode unsigned value. More...
bool | operator== (const OID &lhs, const OID &rhs)
| Compare two OIDs for equality. More...
bool | operator!= (const OID &lhs, const OID &rhs)
| Compare two OIDs for inequality. More...
bool | operator< (const OID &lhs, const OID &rhs)
| Compare two OIDs for ordering. More...
bool | operator<= (const OID &lhs, const OID &rhs)
| Compare two OIDs for ordering. More...
bool | operator>= (const OID &lhs, const OID &rhs)
| Compare two OIDs for ordering. More...
OID | operator+ (const OID &lhs, unsigned long rhs)
| Append a value to an OID. More...
std::ostream & | operator<< (std::ostream &out, const OID &oid)
| Print a OID value. More...

## Detailed Description

Classes and functions for working with ANS.1 objects.

Definition in file asn.h.

## Enumeration Type Documentation

## ◆ ASNTag

enum ASNTag

ASN.1 types.

Note
  These tags are not complete

Enumerator
BOOLEAN | ASN.1 Boolean.
INTEGER | ASN.1 Integer.
BIT_STRING | ASN.1 Bit string.
OCTET_STRING | ASN.1 Octet string.
TAG_NULL | ASN.1 Null.
OBJECT_IDENTIFIER | ASN.1 Object identifier.
OBJECT_DESCRIPTOR | ASN.1 Object descriptor.
EXTERNAL | ASN.1 External reference.
REAL | ASN.1 Real integer.
ENUMERATED | ASN.1 Enumerated value.
UTF8_STRING | ASN.1 UTF-8 string.
SEQUENCE | ASN.1 Sequence.
SET | ASN.1 Set.
NUMERIC_STRING | ASN.1 Numeric string.
PRINTABLE_STRING | ASN.1 Printable string.
T61_STRING | ASN.1 T61 string.
VIDEOTEXT_STRING | ASN.1 Videotext string.
IA5_STRING | ASN.1 IA5 string.
UTC_TIME | ASN.1 UTC time.
GENERALIZED_TIME | ASN.1 Generalized time.
GRAPHIC_STRING | ASN.1 Graphic string.
VISIBLE_STRING | ASN.1 Visible string.
GENERAL_STRING | ASN.1 General string.
UNIVERSAL_STRING | ASN.1 Universal string.
BMP_STRING | ASN.1 BMP string.

Definition at line 29 of file asn.h.

## ◆ ASNIdFlag

enum ASNIdFlag

ASN.1 flags.

Note
  These flags are not complete

Enumerator
UNIVERSAL | ASN.1 Universal class.
PRIMITIVE | ASN.1 Primitive flag.
CONSTRUCTED | ASN.1 Constructed flag.
APPLICATION | ASN.1 Application class.
CONTEXT_SPECIFIC | ASN.1 Context specific class.
PRIVATE | ASN.1 Private class.

Definition at line 85 of file asn.h.

## Function Documentation

## ◆ DERLengthEncode()

CRYPTOPP_DLL size_t CRYPTOPP_API DERLengthEncode | ( | BufferedTransformation & | bt,
|  | lword | length
| ) |  |

DER encode a length.

Parameters

  bt | BufferedTransformation object for writing
  length | the size to encode

Returns
  the number of octets used for the encoding

Definition at line 20 of file asn.cpp.

## ◆ BERLengthDecode()

CRYPTOPP_DLL bool CRYPTOPP_API BERLengthDecode | ( | BufferedTransformation & | bt,
|  | size_t & | length
| ) |  |

BER decode a length.

Parameters

  bt | BufferedTransformation object for reading
  length | the decoded size

Returns
  true if the value was decoded

Exceptions

  BERDecodeError | if the value fails to decode or is too large for size_t

BERLengthDecode() returns false if the encoding is indefinite length.

Definition at line 79 of file asn.cpp.

## ◆ DEREncodeNull()

CRYPTOPP_DLL void CRYPTOPP_API DEREncodeNull | ( | BufferedTransformation & | bt | ) |

DER encode NULL.

Parameters

  bt | BufferedTransformation object for writing

Definition at line 90 of file asn.cpp.

## ◆ BERDecodeNull()

CRYPTOPP_DLL void CRYPTOPP_API BERDecodeNull | ( | BufferedTransformation & | bt | ) |

BER decode NULL.

Parameters

  bt | BufferedTransformation object for reading

Definition at line 96 of file asn.cpp.

## ◆ DEREncodeOctetString() [1/2]

CRYPTOPP_DLL size_t CRYPTOPP_API DEREncodeOctetString | ( | BufferedTransformation & | bt,
|  | const byte * | str,
|  | size_t | strLen
| ) |  |

DER encode octet string.

Parameters

  bt | BufferedTransformation object for writing
  str | the string to encode
  strLen | the length of the string

Returns
  the number of octets used for the encoding

DER encode octet string.

Definition at line 107 of file asn.cpp.

## ◆ DEREncodeOctetString() [2/2]

CRYPTOPP_DLL size_t CRYPTOPP_API DEREncodeOctetString | ( | BufferedTransformation & | bt,
|  | const SecByteBlock & | str
| ) |  |

DER encode octet string.

Parameters

  bt | BufferedTransformation object for reading
  str | the string to encode

Returns
  the number of octets used for the encoding

Definition at line 115 of file asn.cpp.

## ◆ BERDecodeOctetString() [1/2]

CRYPTOPP_DLL size_t CRYPTOPP_API BERDecodeOctetString | ( | BufferedTransformation & | bt,
|  | SecByteBlock & | str
| ) |  |

BER decode octet string.

Parameters

  bt | BufferedTransformation object for reading
  str | the decoded string

Returns
  the number of octets used for the encoding

Definition at line 120 of file asn.cpp.

## ◆ BERDecodeOctetString() [2/2]

CRYPTOPP_DLL size_t CRYPTOPP_API BERDecodeOctetString | ( | BufferedTransformation & | bt,
|  | BufferedTransformation & | str
| ) |  |

BER decode octet string.

Parameters

  bt | BufferedTransformation object for reading
  str | the decoded string

Returns
  the number of octets used for the encoding

Definition at line 138 of file asn.cpp.

## ◆ DEREncodeTextString() [1/3]

CRYPTOPP_DLL size_t CRYPTOPP_API DEREncodeTextString | ( | BufferedTransformation & | bt,
|  | const byte * | str,
|  | size_t | strLen,
|  | byte | asnTag
| ) |  |

DER encode text string.

Parameters

  bt | BufferedTransformation object for writing
  str | the string to encode
  strLen | the length of the string, in bytes
  asnTag | the ASN.1 identifier

Returns
  the number of octets used for the encoding

DEREncodeTextString() can be used for UTF8_STRING, PRINTABLE_STRING, and IA5_STRING

Since
  Crypto++ 8.3

Definition at line 154 of file asn.cpp.

## ◆ DEREncodeTextString() [2/3]

CRYPTOPP_DLL size_t CRYPTOPP_API DEREncodeTextString | ( | BufferedTransformation & | bt,
|  | const SecByteBlock & | str,
|  | byte | asnTag
| ) |  |

DER encode text string.

Parameters

  bt | BufferedTransformation object for writing
  str | the string to encode
  asnTag | the ASN.1 identifier

Returns
  the number of octets used for the encoding

DEREncodeTextString() can be used for UTF8_STRING, PRINTABLE_STRING, and IA5_STRING

Since
  Crypto++ 8.3

Definition at line 162 of file asn.cpp.

## ◆ DEREncodeTextString() [3/3]

CRYPTOPP_DLL size_t CRYPTOPP_API DEREncodeTextString | ( | BufferedTransformation & | bt,
|  | const std::string & | str,
|  | byte | asnTag
| ) |  |

DER encode text string.

Parameters

  bt | BufferedTransformation object for writing
  str | the string to encode
  asnTag | the ASN.1 identifier

Returns
  the number of octets used for the encoding

DEREncodeTextString() can be used for UTF8_STRING, PRINTABLE_STRING, and IA5_STRING

Since
  Crypto++ 6.0

Definition at line 167 of file asn.cpp.

## ◆ BERDecodeTextString() [1/2]

CRYPTOPP_DLL size_t CRYPTOPP_API BERDecodeTextString | ( | BufferedTransformation & | bt,
|  | SecByteBlock & | str,
|  | byte | asnTag
| ) |  |

BER decode text string.

Parameters

  bt | BufferedTransformation object for reading
  str | the string to decode
  asnTag | the ASN.1 identifier

BERDecodeTextString() can be used for UTF8_STRING, PRINTABLE_STRING, and IA5_STRING

Since
  Crypto++ 8.3

Definition at line 172 of file asn.cpp.

## ◆ BERDecodeTextString() [2/2]

CRYPTOPP_DLL size_t CRYPTOPP_API BERDecodeTextString | ( | BufferedTransformation & | bt,
|  | std::string & | str,
|  | byte | asnTag
| ) |  |

BER decode text string.

Parameters

  bt | BufferedTransformation object for reading
  str | the string to decode
  asnTag | the ASN.1 identifier

BERDecodeTextString() can be used for UTF8_STRING, PRINTABLE_STRING, and IA5_STRING

Since
  Crypto++ 6.0

Definition at line 191 of file asn.cpp.

## ◆ DEREncodeDate()

CRYPTOPP_DLL size_t CRYPTOPP_API DEREncodeDate | ( | BufferedTransformation & | bt,
|  | const SecByteBlock & | str,
|  | byte | asnTag
| ) |  |

DER encode date.

Parameters

  bt | BufferedTransformation object for writing
  str | the date to encode
  asnTag | the ASN.1 identifier

Returns
  the number of octets used for the encoding

BERDecodeDate() can be used for UTC_TIME and GENERALIZED_TIME

Since
  Crypto++ 8.3

Definition at line 210 of file asn.cpp.

## ◆ BERDecodeDate()

CRYPTOPP_DLL size_t CRYPTOPP_API BERDecodeDate | ( | BufferedTransformation & | bt,
|  | SecByteBlock & | str,
|  | byte | asnTag
| ) |  |

BER decode date.

Parameters

  bt | BufferedTransformation object for reading
  str | the date to decode
  asnTag | the ASN.1 identifier

BERDecodeDate() can be used for UTC_TIME and GENERALIZED_TIME

Since
  Crypto++ 8.3

Definition at line 218 of file asn.cpp.

## ◆ DEREncodeBitString()

CRYPTOPP_DLL size_t CRYPTOPP_API DEREncodeBitString | ( | BufferedTransformation & | bt,
|  | const byte * | str,
|  | size_t | strLen,
|  | unsigned int | unusedBits = `0`
| ) |  |

DER encode bit string.

Parameters

  bt | BufferedTransformation object for writing
  str | the string to encode
  strLen | the length of the string
  unusedBits | the number of unused bits

Returns
  the number of octets used for the encoding

The caller is responsible for shifting octets if unusedBits is not 0. For example, to DER encode a web server X.509 key usage, the 101b bit mask is often used (digitalSignature and keyEncipherment). In this case `str` is one octet with a value=0xa0 and unusedBits=5. The value 0xa0 is `101b << 5`.

Definition at line 237 of file asn.cpp.

## ◆ BERDecodeBitString()

CRYPTOPP_DLL size_t CRYPTOPP_API BERDecodeBitString | ( | BufferedTransformation & | bt,
|  | SecByteBlock & | str,
|  | unsigned int & | unusedBits
| ) |  |

DER decode bit string.

Parameters

  bt | BufferedTransformation object for reading
  str | the decoded string
  unusedBits | the number of unused bits

The caller is responsible for shifting octets if unusedBits is not 0. For example, to DER encode a web server X.509 key usage, the 101b bit mask is often used (digitalSignature and keyEncipherment). In this case `str` is one octet with a value=0xa0 and unusedBits=5. The value 0xa0 is `101b << 5`.

Definition at line 246 of file asn.cpp.

## ◆ DERReencode()

CRYPTOPP_DLL void CRYPTOPP_API DERReencode | ( | BufferedTransformation & | bt,
|  | BufferedTransformation & | dest
| ) |  |

BER decode and DER re-encode.

Parameters

  bt | BufferedTransformation object for writing
  dest | BufferedTransformation object

Definition at line 271 of file asn.cpp.

## ◆ BERDecodePeekLength()

CRYPTOPP_DLL size_t CRYPTOPP_API BERDecodePeekLength | ( | const BufferedTransformation & | bt | ) |

BER decode size.

Parameters

  bt | BufferedTransformation object for reading

Returns
  the length of the ASN.1 value, in bytes

BERDecodePeekLength() determines the length of a value without consuming octets in the stream. The stream must use definite length encoding. If indefinite length encoding is used or an error occurs, then 0 is returned.

Since
  Crypto++ 8.3

Definition at line 288 of file asn.cpp.

## ◆ DEREncodeUnsigned()

template<class T >

size_t DEREncodeUnsigned | ( | BufferedTransformation & | out,
|  | T | w,
|  | byte | asnTag = `INTEGER`
| ) |  |

DER Encode unsigned value.

Template Parameters

  T | class or type

Parameters

  out | BufferedTransformation object
  w | unsigned value to encode
  asnTag | the ASN.1 identifier

DEREncodeUnsigned() can be used with INTEGER, BOOLEAN, and ENUM

Definition at line 820 of file asn.h.

## ◆ BERDecodeUnsigned()

template<class T >

void BERDecodeUnsigned | ( | BufferedTransformation & | in,
|  | T & | w,
|  | byte | asnTag = `INTEGER`,
|  | T | minValue = `0`,
|  | T | maxValue = `T(0xffffffff)`
| ) |  |

BER Decode unsigned value.

Template Parameters

  T | fundamental C++ type

Parameters

  in | BufferedTransformation object
  w | the decoded value
  asnTag | the ASN.1 identifier
  minValue | the minimum expected value
  maxValue | the maximum expected value

Exceptions

  BERDecodeErr() | if the value cannot be parsed or the decoded value is not within range.

DEREncodeUnsigned() can be used with INTEGER, BOOLEAN, and ENUM

Definition at line 856 of file asn.h.

## ◆ operator==()

bool operator== | ( | const OID & | lhs,
|  | const OID & | rhs
| ) |  |
| inline

Compare two OIDs for equality.

Parameters

  lhs | the first OID
  rhs | the second OID

Returns
  true if the OIDs are equal, false otherwise

## ◆ operator!=()

bool operator!= | ( | const OID & | lhs,
|  | const OID & | rhs
| ) |  |
| inline

Compare two OIDs for inequality.

Parameters

  lhs | the first OID
  rhs | the second OID

Returns
  true if the OIDs are not equal, false otherwise

## ◆ operator<()

bool operator< | ( | const OID & | lhs,
|  | const OID & | rhs
| ) |  |
| inline

Compare two OIDs for ordering.

Parameters

  lhs | the first OID
  rhs | the second OID

Returns
  true if the first OID is less than the second OID, false otherwise

operator<() calls std::lexicographical_compare() on each element in the array of values.

## ◆ operator<=()

bool operator<= | ( | const OID & | lhs,
|  | const OID & | rhs
| ) |  |
| inline

Compare two OIDs for ordering.

Parameters

  lhs | the first OID
  rhs | the second OID

Returns
  true if the first OID is less than or equal to the second OID, false otherwise

operator<=() is implemented in terms of operator==() and operator<().

Since
  Crypto++ 8.3

## ◆ operator>=()

bool operator>= | ( | const OID & | lhs,
|  | const OID & | rhs
| ) |  |
| inline

Compare two OIDs for ordering.

Parameters

  lhs | the first OID
  rhs | the second OID

Returns
  true if the first OID is greater than or equal to the second OID, false otherwise

operator>=() is implemented in terms of operator<().

Since
  Crypto++ 8.3

## ◆ operator+()

OID operator+ | ( | const OID & | lhs,
|  | unsigned long | rhs
| ) |  |
| inline

Append a value to an OID.

Parameters

  lhs | the OID
  rhs | the value to append

## ◆ operator<<()

std::ostream& operator<< | ( | std::ostream & | out,
|  | const OID & | oid
| ) |  |
| inline

Print a OID value.

Parameters

  out | the output stream
  oid | the OID

Definition at line 939 of file asn.h.