GSS-API Definition
This is mainly a translation of RFC 2743/2744 to Ocaml.
OIDs like "1.3.6.1.5.6.2" as array of int's. The empty array
means GSS_C_NO_OID
.
A set of OID's. These lists should not contain OID's twice.
The empty list means GSS_C_NO_OID_SET
.
A credential is opaque for the caller of the GSS-API.
The provider of the GSS-API can emit new credential objects,
and hand them out to the caller. When the caller passes
credentials back to the provider, the provider must check
whether the object is known, and reject any fake objects
created by the caller by raising Invalid_argument
.
A context is also opaque, and the same rules apply as for
credential
.
The method valid
is true as long as the context is not
deleted.
Authentication tokens. These are also opaque to the caller, but have a string representation so that they can be sent over the wire.
Interprocess tokens. These are also opaque to the caller, but have a string representation so that they can be sent over the wire.
Possible errors caused by the caller
Possible errors caused by the provider
Further flags
The major status consists of these three elements. The bits of the supplementary status field are represented as list
The minor status is provider-specific. Note that GSS-API defines
it as unsigned 32-bit integer whereas int32
is signed.
A name is also opaque, and the same rules apply as for
credential
.
Quality-of-proctection parameters are mechanism-specific
Flags for the accept_sec_context
method
Flags for the init_sec_context
method
There are no defined exceptions.
Errors should be reported using the major_status
and minor_status
codes as much as possible.
Invalid_argument
may be raised for clear violations of calling
requirements, e.g. when an opaque object is passed to this interface
that was not returned by it before.
The methods have generally a type of the form
m : 't . arg1 -> ... -> argN -> out:( ret1 -> ... -> retM -> 't ) -> 't
where arg
s are input arguments (with the exception of context
which is in/out), and where outputs are passed back by calling the out
functions with the outputs. The return value of out
is the return
value of the method call.
For example, if only output_token
of the accept_sec_context
method
is needed, one could call this method as in
let output_token =
gss_api # accept_sec_context
...
~out:(fun ~src_name ~mech_type ~output_token ~ret_flags
~time_rec ~delegated_cred_handle ~minor_status
~major_status ->
output_token
)
Output values may not be defined when major_status
indicates
an error. (But see the RFC for details; especially init_sec_contect
and accept_sec_context
may emit tokens even when major_status
indicates an error.)
The names of the parameters are taken from RFC 2744, only
suffixes like _handle
have been removed. When the prefixes
input_
and output_
are meaningless, they are also removed.
All prefixes like "GSS" are removed anyway.
A string name identifying the provider
On the first call, pass ~context:None
. If successful, the
function outputs a non-None ~output_context
which should be
passed as new ~context
in follow-up calls.
If the output_token
is non-empty, it must be transmitted to
the peer - independent of the major_status
.
Output tokens are not supported (this is a deprecated feature of GSSAPI)
Note that display_minor_status
decodes all status value parts in
one step and returns the result as string list
. Also, this
method is restricted to decoding minor statuses
On the first call, pass ~context:None
. If successful, the
function outputs a non-None ~output_context
which should be
passed as new ~context
in follow-up calls.
If the output_token
is non-empty, it must be transmitted to
the peer - independent of the major_status
.
Note that the output_message
can be a buffer of different type
(string vs. bigarray) than input_message
. In
output_message_preferred_type
the called may wish a certain
representation. It is, however, not ensured that the wish is
granted.
output_message_preferred_type
: see unwrap
These functions convert values to strings. Useful for generating log messages.
See RFC 2078, section 4
Returns (service,host
) for "service
There is some chance that some of these routines will finally be moved to netstring
Convert OID's to/from DER. der_to_oid
takes a cursor as second arg.
Encode tokens as described in section 3.1 of RFC 2078. This is usually only done for the initiating token.
Encode names as described in section 3.2 of RFC 2078
Format of the tokens: see RFC 4121
Create a MIC token:
sent_by_acceptor
: whether this token comes from the acceptoracceptor_subkey
: see RFCsequence_number
: a sequence numberget_mic
: the checksum function
(e.g. [root:Netmech_scram].Cryptosystem.get_mic)message
: the message to be signedThe function returns the MIC token
Returns the triple
(sent_by_acceptor
, acceptor_subkey
, sequence_number
) from
the header of a MIC token that is passed to this function as
string. Fails if not parsable
Wraps a message
so that it is encrypted and signed (confidential).
sent_by_acceptor
: whether this token comes from the acceptoracceptor_subkey
: see RFCsequence_number
: a sequence numberget_ec
: This function returns the "extra count" number for
the size of the plaintext w/o filler (e.g. use
[root:Netmech_scram].Cryptosystem.get_ec).encrypt_and_sign
: the encryption function from the cryptosystem.
The plaintext is passed to this function, and the ciphertext with
the appended signature must be returned in the string.message
: the payload messageThe function returns the token wrapping the message.
let (sent_by_acceptor, sealed, acceptor_subkey, sequence_number) =
parse_wrap_token_header token
Fails if the token
cannot be parsed.
Unwraps the token
using the decryption function
decrypt_and_verify
from the cryptosystem.
The functions fails if there is a format error, or the integrity check fails.
Non-confidential messages cannot be unwrapped with this function.
Token functions for non-confidential messages are still missing