From 198ae5a5181cb19dfe2c02005c1b928d60377c1a Mon Sep 17 00:00:00 2001 From: Jeffrey Walton Date: Fri, 8 Apr 2016 01:51:21 -0400 Subject: [PATCH] Updated documentation --- asn.h | 115 ++++++++++++++++++++++++++++++++++++++++++++++++++------- oids.h | 7 +--- 2 files changed, 103 insertions(+), 19 deletions(-) diff --git a/asn.h b/asn.h index ba4a3191..a344fd0a 100644 --- a/asn.h +++ b/asn.h @@ -1,7 +1,6 @@ // asn.h - written and placed in the public domain by Wei Dai -//! \file -//! \headerfile asn.h +//! \file asn.h //! \brief Classes and functions for working with ANS.1 objects #ifndef CRYPTOPP_ASN_H @@ -16,7 +15,8 @@ NAMESPACE_BEGIN(CryptoPP) -// these tags and flags are not complete +//! \brief ASN.1 types +//! \note These tags and flags are not complete enum ASNTag { BOOLEAN = 0x01, @@ -44,6 +44,8 @@ enum ASNTag GENERAL_STRING = 0x1b }; +//! \brief ASN.1 flags +//! \note These tags and flags are not complete enum ASNIdFlag { UNIVERSAL = 0x00, @@ -55,52 +57,131 @@ enum ASNIdFlag PRIVATE = 0xc0 }; +//! \brief Raises a BERDecodeErr inline void BERDecodeError() {throw BERDecodeErr();} +//! \brief Exception thrown when an unknown object identifier is encountered class CRYPTOPP_DLL UnknownOID : public BERDecodeErr { public: + //! \brief Construct an UnknownOID UnknownOID() : BERDecodeErr("BER decode error: unknown object identifier") {} + //! \brief Construct an UnknownOID + //! \param err error message to use for the execption UnknownOID(const char *err) : BERDecodeErr(err) {} }; // unsigned int DERLengthEncode(unsigned int length, byte *output=0); + +//! \brief DER encode a length +//! \param out BufferedTransformation object +//! \param length the size to encode +//! \returns the number of octets used for the encoding CRYPTOPP_DLL size_t CRYPTOPP_API DERLengthEncode(BufferedTransformation &out, lword length); -// returns false if indefinite length + +//! \brief BER decode a length +//! \param in BufferedTransformation object +//! \param length the decoded size +//! \returns true if the value was decoded +//! \throws BERDecodeError if the value fails to decode or is too large for size_t +//! \details BERLengthDecode() returns false if the encoding is indefinite length. CRYPTOPP_DLL bool CRYPTOPP_API BERLengthDecode(BufferedTransformation &in, size_t &length); +//! \brief DER encode NULL +//! \param out BufferedTransformation object CRYPTOPP_DLL void CRYPTOPP_API DEREncodeNull(BufferedTransformation &out); + +//! \brief BER decode NULL +//! \param in BufferedTransformation object CRYPTOPP_DLL void CRYPTOPP_API BERDecodeNull(BufferedTransformation &in); +//! \brief DER encode octet string +//! \param out BufferedTransformation object +//! \param str the string to encode +//! \param strLen the length of the string +//! \returns the number of octets used for the encoding CRYPTOPP_DLL size_t CRYPTOPP_API DEREncodeOctetString(BufferedTransformation &out, const byte *str, size_t strLen); + +//! \brief DER encode octet string +//! \param out BufferedTransformation object +//! \param str the string to encode +//! \returns the number of octets used for the encoding CRYPTOPP_DLL size_t CRYPTOPP_API DEREncodeOctetString(BufferedTransformation &out, const SecByteBlock &str); + +//! \brief BER decode octet string +//! \param in BufferedTransformation object +//! \param str the decoded string +//! \returns the number of octets used for the encoding CRYPTOPP_DLL size_t CRYPTOPP_API BERDecodeOctetString(BufferedTransformation &in, SecByteBlock &str); + +//! \brief BER decode octet string +//! \param in BufferedTransformation object +//! \param str the decoded string +//! \returns the number of octets used for the encoding CRYPTOPP_DLL size_t CRYPTOPP_API BERDecodeOctetString(BufferedTransformation &in, BufferedTransformation &str); -// for UTF8_STRING, PRINTABLE_STRING, and IA5_STRING +//! \brief DER encode text string +//! \param out BufferedTransformation object +//! \param str the string to encode +//! \param asnTag the ASN.1 type +//! \returns the number of octets used for the encoding +//! \details DEREncodeTextString() can be used for UTF8_STRING, PRINTABLE_STRING, and IA5_STRING CRYPTOPP_DLL size_t CRYPTOPP_API DEREncodeTextString(BufferedTransformation &out, const std::string &str, byte asnTag); + +//! \brief BER decode text string +//! \param in BufferedTransformation object +//! \param str the string to encode +//! \param asnTag the ASN.1 type +//! \details DEREncodeTextString() can be used for UTF8_STRING, PRINTABLE_STRING, and IA5_STRING CRYPTOPP_DLL size_t CRYPTOPP_API BERDecodeTextString(BufferedTransformation &in, std::string &str, byte asnTag); +//! \brief DER encode bit string +//! \param out BufferedTransformation object +//! \param str the string to encode +//! \param strLen the length of the string +//! \param unusedBits the number of unused bits +//! \returns the number of octets used for the encoding CRYPTOPP_DLL size_t CRYPTOPP_API DEREncodeBitString(BufferedTransformation &out, const byte *str, size_t strLen, unsigned int unusedBits=0); + +//! \brief DER decode bit string +//! \param in BufferedTransformation object +//! \param str the decoded string +//! \param unusedBits the number of unused bits CRYPTOPP_DLL size_t CRYPTOPP_API BERDecodeBitString(BufferedTransformation &in, SecByteBlock &str, unsigned int &unusedBits); -// BER decode from source and DER reencode into dest +//! \brief BER decode and DER re-encode +//! \param source BufferedTransformation object +//! \param dest BufferedTransformation object CRYPTOPP_DLL void CRYPTOPP_API DERReencode(BufferedTransformation &source, BufferedTransformation &dest); -//! Object Identifier +//! \brief Object Identifier class CRYPTOPP_DLL OID { public: + //! \brief Construct an OID OID() {} + //! \brief Construct an OID + //! \param v value to initialize the OID OID(word32 v) : m_values(1, v) {} + //! \brief Construct an OID + //! \param bt BufferedTransformation object OID(BufferedTransformation &bt) {BERDecode(bt);} + //! \brief Append a value to an OID + //! \param rhs the value to append inline OID & operator+=(word32 rhs) {m_values.push_back(rhs); return *this;} + //! \brief DER encode this OID + //! \param bt BufferedTransformation object void DEREncode(BufferedTransformation &bt) const; + + //! \brief BER decode an OID + //! \param bt BufferedTransformation object void BERDecode(BufferedTransformation &bt); - // throw BERDecodeErr() if decoded value doesn't equal this OID + //! \brief BER decode an OID + //! \param bt BufferedTransformation object + //! \throws BERDecodeErr() if decoded value doesn't equal this OID void BERDecodeAndCheck(BufferedTransformation &bt) const; std::vector m_values; @@ -110,10 +191,16 @@ private: static size_t DecodeValue(BufferedTransformation &bt, word32 &v); }; +//! \brief ASN.1 encoded object filter class EncodedObjectFilter : public Filter { public: enum Flag {PUT_OBJECTS=1, PUT_MESSANGE_END_AFTER_EACH_OBJECT=2, PUT_MESSANGE_END_AFTER_ALL_OBJECTS=4, PUT_MESSANGE_SERIES_END_AFTER_ALL_OBJECTS=8}; + + //! \brief Construct an EncodedObjectFilter + //! \param attachment a BufferedTrasformation to attach to this object + //! \param nObjects + //! \param flags bitwise OR of EncodedObjectFilter::Flag EncodedObjectFilter(BufferedTransformation *attachment = NULL, unsigned int nObjects = 1, word32 flags = 0); void Put(const byte *inString, size_t length); @@ -133,7 +220,7 @@ private: lword m_lengthRemaining; }; -//! BER General Decoder +//! \brief BER General Decoder class CRYPTOPP_DLL BERGeneralDecoder : public Store { public: @@ -170,7 +257,7 @@ private: // proper direction. We did not break the library or versioning based on the output of // `nm --demangle libcryptopp.a | grep DERGeneralEncoder::DERGeneralEncoder | grep -v " U "`. -//! DER General Encoder +//! \brief DER General Encoder class CRYPTOPP_DLL DERGeneralEncoder : public ByteQueue { public: @@ -193,7 +280,7 @@ private: byte m_asnTag; }; -//! BER Sequence Decoder +//! \brief BER Sequence Decoder class CRYPTOPP_DLL BERSequenceDecoder : public BERGeneralDecoder { public: @@ -203,7 +290,7 @@ public: : BERGeneralDecoder(inQueue, asnTag) {} }; -//! DER Sequence Encoder +//! \brief DER Sequence Encoder class CRYPTOPP_DLL DERSequenceEncoder : public DERGeneralEncoder { public: @@ -213,7 +300,7 @@ public: : DERGeneralEncoder(outQueue, asnTag) {} }; -//! BER Set Decoder +//! \brief BER Set Decoder class CRYPTOPP_DLL BERSetDecoder : public BERGeneralDecoder { public: @@ -223,7 +310,7 @@ public: : BERGeneralDecoder(inQueue, asnTag) {} }; -//! DER Set Encoder +//! \brief DER Set Encoder class CRYPTOPP_DLL DERSetEncoder : public DERGeneralEncoder { public: diff --git a/oids.h b/oids.h index 9eac4f10..e43e2992 100644 --- a/oids.h +++ b/oids.h @@ -1,14 +1,11 @@ // oids.h - written and placed in the public domain by Wei Dai -//! \file -//! \headerfile oids.h -//! \brief Object identifiers for algorthms and schemes +//! \file oids.h +//! \brief ASN.1 object identifiers for algorthms and schemes #ifndef CRYPTOPP_OIDS_H #define CRYPTOPP_OIDS_H -// crypto-related ASN.1 object identifiers - #include "asn.h" NAMESPACE_BEGIN(CryptoPP)