### posStart() Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/assets/asn1js/index-local.html Returns the starting position of the element in the stream. ```APIDOC ## posStart() ### Description Returns the starting position of the element in the stream. ### Method posStart() ### Returns - **number** - The starting position. ``` -------------------------------- ### Install asn1js with npm, pnpm, or yarn Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/assets/asn1js/README.md Install the @lapo/asn1js package using your preferred package manager. The commands are alternatives; choose one. ```sh npm install @lapo/asn1js # or other tools pnpm install @lapo/asn1js yarn add @lapo/asn1js ``` -------------------------------- ### Content-Byte Decode Helpers Example Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/lowlevel.md Shows encoding an integer to ASN.1 content bytes, comparing with DER encoding, and decoding back. The content-only bytes omit tag and length, while DER includes them. ```kotlin val contentOnly = 300.encodeToAsn1ContentBytes() contentOnly.toHexString() shouldBe "012c" val der = Asn1.Int(300).derEncoded der.toHexString() shouldBe "0202012c" Int.decodeFromAsn1ContentBytes(contentOnly) shouldBe 300 ``` -------------------------------- ### Parse DER bytes and assert tag with Asn1Element.parseFirst Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/lowlevel.md Parses DER hex bytes into an Asn1Element, asserts the expected tag, and decodes the primitive content. The example shows the returned pair containing the first element and remaining bytes, and verifies the decoded integer value. Parsing empty input throws Asn1Exception. ```kotlin val der = "020101020102".hexToByteArray() val (first, remaining) = Asn1Element.parseFirst(der) first.assertTag(Asn1Element.Tag.INT) first.toDerHexString() shouldBe "020101" remaining.toHexString() shouldBe "020102" first.asPrimitive().decodeToInt() shouldBe 1 ``` -------------------------------- ### Dump ASN.1 structure from CLI with npx Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/assets/asn1js/README.md Run asn1js from the command line without installing it, passing a certificate file to dump its ASN.1 structure. ```sh npx @lapo/asn1js ed25519.cer ``` -------------------------------- ### parseStringUTF(start, end, maxLength) Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/assets/asn1js/index-local.html Parses a region of the stream as a UTF-8 string. Returns an object with the size of the parsed string and the string itself, truncated to the maximum length if specified. ```APIDOC ## parseStringUTF(start, end, maxLength) ### Description Parses a region of the stream as a UTF-8 string. Returns an object with the size of the parsed string and the string itself, truncated to the maximum length if specified. ### Parameters - **start** (number) - Required - Starting position (included) - **end** (number) - Required - Ending position (excluded) - **maxLength** (number) - Required - Maximum length of the output string ### Returns - **Object** - Object with `size` and `str` properties ``` -------------------------------- ### Round-trip a custom SemanticVersion through DER encoding and decoding Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/core.md Encodes a SemanticVersion instance to DER, asserts the expected hex string, and decodes it back to verify equality. This example pairs with the custom type definition above and demonstrates the full encode/decode cycle. ```kotlin val version = SemanticVersion(major = 1, minor = 42) val der = version.encodeToDer() der.toHexString() shouldBe "300602010102012a" /* (1)! */ SemanticVersion.decodeFromDer(der) shouldBe version ``` -------------------------------- ### KnownOIDs[oid] Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/addons.md Gets or sets a description for an ObjectIdentifier in the KnownOIDs map. This is part of the oids module. ```APIDOC ## KnownOIDs[oid] ### Description Gets or sets a description for an ObjectIdentifier in the KnownOIDs map. This is part of the oids module. ### Method indexed access ### Parameters - **oid** (ObjectIdentifier) - Required - The object identifier. ### Response Returns the description string if set, otherwise null. ### Request Example ```kotlin val description = KnownOIDs[KnownOIDs.date] // returns human-readable descriptions KnownOIDs[expressionistOID] = "Edvard Munch" ``` ``` -------------------------------- ### parseStringISO(start, end, maxLength) Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/assets/asn1js/index-local.html Parses a region of the stream as an ISO string. Returns an object with the size of the parsed string and the string itself, truncated to the maximum length if specified. ```APIDOC ## parseStringISO(start, end, maxLength) ### Description Parses a region of the stream as an ISO string. Returns an object with the size of the parsed string and the string itself, truncated to the maximum length if specified. ### Parameters - **start** (number) - Required - Starting position (included) - **end** (number) - Required - Ending position (excluded) - **maxLength** (number) - Required - Maximum length of the output string ### Returns - **Object** - Object with `size` and `str` properties ``` -------------------------------- ### get(pos) Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/assets/asn1js/index-local.html Retrieves a byte from the stream. If no position is specified, it reads the byte at the current position and increments the position. Throws an error if the position is out of bounds. ```APIDOC ## get(pos) ### Description Retrieves a byte from the stream. If no position is specified, it reads the byte at the current position and increments the position. Throws an error if the position is out of bounds. ### Parameters - **pos** (?number) - Optional - Read position if specified, else current position (and increment it) ### Returns - **number** - The byte value at the specified position ### Throws - Error if the position is beyond the stream length ``` -------------------------------- ### b64Dump(start, end, type) Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/assets/asn1js/index-local.html Generates a Base64 dump of a specified region of the stream. The type parameter controls the encoding: 'url' (default, RFC 4648 section 5 without padding) or 'std' (section 4 with padding). ```APIDOC ## b64Dump(start, end, type) ### Description Generates a Base64 dump of a specified region of the stream. The type parameter controls the encoding: 'url' (default, RFC 4648 section 5 without padding) or 'std' (section 4 with padding). ### Parameters - **start** (number) - Required - Starting position (included) - **end** (number) - Required - Ending position (excluded) - **type** (string) - Optional - 'url' (default) or 'std' ### Returns - **string** - Base64 encoded representation of the data ``` -------------------------------- ### parseStringT61(start, end, maxLength) Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/assets/asn1js/index-local.html Parses a region of the stream as a T.61 string. Returns an object with the size of the parsed string and the string itself, truncated to the maximum length if specified. ```APIDOC ## parseStringT61(start, end, maxLength) ### Description Parses a region of the stream as a T.61 string. Returns an object with the size of the parsed string and the string itself, truncated to the maximum length if specified. ### Parameters - **start** (number) - Required - Starting position (included) - **end** (number) - Required - Ending position (excluded) - **maxLength** (number) - Required - Maximum length of the output string ### Returns - **Object** - Object with `size` and `str` properties ``` -------------------------------- ### hexDump(start, end, type) Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/assets/asn1js/index-local.html Generates a hexadecimal dump of a specified region of the stream. The type parameter controls the formatting: 'raw', 'byte', or 'dump' (default). ```APIDOC ## hexDump(start, end, type) ### Description Generates a hexadecimal dump of a specified region of the stream. The type parameter controls the formatting: 'raw', 'byte', or 'dump' (default). ### Parameters - **start** (number) - Required - Starting position (included) - **end** (number) - Required - Ending position (excluded) - **type** (string) - Optional - 'raw', 'byte' or 'dump' (default) ### Returns - **string** - Hexadecimal representation of the data ``` -------------------------------- ### Generic PEM decode and encode with PemBlock Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/core.md Use for parsing or emitting PEM without caring about payload type. Decodes multiple blocks with decodeAllFromPem, encodes a list with encodeAllToPem, and decodes a single block with decodeFromPem. The example shows headers like Proc-Type and DEK-Info preserved. ```kotlin val source = """ -----BEGIN CERTIFICATE----- AQID -----END CERTIFICATE----- -----BEGIN PUBLIC KEY----- BAUG -----END PUBLIC KEY----- """.trimIndent() val blocks: List = PemBlock.decodeAllFromPem(source) blocks.map { it.pemLabel } shouldBe listOf("CERTIFICATE", "PUBLIC KEY") val encryptedLegacy = PemBlock( pemLabel = "RSA PRIVATE KEY", headers = listOf( PemHeader("Proc-Type", "4,ENCRYPTED"), PemHeader("DEK-Info", "AES-256-CBC,00112233445566778899AABBCCDDEEFF") ), payload = byteArrayOf(1, 2, 3) ) val pemText = listOf(encryptedLegacy).encodeAllToPem() PemBlock.decodeFromPem(pemText).headers.map { it.name } shouldBe listOf("Proc-Type", "DEK-Info") ``` -------------------------------- ### ASN.1 PEM bridge contracts Asn1PemEncodable and Asn1PemDecodable Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/core.md Use when the PEM payload is ASN.1 DER. Implement both ASN.1 and PEM bridge contracts. The example encodes an Asn1Integer(42) to PEM and decodes it back, verifying equality. ```kotlin val source = object : Asn1PemEncodable { override val pemLabel: String = "ASN1 INTEGER" override fun encodeToTlv(): Asn1Primitive = Asn1Integer(42).encodeToTlv() } val decoder = object : Asn1PemDecodable, Asn1Decodable by Asn1Integer.Companion { override val canonicalPemLabel: String = "ASN1 INTEGER" } val pem = source.encodeToPem() decoder.decodeFromPem(pem) shouldBe Asn1Integer(42) ``` -------------------------------- ### Load and query OID descriptions Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/addons.md Loads bundled descriptions and queries a description for a known OID. ```kotlin KnownOIDs.describeAll() val description = KnownOIDs[KnownOIDs.date] // returns human-readable descriptions ``` -------------------------------- ### Basic DSL: Build and encode a Sequence Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/lowlevel.md Constructs a Sequence with an Int, Bool, and UtcTime, then encodes to DER hex. The expected hex output is provided in the assertion. ```kotlin val frame = Asn1.Sequence { +Asn1.Int(7) +Asn1.Bool(true) +Asn1.UtcTime(kotlin.time.Instant.parse("2026-01-01T12:30:45Z")) } val derHex = frame.derEncoded.toHexString() derHex shouldBe /* (1)! */"30150201070101ff170d3236303130313132333034355a" ``` -------------------------------- ### isASCII(start, end) Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/assets/asn1js/index-local.html Checks if a region of the stream contains only ASCII characters (codes 32-176). Returns true if all characters are ASCII, false otherwise. ```APIDOC ## isASCII(start, end) ### Description Checks if a region of the stream contains only ASCII characters (codes 32-176). Returns true if all characters are ASCII, false otherwise. ### Parameters - **start** (number) - Required - Starting position (included) - **end** (number) - Required - Ending position (excluded) ### Returns - **boolean** - True if all characters are ASCII, false otherwise ``` -------------------------------- ### Asn1String.Videotex(String) Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/lowlevel.md Constructs a Videotex string. No validation is implemented (`isValid` is null), so the constructor never throws. ```APIDOC ## Asn1String.Videotex(String) ### Description Constructs a Videotex string. No validation is implemented (`isValid` is null), so the constructor never throws. ### Method Constructor ### Parameters #### Input - **value** (String) - Required - The string content to wrap. ### Remarks - `isValid` is always `null`; `rawValue` is preserved as-is. ``` -------------------------------- ### Write and read string content Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/addons.md Writes and reads ASN.1 string content octets using Sink/Source helpers. ```kotlin val s = Buffer() val sBytes = s.writeAsn1StringContent("hello") val value = s.readAsn1StringContent(sBytes) // "hello" ``` -------------------------------- ### Write and read integer content Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/addons.md Writes and reads ASN.1 integer content octets using Sink/Source helpers. ```kotlin val n = Buffer() val nBytes = n.writeAsn1IntContent(42) val value = n.readAsn1IntContent(nBytes) // 42 ``` -------------------------------- ### Asn1String.General(String) Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/lowlevel.md Constructs a General string. Validation is best-effort: it recognizes a fixed low-range subset (7-bit 0x00–0x7F) and never returns false, so the constructor never throws. ```APIDOC ## Asn1String.General(String) ### Description Constructs a General string. Validation is best-effort: it recognizes a fixed low-range subset (7-bit 0x00–0x7F) and never returns false, so the constructor never throws. ### Method Constructor ### Parameters #### Input - **value** (String) - Required - The string content to wrap. ### Remarks - `isValid` returns `true` for recognized content and `null` for anything else; it never returns `false`. ``` -------------------------------- ### Asn1String.IA5(String) Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/lowlevel.md Constructs an IA5 string, enforcing the IA5 repertoire (ITU-T T.50 / ISO 646, 7-bit 0x00–0x7F). Throws Asn1Exception if the input is not valid IA5. ```APIDOC ## Asn1String.IA5(String) ### Description Constructs an IA5 string, enforcing the IA5 repertoire (ITU-T T.50 / ISO 646, 7-bit 0x00–0x7F). Throws Asn1Exception if the input is not valid IA5. ### Method Constructor ### Parameters #### Input - **value** (String) - Required - The string content to wrap. ### Exceptions - **Asn1Exception** - Thrown when the input is not valid IA5. ### Remarks - The `String` constructors (e.g. `Asn1String.IA5("…")`) are the only place that enforces validity; they throw `Asn1Exception` when `isValid` would be `false`. ``` -------------------------------- ### writeAsn1StringContent("hello") Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/addons.md Writes ASN.1 string content to a Sink. This is part of the io module primitive content helpers. ```APIDOC ## writeAsn1StringContent("hello") ### Description Writes ASN.1 string content to a Sink. This is part of the io module primitive content helpers. ### Method writeAsn1StringContent ### Parameters - **value** (String) - Required - The string value to write. ### Request Example ```kotlin val s = Buffer() val sBytes = s.writeAsn1StringContent("hello") ``` ``` -------------------------------- ### KnownOIDs.describeAll() Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/addons.md Bulk-loads all descriptions shipped by the oids module into the KnownOIDs map. This is part of the oids module. ```APIDOC ## KnownOIDs.describeAll() ### Description Bulk-loads all descriptions shipped by the oids module into the KnownOIDs map. This is part of the oids module. ### Method describeAll ### Request Example ```kotlin KnownOIDs.describeAll() ``` ``` -------------------------------- ### Primitive CHOICE alternatives definitions (kxs-choice-primitive-definitions) Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/kxs.md Referenced from the tutorial file at/asitplus/awesn1/serialization/tutorial/SerializationDocumentationTutorialTest.kt:kxs-choice-primitive-definitions. The code is not visible on this page; only the include marker is present. ```kotlin --8<-- "at/asitplus/awesn1/serialization/tutorial/SerializationDocumentationTutorialTest.kt:kxs-choice-primitive-definitions" ``` -------------------------------- ### Asn1String.Printable(String) Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/lowlevel.md Constructs a Printable string, enforcing the Printable repertoire (A–Z, a–z, 0–9, SPACE, and punctuation). Throws Asn1Exception if the input is not valid Printable. ```APIDOC ## Asn1String.Printable(String) ### Description Constructs a Printable string, enforcing the Printable repertoire (A–Z, a–z, 0–9, SPACE, and punctuation). Throws Asn1Exception if the input is not valid Printable. ### Method Constructor ### Parameters #### Input - **value** (String) - Required - The string content to wrap. ### Exceptions - **Asn1Exception** - Thrown when the input is not valid Printable. ### Remarks - The `String` constructors (e.g. `Asn1String.IA5("…")`) are the only place that enforces validity; they throw `Asn1Exception` when `isValid` would be `false`. ``` -------------------------------- ### Add custom OID description Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/addons.md Shows adding a custom description for an OID at runtime. ```kotlin val expressionistOID = ObjectIdentifier(Uuid.random()) KnownOIDs[expressionistOID].shouldBeNull() KnownOIDs[expressionistOID] = "Edvard Munch" KnownOIDs[expressionistOID] shouldBe "Edvard Munch" ``` -------------------------------- ### Encode and decode custom attribute using default DER Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/kxs.md Shows that after registration, the default DER instance can encode and decode the custom attribute type hierarchy. The example uses a concrete attribute value and verifies round-trip equality. ```kotlin val value: CustomAttribute = ConcreteCustomAttribute(ObjectIdentifier("1.2.840.113549.1.7.1")) DER.decodeFromByteArray( DER.encodeToByteArray(value) ) shouldBe ConcreteCustomAttribute(ObjectIdentifier("1.2.840.113549.1.7.1")) ``` -------------------------------- ### Validate fixtures with JVM tests Source: https://github.com/a-sit-plus/awesn1/blob/main/core/DEVELOPMENT.md Run this Gradle command to validate the regenerated fixtures. It executes the core JVM tests, which assert parser behavior and round-trip invariants rather than exact byte equality. ```bash ./gradlew :core:jvmTest ``` -------------------------------- ### Write and read boolean content Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/addons.md Writes and reads ASN.1 boolean content octets using Sink/Source helpers. ```kotlin val b = Buffer() b.writeAsn1BooleanContent(true) val value = b.readAsn1BooleanContent() // true ``` -------------------------------- ### Encode and decode with DER and kxs-io Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/addons.md Shows encoding an ObjectIdentifier to a Sink and decoding from a Source using DER and kxs-io extensions. ```kotlin val oid = ObjectIdentifier("1.2.840.113549.1.1.11") // Encode directly to a kotlinx.io.Sink using DER + kxs-io extension val sink = Buffer() DER.encodeToSink(oid, sink) // Decode directly from a kotlinx.io.Source using DER + kxs-io extension val source = Buffer().apply { write(sink.readByteArray()) } val decoded: ObjectIdentifier = DER.decodeFromSource(source) ``` -------------------------------- ### Primitive CHOICE alternatives roundtrip (kxs-choice-primitive-roundtrip) Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/kxs.md Referenced from the tutorial file at/asitplus/awesn1/serialization/tutorial/SerializationDocumentationTutorialTest.kt:kxs-choice-primitive-roundtrip. The code is not visible on this page; only the include marker is present. ```kotlin --8<-- "at/asitplus/awesn1/serialization/tutorial/SerializationDocumentationTutorialTest.kt:kxs-choice-primitive-roundtrip" ``` -------------------------------- ### constructor(enc, pos) Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/assets/asn1js/index-local.html Creates a new Stream instance to read binary data from an array or string. The constructor validates that the position is numeric and the encoding is a numeric array or string. ```APIDOC ## constructor(enc, pos) ### Description Creates a new Stream instance to read binary data from an array or string. The constructor validates that the position is numeric and the encoding is a numeric array or string. ### Parameters - **enc** (Stream|array|string) - Required - Data to read (will not be copied) - **pos** (?number) - Required - Starting position (mandatory when `end` is not a Stream) ### Throws - Error if `pos` is not a numeric value - Error if `enc` is not a numeric array or a string ``` -------------------------------- ### Asn1String.Teletex(String) Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/lowlevel.md Constructs a Teletex (T61) string. Validation is best-effort: it recognizes a fixed low-range subset (Latin-1 0x00–0xFF) and never returns false, so the constructor never throws. ```APIDOC ## Asn1String.Teletex(String) ### Description Constructs a Teletex (T61) string. Validation is best-effort: it recognizes a fixed low-range subset (Latin-1 0x00–0xFF) and never returns false, so the constructor never throws. ### Method Constructor ### Parameters #### Input - **value** (String) - Required - The string content to wrap. ### Remarks - `isValid` returns `true` for recognized content and `null` for anything else; it never returns `false`. ``` -------------------------------- ### Add awesn1 core and kxs dependencies with Gradle Kotlin DSL Source: https://github.com/a-sit-plus/awesn1/blob/main/README.md Declares the `core` and `kxs` modules as dependencies in a Gradle Kotlin build script. Use `core` for the low-level ASN.1 toolbox and add `kxs` for `kotlinx.serialization` integration. ```kotlin implementation("at.asitplus.awesn1:core:$version") implementation("at.asitplus.awesn1:kxs:$version") ``` -------------------------------- ### Sealed CHOICE definitions (kxs-choice-definitions) Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/kxs.md Referenced from the tutorial file at/asitplus/awesn1/serialization/tutorial/SerializationDocumentationTutorialTest.kt:kxs-choice-definitions. The code is not visible on this page; only the include marker is present. ```kotlin --8<-- "at/asitplus/awesn1/serialization/tutorial/SerializationDocumentationTutorialTest.kt:kxs-choice-definitions" ``` -------------------------------- ### Add kxs-io module dependency Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/addons.md Adds the awesn1 kxs-io module to a Gradle build for kotlinx-io extensions for DER kotlinx.serialization. ```kotlin implementation("at.asitplus.awesn1:kxs-io:$version") ``` -------------------------------- ### Asn1String.Universal(String) Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/lowlevel.md Constructs a Universal string. No validation is implemented (`isValid` is null), so the constructor never throws. ```APIDOC ## Asn1String.Universal(String) ### Description Constructs a Universal string. No validation is implemented (`isValid` is null), so the constructor never throws. ### Method Constructor ### Parameters #### Input - **value** (String) - Required - The string content to wrap. ### Remarks - `isValid` is always `null`; `rawValue` is preserved as-is. ``` -------------------------------- ### Open Polymorphism by OID roundtrip (kxs-open-poly-oid-roundtrip) Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/kxs.md Referenced from the tutorial test file; demonstrates the roundtrip encoding/decoding for OID-based open polymorphism. The actual code is not visible on this page. ```kotlin --8<-- "at/asitplus/awesn1/serialization/tutorial/SerializationDocumentationTutorialTest.kt:kxs-open-poly-oid-roundtrip" ``` -------------------------------- ### SignedBox usage and canonical DER verification (Kotlin) Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/kxs.md Constructs an ExamplePayload and SignedBox, then verifies the raw payload tag is context-specific with tag number 1. Encodes to canonical DER and checks the exact hex output. Decodes back and asserts the payload fields match the original. ```kotlin val payload = ExamplePayload( algorithmIdentifier = ObjectIdentifier("1.2.840.113549.1.1.11"), creationTimeEpochSeconds = 1_736_203_200, validUntilEpochSeconds = 1_767_739_200, integrityFlag = true, payloadData = "deadbeef".hexToByteArray(), ) val canonicalBox = SignedBox( payload, signature = "0102030405".hexToByteArray(), ) canonicalBox.rawPayload.tag shouldBe /* (1)!*/ Asn1Element.Tag(1uL, constructed = true, tagClass = TagClass.CONTEXT_SPECIFIC) fun assertEquivalentPayload(decoded: ExamplePayload, payload: ExamplePayload) { decoded.algorithmIdentifier shouldBe payload.algorithmIdentifier decoded.creationTimeEpochSeconds shouldBe payload.creationTimeEpochSeconds decoded.validUntilEpochSeconds shouldBe payload.validUntilEpochSeconds decoded.integrityFlag shouldBe payload.integrityFlag decoded.payloadData.contentEquals(payload.payloadData) shouldBe true } val canonicalDer = DER.encodeToByteArray(canonicalBox) canonicalDer.toHexString() shouldBe /* (2)! */ "3029a12006092a864886f70d01010b0204677c5bc00204695d8f400101ff0404deadbeef82050102030405" val decoded = DER.decodeFromByteArray(canonicalDer) assertEquivalentPayload(decoded.payload, payload) ``` -------------------------------- ### ExplicitlyTagged wrapper definitions (kxs-explicit-wrapper-definitions) Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/kxs.md Referenced from the tutorial file at/asitplus/awesn1/serialization/tutorial/SerializationDocumentationTutorialTest.kt:kxs-explicit-wrapper-definitions. The code is not visible on this page; only the include marker is present. ```kotlin --8<-- "at/asitplus/awesn1/serialization/tutorial/SerializationDocumentationTutorialTest.kt:kxs-explicit-wrapper-definitions" ``` -------------------------------- ### Open Polymorphism by OID definitions (kxs-open-poly-oid-definitions) Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/kxs.md Referenced from the tutorial test file; defines the OID-based open polymorphism model. The actual code is not visible on this page. ```kotlin --8<-- "at/asitplus/awesn1/serialization/tutorial/SerializationDocumentationTutorialTest.kt:kxs-open-poly-oid-definitions" ``` -------------------------------- ### Instant.encodeToAsn1UtcTimePrimitive() Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/lowlevel.md Encodes an Instant into an ASN.1 UTCTime primitive. ```APIDOC ## Instant.encodeToAsn1UtcTimePrimitive() ### Description Encodes an Instant into an ASN.1 UTCTime primitive. ### Method Function ### Signature `fun Instant.encodeToAsn1UtcTimePrimitive(): Asn1Primitive` ### Parameters None ### Returns - **Asn1Primitive** - The encoded UTCTime primitive. ``` -------------------------------- ### Decode ASN.1 element from Source Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/addons.md Reads one ASN.1 element from a kotlinx.io.Source using the io module extension. ```kotlin val source = Buffer().apply { write(derBytes) } val (element, consumed) = source.readAsn1Element() ``` -------------------------------- ### Expanded Tagging: Explicit and implicit tags Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/lowlevel.md Builds a Sequence with an explicitly tagged Bool, an implicitly tagged Utf8String with a private class tag, and an implicitly tagged Sequence without the CONSTRUCTED bit. The expected DER hex output is provided in the assertion. ```kotlin val tagged = Asn1.Sequence { +Asn1.ExplicitlyTagged(1u) { +Asn1.Bool(false) } +(Asn1.Utf8String("Foo") withImplicitTag (0xCAFEuL withClass TagClass.PRIVATE)) +(Asn1.Sequence { +Asn1.Int(42) } withImplicitTag (0x5EuL without CONSTRUCTED)) } tagged.derEncoded.toHexString() shouldBe /* (1)! */"3013a103010100df83957e03466f6f9f5e0302012a" ``` -------------------------------- ### Add io module dependency Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/addons.md Adds the awesn1 io module to a Gradle build for kotlinx-io integration. ```kotlin implementation("at.asitplus.awesn1:io:$version") ``` -------------------------------- ### Asn1Element.parseFirst(source) Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/addons.md Parses the first ASN.1 element from a kotlinx.io.Source. This is part of the io module integration for ASN.1 parsing. ```APIDOC ## Asn1Element.parseFirst(source) ### Description Parses the first ASN.1 element from a kotlinx.io.Source. This is part of the io module integration for ASN.1 parsing. ### Method parseFirst ### Parameters - **source** (kotlinx.io.Source) - Required - The source to parse from. ### Response Returns an Asn1Element. ``` -------------------------------- ### Maven coordinates for kxs module Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/kxs.md Adds the kxs module to a Gradle Kotlin build. Replace $version with the desired awesn1 version. ```kotlin implementation("at.asitplus.awesn1:kxs:$version") ``` -------------------------------- ### Build a DER-encoded ASN.1 sequence with the Builder DSL Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/core.md Constructs an ASN.1 sequence containing an integer, boolean, and UTC time, then encodes it to DER and asserts the expected hex string. The expected hex value is shown in the assertion; the asn1js.eu link lets you explore the encoding interactively. ```kotlin val frame = Asn1.Sequence { +Asn1.Int(7) +Asn1.Bool(true) +Asn1.UtcTime(kotlin.time.Instant.parse("2026-01-01T12:30:45Z")) } val derHex = frame.derEncoded.toHexString() derHex shouldBe /* (1)! */"30150201070101ff170d3236303130313132333034355a" ``` -------------------------------- ### Asn1String.Visible(String) Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/lowlevel.md Constructs a Visible string, enforcing the Visible repertoire (T.50 graphic subset + SPACE, 0x20–0x7E). Throws Asn1Exception if the input is not valid Visible. ```APIDOC ## Asn1String.Visible(String) ### Description Constructs a Visible string, enforcing the Visible repertoire (T.50 graphic subset + SPACE, 0x20–0x7E). Throws Asn1Exception if the input is not valid Visible. ### Method Constructor ### Parameters #### Input - **value** (String) - Required - The string content to wrap. ### Exceptions - **Asn1Exception** - Thrown when the input is not valid Visible. ### Remarks - The `String` constructors (e.g. `Asn1String.IA5("…")`) are the only place that enforces validity; they throw `Asn1Exception` when `isValid` would be `false`. ``` -------------------------------- ### source.readAsn1Element() Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/addons.md Reads an ASN.1 element from a kotlinx.io.Source. This is part of the io module integration for ASN.1 parsing. ```APIDOC ## source.readAsn1Element() ### Description Reads an ASN.1 element from a kotlinx.io.Source. This is part of the io module integration for ASN.1 parsing. ### Method readAsn1Element ### Parameters - **source** (kotlinx.io.Source) - Required - The source to read from. ### Response Returns a Pair where the first element is the parsed element and the second is the number of bytes consumed. ### Request Example ```kotlin val source = Buffer().apply { write(derBytes) } val (element, consumed) = source.readAsn1Element() ``` ``` -------------------------------- ### Sealed CHOICE roundtrip (kxs-choice-roundtrip) Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/kxs.md Referenced from the tutorial file at/asitplus/awesn1/serialization/tutorial/SerializationDocumentationTutorialTest.kt:kxs-choice-roundtrip. The code is not visible on this page; only the include marker is present. ```kotlin --8<-- "at/asitplus/awesn1/serialization/tutorial/SerializationDocumentationTutorialTest.kt:kxs-choice-roundtrip" ``` -------------------------------- ### Asn1.Sequence builder Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/lowlevel.md Constructs an ASN.1 SEQUENCE structure. Inside the builder, unary '+' accepts raw Asn1Element values, Asn1Encodable values, and transparent wrapper types (WrappedElement, WrappedEncodable) that have the same ASN.1 representation as the exposed value. ```APIDOC ## Asn1.Sequence ### Description Constructs an ASN.1 SEQUENCE structure. Inside the builder, unary '+' accepts raw Asn1Element values, Asn1Encodable values, and transparent wrapper types (WrappedElement, WrappedEncodable) that have the same ASN.1 representation as the exposed value. ### Method Builder DSL constructor ### Parameters #### Builder Context - **receiver** (Asn1.SequenceBuilder) - Required - The builder context where elements are added using unary '+'. ### Response Returns an Asn1Element representing the SEQUENCE. ### Request Example ```kotlin val sequence = Asn1.Sequence { +algorithmIdentifier +signatureValue } ``` ### Response Example ```kotlin val frame = Asn1.Sequence { +Asn1.Int(7) +Asn1.Bool(true) +Asn1.UtcTime(kotlin.time.Instant.parse("2026-01-01T12:30:45Z")) } val derHex = frame.derEncoded.toHexString() derHex shouldBe "30150201070101ff170d3236303130313132333034355a" ``` ``` -------------------------------- ### SignedBox model with raw implicitly tagged payload (Kotlin) Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/kxs.md Defines ExamplePayload, ImplicitlyTaggedPayload, and SignedBox. SignedBox stores the payload as a raw Asn1Element and a signature, both implicitly tagged. A @Transient parsed value is materialized at instantiation to reject structurally invalid raw payloads immediately. ```kotlin @Serializable private data class ExamplePayload( val algorithmIdentifier: ObjectIdentifier, val creationTimeEpochSeconds: Long, val validUntilEpochSeconds: Long, val integrityFlag: Boolean, val payloadData: ByteArray, ) @Serializable @JvmInline @Asn1Tag(tagNumber = 1u) private value class ImplicitlyTaggedPayload( val value: ExamplePayload, ) @Serializable private data class SignedBox private constructor( val rawPayload: Asn1Element, @Asn1Tag(tagNumber = 2u) val signature: ByteArray, ) { //public constructor ensures only valid data is passed constructor(payload: ExamplePayload, signature: ByteArray) : this( rawPayload = DER.encodeToTlv(ImplicitlyTaggedPayload(payload)), signature = signature ) //hidden from serialization, but eager init ensure the data is semantically correct //if you want to be even more lenient, mage it a getter that throws @Transient val payload: ExamplePayload = DER.decodeFromTlv(rawPayload).value } ``` -------------------------------- ### Asn1String.BMP(String) Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/lowlevel.md Constructs a BMP string. No validation is implemented (`isValid` is null), so the constructor never throws. ```APIDOC ## Asn1String.BMP(String) ### Description Constructs a BMP string. No validation is implemented (`isValid` is null), so the constructor never throws. ### Method Constructor ### Parameters #### Input - **value** (String) - Required - The string content to wrap. ### Remarks - `isValid` is always `null`; `rawValue` is preserved as-is. ``` -------------------------------- ### Add core module dependency with Maven coordinates Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/core.md Adds the awesn1 core module as a dependency using Gradle Kotlin DSL. Replace $version with the desired release version. ```kotlin implementation("at.asitplus.awesn1:core:$version") ``` -------------------------------- ### toPrettyString(indent) Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/assets/asn1js/index-local.html Returns a pretty-printed string representation of the ASN.1 element and its sub-elements, with optional indentation. ```APIDOC ## toPrettyString(indent) ### Description Returns a pretty-printed string representation of the ASN.1 element and its sub-elements, with optional indentation. ### Method toPrettyString(indent) ### Parameters - **indent** (string) - Optional - The indentation string. Defaults to "". ### Returns - **string** - The pretty string representation. ``` -------------------------------- ### Import Hex submodule from @lapo/asn1js/hex.js Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/assets/asn1js/README.md Import the Hex utility submodule for hex decoding. ```js import { Hex } from '@lapo/asn1js/hex.js'; ``` -------------------------------- ### X.509 GeneralName and Name CHOICE definitions Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/kxs.md ASN.1 definitions from X.509 showing GeneralName and Name as CHOICE types. dNSName is an implicitly tagged primitive alternative, while directoryName wraps a Name CHOICE in a context-specific constructed [4] wrapper. ```asn1 GeneralName ::= CHOICE { dNSName [2] IA5String, directoryName [4] Name } Name ::= CHOICE { rdnSequence RDNSequence } ``` -------------------------------- ### Asn1Decodable.decodeFromTlv(src, assertTag) Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/lowlevel.md Performs throwing decode from TLV format. ```APIDOC ## Asn1Decodable.decodeFromTlv(src, assertTag) ### Description Performs throwing decode from TLV format. ### Method decodeFromTlv ### Parameters #### Input - **src** - Required - The source to decode from. - **assertTag** - Required - The tag assertion function. ``` -------------------------------- ### Regenerate OpenSSL fixtures Source: https://github.com/a-sit-plus/awesn1/blob/main/core/DEVELOPMENT.md Run this script to regenerate the PEM fixture corpus stored in core/src/jvmTest/resources/fixtures/openssl. The fixtures cover legacy header-based encryption (Proc-Type, DEK-Info) and PKCS#8 encrypted keys (ENCRYPTED PRIVATE KEY), including multi-block documents and mixed-label bundles. Exact bytes may change across regenerations; tests assert parser behavior and round-trip invariants. ```bash ./core/scripts/regenerate-openssl-fixtures.sh ``` -------------------------------- ### writeAsn1IntContent(42) Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/addons.md Writes ASN.1 integer content to a Sink. This is part of the io module primitive content helpers. ```APIDOC ## writeAsn1IntContent(42) ### Description Writes ASN.1 integer content to a Sink. This is part of the io module primitive content helpers. ### Method writeAsn1IntContent ### Parameters - **value** (Int) - Required - The integer value to write. ### Request Example ```kotlin val n = Buffer() val nBytes = n.writeAsn1IntContent(42) ``` ``` -------------------------------- ### ExplicitlyTagged wrapper roundtrip (kxs-explicit-wrapper-roundtrip) Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/kxs.md Referenced from the tutorial file at/asitplus/awesn1/serialization/tutorial/SerializationDocumentationTutorialTest.kt:kxs-explicit-wrapper-roundtrip. The code is not visible on this page; only the include marker is present. ```kotlin --8<-- "at/asitplus/awesn1/serialization/tutorial/SerializationDocumentationTutorialTest.kt:kxs-explicit-wrapper-roundtrip" ``` -------------------------------- ### Instant.encodeToAsn1GeneralizedTimePrimitive() Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/lowlevel.md Encodes an Instant into an ASN.1 GeneralizedTime primitive. ```APIDOC ## Instant.encodeToAsn1GeneralizedTimePrimitive() ### Description Encodes an Instant into an ASN.1 GeneralizedTime primitive. ### Method Function ### Signature `fun Instant.encodeToAsn1GeneralizedTimePrimitive(): Asn1Primitive` ### Parameters None ### Returns - **Asn1Primitive** - The encoded GeneralizedTime primitive. ``` -------------------------------- ### Asn1Element.parseAll(source) Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/addons.md Parses all ASN.1 elements from a kotlinx.io.Source. This is part of the io module integration for ASN.1 parsing. ```APIDOC ## Asn1Element.parseAll(source) ### Description Parses all ASN.1 elements from a kotlinx.io.Source. This is part of the io module integration for ASN.1 parsing. ### Method parseAll ### Parameters - **source** (kotlinx.io.Source) - Required - The source to parse from. ### Response Returns a list of Asn1Element. ``` -------------------------------- ### DER.decodeFromSource(source) Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/addons.md Decodes an ObjectIdentifier from a kotlinx.io.Source using DER and kotlinx.serialization. This is part of the kxs-io module integration. ```APIDOC ## DER.decodeFromSource(source) ### Description Decodes an ObjectIdentifier from a kotlinx.io.Source using DER and kotlinx.serialization. This is part of the kxs-io module integration. ### Method decodeFromSource ### Parameters - **source** (kotlinx.io.Source) - Required - The source to read from. ### Response Returns the decoded ObjectIdentifier. ### Request Example ```kotlin val source = Buffer().apply { write(sink.readByteArray()) } val decoded: ObjectIdentifier = DER.decodeFromSource(source) ``` ``` -------------------------------- ### readAsn1IntContent(nBytes) Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/addons.md Reads ASN.1 integer content from a Source. This is part of the io module primitive content helpers. ```APIDOC ## readAsn1IntContent(nBytes) ### Description Reads ASN.1 integer content from a Source. This is part of the io module primitive content helpers. ### Method readAsn1IntContent ### Parameters - **nBytes** (Long) - Required - The expected content length. ### Response Returns the integer value. ### Request Example ```kotlin val value = n.readAsn1IntContent(nBytes) // 42 ``` ``` -------------------------------- ### Serialize RFC 5280 GeneralName CHOICE with sealed polymorphism Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/core.md Models a subset of GeneralName ::= CHOICE from RFC 5280 with dNSName [2] IA5String and uniformResourceIdentifier [6] IA5String. Encodes two alternatives, round-trips decoding, and asserts exact DER hex bytes. Uses @Asn1Tag annotations for context-specific primitive tags. ```kotlin @Serializable private sealed interface Rfc5280GeneralName @Serializable @JvmInline @Asn1Tag( tagNumber = 2u, tagClass = Asn1Tag.Class.CONTEXT_SPECIFIC, constructed = Asn1Tag.ConstructedBit.PRIMITIVE, ) private value class Rfc5280DnsName( val value: String, ) : Rfc5280GeneralName @Serializable @JvmInline @Asn1Tag( tagNumber = 6u, tagClass = Asn1Tag.Class.CONTEXT_SPECIFIC, constructed = Asn1Tag.ConstructedBit.PRIMITIVE, ) private value class Rfc5280UriName( val value: String, ) : Rfc5280GeneralName private fun coreHookSerializationChoiceRfcDer(): Pair { val dnsName: Rfc5280GeneralName = Rfc5280DnsName("example.com") val uriName: Rfc5280GeneralName = Rfc5280UriName("https://example.com") val dnsDer = DER.encodeToByteArray(dnsName) dnsDer.toHexString() shouldBe "820b6578616d706c652e636f6d" /* (1)! */ DER.decodeFromByteArray(dnsDer) shouldBe dnsName val uriDer = DER.encodeToByteArray(uriName) uriDer.toHexString() shouldBe "861368747470733a2f2f6578616d706c652e636f6d" /* (2)! */ DER.decodeFromByteArray(uriDer) shouldBe uriName return dnsDer to uriDer } ``` -------------------------------- ### Add crypto module dependency with Maven coordinates Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/crypto.md Adds the awesn1 crypto module to a Kotlin/Gradle project using the Maven coordinate `at.asitplus.awesn1:crypto`. The module provides structural ASN.1 DER models for cryptographic and PKI data, not validation or cryptographic operations. ```kotlin implementation("at.asitplus.awesn1:crypto:$version") ``` -------------------------------- ### posEnd() Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/assets/asn1js/index-local.html Returns the ending position of the element in the stream. ```APIDOC ## posEnd() ### Description Returns the ending position of the element in the stream. ### Method posEnd() ### Returns - **number** - The ending position. ``` -------------------------------- ### posContent() Source: https://github.com/a-sit-plus/awesn1/blob/main/docs/docs/assets/asn1js/index-local.html Returns the position of the content in the stream. ```APIDOC ## posContent() ### Description Returns the position of the content in the stream. ### Method posContent() ### Returns - **number** - The content position. ```