bsn1

bsn1 is a rust library to serialize/deserialize in 'ASN.1' format.

What is ASN.1?

ASN.1 stands for 'Abstract Syntax Notation One' and X.690 is an 'ITU-T' standard specifying the following ASN.1 encoding format.

This crate supports BER and DER for now.

ASN.1 resembles 'JSON' in some ways because they both are standard serializing structured data, however, they differ in the following points.

ASN.1 has been used all over the world for a long time and it is very stable. For example, 'Transport Layer Security (TLS, SSL)', 'Lightweight Directory Access Protocol (LDAP)', '4th Generation Mobile Communication System (4G)', and so on.

See also [X.690 (07/2002)] and [Wikipedia].

Examples

'Lightweight Directory Access Protocol (LDAP)' adopts BER. Let's make/parse LDAP Bind Operation (i.e. Login Query.)

See RFC4511 for the details.

``` use bsn1::{Ber, BerRef, ContentsRef, Id, IdRef, ClassTag, PCTag};

/// Creates a BindRequest from name and password. /// /// BindRequest ::= [APPLICATION 0] SEQUENCE { /// version INTEGER (1 .. 127), /// name LDAPDN, /// authentication AuthenticationChoice } fn newbindrequest(name: &str, password: &[u8]) -> Ber { // BindRequest is constituted of version, name, and authentication. // '[APPLICATION 0] SEQUENCE' means "a sequence, but the class is APPLICATION, and the // number is 0." // The RFC does not refer to the Primitive/Constructed flag, // but SEQUENCE is usually Constructed. const IDNUMBER: u32 = 0; let id = Id::new(ClassTag::Application, PCTag::Constructed, IDNUMBER);

let contents = [new_bind_version(), new_bind_name(name),
                new_bind_authentication(password)];

Ber::from_id_iterator(&id, contents.iter())

}

/// Creates a version for bind request. /// This function always returns 3 (the current latest version.) fn newbindversion() -> Ber { Ber::integer(3_i32) }

/// Creates a name for bind request from name. /// /// LDAPDN ::= LDAPString /// -- Constrained to [RFC4514] /// /// LDAPString ::= OCTET STRING -- UTF-8 encoded, /// -- [ISO10646] characters fn newbindname(name: &str) -> Ber { // BER allows both Primitive and Constructed for OCTET STRING. // This function returns Primitive BER. // Call octetstringconstructed() instead if you prefer Constructed. Ber::octetstring(name.asbytes()) }

/// Creates a simple authentication for bind request from password. /// /// AuthenticationChoice ::= CHOICE { /// simple [0] OCTET STRING, /// -- 1 and 2 reserved /// sasl [3] SaslCredentials, /// ... } fn newbindauthentication(password: &[u8]) -> Ber { // 'AuthenticationChoice' is either 'simple [0] OCTET STRING' or 'sasl [3] SaslCredentials'. // This function selects 'simple'. // // '[0] OCTET STRING' means "OCTET STRING, but the number is 0." // RFC does not refer to the class and Primitive/Constructed flag. // This function returns ContextSpecific and Primitive BER. const IDNUMBER: u32 = 0; let id = Id::new(ClassTag::ContextSpecific, PCTag::Primitive, IDNUMBER);

let contents = ContentsRef::from_bytes(password);

Ber::new(&id, contents) }

/// Tries to parse bind request and returns (name, password). fn parsebindrequest(req: &[u8]) -> Result<(&str, &[u8]), String> { let req = BerRef::tryfrombytes(req) .map_err(|e| format!("Failed to parse the request as a BER: {}", e))?;

let id = req.id();
if id.class() != ClassTag::Application || id.number() != Ok(0) {
    return Err("The id of the request is bad.".to_string());
}

let bytes = req.contents().as_bytes();
let version_ber = BerRef::try_from_bytes(bytes)
                    .map_err(|e| format!("Failed to parse the request version: {}", e))?;
let version = parse_bind_version(version_ber)?;
if version != 3 {
    return Err("This function supports only version 3.".to_string());
}

let bytes = &bytes[version_ber.as_bytes().len()..];
let name_ber = BerRef::try_from_bytes(bytes)
                 .map_err(|e| format!("Failed to parse the request name: {}", e))?;
let name = parse_bind_name(name_ber)?;

let bytes = &bytes[name_ber.as_bytes().len()..];
let auth_ber = BerRef::try_from_bytes(bytes)
                 .map_err(|e|
                          format!("Failed to parse the request authentication: {}", e))?;
let password = parse_bind_authentication(auth_ber)?;

let bytes = &bytes[auth_ber.as_bytes().len()..];
if bytes.is_empty() == false {
    return Err("There are some bad octets at the end of the request.".to_string());
}

Ok((name, password))

}

/// Tries to parse the version of bind request. fn parsebindversion(version: &BerRef) -> Result { if version.id() != IdRef::integer() { Err("The id of the version is bad.".tostring()) } else { version.contents() .tointeger() .map_err(|e| format!("Failed to parse the version: {}", e)) } }

/// Tries to parse the name of bind request. fn parsebindname(name: &BerRef) -> Result<&str, String> { if name.id() != IdRef::octetstring() && name.id() != IdRef::octetstringconstructed() { Err("The id of the name is bad.".tostring()) } else { let contents = name.contents().asbytes(); std::str::fromutf8(contents).map_err(|e| format!("Failed to parse the name: {}", e)) } }

/// Tries to parse the password of bind request. fn parsebindauthentication(authentication: &BerRef) -> Result<&[u8], String> { let id = authentication.id(); if id.number() == Ok(3) { Err("This function supports only simple authentication".tostring()) } else if id.number() != Ok(0) { Err("The id of the authentication is bad".tostring()) } else { Ok(authentication.contents().as_bytes()) } }

// Create a bind request let name = "uid=user,dc=mycompany,dc=co,dc=jp"; let password = "opensesami".asbytes(); let request = newbind_request(name, password);

// The client will send the byte to the server actually. let bytes = request.as_bytes();

// The LDAP server will parse the request. let (name, password) = parsebindrequest(bytes).unwrap();

asserteq!(name, name); asserteq!(password, password); ```