{
    "mode": "perldoc",
    "parameter": "Convert::ASN1",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/Convert%3A%3AASN1/json",
    "generated": "2026-06-12T09:27:17Z",
    "synopsis": "use Convert::ASN1;\n$asn = Convert::ASN1->new;\n$asn->prepare(q<\n[APPLICATION 7] SEQUENCE {\nint INTEGER,\nstr OCTET STRING\n}\n>);\n$pdu = $asn->encode( int => 7, str => \"string\");\n$out = $asn->decode($pdu);\nprint $out->{int},\" \",$out->{str},\"\\n\";\nuse Convert::ASN1 qw(:io);\n$peer   = asnrecv($sock,$buffer,0);\n$nbytes = asnread($fh, $buffer);\n$nbytes = asnsend($sock, $buffer, $peer);\n$nbytes = asnsend($sock, $buffer);\n$nbytes = asnwrite($fh, $buffer);\n$buffer = asnget($fh);\n$yes    = asnready($fh)",
    "sections": {
        "NAME": {
            "content": "Convert::ASN1 - ASN.1 Encode/Decode library\n",
            "subsections": []
        },
        "VERSION": {
            "content": "version 0.33\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "use Convert::ASN1;\n\n$asn = Convert::ASN1->new;\n$asn->prepare(q<\n\n[APPLICATION 7] SEQUENCE {\nint INTEGER,\nstr OCTET STRING\n}\n\n>);\n\n$pdu = $asn->encode( int => 7, str => \"string\");\n\n$out = $asn->decode($pdu);\nprint $out->{int},\" \",$out->{str},\"\\n\";\n\nuse Convert::ASN1 qw(:io);\n\n$peer   = asnrecv($sock,$buffer,0);\n$nbytes = asnread($fh, $buffer);\n$nbytes = asnsend($sock, $buffer, $peer);\n$nbytes = asnsend($sock, $buffer);\n$nbytes = asnwrite($fh, $buffer);\n$buffer = asnget($fh);\n$yes    = asnready($fh)\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "Convert::ASN1 encodes and decodes ASN.1 data structures using BER/DER rules.\n",
            "subsections": []
        },
        "METHODS": {
            "content": "new ( [OPTIONS] )\nContructor, creates a new object.\n\nIf given, OPTIONS are the same ones as for \"configure ( OPTIONS )\" below.\n\nerror ()\nReturns the last error.\n\nconfigure ( OPTIONS )\nConfigure options to control how Convert::ASN1 will perform various tasks. Options are passed as\nname-value pairs.\n\nencode\nReference to a hash which contains various encode options.\n\ndecode\nReference to a hash which contains various decode options.\n\nencoding\nOne of 'BER' or 'DER'. The default is 'BER'\n\ntagdefault\nOne of 'EXPLICIT' or 'IMPLICIT'. Default tagging conventions are normally given in the ASN.1\nmodule definition (not supported by the parser). The ASN.1 spec states EXPLICIT tagging is\nthe default, but this option has IMPLICIT tagging default for backward compatibility\nreasons.\n\nEncode options\n\nreal\nWhich encoding to use for real's. One of 'binary', 'nr1', 'nr2', 'nr3'\n\ntime\nThis controls how UTCTime and GeneralizedTime elements are encoded. The default is\n\"withzone\".\n\nutctime\nThe value passed will be encoded without a zone, ie a UTC value.\n\nwithzone\nThe value will be encoded with a zone. By default it will be encoded using the local\ntime offset. The offset may be set using the \"timezone\" configure option.\n\nraw The value passed should already be in the correct format and will be copied into the PDU\nas-is.\n\ntimezone\nBy default UTCTime and GeneralizedTime will be encoded using the local time offset from UTC.\nThis will over-ride that. It is an offset from UTC in seconds. This option can be overridden\nby passing a reference to a list of two values as the time value. The list should contain\nthe time value and the offset from UTC in seconds.\n\nbigint\nIf during encoding an value greater than 32 bits is discovered and is not already a big\ninteger object, then the value will first be converted into a big integer object. This\noption controls the big integer class into which the objects will be blessed. The default is\nto use Math::BigInt\n\nDecode options\n\ntime\nThis controls how a UTCTime or a GeneralizedTime element will be decoded. The default is\n\"utctime\".\n\nutctime\nThe value returned will be a time value as returned by the \"time\" function.\n\nwithzone\nThe value returned will be a reference to an array of two values. The first is the same\nas with \"utctime\", the second is the timezone offset, in seconds, that was used in the\nencoding.\n\nraw The value returned will be the raw encoding as extracted from the PDU.\n\nbigint\nIf during decoding any big integers are discovered (integers greater than 32 bits), they\nwill be decoded into big integer objects. This option controls the big integer class into\nwhich the objects will be blessed. The default is to use Math::BigInt.\n\nnull\nThe value to decode ASN.1 NULL types into. If not set, it defaults to 1.\n\nprepare ( ASN )\nCompile the given ASN.1 description which can be passed as a string or as a filehandle. The\nsyntax used is very close to ASN.1, but has a few differences. If the ASN describes only one\nmacro then encode/decode can be called on this object. If ASN describes more than one ASN.1\nmacro then \"find\" must be called. The method returns undef on error.\n\npreparefile ( ASNPATH )\nCompile the ASN.1 description to be read from the specified pathname.\n\nfind ( MACRO )\nFind a macro from a prepared ASN.1 description. Returns an object which can be used for\nencode/decode.\n\nencode ( VARIABLES )\nEncode a PDU. Top-level variable are passed as name-value pairs, or as a reference to a hash\ncontaining them. Returns the encoded PDU, or undef on error.\n\ndecode ( PDU )\nDecode the PDU, returns a reference to a hash containing the values for the PDU. Returns undef\nif there was an error.\n\nregisteroid ( OID, HANDLER )\nRegister a handler for all ASN.1 elements that are \"DEFINED BY\" the given OID.\n\nHANDLER must be a Convert::ASN1 object, e.g. as returned by \"find ( MACRO )\".\n\nregistertype ( NAME, OID, HANDLER )\nRegister a handler for all ASN.1 elements named \"NAME\", that are \"DEFINED BY\" the given OID.\n\nHANDLER must be a Convert::ASN1 object, e.g. as returned by \"find ( MACRO )\".\n",
            "subsections": []
        },
        "EXPORTS": {
            "content": "As well as providing an object interface for encoding/decoding PDUs Convert::ASN1 also provides\nthe following functions.\n\nIO Functions\nasnrecv ( SOCK, BUFFER, FLAGS )\nWill read a single element from the socket SOCK into BUFFER. FLAGS may be MSGPEEK as\nexported by \"Socket\". Returns the address of the sender, or undef if there was an error.\nSome systems do not support the return of the peer address when the socket is a connected\nsocket, in these cases the empty string will be returned. This is the same behaviour as the\n\"recv\" function in perl itself.\n\nIt is recommended that if the socket is of type SOCKDGRAM then \"recv\" be called directly\ninstead of calling \"asnrecv\".\n\nasnread ( FH, BUFFER, OFFSET )\nasnread ( FH, BUFFER )\nWill read a single element from the filehandle FH into BUFFER. Returns the number of bytes\nread if a complete element was read, -1 if an incomplete element was read or undef if there\nwas an error. If OFFSET is specified then it is assumed that BUFFER already contains an\nincomplete element and new data will be appended starting at OFFSET.\n\nIf FH is a socket the asnrecv is used to read the element, so the same restriction applies\nif FH is a socket of type SOCKDGRAM.\n\nasnsend ( SOCK, BUFFER, FLAGS, TO )\nasnsend ( SOCK, BUFFER, FLAGS )\nIdentical to calling \"send\", see perlfunc\n\nasnwrite ( FH, BUFFER )\nIdentical to calling \"syswrite\" with 2 arguments, see perlfunc\n\nasnget ( FH )\n\"asnget\" provides buffered IO. Because it needs a buffer FH must be a GLOB or a reference\nto a GLOB. \"asnget\" will use two entries in the hash element of the GLOB to use as its\nbuffer:\n\nasnbuffer - input buffer\nasnneed   - number of bytes needed for the next element, if known\n\nReturns an element or undef if there was an error.\n\nasnready ( FH )\n\"asnready\" works with \"asnget\". It will return true if \"asnget\" has already read enough\ndata into the buffer to return a complete element.\n\nEncode/Decode Functions\nasntag ( CLASS, VALUE )\nGiven CLASS and a VALUE, calculate an integer which when encoded will become the tag.\n\nasndecodetag ( TAG )\nDecode the given ASN.1 encoded \"TAG\".\n\nasnencodetag ( TAG )\nEncode TAG value for encoding. We assume that the tag has been correctly generated with\n\"asntag ( CLASS, VALUE )\".\n\nasndecodelength ( LEN )\nDecode the given ASN.1 decoded \"LEN\".\n\nasnencodelength ( LEN )\nEncode the given \"LEN\" to its ASN.1 encoding.\n",
            "subsections": [
                {
                    "name": "Constants",
                    "content": "ASNBITSTR\nASNBOOLEAN\nASNENUMERATED\nASNGENERALTIME\nASNIA5STR\nASNINTEGER\nASNNULL\nASNOBJECTID\nASNOCTETSTR\nASNPRINTSTR\nASNREAL\nASNSEQUENCE\nASNSET\nASNUTCTIME\nASNAPPLICATION\nASNCONTEXT\nASNPRIVATE\nASNUNIVERSAL\nASNPRIMITIVE\nASNCONSTRUCTOR\nASNLONGLEN\nASNEXTENSIONID\nASNBIT\n"
                },
                {
                    "name": "Debug Functions",
                    "content": "asndump ( [FH,] BUFFER )\nTry to decode the given buffer as ASN.1 structure and dump it to the given file handle, or\n\"STDERR\" if the handle is not given.\n\nasnhexdump ( FH, BUFFER )\n"
                }
            ]
        },
        "EXPORT TAGS": {
            "content": ":all\nAll exported functions\n\n:const\nASNBOOLEAN, ASNINTEGER, ASNBITSTR, ASNOCTETSTR, ASNNULL, ASNOBJECTID, ASNREAL,\nASNENUMERATED, ASNSEQUENCE, ASNSET, ASNPRINTSTR, ASNIA5STR, ASNUTCTIME,\nASNGENERALTIME, ASNUNIVERSAL, ASNAPPLICATION, ASNCONTEXT, ASNPRIVATE, ASNPRIMITIVE,\nASNCONSTRUCTOR, ASNLONGLEN, ASNEXTENSIONID, ASNBIT\n\n:debug\nasndump, asnhexdump\n\n:io asnrecv, asnsend, asnread, asnwrite, asnget, asnready\n\n:tag\nasntag, asndecodetag, asnencodetag, asndecodelength, asnencodelength\n\nMAPPING ASN.1 TO PERL\nEvery element in the ASN.1 definition has a name, in perl a hash is used with these names as an\nindex and the element value as the hash value.\n\n# ASN.1\nint INTEGER,\nstr OCTET STRING\n\n# Perl\n{ int => 5, str => \"text\" }\n\nIn the case of a SEQUENCE, SET or CHOICE then the value in the namespace will be a hash\nreference which will be the namespace for the elements with that element.\n\n# ASN.1\nint INTEGER,\nseq SEQUENCE {\nstr OCTET STRING,\nbool BOOLEAN\n}\n\n# Perl\n{ int => 5, seq => { str => \"text\", bool => 1}}\n\nIf the element is a SEQUENCE OF, or SET OF, then the value in the namespace will be an array\nreference. The elements in the array will be of the type expected by the type following the OF.\nFor example with \"SEQUENCE OF STRING\" the array would contain strings. With \"SEQUENCE OF\nSEQUENCE { ... }\" the array will contain hash references which will be used as namespaces\n\n# ASN.1\nint INTEGER,\nstr SEQUENCE OF OCTET STRING\n\n# Perl\n{ int => 5, str => [ \"text1\", \"text2\"]}\n\n# ASN.1\nint INTEGER,\nstr SEQUENCE OF SEQUENCE {\ntype OCTET STRING,\nvalue INTEGER\n}\n\n# Perl\n{ int => 5, str => [\n{ type => \"abc\", value => 4 },\n{ type => \"def\", value => -1 },\n]}\n\nFinally, if you wish to pre-parse ASN.1 and hold it to include inline in your PDU, you can\ncoerce it into the ASN.1 spec by defining the value as ANY in the schema, and then pass the pre\nencoded value inline.\n\n# ASN.1\nint INTEGER,\nstr OCTET STRING,\npre ANY\n\n# Perl\n{ int => 5, str => \"text\", pre=>\"\\x03\\x03\\x00\\x0a\\x05\" }\n\npasses a pre-encoded BIT STRING instance as hex text. -But it could be a previous run of\n$obj->encode() from another run held in some variable.\n",
            "subsections": [
                {
                    "name": "Exceptions",
                    "content": "There are some exceptions where Convert::ASN1 does not require an element to be named. These are\nSEQUENCE {...}, SET {...} and CHOICE. In each case if the element is not given a name then the\nelements inside the {...} will share the same namespace as the elements outside of the {...}.\n"
                }
            ]
        },
        "TODO": {
            "content": "*   XS implementation.\n\n*   More documentation.\n\n*   More tests.\n",
            "subsections": []
        },
        "AUTHOR": {
            "content": "Graham Barr <gbarr@cpan.org>\n",
            "subsections": []
        },
        "SUPPORT": {
            "content": "Report issues via github at https://github.com/gbarr/perl-Convert-ASN1/issues\n\nTo contribute I encourage you to create a git fork of the repository at\nhttps://github.com/gbarr/perl-Convert-ASN1 do you work on a fresh branch created from master and\nsubmit a pull request\n",
            "subsections": []
        },
        "COPYRIGHT": {
            "content": "Copyright (c) 2000-2012 Graham Barr <gbarr@cpan.org>. All rights reserved. This program is free\nsoftware; you can redistribute it and/or modify it under the same terms as Perl itself.\n",
            "subsections": []
        }
    },
    "summary": "Convert::ASN1 - ASN.1 Encode/Decode library",
    "flags": [],
    "examples": [],
    "see_also": []
}