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 ` |
`(*` | Algorithms are identified by an OID and OID-specific parameters. | `*)` |

`type `

pubkey = {

` ` |
`pubkey_type : ` |

` ` |
`pubkey_data : ` |

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 ` |

`|` |
`P_OAEP of ` |

`type `

encrypt_alg =

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

`type `

sign_alg =

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

`type `

kex_alg =

`|` |
`Kex of ` |
`(*` | An algorithm that can be used for key agreement. Same format as
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 ` |
`(*` |
| `*)` |

`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`