# Module Netx509_pubkey

    module Netx509_pubkey: sig .. end

X.509 public key cryptography - keys and naming

Support for reading in public keys and retrieving the type of the key. This module is mostly about naming key types and algorithms.

In the X.509 standard a public key is often part of a certificate and there stored in the `subjectPublicKeyInfo` field. However, "raw" public keys (i.e. outside certificates) are also known. In this case, the same representation as for `subjectPublicKeyInfo` field is chosen and just stored separately in a file.

Like certificates, public keys are described by an ASN.1 syntax and are normally stored by applying the DER encoding rules. If stored in files, PEM headers for the DER encoding are common. Such files have a PEM header of "BEGIN PUBLIC KEY". Note that the header - unlike for private keys - does not indicate the type of key. The type is already a member of the `subjectPublicKeyInfo` field.

A public key consists of three parts:

- the OID of the type of the key
- the parameters of the algorithm
- the key data

A certain type of public key can only be used with certain algorithms. Often, the OID for the type of the key is simply set to the OID for the simplest algorithm that can be used with the key. For example, RSA keys have the OID of the PKCS-1 encryption algorithm. However, you can use the same keys also with the slightly more complicated PKCS-1 signing algorithms.

It depends on the algorithm whether the parameters can be changed while keeping the key data.

See `Netx509_pubkey_crypto` for functions that actually encrypt or sign data with the current crypto provider.

    type oid = Netoid.t

OIDs are just integer sequences

    type alg_id =

`|` | `Alg_id of `oid * Netasn1.Value.value option`` | `(*` | Algorithms are identified by an OID and OID-specific parameters. | `*)`

    type pubkey = {

`` | `pubkey_type : `alg_id`;`
`` | `pubkey_data : `Netasn1.Value.bitstring_value`;`

}

Public key info: the key as such plus the algorithm. This combination is stored in PEM files tagged with "PUBLIC KEY", and also part of X.509 certificates.

    type hash_function = [ `SHA_1 | `SHA_224 | `SHA_256 | `SHA_384 | `SHA_512 ]

    type maskgen_function = [ `MGF1 of hash_function ]

    type alg_param =

`|` | `P_PSS of `hash_function * maskgen_function * int``
`|` | `P_OAEP of `hash_function * maskgen_function * string``

    type encrypt_alg =

`|` | `Encrypt of `oid * alg_param option`` | `(*` | An algorithm that can be used for encryption. Same format as `Alg_id` | `*)`

    type sign_alg =

`|` | `Sign of `oid * alg_param option`` | `(*` | An algorithm that can be used for signing. Same format as `Alg_id` | `*)`

    type kex_alg =

`|`

`Kex of `oid * alg_param option``

`(*`

An algorithm that can be used for key agreement. Same format as `Alg_id`

Remember that you can use any key agreement protocol also as public key mechanism: if Alice sends Bob message A based on a secret a, and Bob replies with message B based on a secret b, and both agree on a key K=f(a,b), you can consider A as the public key and Alices's secret a as the private key. The message B is a parameter of the ciphertext (comparable to the IV in symmetric cryptography), and K is used as transport key (for a symmetric cipher). That's why the key agreement algorithms appear here.

`*)`

    val decode_pubkey_from_der : string -> pubkey

Decodes a DER-encoded public key info structure. Note that this function performs only a partial check on the integrity of the data.

    val encode_pubkey_to_der : pubkey -> string

Encodes a public key info structure as DER

    val read_pubkey_from_pem : Netchannels.in_obj_channel -> pubkey

Reads a PEM file tagged as "PUBLIC KEY". Note that this function performs only a partial check on the integrity of the data.

    type privkey =

`|` | `Privkey of `string * string`` | `(*` | `(format,data)`, using the formats: "RSA", "DSA", "DH", "EC". The `data` string is for the mentioned formats DER-encoded. | `*)`

    val read_privkey_from_pem : Netchannels.in_obj_channel -> privkey

Reads a PEM file tagged as "... PRIVATE KEY". This function cannot handle encrypted private keys. Note that this function performs only a partial check on the integrity of the data.

    module Key: sig .. end

    module Encryption: sig .. end

    module Keyagreement: sig .. end

    module Signing: sig .. end