Signum Kotlin Multiplatform Library

Indispensable ASN.1 is a Kotlin Multiplatform (KMP) library designed for parsing and encoding ASN.1 structures. It is built to be highly portable, depending only on kotlinx-* libraries and KmmResult for smooth iOS interop.

Key features include:

• ASN.1 Parser and Encoder: Includes a DSL for generating ASN.1 structures.
• ObjectIdentifier: Supports human-readable notation (e.g., 1.2.9.6245.3.72.13.4.7.6).
• ASN.1 Integer: Supports variable-length integers.
• BitSet: A 100% pure Kotlin implementation.
• Generic Abstractions: Allows operating on and creating arbitrary ASN.1 data.

Platform Support: Supports all KMP targets except wasm/WASI (due to Kotest limitations).

When using Signum for cryptographic and ASN.1 operations, be aware of the following constraints:

• ASN.1 Encoding: Only DER encoding and parsing of ASN.1 structures are supported.
• X509Certificate Abstractions: High-level abstractions like X509Certificate may exhibit leniency or strictness that differs from some specifications. For example, DSA-signed certificates will not parse into an X509Certificate instance. However, certificates violating the spec by containing duplicate extensions may still parse successfully.
• Revocation Checks: The library does not provide built-in OCSP or CRL checks, although the data required for these checks can be parsed from certificates.
• Algorithm Support: Supported algorithms are limited to standard cryptographic primitives; specialized curves (e.g., Bernstein curves) are not currently supported.

The indispensable-cosef library provides platform-independent COSE (CBOR Object Signing and Encryption) data types and utility functions. It is designed to interoperate with Indispensable data classes such as SignatureAlgorithm, CryptoSignature, and CryptoPublicKey.

Key features include:

• Predefined JOSE algorithm identifiers.
• Guaranteed correct serialization using kotlinx.serialization.
• Specialized classes like CborWebToken that include built-in serialize() and deserialize() functions.
• A preconfigured serializer named coseCompliantSerializer that ensures compliant serialization of all COSE-related data structures.

Parsed Asn1Elements are categorized into two types:

Primitives (Asn1Primitive)

These have a tag and a value. Common convenience wrappers include:

• Asn1BitString
• Asn1PrimitiveOctetString

Structures (Asn1Structure)

These contain child nodes. Common types include:

• Asn1Sequence and Asn1SequenceOf
• Asn1Set and Asn1SetOf (children are sorted by default)
• Asn1EncapsulatingOctetString (contains a valid ASN.1 structure or primitive)
• Asn1ExplicitlyTagged (user-specified tag + CONTEXT_SPECIFIC + CONSTRUCTED)
• Asn1CustomStructure (any other CONSTRUCTED tag)

You can use convenience wrappers like .asSequence() to cast to a subtype, which throws an Asn1Exception if the cast is invalid.

Ephemeral keys and signers are not backed by a persistent provider and are not persisted. They are delegated to platform functionality but work consistently across all platforms.

There are two ways to use them:

1. Directly via Signer.Ephemeral{}: Pass EC or RSA-specific configuration options directly.
2. Via EphemeralKey{}: Create an ephemeral key first, then call .getSigner{} on it. When calling .getSigner{}, you can pass algorithm-specific configuration options (like hash algorithms or padding) if multiple options were specified during key creation.

// Option 1: Direct ephemeral signer
val signer = Signer.Ephemeral(ecConfig)

// Option 2: Via EphemeralKey
val ephemeralKey = EphemeralKey(ecConfig)
val signer = ephemeralKey.getSigner(hashConfig)

The Supreme KMP provider uses Kotlin contracts to allow the compiler to smart-cast objects based on their cryptographic properties. You can combine these to steadily narrow down what an object is capable of:

• isAuthenticated(): Smart-casts AuthCapability to Authenticated<*> or Unauthenticated.
• hasDedicatedMac(): Smart-casts KeyType to WithDedicatedMac and AuthCapability to Authenticated.WithDedicatedMac (or handles the Unauthenticated/Integrated union).
• requiresNonce(): Smart-casts NonceTrait to Nonce.Required or Nonce.Without.
• isIntegrated(): (Only for Authenticated.Integrated objects) Smart-casts AuthCapability and KeyType to their integrated variants.
• isBlockCipher() / isStreamCipher(): Smart-casts the algorithm to BlockCipher or StreamCipher respectively.

The ASN.1 engine uses a two-tier pattern for encoding and decoding.

High-level types (like X509Certificate or CryptoPublicKey) implement Asn1Encodable and their companions implement Asn1Decodable. These types provide enriched semantics for complex structures.

Low-level elements (like Asn1Element, Asn1Primitive, and Asn1Structure) operate on the raw TLV (Tag-Length-Value) structures.

A typical pipeline follows this flow:

1. Encoded Bytes $\rightarrow$ Asn1Element.parse() $\rightarrow$ ASN.1 Element (Low-level)
2. ASN.1 Element $\rightarrow$ decodeFromTlv() $\rightarrow$ Rich Type (High-level, e.g., ObjectIdentifier)

For encoding, the flow is reversed:

1. Rich Type $\rightarrow$ encodeToTlv() $\rightarrow$ ASN.1 Element
2. ASN.1 Element $\rightarrow$ derEncoded $\rightarrow$ Encoded Bytes

Unlike the Java Cryptography Architecture (JCA), Supreme uses a Provider to manage private key material and create Signer instances.

• Provider: Manages signing keys and creates signers.
• Signer: An object used to perform signing operations with a private key.
• Verifier: Instantiated on a SignatureAlgorithm and takes a CryptoPublicKey as a parameter to verify signatures.
• Ephemeral Keys: Creating temporary keys is a dedicated operation decoupled from a Provider.

Important: Supreme relies heavily on KmmResult to communicate success or failure. Do not ignore the results returned by any operation, as the library is designed to never throw exceptions.