{
    "content": [
        {
            "type": "text",
            "text": "# Convert::PEM (perldoc)\n\n## NAME\n\nConvert::PEM - Read/write encrypted ASN.1 PEM files\n\n## SYNOPSIS\n\nuse Convert::PEM;\nmy $pem = Convert::PEM->new(\nName => \"DSA PRIVATE KEY\",\nASN => qq(\nDSAPrivateKey SEQUENCE {\nversion INTEGER,\np INTEGER,\nq INTEGER,\ng INTEGER,\npubkey INTEGER,\nprivkey INTEGER\n}\n));\nmy $keyfile = 'private-key.pem';\nmy $pwd = 'foobar';\nmy $pkey = $pem->read(\nFilename => $keyfile,\nPassword => $pwd\n);\n$pem->write(\nContent  => $pkey,\nPassword => $pwd,\nFilename => $keyfile\n);\n\n## DESCRIPTION\n\n*Convert::PEM* reads and writes PEM files containing ASN.1-encoded objects. The files can\noptionally be encrypted using a symmetric cipher algorithm, such as 3DES. An unencrypted PEM\nfile might look something like this:\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **USAGE**\n- **ERROR HANDLING**\n- **LICENSE**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "Convert::PEM",
        "section": "",
        "mode": "perldoc",
        "summary": "Convert::PEM - Read/write encrypted ASN.1 PEM files",
        "synopsis": "use Convert::PEM;\nmy $pem = Convert::PEM->new(\nName => \"DSA PRIVATE KEY\",\nASN => qq(\nDSAPrivateKey SEQUENCE {\nversion INTEGER,\np INTEGER,\nq INTEGER,\ng INTEGER,\npubkey INTEGER,\nprivkey INTEGER\n}\n));\nmy $keyfile = 'private-key.pem';\nmy $pwd = 'foobar';\nmy $pkey = $pem->read(\nFilename => $keyfile,\nPassword => $pwd\n);\n$pem->write(\nContent  => $pkey,\nPassword => $pwd,\nFilename => $keyfile\n);",
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "SYNOPSIS",
                "lines": 28,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 26,
                "subsections": []
            },
            {
                "name": "USAGE",
                "lines": 130,
                "subsections": []
            },
            {
                "name": "ERROR HANDLING",
                "lines": 16,
                "subsections": []
            },
            {
                "name": "LICENSE",
                "lines": 7,
                "subsections": []
            }
        ],
        "sections": {
            "NAME": {
                "content": "Convert::PEM - Read/write encrypted ASN.1 PEM files\n",
                "subsections": []
            },
            "SYNOPSIS": {
                "content": "use Convert::PEM;\nmy $pem = Convert::PEM->new(\nName => \"DSA PRIVATE KEY\",\nASN => qq(\nDSAPrivateKey SEQUENCE {\nversion INTEGER,\np INTEGER,\nq INTEGER,\ng INTEGER,\npubkey INTEGER,\nprivkey INTEGER\n}\n));\n\nmy $keyfile = 'private-key.pem';\nmy $pwd = 'foobar';\n\nmy $pkey = $pem->read(\nFilename => $keyfile,\nPassword => $pwd\n);\n\n$pem->write(\nContent  => $pkey,\nPassword => $pwd,\nFilename => $keyfile\n);\n",
                "subsections": []
            },
            "DESCRIPTION": {
                "content": "*Convert::PEM* reads and writes PEM files containing ASN.1-encoded objects. The files can\noptionally be encrypted using a symmetric cipher algorithm, such as 3DES. An unencrypted PEM\nfile might look something like this:\n\n-----BEGIN DH PARAMETERS-----\nMB4CGQDUoLoCULb9LsYm5+/WN992xxbiLQlEuIsCAQM=\n-----END DH PARAMETERS-----\n\nThe string beginning \"MB4C...\" is the Base64-encoded, ASN.1-encoded \"object.\"\n\nAn encrypted file would have headers describing the type of encryption used, and the\ninitialization vector:\n\n-----BEGIN DH PARAMETERS-----\nProc-Type: 4,ENCRYPTED\nDEK-Info: DES-EDE3-CBC,C814158661DC1449\n\nAFAZFbnQNrGjZJ/ZemdVSoZa3HWujxZuvBHzHNoesxeyqqidFvnydA==\n-----END DH PARAMETERS-----\n\nThe two headers (\"Proc-Type\" and \"DEK-Info\") indicate information about the type of encryption\nused, and the string starting with \"AFAZ...\" is the Base64-encoded, encrypted, ASN.1-encoded\ncontents of this \"object.\"\n\nThe initialization vector (\"C814158661DC1449\") is chosen randomly.\n",
                "subsections": []
            },
            "USAGE": {
                "content": "$pem = Convert::PEM->new( %arg )\nConstructs a new *Convert::PEM* object designed to read/write an object of a specific type\n(given in *%arg*, see below). Returns the new object on success, \"undef\" on failure (see *ERROR\nHANDLING* for details).\n\n*%arg* can contain:\n\n*   Name\n\nThe name of the object; when decoding a PEM-encoded stream, the name in the encoding will be\nchecked against the value of *Name*. Similarly, when encoding an object, the value of *Name*\nwill be used as the name of the object in the PEM-encoded content. For example, given the\nstring \"FOO BAR\", the output from *encode* will start with a header like:\n\n-----BEGIN FOO BAR-----\n\n*Name* is a required argument.\n\n*   ASN\n\nAn ASN.1 description of the content to be either encoded or decoded.\n\n*ASN* is a required argument.\n\n*   Macro\n\nIf your ASN.1 description (in the *ASN* parameter) includes more than one ASN.1 macro\ndefinition, you will want to use the *Macro* parameter to specify which definition to use\nwhen encoding/decoding objects. For example, if your ASN.1 description looks like this:\n\nFoo ::= SEQUENCE {\nx INTEGER,\nbar Bar\n}\n\nBar ::= INTEGER\n\nIf you want to encode/decode a \"Foo\" object, you will need to tell *Convert::PEM* to use the\n\"Foo\" macro definition by using the *Macro* parameter and setting the value to \"Foo\".\n\n*Macro* is an optional argument.\n\n$obj = $pem->decode(%args)\nDecodes, and, optionally, decrypts a PEM file, returning the object as decoded by\n*Convert::ASN1*. The difference between this method and *read* is that *read* reads the contents\nof a PEM file on disk; this method expects you to pass the PEM contents as an argument.\n\nIf an error occurs while reading the file or decrypting/decoding the contents, the function\nreturns *undef*, and you should check the error message using the *errstr* method (below).\n\n*%args* can contain:\n\n*   Content\n\nThe PEM contents.\n\n*   Password\n\nThe password with which the file contents were encrypted.\n\nIf the file is encrypted, this is a mandatory argument (well, it's not strictly mandatory,\nbut decryption isn't going to work without it). Otherwise it's not necessary.\n\n$blob = $pem->encode(%args)\nConstructs the contents for the PEM file from an object: ASN.1-encodes the object, optionally\nencrypts those contents.\n\nReturns *undef* on failure (encryption failure, file-writing failure, etc.); in this case you\nshould check the error message using the *errstr* method (below). On success returns the\nconstructed PEM string.\n\n*%args* can contain:\n\n*   Content\n\nA hash reference that will be passed to *Convert::ASN1::encode*, and which should correspond\nto the ASN.1 description you gave to the *new* method. The hash reference should have the\nexact same format as that returned from the *read* method.\n\nThis argument is mandatory.\n\n*   Password\n\nA password used to encrypt the contents of the PEM file. This is an optional argument; if\nnot provided the contents will be unencrypted.\n\n$obj = $pem->read(%args)\nReads, decodes, and, optionally, decrypts a PEM file, returning the object as decoded by\n*Convert::ASN1*. This is implemented as a wrapper around *decode*, with the bonus of reading the\nPEM file from disk for you.\n\nIf an error occurs while reading the file or decrypting/decoding the contents, the function\nreturns *undef*, and you should check the error message using the *errstr* method (below).\n\nIn addition to the arguments that can be passed to the *decode* method (minus the *Content*\nmethod), *%args* can contain:\n\n*   Filename\n\nThe location of the PEM file that you wish to read.\n\n$pem->write(%args)\nConstructs the contents for the PEM file from an object: ASN.1-encodes the object, optionally\nencrypts those contents; then writes the file to disk. This is implemented as a wrapper around\n*encode*, with the bonus of writing the file to disk for you.\n\nReturns *undef* on failure (encryption failure, file-writing failure, etc.); in this case you\nshould check the error message using the *errstr* method (below). On success returns the\nconstructed PEM string.\n\nIn addition to the arguments for *encode*, *%args* can contain:\n\n*   Filename\n\nThe location on disk where you'd like the PEM file written.\n\n$pem->errstr\nReturns the value of the last error that occurred. This should only be considered meaningful\nwhen you've received *undef* from one of the functions above; in all other cases its relevance\nis undefined.\n\n$pem->asn\nReturns the *Convert::ASN1* object used internally to decode and encode ASN.1 representations.\nThis is useful when you wish to interact directly with that object; for example, if you need to\ncall *configure* on that object to set the type of big-integer class to be used when\ndecoding/encoding big integers:\n\n$pem->asn->configure( decode => { bigint => 'Math::Pari' },\nencode => { bigint => 'Math::Pari' } );\n",
                "subsections": []
            },
            "ERROR HANDLING": {
                "content": "If an error occurs in any of the above methods, the method will return \"undef\". You should then\ncall the method *errstr* to determine the source of the error:\n\n$pem->errstr\n\nIn the case that you do not yet have a *Convert::PEM* object (that is, if an error occurs while\ncreating a *Convert::PEM* object), the error can be obtained as a class method:\n\nConvert::PEM->errstr\n\nFor example, if you try to decode an encrypted object, and you do not give a passphrase to\ndecrypt the object:\n\nmy $obj = $pem->read( Filename => \"encrypted.pem\" )\nor die \"Decryption failed: \", $pem->errstr;\n",
                "subsections": []
            },
            "LICENSE": {
                "content": "Convert::PEM is free software; you may redistribute it and/or modify it under the same terms as\nPerl itself.\n\nAUTHOR & COPYRIGHTS\nExcept where otherwise noted, Convert::PEM is Copyright Benjamin Trott, cpan@stupidfool.org. All\nrights reserved.\n",
                "subsections": []
            }
        }
    }
}