Ocamlnet 4 Reference Manual : Netsys_gssapi

# Module Netsys_gssapi

    module Netsys_gssapi: sig .. end

GSS-API Definition

This is mainly a translation of RFC 2743/2744 to Ocaml.

The following other modules are also interesting in this context:

- `Netgssapi_support`
- `Netoid`

### Types

    type oid = int array

OIDs like "1.3.6.1.5.6.2" as array of int's. The empty array means `GSS_C_NO_OID`. See also `Netoid`.

    type oid_set = oid list

A set of OID's. These lists should not contain OID's twice. The empty list means `GSS_C_NO_OID_SET`.

    type token = string

Authentication tokens. These are also opaque to the caller, but have a string representation so that they can be sent over the wire.

    type interprocess_token = string

Interprocess tokens. These are also opaque to the caller, but have a string representation so that they can be sent over the wire.

    type calling_error = [ `Bad_structure | `Inaccessible_read | `Inaccessible_write | `None ]

Possible errors caused by the caller

    type routine_error = [ `Bad_QOP
           | `Bad_bindings
           | `Bad_mech
           | `Bad_mic
           | `Bad_name
           | `Bad_nametype
           | `Bad_status
           | `Context_expired
           | `Credentials_expired
           | `Defective_credential
           | `Defective_token
           | `Duplicate_element
           | `Failure
           | `Name_not_mn
           | `No_context
           | `No_cred
           | `None
           | `Unauthorized
           | `Unavailable ]

Possible errors caused by the provider

    type suppl_status = [ `Continue_needed
           | `Duplicate_token
           | `Gap_token
           | `Old_token
           | `Unseq_token ]

Further flags

    type major_status = calling_error * routine_error *
           suppl_status list

The major status consists of these three elements. The bits of the supplementary status field are represented as list

    type minor_status = int32

The minor status is provider-specific. Note that GSS-API defines it as unsigned 32-bit integer whereas `int32` is signed.

    type address = [ `Inet of Unix.inet_addr
           | `Local of string
           | `Nulladdr
           | `Other of int32 * string
           | `Unspecified of string ]

Addresses tagged by address types

    type channel_bindings = address * address * string

Channel binding as tuple `(initiator_address, acceptor_address, application_data)`

    type cred_usage = [ `Accept | `Both | `Initiate ]

    type qop = int32

Quality-of-proctection parameters are mechanism-specific. The value 0 can always be used for a default protection level.

    type message = Netsys_types.mstring list

Messages are represented as lists of `mstring`

    type ret_flag = [ `Anon_flag
           | `Conf_flag
           | `Deleg_flag
           | `Integ_flag
           | `Mutual_flag
           | `Prot_ready_flag
           | `Replay_flag
           | `Sequence_flag
           | `Trans_flag ]

Flags for the `accept_sec_context` method

    type req_flag = [ `Anon_flag
           | `Conf_flag
           | `Deleg_flag
           | `Integ_flag
           | `Mutual_flag
           | `Replay_flag
           | `Sequence_flag ]

Flags for the `init_sec_context` method

    type time = [ `Indefinite | `This of float ]

    class type [['credential, 'name, 'context]] poly_gss_api = object .. end

    module type GSSAPI = sig .. end

### Utility functions

These functions convert values to strings. Useful for generating log messages.

    val string_of_calling_error : calling_error -> string

    val string_of_routine_error : routine_error -> string

    val string_of_suppl_status : suppl_status -> string

    val string_of_major_status : major_status -> string

    val string_of_flag : ret_flag -> string

### Common OID's for name types

See RFC 2078, section 4

    val nt_hostbased_service : oid

names like "service@hostname"

    val nt_hostbased_service_alt : oid

another OID for the same (RFC 1964 mentions it)

    val nt_user_name : oid

names like "username"

    val nt_machine_uid_name : oid

user ID in host byte order

    val nt_string_uid_name : oid

user ID as string of digits

    val nt_anonymous : oid

anonymous name

    val nt_export_name : oid

an export name

    val nt_krb5_principal_name : oid

a Kerberos 5 principal name (see `Netgssapi_support` for parsers

    val parse_hostbased_service : string -> string * string

Returns (`service,host`) for "service@host". Fails if not parseable

### Configuring clients

    type support_level = [ `If_possible | `None | `Required ]

    class type client_config = object .. end

See `Netsys_gssapi.create_client_config`

    val create_client_config : ?mech_type:oid ->
           ?initiator_name:string * oid ->
           ?initiator_cred:exn ->
           ?target_name:string * oid ->
           ?privacy:support_level ->
           ?integrity:support_level ->
           ?flags:(req_flag * support_level) list ->
           unit -> client_config

`mech_type` is the GSSAPI mechanism to use. If left unspecified, a default is used. `target_name` is the name of the service to connect to. `initiator_name` identifies and authenticates the client. Note that you normally can omit all of `mech_type`, `target_name`, and `initiator_name` as GSSAPI already substitutes reasonable defaults (at least if Kerberos is available as mechanism).

If you have a delegated credential you can also pass it as `initiator_cred`. This must be a `Credential` exception from the GSSAPI provider. `initiator_cred` has precedence over `initiator_name`.

`privacy` and `integrity` specify the desired level of protection. By default, both integrity and privacy are enabled if available, but it is no error if the mechanism doesn't support these features.

`flags`: additional GSSAPI flags. These should not contain ``Conf_flag` and ``Integ_flag` (instead use `privacy` and `integrity`, resp.).

    class type client_props = object .. end

Return properties of the client context

    val marshal_client_props : client_props -> string

    val unmarshal_client_props : string -> client_props

### Configuring servers

    class type server_config = object .. end

See `Netsys_gssapi.create_server_config`

    val create_server_config : ?mech_types:oid list ->
           ?acceptor_name:string * oid ->
           ?privacy:support_level ->
           ?integrity:support_level ->
           ?flags:(req_flag * support_level) list ->
           unit -> server_config

`mech_types` is the list of GSSAPI mechanism that are acceptable. If left unspecified, a default is used. `acceptor_name` is the name of the service to offer.

Note that you normally can omit `mech_types` as GSSAPI already substitutes reasonable defaults (at least if Kerberos is available as mechanism). `acceptor_name` should normally be specified.

`privacy` and `integrity` specify the desired level of protection. By default, both integrity and privacy are enabled if available, but it is no error if the mechanism doesn't support these features.

`flags`: additional GSSAPI flags. These should not contain ``Conf_flag` and ``Integ_flag` (instead use `privacy` and `integrity`, resp.).

    class type server_props = object .. end

Return properties of the server context

    val marshal_server_props : server_props -> string

    val unmarshal_server_props : string -> server_props

This doesn't restore deleg_credential which is unmarshallable!

### Encodings

Some conversions have been moved to `Netoid`:

- `oid_to_string` is now `Netoid.to_string_curly`
- `string_to_oid` is now `Netoid.of_string_curly`

The remaining functions can now be found in `Netgssapi_support`.

### Create tokens

All functions have been moved to `Netgssapi_support`