Michael Richardson
2007-05-12 02:11:00 UTC
(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 )
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?
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.
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. 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)
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;
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);
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)
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...
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);
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"); [
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...
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"); [