Crypto++ 8.4 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 | DERLengthEncode (BufferedTransformation &bt, lword length)
| DER encode a length. More...
CRYPTOPP_DLL bool | BERLengthDecode (BufferedTransformation &bt, size_t &length)
| BER decode a length. More...
CRYPTOPP_DLL void | DEREncodeNull (BufferedTransformation &bt)
| DER encode NULL. More...
CRYPTOPP_DLL void | BERDecodeNull (BufferedTransformation &bt)
| BER decode NULL. More...
CRYPTOPP_DLL size_t | DEREncodeOctetString (BufferedTransformation &bt, const byte *str, size_t strLen)
| DER encode octet string. More...
CRYPTOPP_DLL size_t | DEREncodeOctetString (BufferedTransformation &bt, const SecByteBlock &str)
| DER encode octet string. More...
CRYPTOPP_DLL size_t | BERDecodeOctetString (BufferedTransformation &bt, SecByteBlock &str)
| BER decode octet string. More...
CRYPTOPP_DLL size_t | BERDecodeOctetString (BufferedTransformation &bt, BufferedTransformation &str)
| BER decode octet string. More...
CRYPTOPP_DLL size_t | DEREncodeTextString (BufferedTransformation &bt, const byte *str, size_t strLen, byte asnTag)
| DER encode text string. More...
CRYPTOPP_DLL size_t | DEREncodeTextString (BufferedTransformation &bt, const SecByteBlock &str, byte asnTag)
| DER encode text string. More...
CRYPTOPP_DLL size_t | DEREncodeTextString (BufferedTransformation &bt, const std::string &str, byte asnTag)
| DER encode text string. More...
CRYPTOPP_DLL size_t | BERDecodeTextString (BufferedTransformation &bt, SecByteBlock &str, byte asnTag)
| BER decode text string. More...
CRYPTOPP_DLL size_t | BERDecodeTextString (BufferedTransformation &bt, std::string &str, byte asnTag)
| BER decode text string. More...
CRYPTOPP_DLL size_t | DEREncodeDate (BufferedTransformation &bt, const SecByteBlock &str, byte asnTag)
| DER encode date. More...
CRYPTOPP_DLL size_t | BERDecodeDate (BufferedTransformation &bt, SecByteBlock &str, byte asnTag)
| BER decode date. More...
CRYPTOPP_DLL size_t | DEREncodeBitString (BufferedTransformation &bt, const byte *str, size_t strLen, unsigned int unusedBits=0)
| DER encode bit string. More...
CRYPTOPP_DLL size_t | BERDecodeBitString (BufferedTransformation &bt, SecByteBlock &str, unsigned int &unusedBits)
| DER decode bit string. More...
CRYPTOPP_DLL void | DERReencode (BufferedTransformation &bt, BufferedTransformation &dest)
| BER decode and DER re-encode. More...
CRYPTOPP_DLL size_t | 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 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

## ◆ BERLengthDecode()

CRYPTOPP_DLL bool 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.

## ◆ DEREncodeNull()

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

DER encode NULL.

Parameters

  bt | BufferedTransformation object for writing

## ◆ BERDecodeNull()

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

BER decode NULL.

Parameters

  bt | BufferedTransformation object for reading

## ◆ DEREncodeOctetString() [1/2]

CRYPTOPP_DLL size_t 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

## ◆ DEREncodeOctetString() [2/2]

CRYPTOPP_DLL size_t 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

## ◆ BERDecodeOctetString() [1/2]

CRYPTOPP_DLL size_t 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

## ◆ BERDecodeOctetString() [2/2]

CRYPTOPP_DLL size_t 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

## ◆ DEREncodeTextString() [1/3]

CRYPTOPP_DLL size_t 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

## ◆ DEREncodeTextString() [2/3]

CRYPTOPP_DLL size_t 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

## ◆ DEREncodeTextString() [3/3]

CRYPTOPP_DLL size_t 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

## ◆ BERDecodeTextString() [1/2]

CRYPTOPP_DLL size_t 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

## ◆ BERDecodeTextString() [2/2]

CRYPTOPP_DLL size_t 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

## ◆ DEREncodeDate()

CRYPTOPP_DLL size_t 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

## ◆ BERDecodeDate()

CRYPTOPP_DLL size_t 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

## ◆ DEREncodeBitString()

CRYPTOPP_DLL size_t 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`.

## ◆ BERDecodeBitString()

CRYPTOPP_DLL size_t 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`.

## ◆ DERReencode()

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

BER decode and DER re-encode.

Parameters

  bt | BufferedTransformation object for writing
  dest | BufferedTransformation object

## ◆ BERDecodePeekLength()

CRYPTOPP_DLL size_t 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

## ◆ 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.