Subject: [anonsec] suggested changes to btns-api-01

From: mcr at sandelman.ottawa.on.ca (Michael Richardson)
Date: Fri, 11 May 2007 22:11:00 -0400

(new abstract-api document at, which is background to below at:
     http://www.sandelman.ca/SSW/ietf/ipsec/btns/richardson-btns-abstract-api-00.txt )

> 2.1.1 Policy Creation.

change:	   typedef ipsec_policy_t struct ipsec_policy;

to:
	typedef struct ipsec_iToken * ipsec_iToken_t;

	#define IPSEC_ITOKEN_INVALID NULL

change:
      ipsec_policy_t *ipsec_create_policy(uint32_t type);
      int ipsec_free_policy(ipsec_policy_t *policy);

to:	   
	   ipsec_iToken_t ipsec_iToken_alloc(uint32_t type);
	   int ipsec_iToken_free(ipsec_iToken_t i);

COMMENT:  Can you give me a use case for the "type" argument? vs having
	  new creation functions?

> 2.1.2

change:
   int ipsec_get_policy_attr(const ipsec_policy_t *policy,
                             uint32_t attr_type,
                             uint32_t *attr_len,
                             void **attr_val);
   int ipsec_set_policy_attr(ipsec_policy_t *policy,
                             uint32_t attr_type,
                             uint32_t attr_len,
                             const void *attr_val);

to:
   int ipsec_iToken_attr_get(const ipsec_iToken_t iToken,
		             enum iToken_attribute,
                             size_t *attr_len,	/* VALUE/RESULT */
                             void **attr_val);

   int ipsec_iToken_attr_set(const ipsec_iToken_t iToken,
                             enum iToken_attribute attr_type,
                             size_t attr_len,
                             const void *attr_val);

change:
   Function ipsec_get_policy_attr searches for the given attribute type
   (attr_type) from the policy.  It allocates memory into attr_val and
   copies the attribute into the allocated memory.  On successful
   operation, it sets the attribute length in attr_len.

to:
   Function ipsec_pToken_attr_get searches for the given attribute type
   (attr_type) from the pToken.  
   The *attr_val pointer may have memory allocated for it already, if so,
   it will be non-NULL, and the attr_len will have the size of the
   allocated memory set.
   If *attr_val is NULL, then it allocates memory into attr_val (using
   malloc) and copies the attribute into the allocated memory.  On successful
   operation, it sets the attribute length in attr_len.
   If attr_val is NULL, then no object will be returned, but attr_len
   will still be set to the size of the object.
	
COMMENT:
	I don't understand what BTNS_STANDALONE attribute would mean.

>2.1.3

change:
   int ipsec_set_socket_policy(int fd, const ipsec_policy_t *policy);
   int ipsec_get_socket_policy(int fd, ipsec_policy_t **policy);

to:
   const ipsec_iToken_t ipsec_iToken_from_pToken(ipsec_pToken_t p);
   int ipsec_pToken_for_socket(int fd, ipsec_pToken_t *policy);

NOTE: this is really a wrapper around:
   ipsec_pToken_attr_get(pToken, IPSEC_API_ATTR_ITOKEN, &iToken, sizeof(iToken));

>2.1.5

change:
	2.1.5.  Other Policy Related Functions
to:
	2.1.5.  Equivalency of policies

change:
   int ipsec_cmp_policy(ipsec_policy_t *p1, ipsec_policy_t *p2);

   Function ipsec_cmp_policy inputs two policies, p1 and p2, and returns
   zero if they are equal.  Otherwise it returns non-zero.

to:
   int ipsec_pToken_cmp(ipsec_pToken_t p1, ipsec_pToken_t p2);
   int ipsec_iToken_cmp(ipsec_iToken_t p1, ipsec_iToken_t p2);

   Function ipsec_cmp_policy inputs two policies, p1 and p2, and returns
   zero if they represent two SAs that cover identical SPD ranges, and
   have equivalent cryptographic security properties.  The two SAs need not
   represent SAs that identical --- they might vary in many different
   ways, including, but not limited to: 
	 - time. One SA may have been created later, but both are valid.
	 - jitter/performance properties. One SA may be on hardware and
	   	   the other on software, and have different properties
		   about what kind of latency or jitter a packet might
		   experience.
	 - algorithm. one SA might use AES128-CBC while the other uses
		      AES128-CTR (DISCUSS) for performance reasons.
	 - IPsec SA endpoints. The two SAs may cover the same inner
	 	   IP packets, but might connect using differing outer
		   IP addresses, and be used in some kind of multipath
		   IPsec (such as MOBIKE).

   XXX -- belongs in abstract document.
	are equal.  Otherwise it returns non-zero.

MOVE ipsec_dup_policy to seperate section (2.1.6)

>new section 2.1.7 ATTRIBUTES for iToken

enum {
     IPSEC_API_ATTR_auditString,
     IPSEC_API_ATTR_authenticationMethod,
     IPSEC_API_ATTR_certificateAuthorityDN,
     IPSEC_API_ATTR_certificateDN,
     IPSEC_API_ATTR_pubKeyID,
     IPSEC_API_ATTR_channelBinding,
} iToken_attribute;

enum {
     IPSEC_API_authMeth_NONE,
     IPSEC_API_authMeth_BTNS,
     IPSEC_API_authMeth_LEAFOFFAITH,
     IPSEC_API_authMeth_PRESHAREDKEY,
     IPSEC_API_authMeth_GROUPKEY,
     IPSEC_API_authMeth_XAUTH,
     IPSEC_API_authMeth_EAP,
     IPSEC_API_authMeth_PKIX_TRUSTED,
     IPSEC_API_authMeth_PKIX_INLINE,
     IPSEC_API_authMeth_PKIX_OFFLINE
} iToken_auth_meth;

>2.2.1

change:
   typedef ipsec_channel_info_t struct ipsec_channel_info;

to:
	typedef struct ipsec_pToken * ipsec_pToken_t;
	#define IPSEC_PTOKEN_INVALID NULL

change:
   ipsec_channel_info_t *ipsec_create_channel_info();
   int ipsec_free_channel_info(*ipsec_channel_info_t *ci);

to:
	ipsec_pToken_t ipsec_pToken_alloc(void);
        int ipsec_pToken_free(ipsec_pToken_t p);

>2.2.2

change:

   int ipsec_set_channel_attr(ipsec_channel_info_t *ci,
                              uint32_t attr_type,
                              uint32_t attr_len,
                              const void *attr_val);
   int ipsec_get_channel_attr(const ipsec_channel_info_t *ci,
                              uint32_t attr_type,
                              uint32_t *attr_len,
                              void **attr_val);
to:
   int ipsec_pToken_attr_get(const ipsec_pToken_t pToken,
		             enum pToken_attribute,
                             size_t *attr_len,	/* VALUE/RESULT */
                             void **attr_val);

   int ipsec_pToken_attr_set(const ipsec_pToken_t pToken,
                             enum pToken_attribute attr_type,
                             size_t attr_len,
                             const void *attr_val);

(and indicate that **attr_val may be filled in, a la iToken)

>2.2.3

change:
   int ipsec_set_socket_policy(int fd, const ipsec_policy_t *policy);
   int ipsec_get_socket_policy(int fd, ipsec_policy_t **policy);

to:
   const ipsec_pToken_t ipsec_pToken_from_socket(int fd);
   int ipsec_pToken_for_socket(int fd, ipsec_pToken_t *policy);

   The function ipsec_pToken_from_socket() returns IPSEC_PTOKEN_INVALID
   upon failure.

   XXX need to have extended error reporting...

>2.2.4

change:
   int ipsec_set_msg_channel_info(const struct *msg_hdr,
                                  const ipsec_channel_info_t *ci);
   int ipsec_get_msg_channel_info(const struct *msg_hdr,
                                  ipsec_channel_info_t **ci);

to:
	pToken_t ipsec_pToken_from_cmsg(struct msghdr *msg);	
	int ipsec_pToken_for_cmsg(struct msghdr *msg);

>2.2.5 same as 2.1.5...

>2.1.7, new section, ATTRIBUTES:

enum {
     IPSEC_API_ATTR_privacyProtected, 
     IPSEC_API_ATTR_integrityProtected,
     IPSEC_API_ATTR_compressionAvailable,
     IPSEC_API_ATTR_iToken,
     IPSEC_API_ATTR_auditString
} pToken_attribute;

- -- 
]            Bear: "Me, I'm just the shape of a bear."          |  firewalls  [
]   Michael Richardson,    Xelerance Corporation, Ottawa, ON    |net architect[
] mcr at xelerance.com      http://www.sandelman.ottawa.on.ca/mcr/ |device driver[
] panic("Just another Debian GNU/Linux using, kernel hacking, security guy"); [

---

From: julien.IETF at laposte.net (Julien Laganier)
Date: Wed, 30 May 2007 13:23:15 +0200

Folks,

Michael has worked has worked on a revised abstract 
API, available at:
 
<http://www.sandelman.ca/SSW/ietf/ipsec/btns/richardson-btns-abstract-api-00.txt>

While Miika has produced the corresponding C-bindings 
of this abstract API, available at:

<http://www.ietf.org/internet-drafts/draft-komu-btns-api-01.txt>

Hereby I'd like to call for WG adoption of both of 
these documents. If you agree, or disagree with 
adoption, please send an email saying so to the 
mailing list without changing the subject line before 
2007-05-25. (OTOH please do change the subject line if 
you want to discuss contents of the documents 
themselves.)

(If you have no time to read the documents, you might 
take a look at their respective presentations given 
during last meeting.)

-- julien / BTNS co-chair

---

From: julien.IETF at laposte.net (Julien Laganier)
Date: Thu, 31 May 2007 10:41:48 +0200

Folks,

Miika has worked on C-bindings for the abstract API 
(draft-komu-btns-api-01). Hereby I'd like to call for 
WG adoption of this document. If you agree, or 
disagree with adoption, please send an email saying so 
to the mailing list without changing the subject line 
before 2007-06-14. (OTOH please do change the subject 
line if you want to discuss contents of the documents 
themselves.)

---

From: julien.IETF at laposte.net (Julien Laganier)
Date: Thu, 31 May 2007 10:41:44 +0200

Folks,

Michael has worked on a revised abstract API, available 
at:

Hereby I'd like to call for WG adoption of this 
document. If you agree, or disagree with adoption, 
please send an email saying so to the mailing list 
without changing the subject line before 2007-06-14. 
(OTOH please do change the subject line if you want to 
discuss contents of the documents themselves.)

---

From: simon at josefsson.org (Simon Josefsson)
Date: Thu, 31 May 2007 17:52:07 +0200

I object to standardize any API that uses data types from a particular
external implementation (in this case OpenSSL).

The approach used in this document appear to require that every
implementation of the document needs to #include OpenSSL headers, and
possibly call OpenSSL functions (the implementation of the
ipsec_openssl_to_channel_info is unclear to me).  I believe that is
clearly unacceptable for any Standards Track document.

If this problem can be solved, by having a generic interface to input
the necessary information needed from the TLS library, the document
seems like a useful contribution to me.

A suggestion for an improvement to the document would be to add a
copyright license to the example code to make it possible to use the
example in implementations.  This often helps spread usage and leads to
faster adoption of the API.  See section 3 of
draft-josefsson-free-standards-howto-00.txt.

/Simon

Julien Laganier <julien.IETF at laposte.net> writes:

> _______________________________________________

---

From: Nicolas.Williams at sun.com (Nicolas Williams)
Date: Thu, 31 May 2007 12:06:52 -0500

> without changing the subject line before 2007-06-14. 

I am in favor of adopting this document.

---

From: Nicolas.Williams at sun.com (Nicolas Williams)
Date: Thu, 31 May 2007 12:07:30 -0500

> you want to discuss contents of the documents 

I am in favor of adopting both documents.